@holmes-lab/holmes-kit 0.26.2 → 0.27.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.27.0] - 2026-09-20
+
+A repository can now say, as a number anyone can reproduce, how much of it is governed.
+
+### Added
+- **`holmes-kit attest` — how many source files trace to an APPROVED spec** (A-SPEC-702). The request
+  was a "generated under holmes-kit" header in every source file. That was declined: a header is a
+  claim that can be pasted and keeps saying "governed" after an ungoverned edit, it brands files that
+  belong to the consumer, the same sentence in every file is measured retrieval noise, and line 1
+  already carries the `implements` anchor a gate verifies. What was missing is a repository-level
+  statement: the spec-side census lived only inside the dashboard and the file-side one did not exist.
+  `attest` adds **no new judgement** — the denominator is what the scanner returned, the numerator is
+  anchors ∩ approved ids (a draft anchor is not a trace), the spec axis is the existing link census —
+  and prints where the number is true: commit and a digest of the approved specs. `+dirty` is set only
+  when a path that *decides* the number is uncommitted (a scanned source or a spec), so writing the
+  badge does not make the badge a lie. `--exclude a,b` names trees that are not yours (vendored);
+  exclusions match at a path boundary, a prefix meaning "everything" is dropped, and they are echoed in
+  every output. What cannot be measured is `n/a` with the reason, never `0%` or `100%`; percentages are
+  floored, so `100` appears only when every file is traced; ten or fewer untraced files are named.
+  `--badge` writes a self-contained SVG (`.ax/badges/traced.svg` — no href, font, script or fetch).
+  `--readme` rewrites **only** the region between `<!-- holmes-kit:attest:begin -->` and
+  `<!-- holmes-kit:attest:end -->`: a README without the markers is never written (placing them is the
+  consent), a half, doubled or reversed marker is refused with exit 1, and a CRLF README stays CRLF.
+  The numbers never change the exit code — this is a statement, not a gate. CLI only, so it is the
+  same in every harness and adds no MCP schema cost. Measured on this repository: 396/614 (64.4%) as
+  scanned; 386/386 once `reference/` (212 vendored files), `dist-tools/` (build output that carried
+  anchors and had been counting as traced source) and `docs/goals/probes/` are named as excluded.
+
 ## [0.26.2] - 2026-09-20
 
 The last stretch of the number-collision repair: the plan `doctor` has been printing since 0.26.1 can

package/README.md

@@ -6,6 +6,13 @@
 
 > **"No Spec, No Code"** — Deterministic Agentic Software Engineering (ASE) harness with causal traceability.
 
+<!-- holmes-kit:attest:begin -->
+![traced files](.ax/badges/traced.svg)
+
+**386/386** source files (100%) trace to an approved spec · **629/680** approved A-SPECs (92.5%) are anchored from code.
+Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `holmes-kit attest --exclude dist-tools/,docs/goals/probes/,reference/`.
+<!-- holmes-kit:attest:end -->
+
 ---
 
 ## 🕵️ Philosophy & Vision: Beyond Code Generation
