@event4u/agent-config 12.0.0 → 13.0.0

package/docs/guidelines/design-handover-extraction.md

@@ -0,0 +1,87 @@
+# Design Handover — URL / live-page extraction
+
+> Where a URL handover gets extracted to, what consumes it, and in what order it is read back
+
+_Split out of [`design-fidelity-mechanics`](design-fidelity-mechanics.md) § URL / live-page handover, which carries the obligation surface and routes here. The split is the per-file depth ceiling doing its job: the mechanics file sat at 14.2k of its 16k budget, and compressing this material to fit would have cost the parts that make it actionable._
+
+```
+A HANDOVER THAT ARRIVES AS A URL IS STILL RUNG 2, NOT RUNG 4.
+EXTRACT THROUGH THE USER'S CONNECTED BROWSER TOOLS INTO FILES
+BEFORE ANY UI WRITE. A SCREENSHOT TAKEN DURING EXTRACTION
+CARRIES QA DUTY ONLY — IT IS NEVER THE THING YOU BUILD FROM.
+```
+
+When the artifact is handed over as a **URL** rather than a file — a published
+artifact link, a builder's share link, a staging or `localhost` page — rung 2 of
+the [data-basis ladder](design-fidelity-mechanics.md#data-basis-ladder) is
+reachable and rung 4 is not the fallback it looks like. Pull the DOM,
+stylesheets, scripts and assets through the browser tools the user has
+connected, and land them as files first.
+
+## Where the extraction lands
+
+Into `design-system.json` under `.claude/design-system/` — the `path_prefix` the
+`design-fidelity` rule already routes on. That file is an **existing contract**,
+specified in
+[`design-system-json.md`](../../src/skills/design-system-capture/references/design-system-json.md);
+this guideline defines no format of its own. Raw source files land beside it,
+and screenshots taken while extracting land in a references directory next to
+them.
+
+## What consumes it
+
+[`/design-system:import`](../../src/domains/engineering-base/design-system/import/command.md)
+runs the extraction output through the three-lane adapter
+(`native` / `dtcg` / `dembrandt`) into the contract shape, then hands it to
+`design-system-capture`'s per-field import. The adapter is **offline** — it
+reads a file and writes the contract shape; it never fetches, crawls, or
+launches a browser.
+
+## The lock boundary — stated here because this is where an agent would cross it
+
+The package ships the contract, the adapter, and the instructions. It does
+**not** ship the crawler, the Playwright runtime, or a font-bundler. Extraction
+runs through the user's own connected tooling, and its output is *observed, not
+authoritative*: every field is confirmed by the human, and a value conflicting
+with a registered brand token is flagged rather than applied
+(`brand-source-of-truth`).
+
+## Retrieval order — so the source survives the session
+
+Check in this order and stop at the first hit. The point is that the next
+session reads a file instead of re-screenshotting the same page.
+
+| # | Source | Why it ranks here |
+|---|---|---|
+| 1 | The project's own `design-system.json` | Already confirmed by a human in an earlier session — the only rung whose values someone signed off on |
+| 2 | A previous extraction artifact under `.claude/design-system/` | Observed and file-backed; re-reading it costs nothing and re-extracting may drift |
+| 3 | The live page | Authoritative for *today's* page, but only reachable while it is up and the tooling is connected |
+
+**Persistence is not restated here.** Skip-if-exists unless explicitly forced,
+and never silently discarding a prior confirmed decision, are owned by
+[`/design-system:generate`](../../src/domains/engineering-base/design-system/generate/command.md)
+— *"never overwrite a confirmed `DESIGN.md`"*, *"Never persist silently."* This
+guideline states the order; that command states what happens on a collision, and
+stating it twice is how the two drift apart.
+
+## The producer sentence
+
+The documented easy path is a connected extractor MCP, attached once and reused.
+Where none is available, the manual Chrome-DevTools-MCP channel is the fallback,
+and where neither is reachable the handover degrades to rung 3 or 4 — which the
+ladder requires you to **name**, not to pass off as a source-based build.
+
+## Coverage — stated honestly
+
+No fixture scores this class yet. `daf-source-over-screenshot` scores the rung
+choice on an *attached* artifact, not a URL handover, and it is itself recorded
+as SKIPPED on 2026-08-13 for want of a page-reaching capture primitive. Closing
+the gap needs a fixture whose host actually has one; claiming a regression
+witness before then would be the fabrication this package's evidence discipline
+exists to prevent.
+
+## See also
+
+- [`design-fidelity-mechanics`](design-fidelity-mechanics.md) — the data-basis ladder this operationalises, and the adopt-the-code duty that governs what you do with the extracted source.
+- [`design-fidelity`](../../src/rules/design-fidelity.md) — the rule; a provided artifact is the spec.
+- [`design-system-capture`](../../src/skills/design-system-capture/SKILL.md) — the per-field import the adapter hands off to.

package/docs/guidelines/prompt-templates.md

@@ -138,9 +138,32 @@ Given an existing good output, reconstruct the prompt that would
 produce it. Used to mine prompts from public LLM artifacts. Not a
 shaping template — a forensic one.
 
+## Viral-prompt anti-patterns — what this catalogue deliberately omits
+
+Prompt collections that circulate socially optimise for looking impressive
+on the way in, not for what the target model can act on. None of the
+templates above encodes the three patterns below, and that is a decision
+rather than an oversight — a template is a slot structure, and these three
+are slots the model cannot fill honestly.
+
+| Anti-pattern | Why no template carries it |
+|---|---|
+| **Grandiose persona** — "world's foremost", "legendary", "10× expert" | Every template's role slot takes a *capability* (`RTF` Role, `CRISPE` Capacity, `CO-STAR` Style). A superlative is not a capability: it spends tokens and changes nothing the model does. |
+| **Presupposed canon** — "the 7 laws of X", "the standard X framework", for a body of knowledge that may not exist | A presupposition in the context slot is answered by confabulation, and the invented canon inherits the authority of the frame. `Few-Shot` exists precisely so that a real pattern is *shown* rather than asserted. |
+| **Scope stuffing** — analysis *and* strategy *and* copy *and* a checklist in one prompt | Each template has one Expectation / Objective / Format slot by construction. Four deliverables in one prompt produce four shallow ones; split them, or name the primary. |
+
+The catalogue's own position: a template earns its place by making a
+request *checkable*, not by making it sound authoritative. Where a rough
+prompt carries one of these three, the
+[`prompt-optimizer`](../../.agent-src.uncondensed/skills/prompt-optimizer/SKILL.md)
+strips it in its de-inflation sub-step before any template is picked —
+and strips nothing else, because everything outside these three is a
+requirement the author meant. This section is own analysis; it records a
+decision about this catalogue rather than adopting an outside claim.
+
 ## Rejection note
 
-Upstream `nidhinjs/prompt-master` claims that only five techniques
+An external prompt-collection claims that only five techniques
 are "safe" for production prompting:
 
 - few-shot

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "12.0.0",
+    "version": "13.0.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

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

@@ -403,6 +403,38 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
     }
 }
 
