@event4u/agent-config 9.31.0 → 9.33.0

package/src/scripts/_cli/cmd_doctor.ts

@@ -90,6 +90,8 @@ import * as installed_tools from '../_lib/installed_tools.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
 import { censusDuplicateScope } from '../_lib/duplicate_scope_census.js';
+import * as preamble_byte_census from '../preamble_byte_census.js';
+import * as dispatch_economy_report from '../dispatch_economy_report.js';
 import { git_common_dir } from '../_lib/git_common_dir.js';
 import * as sync_gitattributes from '../sync_gitattributes.js';
 import {
@@ -3244,6 +3246,7 @@ interface Options {
     check: string | null;
     trace_root: boolean;
     context: boolean;
+    anatomy: boolean;
     repair: string | null;
 }
 
@@ -3254,13 +3257,15 @@ const PROG = 'agent-config doctor';
 // terminal width; golden tests assert the `usage:` token + exit code only.
 const USAGE =
     `usage: ${PROG} [-h] [--project PROJECT] [--json] [--ci] [--check ID]\n` +
-    '                           [--trace-root] [--context] [--repair ID]\n';
+    '                           [--trace-root] [--context] [--anatomy]\n' +
+    '                           [--repair ID]\n';
 
 const _STORE_TRUE_FLAGS: Record<string, keyof Options> = {
     '--json': 'json',
     '--ci': 'ci',
     '--trace-root': 'trace_root',
     '--context': 'context',
+    '--anatomy': 'anatomy',
 };
 
 const _VALUE_FLAGS: Record<string, keyof Options> = {
@@ -3283,6 +3288,7 @@ function _parse(argv: string[]): Options {
         check: null,
         trace_root: false,
         context: false,
+        anatomy: false,
         repair: null,
     };
 
@@ -3408,6 +3414,65 @@ function _run_context(opts: Options): number {
     return 0;
 }
 
+/**
+ * `--anatomy` — the injection anatomy, rendered from measurements that already
+ * exist. Composes `preamble_byte_census` (what occupies the always-loaded
+ * preamble) with `dispatch_economy_report` (what the dispatch legs cost). It
+ * takes NO new measurement and adds no threshold: both sources are advisory
+ * reports and stay advisory here.
+ *
+ * Neither module runs anything at import time — `preamble_byte_census` gained
+ * the `__AGENT_CONFIG_BUNDLE__` guard for exactly this import, since inside the
+ * `build:cli-delegate` bundle its old entry check would have matched whenever
+ * this command was invoked directly.
+ */
+function _run_anatomy(opts: Options): number {
+    const census = preamble_byte_census;
+    const economy = dispatch_economy_report;
+
+    const byteCensus = census.buildReport(census.parseArgs([]));
+
+    // The economy half reads transcripts and a registration file; either can be
+    // absent on a consumer machine. An absent half is reported as absent, never
+    // as a zero — a fabricated zero is the failure both source reports already
+    // refuse to make.
+    let economyReport: ReturnType<typeof economy.buildReport> | null = null;
+    let economyError: string | null = null;
+    try {
+        economyReport = economy.buildReport({
+            root: economy.DEFAULT_PROJECTS_ROOT,
+            auditDir: path.join(process.cwd(), economy.DEFAULT_AUDIT_DIR),
+            maxAgeDays: 14,
+        });
+    } catch (err) {
+        economyError = err instanceof Error ? err.message : String(err);
+    }
+
+    if (opts.json) {
+        print(
+            _jsonDumpsIndentAscii(
+                {
+                    preamble_byte_census: byteCensus,
+                    dispatch_economy: economyReport,
+                    dispatch_economy_unavailable: economyError,
+                } as unknown as Dict,
+                2,
+            ),
+        );
+        return 0;
+    }
+
+    print('── injection anatomy ─────────────────────────────────────────');
+    print(census.renderText(byteCensus));
+    print('');
+    print(
+        economyReport !== null
+            ? economy.renderText(economyReport)
+            : `dispatch-economy report unavailable: ${economyError}`,
+    );
+    return 0;
+}
+
 function _run_repair(opts: Options): number {
     const target = opts.repair;
     if (target === 'wizard-state') {
@@ -3464,6 +3529,9 @@ function main(argv: string[] | null = null): number {
     if (opts.context) {
         return _run_context(opts);
     }
+    if (opts.anatomy) {
+        return _run_anatomy(opts);
+    }
     let project_root: string;
     let origin: string;
     try {

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -38,6 +38,7 @@ import {
     CAPSULE_SCHEMA_VERSION,
     validateRecycleEnvelope,
 } from '../_lib/subagent_capsule.js';
+import { collectGrounding } from '../_lib/envelope_grounding.js';
 import { atomic_write_json } from '../hooks/state_io.js';
 
 export interface RecycleResult {
@@ -61,6 +62,9 @@ export function templateEnvelope(): Record<string, unknown> {
         open_worker_envelopes: [],
         artifact_paths: ['<path to a deliverable / note / evidence file>'],
         assumptions: [],
+        next_task: '<the ONE task this envelope is written for — select content for it>',
+        suggested_skills: ['<skill the successor should invoke>'],
+        failed_approaches: ['<tried X, failed because Y — or the single entry "none">'],
     };
 }
 
@@ -69,6 +73,7 @@ interface ParsedArgv {
     message?: string;
     file?: string;
     template?: boolean;
+    verify?: boolean;
 }
 
 export function parseArgv(argv: readonly string[]): ParsedArgv {
@@ -77,6 +82,8 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
         const a = argv[i] as string;
         if (a === '--template') {
             parsed.template = true;
+        } else if (a === '--verify') {
+            parsed.verify = true;
         } else if (a === '--file') {
             const value = argv[i + 1];
             if (!value) return { ok: false, message: '--file requires a path' };
@@ -98,7 +105,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
  */
 export function runSessionRecycle(
     input: string,
-    opts: { cwd: string; now?: Date },
+    opts: { cwd: string; now?: Date; verify?: boolean },
 ): RecycleResult {
     const out: string[] = [];
     const err: string[] = [];
@@ -123,6 +130,27 @@ export function runSessionRecycle(
     }
     if (envelope['workspace'] === undefined) envelope['workspace'] = projectRoot;
 
+    // Scripted grounding (Phase 3.3): the factual fields are READ, never
+    // composed. A model-written branch is a claim; this is a reading. The
+    // composer cannot override them — a "next_task" it got wrong is a
+    // proposal, a "head" it got wrong is a silent stale resume.
+    const grounding = collectGrounding(projectRoot);
+    // Drop the composer's factual keys UNCONDITIONALLY first. Guarding each
+    // assignment on `!== null` would leave a model-composed branch or head
+    // standing whenever the git read fails — the consumer would then compare
+    // a fabricated anchor against the real tree and produce either false
+    // drift or, worse, false silence. An unreadable fact is absent, never
+    // inherited from the composer.
+    for (const key of ['repo_identity', 'branch', 'head', 'status_summary', 'last_verify', 'uncommitted_paths']) {
+        delete envelope[key];
+    }
+    if (grounding.repo_identity !== null) envelope['repo_identity'] = grounding.repo_identity;
+    if (grounding.branch !== null) envelope['branch'] = grounding.branch;
+    if (grounding.head !== null) envelope['head'] = grounding.head;
+    if (grounding.status_summary !== null) envelope['status_summary'] = grounding.status_summary;
+    if (grounding.last_verify !== null) envelope['last_verify'] = grounding.last_verify;
+    envelope['uncommitted_paths'] = grounding.uncommitted_paths;
+
     const violations = validateRecycleEnvelope(envelope);
     if (violations.length > 0) {
         return {
@@ -146,6 +174,15 @@ export function runSessionRecycle(
         };
     }
 
+    // `--verify` stops HERE: every rejection above has already run, and the
+    // only thing skipped is the write. Validating through a different path
+    // than the one that writes would make the check a second implementation
+    // to keep in sync — the failure this suite refuses elsewhere.
+    if (opts.verify === true) {
+        out.push(`recycle envelope VALID — ${bytes} bytes, not written (--verify).`);
+        return { code: 0, out, err };
+    }
+
     const target = path.join(projectRoot, RECYCLE_ENVELOPE_REL);
     try {
         atomic_write_json(target, envelope);
@@ -168,9 +205,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const parsed = parseArgv(argv);
     if (!parsed.ok) {
         const usage = [
-            'usage: agent-config session:recycle [--file <envelope.json>] [--template]',
+            'usage: agent-config session:recycle [--file <envelope.json>] [--template] [--verify]',
             '  --file <path>   read the envelope JSON from a file (default: stdin)',
             '  --template      print a skeleton envelope and exit',
+            '  --verify        validate only — same rejections, no write',
         ].join('\n');
         if (parsed.message === 'usage') {
             process.stdout.write(`${usage}\n`);
@@ -200,7 +238,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
 
-    const result = runSessionRecycle(input, { cwd: process.cwd() });
+    const result = runSessionRecycle(input, {
+        cwd: process.cwd(),
+        ...(parsed.verify === true ? { verify: true } : {}),
+    });
     for (const line of result.out) process.stdout.write(`${line}\n`);
     for (const line of result.err) process.stderr.write(`${line}\n`);
     return result.code;

package/src/scripts/_cli/handoff_generate.ts

@@ -35,6 +35,19 @@ export const WORD_CAP = 1200;
 const SNIPPET_CHARS = 200;
 const DONE_SNIPPET_CHARS = 400;
 const MAX_ERRORS = 5;
+/**
+ * Per-error cap. Above `SNIPPET_CHARS` because an error string is kept
+ * verbatim so it stays greppable — but deliberately not far above.
+ *
+ * The section competes for a fixed word cap whose trim pops the NEWEST entry
+ * first, and the newest failure is the one a successor needs. Enlarging each
+ * entry therefore makes that pre-existing trim order bite more often. 400 is
+ * twice the old truncation — enough to carry a real error line whole — while
+ * keeping the five-entry section within roughly a sixth of the cap. The
+ * pop()-newest ordering is pre-existing and is not this change's to alter;
+ * this bound is what keeps the change from amplifying it.
+ */
+const MAX_ERROR_CHARS = 400;
 const MAX_DECISIONS = 5;
 const MAX_FILES = 15;
 
@@ -325,11 +338,23 @@ export function build_handoff(
     );
 
     // Errors + fixes — failure-pattern turns, oldest→newest, last 5.
+    //
+    // Precision rule (Phase 3.1): the error string is carried VERBATIM. It
+    // used to be `_snippet`-ed like every other section, which truncates
+    // mid-string — and a truncated error cannot be grepped, matched against a
+    // tracker, or recognised when it recurs, which is the only reason to
+    // carry it at all. So the FAILURE-matching line is taken whole (capped
+    // only against an absurd single line) instead of the turn being cut at an
+    // arbitrary offset.
     const errors = _redact_items(
         toolish
             .filter((t) => FAILURE_RE.test(t.text))
             .slice(-MAX_ERRORS)
-            .map((t) => _snippet(`${t.tool ? `${t.tool}: ` : ''}${t.text}`, SNIPPET_CHARS)),
+            .map((t) => {
+                const line = t.text.split('\n').find((l) => FAILURE_RE.test(l))?.trim() ?? t.text.trim();
+                const prefix = t.tool ? `${t.tool}: ` : '';
+                return `${prefix}${line}`.slice(0, MAX_ERROR_CHARS);
+            }),
     );
 
     // Key decisions — decision-pattern assistant turns, last 5.
@@ -396,6 +421,16 @@ export function build_handoff(
         }
         for (const s of sections) {
             lines.push('', `## ${s.title}`, '');
+            if (s.title === 'Resume pointer') {
+                // Precision rules (Phase 3.1), rendered where the successor
+                // reads them rather than filed in a doc nobody opens.
+                lines.push(
+                    '> Precision contract: identify code by signature or `path:line`, never by',
+                    '> description; quote error strings verbatim; give every resume step its',
+                    '> expected outcome, so "done" is checkable rather than felt.',
+                    '',
+                );
+            }
             if (s.items.length === 0) {
                 if (s.verbatim && verbatim.withheldLines > 0) {
                     lines.push(`- [${verbatim.withheldLines} line(s) withheld by privacy floor]`);

package/src/scripts/_cli/handoff_sessions.ts

@@ -19,6 +19,11 @@
  * De-dup: native-store sessions whose platform id maps (via
  * `derive_session_tag`) to a chat-history bucket are dropped — the
  * chat-history entry wins.
+ *
+ * Two exclusions then apply to the merged list (road-to-cost-parity-3
+ * Phase 1): the ISSUING session, by exact id and never heuristically, and
+ * every candidate holding nothing worth resuming (`is_substantive`). Both
+ * fail OPEN — an unknown lists.
  */
 
 import * as fs from 'node:fs';
@@ -26,10 +31,35 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 
 import { derive_session_tag, list_sessions, read_entries } from '../chat_history.js';
+import { eolSessionKey, readEolCounters, type StoredEolCounters } from '../_lib/session_eol.js';
 
 export const DEFAULT_CAP = 15;
+/**
+ * Per-source over-fetch factor. The exclusions run after the per-source cap,
+ * so fetching exactly `cap` lets a filtered candidate consume a slot no
+ * eligible session can reclaim. 3× is a backfill margin, not a measurement:
+ * on the observed store 10 of 217 sessions are filtered (~5%), so 3× covers
+ * that comfortably while keeping the per-file scan bounded.
+ */
+const FETCH_OVERSHOOT = 3;
 const SUMMARY_SNIPPET_CHARS = 120;
 
+/**
+ * Committed substantive-content floor, in parsed transcript tokens (billable
+ * input of the last main-chain assistant record, per `cc_transcript.ts`) — the
+ * OR-arm for a session that produced real discussion without ever calling a
+ * tool.
+ *
+ * Derivation (`agents/evidence/analysis/handoff-substantive-threshold.md`,
+ * 217 sessions of the local Claude store, 2026-08-10): 206 of the 207 sessions
+ * carrying an assistant record also carry a `tool_use` block, so this arm
+ * serves the ~0.5 % tail and the hosts whose transcripts log no tool blocks at
+ * all. 10 000 sits **25× below** the p10 of real working sessions (254 939),
+ * so it cannot hide one, and above a single trivial exchange. Changing it is a
+ * PR citing evidence, never a drive-by edit.
+ */
+export const SUBSTANTIVE_TOKEN_FLOOR = 10_000;
+
 export type HandoffSource = 'chat-history' | 'claude-transcript' | 'codex-session';
 
 export interface HandoffSession {
@@ -55,6 +85,21 @@ export interface ListOptions {
     codexSessionsRoot?: string;
     /** Max sessions per source AND in the merged result. Default 15. */
     cap?: number;
+    /**
+     * The ISSUING session's id — excluded from the result unconditionally.
+     *
+     * Default: `AGENT_SESSION_ID` (this package's own envelope convention),
+     * else `CLAUDE_CODE_SESSION_ID`. The second name is **measured, not
+     * guessed**: a live Claude Code session (host 2026-08-10) exports
+     * `CLAUDE_CODE_SESSION_ID` into every Bash tool call and its value is the
+     * session uuid that also names the transcript file — a plausible-looking
+     * `CLAUDE_SESSION_ID` is not exported and would leave this filter inert.
+     *
+     * Pass `null` to disable (a caller that genuinely is not a session).
+     */
+    selfSessionId?: string | null;
+    /** Workspace root holding `agents/runtime/state/session-eol/`. Default: `cwd`. */
+    workspaceRoot?: string;
 }
 
 /** Mirrors the Claude Code project-dir naming: `/` and `.` → `-`. */
@@ -408,28 +453,114 @@ function _sort_key(s: HandoffSession): string {
     return s.endedAt ?? s.startedAt ?? '';
 }
 
+/**
+ * Does this session hold anything worth resuming?
+ *
+ * `≥ 1 assistant turn AND (≥ 1 tool call OR parsed tokens ≥ the committed
+ * floor)`, read from the counts-only session-eol state.
+ *
+ * **Fail-open, deliberately** (Phase 1.2): absent, unreadable or mis-shaped
+ * state LISTS the candidate rather than filtering it, and a `tool_calls` key
+ * missing from a state file written before that counter existed reads as
+ * *unknown*, never as zero. A wrongly listed candidate is noise the user
+ * scrolls past; a wrongly hidden one is data loss they cannot even see.
+ */
+export function is_substantive(counters: StoredEolCounters | null): boolean {
+    if (counters === null) return true;
+    // Every "unknown" below is a NUMBER test, not an `=== undefined` test.
+    // Absent, null and NaN are all unknown, and each one reaches this code by
+    // a real path: a state file written before the counter existed is absent,
+    // `JSON.stringify` turns NaN into null on the way to disk, and a
+    // half-written file yields a parseable object with missing keys. Reading
+    // any of them as "counted zero" hides a session that did real work.
+    if (!Number.isFinite(counters.assistant_records)) return true;
+    if ((counters.assistant_records as number) < 1) return false;
+    if (!Number.isFinite(counters.tool_calls)) return true;
+    if ((counters.tool_calls as number) >= 1) return true;
+    if (!Number.isFinite(counters.final_context_tokens)) return true;
+    return (counters.final_context_tokens as number) >= SUBSTANTIVE_TOKEN_FLOOR;
+}
+
+function _derive_tag(id: string): string | null {
+    try {
+        return derive_session_tag(id);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The state file is keyed on the RAW session id (or transcript path) the hook
+ * saw. A chat-history bucket carries only the derived tag, so the native scan
+ * — which holds both — supplies the raw identity for those buckets.
+ */
+function _counters_for(
+    session: HandoffSession,
+    byTag: Map<string, HandoffSession>,
+    workspaceRoot: string,
+): StoredEolCounters | null {
+    const native = session.source === 'chat-history' ? byTag.get(session.id) : session;
+    const candidates = [
+        ...(session.source === 'chat-history' ? [] : [session.id]),
+        native?.id,
+        native?.transcriptPath,
+    ];
+    for (const candidate of candidates) {
+        if (!candidate) continue;
+        const counters = readEolCounters(workspaceRoot, eolSessionKey(candidate));
+        if (counters !== null) return counters;
+    }
+    return null;
+}
+
 /**
  * Unified newest-first session list. Native-store sessions whose platform
  * id maps to an existing chat-history bucket are dropped (chat-history is
  * the primary source).
+ *
+ * Two exclusions apply to the merged list: the ISSUING session, by exact id
+ * (never heuristically — a heuristic here hides a session the user wanted),
+ * and every candidate `is_substantive` rejects.
  */
 export function list_handoff_sessions(opts: ListOptions = {}): HandoffSession[] {
     const cap = opts.cap ?? DEFAULT_CAP;
+    const workspaceRoot = opts.workspaceRoot ?? opts.cwd ?? process.cwd();
+    const selfId =
+        opts.selfSessionId === null
+            ? null
+            : (opts.selfSessionId ??
+              process.env.AGENT_SESSION_ID ??
+              process.env.CLAUDE_CODE_SESSION_ID ??
+              null);
+    const selfTag = selfId ? _derive_tag(selfId) : null;
+
     const primary = _chat_history_sessions(opts);
     const knownTags = new Set(primary.map((s) => s.id));
 
-    const native = [
-        ..._claude_transcript_sessions(opts, cap),
-        ..._codex_sessions(opts, cap),
-    ].filter((s) => {
-        try {
-            return !knownTags.has(derive_session_tag(s.id));
-        } catch {
-            return true;
-        }
+    // Over-fetch per source, because the two filters below run AFTER it and
+    // the issuing session is by construction among the newest — with a
+    // per-source cap of exactly `cap`, the caller always burns a slot and
+    // every filtered empty session burns another, so a substantive session
+    // just outside the window is silently dropped instead of backfilled.
+    // That is the hidden-session direction Phase 1.2 calls data loss.
+    const fetchCap = cap * FETCH_OVERSHOOT;
+    const nativeAll = [
+        ..._claude_transcript_sessions(opts, fetchCap),
+        ..._codex_sessions(opts, fetchCap),
+    ];
+    const byTag = new Map<string, HandoffSession>();
+    for (const s of nativeAll) {
+        const tag = _derive_tag(s.id);
+        if (tag) byTag.set(tag, s);
+    }
+    const native = nativeAll.filter((s) => {
+        const tag = _derive_tag(s.id);
+        return tag === null || !knownTags.has(tag);
     });
 
     return [...primary, ...native]
+        .filter((s) => s.id !== selfId && (selfTag === null || s.id !== selfTag))
+        .filter((s) => is_substantive(_counters_for(s, byTag, workspaceRoot)))
         .sort((a, b) => (_sort_key(a) < _sort_key(b) ? 1 : _sort_key(a) > _sort_key(b) ? -1 : 0))
         .slice(0, cap);
 }

package/src/scripts/_dispatch.bash

@@ -130,7 +130,7 @@ Tier 1 — power-user (release shape, audit, migration):
                              user-authored files; persists standing consent
                              (install.auto_converge) on first use.
                              Flags: --dry-run | --yes
-  conformance:behavior       Replay local transcripts through the mechanised conformance checks
+  conformance:behavior       Replay local transcripts through the mechanised conformance checks (--why <id> traces one)
   conformance                Consumer conformance contract: doctor --ci +
                              installed-and-firing checks. Exits non-zero on
                              a failed check.
@@ -197,7 +197,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              session register). Flags: --json
   sessions:claim             Claim a roadmap for this session so other sessions skip
                              it; --release clears the claim
-  session:recycle            Validate + write the main-session recycle envelope
+  session:recycle            Validate + write the main-session recycle envelope (--verify validates only)
                              (deliberate recycle instead of auto-compact). Flags:
                              --file <json> | --template; default reads stdin
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
@@ -207,7 +207,9 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   gates                      Open decisions that need you, rendered as actions —
                              roadmap blockers filtered by owner, most-unblocking
                              first. Flags: --all (include maintainer/external),
-                             --json
+                             --json, --reply (reply-close form: the one blocking
+                             decision in full, the rest as a count; prints
+                             nothing when none are yours)
   capabilities:index         Regenerate CAPABILITIES.yaml — the package coverage index
                              (capability area → coverage → backing skills/commands → gaps).
                              Pass --check to fail if stale (for CI). Reads src/ (package repo).

package/src/scripts/_lib/carrier_divergence.ts

@@ -22,8 +22,16 @@
  * provenance-only difference survives even a perfect version alignment. Keeping
  * it apart from class 3 is what turns a bare "0 identical twins" into an answer:
  * `provenanceOnly == shared` means aligning versions would buy nothing, and
- * `bodyDiff > 0` means the two carriers are delivering different text — the only
- * class where a reader has to act.
+ * `bodyDiff > 0` means the two carriers are delivering different bytes.
+ *
+ * `bodyDiff > 0` is NOT the same as "a reader has to act", and an earlier version
+ * of this paragraph said it was. Measured 2026-08-10: all 109 shared rules
+ * classified `bodyDiff` and NONE of them differed in prose. The reader-facing
+ * split lives in `report_carrier_divergence`, which subdivides this class into
+ * prose divergence (act), a `paths:`-scope disagreement (act — it changes WHEN a
+ * rule loads), and a metadata-only difference (do not act). The three-way split
+ * below stays three-way on purpose: it is the DEDUP predicate, and every class
+ * here is a real byte difference.
  *
  * NOT A LICENCE TO DEDUP. Classifying a pair `provenance-only` says the bodies
  * match; it does NOT say the rule is safe to drop from one carrier. Byte-identity
@@ -81,24 +89,47 @@ export function comparePair(a: Buffer, b: Buffer): PairVerdict {
     return 'body-diff';
 }
 
+/** One rule file, split at its frontmatter fence. */
+export interface FrontmatterSplit {
+    /** `true` only when a terminated `---` fence was actually found. */
+    hadFrontmatter: boolean;
+    /** The fence block WITHOUT its delimiters, or `''` when there is none. */
+    frontmatter: string;
+    /** Everything after the fence — the prose the host delivers. */
+    body: string;
+}
+
 /**
- * Drop a leading YAML frontmatter block, returning the prose the host actually
- * delivers.
+ * THE fence parser. One definition, for the reason the header gives: a second
+ * copy is how two surfaces drift into disagreeing about what frontmatter is.
  *
- * A file with no `---` fence, or an unterminated one, is returned unchanged —
- * the same tolerance `report_carrier_divergence`'s own `type:` reader applies,
- * because a malformed fence must not silently swallow a rule's whole text.
+ * An absent or UNTERMINATED fence yields `hadFrontmatter: false` and the whole
+ * text as body. That is deliberate and it is the safe direction: a malformed
+ * fence must not silently swallow a rule's governed text. Note this is the
+ * OPPOSITE of what a naive `type:` reader does — treating the whole file as
+ * frontmatter — and that asymmetry was a live inconsistency between this
+ * function and `report_carrier_divergence._ruleType` until the latter was moved
+ * onto this parser.
  */
-export function stripFrontmatter(text: string): string {
-    if (!text.startsWith('---')) return text;
+export function splitFrontmatter(text: string): FrontmatterSplit {
+    if (!text.startsWith('---')) return { hadFrontmatter: false, frontmatter: '', body: text };
     const end = text.indexOf('\n---', 3);
-    if (end === -1) return text;
+    if (end === -1) return { hadFrontmatter: false, frontmatter: '', body: text };
     const afterFence = text.indexOf('\n', end + 1);
-    return afterFence === -1 ? '' : text.slice(afterFence + 1);
+    return {
+        hadFrontmatter: true,
+        frontmatter: text.slice(3, end),
+        body: afterFence === -1 ? '' : text.slice(afterFence + 1),
+    };
+}
+
+/** The prose a rule file delivers, with any frontmatter block removed. */
+export function stripFrontmatter(text: string): string {
+    return splitFrontmatter(text).body;
 }
 
 /**
- * Do the two copies carry the same governed PROSE, ignoring frontmatter?
+ * Is the ONLY difference between these two copies inside the frontmatter block?
  *
  * WHY THIS IS SEPARATE FROM `comparePair`, AND MUST STAY SEPARATE
  * --------------------------------------------------------------
@@ -109,23 +140,63 @@ export function stripFrontmatter(text: string): string {
  * strict. `measure_scope_dedup` asks exactly that question and its arithmetic
  * stays untouched.
  *
- * This answers the different, reader-facing question `report_carrier_divergence`
- * asks: *must a human act on this pair*. Measured 2026-08-10 over the live
- * carriers at commit `a5b2f4cb7`: 109 shared rules, **0** byte-identical, **109**
- * classified `body-diff` — and after this strip, **0** of the 109 differ in
- * prose. The whole divergence was the metadata block. Reporting that as body
- * divergence manufactures the one class the report tells a reader to act on,
- * which is precisely the failure `compareCarriers` already refuses to commit for
- * an unreadable copy.
- *
- * Edge trimming only, on purpose: the frontmatter fence leaves the two sides one
- * leading newline apart, and that is not a content difference. Internal
- * whitespace and line endings are NOT normalized — a CRLF-vs-LF body stays a
- * prose difference, so this stays no softer than the dedup predicate on the text
- * the host reads.
+ * WHAT IT PROVES, EXACTLY — AND WHY NOT `trim()`
+ * ---------------------------------------------
+ * Two conditions, both required:
+ *
+ *   1. at least one side actually HAD a frontmatter block. Without this the
+ *      predicate would answer "the prose matches" for a pair with no frontmatter
+ *      anywhere, and the caller would print "differs only in frontmatter" about
+ *      a difference that is not in any frontmatter.
+ *   2. the bodies match after removing LEADING newlines only. The fence
+ *      necessarily leaves the stripped side one newline ahead, so that one
+ *      character is a parsing artefact. A `trim()` would additionally absorb a
+ *      TRAILING difference, which is a real byte difference no fence explains —
+ *      and it was measured to be unnecessary: all 109 live pairs on 2026-08-10
+ *      matched on leading-only, 0 needed a trailing trim.
+ *
+ * Nothing else is normalized. Internal whitespace and line endings stay
+ * significant, so a CRLF-vs-LF body is still a prose difference and this stays
+ * no softer than the dedup predicate on the text the host reads.
  */
 export function proseEqual(a: string, b: string): boolean {
-    return stripFrontmatter(a).trim() === stripFrontmatter(b).trim();
+    const sa = splitFrontmatter(a);
+    const sb = splitFrontmatter(b);
+    if (!sa.hadFrontmatter && !sb.hadFrontmatter) return false;
+    const leading = /^\n+/;
+    return sa.body.replace(leading, '') === sb.body.replace(leading, '');
+}
+
+/**
+ * The `paths:` block of a rule's frontmatter, normalized, or `null` when absent.
+ *
+ * `paths` is the ONE frontmatter key this host reads
+ * (`agents/evidence/analysis/claude-code-rules-dir-contract.md`), and it decides
+ * WHEN a rule loads: with it, the rule fires when a matching file is read and is
+ * not re-injected after `/compact`; without it, the rule loads unconditionally
+ * at launch. So two carriers that disagree here deliver the same text on
+ * different schedules, which a reader must act on even though the prose is
+ * identical. Measured 2026-08-10: 24 of the 109 shared rules carry `paths:` in
+ * the project copy and NONE in the global copy, so on a machine with both the
+ * always-on global copy defeats the project copy's scoping for all 24.
+ *
+ * Normalization is deliberately shallow — the key line plus its indented
+ * continuation, whitespace-collapsed. It answers "do these two agree" and is not
+ * a YAML parser; a reordered list reads as a difference, which is the
+ * conservative direction for a report that asks a human to look.
+ */
+export function frontmatterPaths(text: string): string | null {
+    const { hadFrontmatter, frontmatter } = splitFrontmatter(text);
+    if (!hadFrontmatter) return null;
+    const lines = frontmatter.split('\n');
+    const start = lines.findIndex((l) => /^paths:/.test(l));
+    if (start === -1) return null;
+    const block = [lines[start] as string];
+    for (const line of lines.slice(start + 1)) {
+        if (/^\s/.test(line) && line.trim() !== '') block.push(line);
+        else break;
+    }
+    return block.map((l) => l.trim()).join(' ');
 }
 
 export interface RuleDirCensus {