@@ -16,6 +23,7 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 📏 **Say how much of the repository is governed — as a number, not a label** *(new in 0.27.0)*: `holmes-kit attest` reports how many scanned source files are anchored to an **approved** spec, beside how many approved A-SPECs are anchored from code, and says where that is true (commit, plus a digest of the approved specs) so anyone can reproduce it. No new judgement: the scanner's files, the anchors, the existing link census. A per-file "generated under holmes-kit" header was declined — it is a claim that survives an ungoverned edit, and line 1 already carries the anchor a gate verifies. `--exclude a,b` names vendored trees at a path boundary and is echoed in every output; what cannot be measured is `n/a`, never `0%`; `100` appears only when every file is traced. `--badge` writes a self-contained local SVG, and `--readme` rewrites **only** the region between the `holmes-kit:attest` markers — a README without them is never touched, and a half marker is refused. A statement, not a gate: the numbers never change the exit code.
 - 🤝 **The collision plan runs under one approval** *(new in 0.26.2)*: 0.26.1 saw a spec number another machine took and printed the plan; carrying it out was still one `spec_renumber` call per family, and that tool's apply asks for no approval although it rewrites approved documents and source anchors. `spec_reconcile` `plan` is read-only and returns the moves, what each rewrites, the re-seal order, the prose it will **not** touch, and a `target` derived from the plan's content alone. `apply` rebuilds the plan inside the store hold, refuses `plan-changed` if a fetch moved it since you looked, demands one `config-write` approval bound to that `target`, and runs every move through the path `spec_renumber` already uses. Forged `moves` are never read — what runs is the recomputed plan. It never seals: `spec_approve` stays the only sealer. No remote is an answer, not a refusal.
 - 🔢 **A spec number another machine took is seen before the merge** *(new in 0.26.1)*: two checkouts allocated `REQ-694` thirteen minutes apart, neither could see the other, and it surfaced only as an add/add conflict after the push was refused — a rebuilt slice and five out-of-band approvals. `doctor --target` now reads each remote-tracking ref **as last fetched** (no network) and judges only the documents each side *added* since they parted, so a spec one side merely edited is divergence, not an alarm. On a collision the advice is the plan: `Before merging — move 901 → 903: spec_renumber(oldBase=901, newBase=903); then re-seal`. The side that moves is the one not published yet, the destination is free on both sides, and "published" means equal content — never path, because a spec's path is its number.
 - 🔁 **The cycle ratchet finally speaks — and takes a named exception** *(new in 0.26.1)*: since the commit that introduced it, the Stop hook computed the code cycles and called the verdict without them, so the `ART-2` line had never been printed; every unit test passed because each handed the evidence in directly. It is emitted now, bounded (five cycles, five members each, the rest counted — one vendored cycle here has 46 members), and `ax.config.json` gains `architecture.cycleIgnore`: prefixes for trees that are not yours to fix. A cycle is excepted only when every member lies under one, `reference` does not pardon `reference-impl/`, a broken config excepts nothing, and excepted cycles stay counted in the ledger.

package/dist/.build-id

@@ -1 +1 @@
-29f20e72-mu9gw8dl
+4ec4b788-mu9vw1zt

package/dist/holmes/cli/attest.d.ts

@@ -0,0 +1,15 @@
+import { type AttestReport } from '../rtm/traced-files';
+export interface AttestOptions {
+    root: string;
+    exclude: string[];
+    json: boolean;
+    badge: boolean;
+    readme: boolean;
+}
+export interface AttestIo {
+    stdout(s: string): void;
+    stderr(s: string): void;
+}
+export declare const BADGE_REL: string;
+export declare function buildAttestReport(root: string, exclude: string[]): Promise<AttestReport>;
+export declare function runAttest(o: AttestOptions, io: AttestIo): Promise<number>;

package/dist/holmes/cli/attest.js