+/**
+ * Rebuild the archive index after a move, when the builder is present.
+ *
+ * The sweep is the one operation that changes what `agents/roadmaps/archive/`
+ * contains, so it is the one operation that can leave the generated index
+ * stale — and the drift gate on that index runs in the same PR the sweep runs
+ * in. Regenerating here keeps the two from disagreeing by construction rather
+ * than by remembering.
+ *
+ * `build_archive_index` is package-internal (`src/scripts/`), while this sweep
+ * is projected into consumer installs that carry no such script. Absent
+ * builder → nothing to regenerate, and that is a normal consumer state, not a
+ * failure. The spawn is best-effort for the same reason `_regen_dashboard` is:
+ * a sweep that archived correctly must not report failure because a
+ * regeneration could not run.
+ */
+function _regen_archive_index(root: string, dry_run: boolean): void {
+    if (dry_run) {
+        return;
+    }
+    const script = path.join(root, 'src', 'scripts', 'build_archive_index.ts');
+    if (!_isFile(script)) {
+        return;
+    }
+    _runTwin(root, script);
+    for (const rel of ['agents/roadmaps/archive/INDEX.md', 'agents/roadmaps/archive/index.json']) {
+        if (_isFile(path.join(root, rel))) {
+            _run(['git', 'add', '--', rel], root);
+        }
+    }
+}
+
 /** Spawn the dashboard generator twin (tsx) with cwd=root, mirroring `[sys.executable, script]`. */
 function _runTwin(root: string, script: string): void {
     // Python uses `sys.executable` — the interpreter already running this
@@ -491,6 +523,7 @@ function main(argv?: readonly string[]): number {
         return 0;
     }
     _regen_dashboard(root, ns.dry_run);
+    _regen_archive_index(root, ns.dry_run);
     const verb = ns.dry_run ? 'Would archive' : 'Archived';
     for (const rec of archived) {
         process.stdout.write(

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

@@ -126,10 +126,10 @@ function wrap(text: string, width: number, indent: string): string[] {
 
 /**
  * Column width for the label gutter — sized to the longest label in use
- * (`Blocked until:`, 14 chars) plus one separating space, so no value ever
+ * (`If you do nothing:`, 18 chars) plus one separating space, so no value ever
  * runs flush against its own label.
  */
-const LABEL_W = 15;
+const LABEL_W = 19;
 
 /** A labelled block: `  Label:  value`, wrapped and hanging-indented. */
 function field(label: string, value: string): string[] {
@@ -183,6 +183,23 @@ function renderEntry(e: Entry, index: number): string[] {
         ...field('Blocks:', e.blocker.blocks),
     ];
 
+    // What is actually being decided, when the entry says so.
+    if (e.blocker.question) {
+        out.push(...field('The question:', e.blocker.question));
+    }
+
+    // The recommendation leads, because it is the answer — everything below it
+    // is how to carry the answer out. An entry that predates the field says so
+    // rather than rendering a silent gap: the reader needs to know the analysis
+    // is missing, not merely that a line is absent.
+    out.push(
+        ...field(
+            'Recommendation:',
+            e.blocker.recommendation ||
+                '(none recorded — this entry predates the field; ask for one before deciding)',
+        ),
+    );
+
     const doLabel = isLegacy(e.blocker) ? 'Blocked until:' : 'Do this:';
     const steps = regroupTodo(e.blocker.todo);
     if (steps.length === 0) {
@@ -203,6 +220,9 @@ function renderEntry(e: Entry, index: number): string[] {
             out.push(...lines.map((l, i) => (i === 0 ? indent + l : l)));
         }
     }
+    if (e.blocker.ifNothing) {
+        out.push(...field('If you do nothing:', e.blocker.ifNothing));
+    }
     out.push(...field('Done when:', e.blocker.resolvedWhen));
     return out;
 }
@@ -238,6 +258,14 @@ function render(entries: readonly Entry[], all: boolean): string {
     }
     if (shown.length > 0) {
         lines.push('');
+        // Deciding is not the same as executing, and a list that only decides
+        // leaves the second half with the person who has the least context.
+        // Naming the guided path here is the cheapest place to close that gap:
+        // it is on screen at exactly the moment the reader is looking at a
+        // decision they did not write.
+        lines.push('Not sure about one of these? Ask your agent:');
+        lines.push('  "guide me through <id>"   — one decision, step by step');
+        lines.push('');
     }
     return lines.join('\n') + '\n';
 }

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

@@ -347,6 +347,24 @@ interface Blocker {
     blocks: string;
     todo: string[];
     resolvedWhen: string;
+    /**
+     * The two fields that make a blocker *decidable* rather than merely
+     * described. Empty string when the entry predates them — the ratchet in
+     * `lint_roadmap_blockers` keeps the backlog legal, so the renderer has to
+     * cope with absence rather than assume it away.
+     */
+    recommendation: string;
+    ifNothing: string;
+    /**
+     * Optional one-line statement of what is actually being decided.
+     *
+     * Not required, but recognised: three entries in the tree already used
+     * `- **Question:**` and, because the field list did not know it, the
+     * continuation logic silently appended it to `Blocks` — the decision's
+     * subject arrived glued to the end of an unrelated sentence. Naming it
+     * costs one enum entry and turns a silent swallow into a rendered field.
+     */
+    question: string;
 }
 
 // Strip fenced code blocks before blocker detection — a roadmap that shows the
@@ -362,7 +380,23 @@ function _stripFencedCode(text: string): string {
     return text.replace(FENCED_CODE_RE, (m) => '\n'.repeat(_splitlines(m).length));
 }
 
-const BLOCKER_FIELD_RE = /^-[ \t]*\*\*(Status|Owner|Blocks|Resolved when|What to do):\*\*/i;
+/**
+ * Terminator for a blocker field's continuation lines — ANY `- **Label:**`
+ * bullet, not a closed list of known labels.
+ *
+ * It used to enumerate eight names, which silently diverged from the contract
+ * the two call sites below already document ("up to the next `- **Field:**`
+ * marker"): a bullet whose label was not on the list did not terminate, so the
+ * PREVIOUS field kept absorbing it and the dashboard rendered the two as one
+ * run-on sentence. Measured when `- **Options:**` and `- **Side finding:**`
+ * first appeared in a blocker — a reader saw the side finding as part of
+ * `Resolved when`, i.e. the generator changed what a field meant.
+ *
+ * A closed list is the wrong shape for a terminator: every future field name
+ * would have to be added here to avoid corrupting the field above it, and the
+ * failure is silent in generated output nobody edits by hand.
+ */
+const BLOCKER_FIELD_RE = /^-[ \t]*\*\*[^*]+:\*\*/;
 
 /** Strip an inline `<!-- comment -->` and trim. */
 function _stripComment(s: string): string {
@@ -471,6 +505,9 @@ function parse_blockers(raw_text: string): Blocker[] {
                 blocks: _blockerField(body, 'Blocks') ?? '(unspecified)',
                 todo: _blockerTodo(body),
                 resolvedWhen: _blockerField(body, 'Resolved when') ?? '(unspecified)',
+                recommendation: _blockerField(body, 'Recommendation') ?? '',
+                ifNothing: _blockerField(body, 'If you do nothing') ?? '',
+                question: _blockerField(body, 'Question') ?? '',
             });
         }
     }
@@ -502,6 +539,9 @@ function parse_blockers(raw_text: string): Blocker[] {
             blocks: 'entire roadmap',
             todo: [parts.join(' ')],
             resolvedWhen: 'condition described above clears',
+            recommendation: '',
+            ifNothing: '',
+            question: '',
         });
     }
     return blockers;
