From aab5fd5738186ecc50ef5b3f2e42ed95b57ae67a Mon Sep 17 00:00:00 2001
From: Jarek Potiuk <potiuk@apache.org>
Date: Sat, 17 Oct 2026 02:42:13 +0200
Subject: [PATCH] docs(spec-loop): sync specs with main up to 43e4c6eeb

Hand-sync of tools/spec-loop/specs/ with the functionality that landed
between d58ecb75c and 43e4c6eeb.

Specs changed:
- release-management-lifecycle: verify-rc classification as code
  (abd596976, #1619), vote-draft / promote / announce-draft renders
  (c87ad0853, d5fe7fd21), the per-outcome / backend / classification
  file split across the family, and the SKILL.md size gap closed (all
  ten now under 500 lines).
- adoption-and-setup: the utilities first-run welcome guide and the
  text-file mirror fallback in the family scan (9f8c479c1, #1669).
- meta-and-quality-tooling: the zero-token /magpie-skills Claude Code
  mod in magpie-utilities (861c84e02, #1667).
- agent-isolation-sandbox: the agent-guard --junie adapter (6c24f30cb,
  #1666) and sandbox-lint refusing a tracked .claude/settings.json
  (4a07965f2, #1675).
- adapters, security-issue-lifecycle, project-agnosticism: the canonical
  apache-magpie status-rollup marker, preferred over and replacing the
  legacy tracker-named one for new rollups (ccead7069, #1665).
- .last-sync bumped to 43e4c6eeb.

No spec change needed (specs already updated in the commit itself):
43e4c6eeb, 399ab1bc2, 622bfbc96, 5fc6a326e, a75734c77, e44b44a5d,
a93a7d1de, c67e3c651, a3d9b7179, ec015bb3b.

Exempt (mechanical): 0a79a33b0 (dev version bump), 80a0f1f89 (npm pin
bump in prek hooks).

Generated-by: Claude Opus 5
---
 tools/spec-loop/.last-sync                    |  2 +-
 tools/spec-loop/specs/adapters.md             |  8 ++++--
 tools/spec-loop/specs/adoption-and-setup.md   |  8 ++++--
 .../specs/agent-isolation-sandbox.md          | 10 ++++++-
 .../specs/meta-and-quality-tooling.md         |  7 +++++
 tools/spec-loop/specs/project-agnosticism.md  |  4 ++-
 .../specs/release-management-lifecycle.md     | 28 +++++++++++++++----
 .../specs/security-issue-lifecycle.md         | 10 ++++---
 8 files changed, 59 insertions(+), 18 deletions(-)

diff --git a/tools/spec-loop/.last-sync b/tools/spec-loop/.last-sync
index 676e5d854..4fb0724c7 100644
--- a/tools/spec-loop/.last-sync
+++ b/tools/spec-loop/.last-sync
@@ -1 +1 @@
-d58ecb75c69fac3df3844cc1c32835e002c7e2f7
+43e4c6eeb6ba99a2ee1796f2a8ee712db1c31738
diff --git a/tools/spec-loop/specs/adapters.md b/tools/spec-loop/specs/adapters.md
index 7be4e86ff..38b286faf 100644
--- a/tools/spec-loop/specs/adapters.md
+++ b/tools/spec-loop/specs/adapters.md
@@ -85,8 +85,12 @@ by swapping the adapter, not the skill.
   writer's entry is never overwritten), `fold` (moves one legacy bot comment
   into the rollup with its own date and author, then deletes it; refuses to
   fold the rollup itself), `list`, and `latest`.
-  An existing rollup is found by any `<!-- <name> status rollup v<N>`
-  marker, and a comment's id is read from its `#issuecomment-<id>` URL.
+  An existing rollup is found by the canonical
+  `<!-- apache-magpie: status-rollup v<N> -->` marker, preferred when a
+  tracker carries both, or by the legacy `<!-- <name> status rollup v<N>`
+  one; a new rollup always gets the canonical marker, in `github-rollup`
+  and `vetted-op-tracker rollup-append` alike (#1665).
+  A comment's id is read from its `#issuecomment-<id>` URL.
   `tools/github/status-rollup.md` calls the tool instead of carrying its own
   script.
   Under the secure agent setup both tools' `gh` runs sandboxed and fails,
diff --git a/tools/spec-loop/specs/adoption-and-setup.md b/tools/spec-loop/specs/adoption-and-setup.md
index 4c8529728..c20131b40 100644
--- a/tools/spec-loop/specs/adoption-and-setup.md
+++ b/tools/spec-loop/specs/adoption-and-setup.md
@@ -702,12 +702,14 @@ committed version with drift detection.
 37. `tools/setup-preflight` has a **family** scope: a `welcome` finding
     (rules section `welcome`, guide in `facts.guide`, its name in
     `facts.family`). `setup_preflight/guides/general.md` is due on the first
-    run of any Magpie skill, and `guides/<family>.md` — today only
-    `security` — on the first run of a skill in that family. At most one
+    run of any Magpie skill, and `guides/<family>.md` — today `security`
+    and `utilities` (#1669) — on the first run of a skill in that family. At most one
     guide per run: a first showing beats a repeat, and between equals the
     general guide goes first, so a family guide first appears on the run
     after the general one. The skill's family is looked up in `families.py`, generated
-    from frontmatter and kept current by `check-family-plugins`. The answer
+    from frontmatter and kept current by `check-family-plugins`; the live
+    scan also resolves a mirror entry checked out as a plain text file
+    holding its target path, as git writes it without symlink support. The answer
     is recorded under `welcome.<guide>` in the personal layer's
     `reconciled.json` by `python3 -m setup_preflight.welcome record`, never
     by hand: `seen` shows again up to three recorded showings, `dismiss`
diff --git a/tools/spec-loop/specs/agent-isolation-sandbox.md b/tools/spec-loop/specs/agent-isolation-sandbox.md
index 993aaf695..fff4b8deb 100644
--- a/tools/spec-loop/specs/agent-isolation-sandbox.md
+++ b/tools/spec-loop/specs/agent-isolation-sandbox.md
@@ -151,7 +151,11 @@ existing sandbox grants can widen the baseline. See `docs/adapters/gemini.md`.
   for Copilot CLI's `preToolUse` event (wired in `.github/hooks/magpie.json`,
   #1560), which also allows one simple read-only command (`gh` reads,
   `git status/diff/log`, GET-only `gh api`, `vetted-op-read`) so reads never
-  prompt and leaves anything else to Copilot's own permission flow; inspects every shell command
+  prompt and leaves anything else to Copilot's own permission flow, and a
+  `--junie` adapter for JetBrains Junie's Early Access `PreToolUse` hook
+  (`~/.junie/config.json`, #1666; guide in `docs/adapters/junie.md`), which blocks with exit `2` and a
+  `decision` JSON, the one signal Junie honours, because Junie ignores the
+  Claude-shaped `hookSpecificOutput` deny; inspects every shell command
   before it runs and denies the ones that break a hard framework rule,
   independent of model memory. The guard decisions live in a single
   harness-agnostic `dispatch()` core so every wired harness enforces
@@ -233,6 +237,10 @@ existing sandbox grants can widen the baseline. See `docs/adapters/gemini.md`.
   `.claude/settings.json`) — the `sandbox` block (filesystem
   allow/deny, network `allowedDomains`, `excludedCommands`) and
   `permissions` (`deny` / `ask`).
+  `.claude/settings.json` itself is gitignored, and the `sandbox-lint`
+  workflow also runs when that path changes and fails while it is tracked,
+  so a force-added copy that Claude Code would load for every checkout is
+  refused before merge (#1675).
 - `.gemini/settings.json` and `.gemini/policies/magpie.toml` — Magpie's Gemini profile: tool-sandboxing and an explicitly loaded User-tier approval policy.
   Scoped shell reads are allowed; other shell calls, native edits, and MCP calls ask; listed commands and credential paths deny.
   Credential-path denies name the canonical `grep_search`; the native probe verifies its `search_file_content` alias, canonical policy names, and search/multi-file/web/resource argument schemas against the loaded runtime.
diff --git a/tools/spec-loop/specs/meta-and-quality-tooling.md b/tools/spec-loop/specs/meta-and-quality-tooling.md
index 7bb903800..5c569d8b6 100644
--- a/tools/spec-loop/specs/meta-and-quality-tooling.md
+++ b/tools/spec-loop/specs/meta-and-quality-tooling.md
@@ -134,6 +134,13 @@ trustworthy as it grows.
   generated index of every skill, grouped by family).
   The utility skills live at `plugins/magpie-utilities/skills/<alias>/`,
   reached through `skills/<name>` symlinks.
+- Claude Code mod: `plugins/magpie-utilities/hooks/skills-command.ts`
+  (registered in that plugin's `hooks/hooks.json` `modules`, #1667)
+  registers `/magpie-skills` at session start and answers it by running
+  `list-skills`' `list_skills.py` locally, with no model turn: a 30-second
+  timeout, UTF-8 output, `python3` falling back to `python`, and
+  `--verbose` / `-v`, `--help` / `-h` and `--root` passed through.
+  `skills-command.test.ts` covers it.
 - `tools/skill-token-count/` measures full local skill files with pinned
   `tiktoken` / `cl100k_base` and stamps each count into that skill's own
   frontmatter as a generated `measured_tokens:` line (#1394).
diff --git a/tools/spec-loop/specs/project-agnosticism.md b/tools/spec-loop/specs/project-agnosticism.md
index 7a94121c0..50d5ad266 100644
--- a/tools/spec-loop/specs/project-agnosticism.md
+++ b/tools/spec-loop/specs/project-agnosticism.md
@@ -144,7 +144,9 @@ The three mechanisms, in order of preference:
   Generic skills likewise dropped hardcoded release numbers, a backport
   label, maintainer names, a real CVE id, and one project's canned-response
   list in favour of `<project-config>` values, and the status-rollup marker
-  names the adopter's tracker instead of a fixed project slug (#1444).
+  carries no project slug: new rollups get the framework-wide
+  `<!-- apache-magpie: status-rollup v1 -->` marker, while the legacy
+  tracker-named one is still recognised (#1444, #1665).
 - **Advisory, not paternalistic.** The audit surfaces candidate coupling
   for a maintainer to judge; some ASF strings are legitimate (examples,
   the ASF default profile, ASF-specific docs). It does not auto-rewrite.
diff --git a/tools/spec-loop/specs/release-management-lifecycle.md b/tools/spec-loop/specs/release-management-lifecycle.md
index 421bead23..9aaa68618 100644
--- a/tools/spec-loop/specs/release-management-lifecycle.md
+++ b/tools/spec-loop/specs/release-management-lifecycle.md
@@ -128,6 +128,19 @@ code lands.
   Top-level build commands resolve release placeholders; custom builds emit
   their reproducibility record. Per-entry modes describe the checks actually
   run, and a failed outcome cannot propose a staging label.
+  It also classifies `release-verify-rc`'s results from saved files only
+  (#1619): `verify-rc args` emits the `release-verify` invocations from
+  `release-build.md`, and `rat`, `source-tree`, `jvm`, `nexus`, `repro` and
+  `report` classify Steps 4, 7, 6b, 6c, 9 and 10, checking the Nexus
+  staging-repository id shape before any URL is built and withholding the
+  trusted-hardware attestation unless automated signing, a Step 9 `PASS`
+  and every artefact `identical` all hold.
+  It renders the `[VOTE]` draft and planning-issue comment
+  (`vote-draft verdict` / `render`, #1617), the backend-shaped promotion
+  command set with a HOLD per unreproduced convenience artefact
+  (`promote verdict` / `render`, #1618), and the `[ANNOUNCE]` body and
+  site-bump PR (`announce-draft verdict` / `render`, #1618), each refusing
+  (exit `2`) what the skill must refuse.
   A source version is a dotted version of two or more numeric parts with
   no `.postN` (`2.11.0`) or, for a release wave named by date, a calendar
   date `YYYY-MM-DD` (`2026-10-06`, tagged `2026-10-06-rc1`); an impossible
@@ -156,6 +169,11 @@ code lands.
   `plan.md`, `prep.md`, `post.md` and `automated-signing.md`; `rc-cut` into
   `ci-signed.md` and `reproducibility-self-check.md`; `verify-rc` into
   `jvm-artefacts.md`, `nexus-staging.md` and `reproducibility.md`.
+  Since #1604–#1625 every skill in the family also keeps its prerequisites
+  and references in `prerequisites.md` / `references.md` and loads one file
+  per outcome, backend or classification (`outcomes/`, `backends/`,
+  `blockers/`, `classifications/`, `mechanisms/`, `delivery/`,
+  `overrides/`) only when the deterministic verdict names it.
 - Adapters it will read/draft through: `tools/github`, `tools/ponymail`
   (vote threads), `tools/gmail` (announce/vote drafts), plus the project's
   `svn` dist tree as a distribution backend.
@@ -328,9 +346,7 @@ uv run --project tools/skill-evals skill-eval tools/skill-evals/evals/release-an
   values (`project_dist_name: magpie`, ATR for both backends).
   `.apache-magpie-overrides/release-build.md` likewise differs from
   `projects/magpie/release-build.md`.
-- **Several of the family's `SKILL.md` files are still over the 500-line
-  cap.** After the helper tools, sibling scripts, conditional-step split and
-  wording passes (#1510–#1519), six of the ten remain over it
-  (`release-rc-cut` 696, `release-verify-rc` 684, `release-announce-draft`
-  529, `release-vote-draft` 528, `release-audit-report` 516,
-  `release-promote` 504); `release-prepare` fell from 1,208 to 399.
+- **No `SKILL.md` in the family is over the 500-line cap any more.** After
+  the decide-and-render-as-code passes (#1604, #1617–#1619, #1624, #1625)
+  the largest are `release-rc-cut` (472) and `release-verify-rc` (469);
+  `release-prepare` fell from 1,208 to 367.
diff --git a/tools/spec-loop/specs/security-issue-lifecycle.md b/tools/spec-loop/specs/security-issue-lifecycle.md
index 5890e94d8..e0f740b75 100644
--- a/tools/spec-loop/specs/security-issue-lifecycle.md
+++ b/tools/spec-loop/specs/security-issue-lifecycle.md
@@ -103,10 +103,12 @@ publication, with a human gate and an audit-log entry at every step.
 - **Reporter PII redacted in-context; reporter *credit* preserved** in
   the CVE `credits[]` only after the reporter confirms on the thread.
 - **Audit log** of every applied change (redacted identifiers only).
-  The per-tracker status rollup is recognised by any first line of the
-  form `<!-- <name> status rollup v<N>`, and a new rollup's marker names
-  the tracker repository, so the rollup works on any adopter's tracker
-  rather than only the reference one (#1444).
+  The per-tracker status rollup is recognised by a first line carrying the
+  canonical `<!-- apache-magpie: status-rollup v<N> -->` marker or the
+  legacy `<!-- <name> status rollup v<N>` one (#1444), the canonical one
+  winning when a tracker carries both, and a new rollup always gets the
+  canonical marker, so the rollup works on any adopter's tracker and is
+  never duplicated under a second marker (#1665).
   `amend-latest` fills in a value on the newest entry (refusing when that
   entry has a different action), and `fold` moves a legacy bot comment
   into the rollup, deleting the original only after the append succeeds.