@event4u/agent-config 9.29.0 → 9.30.0

package/dist/ui/index.html

@@ -27,7 +27,7 @@
                 document.documentElement.setAttribute('data-theme', theme);
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-JDAF00bC.js"></script>
+      <script type="module" crossorigin src="/assets/index-B5qGYOJo.js"></script>
       <link rel="stylesheet" crossorigin href="/assets/index-jSfMW8_t.css">
     </head>
     <body>

package/docs/contracts/settings-classes.md

@@ -22,14 +22,26 @@ raise a spend ceiling, empty an allowlist, or switch off a gate.
 | **B — consent** | the agent, but only after ONE just-in-time ask that the user answered | **once**, then persisted with provenance. |
 | **C — guarded** | the GUI's write route or a hand-edit, by a human | never asked by the agent; **every agent write path refuses it.** |
 
+### The provenance sidecar's record shape
+
+"Persisted with provenance" means one record per dotted key in
+`settings/.agent-settings.provenance.json`, written by `settings:set` beside
+the value: `{ "source": "auto-detected" | "jit-answer" | "manual" | "gui",
+"at": "<ISO timestamp>" }`. For a class-B key the `at` stamp IS the grant
+time — the consent reader (`consentVerdict`) grants on `jit-answer` / `gui` /
+`manual` provenance, so source + timestamp together are the audit record of
+who consented and when. `expires_at` / `revoked_at` / contract-version fields
+stay deliberately unbuilt until a reader needs them — a field nothing reads is
+surface without a consumer.
+
 ## What the fence covers — and what it does not
 
 **It governs writes, not reads.** Every class is readable by everything. A C
 class does not hide a value; it refuses to let a non-human change it.
 
-**It governs writes, not asks.** Six settings ship an `ask` value in their own
-enum (`tokens.rich_skills`, `subagents.auto`, `subagents.budget_routing`,
-`subagents.adversarial_council`, `worktrees.mode`, `decision_engine.on_block`).
+**It governs writes, not asks.** Four settings ship an `ask` value in their own
+enum (`tokens.rich_skills`, `subagents.adversarial_council`, `worktrees.mode`,
+`decision_engine.on_block`).
 Those are C-class here, and that is not a contradiction: the class says who may
 *persist* a new value; the `ask` value says what happens *at runtime* when the
 setting is already set to `ask`. A C-class key set to `ask` still produces a
@@ -168,8 +180,8 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 27 |
 | B — consent | 3 |
-| C — guarded | 107 |
-| **Total** | **137** |
+| C — guarded | 111 |
+| **Total** | **141** |
 
 The total is every leaf in the template, where *leaf* means anything that is not
 a **non-empty** map. An empty map (like the former `subagents.host_capabilities: {}`) is a real
@@ -269,6 +281,7 @@ Rows follow template order, so a diff against the template reads straight down.
 | `subagents.model_map.high` | C | `""` | names an external model endpoint |
 | `subagents.implementer_model` | C | `""` | names an external model endpoint |
 | `subagents.judge_model` | C | `""` | names an external model endpoint |
+| `subagents.model_ceiling` | C | `""` | session-wide subagent model cap (exported as `CLAUDE_CODE_SUBAGENT_MODEL` by suite-owned CLI spawn wrappers), which is spend and quality |
 | `subagents.max_parallel` | C | `3` | parallelism cap, and therefore a spend rate |
 | `subagents.adversarial_council` | C | `"off"` | governs a paid verification step |
 | `worktrees.mode` | C | `ask` | standing permission for autonomous worktree creation |
@@ -312,6 +325,9 @@ Rows follow template order, so a diff against the template reads straight down.
 | `hooks.rtk_wrap.enabled` | C | `false` | configures code that runs on every tool call |
 | `hooks.design_slop.enabled` | C | `false` | configures code that runs on every tool call |
 | `hooks.code_graph.enabled` | C | `false` | configures code that runs on every tool call |