@@ -0,0 +1,168 @@
+"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.BADGE_REL = void 0;
+exports.buildAttestReport = buildAttestReport;
+exports.runAttest = runAttest;
+// @implements A-SPEC-702
+/**
+ * `holmes-kit attest` — the surface that calls `rtm/traced-files`.
+ *
+ * Reads: one scan, the spec store, git (optional — REQ-128). Writes: AT MOST two files, and only
+ * when asked: the badge (`--badge`) and the region between the README markers (`--readme`). A README
+ * without markers is never written: placing the markers is the consent. Nothing reaches the network,
+ * and the measured numbers never change the exit code — this is a statement, not a gate.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const spec_store_1 = require("../spec/spec-store");
+const root_1 = require("../project/root");
+const test_scope_1 = require("../rtm/test-scope");
+const file_anchors_1 = require("../rtm/file-anchors");
+const link_census_1 = require("../rtm/link-census");
+const traced_files_1 = require("../rtm/traced-files");
+exports.BADGE_REL = path.join('.ax', 'badges', 'traced.svg');
+const SPECS_REL = path.join('.ax', 'specs');
+const git = (root, args) => {
+    try {
+        return (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(process.env) }).toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * `+dirty` only when something that DECIDES the number is uncommitted: a scanned source file or a
+ * spec. The badge and the README are outputs of this very command, and a session ledger is always
+ * moving — counting them would make a committed badge say `+dirty` forever.
+ */
+function decidingPathsDirty(root, scanned) {
+    const out = git(root, ['status', '--porcelain', '-z', '--untracked-files=all']);
+    if (out === undefined)
+        return false;
+    const specs = SPECS_REL.split(path.sep).join('/') + '/';
+    for (const entry of out.split('\0')) {
+        if (entry.length < 4)
+            continue;
+        const p = entry.slice(3);
+        if (p.startsWith(specs) || scanned.has(p))
+            return true;
+    }
+    return false;
+}
+async function buildAttestReport(root, exclude) {
+    const scanned = new cpg_scanner_1.CpgScanner().scan(root, root);
+    const specs = await new spec_store_1.LocalMarkdownRepository(path.join(root, SPECS_REL)).list();
+    const approved = specs.filter((s) => s.status === 'approved');
+    const files = scanned.map((f) => ({ path: f.sourcePath.split(path.sep).join('/'), anchors: f.implementsSpecs ?? [] }));
+    // The spec axis, the way the dashboard computes it (A-SPEC-655). `weakMentions` stays empty: it
+    // only splits the REASON a spec is unlinked, and this command reports the count.
+    const excludes = (0, traced_files_1.normalizeExcludes)(exclude);
+    const kept = files.filter((f) => !excludes.some((e) => f.path.startsWith(e)));
+    const census = (0, link_census_1.linkCensus)({
+        approvedIds: approved.filter((s) => s.id.startsWith('A-SPEC')).map((s) => s.id),
+        implemented: new Set(kept.flatMap((f) => f.anchors)),
+        testAnchors: (0, test_scope_1.scanTestAnchors)(root),
+        fileAnchors: (0, file_anchors_1.scanFileAnchors)(root),
+        weakMentions: {},
+    });
+    const commit = git(root, ['rev-parse', 'HEAD'])?.trim();
+    return {
+        files: (0, traced_files_1.tracedFiles)({ files, approvedIds: approved.map((s) => s.id), exclude }),
+        specs: { total: census.total, linked: census.codeLinked },
+        provenance: (0, traced_files_1.attestProvenance)({
+            commit,
+            dirty: commit ? decidingPathsDirty(root, new Set(files.map((f) => f.path))) : false,
+            approved: approved.map((s) => ({ id: s.id, digest: String(s.frontmatter.approved_digest ?? '') })),
+            exclude,
+        }),
+    };
+}
+async function runAttest(o, io) {
+    if (!fs.existsSync(o.root) || !fs.statSync(o.root).isDirectory()) {
+        io.stderr(`attest: ${o.root} is not a directory\n`);
+        return 2;
+    }
+    const report = await buildAttestReport(o.root, o.exclude);
+    io.stdout(o.json ? (0, traced_files_1.renderAttestJson)(report) : (0, traced_files_1.renderAttestText)(report));
+    let code = 0;
+    const note = (s) => { if (!o.json)
+        io.stdout(s);
+    else
+        io.stderr(s); };
+    if (o.badge) {
+        const file = path.join(o.root, exports.BADGE_REL);
+        const svg = (0, traced_files_1.renderAttestSvg)(report);
+        let same = false;
+        try {
+            same = fs.readFileSync(file, 'utf8') === svg;
+        }
+        catch { /* absent */ }
+        if (!same) {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, svg);
+        }
+        note(`badge          ${exports.BADGE_REL.split(path.sep).join('/')}${same ? ' (unchanged)' : ' written'}\n`);
+    }
+    if (o.readme) {
+        const file = path.join(o.root, 'README.md');
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            text = undefined;
+        }
+        if (text === undefined)
+            note('readme         README.md not found — nothing written\n');
+        else {
+            const r = (0, traced_files_1.replaceMarkerRegion)(text, (0, traced_files_1.renderAttestMarker)(report));
+            if (r.ok) {
+                if (r.changed)
+                    fs.writeFileSync(file, r.text);
+                note(`readme         marker region ${r.changed ? 'updated' : 'unchanged'}\n`);
+            }
+            else if (r.reason === 'no-marker')
+                note('readme         no marker in README.md — nothing written (add the begin/end markers to opt in)\n');
+            else {
+                io.stderr('attest: README.md has an unbalanced holmes-kit:attest marker (each must appear exactly once, begin first) — nothing written\n');
+                code = 1;
+            }
+        }
+    }
+    return code;
+}

package/dist/holmes/cli/index.d.ts

@@ -4,6 +4,7 @@
  * Commands:
  *   init [--mode guardrail|governed] [--target dir] [--dry-run] [--remove] [--force] ...
  *   doctor [--target dir] [--json]
