@holmes-lab/holmes-kit 0.19.5 → 0.20.0

package/dist/holmes/mcp/server.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HOOK_ENFORCED_TOOLS = void 0;
+// @implements A-SPEC-625, A-SPEC-564.1
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
@@ -35,6 +36,7 @@ const elicit = async (req) => {
 };
 const handlers = (0, handlers_1.makeHandlers)(store, {
     elicit,
+    observeInvocation: root => stampSession(root),
     clientName: () => { try {
         return server.getClientVersion()?.name ?? 'unknown';
     }
@@ -120,7 +122,6 @@ const TOOLS = Object.keys(handlers)
 });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
-    stampSession(req.params.arguments?.root);
     // @implements A-SPEC-189
     // The server is the first consumer of its own advertised schemas. Before this check, 15 of 26
     // handlers threw raw internal errors at `{}` over the wire, and a one-key typo in reverse_anchor

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

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
-// @implements A-SPEC-277
+// @implements A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627
+// @implements A-SPEC-642
+// @implements A-SPEC-641
+// @implements A-SPEC-639
+// @implements A-SPEC-632
 // @implements A-SPEC-269
 // @implements A-SPEC-267
 const spec_types_1 = require("../spec/spec-types");
@@ -31,6 +35,31 @@ const ROOT_ANY = str('Absolute path to the project root. Version control is opti
 // the rest of the tool metadata and has no import side effects.
 exports.HOOK_ENFORCED_TOOLS = new Set(['phase_check', 'risk_check', 'rtm_check', 'spec_validate']);
 exports.TOOL_SCHEMAS = {
+    entity_integrate: {
+        description: 'Plan integration of fixed common-ancestor Git inputs for the configured adopted store, apply an exact approved plan, inspect an operation recovery-plan, or recover it with current authority. Preserves entity UUIDs and explicit conflicts, coordinates store/source ownership, journals publication and records completion audit and derived-state obligations. Leaves Git refs/index unchanged. Completed retries verify existing evidence without republishing. discharge rebuilds this replica\'s graph and semantic cache for a completed operation and records one immutable discharge.json bound to its obligations; obligations lists completed operations with pending, discharged or invalid obligations (read-only). abandon rolls a pending operation a third state blocked back to its own before-bytes, preserves foreign bytes, releases ownership and audits the abandonment. Unsupported inputs remain explicit blockers; no implicit adoption or approval.',
+        inputSchema: { type: 'object', properties: { root: ROOT_ANY, operation: { type: 'string', enum: ['plan', 'apply', 'recovery-plan', 'recover', 'abandon', 'discharge', 'obligations'] },
+                base: str('Common ancestor Git revision.'), left: str('First input Git revision.'), right: str('Second input Git revision.'),
+                operationId: str('Integration operation UUID returned in the original plan; required for recovery-plan and discharge.'), plan: { type: 'object', description: 'The entire unchanged plan returned by plan or recovery-plan.' } } },
+    },
+    entity_renumber: {
+        description: 'Plan, apply, inspect recovery-plan and recover UUID-preserving display-ID, dependency and source-comment anchor changes for the configured adopted spec store. Reports prose and coverage diagnostics. Application and recovery require the exact inspected plan and current specification authority; recovery revalidates source and official seal transitions, preserves external edits and resumes remaining journal steps. No implicit adoption or approval.',
+        inputSchema: { type: 'object', properties: { root: ROOT_ANY, operation: { type: 'string', enum: ['plan', 'apply', 'recovery-plan', 'recover', 'abandon'] }, changes: { type: 'array', items: { type: 'object', properties: { entityId: { type: 'string' }, newDisplayId: { type: 'string' } }, required: ['entityId', 'newDisplayId'], additionalProperties: false } }, plan: { type: 'object' } } },
+    },
+    entity_store: {
+        description: 'Inspect or plan entity adoption without writes by default. Explicit adopt requires config-write approval for the exact returned plan and preserves sealed document bytes. Adopted stores retain entity identity through journaled document creation, edits and classification moves. recovery-plan reports interrupted targets without changing them. recover requires separate exact-plan approval to complete interrupted transactions or release locks for verified completed writes. Sealing, unsealing and retirement additionally require current spec-approve authority for the affected ID and the same transition policy as official spec tools. Live or unknown owners, external changes and noncanonical transitions refuse. Recovery audit completion across crashes remains under development.',
+        inputSchema: { type: 'object', properties: { root: ROOT_ANY, operation: { type: 'string', enum: ['status', 'plan-adoption', 'adopt', 'recovery-plan', 'recover'] }, plan: { type: 'object', description: 'The complete unmodified plan returned by plan-adoption or recovery-plan.' } } },
+    },
+    workspace_identity: {
+        description: 'Inspect canonical workspace and local replica identity without writes by default. Explicit initialize creates a Git-shareable .ax/workspace.json and registers this checkout; register requires an existing canonical identity. Preserve legacy specs and ledgers; these identifiers grant no approval authority. Share the manifest through Git and keep .ax/state local. Registered MCP writes include holmes-execution/1 provenance and require a reader supporting that schema; matching package versions alone do not establish this capability.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                operation: { type: 'string', enum: ['status', 'initialize', 'register'], description: 'Defaults to read-only status; initialize and register explicitly write identity records.' },
+            },
+            required: ['root'],
+        },
+    },
     // @implements A-SPEC-156
     // The full basis behind every other answer. It is a separate tool, not a field, because carrying
     // the whole object on all responses is what REQ-122 forbids — the digest rides along, the detail
@@ -126,7 +155,7 @@ exports.TOOL_SCHEMAS = {
         },
     },
     approval_status: {
-        description: "Read-only: report ONE spec's approval/seal state without the caller parsing files — { sealed, approvedDigest?, status, parents: [{ id, status, sealed, resolved }], blockers: [] }. `sealed` is the same approved_digest predicate the code gate reads; `blockers` is the exact list spec_approve would refuse on (empty once approved), so the report cannot drift from the acts it describes. Each parent entry shows that parent's OWN live seal state (an unresolved depends_on id is reported as status:'missing', resolved:false — not dropped). No writes, no ledger append. Refuses a duplicate or unknown id.",
+        description: "Read-only: report ONE spec's approval/seal state without the caller parsing files — { sealed, approvedDigest?, status, parents: [{ id, status, sealed, resolved }], blockers: [], resealBlockers: [] }. `sealed` is the same approved_digest predicate the code gate reads; `blockers` is the exact list spec_approve would refuse on (empty once approved), so the report cannot drift from the acts it describes; `resealBlockers` is that same predicate evaluated on the document as it stands, reported for approved documents too — what a re-seal (spec_approve again, entity_renumber, entity_integrate, store recovery) would be refused on, e.g. a hand-sealed chain whose parent kind violates the rule, or a legacy A-SPEC without its declarations. Each parent entry shows that parent's OWN live seal state (an unresolved depends_on id is reported as status:'missing', resolved:false — not dropped). No writes, no ledger append. Refuses a duplicate or unknown id.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -146,6 +175,18 @@ exports.TOOL_SCHEMAS = {
             },
         },
     },
