@event4u/agent-config 14.21.0 → 14.23.0

package/docs/contracts/settings-classes.md

@@ -247,8 +247,33 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 26 |
 | B — consent | 3 |
-| C — guarded | 110 |
-| **Total** | **139** |
+| C — guarded | 113 |
+| **Total** | **142** |
+
+It rose to 142 on 2026-09-08 from two independent additions that landed in the same
+day and are counted together here: `lean_projection.hosts` (one C, `policy`, from
+`road-to-delivery-for-every-host`) and the two continuity keys below. The merge that
+combined them re-derived the total from the class table rather than adding either
+side's figure to the other, which is the arithmetic `lint_settings_classes` checks.
+
+It rose on 2026-09-08 when `road-to-continuity-writer-activation`
+step 1.2 added `continuity.auto_record` — one C, `consent`: it arms an automatic
+producer on the normal session-end path, and the roadmap step requires the
+default to stay `off` until parity is measured, which is a decision no agent may
+take by writing the key. Step 1.4 added
+`continuity.run_checkpoints` the same day — a second C, shipping `on` because
+that is the behavior the tree already had. It exists so the three session-end
+handlers are independently disableable, which is what the 2026-09-07 council's
+D2 asked for; it changes nothing that ships.
+
+Its disposition is `consent`, and `derivable` was considered first and rejected:
+`derivable` is the **deletion queue**, a claim that the key disappears once the
+mechanism it names exists. This one is an operator kill switch over a recovery
+artifact, so it is meant to survive — and nothing in the tree can derive whether
+an operator wants resumability traded for quiet. It sits in the same shape as the
+kill switches already classified `consent` (`knowledge.global_sharing.enabled`
+and its allowlist): the mechanism's own preconditions are computable, the
+operator's decision to suppress it is not.
 
 The total was 140 until 2026-08-12, when five of the six keys no code path read were
 deleted, minus the one held open (§ The six unread keys, below): one A
@@ -338,9 +363,9 @@ the template, which is the drift this contract exists to prevent.
 |---|---|
 | derivable | 83 |
 | un-inferrable | 9 |
-| consent | 41 |
-| policy | 6 |
-| **Total** | **139** |
+| consent | 43 |
+| policy | 7 |
+| **Total** | **142** |
 
 First measured 2026-08-12 at 140 leaves (derivable 88 · consent 38 ·
 un-inferrable 9 · policy 5), from the table below rather than predicted — the
@@ -355,8 +380,12 @@ mechanism it names actually exists, so 83 measures work outstanding, not keys
 about to disappear. The count is expected to fall while `un-inferrable` does not
 — those 9 plus whatever survives re-examination in `consent` are the floor this
 surface has, and stating it is the point. `policy` is the smallest class and the
-only one whose action is a *move* rather than a keep or a delete: five keys carry
-a project fact the tree could hold instead.
+only one whose action is a *move* rather than a keep or a delete: seven keys carry
+a project fact the tree could hold instead. (This sentence read "five" while the
+counts table beside it read 6, and 2026-09-08 added `lean_projection.hosts` as the
+seventh — corrected in both directions rather than only incremented, because a
+prose number that disagrees with a computed one beside it is the exact defect
+`lint_settings_classes` fails the two Total rows for.)
 
 ## The floor — the nine keys no mechanism can derive
 
@@ -440,6 +469,7 @@ Rows follow template order, so a diff against the template reads straight down.
 | `discipline_profile` | C | `__DISCIPLINE_PROFILE__` | master switch for the discipline rule tier | derivable — its own `auto` resolution against `src/config/host-capabilities.yml` |
 | `rule_loading_tier` | C | `__RULE_LOADING_TIER__` | legacy master switch for rule loading | derivable — `discipline_profile` supersedes it with a documented mapping (minimal→off, balanced→essential, full→full) |
 | `lean_projection.mode` | C | `eager-all` | `thin` removes rule bodies from the agent's context | derivable — `probe_host_compliance.ts` already computes the per-host thin/eager recommendation |
