@event4u/agent-config 14.21.0 → 14.23.0

package/dist/agent-src/contexts/communication/rules-auto/token-efficiency-mechanics.md

@@ -155,3 +155,72 @@ could have shared. `probe_turnaround` reports the rate afterwards and refuses to
 gate on a store CI does not have. This paragraph is the whole mechanism, and the
 roadmap that added it pre-committed to recording a null if the rate does not
 move rather than repeating the reminder more loudly.
+
+## One command per Bash call — the detail
+
+Migrated from `token-efficiency` § One command per Bash call on 2026-09-08,
+because that rule's body is re-written on every subagent spawn while this file
+is loaded on demand. The Iron Law stays in the rule; everything below is
+lookup material.
+
+### Why chaining costs more, not less
+
+The host splits a compound command on `&&`, `||`, `;`, `|`, `|&`, `&` and
+newlines and requires **each segment to match the allowlist independently**.
+A single unmatched segment sends the whole call down the permission path even
+when every other segment was already allowed. So chaining does not save a
+round-trip — it converts N cheap authorizations into one expensive one.
+
+### The measurement
+
+Over 40,268 real Bash calls from one maintainer's transcripts:
+
+- **97.7 %** carry a shell metacharacter. The package's own category-A
+  classifier (`permission_gate` + `category_a.ts`) is therefore reachable on
+  **2.3 %** of real calls; the host allowlist decides the rest.
+- **17.9 %** have a head token matching no allowlist pattern. Distribution:
+  a leading `VAR=…` assignment 5,215×, `./scripts-run` 520×, `python3` 518×,
+  shell loop keywords 460×, `sleep` 155×, `mkdir` 71×, `cp` 49×.
+- Of those 5,215 assignments, **5,037 are genuinely standalone** (`F=/path; …`)
+  and only 178 are env prefixes (`VAR=v cmd`). The distinction was checked
+  rather than assumed, because a review had claimed the whole class was a
+  measurement artifact. It is not: that shape cannot be written as an
+  allowlist pattern at all, so it shrinks only by not being written.
+
+### The substitutions
+
+| Instead of | Write |
+|---|---|
+| `D=/repo; cd $D && git status` | `git -C /repo status` |
+| `V=$(git rev-parse HEAD); echo $V` | two calls, the second using the printed value |
+| `mkdir -p x && cp a x/` | two calls in the same block |
+| `cd sub && <cmd>` | the directory flag the tool already has (`-C`, `--cwd`, `--prefix`) |
+
+A loop that genuinely cannot be expressed without the shell stays a loop —
+prefer a script file over an inline `for` when it recurs.
+
+### What the carrier does and does not do
+
+`chain-nudge` (`src/scripts/hooks/chain_nudge_hook.ts`) is a `pre_tool_use`
+concern bound on the three hook-capable platforms. It reads
+`tool_input.command`, strips quoted spans and heredoc bodies so an operator
+inside a string literal cannot be misread, and injects one advisory line the
+first time a session chains work. It is ON by default with
+`hooks.chain_nudge.enabled: false` as the opt-out — inverting
+`code-graph-nudge`, which gates on a project capability that may be absent,
+because the fact this one carries is a property of the host's permission
+matcher and holds in every consumer.
+
+**It never blocks, and it fires once.** So it changes what the agent knows,
+not what the agent may do: compliance stays model-carried, and the concern's
+tests establish detector behavior, not adherence. On a host with no
+`pre_tool_use` slot nothing fires at all and the rule is model-carried end to
+end — `agent-config hooks:status` reports which slots are bound where you are.
+
+### The sentence this replaced
+
+Until 2026-09-08 the batching paragraph in the rule ended "NOT write shorter
+commands: the long commands are already the batching." That was written about
+token cost, where it holds, and it is wrong about the permission layer below —
+a batch is N tool calls in ONE block, never N shell commands in ONE call. The
+old wording collapsed the two and so encouraged the most expensive shape.

package/dist/agent-src/contexts/execution/auto-dispatch-classification.md

@@ -232,11 +232,11 @@ NEVER A SILENTLY DEGRADED ANSWER. NO LLM CLASSIFIER FALLBACK (CUT C3).
 **Why rg-first** (council 2026-07-28, 2 rounds): the pre-registered benchmark
 behind the `code-graph-retrieval-null` claim (`docs/CLAIMS.md`) measured
 native-graph recall 0.365 vs grep 0.797 on graph-shaped questions — an
-indexing gap that keeps `code_graph.enabled` false BY DEFAULT — not
-permanently: the 2026-08-15 withdrawal retracted that, and the figures predate
-the 2026-08-22 extractor repair. The accelerant clause above is that bound's
-escape hatch; `classifyLookup` reads the flag, so turning it on is the whole
-change.
+indexing gap that kept `code_graph.enabled` false BY DEFAULT until that flag
+was retired (2026-09-07) — not permanently: the 2026-08-15 withdrawal retracted
+that, and the figures predate the 2026-08-22 extractor repair. The accelerant
+clause above is that bound's escape hatch, reached only when a caller passes a
+usable graph, which no production caller yet does.
 
 **Escalation, not degradation:** a primitive that returns nothing (index miss,
 pattern too ambiguous, report script absent) — **or an unusable result**

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/external-code-graph-interop.md

@@ -25,11 +25,10 @@ obligation_frequency: "per-turn"
 
 Some repos commit a pre-built code-intelligence index — a `graph.json`-shaped
 artifact or a SCIP index (`index.scip`, `*.scip`). One that exists is already
