@holmes-lab/holmes-kit 0.21.0 → 0.22.0

package/dist/holmes/mcp/tool-schemas.js

@@ -204,6 +204,7 @@ exports.TOOL_SCHEMAS = {
             properties: {
                 root: str('Optional when the server is bound to a file store — the ledger location is derived from the store itself; if supplied it must resolve to the SAME project, otherwise the approval is refused before anything is written.'),
                 id: str('Id of the spec to approve and seal.'),
+                dismiss: { type: 'array', items: { type: 'string' }, description: 'A-SPEC-663 — advisory ids (from approval_status.advisoryIds) the author judged not useful; recorded as `dismissed` in the reaction ledger, never blocking. Unknown ids are echoed back in `dismissUnknown`.' },
             },
             required: ['id'],
         },

package/dist/holmes/project/ci-runs.d.ts

@@ -0,0 +1,46 @@
+export type CiStatus = 'green' | 'red' | 'clone-failed' | 'checkout-failed' | 'install-failed' | 'build-failed' | 'jest-crashed' | 'vm-unreachable';
+export interface CiRun {
+    rev: string;
+    os: string;
+    arch?: string;
+    machine?: string;
+    node?: string;
+    status: CiStatus | string;
+    suites: number;
+    tests: number;
+    failed: string[];
+    durationMs: number;
+    at: string;
+    note?: string;
+}
+export interface CiVerdict {
+    os: string;
+    state: 'green' | 'red' | 'failed' | 'not-run';
+    rev?: string;
+    at?: string;
+    behind?: number;
+    failed: string[];
+    status?: string;
+}
+/**
+ * @implements A-SPEC-664 — the ADOPTION predicate: does this workspace use the CI matrix at all?
+ *
+ * Existence, not contents. A `ci-runs.<host>.jsonl` that exists but is empty means a run was
+ * attempted here, so silence about a commit is a signal worth saying out loud. No file at all means
+ * nobody ever ran the matrix in this workspace — and the runner script is not in the shipped package
+ * (`files` carries bin/, dist/, grammars/, playbooks/, scripts/install.ps1, docs/, CHANGELOG), so
+ * advising every consumer to run it would be advising a path they do not have. Measured 2026-09-18
+ * on a consumer-shaped tree: the Stop hook printed that advice every turn.
+ */
+export declare function hasCiLedger(root: string): boolean;
+export declare function readCiRuns(root: string): CiRun[];
+/** The most recent run for an OS, by `at`. */
+export declare function latestCiRun(runs: CiRun[], os?: string): CiRun | undefined;
+/**
+ * What the matrix says about `head`. `behind(rev)` is the injected git distance from that rev to
+ * head (commits), or undefined when git cannot answer. No run → `not-run`; an infrastructure
+ * status (clone/install/build failed, VM unreachable) → `failed`, which is not red and not green.
+ */
+export declare function ciVerdict(runs: CiRun[], os: string, head: string | undefined, behind: (rev: string) => number | undefined): CiVerdict;
+/** One line for the Stop hook's tracked channel or doctor. Never says green without a green row. */
+export declare function ciStatusLine(v: CiVerdict): string;

