@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/server-specs-dir.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_SERVER_SPECS = ".ax/specs";
+export declare function resolveServerSpecsDir(env: NodeJS.ProcessEnv, cwd: string, exists?: (p: string) => boolean): string;

package/dist/holmes/mcp/server-specs-dir.js

@@ -0,0 +1,71 @@
+"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.DEFAULT_SERVER_SPECS = void 0;
+exports.resolveServerSpecsDir = resolveServerSpecsDir;
+// @implements A-SPEC-652.2
+/**
+ * Where the MCP server's spec store is. `HOLMES_SPECS` is written RELATIVE by `init` (`.ax/specs`,
+ * so the wiring file stays portable across machines) and used to be resolved against whatever cwd
+ * the server got. Measured 2026-09-14: a session's server refused every store-bound tool with
+ * "바인딩된 스펙 디렉터리 .ax/specs 가 존재하지 않습니다" — its cwd was not the project.
+ *
+ * The base for a relative path is, in order: `CLAUDE_PROJECT_DIR` (Claude Code sets it for every
+ * stdio MCP server to the stable project root — code.claude.com/docs/en/mcp), then the nearest
+ * ancestor of cwd holding `.mcp.json` or `.ax` (a server started in a sub-directory, or by a harness
+ * that sets no variable), then cwd itself (the old behaviour, for a project that has not run `init`).
+ * The answer is always absolute, so every refusal can name the directory it looked at.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.DEFAULT_SERVER_SPECS = '.ax/specs';
+function resolveServerSpecsDir(env, cwd, exists = fs.existsSync) {
+    const configured = env.HOLMES_SPECS && env.HOLMES_SPECS.trim() !== '' ? env.HOLMES_SPECS : exports.DEFAULT_SERVER_SPECS;
+    if (path.isAbsolute(configured))
+        return path.normalize(configured);
+    const projectDir = env.CLAUDE_PROJECT_DIR;
+    if (projectDir && projectDir.trim() !== '' && exists(projectDir))
+        return path.resolve(projectDir, configured);
+    let dir = path.resolve(cwd);
+    for (;;) {
+        if (exists(path.join(dir, '.mcp.json')) || exists(path.join(dir, '.ax')))
+            return path.resolve(dir, configured);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return path.resolve(cwd, configured);
+}

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");
@@ -10,7 +11,16 @@ const tool_schemas_1 = require("./tool-schemas");
 Object.defineProperty(exports, "HOOK_ENFORCED_TOOLS", { enumerable: true, get: function () { return tool_schemas_1.HOOK_ENFORCED_TOOLS; } });
 const validate_args_1 = require("./validate-args");
 // @implements A-SPEC-100.2
-const store = new spec_store_1.LocalMarkdownRepository(process.env.HOLMES_SPECS ?? '.ax/specs');
+// @implements A-SPEC-652.2 — the store is opened at an ABSOLUTE path resolved against the project
+// root (CLAUDE_PROJECT_DIR, then the nearest .mcp.json/.ax ancestor, then cwd), and the path is
+// logged once to stderr (stdout is the protocol channel) so a mis-bound server is diagnosable.
+const { resolveServerSpecsDir } = require('./server-specs-dir');
+const SPECS_DIR = resolveServerSpecsDir(process.env, process.cwd());
+try {
+    process.stderr.write(`[Holmes-Kit] spec store: ${SPECS_DIR}\n`);
+}
+catch { /* a diagnostic must never keep the server from starting */ }
+const store = new spec_store_1.LocalMarkdownRepository(SPECS_DIR);
 // @implements A-SPEC-263.1 — the elicitation approval channel's wiring. The capability arrives at
 // initialize, AFTER this factory runs, so it is consulted lazily at CALL time.
 // @implements A-SPEC-497.1 — the three fates, told apart at THIS seam (the only place the SDK error
@@ -35,6 +45,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 +131,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,121 @@
+"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) {
+    // @implements A-SPEC-651.1 — the scope's root and every root compared against it share one spelling.
+    const owned = execution ? { root: (0, root_1.canonicalPath)(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 = (0, root_1.canonicalPath)(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: (0, root_1.canonicalPath)(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,15 @@ 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;
+/**
+ * @implements A-SPEC-651.1 — "the same directory" judged by ONE spelling. Every path that names a
+ * workspace or a store is canonicalised the way `resolveProjectRoot` canonicalises (`realpath.native`,
+ * so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
+ * `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
+ * (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
+ * native-canonical root, so a workspace entered as `C:\Users\SUNGNA~1\…` was refused as foreign.
+ */
+export declare function sameCanonicalDirectory(a: string, b: string, realpath?: (p: string) => string): boolean;
+export declare function resolveProjectRoot(dir: string, opts?: {
+    includeGit?: boolean;
+}): ProjectRoot;

package/dist/holmes/project/root.js

@@ -36,8 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.canonicalPath = exports.MARKER = void 0;
 exports.cleanSubprocessEnv = cleanSubprocessEnv;
 exports.cleanTestEnv = cleanTestEnv;
+exports.sameCanonicalDirectory = sameCanonicalDirectory;
 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"));
@@ -111,6 +112,23 @@ exports.MARKER = '.ax';
 const canonicalPath = (p) => fs.realpathSync.native(p);
 exports.canonicalPath = canonicalPath;
 const canonical = exports.canonicalPath;
+/**
+ * @implements A-SPEC-651.1 — "the same directory" judged by ONE spelling. Every path that names a
+ * workspace or a store is canonicalised the way `resolveProjectRoot` canonicalises (`realpath.native`,
+ * so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
+ * `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
+ * (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
+ * native-canonical root, so a workspace entered as `C:\Users\SUNGNA~1\…` was refused as foreign.
+ */
+function sameCanonicalDirectory(a, b, realpath = exports.canonicalPath) {
+    const spell = (p) => { try {
+        return realpath(p);
+    }
+    catch {
+        return path.resolve(p);
+    } };
+    return spell(a) === spell(b);
+}
 function gitTopLevel(dir) {
     try {
         // stderr silenced: "not a git repository" is an expected branch here, not a fault worth printing.
@@ -127,7 +145,7 @@ function gitTopLevel(dir) {
         return undefined;
     }
 }
-function resolveProjectRoot(dir) {
+function resolveProjectRoot(dir, opts = {}) {
     let start;
     try {
         start = canonical(path.resolve(dir));
@@ -165,6 +183,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;