-built and structured, so it is the cheap first question for "who calls X",
-"where is Y used", "what does this import". This suite is an **orchestrator
-first, owner where it wins** (ADR-124): query a consumer-shipped index when it
-is present and fresh; where none is shipped, the native engine (default-off,
-benchmark-gated) covers the gap.
+built, so it is the cheap first question for "who calls X", "where is Y used",
+"what does this import". This suite is an **orchestrator first, owner where it
+wins** (ADR-124): query a shipped index when present and fresh; otherwise the
+native engine covers the gap (shipped since ADR-259 — no manual install).
 
 ## The rule
 
@@ -41,6 +40,17 @@ NO FRESH INDEX SHIPPED → THE NATIVE ENGINE MAY BUILD ONE (ADR-124); STILL
 GREP-FALLBACK FOR WHAT THE GRAPH DOES NOT ANSWER, AND SAY WHICH SOURCE ANSWERED.
 ```
 
+## Staleness is part of the answer
+
+```
+AN ANSWER FROM AN INDEX N COMMITS BEHIND IS WORTH LESS THAN THE SAME ANSWER
+FROM A FRESH ONE. NEVER REPORT A GRAPH ANSWER WITHOUT KNOWING WHICH IT WAS.
+```
+
+`behind:N` → refresh first, or grep and say so. Silence is not freshness.
+Delivery per host: [`code-intelligence`](../skills/code-intelligence/SKILL.md)
+§ Staleness delivery.
+
 ## When it fires
 
 A codebase-structure question (call graph, references, usages, import graph)
@@ -58,9 +68,8 @@ AND the repo contains a detectable index:
 3. **Fall back to `grep`/read** only for what the index does not cover, and say
    so ("the index has no entry for X, so I grepped").
 
-Query-first is an **ordering** heuristic, never a claim the index answers better:
-measured 2026-08-28, zero of four graph-shaped classes beat `grep`, so no class
-is graph-first. Routing changes; permission does not. Figures:
+Query-first is an **ordering** heuristic, never a claim the index answers better
+— no measured class beat `grep`. Figures:
 [`code-intelligence`](../skills/code-intelligence/SKILL.md) § Measured.
 
 ## When NOT to fire
@@ -71,11 +80,7 @@ is graph-first. Routing changes; permission does not. Figures:
 ## See also
 
 - [`code-intelligence`](../skills/code-intelligence/SKILL.md) — the executable
-  routing skill (`agent-config code-graph detect|query|affected|path`), the
-  measured per-class figures, and the hook-vs-instruction-file surface question
-  (`agent-config hooks:status`, never a guess from the host name).
-- [`discovery_graph`](../scripts/discovery_graph.ts) — this suite's OWN artefact
-  relation-graph (`affected`/`explain`); the external code-graph is the
-  *source-code* analogue this rule defers to for code questions.
+  routing skill, the measured figures, staleness delivery per host, and the
+  pointer to this suite's OWN artifact relation-graph (`discovery_graph`).
 - [`think-before-action`](think-before-action.md) — analyze with the best
   available tool before grepping blind.

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/rules/token-efficiency.md

@@ -37,9 +37,32 @@ A CALL THAT DOES NOT READ THE PREVIOUS RESULT IS NOT A SECOND TURN.
 
 The ceiling above forbids repetition; this forbids splitting work that had no
 reason to be split — measured mean batch size **1.01**, i.e. fully serial. The
-discriminator is the dependency, never the count. NOT "write shorter commands":
-the long commands are already the batching. `instruction-only` — nothing can
-observe a call that was not batched. Evidence + the absent-cause finding:
+discriminator is the dependency, never the count. `instruction-only` — nothing
+can observe a call that was not batched. Evidence + the absent-cause finding:
+[`token-efficiency-mechanics`](../contexts/communication/rules-auto/token-efficiency-mechanics.md).
+
+## One command per Bash call
+
+```
+ONE COMMAND PER BASH CALL. NEVER CHAIN WORK STEPS WITH `;`, `&&` OR `||`,
+AND NEVER CARRY STATE FORWARD IN A LEADING `VAR=…` ASSIGNMENT.
+N COMMANDS GO IN N CALLS IN ONE BLOCK — THAT IS WHAT A BATCH IS.
+A CHAINED CALL IS AUTHORIZED ONLY AS STRONGLY AS ITS WEAKEST SEGMENT.
+```
+
+A permission rule, not a token one — which is why it is not folded into the
+section above. The host splits a compound command on the shell operators and
+requires **each segment to match the allowlist independently**, so one
+unmatched segment sends the whole call down the permission path even when
+every other segment was already allowed. Chaining converts N cheap
+authorizations into one expensive one. `D=/repo; cd $D && git status` is
+`git -C /repo status`.
+
+**Not forbidden:** a pipe of ordinary filters, a redirect, a heredoc — one
+command with a filter or with input, not two work steps. Carried at tool-call
+time by the `chain-nudge` `pre_tool_use` concern, which is advisory and never
+blocks, so compliance stays model-carried. Measured numbers, the substitution
+table and the carrier's limits:
 [`token-efficiency-mechanics`](../contexts/communication/rules-auto/token-efficiency-mechanics.md).
 
 ## Enumerated file sets are ONE operation, not N repetitions

package/dist/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/dist/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/dist/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/dist/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 */

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

@@ -42,7 +42,9 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+
+import { isCliEntry } from './_cli_entry.js';
 
 const STUB_DIR = path.join('agents', 'roadmaps', 'stubs');
 
@@ -459,24 +461,8 @@ export function main(argv: readonly string[] = process.argv.slice(2)): 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;
-    }
-    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, 'stubs_due')) {
     process.exitCode = main();
 }