@@ -869,6 +909,12 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
             lines.push('**Blockers**\n');
             for (const b of openBlockers) {
                 lines.push(`- **${b.id}** (owner: ${b.owner}) — blocks ${b.blocks}`);
+                if (b.recommendation) {
+                    lines.push(`  - **Recommendation:** ${b.recommendation}`);
+                }
+                if (b.ifNothing) {
+                    lines.push(`  - **If you do nothing:** ${b.ifNothing}`);
+                }
                 lines.push('  - **What to do:**');
                 for (const step of b.todo) {
                     lines.push(`    ${step}`);

package/src/config/evaluator-budgets.json

@@ -58,17 +58,18 @@
       "deterministic": false
     },
     "cli_help_command_count": {
-      "max": 97,
-      "last_measured": 97,
-      "last_measured_at": "2026-08-10",
+      "max": 98,
+      "last_measured": 98,
+      "last_measured_at": "2026-08-15",
       "method": "registry enumeration — count of `{ name: '...', disposition` entries in src/cli/registry.ts (NOT --help prose parsing; methods historically disagreed 74 vs 76 vs 79)",
-      "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82. 82 → 84 on 2026-08-04: the `route:explain` + `route:audit` verbs (routing-correctness validation surface) register in the same PR that adds the surface. Re-measured via the pinned method: 84. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86. 86 → 88 on 2026-08-07: the `sessions:list` + `sessions:claim` verbs (road-to-parallel-session-coordination — the shell surface of the shared session register, needed because /roadmap:next is command markdown and can only reach the register through a shell call) register in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 88. 88 → 89 on 2026-08-08: the `council:status` verb registers in the same PR that adds the surface, per this record's own contract. It exists because an agent in a consumer project announced \"kein Council konfiguriert (keine .agent-settings.yml)\" and substituted a weaker path while the council was configured user-globally the whole time — there was no verb that answered availability, so the only route was an inference from a filename, and the intuitive filename is the one location ADR-104 guarantees is never consulted. Re-measured via the pinned method: 89. 89 → 91 on 2026-08-08: the `self-repair:status` + `self-repair:release` verbs (the queued-defect reader and the single Hard-Floor-gated outward step of the self-repair loop — the loop is deliberately unable to publish unless a human runs the release command) register in the same PR that adds the surface, per this record's own contract. Landed alongside the +1 council:status move in the same branch. Re-measured via the pinned method: 91. 91 → 94 on 2026-08-08: the `packs:active`, `settings:get` and `mcp:available` verbs (road-to-capability-answerability Phase 2 — the three capability probes for the gaps that had none) register in the same PR that adds the surface, per this record's own contract. Each answers a question that was previously only inferable from a filename: which packs are active and from which file, what a setting resolves to and which file set it, and what is declared in mcp.json versus what can actually launch. 94 -> 95 in the same PR: `brand:status` (Phase 2.4 — brand-layer presence, which the rule depended on and no surface could answer). Re-measured twice via the pinned method on the unchanged tree: 95/95. 95 → 96 on 2026-08-10: the `session:recycle` verb (road-to-token-economy-recycling Phase 2.2 — the deterministic producer of the main-session recycle envelope; the recycle advisory names this exact verb, so it must exist as a shell surface) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 96. 96 -> 97 on 2026-08-10: the `gates` verb registers in the same PR that adds the surface, per this record's own contract. It exists because the blocker fields the dashboard already parses (Owner, What to do, Resolved when — CI-enforced by lint_roadmap_blockers) had no owner-filtered reader: the dashboard counts the open blockers across a 600-line file and links each to a per-roadmap anchor, so \"which of these are mine\" was a manual read of every anchor. The same inference-from-a-filename shape as the council:status entry above, one layer up. This branch and the session:recycle branch each measured 96 independently and landed on the same number for different verbs; the merge makes it 97, re-measured twice via the pinned method on the merged tree: 97/97."
+      "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82. 82 → 84 on 2026-08-04: the `route:explain` + `route:audit` verbs (routing-correctness validation surface) register in the same PR that adds the surface. Re-measured via the pinned method: 84. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86. 86 → 88 on 2026-08-07: the `sessions:list` + `sessions:claim` verbs (road-to-parallel-session-coordination — the shell surface of the shared session register, needed because /roadmap:next is command markdown and can only reach the register through a shell call) register in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 88. 88 → 89 on 2026-08-08: the `council:status` verb registers in the same PR that adds the surface, per this record's own contract. It exists because an agent in a consumer project announced \"kein Council konfiguriert (keine .agent-settings.yml)\" and substituted a weaker path while the council was configured user-globally the whole time — there was no verb that answered availability, so the only route was an inference from a filename, and the intuitive filename is the one location ADR-104 guarantees is never consulted. Re-measured via the pinned method: 89. 89 → 91 on 2026-08-08: the `self-repair:status` + `self-repair:release` verbs (the queued-defect reader and the single Hard-Floor-gated outward step of the self-repair loop — the loop is deliberately unable to publish unless a human runs the release command) register in the same PR that adds the surface, per this record's own contract. Landed alongside the +1 council:status move in the same branch. Re-measured via the pinned method: 91. 91 → 94 on 2026-08-08: the `packs:active`, `settings:get` and `mcp:available` verbs (road-to-capability-answerability Phase 2 — the three capability probes for the gaps that had none) register in the same PR that adds the surface, per this record's own contract. Each answers a question that was previously only inferable from a filename: which packs are active and from which file, what a setting resolves to and which file set it, and what is declared in mcp.json versus what can actually launch. 94 -> 95 in the same PR: `brand:status` (Phase 2.4 — brand-layer presence, which the rule depended on and no surface could answer). Re-measured twice via the pinned method on the unchanged tree: 95/95. 95 → 96 on 2026-08-10: the `session:recycle` verb (road-to-token-economy-recycling Phase 2.2 — the deterministic producer of the main-session recycle envelope; the recycle advisory names this exact verb, so it must exist as a shell surface) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 96. 96 -> 97 on 2026-08-10: the `gates` verb registers in the same PR that adds the surface, per this record's own contract. It exists because the blocker fields the dashboard already parses (Owner, What to do, Resolved when — CI-enforced by lint_roadmap_blockers) had no owner-filtered reader: the dashboard counts the open blockers across a 600-line file and links each to a per-roadmap anchor, so \"which of these are mine\" was a manual read of every anchor. The same inference-from-a-filename shape as the council:status entry above, one layer up. This branch and the session:recycle branch each measured 96 independently and landed on the same number for different verbs; the merge makes it 97, re-measured twice via the pinned method on the merged tree: 97/97. 97 -> 98 on 2026-08-15: the `workspace:doctor` verb (road-to-inbox-harvest-2026-08-c-workspace-identity Phase 3 — the read-only report over the new `workspaceIdentity()` resolver) registers in the same PR that adds the surface, per this record's own contract. It exists for the same inference-from-a-filename shape as the council:status and gates entries above, one layer down: the tree answered \"where am I\" in eight ad-hoc places across six files, and the 12.0.0 span shipped the same worktree misclassification twice, so no verb could be asked which checkout is the main one. Read-only by construction — the roadmap's Non-goals put worktree disposal out of scope and its Risk 3 names \"the pressure read becomes a disposal path by accident\" as the failure to design against, so the command carries no --fix and no --prune. Re-measured twice via the pinned method on the unchanged tree: 98/98."
     },
     "mcp_public_tool_count": {
-      "max": 19,
-      "last_measured": 19,
-      "last_measured_at": "2026-08-02",
-      "method": "tools/list length on the stdio server (post-ADR-132: implemented tools only)"
+      "max": 20,
+      "last_measured": 20,
+      "last_measured_at": "2026-08-17",
+      "method": "tools/list length on the stdio server (post-ADR-132: implemented tools only)",
+      "baseline_note": "19 → 20 on 2026-08-17 (release 13.0.0 gate). The +1 is 866bd9861 (feat(mcp): recover what the host dropped — real ranker tool + a route to it, road-to-inbox-harvest-2026-08-d-runtime-skill-routing Phase 4): `suggest_skill_for_task` was promoted from a discovery STUB to a real ALLOWLIST entry and removed from STUB_TOOLS. Worth stating precisely, because the consumer-visible NAME did not grow — the stub already published that name and its `task` + `limit` input schema, which the promotion carried over verbatim. What grew is the count of tools tools/list actually returns, which is exactly what this metric measures post-ADR-132: implemented tools only. Same shape as the cli_help_command_count history above — this RECORDS growth that already shipped through its own reviewed PR (866bd9861 is on main), it does not authorize new surface. The registering PR did not move this budget, so the gate did its job: the breach warned on main and blocked on the release ref, which is the conscious-decision point rather than a silently raised cap. Re-measured twice via the pinned method on a freshly built dist/mcp/server.mjs: 20/20. Headroom stays zero by design — the next tool that leaves STUB_TOOLS must move this number in its own PR."
     }
   }
 }