+| `lean_projection.hosts` | C | `[claude-code]` | decides WHICH hosts a thinning mode may thin, so an added id removes rule bodies from that host's context | policy — the value is a package-level decision the tree already holds: ADR-267 scopes the shipped `delivery` flip to `claude-code` alone. NOT `derivable`, and the distinction is the whole reason for this row: the mechanism that would compute an admissible host set, `admissibleUnderE3` in `src/scripts/_lib/injection_effect.ts`, admits **nothing** today — `src/config/host-injection-effect.json` carries 1 `observed-false` and 8 `unobserved` rows and no `observed-true` — so a derivation would yield `[]` rather than the shipped `[claude-code]`. Naming a mechanism that returns empty as the replacement would put a key in the deletion queue whose deletion would silently change the default. Move target: the ADR plus that census, once a host earns an `observed-true` row |
 | `telegraph.speak` | C | `false` | ships a rule body; a token-cost lever in both directions | derivable — the telegraph kill-criterion bench verdict is a package-level decision, not a per-install one |
 | `tokens.rich_skills` | C | `"on"` | token-spend lever | derivable — the skill's own `token_budget_class: rich` declaration plus the CI ceiling in `lint_token_budget_discipline.ts` |
 | `cost.budgets.daily` | C | `0` | rolling spend ceiling | consent |
@@ -537,6 +567,8 @@ Rows follow template order, so a diff against the template reads straight down.
 | `commands.create_pr.screenshots` | C | `false` | puts captured screenshots into a published PR body | consent |
 | `commands.create_pr.ui_paths` | C | `[]` | glob allowlist | derivable — the frontend-surface heuristic the PR-description flow already applies when the glob list is empty |
 | `commands.create_pr.api_paths` | C | `[]` | glob allowlist | derivable — the API-endpoint heuristic the same flow already applies as its documented empty-list fallback |
+| `continuity.auto_record` | C | `"off"` | arms an automatic producer on the normal session-end path | consent |
+| `continuity.run_checkpoints` | C | `"on"` | disabling it removes a recovery artifact a killed run resumes from | consent |
 | `memory.cadence` | C | `always` | suppressing the visibility line hides what the agent learned from the user | derivable — the hits/asks count the memory-visibility summary already computes; the line only exists when memory was consulted |
 | `memory.review_threshold` | A | `10` | when a review preview surfaces; governs no gate | derivable — the unreviewed-intake count `/memory load` already computes before rendering its preview |
 | `memory.redact_patterns` | C | `[]` | deny-list of secret and PII regexes | policy |
@@ -558,7 +590,7 @@ Rows follow template order, so a diff against the template reads straight down.
 | `hooks.runtime_journal.enabled` | C | `false` | configures code that runs on every dispatched hook event | consent |
 | `hooks.ui_route_nudge.enabled` | C | `false` | configures code that runs on every tool call | derivable — the UI-surface predicate plus the hook's own two-nudges-per-session cap |
 | `hooks.design_pass.enabled` | C | `false` | C-test 1 — it configures code that runs on every tool call and at every turn end, and unlike its two `hooks.*` neighbours its stop pass can BLOCK rather than warn | policy — whether an operator accepts a gate that can refuse a turn is a risk preference, not a fact the tree can compute. The two neighbours are `derivable` because they only ever warn; the block is the discriminator. `road-to-frontend-power` transfers the default flip to the owner for the same reason |
-| `hooks.code_graph.enabled` | C | `false` | configures code that runs on every tool call | derivable — the index-detection probe the nudge already runs; no index means silence |
+| `hooks.code_graph.enabled` | C | `false` | INERT since 2026-09-07 — the nudge it gated was replaced by `code-graph-context`, which reads no flag. The KEY stays registered because `docs/MIGRATION.md` commits to exactly that ("the surfaces stay registered and disabled"): removing it is a breaking change for any consumer who set it, and the row was briefly marked REMOVED, which left the template's own leaf unclassified. Classified, not deleted. | derivable — the index-detection probe the replacement hook already runs; no index means silence |
 | `hooks.suggestion_capture.enabled` | C | `false` | configures code that runs at every turn end and every prompt | consent |
 | `decision_engine.surface_traces` | C | `false` | the decision engine’s own black box; the agent must not be able to close it | derivable — the engine's own active-gate state; there is nothing to surface when no gate fired |
 | `decision_engine.min_confidence` | C | `"off"` | the confidence gate | derivable — the confidence band the scoring engine already computes at the plan phase |

package/docs/guidelines/agent-infra/minimal-safe-diff-mechanics.md

