@event4u/agent-config 9.32.0 → 9.34.0

package/src/scripts/discovery_graph.ts

@@ -23,6 +23,18 @@
  *   build   [--manifest P] [--out P] [--force]     (re)build the graph cache
  *   affected <artefact> [--depth N] [--manifest P]  relation-filtered BFS
  *   explain  <concept>   [--budget N] [--manifest P] seed + 2-hop + budget-cut
+ *   orphans [--manifest P]                          zero-inbound artefact REPORT
+ *
+ * `orphans` is a **report, never a gate** (road-to-inbox-harvest-2026-08-b
+ * estate-lifecycle 3.2): the relation set above is five typed edges and sees a
+ * strictly narrower graph than `check_references.ts`, so a prose-only
+ * cross-reference produces no edge and a reachable artefact reads as
+ * zero-inbound. The false-positive class is provably non-empty, which is why
+ * the command exits 0 on hits and points at review rather than removal.
+ *
+ * Per-pass `stats` accompany the graph: each edge-extraction pass is wrapped in
+ * its own `try`, so one malformed field records `"error"` for that pass instead
+ * of failing the whole build silently or loudly.
  *
  * Exit codes: 0 ok, 1 not-found, 2 usage error, 3 internal error.
  */
@@ -33,14 +45,35 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { reportScanned } from './_lib/scan_scope.js';
 import { scanCached } from './_lib/stat_index.js';
 
 const PROG = 'discovery_graph.ts';
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 // discovery-graph-v<N>.json → version namespace in the path (versioned-cache B5b).
+// The FILE name stays v1 on purpose: `complexity_report.ts:234` reads this exact
+// path. `schema_version` inside the payload carries the shape version instead,
+// and `getGraph` forces a rebuild when a cached payload predates it.
 export const GRAPH_CACHE = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'discovery-graph-v1.json');
 