package/dist/holmes/project/ci-runs.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasCiLedger = hasCiLedger;
+exports.readCiRuns = readCiRuns;
+exports.latestCiRun = latestCiRun;
+exports.ciVerdict = ciVerdict;
+exports.ciStatusLine = ciStatusLine;
+// @implements A-SPEC-664
+/**
+ * The CI-runs ledger reader — the product side of the minimal Linux matrix.
+ *
+ * `scripts/ci-orb-linux.sh` appends one row per judged commit to `.ax/ledger/ci-runs.<host>.jsonl`.
+ * This module reads those rows and says, for a given HEAD, what the matrix last said — and says
+ * "not run" when it has nothing, never "green". Measured 2026-09-17: the 0.21.0 release's first Linux
+ * run showed 136 red suites, all environmental; the cost of not having a row to look at was three
+ * diagnostic rounds. Pure except the ledger read; git distance is injected.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const FILE_RE = /^ci-runs\.([^.]+)\.jsonl$/;
+/**
+ * @implements A-SPEC-664 — the ADOPTION predicate: does this workspace use the CI matrix at all?
+ *
+ * Existence, not contents. A `ci-runs.<host>.jsonl` that exists but is empty means a run was
+ * attempted here, so silence about a commit is a signal worth saying out loud. No file at all means
+ * nobody ever ran the matrix in this workspace — and the runner script is not in the shipped package
+ * (`files` carries bin/, dist/, grammars/, playbooks/, scripts/install.ps1, docs/, CHANGELOG), so
+ * advising every consumer to run it would be advising a path they do not have. Measured 2026-09-18
+ * on a consumer-shaped tree: the Stop hook printed that advice every turn.
+ */
+function hasCiLedger(root) {
+    try {
+        return fs.readdirSync(path.join(root, '.ax', 'ledger')).some((n) => FILE_RE.test(n));
+    }
+    catch {
+        return false;
+    }
+}
+function readCiRuns(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => FILE_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, n), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const r = JSON.parse(line);
+                if (typeof r.rev !== 'string' || typeof r.os !== 'string' || typeof r.at !== 'string')
+                    continue;
+                out.push({ ...r, rev: r.rev, os: r.os, at: r.at, suites: Number(r.suites ?? 0), tests: Number(r.tests ?? 0),
+                    failed: Array.isArray(r.failed) ? r.failed.map(String) : [], durationMs: Number(r.durationMs ?? 0), status: String(r.status ?? 'unknown') });
+            }
+            catch { /* a torn line is not a run */ }
+        }
+    }
+    return out.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+}
+/** The most recent run for an OS, by `at`. */
+function latestCiRun(runs, os = 'linux') {
+    let best;
+    for (const r of runs)
+        if (r.os === os && (!best || r.at >= best.at))
+            best = r;
+    return best;
+}
+/**
+ * What the matrix says about `head`. `behind(rev)` is the injected git distance from that rev to
+ * head (commits), or undefined when git cannot answer. No run → `not-run`; an infrastructure
+ * status (clone/install/build failed, VM unreachable) → `failed`, which is not red and not green.
+ */
+function ciVerdict(runs, os, head, behind) {
+    const latest = latestCiRun(runs, os);
+    if (!latest)
+        return { os, state: 'not-run', failed: [] };
+    const state = latest.status === 'green' ? 'green' : latest.status === 'red' ? 'red' : 'failed';
+    const b = head && latest.rev !== head ? behind(latest.rev) : head ? 0 : undefined;
+    return { os, state, rev: latest.rev, at: latest.at, ...(b === undefined ? {} : { behind: b }), failed: latest.failed, status: latest.status };
+}
+/** One line for the Stop hook's tracked channel or doctor. Never says green without a green row. */
+function ciStatusLine(v) {
+    if (v.state === 'not-run')
+        return `CI: ${v.os} not run (no ci-runs ledger row) — run scripts/ci-orb-linux.sh`;
+    const short = (v.rev ?? '').slice(0, 8);
+    const behind = v.behind === undefined ? '' : v.behind === 0 ? ' (at HEAD)' : ` (${v.behind} commit${v.behind === 1 ? '' : 's'} behind HEAD)`;
+    if (v.state === 'green')
+        return `CI: ${v.os} ${short} green${behind}`;
+    if (v.state === 'red')
+        return `CI: ${v.os} ${short} red${behind}: ${v.failed.slice(0, 5).join(', ')}${v.failed.length > 5 ? ` +${v.failed.length - 5}` : ''}`;
+    return `CI: ${v.os} ${short} ${v.status}${behind} — the matrix could not judge this commit`;
+}

package/dist/holmes/project/install-scripts-policy.js

@@ -1,4 +1,5 @@
 "use strict";
+// @implements A-SPEC-595
 // @implements A-SPEC-579
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PREBUILT_NATIVE_DEPS = exports.NATIVE_INSTALL_SCRIPT_DEPS = void 0;

package/dist/holmes/review/evaluation-metrics.js

@@ -7,6 +7,7 @@ exports.ceilingMetrics = ceilingMetrics;
 exports.achievementRate = achievementRate;
 exports.boundsImpact = boundsImpact;
 exports.overlapOf = overlapOf;