@@ -166,3 +166,76 @@ reviewer has to untangle.
 
 - `minimal-safe-diff` (rule) — Iron Law, the rule, the pre-fix shared-path repair clause, own-orphan cleanup. The pre-diff checklist, the red-flag catalog and the when-in-doubt line live HERE since A1.
 - [`active-remediation-mechanics`](active-remediation-mechanics.md) — the fix-now / note+ask / follow-up-PR ladder detail.
+
+## Re-derive the requirement, don't inherit the shape
+
+```
+A REPAIR INHERITS THE SHAPE OF WHAT IT REPAIRS UNLESS YOU ASK OTHERWISE.
+STATE THE REQUIREMENT IN ONE LINE, THEN ASK WHETHER THE CURRENT FORM
+*CAN* EXPRESS IT. A FORM THAT CANNOT IS NOT A PARAMETER BUG.
+```
+
+Applies to a downstream repair — clearing a red, or fixing what your own diff
+broke — where the smallest change is a different VALUE and the form is
+unexamined.
+
+### Why this is a guideline section and not a rule clause
+
+It was drafted as a clause in `minimal-safe-diff` on 2026-09-07 and moved here
+the same day, on the gate's own evidence rather than on preference.
+`check_preamble_payload_budget` measured the clause at +460 delivered tokens,
+then +271, then +180 after two rounds of cutting — a floor set by the Iron-Law
+block itself. That payload is re-written on EVERY subagent spawn, and the rule it
+would have lived in is `type: auto`: it fires on prompt keywords, not on tool
+output, so a red test nobody mentioned never loads it.
+
+Certain per-spawn cost against an activation path that misses the case the clause
+was written for is a bad trade, and the deterministic half does not depend on it
+— see § Honest limit below. The rule already routes here
+(`routes_to: guideline:agent-infra/minimal-safe-diff-mechanics`), which is the
+same reachability every other migrated body in this repository has.
+
+### Worked failure — 2026-09-07
+
+A change emptied `<repo>/.claude/skills` of skills and left ~49 flat-command
+wrappers behind. `resolveSkillsRoot` tried two workspace-relative roots and took
+the first non-empty one, so it resolved the wrappers, and the skill ranker ranked
+49 command wrappers instead of 299 skills.
+
+The repair chosen was to swap the ORDER of the two roots. The requirement was
+*"rank every catalogue the session can reach"*, which **no ordering of a
+first-hit loop can satisfy** — and the host-global root the whole task was about
+appeared in neither position. The evidence had been measured an hour earlier and
+sat in the same session's own notes: `~/.claude/skills` 307, `.claude/skills` 49,
+`src/skills` 299.
+
+Two things made it easy to miss, and both are the shape of the trap rather than
+this instance of it:
+
+- **The docstring framed the question.** It read *"First existing catalogue root
+  … `.claude/skills` before `src/skills` because a CONSUMER install carries the
+  former"* — i.e. it asked *which root wins*, and that question was answered. A
+  docstring records what the code decided; it never records whether that was the
+  decision to make.
+- **The same docstring contained the premise of the correct answer.** If
+  consumers carry their own skills *and* the package ships skills, both must be
+  read. The sentence was read, used to justify an ordering, and its consequence
+  was not drawn.
+
+### Why the pre-work rules do not cover it
+
+[`improve-before-implement`](../../../src/rules/improve-before-implement.md) does
+not activate for bug fixes ("the problem is already defined") and
+[`invite-challenge`](../../../src/rules/invite-challenge.md) excludes "evidenced
+bug fixes". Both exclusions are right for the case they were written for and
+wrong for a downstream repair, which presents as a defined problem while its
+definition came from the broken code.
+
+### Honest limit
+
+The rule is `type: auto`, so it fires on prompt keywords and not on tool output:
+a red test nobody prompted about does not load it. The clause is the
+model-carried half. The deterministic half is a comparison of the two lists that
+diverged — `tests/contracts/catalogue_layer_parity.test.ts`, which reds when a
+directory the delivery side treats as an artifact source is not a root the reader
+reads, and which was measured to catch this exact defect on the pre-change tree.

package/docs/guidelines/agent-infra/notes-horizon-mechanics.md