+| `hooks.turn_end_gate.enabled` | C | `false` | arms the only concern that can REFUSE a turn-end; an agent must never be able to switch its own delivery gate on |
+| `hooks.turn_end_gate.promissory` | C | `true` | which refusal the turn-end gate may raise; inert while the master switch is off |
+| `hooks.turn_end_gate.language` | C | `true` | which refusal the turn-end gate may raise; inert while the master switch is off |
 | `decision_engine.surface_traces` | C | `false` | the decision engine’s own black box; the agent must not be able to close it |
 | `decision_engine.min_confidence` | C | `"off"` | the confidence gate |
 | `decision_engine.block_on_risk` | C | `"off"` | the risk-class gate |

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.29.0",
+    "version": "9.30.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/roadmap_gates.ts

@@ -0,0 +1,312 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config gates` — the open decisions that need the user, as actions.
+ *
+ * The dashboard (`update_roadmap_progress`) already parses every `## Blockers`
+ * entry and already counts them per roadmap. What it does not do is separate
+ * the blockers the *user* must resolve from the ones the maintainer or an
+ * external party owns: the count links into a per-roadmap breakdown, so
+ * answering "what do I have to do" means opening every anchor and filtering
+ * `Owner:` by hand across the whole file. The fields exist, are CI-enforced by
+ * `lint_roadmap_blockers`, and never reach the user in a form they can act on.
+ *
+ * This command is that missing projection, and nothing more: same parser
+ * (`parse_blockers` / `collect`, imported — never re-implemented), filtered by
+ * owner, ordered by how much each blocker unblocks, rendered action-first.
+ *
+ * Deliberately NOT a gate: it exits 0 whether or not decisions are pending.
+ * Blocking a pipeline on "the user has an open decision" would turn a
+ * visibility aid into a second thing to fight.
+ *
+ * Invocation (from project root):
+ *   ./agent-config gates            # decisions owned by the user
+ *   ./agent-config gates --all      # every open blocker, grouped by owner
+ *   ./agent-config gates --json     # machine-readable
+ */
+
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+import {
+    collect,
+    blocker_needs_user as needsUser,
+    type Blocker,
+} from './update_roadmap_progress.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Hard wrap for the rendered body — keeps output readable in a narrow pane. */
+const WIDTH = 78;
+
+interface Entry {
+    blocker: Blocker;
+    roadmapRel: string;
+    /** Open steps in the roadmap this blocker sits in — the "unblocks" weight. */
+    openSteps: number;
+}
+
+/**
+ * Rejoin wrapped continuation lines into one step each.
+ *
+ * `parse_blockers` returns `todo` as raw stripped lines, so a step that wraps
+ * over three source lines arrives as three entries. A new step starts at an
+ * ordered marker (`1.`, `2)`) or a bullet; everything else continues the one
+ * before it.
+ */
+function regroupTodo(todo: readonly string[]): string[] {
+    const steps: string[] = [];
+    for (const line of todo) {
+        const startsStep = /^(\d+[.)]|[-*+])\s/.test(line);
+        if (startsStep || steps.length === 0) {
+            steps.push(line);
+        } else {
+            steps[steps.length - 1] = `${steps[steps.length - 1] as string} ${line}`;
+        }
+    }
+    return steps;
+}
+
+/** Wrap `text` to `width`, indenting every line after the first by `indent`. */
+function wrap(text: string, width: number, indent: string): string[] {
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+        return [];
+    }
+    const lines: string[] = [];
+    let cur = '';
+    for (const w of words) {
+        const candidate = cur === '' ? w : `${cur} ${w}`;
+        if (candidate.length > width && cur !== '') {
+            lines.push(cur);
+            cur = w;
+        } else {
+            cur = candidate;
+        }
+    }
+    if (cur !== '') {
+        lines.push(cur);
+    }
+    return lines.map((l, i) => (i === 0 ? l : indent + l));
+}
+
+/**
+ * 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
+ * runs flush against its own label.
+ */
+const LABEL_W = 15;
+
+/** A labelled block: `  Label:  value`, wrapped and hanging-indented. */
+function field(label: string, value: string): string[] {
+    const pad = '  ' + label.padEnd(LABEL_W);
+    const indent = ' '.repeat(pad.length);
+    const lines = wrap(value, WIDTH - pad.length, indent);
+    if (lines.length === 0) {
+        return [];
+    }
+    return [pad + lines[0], ...lines.slice(1)];
+}
+
+function collectEntries(roadmapRoot: string): Entry[] {
+    const entries: Entry[] = [];
+    for (const r of collect(roadmapRoot)) {
+        for (const b of r.open_blockers) {
+            entries.push({ blocker: b, roadmapRel: r.rel, openSteps: r.open_ });
+        }
+    }
+    // Most-unblocking first; ties broken deterministically so two runs on an
+    // unchanged tree print byte-identical output.
+    entries.sort(
+        (a, b) =>
+            b.openSteps - a.openSteps ||
+            a.roadmapRel.localeCompare(b.roadmapRel) ||
+            a.blocker.id.localeCompare(b.blocker.id),
+    );
+    return entries;
+}
+
+/**
+ * The parser's legacy fallback synthesises one blocker per `> Blocked until …`
+ * note under the fixed id `legacy`. That id is an implementation detail and
+ * says nothing to a reader, and its text is a *condition* ("blocked until X"),
+ * not an imperative — so both the heading and the field label are renamed for
+ * this one parser-defined case rather than dressed up as a step list.
+ */
+function isLegacy(b: Blocker): boolean {
+    return b.id === 'legacy';
+}
+
+function renderEntry(e: Entry, index: number): string[] {
+    const head = `${index} · ${isLegacy(e.blocker) ? 'blocked-until note' : e.blocker.id}`;
+    const tail =
+        e.openSteps > 0 ? `unblocks: ${e.openSteps} step${e.openSteps !== 1 ? 's' : ''}` : '';
+    const dashes = Math.max(3, WIDTH - head.length - tail.length - 6);
+    const out: string[] = [
+        '',
+        `── ${head} ${'─'.repeat(dashes)} ${tail}`.trimEnd(),
+        ...field('Roadmap:', e.roadmapRel),
+        ...field('Blocks:', e.blocker.blocks),
+    ];
+
+    const doLabel = isLegacy(e.blocker) ? 'Blocked until:' : 'Do this:';
+    const steps = regroupTodo(e.blocker.todo);
+    if (steps.length === 0) {
+        out.push(
+            ...field(
+                doLabel,
+                '(no steps recorded — the blocker entry in the roadmap needs a ' +
+                    '**What to do:** list)',
+            ),
+        );
+    } else {
+        out.push(...field(doLabel, steps[0] as string));
+        for (const s of steps.slice(1)) {
+            // Steps 2..n have no label of their own — align them under the
+            // first step's text, i.e. the same gutter `field()` produces.
+            const indent = ' '.repeat(LABEL_W + 2);
+            const lines = wrap(s, WIDTH - LABEL_W - 2, indent);
+            out.push(...lines.map((l, i) => (i === 0 ? indent + l : l)));
+        }
+    }
+    out.push(...field('Done when:', e.blocker.resolvedWhen));
+    return out;
+}
+
+function render(entries: readonly Entry[], all: boolean): string {
+    const mine = entries.filter((e) => needsUser(e.blocker.owner));
+    const others = entries.filter((e) => !needsUser(e.blocker.owner));
+    const shown = all ? entries : mine;
+    const lines: string[] = [];
+
+    if (mine.length === 0) {
+        lines.push(
+            others.length === 0
+                ? 'No open blockers at all.'
+                : `Nothing is waiting on you. ${others.length} open blocker` +
+                      `${others.length !== 1 ? 's' : ''} sit with maintainer/external` +
+                      `${all ? '' : ' — see --all'}.`,
+        );
+    } else {
+        const head =
+            `${mine.length} decision${mine.length !== 1 ? 's' : ''} need${mine.length === 1 ? 's' : ''} you`;
+        const rest =
+            others.length > 0
+                ? ` · ${others.length} more with maintainer/external${all ? '' : ' (--all)'}`
+                : '';
+        lines.push(head + rest);
+    }
+
+    let n = 0;
+    for (const e of shown) {
+        n += 1;
+        lines.push(...renderEntry(e, n));
+    }
+    if (shown.length > 0) {
+        lines.push('');
+    }
+    return lines.join('\n') + '\n';
+}
+
+function renderJson(entries: readonly Entry[], all: boolean): string {
+    const pick = all ? entries : entries.filter((e) => needsUser(e.blocker.owner));
+    return (
+        JSON.stringify(
+            {
+                needsYou: entries.filter((e) => needsUser(e.blocker.owner)).length,
+                other: entries.filter((e) => !needsUser(e.blocker.owner)).length,
+                blockers: pick.map((e) => ({
+                    id: e.blocker.id,
+                    roadmap: e.roadmapRel,
+                    owner: e.blocker.owner,
+                    needsYou: needsUser(e.blocker.owner),
+                    blocks: e.blocker.blocks,
+                    unblocksSteps: e.openSteps,
+                    todo: regroupTodo(e.blocker.todo),
+                    resolvedWhen: e.blocker.resolvedWhen,
+                })),
+            },
+            null,
+            2,
+        ) + '\n'
+    );
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Same repo-root resolution as the dashboard: honour the cwd when it holds
+ * `agents/roadmaps`, otherwise fall back to the git toplevel (monorepo
+ * sub-project support).
+ */
+function _resolveRepoRoot(start: string): string {
+    if (_isDir(path.join(start, 'agents', 'roadmaps'))) {
+        return start;
+    }
+    try {
+        const r = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: start,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        const top = (r.stdout || '').trim();
+        if (r.status === 0 && top !== '' && _isDir(path.join(top, 'agents', 'roadmaps'))) {
+            return top;
+        }
+    } catch {
+        /* not a git repo / git missing — keep the cwd default */
+    }
+    return start;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const all = args.includes('--all');
+    const json = args.includes('--json');
+
+    const repoRoot = _resolveRepoRoot(process.cwd());
+    const roadmapRoot = path.join(repoRoot, 'agents', 'roadmaps');
+    if (!_isDir(roadmapRoot)) {
+        process.stdout.write(
+            json ? '{"needsYou":0,"other":0,"blockers":[]}\n' : 'No roadmaps directory — nothing to report.\n',
+        );
+        return 0;
+    }
+
+    const entries = collectEntries(roadmapRoot);
+    process.stdout.write(json ? renderJson(entries, all) : render(entries, all));
+    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()) {
+    process.exitCode = main();
+}
+
+export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson };
+export type { Entry };

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

