@event4u/agent-config 14.22.0 → 14.23.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-299-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-120-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-204-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-118-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
+[![Skills](https://img.shields.io/badge/Skills-299-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-120-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-204-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-119-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
 
 <sub>**How these are counted** — one canonical counter, `agent-config` → `update_counts --check`, re-derives all six from the tree and fails CI on a drift of one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: **Commands 202** counts every command file **recursively** (the linked directory holds 61 at its top level), and **Rules 120** counts the **source** rules while the linked projection holds 119 — one rule is dormant and is not projected. **Personas 29** excludes the directory README. Counts are of files and directories: none of them measures quality, activation, or adoption. <!-- claim:published-artifact-counts --></sub>
 

package/dist/agent-src/commands/pr/merge.md

@@ -4,13 +4,13 @@ name: git-pr-merge
 disable-model-invocation: true
 argument-hint: "[all|<pr-number>] [--no-merge]"
 pack: git
-intent: "Prepare an open PR to mergeable — sync the base in, resolve conflicts semantically, drive required checks green — merging itself is gated and inert"
+intent: "Prepare an open PR to mergeable — sync the base in, resolve conflicts semantically, drive required checks green — then merge what the invocation named"
 routes_to: [git-workflow, github-ci]
 replaces: []
 visibility: advanced
 cluster: git-pr-merge
 skills: [git-workflow, github-ci]
-description: Prepare one open PR to mergeable, or the whole open-PR queue with `all` — merging is specified but gated, so today every invocation stops at mergeable-and-open
+description: Prepare one open PR to mergeable, or the whole open-PR queue with `all`, then merge what the invocation named — `--no-merge` stops at mergeable-and-open
 suggestion:
   eligible: false
   rationale: "Merging is irreversible and gated on the user's own word in the invocation — a suggested merge would manufacture the authorization the Hard Floor requires the user to give."
@@ -28,10 +28,13 @@ green on the head that will actually be merged — and then merge it, if and onl
 if the invocation authorised that.
 
 ```
-THE MERGE STEP (§ 9) IS SPECIFIED AND NOT YET ACTIVE. `--no-merge` IS THE
-OPERATIVE PATH TODAY, AND A BARE INVOCATION BEHAVES AS IF IT CARRIED IT.
-ACTIVATION NEEDS THE OWNER DECISION IN THE `merge-authority` BLOCKER OF
-`road-to-drain-commands` — NEVER A COMMAND EDIT, AND NEVER A GUARD EDIT.
+THE MERGE STEP (§ 9) IS ACTIVE. THE OWNER AUTHORISED IT ON 2026-09-08 AND
+ADR-266 RECORDS THE AMENDMENT TO ADR-237 § 4 THAT ACTIVATED IT — THAT RECORD
+IS WHAT ACTIVATED IT, NEVER A COMMAND EDIT AND NEVER A GUARD EDIT.
+AN EXPLICIT `/pr:merge` INVOCATION IS THE THIS-TURN CONFIRMATION, AND IT
+REACHES EXACTLY THE PRs § 1's MANIFEST SNAPSHOTTED FROM IT. IT NEVER REACHES
+A PR THAT ARRIVED LATER, A HEAD THE MANIFEST DID NOT RECORD, OR ANY OTHER
+HARD-FLOOR ACTION. `--no-merge` STILL STOPS BEFORE § 9.
 ```
 
 **The invocation is the authorization, and nothing else is.** `pr-merge` is
@@ -42,11 +45,12 @@ authorized, and this command still reads it as an audit trail; it introduces no
 second authorization store, and it never writes one. When the work left is
 outside what the owner authorized, the run stops and reports (§ 7).
 
-Why it ships inert rather than not at all: everything before § 9 — the target
-manifest, the four conflict classes, the superseded check, the bounded CI
-repair, the cutoff — is the expensive, error-prone half, it is what the live
-runs actually proved, and none of it merges anything. `--no-merge` delivers all
-of it today.
+Why the preparation half is still the bulk of this command: everything before
+§ 9 — the target manifest, the four conflict classes, the superseded check, the
+bounded CI repair, the cutoff — is the expensive, error-prone part, and it is
+what the live runs actually proved. `--no-merge` delivers exactly that half to
+callers that want it, [`/roadmap:process-full`](../../../product-basic/roadmap/process-full/command.md)
+among them.
 
 ## Sub-commands
 
@@ -62,15 +66,16 @@ different lifecycle, not a different count.
 
 ## Dispatch
 
-Every row below **prepares** — the merge step is gated (see the banner above),
-so today every row ends at mergeable-and-open. The column says what each row
-selects, not that it merges.
+Every row below **prepares** first; the last column says whether it then
+merges. A row that merges reaches only the PRs its own manifest snapshotted
+(§ 1), and only once that PR's required checks are green on the head being
+merged (§ 5).
 
 | Invocation | Selects | Prepares | Merges |
 |---|---|---|---|
-| `/pr:merge <N>` | exactly PR N | yes | only once the gate opens |
-| `/pr:merge` | ONE PR: green first, then infrastructure/tooling before content, then smallest diff (`changedFiles`, then additions+deletions), tiebreak ascending number | yes | only once the gate opens |
-| `/pr:merge all` | the whole open-PR list, under § 6's cutoff | yes | only once the gate opens |
+| `/pr:merge <N>` | exactly PR N | yes | yes — PR N |
+| `/pr:merge` | ONE PR: green first, then infrastructure/tooling before content, then smallest diff (`changedFiles`, then additions+deletions), tiebreak ascending number | yes | yes — the one PR it selected |
+| `/pr:merge all` | the whole open-PR list, under § 6's cutoff | yes | yes — the manifest, in queue order |
 | `… --no-merge` | as above | yes | **never**, explicitly. This is the form [`/roadmap:process-full`](../../../product-basic/roadmap/process-full/command.md) calls for its delivery loop. |
 
 **Bare invocation** (`/pr:merge` with no argument) is a **documented default
@@ -81,7 +86,7 @@ to pick would hand back a decision the command can compute. When the open-PR
 list is empty there is nothing to select and the command reports that and
 stops.
 
-## 1. Snapshot the target — an immutable manifest
+## 1. Snapshot the target — a manifest re-checked before every merge
 
 Compute the queue ONCE at invocation and record it as a manifest of
 `(PR number, head SHA)` pairs:
@@ -102,7 +107,11 @@ other than this run" is undetectable without a base SHA to compare against.
 cap truncated.
 
 The manifest is the authorization's target set and is **never silently
-refreshed by a third party's push**. It is, by design, advanced by *this run's
+refreshed by a third party's push**. It lives in this run's own context and in
+no file, so nothing verifies it and no gate would notice if it drifted — what
+actually binds the target is the pre-merge re-read below, a check that fires,
+not a property that holds. Say "re-checked", never "immutable" (ADR-266
+§ What this record does not claim, finding 3). It is, by design, advanced by *this run's
 own* commits — § 2 merges the base in and § 5 pushes, so a prepared PR's head
 is never the snapshot head, and a naive "refuse when the SHA moved" check would
 fire on every PR the run touches.
@@ -195,11 +204,12 @@ AND RECORD IT AS `blocked-external`.
 ```
 
 The asymmetry is deliberate and worth stating, because it looks inconsistent:
-merging is gated on an owner *decision* recorded once in a blocker, while
-closing is gated on a *per-object* confirmation every time. Merging this run's
-own PR is an action the run's whole design is about; closing a PR someone else
-opened is not, it destroys their work in progress, and no guard in this tree
-sees it happen. The cheaper gate goes on the action nothing else watches.
+merging is authorised once by the invocation, while closing needs a *per-object*
+confirmation every time. Merging a PR this queue prepared is the action the
+run's whole design is about, and § 1's manifest already binds it to a named
+number and a recorded head; closing a PR someone else opened is neither, it
+destroys their work in progress, and no guard in this tree sees it happen. The
+stricter gate goes on the action nothing else watches.
 
 ## 5. Drive CI green — bounded
 
@@ -240,13 +250,12 @@ After each merge the base has moved, so the next PR is re-synced against the
 NEW base — that is the loop, and it is why pre-greening several PRs ahead of
 their merges is wasted work.
 
-**While the merge step is gated, that loop does not turn**, and the section
-below is written for when it does. Nothing merges, so the base does not
-advance, no PR leaves the open list, and an `all` run is a **preparation
-sweep**: it syncs, classifies, greens and reports each PR once, then stops. It
-does not re-prepare a PR its own predecessor invalidated, because it has no
-predecessor that landed. The cutoff below still bounds it; the window below
-still cannot close it, for the reason § 7 gives.
+**Under `--no-merge` that loop does not turn**, and the paragraph above is
+written for the form that does. Nothing merges, so the base does not advance,
+no PR leaves the open list, and the run is a **preparation sweep**: it syncs,
+classifies, greens and reports each PR once, then stops. It does not re-prepare
+a PR its own predecessor invalidated, because it has no predecessor that
+landed. The cutoff below bounds both forms.
 
 **Cutoff.** When the manifest is exhausted, recompute the open-PR list
 **exactly once**. PRs that appeared during the run are drained as ONE final
@@ -308,10 +317,9 @@ run, and do not proceed to the next PR.
 
 ## 8. Kill switches, and what happens after a merge
 
-**Armed during preparation, not only before a merge** — otherwise every switch
-below is unreachable while the merge step is gated, and a preparation sweep has
-no way to stop at all. Each one aborts the current PR and ends the run on any
-of:
+**Armed during preparation, not only before a merge** — otherwise a
+`--no-merge` sweep would have no way to stop at all. Each one aborts the current
+PR and ends the run on any of:
 
 - target number or head SHA differs from the manifest;
 - the base advanced by an actor other than this run;
@@ -365,9 +373,10 @@ conflict resolution. The disposition set is closed:
 
 ## Rules
 
-- **Never merge while the gate is closed.** Until the `merge-authority`
-  blocker resolves, every invocation stops at mergeable-and-open, `--no-merge`
-  or not. Once it opens, `--no-merge` is still the explicit way to say stop.
+- **Never merge a PR the invocation did not name.** The authorization is the
+  owner's own `/pr:merge` sentence and reaches exactly the manifest § 1
+  snapshotted from it; a PR that arrived afterwards needs its own go-ahead.
+  `--no-merge` is the explicit way to say stop before § 9.
 - **Never widen, patch, or rebuild-around the git guard.** Verification of the
   authorization window is read-only.
 - **Never rebase a pushed branch**; the base is merged in.

package/dist/agent-src/commands/roadmap/next.md

@@ -148,6 +148,14 @@ ONE THAT MOVES MORE CHECKBOXES. PICKING BY CHECKBOX COUNT IS THE
 GOODHART MOVE THIS PACKAGE'S OWN DISCIPLINE FORBIDS.
 ```
 
+**An owner-recorded precedence outranks the severity read.** Where an accepted ADR
+states that a named roadmap or set is worked first, that record is the ranking and
+this section does not re-derive one — the owner has already made the call the
+council would otherwise settle. Precedence is not a bypass: a precedent roadmap
+still passes every disqualifier in step 2, and a disqualified precedent roadmap is
+skipped with its disqualifier named like any other. A `proposed` record carries no
+precedence.
+
 - **Exactly one survivor, or one that dominates** → take it, state the
   one-line reason inline, proceed. Do not ask
   ([`no-cheap-questions`](../../rules/no-cheap-questions.md)).

package/dist/agent-src/contexts/execution/autonomy-mechanics.md

@@ -193,6 +193,18 @@ decision. Engage per [`rdp-gate`](rdp-gate.md).
 The suite states three retry numbers; they are **stages of one escalation
 ladder on the same failing target**, not competing budgets:
 
+0. **Attempt 1 fails → read the candidate list, if one exists, BEFORE retry 1.**
+   Where the run recorded a candidate set for this work
+   ([`notes-first-reasoning`](../../rules/notes-first-reasoning.md)
+   § Reopening), the first failure reads it first: a failure is evidence about
+   the CHOSEN FORM, and retrying the same approach spends the budget without
+   ever reaching the second-best candidate — which is how the mechanism that
+   discovers a form was wrong never routes back to the form. Where no candidate
+   list exists the ladder is unchanged and stage 1 runs immediately.
+   **This adds a branch; it does not move the budget.** Reading the list is not
+   an attempt and is not counted, and the reopen is capped at one per candidate:
+   the second contradiction on the same candidate continues down this ladder
+   rather than reopening again.
 1. **Attempt 1 fails → up to 2 retries of the same approach**
    ([`think-before-action`](../../rules/think-before-action.md) "MAX 2
    RETRIES PER APPROACH") — the soft, agent-side stage: rethink between

package/dist/agent-src/rules/notes-first-reasoning.md

@@ -24,11 +24,8 @@ obligation_frequency: "per-turn"
 # Notes-First Reasoning
 
 Part of the Reasoning Discipline Protocol. Engage per
-[`rdp-gate`](../contexts/execution/rdp-gate.md) (settings + task-signal + host
-self-assessment) — skip on trivial tasks; apply lightly on a strong-reasoning
-host. The notes file is grounded in the documented cross-run lessons memory
-(consolidated via [`memory-consolidation`](../skills/memory-consolidation/SKILL.md));
-the in-task sections below are a local derivation for within-task scope.
+[`rdp-gate`](../contexts/execution/rdp-gate.md) — skip on trivial tasks, apply
+lightly on a strong-reasoning host.
 
 ## The Iron Law
 
@@ -38,36 +35,50 @@ NOTES FILE — NEVER ECHOED INTO THE RESPONSE.
 THE RESPONSE CARRIES CONCLUSIONS + EVIDENCE ONLY.
 ```
 
-Reasoning dumped into the user-facing answer is both noise and a
-`reasoning_extraction` refusal risk (see `rdp-gate`). Keep it in the notes file.
-This is not "show your work in the reply" — it is the opposite.
+This is not "show your work in the reply" — it is the opposite. Why, and what
+grounds the notes file:
+[`notes-horizon-mechanics`](../docs/guidelines/agent-infra/notes-horizon-mechanics.md).
 
 ## Notes file structure (the file, not the response)
 
-Use the sections that apply; the structure carries the enumeration, so there is
-no "write N hypotheses" instruction — record what the work actually surfaced.
+Use the sections that apply — record what the work actually surfaced.
 
 - `## In-Task Hypothesis Log` — competing explanations under consideration.
-- `## Killed beliefs` — each discarded hypothesis + the evidence that killed it.
-- `## Predictions` — prediction · confidence · result · lesson (the calibration
-  loop: hypothesis → prediction → reality → calibration).
-- `## Decisions` — decision · alternatives · reason · revisit-if. Tactical,
-  in-task decisions stay here; **escalate to
-  [`decision-record`](../skills/decision-record/SKILL.md)/ADR** when the decision
-  is cross-task or architectural (litmus: would a dev on a different component
-  next month need this context?).
+- `## Killed beliefs` — each discarded hypothesis + the `killed-if` that killed
+  it.
+- `## Predictions` — **chosen form** · prediction · confidence · result · lesson.
+- `## Decisions` — decision · alternatives · reason · revisit-if ·
+  **next-commitment**. Tactical decisions stay here; **escalate to
+  [`decision-record`](../skills/decision-record/SKILL.md)/ADR** when cross-task
+  or architectural.
 - `## Uncertainty` — per-dimension score (e.g. architecture/implementation/
   requirements: high/medium/low); feeds the adaptive-effort decision.
 
+### The horizon — where `next-commitment` ends
+
+```
+A CHOICE AUTHORISES WORK UP TO THE NEXT EVIDENCE-PRODUCING BOUNDARY.
+NAME THE BOUNDARY FROM THE LIST. NEVER "THE WORK THE EVIDENCE SUPPORTS" —
+THAT IS A JUDGEMENT, AND A JUDGEMENT IS NOT A HORIZON.
+```
+
+### Reopening — once, on contradiction, never on a schedule
+
+```
+AN OBSERVATION THAT CONTRADICTS THE PREDICTION REOPENS THE CHOICE BEFORE THE
+NEXT STEP — FROM THE CANDIDATE LIST THAT ALREADY EXISTS, NEVER A FRESH
+ENUMERATION. ONE REOPEN PER CANDIDATE. THE SECOND CONTRADICTION HANDS OVER TO
+THE RETRY-BUDGET LADDER RATHER THAN REOPENING AGAIN.
+```
+
 ## What stays out of notes
 
-User-attribute facts, transient TODOs, and durable cross-run lessons — those go
-to the memory system (`memory-consolidation`), not the in-task notes.
+User-attribute facts, transient TODOs, and durable cross-run lessons go to the
+memory system (`memory-consolidation`), not the in-task notes.
 
 ## See also
 
-- [`rdp-gate`](../contexts/execution/rdp-gate.md) — the table-free engagement gate.
-- [`memory-consolidation`](../skills/memory-consolidation/SKILL.md) — promotes
-  durable lessons across runs.
-- [`verify-before-complete`](verify-before-complete.md) — the evidence the
-  response carries comes from real tool results.
+[`notes-horizon-mechanics`](../docs/guidelines/agent-infra/notes-horizon-mechanics.md)
+— every mechanic this rule points at. Also
+[`rdp-gate`](../contexts/execution/rdp-gate.md) and
+[`verify-before-complete`](verify-before-complete.md).

package/dist/agent-src/scripts/archive_completed_roadmaps.ts

@@ -58,7 +58,11 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import { collect } from './update_roadmap_progress.js';
+import {
+    blocker_is_resolved,
+    collect,
+    parse_blockers,
+} from './update_roadmap_progress.js';
 import { guardedBaselineProblems, parseGuardedBaselines } from './guarded_baseline.js';
 
 import { isCliEntry } from './_cli_entry.js';
@@ -265,6 +269,80 @@ function _git_mv(root: string, src_rel: string, dst_rel: string, dry_run: boolea
     }
 }
 
+// ---------------------------------------------------------------------
+// The index/working-tree blocker divergence check (1b) + staging (1a)
+// ---------------------------------------------------------------------
+//
+// The open-blocker refusal below reads the file with `fs.readFileSync`, i.e.
+// the WORKING TREE. `git mv` then moves the INDEX ENTRY, which still carries
+// whatever was staged. When the two disagree the commit ships the index
+// content — content this gate never read.
+//
+// Measured, once, at full cost (2026-09-08): an edit removing a roadmap's
+// blocker was made and never staged; `git mv` moved the stale index entry; the
+// archived file shipped a blocker declared `Status: open` that had already been
+// relocated to an active roadmap. The same blocker was open in two files at
+// once, one of them archived, and it was caught by a human reading
+// `git status` rather than by any gate.
+//
+// The check is scoped to blocker id → status and deliberately NOT to whole-file
+// equality. An unstaged typo fix in a roadmap title has nothing to do with the
+// defect, and refusing archival for it trains `git add -A`, which destroys the
+// staging discipline this check depends on. AI council 2026-09-08, 2/2 present
+// (anthropic/claude-sonnet-4-5 + openai/gpt-4o), on that scoping specifically:
+// broad scoping is "user-hostile, trains developers to `git add -A`
+// reflexively, defeating staging discipline".
+
+/** Blocker id → status, as the archive-transition check compares them. */
+function _blockerStatuses(text: string): Map<string, string> {
+    const out = new Map<string, string>();
+    for (const b of parse_blockers(text)) {
+        out.set(b.id, blocker_is_resolved(b) ? 'resolved' : 'open');
+    }
+    return out;
+}
+
+/**
+ * `git show :<rel>` — the STAGED content of a path, or null when the path has
+ * no index entry.
+ *
+ * Null is the untracked / pre-first-commit case, which `_git_mv` already
+ * handles by falling back to a plain rename. There is no index entry to
+ * disagree with, so the divergence check has nothing to assert and says so by
+ * returning null rather than by guessing at an empty string — an empty staged
+ * file and an absent one differ, and only the second is legitimate here.
+ */
+function _indexContent(root: string, rel: string): string | null {
+    const cp = _run(['git', 'show', `:${rel}`], root);
+    return cp.returncode === 0 ? cp.stdout : null;
+}
+
+/**
+ * Human-readable disagreements between the staged and working-tree blocker
+ * maps of one path. Empty array = the two agree, or there is no index entry.
+ */
+function _blockerDivergence(root: string, rel: string, workTreeText: string): string[] {
+    const staged = _indexContent(root, rel);
+    if (staged === null) {
+        return [];
+    }
+    const wt = _blockerStatuses(workTreeText);
+    const idx = _blockerStatuses(staged);
+    const ids = [...new Set([...wt.keys(), ...idx.keys()])].sort();
+    const out: string[] = [];
+    for (const id of ids) {
+        const a = idx.get(id);
+        const b = wt.get(id);
+        if (a === b) {
+            continue;
+        }
+        out.push(
+            `blocker '${id}': staged=${a ?? 'absent'} vs working tree=${b ?? 'absent'}`,
+        );
+    }
+    return out;
+}
+
 /**
  * Repo-relative paths of files containing `needle`, by walking the filesystem.
  *
@@ -547,9 +625,8 @@ function archive_completed(
         // and invisible in a sweep that only reports what it moved; a MALFORMED
         // one on `[x]` would otherwise archive with an annotation claiming the
         // opposite. Both are named here instead.
-        const guarded = parseGuardedBaselines(
-            fs.readFileSync(path.join(roadmap_root, stats.rel), 'utf-8'),
-        );
+        const roadmapText = fs.readFileSync(path.join(roadmap_root, stats.rel), 'utf-8');
+        const guarded = parseGuardedBaselines(roadmapText);
         if (guarded.length > 0) {
             process.stderr.write(
                 `  ⚠️  ${stats.rel}: ${guarded.length} guarded-baseline step(s) — ` +
@@ -603,12 +680,37 @@ function archive_completed(
         if (changed_only && !(touched as Set<string>).has(old_rel)) {
             continue; // complete, but not this branch's work
         }
+        // The gate above validated the WORKING TREE; `git mv` ships the INDEX.
+        // When they disagree about a blocker, the validated content is not the
+        // content that gets committed — see § the index/working-tree blocker
+        // divergence check above for the measured failure.
+        const divergence = _blockerDivergence(root, old_rel, roadmapText);
+        if (divergence.length > 0) {
+            process.stderr.write(
+                `  ⚠️  ${stats.rel}: staged and working-tree blockers disagree ` +
+                    `(${divergence.length}) — not archived. \`git mv\` would commit ` +
+                    'the staged content, which this sweep never validated. Stage or ' +
+                    'discard the change, then re-run.\n',
+            );
+            for (const d of divergence) {
+                process.stderr.write(`        · ${d}\n`);
+            }
+            continue;
+        }
         const new_rel = `agents/roadmaps/archive/${stats.rel}`;
         const mv = _git_mv(root, old_rel, new_rel, dry_run);
         if (!mv.ok) {
             process.stderr.write(`  ⚠️  could not archive ${old_rel} (mv failed)\n`);
             continue;
         }
+        // `git mv` moved the index ENTRY, not the working-tree content. Staging
+        // the destination makes what gets committed identical to what the checks
+        // above read — the divergence check refuses a disagreement that exists
+        // BEFORE the move, and this closes one created by an edit between the
+        // move and the commit.
+        if (!dry_run && mv.tracked) {
+            _run(['git', 'add', '--', new_rel], root);
+        }
         const refs = _inbound_ref_rewrite(root, old_rel, new_rel, dry_run, mv.tracked);
         // Stage rewritten refs only in a tracked repo; an untracked consumer's
         // files are not in the index, so the filesystem rewrite is the whole job.

package/dist/agent-src/skills/code-intelligence/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: code-intelligence
-description: "Route codebase-structure questions (who calls X, where is this used, what imports, change-impact) to an existing code-graph first: cheaper, never more precise; grep stays routine. Also 'call graph'."
+description: "Route codebase-structure questions (who calls X, where used, change-impact) to an existing code-graph first: impact, tests-for, dead cheaper, never more precise; grep routine. Also 'call graph'."
 domain: engineering
 workspaces:
   - engineering
@@ -204,6 +204,62 @@ refresh` first, or use grep and say so. This is a freshness obligation, not an
 ordering claim; the rule's query-first ordering still governs which source to
 reach for.
 
+## The four gate verbs — a diff, not a symbol (2026-09-08)
+
+`query` / `affected` / `path` / `explain` answer a question about a SYMBOL.
+Four more answer a question about a DIFF, and they are documented here rather
+than in § Procedure for a mechanical reason worth stating: step 4.3 of
+`road-to-a-graph-that-is-shipped` verifies that this file's line 164 — the
+**No class is graph-first** sentence — is unchanged, and inserting anything
+above it moves that line. So the ordering claim K5 protects stays byte-fixed
+and the new material sits below it.
+
+Each of the four walks only edges whose resolution mechanism is a stated fact
+(never a repo-wide same-name guess, never an untyped receiver), and each prints
+the mechanisms it accepted, the mechanisms it refused, and the graph's
+staleness — so a narrow answer is distinguishable from a decoupled one:
+
+- `agent-config code-graph impact --diff <rev>` — callers, dependents and test
+  files reachable from the changed symbols, plus the producing edges and a
+  minimal read set.
+- `agent-config code-graph tests-for <symbol>` — the test files that import it.
+  An empty list is a finding, not an error.
+- `agent-config code-graph untested --diff <rev>` — changed symbols that no test
+  file imports.
+- `agent-config code-graph dead [--entry-points F | --accept-missing-exports]` —
+  symbols with no accepted reference that no declared entry point names. It
+  **refuses** rather than answering while an entry-point source cannot be read:
+  this engine records no exportedness, so without a supplied list an
+  exported-but-unimported symbol is indistinguishable from a dead one, and a
+  confident false "dead" invites a deletion the graph cannot justify. Nothing it
+  lists is a deletion recommendation.
+
+These answers reach an agent over MCP without shelling out, and the mapping is
+**not** one tool per verb — corrected after an independent review found this
+paragraph claiming "the same five answers" directly after a list of four:
+
+| MCP tool | answers |
+|---|---|
+| `graph_impact` | `impact --diff`, **and** `untested --diff` via `untested_only: true` |
+| `graph_tests_for` | `tests-for` |
+| `graph_dead` | `dead` |
+| `graph_query` | `query` |
+| `graph_path` | `path` |
+
+`untested` has no tool of its own; it is a flag on `graph_impact`, because the
+two answer the same question over the same diff and a sixth tool would have cost
+standing context for a boolean. `graph_impact` is the only one that is not
+read-only — it runs `git diff --name-only` to resolve its rev — and
+`graph_dead`'s refusal arrives as `status: "refused"`, never as `status: "ok"`
+with an empty list.
+
+**No ordering claim is added here, and no measurement claim either.** These
+verbs are cheaper than reconstructing the same relationship by hand — that is a
+claim about the ALTERNATIVE being a manual reconstruction, not about grep.
+Nothing on this page says they beat grep, none of the four appears in the v2
+benchmark corpus (which measures `callers`, `transitive-impact`, `path-between`
+and `references`), and § Measured twice still governs that question.
+
 ## Do NOT
 
 - Do NOT rebuild a **fresh** consumer-shipped index — query it (interop

package/dist/agent-src/skills/git-workflow/references/push-closes-its-loop.md

@@ -68,6 +68,15 @@ returned 0, the turn closed, and the red arrived where the user found it.
   ending the turn silently on one is what the reminder exists to stop. Whether
   the reminder changes behavior is unmeasured — it ships as a carrier, not as a
   claim.
+- **`ci_settle` will not answer for a head that stopped mattering.** Since
+  2026-09-08 it reads the PR's `state` and compares its recorded head against
+  `git ls-remote` — before the wait and again at verdict time — and exits 2 with
+  a reason when the PR is merged, closed, or record-behind-branch. A green names
+  the head it is about. The measured reason: a merged PR's rollup kept answering
+  with its merge-time checks, so the tool reported `SETTLED GREEN — 40 check(s)`
+  for a commit that had zero check runs. The check does not apply to a fork PR
+  whose ref is not under this `origin`, and the line says so instead of claiming
+  it passed.
 - **Neither reaches a host without the slot.** `agent-config hooks:status`
   answers which slots are bound where you actually are; `post_tool_use` is
   unbound on windsurf and copilot, and there the settle obligation is

package/dist/agent-src/skills/tailwind-engineer/SKILL.md

@@ -51,6 +51,42 @@ radius, spacing, shadow, font-size to a configured token. If the design hands yo
 (`bg-[#3B82F6]`, `mt-[17px]`) are a smell — accept only with a
 one-line comment naming the design source.
 
+**That paragraph is written for greenfield, and artifact-bound work inverts
+it.** When a provided finished design is the spec
+([`design-fidelity`](../../rules/design-fidelity.md)), `#3B82F6` is a decision
+somebody already made and `bg-blue-500` is a guess about it. Three obligations
+follow, and the third is the one this skill used to get wrong:
+
+1. **Do not snap.** Replacing the artifact's value with the nearest configured
+   token is the deviation the rule's Iron Law forbids — *"NEVER SWAP … SPACING,
+   OR COLOUR"* without explicit confirmation. An artifact-derived exact value is
+   not a smell here: it *is* the spec, and the source-naming comment the
+   paragraph above asks for is what records it.
+2. **Translate once, not per call site.** Where the artifact's literal genuinely
+   needs to live in the project's system, add **one** named project token
+   carrying that exact value and use it everywhere — one token the project owns
+   beats N approximations of the same colour. That is a token duty, not a
+   deviation: the value does not change.
+3. **Reconcile as a proposal, never autonomously.** Report each value's
+   distance to the nearest project token on the `Reconciled:` line below, and
+   let the human decide. Writing a *different* project value because the
+   difference looks small is exactly the unconfirmed swap (1) rules out — the
+   mode table at `design-fidelity.md:117-121` grants no visibility exemption,
+   and `structural` grants only the filling of a spec that is genuinely
+   **silent**, which an artifact stating `#3B82F6` is not.
+
+**Why not "just approximate within tolerance", which is the eventual intent:**
+that needs a tolerance to exist. There is none — no `reconcile`, `tolerance`,
+`approximat` or `nearest` in the rule or its guideline — and both the threshold
+and whether approximation is autonomous by default are owner decisions, tracked
+as `blocker: approximation-tolerance` and `blocker: fidelity-default-flip` on
+`road-to-design-intent-conformance`. Until they land, a skill granting that
+autonomy would be re-writing the rule from underneath it.
+
+Structure, controls, icons, grid and breakpoints are never this skill's to
+adjust; those stay 1:1 with the artifact and belong to the rule, not to a
+utility-class decision.
+
 Token authoring (DTCG 3-layer model, CSS-var/Tailwind generation) lives
 in [`design-tokens`](../design-tokens/SKILL.md); its
 `tokens.ts validate --dir <path>` is the **single token-discipline
@@ -103,7 +139,11 @@ When reviewing or proposing styles, return:
 
 1. Token map — every colour, spacing, radius, shadow, font-size mapped
    to its configured token; arbitrary values flagged with the design
-   source they cite.
+   source they cite. Artifact-bound work adds a **Reconciled** block here:
+   one line per value, as `<artifact value> → <kept, or the token that
+   carries it exactly> (<distance to the nearest project token>)`. This is
+   the destination "report the distance" means; without it the obligation
+   has nowhere to land and is unobservable in the deliverable.
 2. Class list — ordered (layout → box-model → typography → colour →
    state → responsive); inline-style use justified per element.
 3. Extraction + risk call-out — component / constant / `@apply` / none
@@ -115,6 +155,7 @@ Concrete shape:
 ```
 Element:        <selector or component name>
 Token map:      <colour/spacing/etc → config token>
+Reconciled:     <artifact value → kept or exact-carrying token, + distance>
 Class list:     <ordered classes>
 Inline style:   <only if runtime-computed; else "none">
 Extraction:     <component | constant | @apply | none — reason>
@@ -128,7 +169,16 @@ Risks:          <arbitrary values, !important, dark-mode gaps>
 - `dark:` variants need a token map in both modes; one-sided dark
   styling is half a feature.
 - Arbitrary values (`mt-[17px]`) survive Tailwind upgrades but
-  break the design system; they accumulate silently.
+  break the design system; they accumulate silently. **Artifact-bound is the
+  exception, not a loophole:** a value the provided design specifies is not
+  accumulation, and step 1's three obligations decide it. An arbitrary value
+  nobody can trace to a source is still the smell this bullet is about.
+- **The carrier is CSS or a utility class; the value is the design's.** Static
+  presentation belongs in CSS / tokens / classes — `style=` is for what only
+  the runtime knows (a computed width, a live transform, a measured offset).
+  Porting an artifact's inline `style=` into classes is therefore expected and
+  is not a deviation, **as long as the resolved value comes out identical**.
+  Changing the carrier is free; changing the number is not.
 - `@apply` inside component CSS interacts with PurgeCSS — keep it
   in files Tailwind scans, not in vendor CSS.
 - **Anti-AI-slop catalog.** The bullets below are the Tailwind-specific

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "14.22.0"
+agent_config_version: "14.23.0"
 
 # --- Project identity ---
 project:

package/dist/cli/registry.js

@@ -73,7 +73,7 @@ export const REGISTRY = [
     { name: 'affected', disposition: 'delegate', synopsis: 'Artefacts related to <artefact> via the discovery relation-graph (BFS).' },
     { name: 'graph-explain', disposition: 'delegate', synopsis: 'Seed on a <concept>, expand 2 hops over the discovery relation-graph with a node budget.' },
     { name: 'benchmark', disposition: 'delegate', synopsis: 'Report context-token reduction vs the full always-loaded projection.' },
-    { name: 'code-graph', disposition: 'delegate', synopsis: 'Deterministic code-graph engine: build|detect|query|affected|path|explain|validate.' },
+    { name: 'code-graph', disposition: 'delegate', synopsis: 'Deterministic code-graph engine: build|detect|refresh|validate|query|affected|path|explain, plus the gate verbs impact|tests-for|untested|dead.' },
     { name: 'hooks:install', disposition: 'delegate', synopsis: 'Install the combined pre-commit hook.' },
     { name: 'hooks:status', disposition: 'delegate', synopsis: 'Print the runtime hook matrix (per-platform install + bindings).' },
     { name: 'hooks:doctor', disposition: 'delegate', synopsis: 'Diagnose hook health: concerns, posture, missing trampolines (read-only).' },