@@ -0,0 +1,90 @@
+# Notes-first reasoning — horizon and reopening mechanics
+
+Migrated out of [`notes-first-reasoning`](../../../src/rules/notes-first-reasoning.md)
+on 2026-09-08. That rule is delivered on **every subagent spawn**, so its body is
+paid per spawn; this material is reference read on demand. Nothing was dropped —
+the four passages below are the rule's own text, verbatim, and the rule keeps
+both Iron Laws and points here.
+
+Same reason, and the same remedy, as the 2026-08-29 drain run recorded for
+`source-confidentiality`: the addition had no room under the per-spawn ceiling,
+and raising that ceiling is the config-weakening move this repository refuses.
+
+### Why reasoning stays out of the reply, and what grounds the notes file
+
+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.
+
+The notes file is grounded in the documented cross-run lessons memory
+(consolidated via [`memory-consolidation`](../../../src/skills/memory-consolidation/SKILL.md));
+the rule's in-task sections are a local derivation for within-task scope. The
+gate itself reads settings + task-signal + host self-assessment.
+
+### The two section fields, in full
+
+The rule lists the sections and no count. That is deliberate: the structure
+carries the enumeration, so there is no "write N hypotheses" instruction to
+follow — a run records what the work actually surfaced, and an empty section is
+a fact about the work rather than a gap in the notes.
+
+`## Predictions` carries **chosen form** · prediction · confidence · result ·
+lesson — the calibration loop: hypothesis → prediction → reality →
+calibration. The form is named first because a prediction with no subject
+cannot be contradicted: when the observation comes back, "the prediction
+missed" has to point at *what* it was a prediction about, or nothing reopens.
+
+`## Decisions` escalates to
+[`decision-record`](../../../src/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? And `next-commitment` is the boundary
+this choice authorises work up to, not the plan for it: choosing a form is not
+permission to execute a twelve-step plan on it without re-reading the position.
+
+### The horizon — which boundaries count
+
+The boundary is the nearest of these that the plan actually reaches: a **test
+result** · a **type or schema inspection** · a **compile** · a **runtime probe**
+· a **call-site inventory** · a **dry run** · a **browser observation** · a
+**dependency-contract read**. The set is enumerable, which is the whole point —
+"the work up to the nearest of those" is decidable from the plan, and `next
+justified commitment` as prose degrades to *"implement solution"*, which is the
+starting point wearing a label.
+
+### Width scales with reversibility, never with task size
+
+| The action is… | The horizon runs to… |
+|---|---|
+| a reversible local edit | a whole implementation slice — stopping at the first boundary costs more than it saves |
+| stateful or cross-layer | the next boundary from the list above |
+| irreversible or a public contract | **before** the irreversible step, unless direct evidence already covers it |
+
+### The look-ahead ladder is a CEILING, never a quota
+
+Three to five moves is the *maximum*, and only for a forcing, irreversible or
+externally observable line. Stateful or cross-layer gets two to three. A quiet
+reversible line gets **one, deliberately** — and no artifact anywhere requires a
+minimum depth. Always-three-to-five across all variants is 1024 leaves at four
+branches and depth five, which buys nothing and costs the run its budget.
+
+### Reopening — the two consequences
+
+A reopen driven by ritual rather than by contradicting evidence is ceremony, and
+an uncapped reopen is a loop with better manners. Two consequences:
+
+- **A rejection whose premise is falsified is not a rejection.** A candidate
+  killed by an assumption that later turns out false is *un-evaluated*, not
+  dead — it returns to the set. That is what makes a stated `killed-if`
+  condition worth carrying: without it, "we ruled that out" is unfalsifiable.
+- **The first failure reads the candidate list before the retry**, where one
+  exists — see [`autonomy-mechanics`](../../../src/agent-src/contexts/execution/autonomy-mechanics.md)
+  § Retry-budget escalation ladder. Where none exists the ladder is unchanged.
+  This adds a branch; it does not move the N=3 budget.
+
+## See also
+
+- [`notes-first-reasoning`](../../../src/rules/notes-first-reasoning.md) — the
+  rule this material was paid for in, and which keeps both Iron Laws.
+- [`rdp-gate`](../../../src/agent-src/contexts/execution/rdp-gate.md) — the
+  engagement gate that decides whether the notes discipline runs at all.
+- [`decision-record`](../../../src/skills/decision-record/SKILL.md) — where a
+  cross-task or architectural decision escalates to.

package/llms.txt

@@ -41,7 +41,7 @@ canvas-design: Creating static visual art — posters, marketing visuals, brand
 character-consistency: Use when a character must stay visually identical across AI video scenes — locks identity tokens (silhouette, palette, wardrobe, prop) in JSON. Triggers 'character lock', 'same character'.
 check-refs: Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions.
 churn-prevention: Use when designing churn defence — health-score signals, churn-cause split (involuntary / value / relationship / fit), early-warning loop. Triggers on 'why are accounts leaving'.
-code-intelligence: 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'.
+code-intelligence: 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'.
 code-refactoring: When the user says 'refactor this', 'rename class', or 'move method'. Safely refactors code in any language — finds all callers, updates downstream dependencies, verifies via quality tools.
 code-review: Use when the user says \"review this\", \"check my code\", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards.
 command-routing: Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "14.21.0",
+    "version": "14.23.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including the counts in these badges.",
     "license": "MIT",
     "private": false,
@@ -48,6 +48,7 @@
         "src/agent-src/scripts/",
         "src/agent-src/templates/scripts/",
         "src/templates/",
+        "src/vendor/grammars/",
         "tests/fixtures/hooks/",
         "AGENTS.md",
         "CHANGELOG.md",
@@ -80,13 +81,15 @@
         "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "build:mcp-bundle": "esbuild src/scripts/mcp_server/__main__.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/mcp/server.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_MCP_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "build:cli-delegate": "esbuild src/scripts/_cli/cmd_*.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --define:__AGENT_CONFIG_CLI_DELEGATE__=true --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
+        "build:agent-src-delegate": "esbuild src/agent-src/scripts/*.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --define:__AGENT_CONFIG_CLI_DELEGATE__=true --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
+        "build:delegate-aux": "esbuild src/scripts/_lib/pin_resolver.ts src/scripts/check_update_banner.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --define:__AGENT_CONFIG_CLI_DELEGATE__=true --outbase=src/scripts --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
         "build:ui": "vite build",
         "tokens:build": "node tokens/build-ac.mjs && node tokens/build-as.mjs",
         "tokens:check": "node tokens/build-ac.mjs --check && node tokens/build-as.mjs --check && node tokens/check-contrast.mjs",
         "build:discovery": "./scripts-run src/scripts/build_discovery_manifest --write --strict",
         "build:mcp-manifest": "./scripts-run src/scripts/build_mcp_registry_manifest --write --strict",
         "build:mcp-catalog": "./scripts-run src/scripts/build_mcp_catalog --write --strict",
-        "build": "npm run build:cli && npm run build:install-bundle && npm run build:hooks && npm run build:mcp-bundle && npm run build:cli-delegate && npm run build:ui",
+        "build": "npm run build:cli && npm run build:install-bundle && npm run build:hooks && npm run build:mcp-bundle && npm run build:cli-delegate && npm run build:agent-src-delegate && npm run build:delegate-aux && npm run build:ui",
         "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
         "lint:ts": "eslint --cache --max-warnings 0 'src/**/*.ts'",
         "test:ts": "vitest run",
@@ -116,8 +119,7 @@
         "tsx": "^4.23.1",
         "typescript": "^5.9.3",
         "vite": "^5.4.21",
-        "vitest": "^2.1.9",
-        "web-tree-sitter": "0.24.7"
+        "vitest": "^2.1.9"
     },
     "dependencies": {
         "@fastify/static": "^10.1.2",
@@ -129,6 +131,7 @@
         "js-yaml": "^5.2.0",
         "open": "^11.0.0",
         "preact": "^10.29.0",
+        "web-tree-sitter": "0.24.7",
         "yaml": "^2.9.0",
         "zod": "^3.25.0",
         "zod-to-json-schema": "^3.25.0"

package/src/agent-src/scripts/_cli_entry.ts

@@ -0,0 +1,51 @@
+/**
+ * "Was this module invoked as the command?" — one definition for the scripts
+ * under `agents/scripts` that both run directly and are imported by siblings.
+ *
+ * Five of them carried a byte-identical copy of this logic, and the copies were
+ * about to gain a sixth clause each. The interesting part is why the obvious
+ * one-liner is not enough:
+ *
+ *  - `--splitting` in `build:agent-src-delegate` can move a module body into a
+ *    shared chunk, where `import.meta.url` names the CHUNK. The URL comparison
+ *    then never matches and the command exits 0 having done nothing — measured
+ *    on `update_roadmap_progress` before this guard existed. Inside the bundle
+ *    the invoked file name is the reliable signal, so the delegate branch runs
+ *    first and a miss falls through rather than returning false.
+ *  - A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
+ *    macOS `/var` → `/private/var`) makes the raw URLs differ: `import.meta.url`
+ *    is the resolved real path while `argv[1]` keeps the symlink. Hence the
+ *    realpath comparison last.
+ *
+ * `moduleUrl` is the caller's own `import.meta.url` — it cannot be read from
+ * here, which is why it is a parameter rather than a lookup.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** Defined only by the esbuild delegate builds; `undefined` under tsx and node. */
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
+export function isCliEntry(moduleUrl: string, name: string): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    if (
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' &&
+        __AGENT_CONFIG_CLI_DELEGATE__ &&
+        path.basename(argv1, '.js') === name
+    ) {
+        return true;
+    }
+    const argvPath = path.resolve(argv1);
+    if (moduleUrl === pathToFileURL(argvPath).href) {
+        return true;
+    }
+    try {
+        return fs.realpathSync(fileURLToPath(moduleUrl)) === fs.realpathSync(argvPath);
+    } catch {
+        return false;
+    }
+}

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