+ *   attest [--target dir] [--exclude a,b] [--json] [--badge] [--readme]
  */
 /**
  * The installed package root. From `dist/holmes/cli/index.js` that is three levels up. Node resolves

package/dist/holmes/cli/index.js

@@ -55,6 +55,7 @@ const colophon_1 = require("./colophon");
  * Commands:
  *   init [--mode guardrail|governed] [--target dir] [--dry-run] [--remove] [--force] ...
  *   doctor [--target dir] [--json]
+ *   attest [--target dir] [--exclude a,b] [--json] [--badge] [--readme]
  */
 /**
  * The installed package root. From `dist/holmes/cli/index.js` that is three levels up. Node resolves
@@ -78,6 +79,8 @@ const KNOWN_FLAGS = {
     init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent', 'mcp-launcher', 'autonomy', 'no-autonomy'],
     autonomy: ['help', 'target', 'for'],
     doctor: ['help', 'target', 'json'],
+    // @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
+    attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
     skills: ['help', 'target'],
     ci: ['help', 'target', 'specs-dir', 'json'],
     serve: ['help', 'target', 'port'],
@@ -119,7 +122,7 @@ class UnknownFlagError extends Error {
  * what you'd do" spelling performed a REAL write (round-3 HIGH; same class inverted --remove and
  * --force). A boolean flag must never consume a token.
  */
-const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy']); // A-SPEC-650: --status
+const BOOLEAN_FLAGS = new Set(['badge', 'readme', 'help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy']); // A-SPEC-650: --status
 function parseFlags(argv, known) {
     const flags = {};
     const positionals = [];
@@ -239,6 +242,14 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
     --target <dir>             also verify that target's wiring points at this install
     --json                     machine-readable output
 
+  holmes-kit attest [flags]    say how many source files trace to an APPROVED spec (a statement, not a gate)
+    --target <dir>             the project to measure (default: current directory)
+    --exclude <a,b>            path prefixes that are not this project's source (vendored trees); echoed in the output
+    --json                     machine-readable output
+    --badge                    write a self-contained SVG to .ax/badges/traced.svg
+    --readme                   update ONLY the region between the holmes-kit:attest markers in README.md;
+                               a README without the markers is never written
+
   holmes-kit upgrade [flags]   install the latest and re-pin every recorded workspace (one command)
     --dry-run                  show the plan (current→latest, workspaces to re-pin), change nothing
     --yes                      skip the confirmation prompt (required in a non-interactive shell)
@@ -376,6 +387,14 @@ async function main(argv) {
         }
         return reported.code;
     }
