@holmes-lab/holmes-kit 0.19.6 → 0.20.0

package/dist/holmes/spec/renumber.d.ts

@@ -1,3 +1,61 @@
+export interface SourceRenumberInventory {
+    files: Array<{
+        file: string;
+        before: string;
+        after: string;
+        version: string;
+        anchorIds: string[];
+    }>;
+    inventory: Array<{
+        file: string;
+        version: string;
+    }>;
+    diagnostics: Array<{
+        file: string;
+        reason: string;
+    }>;
+    proseCandidates: Array<{
+        file: string;
+        line: number;
+        text: string;
+    }>;
+    ignoreVersion: string | null;
+}
+/**
+ * @implements A-SPEC-646
+ * Installer-owned text, blanked to spaces (length and line count preserved, so AST offsets and prose line
+ * numbers still address the real source). Measured 2026-09-14 in a workspace wired by `holmes-kit init`:
+ * the `.gitattributes` marker block carries `# @implements A-SPEC-256.1` (holmes-kit's OWN spec) and the
+ * installed skills mention `@implements`; both were "reference-bearing files with no supported comment
+ * grammar" and every integration in every init-wired workspace was blocked by the product's own files.
+ * Ownership, not the id, is the distinction: a workspace file anchoring an id no entity carries stays an
+ * explicit conflict (A-SPEC-629). Marker recognition reuses the installer's own definitions.
+ */
+export declare function maskInstallerOwned(source: string): string;
+/** Plan directly from immutable bytes; filesystem discovery and Git object loading remain outside. */
+export declare function planSourceTextRenumber(file: string, bytes: Buffer, pairs: Array<{
+    oldId: string;
+    newId: string;
+}>, options?: {
+    inspectAllAnchors?: boolean;
+}): Promise<Omit<SourceRenumberInventory, 'ignoreVersion'>>;
+/**
+ * @implements A-SPEC-648
+ * Is this unfollowed symlink a VIEW of directories the walk already reaches, rather than a source?
+ * Measured 2026-09-14 in external workspaces on macOS and Linux: `holmes-kit init --agent all` writes
+ * `.agents/skills -> ../.claude/skills` (the Antigravity view of the one skills directory) and the walk
+ * diagnosed it like an aliased source, so `entity_renumber` was never executable in any three-harness
+ * workspace. The Git snapshot walk already treats an unchanged non-regular entry as untouched (A-SPEC-637).
+ * A directory link whose real path stays inside the workspace and is not the store or the entity control
+ * state contributes nothing — its files are reached (or deliberately skipped) through the real directory.
+ * A file link, a dangling link, a link leaving the workspace or one onto the store keeps the diagnostic.
+ * Nothing is followed either way.
+ */
+export declare function isWorkspaceViewLink(root: string, abs: string, storeLocator: string): boolean;
+export declare function planSourceRenumber(root: string, pairs: Array<{
+    oldId: string;
+    newId: string;
+}>, storeLocator: string, originalSources?: ReadonlyMap<string, string>): Promise<SourceRenumberInventory>;
 export interface RenumberPlan {
     moves: {
         from: string;

package/dist/holmes/spec/renumber.js

@@ -33,12 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskInstallerOwned = maskInstallerOwned;
+exports.planSourceTextRenumber = planSourceTextRenumber;
+exports.isWorkspaceViewLink = isWorkspaceViewLink;
+exports.planSourceRenumber = planSourceRenumber;
 exports.rewriteAnchors = rewriteAnchors;
 exports.planRenumber = planRenumber;
 exports.applyRenumber = applyRenumber;
 exports.readSourcesForRenumber = readSourcesForRenumber;
 exports.readSpecsForRenumber = readSpecsForRenumber;
-// @implements A-SPEC-255
+// @implements A-SPEC-629.1, A-SPEC-628, A-SPEC-255
+// @implements A-SPEC-640
 /**
  * Renumbering a spec, as a contract instead of a memory exercise.
  *
@@ -65,6 +70,200 @@ exports.readSpecsForRenumber = readSpecsForRenumber;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const spec_id_1 = require("./spec-id");
+const node_crypto_1 = require("node:crypto");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const ast_store_1 = require("../cpg/foundation/ast-store");
+const ignore_1 = require("../project/ignore");
+const change_source_1 = require("../project/change-source");
+const anchor_ids_1 = require("../rtm/anchor-ids");
+const entity_transaction_1 = require("./entity-transaction");
+const installer_markers_1 = require("../project/installer-markers");
+/**
+ * @implements A-SPEC-646
+ * Installer-owned text, blanked to spaces (length and line count preserved, so AST offsets and prose line
+ * numbers still address the real source). Measured 2026-09-14 in a workspace wired by `holmes-kit init`:
+ * the `.gitattributes` marker block carries `# @implements A-SPEC-256.1` (holmes-kit's OWN spec) and the
+ * installed skills mention `@implements`; both were "reference-bearing files with no supported comment
+ * grammar" and every integration in every init-wired workspace was blocked by the product's own files.
+ * Ownership, not the id, is the distinction: a workspace file anchoring an id no entity carries stays an
+ * explicit conflict (A-SPEC-629). Marker recognition reuses the installer's own definitions.
+ */
+function maskInstallerOwned(source) {
+    const blank = (text) => text.replace(/[^\n]/g, ' ');
+    if ((0, installer_markers_1.carriesMarker)(source))
+        return blank(source);
+    const lines = source.split('\n');
+    let inside = false;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (!inside && trimmed === installer_markers_1.HOLMES_BLOCK_BEGIN)
+            inside = true;
+        if (inside) {
+            const closing = trimmed === installer_markers_1.HOLMES_BLOCK_END;
+            lines[i] = blank(lines[i]);
+            if (closing)
+                inside = false;
+        }
+    }
+    return lines.join('\n');
+}
+/** Plan directly from immutable bytes; filesystem discovery and Git object loading remain outside. */
+async function planSourceTextRenumber(file, bytes, pairs, options = {}) {
+    const result = { files: [], inventory: [], diagnostics: [], proseCandidates: [] };
+    const ids = new Set(pairs.map(pair => pair.oldId));
+    const mentions = (text) => [...text.matchAll(new RegExp(ID_RE, 'g'))].some(match => options.inspectAllAnchors || ids.has(match[0]));
+    const source = bytes.toString('utf8'), version = 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+    const visible = maskInstallerOwned(source); // A-SPEC-646 — judged text; rewriting stays on `source`
+    if (path.posix.basename(file) === '.gitignore') {
+        result.diagnostics.push({ file, reason: 'Nested ignore rules are not interpreted.' });
+        result.inventory.push({ file, version });
+        return result;
+    }
+    const supported = cpg_scanner_1.SCANNABLE_EXTENSIONS.includes(path.extname(file));
+    if (!supported && !mentions(visible))
+        return result;
+    result.inventory.push({ file, version });
+    if (!mentions(visible))
+        return result;
+    if (!Buffer.from(source).equals(bytes) || source.includes('\0')) {
+        result.diagnostics.push({ file, reason: 'Reference-bearing file is not UTF-8 text.' });
+        return result;
+    }
+    let after = source, prose = visible;
+    const anchorIds = new Set();
+    if (supported && (0, ast_store_1.languageFor)(file)) {
+        try {
+            const ast = await (0, ast_store_1.parseAst)(source, file);
+            if (!ast || ast.errorCount) {
+                result.diagnostics.push({ file, reason: 'Source syntax could not be parsed completely.' });
+            }
+            else {
+                const comments = ast.nodes.filter(node => /(?:^|_)comment$/.test(node.type)).sort((a, b) => a.start - b.start || b.end - a.end);
+                const outer = comments.filter((node, i) => !comments.slice(0, i).some(parent => parent.start <= node.start && parent.end >= node.end));
+                for (const node of outer.reverse()) {
+                    const comment = source.slice(node.start, node.end), visibleComment = visible.slice(node.start, node.end);
+                    for (const id of (0, anchor_ids_1.implementsIdLists)(visibleComment).flat())
+                        if (options.inspectAllAnchors || ids.has(id))
+                            anchorIds.add(id);
+                    after = after.slice(0, node.start) + rewriteAnchors(comment, pairs) + after.slice(node.end);
+                    prose = prose.slice(0, node.start) + visibleComment.replace(ANCHOR_LIST_RE, marker => ' '.repeat(marker.length)) + prose.slice(node.end);
+                }
+            }
+        }
+        catch {
+            result.diagnostics.push({ file, reason: 'Source grammar is unavailable.' });
+        }
+    }
+    else if (visible.includes('@implements'))
+        result.diagnostics.push({ file, reason: 'Reference-bearing file has no supported comment grammar.' });
+    const originalLines = source.split('\n');
+    prose.split('\n').forEach((line, index) => { if (mentions(line))
+        result.proseCandidates.push({ file, line: index + 1, text: originalLines[index] }); });
+    if (after !== source || (options.inspectAllAnchors && anchorIds.size))
+        result.files.push({ file, before: source, after, version, anchorIds: [...anchorIds].sort() });
+    return result;
+}
+/**
+ * @implements A-SPEC-648
+ * Is this unfollowed symlink a VIEW of directories the walk already reaches, rather than a source?
+ * Measured 2026-09-14 in external workspaces on macOS and Linux: `holmes-kit init --agent all` writes
+ * `.agents/skills -> ../.claude/skills` (the Antigravity view of the one skills directory) and the walk
+ * diagnosed it like an aliased source, so `entity_renumber` was never executable in any three-harness
+ * workspace. The Git snapshot walk already treats an unchanged non-regular entry as untouched (A-SPEC-637).
+ * A directory link whose real path stays inside the workspace and is not the store or the entity control
+ * state contributes nothing — its files are reached (or deliberately skipped) through the real directory.
+ * A file link, a dangling link, a link leaving the workspace or one onto the store keeps the diagnostic.
+ * Nothing is followed either way.
+ */
+function isWorkspaceViewLink(root, abs, storeLocator) {
+    let real;
+    try {
+        real = fs.realpathSync(abs);
+        if (!fs.statSync(real).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const base = fs.realpathSync(root);
+    if (real !== base && !real.startsWith(base + path.sep))
+        return false;
+    const rel = path.relative(base, real).split(path.sep).join('/');
+    const under = (prefix) => rel === prefix || rel.startsWith(prefix + '/');
+    return !(under(storeLocator) || under('.ax/entities') || under('.ax/approvals'));
+}
+async function planSourceRenumber(root, pairs, storeLocator, originalSources = new Map()) {
+    const result = { files: [], inventory: [], diagnostics: [], proseCandidates: [], ignoreVersion: null };
+    const digest = (bytes) => 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+    let ignoreText = '';
+    try {
+        const file = path.join(root, '.gitignore');
+        if (fs.lstatSync(file).isSymbolicLink())
+            throw new Error('Symlinked ignore policy');
+        const bytes = fs.readFileSync(file);
+        ignoreText = bytes.toString('utf8');
+        result.ignoreVersion = digest(bytes);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            result.diagnostics.push({ file: '.gitignore', reason: 'Ignore policy could not be read safely.' });
+    }
+    const ignore = (0, ignore_1.parseIgnore)(ignoreText);
+    for (const pattern of ignore.unsupportedPatterns())
+        result.diagnostics.push({ file: '.gitignore', reason: 'Unsupported ignore pattern: ' + pattern });
+    const walkSources = async (relative) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(root, relative), { withFileTypes: true });
+        }
+        catch {
+            result.diagnostics.push({ file: relative || '.', reason: 'Unreadable source directory.' });
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            const file = relative ? relative + '/' + entry.name : entry.name, abs = path.join(root, file);
+            const controlState = file === '.ax/entities' || file === '.ax/approvals' || (0, change_source_1.isDerivedState)(file + (entry.isDirectory() ? '/' : ''));
+            if (controlState || file === storeLocator || file.startsWith(storeLocator + '/') || (entry.isDirectory() && cpg_scanner_1.SKIP.has(entry.name)) || ignore.isIgnored(file))
+                continue;
+            // @implements A-SPEC-640 — the publication primitive's transients (temp, aside) are never sources.
+            if ((0, entity_transaction_1.isEntityTransientName)(entry.name))
+                continue;
+            if (entry.isSymbolicLink()) {
+                if (isWorkspaceViewLink(root, abs, storeLocator))
+                    continue; // A-SPEC-648 — a view, not a source
+                result.diagnostics.push({ file, reason: 'Symlinked source is not followed.' });
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (fs.existsSync(path.join(abs, 'pyvenv.cfg')))
+                    continue;
+                await walkSources(file);
+                continue;
+            }
+            if (!entry.isFile()) {
+                result.diagnostics.push({ file, reason: 'Unsupported source file type.' });
+                continue;
+            }
+            if (file === '.gitignore')
+                continue;
+            let bytes;
+            try {
+                bytes = originalSources.has(file) ? Buffer.from(originalSources.get(file)) : fs.readFileSync(abs);
+            }
+            catch {
+                result.diagnostics.push({ file, reason: 'Unreadable source file.' });
+                continue;
+            }
+            const planned = await planSourceTextRenumber(file, bytes, pairs);
+            result.files.push(...planned.files);
+            result.inventory.push(...planned.inventory);
+            result.diagnostics.push(...planned.diagnostics);
+            result.proseCandidates.push(...planned.proseCandidates);
+        }
+    };
+    await walkSources('');
+    return result;
+}
 /** The anchor grammar, shared with `rtm/anchor-ids.ts` so the two judgments cannot drift apart. */
 const ID_RE = String.raw `(?:REQ|A-SPEC|H-SPEC|C-SPEC|T-SPEC)-\d{3,}(?:\.\d+)?`;
 const ANCHOR_LIST_RE = new RegExp(String.raw `(@implements[ \t]+)(${ID_RE}(?:[ \t]*,[ \t]*${ID_RE})*)`, 'g');