package/src/config/gate-coverage.yml

@@ -40,20 +40,24 @@
 #                visible, or it repeats the sin it exists to catch.
 #   canary       optional mutation recipe (Phase 7) — see CANARY below
 #
-# COVERAGE — THE HONEST DENOMINATOR (re-measured 2026-08-13)
+# COVERAGE — THE HONEST DENOMINATOR (re-measured 2026-08-16)
 # ----------------------------------------------------------
-# 257 `lint_*` / `check_*` / `audit_*` scripts live under `src/scripts/`
+# 260 `lint_*` / `check_*` / `audit_*` scripts live under `src/scripts/`
 # (the count is computed, not asserted — `check_gate_coverage.count_gate_scripts`).
-# **35 of them emit the machine-readable `scanned: <N>` line under their
-# CI-identical argv, and all 35 are listed below.** The manifest is therefore
+# **37 of them emit the machine-readable `scanned: <N>` line under their
+# CI-identical argv, and all 37 are listed below.** The manifest is therefore
 # complete with respect to its own contract, and covers ~14 % of the population.
-# (The 2026-08-05 reading said "32 … and all 31 are listed"; the 2026-08-10
-# reading said "33 … and all 33" while 34 entries were listed. Both halves are
-# RECOUNTED here: 257 is what `count_gate_scripts()` returns on the tree that
-# carries this change, and 35 is the entries counted directly. It read 255 while
-# this change was being written and 257 after `main` merged in two further gate
-# scripts — re-measured at the merge rather than left at the earlier reading,
-# which is the same discipline the note below records failing.)
+# (The 2026-08-05 reading said "32 … and all 31 are listed" and the 2026-08-10
+# reading said "33 … and all 33" while 34 entries were listed — those two are
+# the MISCOUNTS this paragraph exists to warn about, and they are listed here
+# precisely because they were wrong, not correct-at-the-time. The 2026-08-13
+# reading ("257 … 35 of them") and the 2026-08-15 reading ("259 … 36 of them")
+# were both correct when written.
+# Both halves are RECOUNTED here on 2026-08-16: 260 is what
+# `count_gate_scripts()` returns on the tree that carries this change, and 37 is
+# `grep -c '^  - id:'` on this file. Neither number was derived by adding one to
+# the previous prose, which is the move the note below forbids — and the
+# temptation was live, because this change does add exactly one of each.)
 #
 # A 2026-08-13 revision of this paragraph first wrote 256, derived as "255 before
 # this change plus the one it adds" — inside the sentence claiming to have