+// @implements A-SPEC-314
 // @implements A-SPEC-296
 /**
  * Objective evaluation of a replay corpus (Goal Phase 8).

package/dist/holmes/review/kills-check.d.ts

@@ -0,0 +1,40 @@
+import { Mutation } from '../spec/kills';
+export type UnapplicableReason = 'where-empty' | 'no-anchored-source' | 'where-looks-like-path' | 'where-not-found';
+export interface UnapplicableKill {
+    where: string;
+    mutate: string;
+    reason: UnapplicableReason;
+}
+export interface KillsAdvisory {
+    kind: 'kills-unapplicable';
+    tspec: string;
+    aspec: string;
+    total: number;
+    applicable: number;
+    unapplicable: UnapplicableKill[];
+}
+/** Reason precedence: empty → no source at all → found (applicable) → path-shaped → not found. Pure. */
+export declare function killsApplicability(kills: Mutation[], sourceTexts: Record<string, string>): {
+    applicable: Mutation[];
+    unapplicable: UnapplicableKill[];
+};
+/** The advisory a T-SPEC approval carries; null when there is nothing to say. Pure. */
+export declare function killsAdvisory(tspec: string, aspec: string, kills: Mutation[], sourceTexts: Record<string, string>): KillsAdvisory | null;
+/**
+ * `applied:false` results are UNAPPLIED, never survivors: a mutation that was never made cannot have
+ * survived anything. Survivors are the applied mutations the covering tests did not catch. Pure.
+ */
+export declare function partitionMutateResults<R extends {
+    mutation: Mutation;
+    applied: boolean;
+    reason?: string;
+    verdict?: 'killed' | 'survived';
+}>(results: R[]): {
+    survivors: Mutation[];
+    unapplied: {
+        where: string;
+        reason: string;
+    }[];
+};
+/** Text of every production source that @implements `aspecId`. Unreadable root → {}; unreadable file → skipped. */
+export declare function anchoredSourceTexts(root: string, aspecId: string): Record<string, string>;

package/dist/holmes/review/kills-check.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.killsApplicability = killsApplicability;
+exports.killsAdvisory = killsAdvisory;
+exports.partitionMutateResults = partitionMutateResults;
+exports.anchoredSourceTexts = anchoredSourceTexts;
+// @implements A-SPEC-662
+/**
+ * `kills` applicability — the honesty half of the C-layer mutation field.
+ *
+ * Measured 2026-09-17 (docs/goals/EVIDENCE-kills-cost-2026-09-17.md): every one of the 22 `kills`
+ * entries in this repository wrote `where` as a file path and `mutate` as prose, so the literal-
+ * replacement engine (`spec/kills.ts`) applied none of them — and `test_run --mutate` then answered
+ * `survivors: []`, the same shape a clean run has. Nothing at approval time said a word.
+ *
+ * Pure judgement here; the walk that collects anchored source text is the only I/O, kept separate
+ * and injectable. The rule is the engine's own: `where` must occur literally in a production source
+ * that @implements the A-SPEC. This module never blocks — it names what will not apply.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// A bare relative path with an extension and no whitespace — the shape all 22 measured entries had.
+const LOOKS_LIKE_PATH = /^[\w@./-]+\.[A-Za-z0-9]{1,6}$/;
+/** Reason precedence: empty → no source at all → found (applicable) → path-shaped → not found. Pure. */
+function killsApplicability(kills, sourceTexts) {
+    const texts = Object.values(sourceTexts);
+    const applicable = [];
+    const unapplicable = [];
+    for (const m of kills) {
+        const where = String(m.where ?? '');
+        let reason = null;
+        if (where.trim() === '')
+            reason = 'where-empty';
+        else if (texts.length === 0)
+            reason = 'no-anchored-source';
+        else if (texts.some((t) => t.includes(where)))
+            reason = null;
+        else if (LOOKS_LIKE_PATH.test(where))
+            reason = 'where-looks-like-path';
+        else
+            reason = 'where-not-found';
+        if (reason === null)
+            applicable.push(m);
+        else
+            unapplicable.push({ where: m.where, mutate: m.mutate, reason });
+    }
+    return { applicable, unapplicable };
+}
+/** The advisory a T-SPEC approval carries; null when there is nothing to say. Pure. */
+function killsAdvisory(tspec, aspec, kills, sourceTexts) {
+    if (kills.length === 0)
+        return null;
+    const r = killsApplicability(kills, sourceTexts);
+    if (r.unapplicable.length === 0)
+        return null;
+    return { kind: 'kills-unapplicable', tspec, aspec, total: kills.length, applicable: r.applicable.length, unapplicable: r.unapplicable };
+}
+/**
+ * `applied:false` results are UNAPPLIED, never survivors: a mutation that was never made cannot have
+ * survived anything. Survivors are the applied mutations the covering tests did not catch. Pure.
+ */
+function partitionMutateResults(results) {
+    const survivors = [];
+    const unapplied = [];
+    for (const r of results) {
+        if (r.applied === false) {
+            unapplied.push({ where: r.mutation.where, reason: r.reason ?? 'not applied' });
+            continue;
+        }
+        if (r.verdict === 'survived')
+            survivors.push(r.mutation);
+    }
+    return { survivors, unapplied };
+}
+// The same walk `handlers/test-execution.ts` (`sourceFileWithMutation`) makes: bounded, skips vendored,
+// hidden, built and test files. Keys are repo-relative POSIX paths.
+const SOURCE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|rb|php|swift)$/;
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'reference', 'vendor', 'third_party']);
+/** Text of every production source that @implements `aspecId`. Unreadable root → {}; unreadable file → skipped. */
+function anchoredSourceTexts(root, aspecId) {
+    const out = {};
+    const marker = `@implements ${aspecId}`;
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (SKIP_DIRS.has(e.name) || e.name.startsWith('.'))
+                continue;
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+                continue;
+            }
+            if (!SOURCE.test(e.name) || /\.test\./.test(e.name))
+                continue;
+            let text;
+            try {
+                text = fs.readFileSync(p, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (text.includes(marker))
+                out[path.relative(root, p).split(path.sep).join('/')] = text;
+        }
+    };
+    walk(root);
+    return out;
+}

