@holmes-lab/holmes-kit 0.19.6 → 0.20.0

package/dist/holmes/mcp/handlers/spec-approval.d.ts

@@ -0,0 +1,105 @@
+import { SpecStore } from '../../spec/spec-store';
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { Approval } from '../../guardrail/risk-gate';
+import { ElicitOutcome } from '../elicit-approval';
+export interface SpecApprovalContext {
+    store: SpecStore;
+    resolver(specs: Spec[]): (id: string) => Spec | null;
+    projectRootOf(root: string): string;
+    cachedScan(root: string, repoRoot?: string): ScannedFile[];
+    tryElicit(kind: string, target: string, summary: string): Promise<ElicitOutcome>;
+    elicitApproval(reason?: string): Approval;
+    autonomousApproval(derivedFrom?: string[]): Approval;
+    resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
+        kind: string;
+        target: string;
+        subject?: string;
+    }, now: string): {
+        approval: Approval;
+        source: 'env' | 'grant';
+        root?: string;
+    } | undefined;
+    refusalQueueHint(root: string | undefined, request: {
+        kind: string;
+        target: string;
+        why: string;
+        subject?: string;
+        risk?: string;
+    }): string;
+    foreignRootReason(root?: string): string | null;
+}
+export declare function createSpecApprovalHandlers(context: SpecApprovalContext): {
+    /**
+     * @implements A-SPEC-132
+     * Approval as an ACT: validate → seal → flip → ledger, in one call. This is the designed
+     * reversal of "no approval tool exists" (which promote-slice documented while it was true) —
+     * the act now includes digest computation a hand edit cannot perform honestly. Fail-closed on
+     * the SERVER-environment approval: nothing in the request payload can substitute, because the
+     * agent authors the payload and the operator authors the environment.
+     */
+    spec_approve(a: {
+        root?: string;
+        id: string;
+    }): Promise<{
+        ok: false;
+        reason: string;
+        findings: import("../../spec/validator").Finding[];
+        candidate?: undefined;
+        digest?: undefined;
+        parentDigests?: undefined;
+    } | {
+        ok: boolean;
+        reason: string;
+        conflict?: undefined;
+    } | {
+        ok: boolean;
+        reason: string;
+        conflict: import("../../spec/version-conflict").ConflictDetail;
+    } | {
+        impactAdvisoryUnavailable?: "empty" | "unreadable" | undefined;
+        impactGraph?: {
+            status: "current" | "stale" | "unverified";
+            sourceCommit: string | null;
+            head: string | null;
+            graphAsOf?: string;
+        } | undefined;
+        anchorDensity?: import("../../rtm/anchor-density").AnchorDensityFinding[] | undefined;
+        impactAdvisory?: import("../../rtm/impact-advisory").ImpactAdvisory | undefined;
+        approved: string;
+        digest: string;
+        ok?: undefined;
+        reason?: undefined;
+        conflict?: undefined;
+    }>;
+    /**
+     * Pin a REQ's citations: compute the content digest of every cited source that resolves inside
+     * the repo and record it as `rev`, so an author never hashes a file by hand and the digest is
+     * always derived from what is actually on disk.
+     *
+     * Explicit-invocation only, dry-run by DEFAULT, and never overwrites an existing digest — a
+     * re-pin would replace evidence of upstream drift with a fresh-looking value, converting the
+     * detector into a concealer.
+     */
+    citation_pin(a: {
+        root: string;
+        id: string;
+        dryRun?: boolean;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        id?: undefined;
+        dryRun?: undefined;
+        pinned?: undefined;
+        findings?: undefined;
+        citations?: undefined;
+    } | {
+        ok: boolean;
+        id: string;
+        dryRun: boolean;
+        pinned: string[];
+        findings: import("../../spec/validator").Finding[];
+        citations: unknown[];
+        reason?: undefined;
+    }>;
+};

package/dist/holmes/mcp/handlers/spec-approval.js

@@ -0,0 +1,504 @@
+"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.createSpecApprovalHandlers = createSpecApprovalHandlers;
+// @implements A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245
+// @implements A-SPEC-631
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const spec_store_1 = require("../../spec/spec-store");
+const transition_policy_1 = require("../../spec/transition-policy");
+const validator_1 = require("../../spec/validator");
+const elicit_approval_1 = require("../elicit-approval");
+const autonomy_1 = require("../../governance/autonomy");
+const write_target_1 = require("../../guardrail/write-target");
+const approval_grants_1 = require("../../governance/approval-grants");
+const spec_digest_1 = require("../../spec/spec-digest");
+const version_conflict_1 = require("../../spec/version-conflict");
+const ledger_store_1 = require("../../governance/ledger-store");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+const review_targets_1 = require("../../review/review-targets");
+function createSpecApprovalHandlers(context) {
+    const { store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval } = context;
+    return {
+        /**
+         * @implements A-SPEC-132
+         * Approval as an ACT: validate → seal → flip → ledger, in one call. This is the designed
+         * reversal of "no approval tool exists" (which promote-slice documented while it was true) —
+         * the act now includes digest computation a hand edit cannot perform honestly. Fail-closed on
+         * the SERVER-environment approval: nothing in the request payload can substitute, because the
+         * agent authors the payload and the operator authors the environment.
+         */
+        async spec_approve(a) {
+            const approvalRaw = process.env.HOLMES_APPROVAL;
+            let approval;
+            try {
+                approval = approvalRaw ? JSON.parse(approvalRaw) : undefined;
+            }
+            catch {
+                approval = undefined;
+            }
+            // covers, not merely well-formed (round-3 escalation: a token scoped to review-resolve — or
+            // expired outright — completed a FULL SEAL here, so A-SPEC-133's narrowing was decorative at
+            // the most consequential consumer). Unscoped {actor,token,rationale} stays the session key.
+            // @implements A-SPEC-649 — coverage is resolved by kind/target here; the SUBJECT binding of a
+            // grant is checked against the ONE versioned read the seal uses (below), never against an
+            // extra read — an extra read moved the optimistic-write window and let an external edit be
+            // sealed (measured by the A-SPEC-188 TOCTOU pin).
+            const action = { kind: 'spec-approve', target: a.id };
+            let approveResolved = context.resolveHandlerApproval(a.root, approval, action, new Date().toISOString());
+            // @implements A-SPEC-263.1 — asked ONLY after the existing channels failed to cover (an open
+            // door never summons a human), and only about a spec that exists (a question about a missing
+            // id helps no one — the standard refusal handles it).
+            let elicitExpiredMs;
+            let risk;
+            let subject;
+            if (approveResolved === undefined) {
+                const target = await store.read(a.id).catch(() => null);
+                // @implements A-SPEC-649 — the digest of what the operator will read rides the request.
+                subject = target ? (0, spec_digest_1.specDigest)(target.spec) : undefined;
+                if (target) {
+                    // @implements A-SPEC-532.2 — the autonomous gate sits BEFORE the human ask: when the
+                    // out-of-band autonomy switch is on AND the spec is low/mid-risk (never gate-behavior, an
+                    // architecture/taint file, or an upstream REQ/H/C — those stay human), the agent seals it
+                    // itself. The switch is env-only and an agent cannot set it (pre-tool-use blocks that,
+                    // A-SPEC-532.2). Off, or a hitl-classed spec, falls straight through to the elicitor
+                    // unchanged — the autonomous-OFF path is byte-identical to before.
+                    // @implements A-SPEC-553.1 — autonomy is the out-of-band env switch OR a valid, non-expired
+                    // session envelope marker under this project's `.ax/state/` (which an agent cannot write).
+                    const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, a.root, new Date().toISOString());
+                    // @implements A-SPEC-587 — an upstream REQ/H-SPEC is graded by the A-SPECs beneath it, so
+                    // the store is consulted for its descendants (only then: the list is a cost the auto-grade
+                    // A-SPEC/T-SPEC path does not pay). Unknown scope (none yet) keeps the human answer.
+                    const upstream = target.spec.type === 'REQ' || target.spec.type === 'H-SPEC';
+                    const below = upstream ? (0, autonomy_1.descendantAspecs)(target.spec, await store.list()) : undefined;
+                    // @implements A-SPEC-649 — the grade is recorded on the request either way (the screen shows it).
+                    risk = (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec]), below);
+                    if (autonomyOn
+                        && (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec]), below) === 'auto') {
+                        approveResolved = { approval: autonomousApproval(below?.map((s) => s.id)), source: 'autonomous' };
+                    }
+                    else if (autonomyOn) {
+                        // @implements A-SPEC-551.1 — hitl-grade spec under autonomy: the in-session elicitation
+                        // dialog is auto-acceptable by an auto-mode client (the protocol cannot tell a human
+                        // from an auto-accept), so a governance-critical spec is never offered it. Do nothing
+                        // here — approveResolved stays undefined and the fail-closed refuse+enqueue path below
+                        // routes the act to the out-of-band human queue (holmes-kit approve). The A-SPEC-532.1
+                        // bound ("governance-critical specs never leave the human channel") thus becomes
+                        // ENFORCED, not aspirational. Autonomy OFF (the else) and the auto-grade branch above
+                        // stay byte-identical to before.
+                    }
+                    else {
+                        const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
+                        // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
+                        // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
+                        // more consequential act) as a first approval. The cap cuts the title, never the marker.
+                        const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
+                        if (out.kind === 'answered' && out.decision.granted) {
+                            approveResolved = { approval: elicitApproval(out.decision.reason), source: 'elicitation' };
+                        }
+                        else if (out.kind === 'answered') {
+                            // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
+                            // entry is filed — a decided request is not a pending one (REQ-246 visibility).
+                            return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
+                        }
+                        else if (out.kind === 'expired') {
+                            // @implements A-SPEC-497.1 — only the expiry earns a name: the notice LEADS the same
+                            // fail-closed refusal + queue path, so the semantics stay refusal+queue and only the
+                            // message learned to say what happened.
+                            elicitExpiredMs = out.waitedMs;
+                        }
+                        // silent: the channel gave no answer — fall through to the byte-identical refusal.
+                    }
+                }
+            }
+            if (approveResolved === undefined) {
+                // @implements A-SPEC-649 — a grant that exists but is refused by its binding is NAMED, so the
+                // operator learns to revoke or re-decide instead of wondering why nothing opened.
+                let refusedGrants = '';
+                try {
+                    const projectRoot = context.projectRootOf(a.root ?? store.specsRoot);
+                    refusedGrants = (0, approval_grants_1.refusedGrantReasons)(projectRoot, { ...action, ...(subject ? { subject } : {}) }, new Date().toISOString()).map((g) => `\n[grant ${g.nonce} refused: ${g.reason}]`).join('');
+                }
+                catch {
+                    refusedGrants = '';
+                }
+                return { ok: false, reason: (elicitExpiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(elicitExpiredMs) : '') + refusedGrants
+                        + 'spec_approve requires an out-of-band HOLMES_APPROVAL that COVERS this act — a request-payload approval is not a channel, and an expired or elsewhere-scoped token does not open this door (scoped approvals need kind "spec-approve"). (fail-closed)'
+                        + context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인', ...(subject ? { subject } : {}), ...(risk ? { risk } : {}) }) };
+            }
+            // @implements A-SPEC-188 — destination BEFORE seal.
+            // The old order (seal at :481, resolve the ledger at :483) produced both measured harms: a
+            // bad root left a standing seal with no ledger entry anywhere while the CALLER WAS TOLD IT
+            // FAILED, and a foreign root filed the only audit record in another project's ledger. This
+            // repository lived the first one — REQ-182's chain was approved rootless on 2026-08-13 and
+            // the missing entries were found two review rounds later.
+            //
+            // The destination is DERIVED from the store the server was bound to (same principle as
+            // spec_create's A-SPEC-163 guard); a supplied `root` is a confirmation that must match. Any
+            // failure here is a refusal with nothing written.
+            let ledgerRoot;
+            try {
+                if (store instanceof spec_store_1.LocalMarkdownRepository) {
+                    // Compared at PROJECT level, through the same walk-up the old code used: a root pointing
+                    // anywhere INSIDE this project (the specs dir, a subdirectory) resolves to the same
+                    // project and is accepted — round-2 review caught the first cut refusing those with a
+                    // message that printed the identical path on both sides. Only a root resolving to a
+                    // DIFFERENT project is refused, and the message names both projects.
+                    //
+                    // Round-3 caught the fallback: resolveProjectRoot returns its INPUT when no .ax ancestor
+                    // exists, so a custom HOLMES_SPECS outside any .ax tree "derived" the specs dir itself as
+                    // the project — a rootless approval then minted .ax/ledger INSIDE the spec store, and the
+                    // correct explicit root was refused as a "different project". Derivation only counts when
+                    // the walk actually found a marker; otherwise the old contract stands: root is required
+                    // and names the project.
+                    const derived = projectRootOf(store.specsRoot);
+                    const derivationFoundMarker = fs.existsSync(path.join(derived, '.ax'));
+                    if (derivationFoundMarker) {
+                        ledgerRoot = derived;
+                        if (typeof a.root === 'string' && a.root !== '') {
+                            const askedProject = (0, write_target_1.resolveTarget)(projectRootOf(a.root), '.');
+                            const boundProject = (0, write_target_1.resolveTarget)(ledgerRoot, '.');
+                            if (askedProject !== boundProject) {
+                                return {
+                                    ok: false,
+                                    reason: `이 서버는 ${boundProject} 프로젝트에 바인딩되어 있습니다 — 요청한 root ${a.root}는 ${askedProject} 프로젝트를 가리킵니다.`
+                                        + ' 다른 프로젝트의 원장에 기록하지 않기 위해 봉인 전에 거부합니다.',
+                                };
+                            }
+                        }
+                    }
+                    else if (typeof a.root === 'string' && a.root !== '') {
+                        ledgerRoot = projectRootOf(a.root);
+                    }
+                    else {
+                        return {
+                            ok: false,
+                            reason: '스토어 위치에서 프로젝트를 파생할 수 없습니다(.ax 상위 디렉터리 없음) — 원장을 어디에 둘지 알 수 없어 봉인 전에 거부합니다. root를 지정하십시오.',
+                        };
+                    }
+                }
+                else {
+                    if (typeof a.root !== 'string' || a.root === '') {
+                        return { ok: false, reason: 'root가 없고 스토어에서 원장 위치를 파생할 수도 없습니다 — 봉인 전에 거부합니다. root를 지정하십시오.' };
+                    }
+                    ledgerRoot = projectRootOf(a.root);
+                }
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    reason: `원장 위치를 확정할 수 없어 봉인 전에 거부합니다: ${String(e.message)}.`
+                        + ' 올바른 root를 지정하거나, 파일 스토어에 바인딩된 서버에서는 root를 생략하십시오.',
+                };
+            }
+            const specs = await store.list();
+            // @implements A-SPEC-188 — with DUPLICATE ids the tool cannot know which copy is canonical:
+            // read() resolves the last-walked file while list().find sees the first, so approving would
+            // seal a stray's content and delete the canonical file — success reported, edit destroyed
+            // (round-2 review reproduced exactly that). Duplicates are a recognized invalid state
+            // (doctor detects them); the act refuses rather than picking a side.
+            // @implements A-SPEC-188 — the spec this act validates and seals is the one read NOW, with
+            // its version captured for the optimistic write below. Basing the candidate on the list()
+            // element instead leaves a window in which an external edit is silently destroyed and the
+            // STALE content gets sealed (measured: 17 of 40 concurrent edits lost, 35-55ms window).
+            const cur = await store.read(a.id);
+            // @implements A-SPEC-649 — a grant bound to a subject opens only for THAT subject: the digest of
+            // the spec read now (the same read the seal is based on) must equal the one the operator read.
+            // Measured 2026-09-14: a grant read against "Original title" sealed "CHANGED after the grant".
+            if (cur && approveResolved.source === 'grant') {
+                const bound = approveResolved.approval;
+                if (typeof bound.subject === 'string' && bound.subject !== '' && bound.subject !== (0, spec_digest_1.specDigest)(cur.spec)) {
+                    const current = (0, spec_digest_1.specDigest)(cur.spec);
+                    return { ok: false, reason: `[grant ${bound.nonce ?? '?'} refused: stale-subject] the grant was minted for another content of ${a.id}; the operator must read the current content and decide again (revoke the stale grant with holmes-kit approve --revoke).`
+                            + context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인', subject: current }) };
+                }
+            }
+            // @implements A-SPEC-536.1 — BUG-1: a spec whose YAML is broken is dropped by read()/list(),
+            // so a bare "not found" hid that the file EXISTS but cannot be parsed. Surface the skipped
+            // files when there are any; byte-identical to the legacy message when there are none. The
+            // store's specsRoot is read through the same cast the reachability checks use (A-SPEC-169).
+            if (!cur) {
+                const dir = store.specsRoot;
+                const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
+                return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
+            }
+            const spec = cur.spec;
+            const prepared = (0, transition_policy_1.prepareApprovedSpec)(spec, specs, resolver, (rel) => {
+                try {
+                    return a.root ? fs.readFileSync(path.join(a.root, rel), 'utf8') : null;
+                }
+                catch {
+                    return null;
+                }
+            });
+            if (!prepared.ok)
+                return prepared;
+            const { candidate, digest } = prepared;
+            const priorDigest = (0, spec_digest_1.sealOf)(spec).approvedDigest;
+            // @implements A-SPEC-188 — the seal is written only at the version this act READ. On
+            // conflict the EDIT wins and the APPROVAL loses: the edit is what a person just wrote; the
+            // approval is an act that can simply be retried. The reverse (the old behaviour) sealed
+            // stale content over a destroyed edit with no notice.
+            try {
+                await store.write(candidate, { expectedVersion: cur.version });
+            }
+            catch (e) {
+                if (e instanceof spec_store_1.SpecVersionConflictError) {
+                    // @implements A-SPEC-538.4 — the refusal is unchanged (refuse, write nothing, the edit
+                    // wins); it now also CARRIES the conflict: the version this act read, the version now on
+                    // disk, and what to retry. Re-read to learn the current version (null if it vanished).
+                    const now = await store.read(a.id).catch(() => null);
+                    return {
+                        ok: false,
+                        reason: `승인 진행 중 ${a.id}이(가) 바뀌었습니다 — 바뀐 내용을 확인하고 다시 승인하십시오.`
+                            + ' 이번 승인은 아무것도 쓰지 않았습니다.',
+                        conflict: (0, version_conflict_1.conflictDetail)({ id: a.id, expected: cur.version, current: now?.version ?? null }),
+                    };
+                }
+                // @implements A-SPEC-188 — approval can RELOCATE the file (req_type classification moves
+                // an H-SPEC into its subfolder). Round-3 probed that landing on an unreadable human note
+                // destroyed it with success reported; the store now refuses, and this act relays why.
+                if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                    return {
+                        ok: false,
+                        reason: `${a.id}의 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다.`
+                            + ' 사람이 확인해 옮기거나 고친 뒤 다시 승인하십시오. 이번 승인은 아무것도 쓰지 않았습니다.',
+                    };
+                }
+                throw e;
+            }
+            // @implements A-SPEC-148 — writes go to THIS replica's chain; the legacy file is read-only now.
+            const chain = new ledger_store_1.FileLedgerStore(path.join(ledgerRoot, '.ax', 'ledger'));
+            chain.append({
+                ts: new Date().toISOString(),
+                actor: approveResolved.approval.actor,
+                kind: 'spec-approved',
+                summary: `approved ${a.id} sealing ${digest}`,
+                inputs: [a.id, digest],
+                rationale: approveResolved.approval.rationale,
+                authorization: (0, provenance_chain_1.authorizationRef)(approveResolved.approval.actor, approveResolved.approval.token),
+            });
+            // @implements A-SPEC-135
+            // P4 routing signal: a re-approval whose content CHANGED (prior seal existed and differs) mints
+            // a `review-needed` entry naming the anchored source files — the exact set a targeted review must
+            // re-examine against the new content. A first approval or an idempotent re-seal is not drift and
+            // mints nothing. This ROUTES review; it never verdicts the code. Best-effort: a missed route is
+            // not a broken seal, so an append failure does not fail the approval.
+            if (priorDigest && priorDigest !== digest) {
+                try {
+                    const files = (0, review_targets_1.anchoredForReview)(a.id, cachedScan(ledgerRoot, ledgerRoot), specs);
+                    chain.append({
+                        ts: new Date().toISOString(), actor: approveResolved.approval.actor, kind: 'review-needed',
+                        summary: `targeted review needed: ${a.id} content moved — re-examine ${files.length} anchored file(s) against the new spec content`,
+                        inputs: [a.id, priorDigest, digest, ...files],
+                        rationale: approveResolved.approval.rationale, authorization: '',
+                    });
+                }
+                catch { /* a missed routing signal is not a broken seal */ }
+            }
+            // @implements A-SPEC-245 — single-use: the grant is spent by the seal it authorized.
+            if (approveResolved.source === 'grant' && approveResolved.root && approveResolved.approval.nonce) {
+                (0, approval_grants_1.consumeGrantFile)(approveResolved.root, approveResolved.approval.nonce);
+            }
+            // @implements A-SPEC-566.2 — the impact advisory rides the SUCCESS, after the seal is done:
+            // the verdict is already committed, so nothing here can change it (advisory, never gate —
+            // Judgments must not be budgeted). Reuses the persisted graph READ-ONLY; it never scans,
+            // parses or builds (scan:build measured 20~38x — an approval must not pay that), and every
+            // failure below degrades to "no advisory field" on an otherwise identical response.
+            let impactAdvisory;
+            let anchorDensity;
+            // @implements A-SPEC-631 — the graph's CONDITION rides beside the advisory: current/stale/unverified,
+            // or the reason no advisory could be derived. An empty graph is never reported as no impact.
+            let impactGraph;
+            let impactAdvisoryUnavailable;
+            try {
+                if (spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    // @implements A-SPEC-631 — non-mutating inspection: never clears, never deletes, and says
+                    // what the file is. Freshness costs one `git rev-parse`, never a scan.
+                    const { openPublishedGraph, headCommitOf } = require('../../rtm/graph-store');
+                    const { cleanSubprocessEnv } = require('../../project/root');
+                    const view = openPublishedGraph(dbPath, headCommitOf(a.root, cleanSubprocessEnv()));
+                    if (view.status === 'empty' || view.status === 'unreadable') {
+                        impactAdvisoryUnavailable = view.status;
+                    }
+                    else if (view.graph !== null) {
+                        const { declaredImpactGap, appendImpactAdvisory } = require('../../rtm/impact-advisory');
+                        const { filesToTouch } = require('../../spec/compat-impact');
+                        // Closed in finally (high-effort review F4): this handler lives in a long-running MCP
+                        // server, and an unclosed native handle per approval accumulates for the process
+                        // lifetime — and on Windows can hold rtm.sqlite locked against the next rebuild.
+                        const graph = view.graph;
+                        impactGraph = { status: view.status, sourceCommit: view.sourceCommit, head: view.head, ...(view.graphAsOf ? { graphAsOf: view.graphAsOf } : {}) };
+                        try {
+                            const ftt = filesToTouch(candidate);
+                            const gap = declaredImpactGap(ftt, graph, (rel) => { try {
+                                return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                            }
+                            catch {
+                                return null;
+                            } });
+                            if (gap) {
+                                const graphAsOf = (() => { try {
+                                    return fs.statSync(dbPath).mtime.toISOString();
+                                }
+                                catch {
+                                    return undefined;
+                                } })();
+                                impactAdvisory = { ...gap, ...(graphAsOf ? { graphAsOf } : {}) };
+                                appendImpactAdvisory(a.root, {
+                                    aspec: a.id, files: gap.files.map((f) => f.path), more: gap.more,
+                                    ...(graphAsOf ? { graphAsOf } : {}), ts: new Date().toISOString(),
+                                });
+                            }
+                            // @implements A-SPEC-569.5 — anchor-density OBSERVATION, same reopened graph, same
+                            // no-scan contract, same lifecycle as the advisory above (observe → ledger → measure
+                            // before anyone proposes promotion). Never a verdict input: the seal is already done,
+                            // and its own failure degrades to "no field" on an otherwise identical response.
+                            try {
+                                const { anchorDensityFindings, appendAnchorDensity } = require('../../rtm/anchor-density');
+                                const findings = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
+                                if (findings.length > 0) {
+                                    anchorDensity = findings;
+                                    appendAnchorDensity(a.root, {
+                                        aspec: a.id, files: findings.map((f) => ({ path: f.path, anchors: f.anchors })),
+                                        p90: findings[0].p90, ts: new Date().toISOString(),
+                                    });
+                                }
+                            }
+                            catch {
+                                anchorDensity = undefined;
+                            }
+                        }
+                        finally {
+                            graph.close();
+                        }
+                    }
+                }
+            }
+            catch {
+                impactAdvisory = undefined;
+                anchorDensity = undefined;
+                impactGraph = undefined;
+                impactAdvisoryUnavailable = undefined;
+            }
+            return { approved: a.id, digest, ...(impactAdvisory ? { impactAdvisory } : {}), ...(anchorDensity ? { anchorDensity } : {}),
+                ...(impactGraph ? { impactGraph } : {}), ...(impactAdvisoryUnavailable ? { impactAdvisoryUnavailable } : {}) };
+        },
+        /**
+         * Pin a REQ's citations: compute the content digest of every cited source that resolves inside
+         * the repo and record it as `rev`, so an author never hashes a file by hand and the digest is
+         * always derived from what is actually on disk.
+         *
+         * Explicit-invocation only, dry-run by DEFAULT, and never overwrites an existing digest — a
+         * re-pin would replace evidence of upstream drift with a fresh-looking value, converting the
+         * detector into a concealer.
+         */
+        async citation_pin(a) {
+            // @implements A-SPEC-189 §15 (round 13) — every sibling that reads or writes on behalf of a
+            // project refuses a foreign root (spec_create, phase_status, review_record, review_status,
+            // spec_approve). `citation_pin` did not, and it SEALS what it read: the sha256 of another
+            // project's file was written into this store's REQ frontmatter as evidence, permanently —
+            // the design deliberately never overwrites an existing digest.
+            const foreignPin = context.foreignRootReason(a.root);
+            if (foreignPin !== null)
+                return { ok: false, reason: `citation_pin: ${foreignPin}` };
+            // @implements A-SPEC-189 §14 (round 13) — the derivation was computed and discarded, so the
+            // advertised "a subdirectory resolves up to it" held for `taint_scan` and no one else.
+            const root = projectRootOf(a.root);
+            // @implements A-SPEC-188 — the third writer, same duplicate hazard as approve/upgrade:
+            // read() resolves the last-walked copy and the write's orphan sweep deletes the other.
+            if ((await store.list()).filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 기록 전에 거부합니다.`
+                        + ' doctor로 중복 파일을 확인해 하나로 정리한 뒤 다시 시도하십시오.',
+                };
+            }
+            // @implements A-SPEC-151
+            // `read` now yields the spec together with the version it was read at, so a write can say
+            // "only if nobody touched this since". citation_pin uses it: the pin is derived from what was
+            // read, and writing it back over someone else's edit would silently discard their change.
+            const found = await store.read(a.id);
+            if (!found)
+                return { ok: false, reason: `spec ${a.id} not found` };
+            const { spec, version } = found;
+            if (spec.type !== 'REQ')
+                return { ok: false, reason: `citations live on REQ; ${a.id} is ${spec.type}` };
+            if (spec.frontmatter.source == null)
+                return { ok: false, reason: `${a.id} has no source to pin` };
+            const readLocal = (ref) => {
+                const abs = path.resolve(root, ref);
+                // A ref that escapes the repository is not ours to read, and following it would let a spec
+                // pull arbitrary host files into the provenance record.
+                if (!abs.startsWith(path.resolve(root) + path.sep))
+                    return null;
+                try {
+                    return fs.readFileSync(abs, 'utf8');
+                }
+                catch {
+                    return null;
+                }
+            };
+            const { citations, pinned, findings } = (0, validator_1.pinCitations)(spec.frontmatter.source, readLocal);
+            const dryRun = a.dryRun !== false; // opt IN to writing
+            if (!dryRun && pinned.length > 0) {
+                try {
+                    try {
+                        await store.write({ ...spec, frontmatter: { ...spec.frontmatter, source: citations } }, { expectedVersion: version });
+                    }
+                    catch (e) {
+                        if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                            return {
+                                ok: false,
+                                reason: `${a.id}의 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다.`
+                                    + ' 사람이 확인해 옮기거나 고친 뒤 다시 시도하십시오.',
+                            };
+                        }
+                        throw e;
+                    }
+                }
+                catch (err) {
+                    if (err instanceof spec_store_1.SpecVersionConflictError) {
+                        return { ok: false, reason: `${a.id} changed while its citations were being pinned — re-read and retry (${err.message})` };
+                    }
+                    throw err;
+                }
+            }
+            return { ok: true, id: a.id, dryRun, pinned, findings, citations };
+        },
+    };
+}