package/dist/holmes/spec/spec-store.d.ts

@@ -96,8 +96,8 @@ export declare class LocalMarkdownRepository implements SpecStore {
      * Writes are SERIALIZED per store instance. The expectedVersion check and the file write are
      * separated by an `await this.list()` (the orphan sweep), so two concurrent write() calls could
      * both pass the check before either wrote — a check-then-act hole round-3 review demonstrated.
-     * The server is single-process; a promise chain closes the in-process window. Cross-process
-     * concurrency remains the caller's problem, as it was.
+     * The promise chain preserves same-instance ordering. Holmes workspace writes also hold the
+     * entity-store lock across asynchronous lookups, coordinating with explicit adoption.
      */
     private writeChain;
     write(spec: Spec, opts?: {
@@ -106,6 +106,7 @@ export declare class LocalMarkdownRepository implements SpecStore {
         version: string;
     }>;
     private writeSerialized;
+    private writeLegacy;
     private findFilePath;
     list(): Promise<Spec[]>;
     read(id: string): Promise<{

package/dist/holmes/spec/spec-store.js

@@ -36,7 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemorySpecStore = exports.LocalMarkdownRepository = exports.TargetPathOccupiedError = exports.SpecVersionConflictError = void 0;
 exports.unreadableSpecFiles = unreadableSpecFiles;
 exports.notFoundReason = notFoundReason;
+// @implements A-SPEC-627, A-SPEC-151, A-SPEC-100.1
 const node_crypto_1 = require("node:crypto");
+const entity_store_1 = require("./entity-store");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const spec_parser_1 = require("./spec-parser");
@@ -186,8 +188,8 @@ class LocalMarkdownRepository {
      * Writes are SERIALIZED per store instance. The expectedVersion check and the file write are
      * separated by an `await this.list()` (the orphan sweep), so two concurrent write() calls could
      * both pass the check before either wrote — a check-then-act hole round-3 review demonstrated.
-     * The server is single-process; a promise chain closes the in-process window. Cross-process
-     * concurrency remains the caller's problem, as it was.
+     * The promise chain preserves same-instance ordering. Holmes workspace writes also hold the
+     * entity-store lock across asynchronous lookups, coordinating with explicit adoption.
      */
     writeChain = Promise.resolve();
     async write(spec, opts) {
@@ -197,6 +199,19 @@ class LocalMarkdownRepository {
         return p;
     }
     async writeSerialized(spec, opts) {
+        const newPath = this.targetPathFor(spec);
+        try {
+            return await (0, entity_store_1.writeEntityRepository)(this.root, spec, newPath, opts?.expectedVersion, () => this.writeLegacy(spec, opts));
+        }
+        catch (e) {
+            if (e instanceof entity_store_1.EntityStoreError && e.code === 'version-conflict')
+                throw new SpecVersionConflictError(e.message);
+            if (e instanceof entity_store_1.EntityStoreError && e.code === 'target-occupied')
+                throw new TargetPathOccupiedError(e.message, newPath);
+            throw e;
+        }
+    }
+    async writeLegacy(spec, opts) {
         const newPath = this.targetPathFor(spec);
         // @implements A-SPEC-151
         // Checked BEFORE any filesystem change. A refusal that half-wrote would be the worst outcome:
@@ -264,6 +279,9 @@ class LocalMarkdownRepository {
         return result;
     }
     async list() {
+        const entitySnapshot = (0, entity_store_1.readEntityRepositorySnapshot)(this.root);
+        if (entitySnapshot !== undefined)
+            return entitySnapshot.map(record => record.spec);
         const out = [];
         const walk = (d) => {
             if (!fs.existsSync(d))
@@ -292,6 +310,9 @@ class LocalMarkdownRepository {
         return out;
     }
     async read(id) {
+        const entitySnapshot = (0, entity_store_1.readEntityRepositorySnapshot)(this.root);
+        if (entitySnapshot !== undefined)
+            return entitySnapshot.find(record => record.spec.id === id) ?? null;
         const file = await this.findFilePath(id);
         if (file === null)
             return null;

package/dist/holmes/spec/transition-policy.d.ts

@@ -0,0 +1,36 @@
+import { Spec } from './spec-parser';
+/** Withdrawal policy is shared; callers retain authority and idempotent no-op handling. */
+export declare function prepareLifecycleSpec(spec: Spec, all: Spec[], operation: 'unseal' | 'retire', reason?: string): {
+    ok: false;
+    reason: string;
+    candidate?: undefined;
+    dependents?: undefined;
+} | {
+    ok: true;
+    candidate: Spec;
+    dependents: Spec[];
+    reason?: undefined;
+};
+/** Act-time policy only: callers own authority, version checks, persistence and audit. */
+export declare function prepareApprovedSpec(spec: Spec, specs: Spec[], resolver: (specs: Spec[]) => (id: string) => Spec | null, readFile: (relative: string) => string | null): {
+    ok: false;
+    reason: string;
+    findings?: undefined;
+    candidate?: undefined;
+    digest?: undefined;
+    parentDigests?: undefined;
+} | {
+    ok: false;
+    reason: string;
+    findings: import("./validator").Finding[];
+    candidate?: undefined;
+    digest?: undefined;
+    parentDigests?: undefined;
+} | {
+    ok: true;
+    candidate: Spec;
+    digest: string;
+    parentDigests: Record<string, string>;
+    reason?: undefined;
+    findings?: undefined;
+};

package/dist/holmes/spec/transition-policy.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareLifecycleSpec = prepareLifecycleSpec;
+exports.prepareApprovedSpec = prepareApprovedSpec;
+const validator_1 = require("./validator");
+const spec_digest_1 = require("./spec-digest");
+const breaking_change_1 = require("./breaking-change");
+const compat_impact_1 = require("./compat-impact");
+const approval_blockers_1 = require("./approval-blockers");
+/** Withdrawal policy is shared; callers retain authority and idempotent no-op handling. */
+function prepareLifecycleSpec(spec, all, operation, reason) {
+    const dependents = all.filter(s => s.id !== spec.id && s.dependsOn.includes(spec.id));
+    const blocking = dependents.filter(s => s.status === 'approved').map(s => s.id);
+    if (blocking.length > 0)
+        return {
+            ok: false,
+            reason: operation === 'retire'
+                ? `${spec.id}을(를) 폐기하면 approved 문서 ${blocking.join(', ')}의 사슬이 끊깁니다 — 지금 무언가를 지탱하고 있는 사슬이므로 거부합니다.` + ' 해당 문서를 먼저 폐기하거나 부모를 다른 문서로 옮기십시오.'
+                : `${spec.id}의 봉인을 해제하면 approved 문서 ${blocking.join(', ')}의 parent_digests 가 stale 이 됩니다 — 지금 그 사슬을 지탱하고 있으므로 거부합니다.` + ' 해당 문서를 먼저 해제/폐기하거나 부모를 다른 문서로 옮기십시오.',
+        };
+    const frontmatter = { ...spec.frontmatter };
+    if (operation === 'unseal') {
+        delete frontmatter.approved_digest;
+        delete frontmatter.parent_digests;
+    }
+    else if (typeof reason === 'string' && reason.trim() && frontmatter.superseded_by === undefined) {
+        frontmatter.retired_reason = reason.trim();
+    }
+    const candidate = { ...spec, status: operation === 'unseal' ? 'draft' : 'outdated', frontmatter };
+    return { ok: true, candidate, dependents };
+}
+/** Act-time policy only: callers own authority, version checks, persistence and audit. */
+function prepareApprovedSpec(spec, specs, resolver, readFile) {
+    // @implements A-SPEC-188 — duplicates make the id ambiguous, for the SPEC and for its
+    // PARENTS alike. Round-3 probed the parent half: with a stray duplicate of the parent
+    // walking first, the child's parent_digests sealed the stray's (forged) digest — the very
+    // snapshot drift detection compares against — while the refusal principle stated one field
+    // away was "the tool does not pick a copy". Refuse for every ambiguous id in the act.
+    const ambiguous = [spec.id, ...spec.dependsOn].filter((id) => specs.filter((s) => s.id === id).length > 1);
+    if (ambiguous.length > 0) {
+        return {
+            ok: false,
+            reason: `${[...new Set(ambiguous)].join(', ')}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 봉인 전에 거부합니다.`
+                + ' doctor로 중복 파일을 확인해 하나로 정리한 뒤 다시 승인하십시오.',
+        };
+    }
+    // @implements A-SPEC-168
+    // A child may not be approved under a parent that is not. The chain's meaning is that each
+    // layer is justified by the one above it, and measured 2026-08-08 that failed in four places —
+    // including A-SPEC-100.1/100.2, the core MCP guardrail, whose design H-SPEC-100 nobody ever
+    // approved. The obligation is on the ACT: existing approvals are untouched, because making it
+    // a state rule is what REQ-146 measured turning 302 specs into violations at once.
+    // @implements A-SPEC-182
+    // Shared with the gate rather than restated. Adversarial review found this check living ONLY
+    // here: the gate reported "nothing blocks" for a draft under a draft parent — the modal state
+    // of top-down authoring — and the author learned otherwise only by attempting the approval.
+    const parentIssues = (0, approval_blockers_1.parentBlockers)(spec, resolver(specs));
+    if (parentIssues.length > 0)
+        return { ok: false, reason: parentIssues[0] };
+    // Validate AS IT WILL BE — approved. Approval-gated checks (placeholder citations, 4-quadrant
+    // GWT) must fire NOW, not one turn after the seal exists.
+    const candidate = { ...spec, status: 'approved', frontmatter: { ...spec.frontmatter } };
+    delete candidate.frontmatter.approved_digest; // seals are recomputed by this act, never inherited
+    delete candidate.frontmatter.parent_digests;
+    const prevalidation = (0, validator_1.validateSpec)(candidate, resolver(specs));
+    const blocking = prevalidation.findings.filter((f) => f.level === 'error' && !approval_blockers_1.SUPPLIED_BY_APPROVAL.has(f.code) // this act supplies exactly those
+    );
+    // @implements A-SPEC-641 — the reason names the findings: measured 2026-09-14, the bare sentence
+    // reached renumber and integration operators as "validation errors block approval" with nothing
+    // to act on. The multi-document acts prefix the document id.
+    if (blocking.length > 0)
+        return { ok: false, reason: 'validation errors block approval: ' + blocking.map((f) => f.message).join('; '), findings: blocking };
+    // @implements A-SPEC-146
+    // ADR-013's duty is owed by the ACT, not by the document's static validity. Measured: putting
+    // this in `validateSpec`'s requiredFields produced 38 ART-3 violations and a Stop hook that
+    // blocked every turn, because all 38 governed A-SPECs are already approved. Here it constrains
+    // the future without invalidating the past — and a re-approval, which by definition means the
+    // content changed, is exactly when the question is due.
+    const breakingIssue = (0, breaking_change_1.checkBreakingChangeDeclared)(candidate);
+    if (breakingIssue)
+        return { ok: false, reason: breakingIssue };
+    // @implements A-SPEC-565.1 — the compat declaration duty rides the SAME act (REQ-565): sealing
+    // is when "did you consider the three harnesses and the three OSes" is due, and act-time is
+    // what keeps 512 already-approved specs out of retroactive violation (the 38-violation incident
+    // above). The bound reader feeds the OS cross-check from this root's working tree.
+    const compatIssue = (0, compat_impact_1.checkCompatDeclared)(candidate, {
+        // No root → no working tree to read: the OS cross-check skips file-by-file (fail-open),
+        // while the declaration syntax itself is still enforced — the duty never depends on `root`.
+        readFile,
+    });
+    if (compatIssue)
+        return { ok: false, reason: compatIssue };
+    // @implements A-SPEC-182
+    // A document whose prose is still the generator's placeholder must not be sealed. Measured
+    // 2026-08-13 on a brownfield adoption: H-SPEC-100 took `status: approved` and an
+    // `approved_digest` with all seven prose sections reading "TODO — a human writes this" —
+    // while its own first line said approving is the point a description becomes normative.
+    // Placed on the ACT, not in `validateSpec`, for the reason A-SPEC-146 measured: a static
+    // predicate turns every already-approved spec into a violation and bricks the harness.
+    const stubs = (0, approval_blockers_1.placeholderSections)(candidate);
+    if (stubs.length > 0) {
+        return { ok: false, reason: (0, approval_blockers_1.placeholderMessage)(stubs) };
+    }
+    // @implements A-SPEC-505.1 — acceptance substance, judged at the ACT on the same candidate
+    // the seal would freeze, like the placeholder gate above (154/428 approved REQs here are
+    // non-stated legacy; a validateSpec predicate would brick them all). Judged HERE and not
+    // before the approval channels: an earlier extra read shifts the optimistic-concurrency
+    // window and lets a mid-approval edit get sealed (store-integrity contract: edits win,
+    // approvals lose). The post-grant refusal it costs is the standing property of every
+    // act-time blocker in this block (breaking_change, placeholder) — one ordering, one truth.
+    const unactionable = (0, approval_blockers_1.unactionableCriteriaBlocker)(candidate);
+    if (unactionable)
+        return { ok: false, reason: unactionable };
+    // Parents-first: a sealed child snapshotting an unsealed parent would pin nothing. This loop
+    // exists to COLLECT the digests; the refusal inside it is now a backstop, because
+    // `parentBlockers` above already returns for the same condition with the same sentence. Kept
+    // rather than deleted so a future change to that function cannot silently let an unsealed
+    // parent through — but note the wording lives there, and only there, if it is ever edited.
+    const parentDigests = {};
+    for (const pid of spec.dependsOn) {
+        const parent = specs.find((s) => s.id === pid);
+        if (parent && parent.status === 'approved') {
+            const parentSeal = (0, spec_digest_1.sealOf)(parent).approvedDigest;
+            if (!parentSeal)
+                return { ok: false, reason: (0, approval_blockers_1.unsealedParentMessage)(pid) };
+            parentDigests[pid] = parentSeal;
+        }
+    }
+    // @implements A-SPEC-135
+    // The caller compares the returned digest with the prior seal to record seal movement.
+    const digest = (0, spec_digest_1.specDigest)(candidate);
+    candidate.frontmatter.approved_digest = digest;
+    candidate.frontmatter.parent_digests = parentDigests;
+    return { ok: true, candidate, digest, parentDigests };
+}

package/package.json

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