@@ -56,11 +56,17 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+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';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 interface CompletedProcess {
@@ -263,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.
  *
@@ -545,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) — ` +
@@ -601,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.
@@ -638,6 +742,16 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
     if (dry_run) {
         return;
     }
+    // Inside `dist/cli-delegate/` the twin sits next to us as a precompiled
+    // bundle, and plain `node` runs it — the tsx walk below would otherwise
+    // reach `npx tsx`, which resolves against the CONSUMER's npm config and
+    // hard-fails on a mismatched `engines`/`devEngines` pin (the very class
+    // ADR-204 removed from the dispatcher and left standing here).
+    const bundledTwin = path.join(path.dirname(_HERE), 'update_roadmap_progress.js');
+    if (_isFile(bundledTwin)) {
+        spawnSync(process.execPath, [bundledTwin], { cwd: root, encoding: 'utf-8' });
+        return;
+    }
     const script = path.join(path.dirname(_HERE), 'update_roadmap_progress.ts');
     // Python: `_run([sys.executable, str(script)], root)`; the twin spawns the
     // dashboard generator twin through the same `tsx` runtime, cwd=root.
@@ -800,28 +914,7 @@ function main(argv?: readonly string[]): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
-    if (import.meta.url === argvUrl) {
-        return true;
-    }
-    // A symlinked invocation (e.g. via `.augment/scripts` → `dist/agent-src/scripts`,
-    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
-    // import.meta.url is the resolved real path while argv[1] keeps the symlink
-    // path. Compare realpaths so the entry guard still fires (without this the
-    // archival sweep silently no-ops when run through the symlink).
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
-if (_isCliEntry() || process.argv[1] === _HERE) {
+if (isCliEntry(import.meta.url, 'archive_completed_roadmaps')) {
     try {
         process.exitCode = main();
     } catch (exc) {

package/src/agent-src/scripts/roadmap_gates.ts

@@ -65,7 +65,7 @@
  */
 
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import * as fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 
@@ -80,6 +80,8 @@ import { execute } from './gate_execute.js';
 import { listPending } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation_store.js';
 import type { StagedAction } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation.js';
 
+import { isCliEntry } from './_cli_entry.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 /** Hard wrap for the rendered body — keeps output readable in a narrow pane. */
@@ -928,26 +930,8 @@ function main(argv?: readonly string[]): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvPath = path.resolve(process.argv[1]);
-    if (import.meta.url === pathToFileURL(argvPath).href) {
-        return true;
-    }
-    // A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
-    // macOS /var → /private/var) makes the raw URLs differ: import.meta.url is
-    // the resolved real path while argv[1] keeps the symlink. Compare realpaths
-    // so the entry guard still fires through the projection.
-    try {
-        return fs.realpathSync(_HERE) === fs.realpathSync(argvPath);
-    } catch {
-        return false;
-    }
-}
 
-if (_isCliEntry()) {
+if (isCliEntry(import.meta.url, 'roadmap_gates')) {
     process.exitCode = main();
 }
 

package/src/agent-src/scripts/roadmap_set_step.ts

@@ -30,7 +30,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+
+import { isCliEntry } from './_cli_entry.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -246,8 +248,9 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 }
 
+
 /* c8 ignore start */
-if (process.argv[1] !== undefined && pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href) {
+if (isCliEntry(import.meta.url, 'roadmap_set_step')) {
     process.exit(main());
 }
 /* c8 ignore stop */