@@ -769,3 +773,51 @@ gates:
       The canary plants a manifest whose declared CSV does not exist — the exact
       gap `corpus-grounding/scripts/schema_validator.ts` leaves open, since it
       computes the path and never opens the file.
+
+  - id: lint_scheduled_deprecations
+    argv: ["--quiet"]
+    min_scanned: 1
+    corpus: "rows of the `docs/MIGRATION.md` scheduled-deprecations table (3 at baseline)"
+    status: enforced
+    note: >
+      `argv` carries `--quiet` because that is what the task passes: the
+      Taskfile resolves `{{.QUIET_FLAG}}` to `--quiet` unless
+      AGENT_SCRIPT_VERBOSITY=verbose, and the consistency workflow goes through
+      the same task. It passed as a bare call only because `reportScanned` is
+      not quiet-gated while this gate's success line and ledger report are — a
+      coincidence, not the contract rule 2 states.
+      The floor is 1, not "a floor comfortably below the corpus", and the reason
+      is worth stating rather than hiding: the corpus is three rows, so no floor
+      exists that is both below it and far above a collapse. What the floor
+      actually buys here is the contract that the count is PUBLISHED; the
+      collapse case — a drifted heading or a reformatted table parsing to zero
+      rows — is caught one layer up by the gate's own `reportScanned`
+      assertion, which reds instead of printing a green line over nothing.
+      That case is the gate's own subject, so it is pinned by a test fixture
+      too (`a table that parses to zero rows reds rather than exiting green`).
+      No `canary:` recipe: this gate's only violation shape is a MODIFICATION of
+      a tracked artefact (`docs/MIGRATION.md`), and the canary contract is
+      create-only, so it reports UNPROVEN rather than green. Discrimination is
+      proven instead by paired fixtures in
+      `tests/scripts/lint_scheduled_deprecations.test.ts`, verified by mutation:
+      widening the overdue threshold fails the overdue-by-construction case, and
+      granting `allowEmpty` fails the zero-row case.
+
+  - id: check_source_size_budget
+    argv: []
+    min_scanned: 900
+    corpus: "TypeScript sources — src/**/*.ts excluding *.d.ts and *.test.ts, the same two kinds _lib/gate_population excludes (1,063 at baseline)"
+    status: enforced
+    # No `canary:` recipe, and the reason is the canary contract's own shape
+    # rather than a gap. The violation this gate detects is a file OVER 1,500
+    # lines, so a create-only recipe would have to inline 1,501 lines of content
+    # into this manifest — a plant larger than the manifest it lives in. It
+    # reports UNPROVEN rather than green, which is the honest state.
+    #
+    # Discrimination is proven instead by the gate's own `--self-test`, and it is
+    # stronger here than a single plant would be: six cases, three rejecting,
+    # covering a file one line over the ceiling, one line under, exactly at it
+    # (inclusive), a dead scan root, AND — the case a canary could not express —
+    # an already-listed file that GREW while the file COUNT stayed at one. That
+    # last case is what pins the metric as excess lines rather than a file count;
+    # a count-based ratchet passes it, and this gate must not.

package/src/config/gate-violation-baselines.json

@@ -22,6 +22,12 @@
       "landed": "2026-08-02",
       "note": "All 18 are `handoff_tier_mismatch`: a senior-tier skill links to a peer whose frontmatter carries no `tier` (reported as tier='unset') — e.g. build-buy-partner → adr-create, customer-research → po-discovery, gated-reach → threat-modeling. This is a tier-metadata backfill backlog on the LINKED-TO skills, not a broken link. The one genuinely dangling link revealed by the same repair (competitive-positioning → a non-existent ../analyze-reference-repo/SKILL.md; it is a command, not a skill) was FIXED in the repairing commit rather than baselined. Clearing this entry means backfilling `tier` on the linked-to skills, or deciding that `tier: unset` on a link target is not a violation and narrowing the rule."
     },
