@holmes-lab/holmes-kit 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -5,6 +5,71 @@ 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
+now be executed — the plan a person saw, under one approval, before the merge.
+
+### Added
+- **`spec_reconcile` — the seen plan, one approval, before the merge** (A-SPEC-700.2). 0.26.1 detected a
+  spec number another machine took and printed the plan; executing it was still a person calling
+  `spec_renumber` once per family. `spec_reconcile({operation:'plan'})` is read-only: it chains the
+  existing collectors, collision detector, planner and `planRenumber` — no new judgement — and returns
+  the moves, how many documents / `depends_on` / anchors each rewrites, the re-seal order, the prose
+  candidates, and a `target` derived from the plan's content alone (no clock, no nonce: the same state
+  plans to the same target). `apply` takes that plan back, **rebuilds it inside the store hold**, and
+  refuses `plan-changed` if it is no longer the one that was seen — a fetch in between may have given
+  the destination away. It then demands one `config-write` approval bound to `target`, and runs every
+  move through the same path `spec_renumber` uses. Found while building it: `spec_renumber`'s own apply
+  asks for **no approval at all**, although it rewrites approved documents and source anchors; this
+  tool is the first path that honours REQ-700's "one approval" constraint, and the standalone tool is
+  unchanged (a separate decision). It never seals — `spec_approve` stays the only sealer, and the order
+  is returned. Prose is reported, never rewritten. No remote, or no git, is an answer (`moves: []` with
+  a note), not a refusal. Measured cost: the tool adds ≈414 schema tokens (41 tools ≈ 10,724).
+  An adversarial pass **run, not read**: forged `moves` under a true `target` are never read (what runs
+  is the recomputed plan); a grant is spent once and a refused apply spends nothing; a second move that
+  stops reports `moved` / `remaining` and planning again yields only the rest. It found one defect,
+  fixed here: with two colliding families that depend on each other, the re-seal order named a document
+  a sibling move had already renamed.
+- `doctor`'s collision advice now ends by naming the tool: `… then re-seal with spec_approve, and merge
+  (spec_reconcile plan → apply runs every move under one approval)`.
+
+### Fixed
+- **A finished entity operation is no longer read as "interrupted" or "vanished"** (A-SPEC-701). The
+  pending-operation scan read each `journal.json` twice while retirement is a single rename, so a scan
+  racing a retirement could see the journal on the first read and not the second, and refuse
+  `recovery-required` for work that had just completed — measured as the Linux CI red on
+  `entity-store-boundaries` at a commit that changed no code. The scan reads once and skips an
+  operation whose directory has retired; the set of legal outcomes is not widened.
+
 ## [0.26.1] - 2026-09-20
 
 Three judgements that were computed and reached nobody now reach a person, and a spec number another

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,8 @@
 
 ### 🛡️ 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.
 - 🧬 **Declare your architecture, in every language the graph can follow** *(new in 0.26.0)*: a C-SPEC's `## Forbidden Edges` takes a third rule kind beside `import` and `call` — `- inherits src/app -x-> ConcreteBase`, an exact match enforced at the pre-edit gate. Nothing is inferred: the rule reads the graph's `inherits` edges and never asks which class is "abstract", which is what makes it hold in Go, where interface satisfaction cannot be inferred at all. A project that already breaks the rule it wants adopts it with a **baseline that expires** — `- allow until 2026-09-27 : inherits src/legacy/a.ts -> LegacyBase`, exact on kind, file and target, never a prefix. Past its date the allowance still holds, because an expiry that blocked would turn the rule into a barrier to adoption; it is **reported** instead, carrying `(reconfirmed n since <date>)` so a twelfth renewal cannot hide.

package/dist/.build-id

@@ -1 +1 @@
-256f1396-mu9du216
+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/mcp/handlers/spec-lifecycle.d.ts

@@ -1,5 +1,6 @@
 import { SpecStore } from '../../spec/spec-store';
 import { Approval } from '../../guardrail/risk-gate';
+import { type RenumberPlan } from '../../spec/renumber';
 export interface SpecLifecycleContext {
     store: SpecStore;
     resolveLedgerRoot(root?: string): {
@@ -64,6 +65,19 @@ export declare function createSpecLifecycleHandlers(context: SpecLifecycleContex
         dependents: string[];
         reason?: undefined;
     }>;
+    /**
+     * @implements A-SPEC-700.2
+     * The plan a person SAW, executed under ONE approval, before the merge. `plan` reads; `apply`
+     * rebuilds the plan, refuses `plan-changed` if it is not the one that was seen, demands a
+     * `config-write` approval bound to the plan's `target`, then runs every move through the SAME
+     * path `spec_renumber` uses, inside one store hold. It never seals: `spec_approve` is the only
+     * sealer, so `approveOrder` is returned and the caller runs it.
+     */
+    spec_reconcile(a: {
+        root?: string;
+        operation?: string;
+        plan?: unknown;
+    }): Promise<Record<string, unknown>>;
     spec_renumber(a: {
         root?: string;
         oldBase: string;
@@ -79,13 +93,13 @@ export declare function createSpecLifecycleHandlers(context: SpecLifecycleContex
     } | {
         ok: boolean;
         dryRun: boolean;
-        plan: import("../../spec/renumber").RenumberPlan;
+        plan: RenumberPlan;
         movedSpecs?: undefined;
     } | {
         ok: boolean;
         dryRun: boolean;
         movedSpecs: number;
-        plan: import("../../spec/renumber").RenumberPlan;
+        plan: RenumberPlan;
     }>;
     /**
      * @implements A-SPEC-538.1