+    // @implements A-SPEC-702 — reads one scan and the spec store; writes only the badge and the README's
+    // marker region, and only when asked. The numbers never change the exit code.
+    if (cmd === 'attest') {
+        const { runAttest } = require('./attest');
+        const target = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
+        const exclude = typeof flags.exclude === 'string' ? flags.exclude.split(',') : [];
+        return runAttest({ root: target, exclude, json: flags.json === true, badge: flags.badge === true, readme: flags.readme === true }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
+    }
     if (cmd === 'doctor') {
         // A nonexistent target read as "healthy but unwired" and both advised remedies then refused it
         // (round-6) — the typo is the diagnosis, so say it.

package/dist/holmes/rtm/traced-files.d.ts

@@ -0,0 +1,83 @@
+export interface TracedFilesInput {
+    /** What the scanner returned: repo-relative path and the spec ids the file anchors. */
+    files: readonly {
+        path: string;
+        anchors: readonly string[];
+    }[];
+    /** Ids whose status is `approved`. A draft anchor is not a trace. */
+    approvedIds: Iterable<string>;
+    /** Path prefixes that are not this project's source (vendored trees). Explicit, and echoed back. */
+    exclude?: readonly string[];
+}
+export interface TracedFiles {
+    total: number;
+    traced: number;
+    excluded: number;
+    /** Sorted. */
+    untraced: string[];
+    measurable: boolean;
+    reason?: string;
+    /** One decimal, FLOORED; `null` when not measurable. */
+    tracedPct: number | null;
+}
+export interface AttestProvenance {
+    at: string;
+    specs: string;
+    exclude: string[];
+}
+export interface AttestReport {
+    files: TracedFiles;
+    specs: {
+        total: number;
+        linked: number;
+    };
+    provenance: AttestProvenance;
+}
+export declare const ATTEST_BEGIN = "<!-- holmes-kit:attest:begin -->";
+export declare const ATTEST_END = "<!-- holmes-kit:attest:end -->";
+export declare const ATTEST_SCHEMA = "holmes-attest/1";
+/** Above this many untraced files the text names none and points at `--json`. */
+export declare const UNTRACED_LINE_CAP = 10;
+/**
+ * Backslashes folded, one trailing slash. A prefix that means "everything" is DROPPED: excluding the
+ * whole tree would read as n/a at best and 100% at worst (the same rule A-SPEC-694 pinned for
+ * `cycleIgnore`). Sorted and de-duplicated so the provenance does not depend on how it was typed.
+ */
+export declare function normalizeExcludes(raw: readonly string[] | undefined): string[];
+/** Floored to one decimal: 99.96 must not read as 100 — 100 means every file. */
+export declare function flooredPct(num: number, den: number): number | null;
+export declare function tracedFiles(input: TracedFilesInput): TracedFiles;
+/**
+ * Where and when the number is true. `+dirty` because a commit alone would call an unreproducible
+ * number reproducible. The spec digest covers (id, seal) of every approved spec — that set is what
+ * decides the numerator. No clock anywhere.
+ */
+export declare function attestProvenance(input: {
+    commit?: string;
+    dirty: boolean;
+    approved: readonly {
+        id: string;
+        digest: string;
+    }[];
+    exclude: readonly string[];
+}): AttestProvenance;
+export declare function renderAttestText(r: AttestReport): string;
+export declare function renderAttestJson(r: AttestReport): string;
+/** Self-contained: no href, font, script or fetch. Only the ratio, the percentage and `at` go in. */
+export declare function renderAttestSvg(r: AttestReport): string;
+/** What goes between the markers. Carries the excludes, so the README says how to reproduce it. */
+export declare function renderAttestMarker(r: AttestReport): string;
+/**
+ * Replace what lies between the two markers — and ONLY when each appears exactly once, begin first.
+ * No marker is `no-marker`: the person never asked, so nothing is written. Anything else malformed is
+ * `unbalanced`: a lone begin marker followed by "replace to the end" is this feature's worst failure.
+ * The README's own line ending is kept, so a CRLF file does not become one whole-file diff.
+ */
+export declare function replaceMarkerRegion(readme: string, inner: string): {
+    ok: true;
+    text: string;
+    changed: boolean;
+} | {
+    ok: false;
+    reason: 'no-marker' | 'unbalanced';
+};

package/dist/holmes/rtm/traced-files.js

@@ -0,0 +1,207 @@
+"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.UNTRACED_LINE_CAP = exports.ATTEST_SCHEMA = exports.ATTEST_END = exports.ATTEST_BEGIN = void 0;
+exports.normalizeExcludes = normalizeExcludes;
+exports.flooredPct = flooredPct;
+exports.tracedFiles = tracedFiles;
+exports.attestProvenance = attestProvenance;
+exports.renderAttestText = renderAttestText;
+exports.renderAttestJson = renderAttestJson;
+exports.renderAttestSvg = renderAttestSvg;
+exports.renderAttestMarker = renderAttestMarker;
+exports.replaceMarkerRegion = replaceMarkerRegion;
+// @implements A-SPEC-702
+/**
+ * How many of a repository's source files trace to an APPROVED spec — said as a number anyone can
+ * reproduce, with the commit and spec-store state it was measured at.
+ *
+ * This exists INSTEAD of a "generated under holmes-kit" header in every file (REQ-702). A header is
+ * a claim: it can be pasted, and it keeps saying "governed" after an ungoverned edit. Line 1 already
+ * carries the `implements` anchor, which a gate verifies. What was missing is a repository-level
+ * statement, and the spec-side half of it (`linkCensus`) lived only inside the dashboard.
+ *
+ * NO NEW JUDGEMENT. The denominator is whatever the scanner returned, the numerator is anchors ∩
+ * approved ids. Everything here is pure — no clock, no filesystem, no git — so the same input is the
+ * same bytes and a committed badge does not churn. The CLI that feeds it is `cli/attest.ts`.
+ */
+const crypto = __importStar(require("node:crypto"));
+exports.ATTEST_BEGIN = '<!-- holmes-kit:attest:begin -->';
+exports.ATTEST_END = '<!-- holmes-kit:attest:end -->';
+exports.ATTEST_SCHEMA = 'holmes-attest/1';
+/** Above this many untraced files the text names none and points at `--json`. */
+exports.UNTRACED_LINE_CAP = 10;
+const posix = (p) => p.replace(/\\/g, '/').replace(/^\.\//, '');
+/**
+ * Backslashes folded, one trailing slash. A prefix that means "everything" is DROPPED: excluding the
+ * whole tree would read as n/a at best and 100% at worst (the same rule A-SPEC-694 pinned for
+ * `cycleIgnore`). Sorted and de-duplicated so the provenance does not depend on how it was typed.
+ */
+function normalizeExcludes(raw) {
+    const out = new Set();
+    for (const r of raw ?? []) {
+        const p = posix(String(r).trim()).replace(/^\/+/, '').replace(/\/+$/, '');
+        if (p === '' || p === '.')
+            continue;
+        out.add(p + '/');
+    }
+    return [...out].sort();
+}
+/** Floored to one decimal: 99.96 must not read as 100 — 100 means every file. */
+function flooredPct(num, den) {
+    if (den <= 0)
+        return null;
+    return Math.floor((num / den) * 1000) / 10;
+}
+function tracedFiles(input) {
+    const approved = new Set(input.approvedIds);
+    const excludes = normalizeExcludes(input.exclude);
+    let excluded = 0, traced = 0, total = 0;
+    const untraced = [];
+    for (const f of input.files) {
+        const p = posix(f.path);
+        // Boundary match: every prefix ends in '/', so `reference/` cannot pardon `reference-impl/`.
+        if (excludes.some((e) => p.startsWith(e))) {
+            excluded++;
+            continue;
+        }
+        total++;
+        if (f.anchors.some((id) => approved.has(id)))
+            traced++;
+        else
+            untraced.push(p);
+    }
+    untraced.sort();
+    const reason = total === 0 ? 'no source files' : approved.size === 0 ? 'no approved specs' : undefined;
+    return {
+        total, traced, excluded, untraced,
+        measurable: reason === undefined,
+        ...(reason !== undefined ? { reason } : {}),
+        tracedPct: reason === undefined ? flooredPct(traced, total) : null,
+    };
+}
+/**
+ * Where and when the number is true. `+dirty` because a commit alone would call an unreproducible
+ * number reproducible. The spec digest covers (id, seal) of every approved spec — that set is what
+ * decides the numerator. No clock anywhere.
+ */
+function attestProvenance(input) {
+    const lines = input.approved.map((a) => `${a.id}\t${a.digest}`).sort();
+    const specs = crypto.createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 12);
+    const commit = (input.commit ?? '').trim();
+    const at = commit === '' ? 'unversioned' : commit.slice(0, 12) + (input.dirty ? '+dirty' : '');
+    return { at, specs, exclude: normalizeExcludes(input.exclude) };
+}
+const pctText = (pct) => (pct === null ? 'n/a' : `${pct}%`);
+const ratio = (num, den, sep) => `${num}${sep}${den}`;
+function renderAttestText(r) {
+    const f = r.files;
+    const filesLine = f.measurable
+        ? `${ratio(f.traced, f.total, ' / ')} (${pctText(f.tracedPct)})`
+        : `n/a — ${f.reason}`;
+    const specPct = flooredPct(r.specs.linked, r.specs.total);
+    const specsLine = specPct === null ? 'n/a — no approved A-SPECs' : `${ratio(r.specs.linked, r.specs.total, ' / ')} (${pctText(specPct)})`;
+    const lines = [
+        `traced files   ${filesLine}   — source files anchored to an APPROVED spec`,
+        `linked specs   ${specsLine}   — approved A-SPECs anchored from code`,
+    ];
+    // Few enough to act on → name them; a wall of paths helps nobody, so beyond that point to --json.
+    if (f.measurable && f.untraced.length > 0) {
+        lines.push(f.untraced.length <= exports.UNTRACED_LINE_CAP
+            ? `untraced       ${f.untraced.join(', ')}`
+            : `untraced       ${f.untraced.length} file(s) — list them with --json`);
+    }
+    if (r.provenance.exclude.length > 0)
+        lines.push(`excluded       ${f.excluded} file(s) under: ${r.provenance.exclude.join(', ')}`);
+    lines.push(`at             ${r.provenance.at} · specs sha256:${r.provenance.specs}`);
+    return lines.join('\n') + '\n';
+}
+function renderAttestJson(r) {
+    return JSON.stringify({ schema: exports.ATTEST_SCHEMA, files: r.files, specs: r.specs, provenance: r.provenance }, null, 2) + '\n';
+}
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** Self-contained: no href, font, script or fetch. Only the ratio, the percentage and `at` go in. */
+function renderAttestSvg(r) {
+    const f = r.files;
+    const value = f.measurable ? `${ratio(f.traced, f.total, '/')} · ${pctText(f.tracedPct)}` : 'n/a';
+    const label = 'traced files';
+    const lw = 86, vw = Math.max(64, 14 + value.length * 7), w = lw + vw;
+    const colour = !f.measurable ? '#9f9f9f' : (f.tracedPct ?? 0) >= 90 ? '#2e7d32' : (f.tracedPct ?? 0) >= 60 ? '#b08900' : '#b3541e';
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="34" role="img" aria-label="${xml(label + ': ' + value)}">`,
+        `<title>${xml(label + ': ' + value + ' @ ' + r.provenance.at)}</title>`,
+        `<rect width="${lw}" height="20" fill="#444"/>`,
+        `<rect x="${lw}" width="${vw}" height="20" fill="${colour}"/>`,
+        `<g fill="#fff" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">`,
+        `<text x="${lw / 2}" y="14" text-anchor="middle">${xml(label)}</text>`,
+        `<text x="${lw + vw / 2}" y="14" text-anchor="middle">${xml(value)}</text>`,
+        `</g>`,
+        `<text x="0" y="31" fill="#666" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="9">${xml('at ' + r.provenance.at)}</text>`,
+        `</svg>`,
+    ].join('') + '\n';
+}
+/** What goes between the markers. Carries the excludes, so the README says how to reproduce it. */
+function renderAttestMarker(r) {
+    const f = r.files;
+    const files = f.measurable ? `**${ratio(f.traced, f.total, '/')}** source files (${pctText(f.tracedPct)}) trace to an approved spec` : `traced files: n/a — ${f.reason}`;
+    const specPct = flooredPct(r.specs.linked, r.specs.total);
+    const specs = specPct === null ? '' : ` · **${ratio(r.specs.linked, r.specs.total, '/')}** approved A-SPECs (${pctText(specPct)}) are anchored from code`;
+    const excl = r.provenance.exclude.length > 0 ? ` --exclude ${r.provenance.exclude.join(',')}` : '';
+    return [
+        `![traced files](.ax/badges/traced.svg)`,
+        ``,
+        `${files}${specs}.`,
+        `Measured at \`${r.provenance.at}\` (specs \`sha256:${r.provenance.specs}\`) — reproduce with \`holmes-kit attest${excl}\`.`,
+    ].join('\n');
+}
+const count = (hay, needle) => hay.split(needle).length - 1;
+/**
+ * Replace what lies between the two markers — and ONLY when each appears exactly once, begin first.
+ * No marker is `no-marker`: the person never asked, so nothing is written. Anything else malformed is
+ * `unbalanced`: a lone begin marker followed by "replace to the end" is this feature's worst failure.
+ * The README's own line ending is kept, so a CRLF file does not become one whole-file diff.
+ */
+function replaceMarkerRegion(readme, inner) {
+    const begins = count(readme, exports.ATTEST_BEGIN), ends = count(readme, exports.ATTEST_END);
+    if (begins === 0 && ends === 0)
+        return { ok: false, reason: 'no-marker' };
+    const b = readme.indexOf(exports.ATTEST_BEGIN), e = readme.indexOf(exports.ATTEST_END);
+    if (begins !== 1 || ends !== 1 || e < b)
+        return { ok: false, reason: 'unbalanced' };
+    const eol = readme.includes('\r\n') ? '\r\n' : '\n';
+    const body = inner.replace(/\r\n/g, '\n').split('\n').join(eol);
+    const text = readme.slice(0, b + exports.ATTEST_BEGIN.length) + eol + body + eol + readme.slice(e);
+    return { ok: true, text, changed: text !== readme };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.26.2",
+  "version": "0.27.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",