@adia-ai/adia-ui-forge 0.8.5 → 0.8.6

package/skills/adia-release/references/changelog-discipline.md

@@ -85,7 +85,7 @@ The inserted block:
 
 ### Maintenance
 - **Lockstep version bump only.** No source changes in this package; bumped to
-  maintain the 9-package version coherence enforced by
+  maintain the 11-package version coherence enforced by
   `scripts/release/check-lockstep.mjs`. Substantive v0.X.Y work shipped in
   <SUBSTANTIVE>. See `<XREF>` for details.
 ```
@@ -93,19 +93,25 @@ The inserted block:
 - **Make the PATCH-cut asymmetry visible** when an entry mentions a dependency: version bumps to `X.Y.Z` while internal ranges hold at `^X.Y.0` — spell it as `dependencies["@adia-ai/<x>"]: ^X.Y.0 (covers X.Y.Z)` so it doesn't read as a bug.
 - **Stale stubs are an F-N1 hazard.** A "no source changes" stub on a package that DID change earns a warn; the fix is authoring (§Authoring), not stubbing.
 
-## §F-N1 diff-coverage enrichment — the path-keyword discipline
+## §F-N1 diff-coverage — mechanized at cut time (Step 4f)
 
 F-N1 (`node scripts/release/check-release.mjs --all-pending`) cross-checks the git diff between consecutive package tags against the `[VERSION]` block: every touched directory should have its keyword mentioned.
 
-**Cosmetic vs real — read the entry.** Does any bullet describe the touched files (by component name, by what the change does)? Yes → cosmetic regex miss → enrich. No → real coverage gap → author a new entry.
+**The coverage pass is mechanized — run it BEFORE the release PR, never discover gaps after tagging:**
 
-**Enrichment:** add the path keyword inline where it makes the entry *more* accurate — `` `table.yaml` `` → `` `components/table/table.yaml` `` — never as a bolted-on parenthetical. Then (post-invariant-3: the release commit is already merged via PR, so `--amend` is not possible — this lands as a new commit):
+```bash
+node scripts/release/check-release.mjs --pending-version X.Y.Z --fix
+```
 
-1. `git add` the CHANGELOG; `git commit -m "fix(release): F-N1 enrichment — vX.Y.Z"`; push the branch → PR → CI → merge (or land on the same still-open release PR if one exists).
-2. The SHA moved: `node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/tag-lockstep.mjs" --version X.Y.Z --delete`, then re-tag at `main`'s new post-merge HEAD.
-3. Re-run F-N1; expect per-package clean (umbrella error stays, ignored).
+This is cut-procedure §Step 4f: the SAME matcher F-N1 uses at tag time (all 11 packages, the `changelogMentions` pattern set including the `.claude-plugin` leading-dot case), run against the working tree, auto-appending a verified `### Maintenance` bullet per uncovered directory. It re-checks its own output before writing — the v0.8.5 cut hand-authored "enrichment" three times that read correctly but didn't contain the literal substrings the checker matches, costing 3 PRs and 3 tag rewrites. `release-pack.mjs` cut modes run this automatically.
 
-Goal state: author entries with full paths from the start so no enrichment pass is needed.
+**Hand-enrichment (better prose than the auto-bullet):** add the path keyword inline where it makes the entry *more* accurate — `` `table.yaml` `` → `` `components/table/table.yaml` `` — never as a bolted-on parenthetical. Verify with `--pending-version` (no `--fix`) before committing; never assume prose satisfies the matcher.
+
+**Recovery — a warn AFTER tagging** (Step 4f skipped, or an interleaved merge added uncovered changes): the release commit is already merged via PR, so `--amend` is not possible —
+
+1. Run `--pending-version X.Y.Z --fix`; `git add` the CHANGELOGs; `git commit -m "fix(release): F-N1 enrichment — vX.Y.Z"`; push the branch → PR → CI → merge.
+2. The SHA moved: `node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/tag-lockstep.mjs" --version X.Y.Z --delete`, then re-tag at `main`'s new post-merge HEAD.
+3. Re-run F-N1; expect per-package clean (umbrella error stays, ignored). ONE recovery round — if a second warn appears, the cause is upstream (find what keeps merging into the window), not another enrichment.
 
 ## §Dating and anchors
 

package/skills/adia-release/references/cut-procedure.md

