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

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch sync-specs-20261025-2
in repository https://gitbox.apache.org/repos/asf/magpie.git

commit b0e5145a6deff333f3613f154a69feedefdba238
Author: Jarek Potiuk <po...@apache.org>
AuthorDate: Sun Oct 25 23:36:51 2026 +0100

    docs(spec-loop): sync specs with #1829
    
    Brings the specs up to main at cb51b53b5: the setup skill's own
    welcome-only check, the Subversion personal layer on the pre-flight path
    and in `setup config` Step 0, the re-pointed root Codex hook and the
    corrected SETUP_HOOKS fallback (dropping the two known gaps #1829
    closed), and the generate-cve-json configuration docs.
    
    Generated-by: Claude Opus 5
---
 tools/spec-loop/.last-sync                        |  2 +-
 tools/spec-loop/specs/adoption-and-setup.md       | 32 +++++++++++++++++------
 tools/spec-loop/specs/cve-tooling.md              |  4 +++
 tools/spec-loop/specs/marketplace-distribution.md | 17 +++++-------
 4 files changed, 36 insertions(+), 19 deletions(-)

diff --git a/tools/spec-loop/.last-sync b/tools/spec-loop/.last-sync
index a75880d31..70991c999 100644
--- a/tools/spec-loop/.last-sync
+++ b/tools/spec-loop/.last-sync
@@ -1 +1 @@
-95b0e91475115aeb5cdadc44e162712cc1f2e675
+cb51b53b5c75dc4d98421da894417a32dd7872cd
diff --git a/tools/spec-loop/specs/adoption-and-setup.md b/tools/spec-loop/specs/adoption-and-setup.md
index f491366a8..c85f225b8 100644
--- a/tools/spec-loop/specs/adoption-and-setup.md
+++ b/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.
diff --git a/tools/spec-loop/specs/cve-tooling.md b/tools/spec-loop/specs/cve-tooling.md
index 2301d0066..517085ea9 100644
--- a/tools/spec-loop/specs/cve-tooling.md
+++ b/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`
diff --git a/tools/spec-loop/specs/marketplace-distribution.md b/tools/spec-loop/specs/marketplace-distribution.md
index 4c25fb2e9..5c7578e48 100644
--- a/tools/spec-loop/specs/marketplace-distribution.md
+++ b/tools/spec-loop/specs/marketplace-distribution.md
@@ -107,7 +107,13 @@ 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).
+The root `.codex-plugin/plugin.json` wires the same script inline as
+`/bin/bash -p "${PLUGIN_ROOT}/plugins/magpie-setup/hooks/check-upgrade.sh"`:
+the root plugin's `PLUGIN_ROOT` is the repository root, where the script
+finds the version manifests and the `skills/setup` link it needs, and
+`check-family-plugins.py` fails on any other wiring (`CODEX_HOOKS`, #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`,
@@ -291,12 +297,3 @@ For the Claude Code family, `claude plugin validate . --strict`.
   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.