+/** Payload shape version. Bumped when `Graph` gains or changes a field. */
+export const GRAPH_SCHEMA_VERSION = 2;
+
+/**
+ * Prefixes that mark a node as SYNTHETIC — a pack or workspace container the
+ * graph invents, not an artefact on disk. Artefact ids are bare repo-relative
+ * paths (`idOf`), so the two live in one id space; anything reasoning over
+ * "artefacts" must exclude these explicitly rather than assume no path ever
+ * starts with `pack:`.
+ */
+export const SYNTHETIC_NODE_PREFIXES = ['pack:', 'workspace:'] as const;
+
+/** True when `id` names a pack/workspace container rather than an artefact. */
+export function isSyntheticNode(id: string): boolean {
+    return SYNTHETIC_NODE_PREFIXES.some((p) => id.startsWith(p));
+}
+
 export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
 export interface Edge {
     from: string;
@@ -48,11 +81,14 @@ export interface Edge {
     rel: string;
     confidence: EdgeConfidence;
 }
+/** Per-pass edge counts; `"error"` marks a pass that threw and produced nothing. */
+export type GraphStats = Record<string, number | 'error'>;
 export interface Graph {
     schema_version: number;
     source_checksum: string;
     nodes: string[];
     edges: Edge[];
+    stats: GraphStats;
 }
 
 interface Artefact {
@@ -94,43 +130,92 @@ export function loadManifest(manifestPath: string | null): Manifest {
     return parsed;
 }
 
+/** The five independent edge-extraction passes, in stats-key order. */
+const _PASSES = ['supersedes', 'routes_to', 'references_adr', 'member_of_pack', 'member_of_workspace'] as const;
+type PassName = (typeof _PASSES)[number];
+
 /** Deterministic edge extraction from the manifest's structured fields. */
 export function buildGraph(manifest: Manifest): Graph {
     const nodeSet = new Set<string>();
     const edges: Edge[] = [];
     const idOf = (a: Artefact): string => a.path;
 
+    // Per-pass counters + error containment. One malformed field must not cost
+    // the other four passes: a pass that throws is recorded as `"error"` and
+    // contributes no edges, instead of aborting the build or — worse — being
+    // swallowed into a silently smaller graph nobody can distinguish from a
+    // correct one.
+    const counts = new Map<PassName, number>(_PASSES.map((p) => [p, 0]));
+    const failed = new Set<PassName>();
+    const run = (pass: PassName, fn: () => number): void => {
+        if (failed.has(pass)) return;
+        try {
+            counts.set(pass, (counts.get(pass) ?? 0) + fn());
+        } catch {
+            failed.add(pass);
+        }
+    };
+
     for (const a of manifest.artefacts) {
         const id = idOf(a);
         nodeSet.add(id);
-        for (const r of _asStrings(a.replaces)) {
-            edges.push({ from: id, to: r, rel: 'supersedes', confidence: 'EXTRACTED' });
-            edges.push({ from: r, to: id, rel: 'superseded_by', confidence: 'EXTRACTED' });
-            nodeSet.add(r);
-        }
-        for (const t of _asStrings(a.routes_to)) {
-            edges.push({ from: id, to: t, rel: 'routes_to', confidence: 'EXTRACTED' });
-            nodeSet.add(t);
-        }
-        // ADR references surfaced through any structured target field.
-        for (const t of [..._asStrings(a.replaces), ..._asStrings(a.routes_to)]) {
-            if (/(^|\/)docs\/(decisions|adr)\/ADR-/i.test(t) || /\bADR-\d+/.test(t)) {
-                edges.push({ from: id, to: t, rel: 'references_adr', confidence: 'EXTRACTED' });
+        run('supersedes', () => {
+            let n = 0;
+            for (const r of _asStrings(a.replaces)) {
+                edges.push({ from: id, to: r, rel: 'supersedes', confidence: 'EXTRACTED' });
+                edges.push({ from: r, to: id, rel: 'superseded_by', confidence: 'EXTRACTED' });
+                nodeSet.add(r);
+                n += 2;
+            }
+            return n;
+        });
+        run('routes_to', () => {
+            let n = 0;
+            for (const t of _asStrings(a.routes_to)) {
+                edges.push({ from: id, to: t, rel: 'routes_to', confidence: 'EXTRACTED' });
                 nodeSet.add(t);
+                n += 1;
             }
-        }
-        for (const p of _asStrings(a.packs)) {
-            const node = `pack:${p}`;
-            edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
-            nodeSet.add(node);
-        }
-        for (const w of _asStrings(a.workspaces)) {
-            const node = `workspace:${w}`;
-            edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
-            nodeSet.add(node);
-        }
+            return n;
+        });
+        // ADR references surfaced through any structured target field.
+        run('references_adr', () => {
+            let n = 0;
+            for (const t of [..._asStrings(a.replaces), ..._asStrings(a.routes_to)]) {
+                if (/(^|\/)docs\/(decisions|adr)\/ADR-/i.test(t) || /\bADR-\d+/.test(t)) {
+                    edges.push({ from: id, to: t, rel: 'references_adr', confidence: 'EXTRACTED' });
+                    nodeSet.add(t);
+                    n += 1;
+                }
+            }
+            return n;
+        });
+        run('member_of_pack', () => {
+            let n = 0;
+            for (const p of _asStrings(a.packs)) {
+                const node = `pack:${p}`;
+                edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
+                nodeSet.add(node);
+                n += 1;
+            }
+            return n;
+        });
+        run('member_of_workspace', () => {
+            let n = 0;
+            for (const w of _asStrings(a.workspaces)) {
+                const node = `workspace:${w}`;
+                edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
+                nodeSet.add(node);
+                n += 1;
+            }
+            return n;
+        });
     }
 
+    const stats: GraphStats = {};
+    for (const p of _PASSES) stats[p] = failed.has(p) ? 'error' : (counts.get(p) ?? 0);
+    const artefactIds = new Set(manifest.artefacts.map(idOf));
+
     // Stable, de-duplicated ordering → byte-stable output.
     const seen = new Set<string>();
     const uniq = edges.filter((e) => {
@@ -140,15 +225,28 @@ export function buildGraph(manifest: Manifest): Graph {
         return true;
     });
     uniq.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.rel.localeCompare(b.rel));
+    // Distinct EXTRACTED targets that name no artefact in the manifest. The
+    // structured fields carry LOGICAL names (`commit:in-chunks`) while node ids
+    // are repo-relative paths, so a non-zero count here means inbound degree is
+    // systematically under-counted — the fact any inverse traversal has to know
+    // before it presents a list. Measured, not assumed: see
+    // `agents/evidence/analysis/discovery-graph-inbound-degree.md`.
+    const danglingTargets = new Set(
+        uniq.filter((e) => e.confidence === 'EXTRACTED' && !artefactIds.has(e.to)).map((e) => e.to),
+    );
+    stats['dangling_targets'] = danglingTargets.size;
     const checksum =
         typeof manifest.checksum === 'string' && manifest.checksum
             ? manifest.checksum
             : 'sha256:' + createHash('sha256').update(JSON.stringify(manifest.artefacts)).digest('hex');
     return {
-        schema_version: 1,
+        schema_version: GRAPH_SCHEMA_VERSION,
         source_checksum: checksum,
         nodes: [...nodeSet].sort(),
         edges: uniq,
+        // Counts are edges EXTRACTED per pass, before the de-duplication above —
+        // so they sum to ≥ `edges.length` and stay attributable to one pass.
+        stats,
     };
 }
 
@@ -188,7 +286,39 @@ export function getGraph(manifestPath: string | null, force: boolean): Graph {
     if (manifestPath !== null) {
         return buildGraph(loadManifest(manifestPath));
     }
-    return scanCached<Graph>(GRAPH_CACHE, _sourceFiles(), () => buildGraph(loadManifest(null)), force);
+    const files = _sourceFiles();
+    const graph = scanCached<Graph>(GRAPH_CACHE, files, () => buildGraph(loadManifest(null)), force);
+    // A cache written before the current payload shape is a stale shape, not a
+    // stale signature — `scanCached` compares signatures only, so the guard is
+    // here. One forced rebuild costs a manifest pass; serving a payload missing
+    // fields the caller's type promises costs a wrong answer.
+    if (graph.schema_version !== GRAPH_SCHEMA_VERSION) {
+        return scanCached<Graph>(GRAPH_CACHE, files, () => buildGraph(loadManifest(null)), true);
+    }
+    return graph;
+}
+
+/**
+ * Artefact nodes with zero inbound EXTRACTED edges — the estate's "nothing
+ * points at this" question, as an inverse traversal of the existing edge set.
+ *
+ * Two exclusions, both load-bearing:
+ *
+ * - `member_of` is INFERRED (`packs`/`workspaces`), and every packed artefact
+ *   has one. Counting it would make almost everything look reachable via its
+ *   own pack node and reduce the report to noise.
+ * - Synthetic pack/workspace nodes are not artefacts and are never the subject
+ *   of the question.
+ *
+ * The result is a REVIEW list, never a removal list — see the module header.
+ */
+export function inboundZero(graph: Graph): string[] {
+    const withInbound = new Set<string>();
+    for (const e of graph.edges) {
+        if (e.confidence !== 'EXTRACTED') continue;
+        withInbound.add(e.to);
+    }
+    return graph.nodes.filter((n) => !isSyntheticNode(n) && !withInbound.has(n)).sort();
 }
 
 /** Relation-filtered BFS from a start node. Returns reachable nodes + hop depth. */
@@ -247,6 +377,50 @@ export function main(argv: string[]): number {
         if (sub === 'build') {
             const graph = getGraph(manifestPath, rest.includes('--force'));
             process.stdout.write(`${PROG}: graph — ${graph.nodes.length} nodes, ${graph.edges.length} edges\n`);
+            for (const [pass, n] of Object.entries(graph.stats)) {
+                process.stdout.write(`  ${pass}: ${String(n)}\n`);
+            }
+            reportScanned({
+                gate: PROG,
+                scanned: graph.nodes.length,
+                units: 'node(s)',
+                roots: ['src', 'docs/decisions', 'docs/adr'],
+            });
+            return 0;
+        }
+        if (sub === 'orphans') {
+            const graph = getGraph(manifestPath, false);
+            const hits = inboundZero(graph);
+            const dangling = graph.stats['dangling_targets'];
+            // Degraded path, NAMED rather than papered over: while EXTRACTED
+            // targets do not resolve to artefact paths, inbound degree is
+            // under-counted for every artefact and the list below is the whole
+            // estate, not a finding. Printing it anyway would be a report that
+            // looks like evidence and is not.
+            if (typeof dangling === 'number' && dangling > 0) {
+                process.stdout.write(
+                    `${PROG}: inbound degree is DEGRADED — ${String(dangling)} EXTRACTED edge target(s)\n` +
+                        'name no artefact path in the manifest (the structured fields carry logical\n' +
+                        'names, node ids are repo-relative paths). Every artefact therefore reads as\n' +
+                        `zero-inbound (${String(hits.length)} of ${String(graph.nodes.length)} nodes), which is a\n` +
+                        'property of the edge set, not of the estate. No list is printed.\n' +
+                        'See `agents/evidence/analysis/discovery-graph-inbound-degree.md`.\n',
+                );
+                return 0;
+            }
+            process.stdout.write(`zero-inbound artefacts (${hits.length} of ${graph.nodes.length} nodes):\n`);
+            for (const h of hits) process.stdout.write(`  ${h}\n`);
+            // 3.3 — the disposition line travels WITH the list, so a reader who
+            // sees only the output still sees what it licenses.
+            process.stdout.write(
+                '\nThis is a review prompt, not a removal list. The graph sees five typed\n' +
+                    'edge kinds and no prose cross-references, so a referenced artefact can\n' +
+                    'appear here; `check_references.ts` is the cross-reference gate, not this.\n' +
+                    'Sunset stays explicit and recorded in the removing commit, with no\n' +
+                    'tombstone files (`docs/governance.md` § Skill lifecycle policy), and the\n' +
+                    'shipped precedent for stale artefacts is archive-not-delete\n' +
+                    '(`src/scripts/janitor.ts:10` — never auto-sweeps).\n',
+            );
             return 0;
         }
         if (sub === 'affected') {
@@ -279,7 +453,7 @@ export function main(argv: string[]): number {
             for (const n of nodes) process.stdout.write(`  [${n.depth}] ${n.node}  (via ${n.via})\n`);
             return 0;
         }
-        process.stderr.write(`usage: ${PROG} <build|affected|explain> [args]\n`);
+        process.stderr.write(`usage: ${PROG} <build|affected|explain|orphans> [args]\n`);
         return 2;
     } catch (exc) {
         process.stderr.write(`${PROG}: error: ${String(exc)}\n`);

package/src/scripts/dispatch_economy_report.ts

@@ -54,7 +54,9 @@ const _HERE = fileURLToPath(import.meta.url);
 // 2-up resolution cache_realization_report.ts uses at the same depth).
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const REGISTRATION_FILE = path.join(REPO_ROOT, 'src', 'config', 'dispatch-economy-metrics.json');
-const DEFAULT_AUDIT_DIR = path.join('agents', 'runtime', 'state', 'audit');
+/** Exported so `doctor --anatomy` resolves the same audit dir this script does. */
+export const DEFAULT_AUDIT_DIR = path.join('agents', 'runtime', 'state', 'audit');
+export { DEFAULT_PROJECTS_ROOT };
 
 /** Reviewer attribution off audit-line agent_combo — id-shaped types only. */
 const REVIEWER_TYPE_RE = /review|judge|validator/i;
@@ -375,7 +377,8 @@ function fmtTokens(n: number | null): string {
     return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(Math.round(n));
 }
 
-function renderText(r: Report): string {
+/** Exported so `doctor --anatomy` renders the same text this script prints. */
+export function renderText(r: Report): string {
     const lines: string[] = [];
     lines.push('dispatch-economy report (registered: ' + r.registration.registered_at + ' · review by: ' + r.registration.review_by + ')');
     lines.push(`window: ${r.window.max_age_days}d · ${r.window.transcript_records} deduped records · ${r.window.legs} legs`);

package/src/scripts/dispatch_r2_reviewer.ts

@@ -306,6 +306,84 @@ export function computeReviewScope(runGit: GitRunner, base: string): ReviewScope
     return { diffText, hash: sha256(diffText), empty: isEmptyScope(diffText) };
 }
 
+/**
+ * Staleness verdict for a findings artefact already sitting at the dispatch
+ * target, decided by the ONE review-scope hash both dispatcher and validator
+ * bind to — never by a second definition of "same review".
+ *
+ *   - `current` — its manifest claims the scope being dispatched now. This is
+ *     the live review; overwriting it would destroy the record of the review
+ *     that is still in force, so the refusal stands.
+ *   - `stale` — it claims a DIFFERENT scope. The fixes moved the scope past it,
+ *     which is exactly the §2.7 re-bind case, and it must not be mistaken for
+ *     the current review.
+ *   - `unreadable` — no parseable manifest. Treated like `current`: refusing is
+ *     the conservative branch when the artefact cannot be identified, since the
+ *     alternative is renaming a file whose contents nobody established.
+ */
+export type ArtefactStaleness = 'current' | 'stale' | 'unreadable';
+
+export function artefactStaleness(text: string, currentScopeHash: string): ArtefactStaleness {
+    const manifest = parseManifest(text);
+    if (manifest === null) {
+        return 'unreadable';
+    }
+    return manifest.scope_hash === currentScopeHash ? 'current' : 'stale';
+}
+
+/**
+ * The refusal text for a leftover artefact at the dispatch target, naming which
+ * of the contract's two paths applies instead of offering only `--force`.
+ *
+ * **Why this is a message and NOT an automatic rename.** Renaming a stale
+ * artefact aside looks like the obvious fix and contract §2.7 forbids it: a fix
+ * pass changes the review scope, so an artefact bound to the previous scope is
+ * the NORMAL in-place re-bind case, and "renaming instead of re-binding here
+ * would leave the shipping content with no review at all → `missing-artifact`".
+ * The archival rename is a separate, later step, it has a prescribed name
+ * (`<slug>.round<N>-review.md`), and it is gated on every finding already being
+ * terminal (`check_review_dispositions`, which recognises an archived record by
+ * `-review.md`). An invented quarantine name would have slipped past that gate
+ * too, creating an archive path with no terminal check on it.
+ *
+ * So the dispatcher classifies and explains; the operator performs whichever
+ * contract-conform step actually applies.
+ */
+export function leftoverArtefactRefusal(
+    findingsPathRel: string,
+    verdict: ArtefactStaleness,
+    staleScopeHash: string,
+    currentScopeHash: string,
+): string {
+    const head = `❌  Refusing to overwrite existing findings artifact: ${findingsPathRel}\n`;
+    if (verdict === 'unreadable') {
+        return (
+            head +
+            '    Its manifest is unreadable, so it cannot be identified as superseded.\n' +
+            '    Inspect it before doing anything: --force OVERWRITES, and an unidentified\n' +
+            '    artefact may be the only record of a review that happened.\n'
+        );
+    }
+    if (verdict === 'current') {
+        return (
+            head +
+            `    It already binds the scope being dispatched now (${currentScopeHash.slice(0, 12)}),\n` +
+            '    so it is the LIVE review of this content. Re-dispatching would discard it.\n'
+        );
+    }
+    return (
+        head +
+        `    It binds scope ${staleScopeHash.slice(0, 12)}; this dispatch binds ${currentScopeHash.slice(0, 12)},\n` +
+        '    so the reviewed content moved under it. That is the normal re-bind case, and\n' +
+        '    contract §2.7 gives it two paths — neither of which is a fresh skeleton:\n' +
+        '      1. RE-BIND IN PLACE (the usual one): edit this artefact — new `scope:`, rows\n' +
+        '         flipped to terminal — and re-commit it. §2.5 expects exactly that.\n' +
+        '      2. ARCHIVE the closed round: rename it to `<slug>.round<N>-review.md` ONCE every\n' +
+        '         finding is terminal, which `check_review_dispositions` enforces. Then dispatch.\n' +
+        '    --force writes a fresh skeleton OVER this file and destroys the record.\n'
+    );
+}
+
 /** Manifest comment block — exactly the contract §5 shape. */
 export function deriveManifest(inputs: ManifestInputs): string {
     return [
@@ -895,8 +973,31 @@ function runDispatch(args: Args): number {
     const outDirAbs = path.resolve(args.repo, args.outDir);
     const inputDirAbs = path.join(outDirAbs, `${slug}.review-input`);
     const findingsAbs = path.join(outDirAbs, `${slug}.findings.md`);
+    // A leftover artefact at the target is one of three very different things and
+    // the pre-existing refusal could not tell them apart: it said "use --force"
+    // for all of them, and `--force` overwrites — so the only escape it offered
+    // destroys the record of a review that happened. Classify by the ONE
+    // review-scope hash both dispatcher and validator bind to, and name the
+    // contract-conform step for what was actually found.
     if (fs.existsSync(findingsAbs) && !args.force) {
-        process.stderr.write(`❌  Refusing to overwrite existing findings artifact: ${findingsAbs} (use --force)\n`);
+        let existingText: string | null = null;
+        try {
+            existingText = fs.readFileSync(findingsAbs, 'utf-8');
+        } catch {
+            existingText = null;
+        }
+        const verdict: ArtefactStaleness =
+            existingText === null ? 'unreadable' : artefactStaleness(existingText, hashes.scope_hash);
+        const staleHash =
+            existingText === null ? '' : (parseManifest(existingText)?.scope_hash ?? '');
+        process.stderr.write(
+            leftoverArtefactRefusal(
+                path.relative(args.repo, findingsAbs),
+                verdict,
+                staleHash,
+                hashes.scope_hash,
+            ),
+        );
         return 1;
     }
 

package/src/scripts/install.ts

@@ -975,13 +975,17 @@ function ensure_agent_settings(
     success(`${SETTINGS_FILE} created (rule_loading_tier=${profile}${suffix})`);
 }
 
-function ensure_vscode_bridge(project_root: string, package_type: string, force: boolean): void {
+function ensure_vscode_bridge(
+    project_root: string,
+    package_type: string,
+    force: boolean,
+): Record<string, unknown>[] {
     const plugin_paths: Record<string, string> = {
         npm: './node_modules/@event4u/agent-config/plugin/agent-config',
     };
     const plugin_path = plugin_paths[package_type] ?? './plugin/agent-config';
     const bridge = { 'chat.pluginLocations': { [plugin_path]: true } };
-    merge_json_file(
+    return merge_json_file(
         path.join(project_root, '.vscode', 'settings.json'),
         bridge,
         force,
@@ -1043,8 +1047,11 @@ function _remove_legacy_augment_trampolines(): void {
                 fs.unlinkSync(legacy);
                 skip(`removed legacy ~/.augment/hooks/${name}`);
             }
-        } catch {
-            /* OSError → ignore */
+        } catch (err) {
+            // A swallowed failure leaves a stale trampoline that no manifest entry
+            // covers, so uninstall cannot reach it. Non-fatal and semantics-neutral:
+            // the removal is still best-effort, it is simply no longer silent.
+            warn(`could not remove legacy ${legacy}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }
@@ -5075,8 +5082,15 @@ function _main_project_install(
     const merged_keys_by_tool: Record<string, Record<string, unknown>[]> = {};
 
     if (!opts.skip_bridges) {
-        ensure_vscode_bridge(project_root, package_type, opts.force);
-        merged_keys_by_tool['augment'] = ensure_augment_bridge(project_root, opts.force);
+        // `.vscode/settings.json` and `.augment/settings.json` are the two bridges
+        // written unconditionally, so neither belongs to a selected tool. The
+        // lockfile keys `merged_keys` by tool name (`_VALID_TOOLS`), so both are
+        // recorded under the substrate entry `augment` — see
+        // `docs/contracts/install-layout.md` § Untracked surfaces for the residual.
+        merged_keys_by_tool['augment'] = [
+            ...ensure_vscode_bridge(project_root, package_type, opts.force),
+            ...ensure_augment_bridge(project_root, opts.force),
+        ];
         if (_is_tool_enabled(tools, 'claude-code')) {
             merged_keys_by_tool['claude-code'] = ensure_claude_bridge(project_root, opts.force);
         }

package/src/scripts/lint_budget_ownership.ts

@@ -15,6 +15,16 @@
  * are allowed but not required — the top-level owner/review_by covers the
  * file.
  *
+ * ROW-LEVEL schema, opt-in (road-to-cost-parity-0-program § 1.2b/1.3): a
+ * budget file that declares a `row_schema` block additionally has every row
+ * of every top-level array checked for the fields it names — in practice
+ * `source` (so a baseline figure without a traceable origin cannot enter the
+ * file) plus the three honest-null fields. The honest-null contract is the
+ * part that binds: a row that records a `revised_from` without a
+ * `revision_evidence` pointer fails the file, because a target that moved
+ * without published evidence is precisely the drift the clause exists to
+ * refuse. Files that declare no `row_schema` are untouched by this half.
+ *
  * Exit codes: 0 clean · 1 findings · 2 internal error.
  */
 import * as fs from 'node:fs';
@@ -41,6 +51,76 @@ export function checkBudgetDoc(relPath: string, doc: Record<string, unknown>): s
     return errors;
 }
 
+const DEFAULT_ROW_FIELDS = [
+    'id',
+    'unit',
+    'baseline',
+    'source',
+    'revisable',
+    'revision_evidence',
+    'revised_from',
+];
+
+function isRow(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Row-level checks for budget files that opt in via a `row_schema` block.
+ * Returns [] for every file that does not declare one.
+ */
+export function checkBudgetRows(relPath: string, doc: Record<string, unknown>): string[] {
+    const schema = doc['row_schema'];
+    if (!isRow(schema)) return [];
+
+    const declared = schema['required_row_fields'];
+    const required =
+        Array.isArray(declared) && declared.every((f) => typeof f === 'string')
+            ? (declared as string[])
+            : DEFAULT_ROW_FIELDS;
+
+    const errors: string[] = [];
+    if (typeof doc['schema_version'] !== 'number') {
+        errors.push(`${relPath}: \`row_schema\` declared but no numeric top-level \`schema_version\``);
+    }
+    if (typeof doc['registered_at'] !== 'string' || !DATE_RE.test(doc['registered_at'])) {
+        errors.push(`${relPath}: \`row_schema\` declared but no valid top-level \`registered_at\` (YYYY-MM-DD)`);
+    }
+
+    for (const [key, value] of Object.entries(doc)) {
+        if (!Array.isArray(value)) continue;
+        value.forEach((row, index) => {
+            if (!isRow(row)) return;
+            const id = typeof row['id'] === 'string' ? row['id'] : `#${index}`;
+            const where = `${relPath}: ${key}[${index}] (${id})`;
+
+            for (const field of required) {
+                if (!(field in row)) errors.push(`${where}: missing \`${field}\``);
+            }
+            if ('source' in row) {
+                const source = row['source'];
+                if (typeof source !== 'string' || source.trim() === '') {
+                    errors.push(`${where}: empty \`source\` — a baseline figure needs a traceable origin`);
+                }
+            }
+            if ('revisable' in row && row['revisable'] !== true) {
+                errors.push(`${where}: \`revisable\` must be true — an unrevisable target is not honest-null`);
+            }
+            // The honest-null contract: a moved target must publish what moved it.
+            const revisedFrom = row['revised_from'];
+            if (revisedFrom !== null && revisedFrom !== undefined) {
+                const evidence = row['revision_evidence'];
+                if (typeof evidence !== 'string' || evidence.trim() === '') {
+                    errors.push(
+                        `${where}: sets \`revised_from\` without a \`revision_evidence\` pointer — a revision without published evidence`,
+                    );
+                }
+            }
+        });
+    }
+    return errors;
+}
+
 export function budgetFiles(dir: string = CONFIG_DIR): string[] {
     try {
         return fs
@@ -85,6 +165,7 @@ export function main(): number {
             continue;
         }
         errors.push(...checkBudgetDoc(rel, doc));
+        errors.push(...checkBudgetRows(rel, doc));
         const review = doc['review_by'];
         if (typeof review === 'string' && DATE_RE.test(review) && review < today) {
             process.stderr.write(