@@ -12,7 +12,7 @@ Two entry variants, converging at Step 5:
 - **Variant A — deploy handoff:** a peer pre-cut the release commit + CHANGELOG + bump + lockfile. Re-baseline, verify, run **Step 4e** (release docs + team notes — the peer's cut may not have generated them, and the pretag gate blocks Step 6 without them), then resume at Step 6 (tag).
 - **Variant B — author from scratch:** source landed under `## [Unreleased]` with no bump. Do Step 4 (promotion + bump + lockfile), then the full tail.
 
-`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/release-pack.mjs` `` (bundled) mechanizes the sequence in two phases per invariant 3 — the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main — with the three operator checkpoints preserved; the steps below are the manual/diagnostic form.
+`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/release-pack.mjs` `` (bundled) mechanizes the sequence in two phases per invariant 3 — the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main. **Run with `--go` for an operator-initiated release** (single authorization, §below); the steps below are the manual/diagnostic form and run straight through on the same one-go model.
 
 | Step | Action | Mutates? |
 | --- | --- | --- |
@@ -20,14 +20,15 @@ Two entry variants, converging at Step 5:
 | 2 | Classify uncommitted files; stash strays | Stash only |
 | 3 | Pre-flight gates (+ harvest preamble if source content changed) | No |
 | 4 | (Variant B) Promote `[Unreleased]`; bump; lockfile | Yes |
+| 4f | Pre-tag coverage `--fix` — authoritative F-N1 matcher, pre-PR | CHANGELOGs |
 | 5 | Stage the release allowlist; commit on `release/vX.Y.Z` | Yes |
 | 5.5 | Pre-commit freshness trip-wire | No |
 | 5.7 | Release PR: push branch → CI → merge → re-baseline on `main` | PR + merge |
-| 6 | Tag umbrella + per-package at post-merge HEAD — **checkpoint 1 first** | Yes |
-| 7 | F-N1 release trip-wire; enrich CHANGELOGs on warns | If warns |
-| 8 | Push tags (one per push; `main` already merged) — **checkpoint 2 first** | Push |
-| 9 | Dispatch publish workflows; wait; verify registry — **checkpoint 3 first** | Publish |
-| 10 | GH releases + site deploy — **checkpoint 4 first** | Deploy |
+| 6 | Tag umbrella + per-package at post-merge HEAD | Yes |
+| 7 | F-N1 release trip-wire (expected clean — 4f already ran) | No |
+| 8 | Push tags (one per push; `main` already merged) | Push |
+| 9 | Dispatch publish workflows; wait; verify registry | Publish |
+| 10 | GH releases + site deploy dispatch | Deploy |
 | 11 | Author release notes (default, not optional) | No |
 
 ---
@@ -172,22 +173,32 @@ post-merge HEAD, so anything merged before tagging ships in the tarball.
 If unrelated PRs merged between yours and the tag step, that is fine: tag
 at HEAD is the invariant, and the window closes at the tag.
 
-## §Operator checkpoints — evidence-first, not a bare y/N
+## §Single authorization + evidence log (operator ruling 2026-07-17)
 
-Four checkpoints total (corrected on PR #289 review — this section previously said "three", missing the Step-10 deploy-dispatch confirm that already existed in the script). Each prints its evidence block BEFORE the prompt, never a bare confirm (H5, forge-campaign gh#268 audit — the prior shape asked "proceed? [y/N]" with nothing to judge it against). The prompt itself is a plain two-way gate, honestly: **yes proceeds** (the mutating step for that checkpoint runs); **anything else aborts** — the script exits cleanly having done nothing past that point. There is no in-script "enrich" path (a CodeRabbit finding on PR #289 caught this doc previously over-promising a three-way go/enrich/abort choice the code never implemented) — to enrich, abort, fix the thing the evidence surfaced (a CHANGELOG entry, a version mismatch), then re-run from that checkpoint; the evidence re-prints fresh against the fixed state.
+The operator's initiating instruction covers the whole cycle — no per-step re-confirmation (this replaced the 4-checkpoint sign-off model after the v0.8.5 cut spent ~40 minutes on approval relays while every real protection fired deterministically). The evidence blocks the checkpoints used to gate on still PRINT, as a running log — the audit trail is unchanged; only the waiting is gone:
 
-| Checkpoint | Evidence shown BEFORE the prompt | Why this evidence (not F-N1 at cp1) |
+| Evidence logged before | Content | Why it's still printed |
 | --- | --- | --- |
-| 1 — before tagging | The planned tag list (umbrella + 11 per-package) | F-N1 inspects tag commits — it has nothing to check until Step 6 creates them |
-| 2 — before pushing | The Step 7 F-N1 output (now real, against the just-created tags) + the tag list again | This is the FIRST point F-N1 evidence exists — showing it here, not at cp1, is why the step order (tag → F-N1 → cp2) is fixed |
-| 3 — before publishing | The current registry snapshot (per-package versions + `dist-tags.latest`) | Publish ordering is judged against what's LIVE right now, not an assumption |
-| 4 — before deploying the site | The `deploy-site.yml` dispatch itself as evidence (never a raw rsync) | Deploy is its own irreversible, outward-facing action distinct from publish |
+| Tagging (Step 6) | The planned tag list (umbrella + 11 per-package) | The log line a recovery diagnoses from |
+| Pushing (Step 8) | The Step 7 F-N1 output + tag list + `origin/main..HEAD` count | F-N1's first real evidence — and its ERROR path still hard-stops unconditionally |
+| Publishing (Step 9) | The current registry snapshot (versions + `dist-tags.latest`) | Ordering is verified against what's LIVE, mechanically |
+| Deploying (Step 10) | The `deploy-site.yml` dispatch (never a raw rsync) | The workflow carries its own GitHub-environment human gate |
 
-`release-pack.mjs` implements this: `checkpoint(label, evidence, autoConfirmed)` always prints `evidence` first, then `[CHECKPOINT] <label> — proceed? [y/N]`; `--yes` auto-confirms checkpoint 1 ONLY, `--push` gates checkpoint 2, `--publish` gates checkpoints 3 AND 4 (a single `--yes` used to flatten all of them — the defect this replaced). **F-N1 errors (not warns) hard-stop before checkpoint 2 even appears — no flag, including `--push`, skips this.** A cosmetic F-N1 warn does not hard-stop, but it also blocks `--push` from auto-confirming checkpoint 2 — only the interactive prompt may proceed past a warn (never past an error, which already exited).
+`release-pack.mjs --go` auto-confirms all of these; the granular `--yes` / `--push` / `--publish` flags remain for cautious manual runs and prompt interactively when absent. **Two rules no flag or instruction wording skips:** an F-N1 *error* hard-stops before the push step exists at all, and a cosmetic F-N1 *warn* refuses auto-confirmation at the push boundary (with Step 4f mechanized, a warn appearing at Step 7 means something novel — investigate, don't loop enrichment PRs).
 
-## §Step 6 — Tag ← operator checkpoint 1 (before tagging)
+## §Step 4f — Pre-tag coverage `--fix` (the retag-loop killer)
 
-Show the operator the planned tag list; proceed only on their go (F-N1 can't run yet — see the table above). Then tag **at `main`'s post-merge HEAD** (post-bump fixes belong in the tarball; the window's last merge is the tag point — exception: batch push tags each version at its own release-merge SHA):
+After the bump + lockfile, run the AUTHORITATIVE F-N1 matcher against the working tree — same code, same `changelogMentions` patterns, all 11 packages — and let it append verified Maintenance bullets for any changed-but-unmentioned directory:
+
+```bash
+node scripts/release/check-release.mjs --pending-version X.Y.Z --fix
+```
+
+Stage its CHANGELOG edits into the release commit (the Step-5 allowlist already covers `CHANGELOG.md`). It re-verifies its own output with the same matcher before writing — a `--fix` that doesn't satisfy the checker is a hard error, not a silent pass. Do NOT use `check-changelog-coverage.mjs` as the pre-tag gate: it carries a different matcher and a 9-package roster missing the 2 plugins — the drift that cost the v0.8.5 cut 3 enrichment PRs and 3 tag rewrites after "coverage clean" at cut time.
+
+## §Step 6 — Tag
+
+Log the planned tag list (evidence table above), then tag **at `main`'s post-merge HEAD** (post-bump fixes belong in the tarball; the window's last merge is the tag point — exception: batch push tags each version at its own release-merge SHA):
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/tag-lockstep.mjs" \
@@ -200,16 +211,15 @@ node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/tag-lockstep.mjs" \
 node scripts/release/check-release.mjs --all-pending
 ```
 
-Per-package tags must be `✓ clean`; the umbrella-tag error is expected noise. On warns, run the enrichment pass ([`changelog-discipline.md`](changelog-discipline.md) §F-N1): fix the entry, land it as a follow-up commit through the PR flow (`--amend` is no longer possible — the release commit is already merged), delete + re-create the tags at the new post-merge SHA, re-run.
+Per-package tags must be `✓ clean`; the umbrella-tag error is expected noise. **Expected outcome: clean — Step 4f already ran the same matcher pre-PR.** A warn here means something changed between 4f and the tag (an interleaved merge, a 4f skip) — investigate the cause, then recover via [`changelog-discipline.md`](changelog-discipline.md) §F-N1: fix the entry, land it as a follow-up commit through the PR flow (`--amend` is not possible — the release commit is already merged), delete + re-create the tags at the new post-merge SHA, re-run.
 
-## §Step 8 — Push tags ← operator checkpoint 2 (before pushing tags)
+## §Step 8 — Push tags
 
 `main` is already on the remote (the release PR merged in Step 5.7) —
-only the tags push here. Show the Step 7 F-N1 results + the tag list (the
-evidence block for this checkpoint — see the table above) + confirm
-`git rev-list --count origin/main..HEAD` is 0 (a non-zero count means
-local commits bypassed the PR flow — stop and route them through a PR
-first); on go:
+only the tags push here. Log the Step 7 F-N1 results + the tag list
+(evidence table above) + confirm `git rev-list --count origin/main..HEAD`
+is 0 (a non-zero count means local commits bypassed the PR flow — stop
+and route them through a PR first); then:
 
 ```bash
 for t in web-components-vX.Y.Z web-modules-vX.Y.Z llm-vX.Y.Z a2ui-runtime-vX.Y.Z \
@@ -221,9 +231,9 @@ done                                     # pushes drop the create event (Scenari
 git -C "$REPO" push origin vX.Y.Z        # umbrella last; triggers nothing
 ```
 
-## §Step 9 — Publish ← operator checkpoint 3 (before publishing)
+## §Step 9 — Publish
 
-Show the current registry snapshot (per-package versions + `dist-tags.latest`) as this checkpoint's evidence. For batch pushes, confirm ordering with the operator against that snapshot: **oldest version publishes and settles first** — `npm dist-tag latest` is set by publish order. Then:
+Log the current registry snapshot (per-package versions + `dist-tags.latest`) before dispatching. For batch pushes, verify ordering against that snapshot: **oldest version publishes and settles first** — `npm dist-tag latest` is set by publish order. Then:
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
@@ -242,13 +252,15 @@ npm view @adia-ai/web-components dist-tags.latest   # must equal X.Y.Z
 
 Zero workflows fired after a tag push → [`recovery-paths.md`](recovery-paths.md) §Scenario 7.
 
-## §Step 10 — GH releases + site deploy ← operator checkpoint 4 (before deploying)
+## §Step 10 — GH releases + site deploy dispatch
 
 ```bash
 for pkg in <the 9>; do
   gh release create "$pkg-vX.Y.Z" --title "@adia-ai/$pkg vX.Y.Z" --notes-file <body>.md
 done
-# Site deploy goes through the pipeline, never a raw rsync (operator go required — deploy is checkpoint-class):
+# Site deploy goes through the pipeline, never a raw rsync. The dispatch is
+# covered by the cycle's single authorization; the workflow's own GitHub
+# environment gate (production-site required reviewers) is the human stop:
 gh workflow run "Deploy site (ui-kit.exe.xyz)" --repo adiahealth/gen-ui-kit --ref main
 ```
 
@@ -274,7 +286,15 @@ Always author notes at end-of-cycle without being asked — context is freshest
 
 ## §Variant A shortcut
 
-Peer pre-cut the release commit: Step 1 (confirm HEAD is the `release(*): vX.Y.Z` commit) → Step 2 → Step 3 → skip 4–5 → resume at Step 6.
+Peer pre-cut the release commit: Step 1 (confirm HEAD is the `release(*): vX.Y.Z` commit) → Step 2 → Step 3 → skip 4–5 → resume at Step 6. The peer's release commit must already be MERGED to `main` via its PR before tagging (invariant 3 — tag at post-merge HEAD, never at an unpushed local commit); an unmerged pre-cut commit goes through Step 5.7 first, it doesn't shortcut past it.
+
+## §Plugin cache — content between cuts is invisible until the next bump
+
+The installed Claude Code plugin cache is keyed by the version string in `.claude-plugin/plugin.json` — `/reload-plugins` only refreshes when that string CHANGES. Lockstep forbids a solo plugin bump, so any skill/agent/doc content merged to `main` between cuts does NOT reach the installed plugin until the next lockstep cut (or a deliberate manual `rsync` of the plugin dir over `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`). Consequences:
+
+- Shipping plugin-content changes mid-cycle is fine — just know they're repo-only until the next cut; don't report them as "live in the harness".
+- The v0.8.5 case (PR #304): a full release-process rewrite merged with no bump, and the installed plugin silently kept executing the RETIRED procedure until a manual cache sync. If the merged content changes operational behavior an active session depends on, do the manual sync immediately and say so.
+- At cut time nothing extra is needed — the lockstep bump itself is what invalidates the cache.
 
 ## §When to abort
 

package/skills/adia-release/references/independent-package-release.md

@@ -21,7 +21,7 @@
 | Demo-site deploy | yes | **none** |
 | Publish trigger | tag-triggered per-package workflow | same mechanism (`.github/workflows/publish-adia-ui-{factory,forge}.yml`) |
 
-Class B keeps the operator checkpoints and the verify-against-the-registry discipline; it drops every lockstep-specific invariant.
+Class B keeps the single-authorization model and the verify-against-the-registry discipline; it drops every lockstep-specific invariant.
 
 ## §New-package onboarding — the three trip-wires a FIRST cut hits
 

package/skills/adia-release/scripts/insert-stub.mjs

@@ -68,7 +68,7 @@ function buildStub(version, date, substantive, xref) {
   return `## [${version}] — ${date}
 
 ### Maintenance
-- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 9-package version coherence enforced by \`scripts/release/check-lockstep.mjs\`. Substantive v${version} work shipped in ${substantive}. See \`${xref}\` for details.
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 11-package version coherence enforced by \`scripts/release/check-lockstep.mjs\`. Substantive v${version} work shipped in ${substantive}. See \`${xref}\` for details.
 
 `;
 }

package/skills/adia-release/scripts/release-pack.mjs

@@ -4,8 +4,11 @@
 // Chains the 5 CLI helpers (bump · promote-unreleased · insert-stub ·
 // tag-lockstep · dispatch-publish) plus the non-helper steps (lockfile ·
 // pre-flight gates · git commit · F-N1 · push · GH releases · site
-// deploy) into one walked sequence with 3 operator checkpoints (before
-// tag, before push, before publish) per SKILL.md operator checkpoints.
+// deploy) into one walked sequence with 4 confirmation boundaries (before
+// tag, before push, before publish, before deploy dispatch). Under the
+// single-authorization model (SKILL.md §Authorization, operator ruling
+// 2026-07-17) `--go` auto-confirms all of them — the evidence blocks still
+// print as a log; the granular flags below remain for cautious manual runs.
 //
 // MODES (two-phase since 2026-07-16 — invariant 3: release commits land via
 // PR, so the cut modes stop after the release commit; handoff runs the
@@ -35,22 +38,27 @@
 //   --stub-packages a,b,c             : packages getting the lockstep stub
 //
 // FLAGS:
+//   --go                 : single-authorization — the operator's cut-start go
+//                          covers the whole cycle; equals --yes --push --publish.
+//                          THE standard invocation for an operator-initiated
+//                          release. An F-N1 warn still refuses auto-confirm at
+//                          the push boundary (a gate failure, not ceremony).
 //   --dry                : preview all commands, no mutation, no prompts
-//   --yes                : auto-confirm CHECKPOINT 1 ONLY (before tagging). Tag
-//                          creation is the least destructive of the three
-//                          mutating boundaries (moving/deleting a local-only
-//                          tag is free); push and publish each need their own
-//                          explicit go — --yes does not cover them (H5/defect-2:
-//                          a single --yes used to flatten all 3 checkpoints).
-//   --push               : auto-confirm CHECKPOINT 2 (before pushing tags)
-//   --publish            : auto-confirm CHECKPOINT 3 (before dispatching publishes)
+//   --yes                : auto-confirm the tag boundary ONLY. Tag creation is
+//                          the least destructive of the mutating boundaries
+//                          (moving/deleting a local-only tag is free); push and
+//                          publish each need their own flag — --yes does not
+//                          cover them (H5/defect-2: a single --yes used to
+//                          flatten every boundary).
+//   --push               : auto-confirm the push-tags boundary
+//   --publish            : auto-confirm the publish + deploy-dispatch boundaries
 //   --skip-gates         : (DEBUG ONLY) skip pre-flight (don't ship anything!)
 //   --skip-site          : skip the EXE deploy step (rare; for offline cycles)
 //
 // Part of the adia-release skill. Mechanizes the cut procedure from
-// references/cut-procedure.md while preserving operator judgment at
-// the 3 mutating-checkpoint boundaries. Every checkpoint prints its evidence
-// block BEFORE the prompt (H5) — never a bare y/N.
+// references/cut-procedure.md. Every confirmation boundary prints its evidence
+// block BEFORE the prompt (H5) — never a bare y/N — whether it waits for input
+// (manual flags) or auto-confirms (--go).
 
 import { execSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
@@ -108,6 +116,14 @@ function parseArgs(argv) {
     else if (k === '--yes') args.yes = true;
     else if (k === '--push') args.push = true;
     else if (k === '--publish') args.publish = true;
+    // --go: the single-authorization model (operator ruling 2026-07-17,
+    // replacing the 4-checkpoint ceremony after the v0.8.5 cut spent ~40
+    // minutes on approval relays that produced zero safety). The operator's
+    // cut-start instruction covers the WHOLE cycle; the run stops only on
+    // gate failures. Equivalent to --yes --push --publish; the F-N1
+    // error hard-stop and the warn-blocks-auto-confirm rule still apply —
+    // those are gates, not approvals, and no flag skips them.
+    else if (k === '--go') { args.yes = true; args.push = true; args.publish = true; }
     else if (k === '--skip-gates') args.skipGates = true;
     else if (k === '--skip-site') args.skipSite = true;
     else if (k === '-h' || k === '--help') { help(); process.exit(0); }
@@ -144,7 +160,10 @@ function help() {
     --substantive-packages web-components,web-modules,a2ui/corpus \\
     --stub-packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
 
-Flags: --dry  (preview all)  --yes  (auto-confirm checkpoint 1 ONLY — tag)
+Flags: --go   (single-authorization: the operator's cut-start go covers the
+               whole cycle — auto-confirms ALL checkpoints; stops only on
+               gate failures. THE DEFAULT for an operator-initiated release.)
+       --dry  (preview all)  --yes  (auto-confirm checkpoint 1 ONLY — tag)
        --push  (auto-confirm checkpoint 2 — push tags)
        --publish  (auto-confirm checkpoint 3 — dispatch publishes)
        --skip-site  (skip EXE deploy)
@@ -311,6 +330,15 @@ function step4PromoteAndBump(args) {
   sh(`node ${SCRIPT_DIR}/bump.mjs --from ${args.previous} --to ${args.version}`, args);
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
+
+  // Step 4f — pre-tag F-N1 coverage with auto-fix, run with the AUTHORITATIVE
+  // matcher (check-release.mjs itself, not the drifted 9-package
+  // check-changelog-coverage.mjs). Appends verified Maintenance bullets for
+  // any changed-but-unmentioned directory so the post-tag F-N1 (Step 7) is a
+  // formality. The v0.8.5 cut lacked this and paid 3 enrichment PRs + 3
+  // delete/retag rounds discovering the same gaps only after tagging.
+  console.log('\n  Step 4f — pre-tag coverage (+auto-fix) with the authoritative F-N1 matcher:');
+  sh(`node scripts/release/check-release.mjs --pending-version ${args.version} --fix`, args);
 }
 
 // ── Step 5 — Commit ──────────────────────────────────────────────

package/skills/adia-site-docs/SKILL.md

@@ -35,7 +35,7 @@ skill routes to it and enforces it, it does not restate it.
 | Task shape | Do |
 | --- | --- |
 | New page in an owned category | Read the convention doc's template section; copy the shared skeleton from a sibling page in the same category (narrative archetype vs. reference/gallery archetype). |
-| Callout / "meta content" block | `<alert-ui variant="warning\|info\|...">` with `<div slot="content">` (never `<span>` — the transpiler only treats `p`/`div`/`ul`/`ol` as prose; a `<span>` silently reorders mixed inline content on regen) for rich text — never a bare `data-*` attribute. A whole multi-heading section aimed at a different reader (not a short callout) is NOT `alert-ui`'s job either (wrong shape) — currently there's no working distinguishing treatment for this case beyond the heading text itself; see the convention doc's rule 2 for what's been tried and why it doesn't render. |
+| Callout / "meta content" block | `<alert-ui variant="warning\|info\|...">` with `<div slot="content">` (never `<span>` — the transpiler only treats `p`/`div`/`ul`/`ol` as prose; a `<span>` silently reorders mixed inline content on regen) for rich text — never a bare `data-*` attribute. A whole multi-heading section aimed at a different reader (not a short callout) is NOT `alert-ui`'s job either — wrong shape — the convention doc's rule 2 carries the working treatment (eyebrow `<tag-ui>` title-row, TKT-0011). |
 | Tamed admin-shell demo | Add `class="demo-frame"` to the shell instance + a page-local `<style>` block setting only `--demo-frame-height` (and any genuinely page-specific extra). That's `site/site.css`'s `.demo-frame` utility already covering `position`/`border`/`overflow`/`.demo-body` padding. |
 | A surface needs to read as "its own distinct object" against the page background (a chip, a pill) | Reuse `--a-canvas-well-strong` (`packages/web-components/styles/colors/semantics/core.css`) — verified ≥3:1 (WCAG 2.2 SC 1.4.11) in both schemes. `--a-canvas-well` alone is for a subtly-sunken panel; a new candidate token always runs through `color:color-verify` first. |
 | "Is this page consistent?" / review request | Check the page against the convention doc's rules 1–4 by name; a finding names the specific rule violated, not just "this looks off." |
@@ -63,6 +63,11 @@ A check that cannot run (missing script, no network for a build step) is a
 named blocker in the report — flag it and stop; never mark the page done on
 an assumed pass.
 
+The fresh-context critic for an authored page is the `framework-reviewer`
+agent (its dogfood visual probe covers rendered site surfaces) — the author
+never certifies their own page's rendered result; the mechanical checks
+above plus that read-only pass together are the review.
+
 Done when the touched page(s) pass the checks above and, for a reviewed
 page, every finding cites the specific rule in `site-pages-authoring.md` it
 violates.

package/skills/adia-site-docs/evals/routing-corpus.json

@@ -1,176 +1,38 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "adia-site-docs routing accuracy corpus",
-  "version": "1.0.0",
-  "purpose": "Routing-eval corpus for adia-site-docs (adia-forge plugin). Each phrase declares whether adia-site-docs SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
-  "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
-  "license": "internal",
-  "scope": "adia-site-docs routing — does this phrase activate adia-site-docs?",
-
-  "minimums_per_spec": {
-    "trigger_phrases": 16,
-    "adversarial_phrases": 6,
-    "task_shapes_covered": "new-page, review-page, callout-fix, demo-frame-consistency, contrast-token, sibling-boundary",
-    "adversarial_fraction": "27%"
-  },
-
-  "phrases": [
-    {
-      "id": "site-docs-review-01",
-      "phrase": "review this site docs page for consistency",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Canonical review-a-page task shape."
-    },
-    {
-      "id": "site-docs-review-02",
-      "phrase": "does this callout look like plain text to you",
-      "should_route_to_site_docs": true,
-      "expected_shape": "callout-fix",
-      "rationale": "Symptom description matching Defect 2 (fabricated data-alert)."
-    },
-    {
-      "id": "site-docs-review-03",
-      "phrase": "why is the code background not visible on this page",
-      "should_route_to_site_docs": true,
-      "expected_shape": "contrast-token",
-      "rationale": "Symptom description matching Defect 1 (inline-code contrast)."
-    },
-    {
-      "id": "site-docs-new-page-01",
-      "phrase": "add a new pattern page under site/pages/patterns",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "Explicit site/pages/patterns path mention."
-    },
-    {
-      "id": "site-docs-new-page-02",
-      "phrase": "author a new getting-started guide page",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "getting-started/ is one of this skill's 5 owned categories."
-    },
-    {
-      "id": "site-docs-new-page-03",
-      "phrase": "write a new architecture explainer page for the docs site",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "architecture/ is one of this skill's 5 owned categories."
-    },
-    {
-      "id": "site-docs-new-page-04",
-      "phrase": "create a reference page documenting the MCP tools",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "reference/ is one of this skill's 5 owned categories."
-    },
-    {
-      "id": "site-docs-demo-frame-01",
-      "phrase": "this demo page needs a tamed static frame like the other pattern pages",
-      "should_route_to_site_docs": true,
-      "expected_shape": "demo-frame-consistency",
-      "rationale": "Matches the .demo-frame consolidation rule."
-    },
-    {
-      "id": "site-docs-demo-frame-02",
-      "phrase": "add a new admin-shell demo to this patterns page without duplicating the taming CSS",
-      "should_route_to_site_docs": true,
-      "expected_shape": "demo-frame-consistency",
-      "rationale": "Direct match on rule 3 (reuse .demo-frame)."
-    },
-    {
-      "id": "site-docs-review-04",
-      "phrase": "is this site page consistent with our authoring conventions",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Direct convention-compliance ask."
-    },
-    {
-      "id": "site-docs-review-05",
-      "phrase": "audit site/pages/guides for the same callout bug we found elsewhere",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Explicit guides/ path + defect-class reference."
-    },
-    {
-      "id": "site-docs-callout-01",
-      "phrase": "this warning box on the docs page has no background at all",
-      "should_route_to_site_docs": true,
-      "expected_shape": "callout-fix",
-      "rationale": "Symptom description matching the fabricated data-alert defect."
-    },
-    {
-      "id": "site-docs-new-page-05",
-      "phrase": "what's the shared skeleton every site docs page should follow",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "Direct ask about the template decomposition this skill carries."
-    },
-    {
-      "id": "site-docs-contrast-01",
-      "phrase": "what token should a new chip-like surface use to stay readable against the page background",
-      "should_route_to_site_docs": true,
-      "expected_shape": "contrast-token",
-      "rationale": "Direct match on rule 1 (--a-canvas-well-strong)."
-    },
-    {
-      "id": "site-docs-review-06",
-      "phrase": "check the patterns pages for any other unstyled data attributes like data-alert",
-      "should_route_to_site_docs": true,
-      "expected_shape": "review-page",
-      "rationale": "Direct defect-class sweep request."
-    },
-    {
-      "id": "site-docs-new-page-06",
-      "phrase": "scaffold a new getting-started/theming-dark-mode.html page",
-      "should_route_to_site_docs": true,
-      "expected_shape": "new-page",
-      "rationale": "Explicit new-file-under-owned-category shape."
-    },
-
-    {
-      "id": "site-docs-adversarial-01",
-      "phrase": "review this component's own demo gallery in its .examples.html file",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "packages/web-components/components/*/*.examples.html is adia-author's remit, not this skill's."
-    },
-    {
-      "id": "site-docs-adversarial-02",
-      "phrase": "fix this gen-ui training exemplar page under site/pages/examples",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "site/pages/examples/** is the pure-primitive-composition training-harvest surface governed by composition-and-examples.md + adia-a2ui, explicitly fenced out."
-    },
-    {
-      "id": "site-docs-adversarial-03",
-      "phrase": "tune the zettel retrieval threshold for the chunk corpus",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "A2UI pipeline internals belong to adia-a2ui, unrelated to site/pages authoring."
-    },
-    {
-      "id": "site-docs-adversarial-04",
-      "phrase": "add a new prop to the button-ui primitive",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "Primitive authoring is adia-author's remit."
-    },
-    {
-      "id": "site-docs-adversarial-05",
-      "phrase": "cut the next npm release for the 9 @adia-ai packages",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "Release engineering is adia-release's remit, unrelated to docs-page authoring."
-    },
-    {
-      "id": "site-docs-adversarial-06",
-      "phrase": "deploy the docs site to ui-kit.exe.xyz",
-      "should_route_to_site_docs": false,
-      "expected_shape": "sibling-boundary",
-      "rationale": "Deploy operations are adia-deploy's remit; this skill authors content, it doesn't ship it."
-    }
+  "positives": [
+    "review this site docs page for consistency",
+    "does this callout look like plain text to you",
+    "why is the code background not visible on this page",
+    "add a new pattern page under site/pages/patterns",
+    "author a new getting-started guide page",
+    "write a new architecture explainer page for the docs site",
+    "create a reference page documenting the MCP tools",
+    "this demo page needs a tamed static frame like the other pattern pages",
+    "add a new admin-shell demo to this patterns page without duplicating the taming CSS",
+    "is this site page consistent with our authoring conventions",
+    "audit site/pages/guides for the same callout bug we found elsewhere",
+    "this warning box on the docs page has no background at all",
+    "what's the shared skeleton every site docs page should follow",
+    "what token should a new chip-like surface use to stay readable against the page background",
+    "check the patterns pages for any other unstyled data attributes like data-alert",
+    "scaffold a new getting-started/theming-dark-mode.html page"
   ],
-
-  "evaluator_notes": "Adversarial phrases 1-2 specifically test the two hardest-to-distinguish fences (component .examples.html vs site/pages/patterns/*.html; site/pages/examples/** vs site/pages/{architecture,getting-started,guides,patterns,reference}/**) — both surfaces are literally *.html under similar-looking paths, so the description must lean on the explicit path lists, not just 'site pages' as a phrase."
+  "negatives": [
+    "review this component's own demo gallery in its .examples.html file",
+    "fix this gen-ui training exemplar page under site/pages/examples",
+    "tune the zettel retrieval threshold for the chunk corpus",
+    "add a new prop to the button-ui primitive",
+    "cut the next npm release for the 9 @adia-ai packages",
+    "deploy the docs site to ui-kit.exe.xyz",
+    "fix this gen-ui training exemplar page",
+    "add a demo to the patterns page for card-ui"
+  ],
+  "_measured": {
+    "as_of": "2026-07-18",
+    "scorer": "routing_eval.py (nonoun-plugins/forge)",
+    "f1": 0.733,
+    "precision": 0.786,
+    "recall": 0.688,
+    "exit_code": 0
+  }
 }