+    "lint_roadmap_blockers:decidability": {
+      "count": 26,
+      "landed": "2026-08-16",
+      "note": "Open blocker entries that are not yet DECIDABLE by the person who owns them — missing `Recommendation:` (which option and why), missing `If you do nothing:` (the cost of the non-decision), or a `What to do:` carrying no command, path or enumerated option set. Revealed by adding the decidability half to lint_roadmap_blockers, not created by it: the five original fields describe a situation and never made it actionable, so a blocker could pass the contract while handing the analysis back to the person least equipped to redo it. Measured at introduction: 36 open entries, ALL 36 undecidable, and 14 of the 46 total entries carry no command/path/option at all in `What to do`. Baselined rather than hard-failed because 36 findings nobody can clear in the change that reveals them is the gate-that-lands-as-N-instant-blockers failure this repository has refused before — the same reasoning as ci-parity:local-only above. First measured at 34 rather than 36 because the two blockers on the branch that introduced this (`ac3-false-positive-reading`, `publish-side-marker-invariant`) were rewritten to the new standard and then closed in the same change; a baseline above the truth silently permits new violations. Re-measured at 38 when the branch was re-pointed at current main, and the +4 is population growth rather than a loosening: main gained the four `road-to-inbox-harvest-2026-08-d-*` roadmaps (context-ledger, runtime-skill-routing, scheduled-deprecation, top-band-model-economy), each carrying one open blocker authored before this requirement existed. That is the honest number for the population this gate now scans — recording 34 against a 38-entry tree would have failed the gate on its own introducing commit and taught the next reader to distrust it. Lowering happens one blocker at a time, and every roadmap touched for other reasons is a chance to lower it. Lowered 38→37 by the scheduled-deprecation PR, which is exactly that shape: code-graph-removal-authorisation was rewritten to the new standard because the roadmap was being touched anyway. Its `If you do nothing:` was one of the few that was not the common no-cost answer — the release gate that PR ships would have refused the next major cut while the blocker stayed open. Recorded in the past tense because the maintainer then RESOLVED that blocker on the trunk by withdrawing the commitment, so nothing refuses a cut today. The lowering stands on the rewrite, not on the consequence, and the sentence is corrected rather than deleted because a baseline note arguing from a retracted state is how a ratchet's rationale rots. The 56-day expiry is the point, not a hazard: if this number has not moved in two months, the fields are not being written and the gate should fail until someone decides whether the requirement is real. Lowered 37→34 when the scheduled-deprecation branch merged current main: three blockers were resolved or rewritten on the trunk in the meantime, so the drop is a genuine drain plus a merge, not a loosening. Re-tightened here rather than left loose because a ratchet that lags its own tree permits violations back in silently. Lowered 34→29 on 2026-08-16 by rewriting six entries to the new standard (raw-capture-needs-host-env, telemetry-sample-size, repo-admin-and-usage, benchmark-spend, measurement-a-no-per-arm-builder-tier, measurement-b-no-renderable-lane-pair) in a PR whose only purpose was the drain — the first lowering not taken on the back of another change, which the note above says is the usual shape. Two findings from that pass are worth keeping. The tree measured 35 against a baseline of 34 BEFORE the drain, i.e. the ratchet was already red on main and nobody knew: this gate runs in `task ci`, no workflow invokes `task ci`, and the local run that would have shown it was read through a `tail`, which hid every row above the last six. And four of the six `If you do nothing:` answers are honestly that nothing degrades — that is the true answer for a held measurement, and writing it is what makes the entry decidable, so the field earns its place by being cheap to answer truthfully rather than by always carrying a cost. Lowered 29 → 27 on 2026-08-16 by the merge of this branch and the trunk drain above, and the arithmetic matters more than the delta: both sides rewrote entries from the same tree of 35 independently — the trunk six (recorded above), this branch two (deferred-finding-decision-reopen, spent-inbox-artifacts-await-deletion, rewritten because road-to-inbox-harvest-residuals was being touched anyway). The sets are disjoint, so the merged tree measures 27 and the gate itself reported the slack. Tightened rather than banked: 29 against a 27-entry tree would absorb the next two undecidable blockers without anything noticing, which is the lag this note has now corrected twice. Lowered 27 → 26 on 2026-08-16 by rewriting `picktier-wire-or-archive` (road-to-inbox-harvest-2026-08-d-top-band-model-economy), and this one is the usual shape the note describes rather than the dedicated-drain shape: the roadmap was being worked for its own Step 4.1 and the entry was rewritten because it was open on the desk. Worth recording for what writing the two fields SURFACED, which is the argument for the requirement: `Recommendation:` forced the question 'which option, and why' and the honest answer turned out not to be one of the three options at all — the entry defers to a converged council verdict, and the council cannot reach quorum (re-measured 0 of 2 the same day), so the actionable next step is a one-line fix to a user-global config file outside this repository. Five fields had described that situation accurately for two weeks without anyone noticing that the named blocker was infrastructure rather than judgement.",
+      "falsifier": "./scripts-run src/scripts/lint_roadmap_blockers --quiet"
+    },
     "lint_pack_boundaries": {
       "count": 337,
       "landed": "2026-08-02",
@@ -49,6 +55,12 @@
       "landed": "2026-08-12",
       "note": "Anti-regrowth ratchet for the settings disposition axis. 83 of 134 template leaves are classified `derivable` — the mechanism can decide from the situation, so the key should not exist — and each names the replacement that would decide instead (`lint_settings_classes` rejects the bare label, which is what keeps the class from becoming a synonym for \"inconvenient to keep\"). This is a DELETION QUEUE, not 83 deletions: a row stays until the mechanism it names actually exists, and deleting a key ahead of its mechanism is a silently-changed default rather than a simplification. Shrink-only from here, which is the anti-regrowth half — a NEW key classified `derivable` raises the number and reds, so a key whose answer the situation already carries cannot be added at all. The 56-day non-stagnation clause is the other half and is wanted here rather than tolerated: a queue that never drains is a stated direction nobody is walking. The queue opened at 88 of 140 on 2026-08-12 and drained to 83 of 134 the same day: six keys had no reader whatsoever (telegraph.speak_scope, chat_history.max_size_kb, chat_history.on_overflow, quality.wait_for_remote_ci, screenshots.data_bearing_gate, legal_review_prep.consented_at), five of them `derivable` and one a `consent` row reclassified because a published-egress confirmation is a Hard Floor no setting may lift. An unread key is the only deletion that cannot silently change a default, which is why that batch went first. The classification itself is docs/contracts/settings-classes.md.",
       "falsifier": "./scripts-run src/scripts/lint_settings_classes"
+    },
+    "check_source_size_budget": {
+      "count": 19725,
+      "landed": "2026-08-17",
+      "note": "Lowered 19,763 → 19,725 on 2026-08-17 by the T4/T5 endpoint branch, and it is a lowering rather than a re-anchor: that branch grew two already-over-ceiling files (bench_ab_v2_run.ts, bench_ab_v2_stats.ts) by 89 lines and paid it back by EXTRACTION — the workspace/transcript lifecycle and the T5 report adapters moved into `_lib/`, which is exactly what this entry means by lowering happening through splitting a god-file. Trimming comments was tried first and reached 5 of the 89; the extraction went 38 past the baseline, which is the difference between the two moves. Total lines above the 1,500-line source ceiling, summed across the 1,063 hand-written `.ts` files under `src/` — `*.d.ts` and `*.test.ts` are excluded, the same two kinds `_lib/gate_population` excludes and for the same stated reasons (a declaration has no runtime behaviour; a test file is not the reviewable code this ceiling bounds). Latent rather than cosmetic: a GENERATED `.d.ts` over the ceiling would otherwise red a ratchet aimed at hand-written code. Revealed by introducing check_source_size_budget, not created by it: every other size budget in this suite guards prose (rules by char cap, skills by token class, the depth layer by check_depth_budget), and the TypeScript the package actually ships carried none — which is where the largest artefacts in the tree sit. Fifteen files are over the ceiling; the worst three are install.ts (5,461), skill_linter.ts (4,742) and council_cli.ts (4,058). THE METRIC IS EXCESS LINES, NOT A FILE COUNT, and that is the load-bearing choice: a file count would read 15 whether install.ts sits at 5,461 or at 9,000, so the gate would stay green while the exact defect it exists for got worse. Summing the excess costs the same one integer and fails on growth inside an already-listed file — pinned by a self-test case that holds the file count at 1 and moves only the size. Baselined rather than hard-failed because 15 god-files nobody can split in the change that reveals them is the gate-that-lands-as-N-instant-blockers failure this repository has refused before; shrink-only keeps the property that matters, namely that a NEW file over 1,500 lines reds immediately. The ceiling is a growth ratchet, never a quality threshold: 1,500 was chosen by measuring this tree (15 files over 1,500, versus 44 over 1,000 and 75 over 800) as the tightest ceiling whose ledger stays signal rather than becoming the 20-plus-entry allowlist this repository's own rules call evidence that the linter is wrong. Lowering happens by splitting a god-file, and the ordering is deliberate: ratchet BEFORE split, so every later split is a lowering commit whose gain is visible in one integer, instead of a large diff with nothing asserting it improved anything. The 56-day expiry is the point, not a hazard — a ceiling with no forcing function would leave these fifteen files at these fifteen sizes indefinitely with the gate green the whole time. Re-anchored 19,676 → 19,763 on 2026-08-16 when this branch merged current main, and the +87 is population growth rather than a loosening — the same shape the blocker ratchet above records for its own +4. Every one of the 87 lines is `src/scripts/mcp_server/tools.ts` growing on the trunk between this branch's base (8edeae39) and the merge; no file in this branch's own diff is over the ceiling at all, which is checkable in one command: `git diff --stat <base> origin/main -- <the fifteen listed files>`. Recording 19,676 against a 19,763-line tree is the failure this entry's own test asserts against — a baseline below the truth fails the gate on arrival, and one above it silently sells a free regression.",
+      "falsifier": "./scripts-run src/scripts/check_source_size_budget --quiet"
     }
   }
 }