@@ -398,14 +398,32 @@ function _blockerField(slice: string, label: string): string | null {
     return parts.length ? parts.join(' ') : null;
 }
 
-/** Lines under `- **What to do:**` up to the next `- **Field:**` marker. */
+/**
+ * The `- **What to do:**` text: the remainder of the marker line, plus every
+ * line under it up to the next `- **Field:**` marker.
+ *
+ * The marker line's own remainder is load-bearing and used to be dropped.
+ * Authors write both shapes — a numbered list under the marker, and prose that
+ * starts inline (`- **What to do:** the build work is done; only real …`) —
+ * and every *other* blocker field reads the inline part via `_blockerField`.
+ * Skipping it here truncated instructions mid-sentence in both the dashboard
+ * and `agent-config gates`, which is precisely the content those surfaces
+ * exist to deliver.
+ */
 function _blockerTodo(slice: string): string[] {
     const lines = _splitlines(slice);
-    const startIdx = lines.findIndex((l) => /^-[ \t]*\*\*What to do:\*\*/i.test(_strip(l)));
+    const markerRe = /^-[ \t]*\*\*What to do:\*\*[ \t]*(.*)$/i;
+    const startIdx = lines.findIndex((l) => markerRe.test(_strip(l)));
     if (startIdx === -1) {
         return [];
     }
     const out: string[] = [];
+    const inline = _stripComment(
+        (markerRe.exec(_strip(lines[startIdx] as string))?.[1] as string) ?? '',
+    );
+    if (inline) {
+        out.push(inline);
+    }
     for (let i = startIdx + 1; i < lines.length; i++) {
         const trimmed = _strip(lines[i] as string);
         if (BLOCKER_FIELD_RE.test(trimmed) || trimmed.startsWith('#')) {
@@ -458,18 +476,56 @@ function parse_blockers(raw_text: string): Blocker[] {
     }
     const legacyMatch = LEGACY_BLOCKED_UNTIL_RE.exec(text);
     if (legacyMatch) {
+        // The legacy note is a blockquote and routinely wraps over several
+        // `> ` lines. The regex captures one line, so the continuation used to
+        // be dropped and the instruction ended mid-sentence — the same defect
+        // `_blockerTodo` carried above. Walk the following quoted lines until
+        // the quote block ends.
+        const parts = [_strip(legacyMatch[1] as string)];
+        const allLines = _splitlines(text);
+        const noteIdx = allLines.findIndex((l) => LEGACY_BLOCKED_UNTIL_RE.test(_strip(l)));
+        for (let i = noteIdx + 1; noteIdx !== -1 && i < allLines.length; i++) {
+            const quoted = /^>[ \t]?(.*)$/.exec(_strip(allLines[i] as string));
+            if (!quoted) {
+                break;
+            }
+            const cont = _strip(quoted[1] as string);
+            if (cont === '') {
+                break;
+            }
+            parts.push(cont);
+        }
         blockers.push({
             id: 'legacy',
             status: 'open',
             owner: 'user',
             blocks: 'entire roadmap',
-            todo: [_strip(legacyMatch[1] as string)],
+            todo: [parts.join(' ')],
             resolvedWhen: 'condition described above clears',
         });
     }
     return blockers;
 }
 
+/**
+ * Does this blocker need the human at the keyboard, rather than the maintainer
+ * or an external party?
+ *
+ * Owner values in the wild are not the clean `user | maintainer | external`
+ * enum the template comment suggests — real entries carry qualifiers
+ * (`user (billable spend)`, `user / maintainer`, `maintainer (security role)`).
+ * Word-boundary matching on `user` keeps the qualified forms and rejects
+ * `maintainer`. A shared `user / maintainer` blocker deliberately counts as the
+ * user's: showing one decision too many costs a line, hiding one costs the wait.
+ *
+ * Lives here rather than in `roadmap_gates` because it is owner *semantics*,
+ * not presentation — the dashboard header and `agent-config gates` must agree
+ * on the split, and two copies of this regex would drift.
+ */
+function blocker_needs_user(owner: string): boolean {
+    return /\buser\b/i.test(owner);
+}
+
 function parse_roadmap(p: string, roadmap_root: string): RoadmapStats | null {
     const text = fs.readFileSync(p, { encoding: 'utf-8' });
     const phase_matches: Array<{ start: number; end: number; g2: string; g3: string | undefined }> =
@@ -674,6 +730,14 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
     const total_open_blockers = roadmaps.reduce((s, r) => s + r.open_blockers.length, 0);
+    // The count alone answers "is something blocked", never "is it on me" —
+    // and the per-roadmap anchors make the owner split a manual read across the
+    // whole file. Name the user's share here and point at the command that
+    // renders those entries as actions.
+    const user_open_blockers = roadmaps.reduce(
+        (s, r) => s + r.open_blockers.filter((b) => blocker_needs_user(b.owner)).length,
+        0,
+    );
     const lines: string[] = [];
     lines.push('# Roadmap Progress\n');
     const header_meta =
@@ -682,7 +746,10 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
         ' · [roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · ' +
         '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)' +
         (total_open_blockers > 0
-            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}`
+            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}` +
+              (user_open_blockers > 0
+                  ? `, **${user_open_blockers}** need you → \`agent-config gates\``
+                  : '')
             : '') +
         '\n';
     lines.push(
@@ -1074,6 +1141,7 @@ export {
     is_roadmap_candidate,
     count_checkboxes,
     parse_blockers,
+    blocker_needs_user,
     parse_roadmap,
     bar,
     collect,

package/src/config/agent-settings.template.yml

@@ -786,6 +786,14 @@ subagents:
   # (empty = one tier above implementer: opus if sonnet, sonnet if haiku)
   judge_model: ""
 
+  # Session-wide model CEILING for subagents (token-economy-dispatch Phase
+  # 5.2). Empty (default) = no ceiling. When set (e.g. "claude-sonnet-4-5"),
+  # suite-owned CLI spawn wrappers export CLAUDE_CODE_SUBAGENT_MODEL to the
+  # sessions THEY launch — a spend cap on every subagent those sessions
+  # spawn. Class C: a human sets it; the agent never writes it and never
+  # infers one.
+  model_ceiling: ""
+
   # Maximum number of parallel subagent invocations
   # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
   max_parallel: 3
@@ -1182,6 +1190,34 @@ hooks:
   injection_scan:
     enabled: false
 
+  # Stop-slot turn-end gate (road-to-conformance-round5 Phase 3). Default-OFF,
+  # and it is the only concern in this file that can REFUSE a turn-end rather
+  # than a tool call — so it soaks behind an explicit opt-in before it binds.
+  #
+  # Round 5 measured what it is for: both BLOCKING carriers reached zero
+  # violations, neither ADVISORY carrier did, and 19 wrong-language replies
+  # survived a pin that had fired 26-35 seconds earlier. A reminder at higher
+  # frequency is the same failed mechanism running more often; a check at
+  # delivery that can say no is a different one.
+  #
+  # enabled     — master switch. false = the concern is a no-op costing one
+  #               settings read per turn-end.
+  # promissory  — detector A: the closing paragraph promises work not yet
+  #               performed while asking the user nothing (20 measured).
+  # language    — detector B: the user-visible prose is not in the pinned
+  #               language, with code, quotes, paths and identifiers already
+  #               excluded (19 measured).
+  #
+  # Both detectors default ON *within* the master switch, so opting in needs
+  # one line, and either can be silenced without editing the hook manifest.
+  # A refused turn continues in the same turn and is never refused twice —
+  # re-entrancy is `stop_hook_active` plus a marker keyed on the last user
+  # message, never on the reply.
+  turn_end_gate:
+    enabled: false
+    promissory: true
+    language: true
+
   # PreToolUse RTK-wrap nudge (token-saving Phase 3). Default-OFF. When enabled
   # AND `rtk` is on PATH (a live probe — not a self-reported flag), warns (exit
   # 2, never blocks) "re-run wrapped with rtk" before a single verbose CLI

package/src/config/dispatch-economy-metrics.json

@@ -0,0 +1,61 @@
+{
+    "_comment": "Registered metrics for road-to-token-economy-dispatch Phase 1 (registered BEFORE any reduction lever ships — the budget-ownership discipline of hook-latency-budget.json / preamble-payload-budget.json). Baseline anchor: road-to-cache-economy census 2026-07-30 (median subagent cold start 235.5k tokens written-or-uncached, C-1 cold-start dominance 69.7%). Thresholds are the roadmap's committed numbers; changing one is a PR citing evidence, never a drive-by edit.",
+    "schema_version": 1,
+    "registered_at": "2026-08-10",
+    "owner": "maintainer",
+    "review_by": "2026-11-10",
+    "metrics": {
+        "dispatch_floor": {
+            "definition": "Median init_tokens per role (worker, reviewer) and the COST-shaped init/work ratio per dispatched leg. init_tokens = billable_input of the leg's FIRST assistant record (raw — comparable to the cache-economy 235.5k baseline); work_tokens = leg total billable_input minus init_tokens. The RATIO is computed on weighted input units (read 0.1x, 5m write 1.25x, 1h write 2.0x — _lib/cc_transcript.ts weightedInputUnits), NOT raw billable_input: raw counts every later turn's cache-read re-transmission at full weight, which makes the 'more spent loading than working' threshold unmeetable by construction (measured live 2026-08-10: raw ratio 0.02 on the same legs). billable_input = input_tokens + cache_read_input_tokens + cache_creation_input_tokens (never usage.input_tokens alone).",
+            "source": "Primary: transcript ledger via src/scripts/_lib/cc_transcript.ts (per-agentId legs, message.id+requestId dedupe). Secondary: audit-log orchestration lines carrying init_tokens/work_tokens with floor_provenance=measured.",
+            "role_attribution": "HONEST LIMITATION until the role axis (Phase 2) ships: transcripts carry no session role, so all subagent legs report as role=worker; reviewer legs are attributed from audit-line agent_combo where present. The report states which attribution produced each number.",
+            "thresholds": {
+                "projection_mandatory_ratio": 1.0,
+                "_projection_mandatory": "sustained median init/work ratio > 1.0 for rung-1 workers over a review window makes Phase 3 (worker thin projection) mandatory, not optional",
+                "success_ratio_after_projection": 0.15,
+                "_success": "median ratio < 0.15 after Phase 3 ships is the roadmap's registered success criterion"
+            },
+            "baseline": {
+                "cold_start_median_tokens": 235500,
+                "cold_start_write_volume_share_pct": 69.7,
+                "at": "2026-07-30",
+                "source": "road-to-cache-economy first-party measurement (14-day window, host CC 2.1.220); re-measure on the post-9.29 tree is Phase 1's first report run"
+            }
+        },
+        "return_channel": {
+            "definition": "Orchestrator context growth per dispatch (roadmap Phase 6.3): serialized chars of the tool result returned into the parent context (return_channel_chars on sync completions, hook-carried). The failure this number exists to catch: the isolation win refunded through the return channel.",
+            "source": "orchestration_record_hook.ts on post_tool_use Agent/Task completions; a count derived from the result object, never its content.",
+            "thresholds": {
+                "envelope_cap_chars": 12000,
+                "_cap": "the committed MAX_ENVELOPE_CHARS from _lib/subagent_response.ts — a median return above it over the review window means transcript-shaped returns are flowing back and the envelope discipline is not holding"
+            }
+        },
+        "projection_quality": {
+            "definition": "Kill criterion for the worker thin projection (roadmap Phase 3.4, REGISTERED before the projection exists): worker verify-fail rate on projected sessions vs the pre-projection baseline.",
+            "source": "Orchestration lines' dispatch_outcome + verify_mode on role-marked sessions, compared against the same window pre-projection.",
+            "thresholds": {
+                "kill_margin_pp": 5,
+                "_kill": "verify-fail rate exceeding the pre-projection baseline by more than 5 percentage points over a 2-week review window reverts the projection for that rung and the regression is published (roadmap 3.4)"
+            },
+            "status": "armed-awaiting-projection: Phase 3.1-3.3 are data-window-gated (>= 2 weeks of rules_used); this criterion binds the moment a projection ships"
+        },
+        "ask_economy": {
+            "definition": "Rung-0.5 substitution and adoption (roadmap Phase 4.4): substitution = ask-routed lines / (ask-routed + rung-1 spawn lines); adoption = ask lines with dispatch_outcome DONE / all ask lines; escalation = the caller\u0027s follow-up SPAWN lines carrying route_taken=subagent + escalated=true + origin=dispatch-economy-2026 (the ask line itself cannot know it was insufficient).",
+            "source": "Audit-log orchestration lines with route_taken='ask' (written by src/scripts/ask_transport.ts, origin tag dispatch-economy-2026).",
+            "thresholds": {
+                "escalation_kill": 0.3,
+                "_kill": "if more than 30% of asks over the review window are re-asked or escalated to spawns, the rung's signals tighten or the rung dies — by evidence, in a PR (roadmap 4.4)"
+            }
+        },
+        "rules_efficiency": {
+            "definition": "rules_used / rules_carried per worker envelope (fields shipped by road-to-lean-agent-init, validated in _lib/orchestration_record.ts). Sustained low quota is simultaneously the Phase 3 cut-line evidence AND the demand-signal datum later/road-to-deferred-rule-retriever gate (2c) asks for — one measurement, two consumers.",
+            "source": "Audit-log orchestration lines (agents/runtime/state/audit/*.jsonl) where both fields are non-null.",
+            "thresholds": {
+                "low_quota_signal": 0.2,
+                "_low_quota": "a sustained median quota below 0.2 over the review window is the cut-line evidence Phase 3.1 requires (>= 2 weeks of data) and the retriever gate's demand signal"
+            }
+        }
+    },
+    "honest_null_consequence": "If the re-measured floor on the post-9.29 tree is materially smaller than the cache-economy baseline (roadmap step 1.4), phases 3-5 of road-to-token-economy-dispatch downgrade to blockers citing the null, and the null is published in docs/benchmark.md. A metric nobody re-runs by review_by is treated as the latency file's fossilization failure: the report command below is the re-verification procedure.",
+    "report_command": "./scripts-run src/scripts/dispatch_economy_report [--format text|json] [--root <transcripts>] [--audit-dir <dir>] [--max-age-days 14]"
+}

package/src/config/evaluator-budgets.json

@@ -58,11 +58,11 @@
       "deterministic": false
     },
     "cli_help_command_count": {
-      "max": 95,
-      "last_measured": 95,
-      "last_measured_at": "2026-08-08",
+      "max": 97,
+      "last_measured": 97,
+      "last_measured_at": "2026-08-10",
       "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."
+      "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."
     },
     "mcp_public_tool_count": {
       "max": 19,