+    ledger_reconcile: {
+        description: "Reconcile ONE cross-replica double-spend in the merged provenance ledger: a single-use approval nonce consumed on two or more replicas while offline. Requires an out-of-band HOLMES_APPROVAL (or grant) of kind \"ledger-reconcile\" whose target is that nonce input (e.g. \"nonce:91ad2a8ad9a1\"); appends `nonce-double-spend-reconciled` on this replica's chain referencing the nonce and every consuming event's hash, after which verifyAll, the Stop hook, baseline trust and the ledger-conflict refusals (spec_approve, spec_unseal, spec_retire, review_record, entity acts, risk_check, the shell gate) clear. { ok, reconciled, nonce, events, remaining } — `reconciled: false` with `pending` when the nonce is not an unreconciled double-spend. Refuses while any chain is broken (audit-conflict). Never erases a consumption.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                nonce: str('The nonce input exactly as verifyAll / doubleSpends names it (usually the fingerprint form "nonce:<12 hex>").'),
+                rationale: str('Why the double-spend is accepted as reconciled (recorded on the event; defaults to the approval rationale).'),
+                root: str('Optional when the server is bound to a file store; if supplied it must resolve to the SAME project.'),
+            },
+            required: ['nonce'],
+        },
+    },
     rtm_dashboard: {
         description: "Launch (idempotently) the interactive RTM/CPG dashboard the agent would otherwise start by hand, and return { ok, url, running, census } — use it when a human asks to SEE the RTM heatmap / coverage matrix / dashboard. `url` is the localhost address to open; `running` is true when an already-live server for this project was reused (a second call never starts a second server). `census` is an honesty summary of what the dashboard shows — { reqCount, pipelineCount, coveredCount, coveragePct, retiredCount, findingsScanned } — so the caller can report coverage without scraping the page. No spec writes, no ledger append. Refuses when a supplied `root` points at a different project than the server is bound to.",
         inputSchema: {

package/dist/holmes/project/execution-context.d.ts

@@ -0,0 +1,17 @@
+export interface ExecutionContext {
+    readonly schema: 'holmes-execution/1';
+    readonly workspaceId: string;
+    readonly replicaId: string;
+    readonly runId: string;
+}
+export declare function validateExecution(value: unknown): ExecutionContext;
+/** Internal entry-point boundary; an unavailable operator identity explicitly clears ambient scope. */
+export declare function withOwnedExecution<T>(root: string, execution: ExecutionContext | undefined, act: () => T): T;
+/** Writers may inherit only the context of the actual checkout that owns them. */
+export declare function executionForRoot(root: string): ExecutionContext | undefined;
+/** A handler factory owns one run; neither request payload nor a global last-root can set it. */
+export declare function createExecutionScope(storeRoot?: string, observe?: (root: string) => void | Promise<void>): <T>(askedRoot: string | undefined, act: () => Promise<T>) => Promise<T>;
+/** Validate observation attribution before an append; absence is never inferred from bad input. */
+export declare function observationExecution(root: string, record: {
+    execution?: unknown;
+}): ExecutionContext | undefined;

package/dist/holmes/project/execution-context.js

@@ -0,0 +1,120 @@
+"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.validateExecution = validateExecution;
+exports.withOwnedExecution = withOwnedExecution;
+exports.executionForRoot = executionForRoot;
+exports.createExecutionScope = createExecutionScope;
+exports.observationExecution = observationExecution;
+// @implements A-SPEC-624, A-SPEC-625, A-SPEC-626
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const root_1 = require("./root");
+const workspace_identity_1 = require("./workspace-identity");
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function validateExecution(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid execution context');
+    const v = value;
+    if (Object.keys(v).length !== 4 || v.schema !== 'holmes-execution/1' ||
+        !['workspaceId', 'replicaId', 'runId'].every(k => typeof v[k] === 'string' && uuid.test(v[k]))) {
+        throw new Error('Invalid execution context schema, fields or UUID');
+    }
+    return Object.freeze({ schema: 'holmes-execution/1', workspaceId: v.workspaceId, replicaId: v.replicaId, runId: v.runId });
+}
+const scope = new node_async_hooks_1.AsyncLocalStorage();
+/** Internal entry-point boundary; an unavailable operator identity explicitly clears ambient scope. */
+function withOwnedExecution(root, execution, act) {
+    const owned = execution ? { root: fs.realpathSync(root), execution: validateExecution(execution) } : undefined;
+    return scope.run(owned, act);
+}
+/** Writers may inherit only the context of the actual checkout that owns them. */
+function executionForRoot(root) {
+    const active = scope.getStore();
+    if (!active)
+        return undefined;
+    let actual = path.resolve(root);
+    if (fs.existsSync(actual))
+        actual = fs.realpathSync(actual);
+    if (actual !== active.root)
+        throw new workspace_identity_1.WorkspaceIdentityError('foreign-execution', 'The writer belongs to a different execution workspace.');
+    return active.execution;
+}
+/** A handler factory owns one run; neither request payload nor a global last-root can set it. */
+function createExecutionScope(storeRoot, observe) {
+    const runId = (0, node_crypto_1.randomUUID)();
+    return async (askedRoot, act) => {
+        if (storeRoot === undefined)
+            return scope.run(undefined, act);
+        let ancestor = path.resolve(storeRoot);
+        while (!fs.existsSync(ancestor) && path.dirname(ancestor) !== ancestor)
+            ancestor = path.dirname(ancestor);
+        const bound = (0, root_1.resolveProjectRoot)(ancestor);
+        if (bound.marker !== '.ax')
+            return scope.run(undefined, act);
+        const invoke = async () => {
+            try {
+                await observe?.(bound.root);
+            }
+            catch { /* observation does not change the act */ }
+            return act();
+        };
+        const identity = (0, workspace_identity_1.workspaceIdentity)(bound.root);
+        if (identity.state === 'legacy')
+            return scope.run(undefined, invoke);
+        if (askedRoot !== undefined && (0, root_1.resolveProjectRoot)(askedRoot).root !== bound.root) {
+            throw new workspace_identity_1.WorkspaceIdentityError('foreign-workspace', 'The requested workspace differs from the configured spec store.');
+        }
+        if (identity.state !== 'registered')
+            throw new workspace_identity_1.WorkspaceIdentityError('unregistered-replica', 'Register this replica through workspace_identity before governance writes.');
+        const execution = validateExecution({ schema: 'holmes-execution/1', workspaceId: identity.workspaceId, replicaId: identity.replicaId, runId });
+        return scope.run({ root: fs.realpathSync(bound.root), execution }, invoke);
+    };
+}
+/** Validate observation attribution before an append; absence is never inferred from bad input. */
+function observationExecution(root, record) {
+    const active = executionForRoot(root);
+    const supplied = 'execution' in record ? validateExecution(record.execution) : undefined;
+    if (active && supplied && JSON.stringify(active) !== JSON.stringify(supplied))
+        throw new Error('Observation execution differs from owned run');
+    if (!active && supplied) {
+        const identity = (0, workspace_identity_1.workspaceIdentity)(root);
+        if (identity.state !== 'registered' || identity.workspaceId !== supplied.workspaceId || identity.replicaId !== supplied.replicaId)
+            throw new Error('Observation execution differs from workspace registration');
+    }
+    return active ?? supplied;
+}

package/dist/holmes/project/installer-markers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The marks by which holmes-kit's installer claims text as ITS OWN — the `.gitignore`/`.gitattributes`
+ * block delimiters and the installed-skill marker — with the ownership judgement built on them.
+ *
+ * They live under `project/` rather than `cli/` because two layers need one definition: the installer
+ * (cli) writes them, and the entity source walk (spec/) must ignore exactly what the installer wrote
+ * (A-SPEC-646). Measured 2026-09-14: with the definitions in `cli/`, the walk's import was a C-SPEC-224
+ * forbidden edge (`spec/ -x-> cli/`); duplicating the strings would let what is written and what is
+ * ignored drift apart.
+ */
+export declare const HOLMES_BLOCK_BEGIN = "# >>> holmes-kit >>>";
+export declare const HOLMES_BLOCK_END = "# <<< holmes-kit <<<";
+/**
+ * Marks a file as OURS. Ownership is decided by this marker and never by the path, because the path
+ * is exactly what a user's own skill of the same name would occupy, and overwriting that would be
+ * the same class of error as clobbering their settings.
+ */
+export declare const PLAYBOOK_SKILL_MARKER = "<!-- installed by holmes-kit; edits will be replaced on upgrade -->";
+/**
+ * @implements A-SPEC-190 (round 7)
+ * Ownership is the marker AT ITS PLACE, not the string anywhere in the file. `includes` made any
+ * document that merely QUOTES the marker — documentation about holmes-kit, a review note — read as
+ * ours: doctor called it `drifted` and the refresh it advised overwrote the user's file with no
+ * backup. A quotation is not a claim of ownership.
+ */
+export declare function carriesMarker(content: string): boolean;
+/**
+ * @implements A-SPEC-190 (round 8)
+ * Where a leading YAML frontmatter block ends, or null. Round-8 measured the shapes the first
+ * regex missed — a BOM, an EMPTY block (`---\n---\n`), and a closing fence at end-of-file with no
+ * trailing newline — each of which sent the marker back to byte 0, recreating the CRITICAL the
+ * round-7 fix existed to remove while doctor certified the result as `current`.
+ */
+export declare function frontmatterEnd(content: string): number | null;

package/dist/holmes/project/installer-markers.js

@@ -0,0 +1,65 @@
+"use strict";
+// @implements A-SPEC-646
+// @implements A-SPEC-190
+/**
+ * The marks by which holmes-kit's installer claims text as ITS OWN — the `.gitignore`/`.gitattributes`
+ * block delimiters and the installed-skill marker — with the ownership judgement built on them.
+ *
+ * They live under `project/` rather than `cli/` because two layers need one definition: the installer
+ * (cli) writes them, and the entity source walk (spec/) must ignore exactly what the installer wrote
+ * (A-SPEC-646). Measured 2026-09-14: with the definitions in `cli/`, the walk's import was a C-SPEC-224
+ * forbidden edge (`spec/ -x-> cli/`); duplicating the strings would let what is written and what is
+ * ignored drift apart.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAYBOOK_SKILL_MARKER = exports.HOLMES_BLOCK_END = exports.HOLMES_BLOCK_BEGIN = void 0;
+exports.carriesMarker = carriesMarker;
+exports.frontmatterEnd = frontmatterEnd;
+exports.HOLMES_BLOCK_BEGIN = '# >>> holmes-kit >>>';
+exports.HOLMES_BLOCK_END = '# <<< holmes-kit <<<';
+/**
+ * Marks a file as OURS. Ownership is decided by this marker and never by the path, because the path
+ * is exactly what a user's own skill of the same name would occupy, and overwriting that would be
+ * the same class of error as clobbering their settings.
+ */
+exports.PLAYBOOK_SKILL_MARKER = '<!-- installed by holmes-kit; edits will be replaced on upgrade -->';
+/**
+ * @implements A-SPEC-190 (round 7)
+ * Ownership is the marker AT ITS PLACE, not the string anywhere in the file. `includes` made any
+ * document that merely QUOTES the marker — documentation about holmes-kit, a review note — read as
+ * ours: doctor called it `drifted` and the refresh it advised overwrote the user's file with no
+ * backup. A quotation is not a claim of ownership.
+ */
+function carriesMarker(content) {
+    // Round-8: judging on raw bytes made ownership brittle in the direction that cannot be repaired.
+    // A CRLF normalisation (a Windows editor, `core.autocrlf`, `.gitattributes eol=crlf`), a BOM, or a
+    // trailing space on the marker line each turned a file the kit itself wrote into `foreign` —
+    // permanently, since install then skips it forever and doctor advises deleting it as "yours".
+    // Whitespace and line endings are not ownership; the marker is.
+    const text = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const markerAt = (s) => {
+        const line = s.split('\n', 1)[0];
+        return line.trimEnd() === exports.PLAYBOOK_SKILL_MARKER;
+    };
+    if (markerAt(text))
+        return true; // 옛 배치(마커 먼저) — 우리 것이므로 고칠 수 있다
+    const fm = frontmatterEnd(text);
+    // 빈 줄 하나가 소유를 지우지 않는다(round-9: frontmatter 뒤 개행 하나로 영구 foreign 이 됐다).
+    return fm !== null && markerAt(text.slice(fm).replace(/^\s*\n/, ''));
+}
+/**
+ * @implements A-SPEC-190 (round 8)
+ * Where a leading YAML frontmatter block ends, or null. Round-8 measured the shapes the first
+ * regex missed — a BOM, an EMPTY block (`---\n---\n`), and a closing fence at end-of-file with no
+ * trailing newline — each of which sent the marker back to byte 0, recreating the CRITICAL the
+ * round-7 fix existed to remove while doctor certified the result as `current`.
+ */
+function frontmatterEnd(content) {
+    const text = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    if (!/^---[ \t]*(\n|$)/.test(text))
+        return null;
+    const m = /\n---[ \t]*(\n|$)/.exec(text.slice(3));
+    if (!m)
+        return null;
+    return 3 + m.index + m[0].length;
+}

package/dist/holmes/project/root.d.ts

@@ -45,4 +45,6 @@ export declare const MARKER = ".ax";
  * makes: one spelling per directory, the spelling every path key is built from.
  */
 export declare const canonicalPath: (p: string) => string;
-export declare function resolveProjectRoot(dir: string): ProjectRoot;
+export declare function resolveProjectRoot(dir: string, opts?: {
+    includeGit?: boolean;
+}): ProjectRoot;

package/dist/holmes/project/root.js

@@ -37,7 +37,7 @@ exports.canonicalPath = exports.MARKER = void 0;
 exports.cleanSubprocessEnv = cleanSubprocessEnv;
 exports.cleanTestEnv = cleanTestEnv;
 exports.resolveProjectRoot = resolveProjectRoot;
-// @implements A-SPEC-205
+// @implements A-SPEC-205, A-SPEC-627
 // @implements A-SPEC-128
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -127,7 +127,7 @@ function gitTopLevel(dir) {
         return undefined;
     }
 }
-function resolveProjectRoot(dir) {
+function resolveProjectRoot(dir, opts = {}) {
     let start;
     try {
         start = canonical(path.resolve(dir));
@@ -165,6 +165,7 @@ function resolveProjectRoot(dir) {
             break;
     }
     const root = found ?? start;
-    const topLevel = gitTopLevel(root);
+    // Storage readers need the canonical workspace boundary, not a subprocess on every document.
+    const topLevel = opts.includeGit === false ? undefined : gitTopLevel(root);
     return { root, marker: found ? exports.MARKER : 'given', ...(topLevel ? { git: { topLevel } } : {}) };
 }

package/dist/holmes/project/workspace-identity.d.ts

@@ -0,0 +1,29 @@
+export type IdentityOperation = 'status' | 'initialize' | 'register';
+export interface WorkspaceManifest {
+    schema: 'holmes-workspace/1';
+    workspaceId: string;
+}
+export interface WorkspaceReplica {
+    schema: 'holmes-workspace-replica/1';
+    workspaceId: string;
+    replicaId: string;
+}
+export type WorkspaceIdentityStatus = {
+    ok: true;
+    state: 'legacy';
+} | {
+    ok: true;
+    state: 'initialized';
+    workspaceId: string;
+} | {
+    ok: true;
+    state: 'registered';
+    workspaceId: string;
+    replicaId: string;
+};
+export declare class WorkspaceIdentityError extends Error {
+    readonly code: string;
+    readonly holmesRefusal = true;
+    constructor(code: string, message: string);
+}
+export declare function workspaceIdentity(rootArg: string, operation?: IdentityOperation): WorkspaceIdentityStatus;

package/dist/holmes/project/workspace-identity.js

@@ -0,0 +1,181 @@
+"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.WorkspaceIdentityError = void 0;
+exports.workspaceIdentity = workspaceIdentity;
+// @implements A-SPEC-623
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const root_1 = require("./root");
+class WorkspaceIdentityError extends Error {
+    code;
+    holmesRefusal = true;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkspaceIdentityError';
+    }
+}
+exports.WorkspaceIdentityError = WorkspaceIdentityError;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const errno = (e, code) => e?.code === code;
+function directory(file, optional = false) {
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (optional && errno(e, 'ENOENT'))
+            return false;
+        throw e;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new WorkspaceIdentityError('unsafe-path', 'Identity directories must be real directories, not symlinks.');
+    return true;
+}
+function readRecord(file, local) {
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (errno(e, 'ENOENT'))
+            return null;
+        throw e;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new WorkspaceIdentityError('unsafe-path', 'Identity must be a regular file, not a symlink.');
+    let value;
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino)
+            throw new WorkspaceIdentityError('identity-changed', 'Identity changed while opening; retry.');
+        try {
+            value = JSON.parse(fs.readFileSync(fd, 'utf8'));
+        }
+        catch (e) {
+            if (e instanceof SyntaxError)
+                throw new WorkspaceIdentityError('invalid-identity', 'Identity contains invalid JSON; preserve and repair it explicitly.');
+            throw e;
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const schema = local ? 'holmes-workspace-replica/1' : 'holmes-workspace/1';
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new WorkspaceIdentityError('invalid-identity', 'Identity must be a schema-versioned object.');
+    const record = value, keys = local ? ['schema', 'workspaceId', 'replicaId'] : ['schema', 'workspaceId'];
+    if (record.schema !== schema || Object.keys(record).length !== keys.length || keys.some(k => !(k in record))
+        || typeof record.workspaceId !== 'string' || !uuid.test(record.workspaceId)
+        || (local && (typeof record.replicaId !== 'string' || !uuid.test(record.replicaId)))) {
+        throw new WorkspaceIdentityError('invalid-identity', 'Unsupported schema, fields or identifier; existing identity was not replaced.');
+    }
+    return local ? record : record;
+}
+/** Complete bytes first, then one atomic no-replace link. Never fall back to overwriting a winner. */
+function publish(file, record) {
+    const temp = path.join(path.dirname(file), `.identity-${(0, node_crypto_1.randomUUID)()}.tmp`);
+    let owned = false;
+    try {
+        const fd = fs.openSync(temp, 'wx', 0o600);
+        owned = true;
+        try {
+            fs.writeFileSync(fd, JSON.stringify(record) + '\n');
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        try {
+            fs.linkSync(temp, file);
+        }
+        catch (e) {
+            if (!errno(e, 'EEXIST'))
+                throw e;
+        }
+    }
+    finally {
+        if (owned)
+            fs.unlinkSync(temp);
+    }
+}
+function workspaceIdentity(rootArg, operation = 'status') {
+    if (!['status', 'initialize', 'register'].includes(operation))
+        throw new WorkspaceIdentityError('invalid-operation', 'Use status, initialize or register.');
+    const resolved = (0, root_1.resolveProjectRoot)(rootArg, { includeGit: false });
+    if (resolved.marker !== '.ax')
+        throw new WorkspaceIdentityError('missing-workspace', 'An existing Holmes .ax workspace marker is required.');
+    const ax = path.join(resolved.root, '.ax'), state = path.join(ax, 'state');
+    directory(ax);
+    const canonicalFile = path.join(ax, 'workspace.json'), localFile = path.join(state, 'workspace-replica.json');
+    let canonical = readRecord(canonicalFile, false);
+    let local = directory(state, true) ? readRecord(localFile, true) : null;
+    if (local && (!canonical || local.workspaceId !== canonical.workspaceId))
+        throw new WorkspaceIdentityError('workspace-mismatch', 'Local registration does not belong to the canonical workspace; it was preserved.');
+    if (!canonical) {
+        if (operation === 'status')
+            return { ok: true, state: 'legacy' };
+        if (operation === 'register')
+            throw new WorkspaceIdentityError('uninitialized', 'Initialize and share the canonical workspace identity before registering a replica.');
+        publish(canonicalFile, { schema: 'holmes-workspace/1', workspaceId: (0, node_crypto_1.randomUUID)() });
+        canonical = readRecord(canonicalFile, false);
+        if (!canonical)
+            throw new WorkspaceIdentityError('identity-changed', 'Canonical identity disappeared during initialization; retry.');
+    }
+    if (!local && operation !== 'status') {
+        try {
+            fs.mkdirSync(state);
+        }
+        catch (e) {
+            if (!errno(e, 'EEXIST'))
+                throw e;
+        }
+        directory(state);
+        publish(localFile, { schema: 'holmes-workspace-replica/1', workspaceId: canonical.workspaceId, replicaId: (0, node_crypto_1.randomUUID)() });
+        local = readRecord(localFile, true);
+        if (!local)
+            throw new WorkspaceIdentityError('identity-changed', 'Local registration disappeared during initialization; retry.');
+    }
+    const current = readRecord(canonicalFile, false);
+    if (!current || current.workspaceId !== canonical.workspaceId || (local && local.workspaceId !== canonical.workspaceId)) {
+        throw new WorkspaceIdentityError('workspace-mismatch', 'Workspace identity changed during registration; preserve records and resolve the mismatch.');
+    }
+    return local
+        ? { ok: true, state: 'registered', workspaceId: canonical.workspaceId, replicaId: local.replicaId }
+        : { ok: true, state: 'initialized', workspaceId: canonical.workspaceId };
+}

package/dist/holmes/review/test-outcomes.d.ts

@@ -1,3 +1,4 @@
+import { ExecutionContext } from '../project/execution-context';
 import { TestOutcome } from './test-runner';
 export declare const OUTCOMES_FILE: string;
 export declare function outcomesFilename(replica: string): string;
@@ -10,6 +11,7 @@ export declare function isOutcomesFilename(name: string): boolean;
  * still dirty, which is exactly when the Stop gate reads them.
  */
 export interface OutcomeRecord {
+    execution?: ExecutionContext;
     aspec: string;
     outcome: TestOutcome;
     ts: string;
@@ -44,7 +46,10 @@ export declare function buildOutcomeRecords(outcomeByFile: Record<string, TestOu
  * Group outcomes by A-SPEC, keeping only records stamped with the given baseline `head` — a stale
  * record from another commit cannot vouch for the current work (the isFresh discipline). Pure.
  */
-export declare function groupOutcomesByAspec(records: OutcomeRecord[], head: string): Record<string, Array<{
+export declare function groupOutcomesByAspec(records: OutcomeRecord[], head: string, 
+/** @implements A-SPEC-645 — maps a record's display id to the id the entity carries now (from the ledger's renames). */
+canonical?: (id: string) => string): Record<string, Array<{
     outcome: TestOutcome;
     ts: string;
+    execution?: ExecutionContext;
 }>>;