package/src/config/hook-token-budget.json

@@ -27,7 +27,9 @@
         "reread-guard": 1024,
         "reread-guard_reason": "one advisory line naming the earlier read / ranged alternative (roadmap 6.1)",
         "session-eol": 1024,
-        "session-eol_reason": "one recycle-advisory line, once per session past the committed threshold (road-to-token-economy-recycling 3.2); recording itself emits nothing"
+        "session-eol_reason": "one recycle-advisory line, once per session past the committed threshold (road-to-token-economy-recycling 3.2); recording itself emits nothing",
+        "skill-route": 512,
+        "skill-route_reason": "road-to-inbox-harvest-2026-08-d-runtime-skill-routing 2.1: one line carrying at most three skill ids and their scores - pointers, never bodies. Registered BELOW the 1024 default deliberately: this row is the ceiling that keeps it a pointer line, so a later change that starts injecting descriptions fails the build instead of quietly doubling a per-turn slot that already carries nine other concerns under a 4096-byte sum cap"
     },
     "per_slot_sum_caps_bytes": {
         "_comment": "Cross-concern per-fire sum per slot (roadmap 3.1). session_start is one-time and may carry the restore payloads; per-turn slots stay tight.",
@@ -49,6 +51,11 @@
         "_comment": "Roadmap 5.3 + 6.4 registrations. These are BEHAVIOUR metrics (advisory adoption), not injection bytes - registered here because this file already carries the owner/review discipline for the same concerns.",
         "owner": "maintainer",
         "review_by": "2026-11-10",
+        "skill_route_pointer_rate": {
+            "definition": "road-to-inbox-harvest-2026-08-d-runtime-skill-routing 2.2: skill-route fires / user_prompt_submit events per session - the share of prompts where the deterministic ranker cleared its measured p90 floor and injected pointers. NO THRESHOLD IS COMMITTED, deliberately and by the house baseline-first rule: the TRIGGER is calibrated (top-1 >= 30/100, the p90 of 496 routing-matrix prompt lines, expected to fire on ~13.9%), the OUTCOME is not. Kill standard as for the sibling nudges: a nudge whose pointers are measurably ignored over the review window gets its floor raised or its line removed. Expected fire rate is the falsifier for the trigger half - a live rate far from 13.9% means the corpus is not representative of real prompts, which is a finding about the corpus and is published either way.",
+            "instrument": "rule-trips.json warn counters for the skill-route concern (fires) + conformance audits for whether the pointed-at skill was opened (adoption); HONEST GAP: no deterministic counter exists for 'the agent acted on the pointer' - the numerator is audit-carried and registered as such rather than implied to be automatic",
+            "threshold": "none committed before data - baseline first, threshold at review date (2026-11-10)"
+        },
         "full_rewrite_small_diff_rate": {
             "definition": "edit-shape fires / Write calls per session (the full-rewrite-with-small-diff rate). Kill criterion per the shipped nudge standard: a nudge whose verdicts are measurably ignored (adoption near zero over the review window, from conformance audits) gets its trigger tightened or the injected line removed.",
             "instrument": "rule-trips.json warn counters (the dispatcher already counts every warn per concern) + conformance audits for adoption"
@@ -58,10 +65,16 @@
             "instrument": "rule-trips.json warn counters per concern"
         },
         "unbounded_output_advisory_rate": {
-            "definition": "Roadmap 4.3 + 4.4 registration (advisory-degraded per the resolved pretooluse-rewrite-semantics blocker: no updatedInput in the v1 contract, so nothing caps and nothing can be bypassed - the demand signal is the fire count itself). rtk-wrap cap-advisory fires per session from the OUTPUT_CAP_TABLE branch; adoption (did the next run use a bounded form) via conformance audits. HONEST GAP: bytes-into-context from tool RESULTS is not instrumented anywhere (the census covers hook payloads only) - the pre/post bytes half of roadmap 4.4 is registered as unmeasurable until a tool-result byte counter exists.",
+            "definition": "Roadmap 4.3 + 4.4 registration (advisory-degraded per the resolved pretooluse-rewrite-semantics blocker: no updatedInput in the v1 contract, so nothing caps and nothing can be bypassed - the demand signal is the fire count itself). rtk-wrap cap-advisory fires per session from the OUTPUT_CAP_TABLE branch; adoption (did the next run use a bounded form) via conformance audits. GAP CLOSED 2026-08-15 (road-to-inbox-harvest-2026-08-d-context-ledger Step 1.1): the tool-result byte counter now exists and its stream is registered below as `tool_result_bytes`. The pre/post bytes half of roadmap 4.4 is measurable from that census once it carries data; it stays unread, not unmeasurable, until a baseline is published.",
             "instrument": "rule-trips.json warn counters for the rtk-wrap concern + conformance audits",
             "threshold": "none committed before data - baseline first, threshold at review date"
         },
+        "tool_result_bytes": {
+            "definition": "road-to-inbox-harvest-2026-08-d-context-ledger 1.1: UTF-8 bytes of every tool RESULT entering context, per call, keyed by tool name. Closes the gap `unbounded_output_advisory_rate` registered above - the injection census measures what this suite puts into context, this measures what the host's tools do, and the second is the larger term. CAPTURE ONLY: the concern emits zero bytes to the model, so it carries no per-concern injection cap; it is registered here because this file already owns the owner/review discipline for context-cost instruments.",
+            "instrument": "the `tool-result-bytes` concern (src/scripts/hooks/tool_result_bytes_hook.ts) on post_tool_use, appending {ts, tool, bytes, measurable} to agents/runtime/state/tool-result-census.jsonl",
+            "privacy": "census lines carry a tool NAME, a byte COUNT and a timestamp - the record type has no field able to hold file contents, command output or any free text, so there is no scrubber that can fail",
+            "threshold": "none committed before data - baseline first, threshold at review date. A `measurable: false` line means the host's payload carried no readable result; that absence is itself a coverage finding and is never counted as zero bytes"
+        },
         "turns_per_task": {
             "definition": "user_prompt_submit count keyed to the task envelope - the invisible multiplier (every turn re-pays the accumulated context at read rates).",
             "instrument": "session-register / chat-history turn counters; HONEST GAP: no task-envelope key exists yet in those counters - the number is per-SESSION until a task key ships; registered with that stated limitation rather than silently redefined",

package/src/config/preamble-payload-budget.json

@@ -35,6 +35,34 @@
         "p95": 50000,
         "_comment": "The roadmap's candidate numbers, kept as the destination. Reaching them needs reductions this package has not built yet; scope-dedup (C-3) removes a redundant COPY at the consumer, it does not shrink the suite itself."
     },
+    "target_schedule": {
+        "_comment": "road-to-inbox-harvest-2026-08-d-context-ledger Step 5.3. The target above was a destination with no route: the ratchet fails on GROWTH only, so the corpus can drift away from 40k indefinitely without any gate objecting. These milestones give the destination a schedule. They are DATES WITH NUMBERS, not a derivation - no measurement in this tree says the estate can reach 85k by a given day, and pretending otherwise would be the invented-threshold failure this file's own baseline_history is careful to avoid. What they buy is that a miss becomes a published fact with an owner instead of a silent drift.",
+        "owner": "maintainer",
+        "measured_at_registration": {
+            "tokens": 125593,
+            "at": "2026-08-15",
+            "note": "MEASURED total at registration time, from check_preamble_payload_budget. It is ~23k ABOVE both baseline_tokens (102520) and the derived ceiling, i.e. the gate is red on the tree as it stands. The baseline is deliberately NOT raised to meet it - raising a ratchet baseline to clear a failing check is the config-weakening move this repo blocks by construction. It is recorded here so the milestones below are planned against the real starting point rather than a stale one. Per-rule ranking: agents/evidence/analysis/rule-paths-coverage-census.md"
+        },
+        "milestones": [
+            {
+                "by": "2026-11-10",
+                "tokens": 102520,
+                "why": "Return to the registered baseline. This is a RECOVERY milestone, not progress toward 40k - it undoes drift rather than shrinking the estate. The date is the review_by both budget files already carry, so it needs no new calendar."
+            },
+            {
+                "by": "2027-02-10",
+                "tokens": 85000,
+                "why": "First real reduction. The rule-paths census shows 92.1% of rule weight sits in the auto tier and the top 20 files carry 35.5% of it, so a scoped tranche is the plausible mechanism - GATED on the paths-scoping consumer decision, which is a human call and may resolve against scoping entirely."
+            },
+            {
+                "by": "2027-05-10",
+                "tokens": 60000,
+                "why": "Second reduction. No mechanism is committed for this one; it exists so the destination keeps a date after the first tranche lands, and it is the milestone most likely to be revised on evidence."
+            }
+        ],
+        "on_miss": "A missed milestone is PUBLISHED - recorded here with the measured number and the reason - and never silently re-dated. Two consecutive misses mean the schedule was wrong or the destination is unreachable with the mechanisms available; either outcome is a decision to surface, not a date to move again.",
+        "revisit_if": "The paths-scoping decision resolves against scoping (removing the only named mechanism for the 85k milestone), or a measured reduction lands ahead of schedule and the remaining milestones are re-derived from it."
+    },
     "reference_measurements": {
         "measured_cold_start_median_tokens": 230930,
         "c3_scope_dedup_reduction_pct": 38,

package/src/scripts/_dispatch.bash

@@ -250,6 +250,11 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              router + projection freshness, host bridge status.
                              Flags: --platform <p>, --workspace <path>, --json, --strict,
                              --no-freshness
+  workspace:doctor           One answer to "where am I": repo root, main worktree, current
+                             worktree, branch, PR base — each with its provenance — plus
+                             session claim, conflicting records and worktree pressure.
+                             Read-only; no disposal path by design.
+                             Flags: --from <dir>, --json, --strict
   route:explain              Deterministic rule-routing trace for one prompt: matched
                              triggers, tier, injected-vs-pointer disposition, budget
                              consumption, rejected candidates. Trigger-match level only
@@ -899,6 +904,10 @@ cmd_routing_doctor() {
   exec_hook "src/scripts/routing_doctor" "$@"
 }
 
+cmd_workspace_doctor() {
+  exec_hook "src/scripts/workspace_doctor" "$@"
+}
+
 cmd_hooks_replay() {
   exec_hook "src/scripts/hooks/replay_hook" "$@"
 }
@@ -1422,6 +1431,7 @@ main() {
     hooks:status)            cmd_hooks_status "$@" ;;
     hooks:doctor)            cmd_hooks_doctor "$@" ;;
     routing:doctor)          cmd_routing_doctor "$@" ;;
+    workspace:doctor)        cmd_workspace_doctor "$@" ;;
     route:explain)           cmd_route_explain "$@" ;;
     route:audit)             cmd_route_audit "$@" ;;
     hooks:replay)            cmd_hooks_replay "$@" ;;