docs(spec-loop): sync specs with #1829

tools/spec-loop/.last-sync

@@ -1 +1 @@
-95b0e91475115aeb5cdadc44e162712cc1f2e675
+cb51b53b5c75dc4d98421da894417a32dd7872cd

tools/spec-loop/specs/adoption-and-setup.md

@@ -84,7 +84,12 @@ acceptance:
   - Every skill's pre-flight runs the checker with
     `PYTHONPATH=".apache-magpie-local:$(git rev-parse --git-common-dir 2>/dev/null || echo .git)/../.apache-magpie-local:$(git rev-parse --git-common-dir 2>/dev/null || echo .git)/apache-magpie:.svn/apache-magpie"`,
     so the copy is found in this checkout's `.apache-magpie-local/`, the
-    main checkout's, or the git-directory home. The project-verdict
+    main checkout's, the git-directory home, or a Subversion working
+    copy's `.svn/apache-magpie/` (#1829); outside git the substitution
+    falls back to `.git`, yielding paths that do not exist, so the command
+    never errors. `tools/setup-preflight/tests/test_layers.py` runs the
+    block's path in a git repository, a Subversion working copy and a
+    directory with no version control. The project-verdict
     cache is keyed on the checkout, since worktrees may share one
     personal layer.
   - An unadopted repository that still has an in-tree
@@ -834,11 +839,25 @@ committed version with drift detection.
     Checker verification during `config` and `upgrade` uses `--no-welcome`;
     unreadable optional guides do not suppress actual setup findings, and
     guide names cannot select Markdown files outside the shipped guides.
+    The setup family runs no shared pre-flight, so the `setup` skill alone
+    checks for its guide, before any sub-action:
+    `python3 -m setup_preflight.welcome due --skill setup` answers
+    `{"verdict": "ok"}` or the same `welcome` finding and rules the
+    pre-flight would emit, built without importing `core`, and is silent
+    when it cannot run; the other setup-family skills show no guide
+    (#1829, eval suite `setup/welcome-first-run`).
 38. A freshly scaffolded `project.md` carries `tracker.platform: TODO`, so
     `setup config` asks for the security-tracker backend (`github`,
     `jira` or `local-files`) on every first setup with a `security-*` skill
     in scope; the Jira steps map labels to whitespace-free names and
     require the backend's `doctor` to pass (#1683).
+39. `setup config` Step 0 names the working copy's version control, as
+    `layers.py` does (#1829): git keeps the personal layer in the git
+    directory, a Subversion working copy (`.svn/` holding `wc.db` in the
+    current directory) in `.svn/apache-magpie/`, and a directory with no
+    version control in the in-tree `.apache-magpie-local/`. A `.svn/` only
+    in a parent directory stops `config` and asks for it to be run from the
+    working copy's root.
 
 ## Validation
 
@@ -855,13 +874,10 @@ uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-valid
   here is the fallback. The skills delivered are the same tree either way —
   only the namespace of their invocation differs.
 
-- **The `setup` family's welcome guide (#1725) is never shown on its own.**
-  The setup family is exempt from the shared pre-flight block
-  (`EXEMPT_FAMILIES` in `tools/dev/check-shared-blocks.py`), and no setup
-  skill runs the checker's welcome path, so `guides/setup.md` is reachable
-  only through `/magpie-setup:welcome-guide setup`; the checker's logic for it
-  is tested (`test_welcome.py`, eval case `preflight-floor` 20) but no skill
-  ever asks for it.
+- **The `setup` welcome check is silent until the checker is in the personal
+  layer on a sandboxed marketplace install,** where the plugin cache cannot
+  be executed, and on a machine whose personal-layer checker predates the
+  `due` action until `setup upgrade` refreshes it.
 - `stable`; gaps appear as new agent targets to add to the registry
   ([`agents.md`](../../../plugins/magpie-setup/skills/setup/agents.md)) or new override
   surfaces — recorded by the plan pass.

tools/spec-loop/specs/cve-tooling.md

@@ -65,6 +65,10 @@ reviewable.
   `cve_authority.vulnogram.asf_org_id` in
   `organizations/ASF/organization.md`, where the one ASF-wide UUID now
   lives instead of a per-project row (#1779).
+  The package README's *Configuration* section documents that lookup
+  order, every key with its type, default and meaning, and a minimal
+  example, and the generator's config-not-found error points at it
+  (#1829).
 - `tools/cve-tool-vulnogram/oauth-api/` — a `uv` project exposing six
   console scripts that talk to the Vulnogram HTTP API with a Bearer token
   the operator copies from `https://cveprocess.apache.org/users/token`

tools/spec-loop/specs/marketplace-distribution.md

@@ -107,7 +107,8 @@ choose the shell (#1794); on a version change it points at
 [`adoption-and-setup.md`](adoption-and-setup.md).
 `tools/setup-preflight/tests/test_session_hook.py` asserts that wiring;
 `check-family-plugins.py` checks only that `hooks.json` references
-`check-upgrade.sh`.
+`check-upgrade.sh`, and its `--fix` fallback writes the same `/bin/bash -p`
+command when `hooks.json` is missing (#1829).
 Its manifest declares `"types": "./hooks/types.d.ts"`, and
 `check-family-plugins.py` fails when `hooks.json` lacks `modules` or the
 `check-upgrade.sh` hook, or when the manifest also declares inline `hooks`,
@@ -287,16 +288,16 @@ For the Claude Code family, `claude plugin validate . --strict`.
   likely of the set to churn.
 - **Gemini has no migration path off `gemini-extension.json`.** Google has
   joined the AP1 TSC but published nothing, so both files stay.
+- **Codex never runs the upgrade-detection hook.**
+  `plugins/magpie-setup/` has no `.codex-plugin/plugin.json`, so Codex reads
+  its default `hooks/hooks.json`, whose top-level `$schema` and `modules`
+  keys its strict hooks-file schema rejects: no hook loads.
+  The root `.codex-plugin/plugin.json` hook #1829 re-pointed is written as
+  `{"SessionStart": …}` without the inner `hooks` wrapper Codex's inline
+  form needs, so it is ignored too, and the Codex catalogue never installs
+  the root plugin anyway; `check-family-plugins.py`'s `CODEX_HOOKS` pins
+  that shape.
 - **Nothing checks the dev-suffix stamp is fresher than the last release**, so
   a bump that is forgotten fails silently in the one way that matters: adopters
   keep being told they are up to date. The staleness is only visible by reading
   the timestamp.
-- **`check-family-plugins.py`'s `SETUP_HOOKS` fallback lags the wiring.**
-  When `plugins/magpie-setup/hooks/hooks.json` is missing, `--fix` writes
-  inline manifest hooks with the bare `${CLAUDE_PLUGIN_ROOT}/hooks/check-upgrade.sh`
-  command, not the `/bin/bash -p` form `hooks.json` uses since #1794.
-- **The root `.codex-plugin/plugin.json` wires a hook that does not ship.**
-  Its inline `SessionStart` hook runs `${PLUGIN_ROOT}/hooks/check-upgrade.sh`,
-  but the repository root has had no `hooks/` directory since #1208; the
-  script lives only in `plugins/magpie-setup/hooks/`, and the root wiring also
-  lacks the `/bin/bash -p` form.