package/dist/holmes/review/manual-baseline.js

@@ -5,6 +5,7 @@ exports.manualBaselineOutcomes = manualBaselineOutcomes;
 exports.shippedOutcomes = shippedOutcomes;
 exports.shippedBeatsManual = shippedBeatsManual;
 exports.poolCoverage = poolCoverage;
+// @implements A-SPEC-412, A-SPEC-413, A-SPEC-414
 // @implements A-SPEC-404
 /**
  * The "strong model with plain file search" baseline (Goal Phase B).

package/dist/holmes/rtm/advisory-outcomes.d.ts

@@ -0,0 +1,137 @@
+export type AdvisoryKind = 'impact-advisory' | 'anchor-density' | 'ftt-fulfilment' | 'trace-gap' | 'kills-unapplicable';
+export type AdvisoryOutcome = 'issued' | 'resolved' | 'persisted' | 'dismissed';
+export interface AdvisoryKey {
+    id: string;
+    kind: AdvisoryKind;
+    aspec: string;
+}
+export interface AdvisoryOutcomeRecord extends AdvisoryKey {
+    outcome: AdvisoryOutcome;
+    firstSeen: string;
+    judgedAt: string;
+    head: string;
+    replica?: string;
+}
+export interface AdvisoryState extends AdvisoryKey {
+    firstSeen: string;
+    last: AdvisoryOutcome;
+    lastAt: string;
+    rows: number;
+}
+/** Canonical JSON: sorted keys, arrays kept in order — the same payload always gives the same id. */
+export declare function canonical(value: unknown): string;
+/** Deterministic identity of one finding: kind + spec + canonical payload → sha256, first 16 hex. */
+export declare function advisoryId(kind: AdvisoryKind, aspec: string, payload: unknown): string;
+/** Latest state per id, in first-seen order. `dismissed` and `resolved` are terminal until re-issued. */
+export declare function foldAdvisoryState(rows: AdvisoryOutcomeRecord[]): AdvisoryState[];
+/**
+ * Judge the advisories a re-evaluation produced against what the ledger already knows.
+ *  - a current finding with no state, or whose last state is resolved/dismissed → `issued`
+ *  - a current finding whose last state is issued/persisted → `persisted`
+ *  - an open (issued/persisted) finding of the judged scope that is no longer current → `resolved`
+ * One row per (id, outcome) per UTC day: re-running the same query the same day adds nothing.
+ * `scope` names which open findings this evaluation could have seen (so an unrelated spec's finding
+ * is never resolved by a query that did not look at it).
+ */
+export declare function judgeAdvisories(state: AdvisoryState[], current: AdvisoryKey[], scope: (s: AdvisoryState) => boolean, now: string, head: string, recent?: AdvisoryOutcomeRecord[], opts?: {
+    issue?: boolean;
+}): AdvisoryOutcomeRecord[];
+/** Explicit dismissal by the author: only for findings the ledger knows and that are still open. */
+export declare function dismissAdvisories(state: AdvisoryState[], ids: string[], now: string, head: string): AdvisoryOutcomeRecord[];
+export type AdvisoryCensus = Record<AdvisoryKind, {
+    issued: number;
+    resolved: number;
+    persisted: number;
+    dismissed: number;
+}>;
+export declare const ADVISORY_KINDS: AdvisoryKind[];
+/** Per kind: how many findings were ever issued, and how many stand resolved / persisted / dismissed now. */
+export declare function advisoryCensus(rows: AdvisoryOutcomeRecord[]): AdvisoryCensus;
+export declare function appendAdvisoryOutcomes(root: string, rows: AdvisoryOutcomeRecord[]): boolean;
+export declare function readAdvisoryOutcomes(root: string): AdvisoryOutcomeRecord[];
+/**
+ * One trace-gap finding per unlinked approved A-SPEC that declares at least one SCANNED production
+ * file in its Files to Touch — the same population REQ-658 reports per change, taken whole. The
+ * payload is the sorted file list, so moving one anchor changes the id (a smaller gap is a new
+ * finding, the old one resolved) — honest, if noisy; the census counts findings, not specs.
+ */
+export declare function traceGapAdvisories(specs: ReadonlyArray<{
+    id: string;
+    type: string;
+    status: string;
+    sections?: Record<string, string>;
+}>, scanned: ReadonlyArray<{
+    path: string;
+    implementsSpecs?: string[];
+}>, root?: string): AdvisoryKey[];
+/**
+ * The findings a seal or a preview computed, as ledger keys. Each kind's payload is its minimal
+ * canonical form — paths and reasons only, never summaries or counts that vary without the finding
+ * changing. Absent inputs contribute nothing.
+ */
+export interface ComputedAdvisories {
+    impactAdvisory?: {
+        files: Array<{
+            path: string;
+        }>;
+    } | null;
+    anchorDensity?: Array<{
+        path: string;
+    }> | null;
+    fttFulfilment?: {
+        missing: Array<{
+            path: string;
+        }>;
+        moved: Array<{
+            path: string;
+        }>;
+        alternatives: Array<{
+            path: string;
+        }>;
+    } | null;
+    killsAdvisory?: {
+        unapplicable: Array<{
+            where: string;
+            reason: string;
+        }>;
+    } | null;
+    traceGap?: {
+        files: string[];
+    } | null;
+}
+export declare function currentAdvisoryKeys(aspec: string, c: ComputedAdvisories): {
+    keys: AdvisoryKey[];
+    ids: Partial<Record<AdvisoryKind, string>>;
+};
+/**
+ * One act: read the ledger, judge `current` against it within `scope`, apply explicit dismissals,
+ * append, and return what the response should carry. I/O failures leave the response without the
+ * fields (the seal or the query is unaffected). Never throws.
+ */
+export declare function recordAdvisoryOutcomes(root: string, aspec: string, current: AdvisoryKey[], scope: (s: AdvisoryState) => boolean, head: string, dismiss?: string[], now?: string, opts?: {
+    issue?: boolean;
+}): {
+    history: AdvisoryState[];
+    dismissUnknown: string[];
+};
+/** The scanned production files an A-SPEC declares — the trace-gap payload for one spec. */
+export declare function traceGapFiles(spec: {
+    sections?: Record<string, string>;
+}, scanned: ReadonlyArray<{
+    path: string;
+}>, root?: string): string[];
+/** The commit a reaction row is judged at; 'nogit' when git cannot say. Never throws. */
+export declare function gitHeadOf(root: string): string;
+/**
+ * The trace-gap finding for ONE spec, status aside: the scanned production files it declares, or
+ * null when a scanned file already anchors it or it declares none. Used at the seal (where the
+ * spec is approved by the time this runs) and in the preview.
+ */
+export declare function traceGapFor(specId: string, spec: {
+    sections?: Record<string, string>;
+}, scanned: ReadonlyArray<{
+    path: string;
+    implementsSpecs?: string[];
+}>, root?: string): {
+    files: string[];
+} | null;