@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/mcp/handlers.js

@@ -0,0 +1,1831 @@
+"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.HandlerRefusal = void 0;
+exports.isHandlerRefusal = isHandlerRefusal;
+exports.makeHandlers = makeHandlers;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
+const node_child_process_1 = require("node:child_process");
+const validator_1 = require("../spec/validator");
+const rtm_check_1 = require("../rtm/rtm-check");
+const test_scope_1 = require("../rtm/test-scope");
+const gap_analyzer_1 = require("../rtm/gap-analyzer");
+const test_runner_1 = require("../review/test-runner");
+const test_evidence_1 = require("../review/test-evidence");
+const localize_1 = require("../rtm/localize");
+const phase_1 = require("../guardrail/phase");
+const spec_types_1 = require("../spec/spec-types");
+const legacy_format_1 = require("../spec/legacy-format");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const scan_cache_1 = require("../cpg/scan-cache");
+// N7: every whole-tree scan goes through the file-key incremental cache under the PROJECT root's
+// .ax/cpg_cache — unchanged files (content-hash hit) skip the tree-sitter parse entirely.
+// The cache lives under the RESOLVED project root, not the raw scan root: scanning a SUBDIRECTORY
+// otherwise littered a second `.ax/cpg_cache` under that subdirectory (measured leak — `src/.ax/`),
+// and the .gitignore only anchors the root `.ax/cpg_cache/`. Resolving to the .ax-bearing ancestor
+// keeps one cache per project and matches where git-ignore expects it.
+// @implements A-SPEC-189 §13 (round 12) — `resolveProjectRoot` returns the input when it finds no
+// marker, so a read-looking scan of any directory CREATED `.ax` there and every later resolution
+// under that tree stopped at the minted marker. This is the harm §8 closed for `review_record`,
+// left open on the scan path. When the store is bound, the cache is the bound project's; otherwise
+// only an anchored answer may be written to, and an unanchored one falls back to a temp cache.
+const cacheDirFor = (root) => {
+    const r = (0, root_1.resolveProjectRoot)(root);
+    if (r.marker !== 'given')
+        return path.join(r.root, '.ax', 'cpg_cache');
+    if (fs.existsSync(path.join(r.root, '.ax')))
+        return path.join(r.root, '.ax', 'cpg_cache');
+    return path.join(os.tmpdir(), `holmes-cpg-cache-${crypto.createHash('sha256').update(r.root).digest('hex').slice(0, 16)}`);
+};
+const cachedScan = (root, repoRoot = root) => new cpg_scanner_1.CpgScanner(undefined, new scan_cache_1.ScanFileCache(cacheDirFor(root))).scan(root, repoRoot);
+// @implements A-SPEC-131
+// Same scan, with the skip report kept: the callers that make honesty claims (cpg_scan's surface,
+// the changed-file accounting) need to know what the scan could NOT ingest, not just what it did.
+const cachedScanWithReport = (root, repoRoot = root) => {
+    const scanner = new cpg_scanner_1.CpgScanner(undefined, new scan_cache_1.ScanFileCache(cacheDirFor(root)));
+    const scanned = scanner.scan(root, repoRoot);
+    return { scanned, skipped: scanner.scanSkipped() };
+};
+const rtm_builder_1 = require("../rtm/rtm-builder");
+const rtm_graph_1 = require("../rtm/rtm-graph");
+const taint_1 = require("../rtm/taint");
+const incremental_1 = require("../rtm/incremental");
+const hash_cache_1 = require("../cpg/hash-cache");
+const bundler_1 = require("../context/bundler");
+const scope_1 = require("../review/scope");
+const review_targets_1 = require("../review/review-targets");
+const coverage_1 = require("../review/coverage");
+const basis_1 = require("./basis");
+const write_target_1 = require("../guardrail/write-target");
+const spec_store_1 = require("../spec/spec-store");
+const findings_1 = require("../review/findings");
+const package_1 = require("../review/package");
+const risk_classifier_1 = require("../guardrail/risk-classifier");
+const risk_gate_1 = require("../guardrail/risk-gate");
+const spec_digest_1 = require("../spec/spec-digest");
+const spec_store_2 = require("../spec/spec-store");
+const breaking_change_1 = require("../spec/breaking-change");
+const approval_blockers_1 = require("../spec/approval-blockers");
+const ledger_store_1 = require("../governance/ledger-store");
+const provenance_chain_1 = require("../governance/provenance-chain");
+const ledger_lock_1 = require("../governance/ledger-lock");
+const decision_ledger_1 = require("../guardrail/decision-ledger");
+/**
+ * @implements A-SPEC-189 §7 (round 10)
+ * A DELIBERATE refusal, distinguished by construction rather than by class.
+ *
+ * Round 9 converted thrown errors into `{ok:false, reason}` at the wire and told them apart with
+ * `e.constructor === Error`. Measured: Node's own fs/exec failures (ENOENT, EISDIR, EACCES) are
+ * exactly `Error`, so a CRASH became an orderly refusal — and for `review_status` that refusal had
+ * no `blocked` field at all, i.e. a gate reader's `if (out.blocked)` read undefined and passed.
+ * The check that used to stop the caller loudly (-32603) became a silent gate pass. A refusal is
+ * something a handler chooses to say; nothing infers it from a class.
+ */
+class HandlerRefusal extends Error {
+    holmesRefusal = true;
+    constructor(message) { super(message); this.name = 'HandlerRefusal'; }
+}
+exports.HandlerRefusal = HandlerRefusal;
+/** Marker test that survives realm boundaries (jest's instanceof does not). */
+function isHandlerRefusal(e) {
+    return !!e && typeof e === 'object' && e.holmesRefusal === true;
+}
+// @implements A-SPEC-128
+const root_1 = require("../project/root");
+const change_source_1 = require("../project/change-source");
+const baseline_1 = require("../project/baseline");
+const ignore_1 = require("../project/ignore");
+// @implements A-SPEC-126
+const scan_1 = require("../reverse/scan");
+const draft_1 = require("../reverse/draft");
+const anchor_1 = require("../reverse/anchor");
+// @implements A-SPEC-128
+// Where a project begins, for tools that only walk the tree.
+//
+// This REPLACES `assertRepoTopLevel`, which demanded `root === git rev-parse --show-toplevel` and
+// threw otherwise — imposed uniformly, including on tools that never look at a diff. Measured, that
+// made cpg_scan, issue_localize, rtm_check(root), test_run and review_scope all throw on a directory
+// with no `.git`, while reverse_scan (which asks git only for a candidacy refinement) carried on.
+//
+// The hazard that guard addressed is real but belongs to the GIT CHANGE SOURCE: gitChangedFiles
+// yields top-level-relative paths while scan(root, root) tags root-relative ones, so a disagreement
+// silently produces wrong impact sets. `GitChangeSource` now enforces exactly that, and only there.
+function projectRootOf(root) {
+    return (0, root_1.resolveProjectRoot)(root).root;
+}
+// @implements A-SPEC-191 §10 — WHERE a single-use approval is spent must not be a caller's choice.
+// r8 measured all three escapes at once: a second `root`, a `root` naming a subdirectory, and an
+// omitted `root` (cwd-relative) each handed the same nonce a fresh, empty ledger — 'N-RISK' opened a
+// hard-hitl door three times over, the round-7 fix notwithstanding, and the audit line for each
+// reopening was filed in the attacker's directory. The destination is DERIVED from the store this
+// server was bound to (spec_approve's A-SPEC-188 principle). A server that cannot derive a project
+// cannot promise single use at all, so it says so instead of pretending: null is a refusal, never a
+// fallback to whatever the caller named.
+/**
+ * @implements A-SPEC-191 §15 (round 11)
+ * Does this caller's `root` name the project this server is bound to? A tool that ADVERTISES root
+ * and neither reads nor checks it answers about somewhere else in a success shape: a single typo in
+ * `root` made review_status — the merge gate's own reader — report `blocked: false` for a project
+ * whose ledger it never opened. Returns a refusal reason, or null when the root is fine.
+ */
+function foreignRootReason(store, root) {
+    if (typeof root !== 'string' || root === '' || !(store instanceof spec_store_1.LocalMarkdownRepository))
+        return null;
+    // An unresolvable STORE is not the caller's mistake — there is simply nothing to compare against.
+    let derived;
+    try {
+        derived = projectRootOf(store.specsRoot);
+        if (!fs.existsSync(path.join(derived, '.ax')))
+            return null; // 파생이 표지를 찾지 못하면 대조할 것이 없다
+    }
+    catch {
+        return null;
+    }
+    try {
+        const asked = (0, write_target_1.resolveTarget)(projectRootOf(root), '.');
+        const bound = (0, write_target_1.resolveTarget)(derived, '.');
+        if (asked === bound)
+            return null;
+        return `이 서버는 ${bound} 프로젝트에 바인딩되어 있습니다 — 요청한 root ${root}는 ${asked} 를 가리킵니다.`
+            + ' 다른 프로젝트에 대해 이 서버가 대신 답하지 않습니다.';
+    }
+    catch (e) {
+        return `root를 해석할 수 없습니다: ${String(e.message)}`;
+    }
+}
+/**
+ * A root the caller named that this process cannot read is the CALLER'S mistake, not a fault.
+ * @implements A-SPEC-189 §10 (round 11)
+ */
+function assertReadableRoot(tool, root) {
+    if (typeof root !== 'string' || root === '') {
+        throw new HandlerRefusal(`${tool}: root 는 프로젝트 루트의 절대 경로여야 합니다 (받은 값: ${JSON.stringify(root)})`);
+    }
+    let stat;
+    try {
+        stat = fs.statSync(root);
+    }
+    catch {
+        throw new HandlerRefusal(`${tool}: ${root} 를 읽을 수 없습니다 — 그 경로가 존재하는지 확인하십시오`);
+    }
+    if (!stat.isDirectory())
+        throw new HandlerRefusal(`${tool}: ${root} 는 디렉터리가 아닙니다`);
+}
+function boundNonceLedger(store) {
+    if (!(store instanceof spec_store_1.LocalMarkdownRepository))
+        return null;
+    try {
+        const derived = projectRootOf(store.specsRoot);
+        // @implements A-SPEC-191 §14 (round 10) — a project root INSIDE the spec store is not a project
+        // root, whatever it is spelled. The `.ax` exclusion only covers the default layout; with
+        // `--specs-dir docs/specs` an ordinary review_record could still plant `docs/specs/.ax` and move
+        // every consumed nonce, every audit line, and spec_approve's notion of "this project" with it.
+        const storeReal = (() => { try {
+            return fs.realpathSync(store.specsRoot);
+        }
+        catch {
+            return store.specsRoot;
+        } })();
+        const derivedReal = (() => { try {
+            return fs.realpathSync(derived);
+        }
+        catch {
+            return derived;
+        } })();
+        if (derivedReal === storeReal || derivedReal.startsWith(storeReal + path.sep))
+            return null;
+        if (!fs.existsSync(path.join(derived, '.ax')))
+            return null;
+        return path.join(derived, '.ax', 'ledger', 'provenance.jsonl');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where the FINDINGS ledger of this server's project lives.
+ *
+ * @implements A-SPEC-189 §8 (round 11) — `review_record` joined the caller's `root` straight into a
+ * path, so a subdirectory root wrote `<root>/pkg/.ax/ledger/findings.jsonl` — and that write MINTED a
+ * project marker at `pkg`, after which the same subdirectory read as its own project (measured: the
+ * second call to the very same root was then refused as foreign). `review_status` and the Stop gate
+ * read the project's ledger, so those findings gated nothing while reporting `{recorded: N}`.
+ * The ledger's location is the bound project's fact, not an argument.
+ */
+function boundFindingsLedger(store, root) {
+    const projRoot = projectRootOf(root);
+    const fallback = path.join(projRoot, '.ax', 'ledger', 'findings.jsonl');
+    if (!(store instanceof spec_store_1.LocalMarkdownRepository))
+        return fallback;
+    try {
+        const derived = projectRootOf(store.specsRoot);
+        const storeReal = (() => { try {
+            return fs.realpathSync(store.specsRoot);
+        }
+        catch {
+            return store.specsRoot;
+        } })();
+        const derivedReal = (() => { try {
+            return fs.realpathSync(derived);
+        }
+        catch {
+            return derived;
+        } })();
+        if (derivedReal === storeReal || derivedReal.startsWith(storeReal + path.sep))
+            return fallback;
+        if (!fs.existsSync(path.join(derived, '.ax')))
+            return fallback;
+        return path.join(derived, '.ax', 'ledger', 'findings.jsonl');
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Build the change source a diff-consuming tool should use, from what the caller supplied.
+ *
+ * Precedence is explicit-over-implicit: an explicit git range wins, then a named baseline, then the
+ * default baseline — so a caller who passes nothing on a project that has been verified before still
+ * gets a scoped answer, and a caller who passes a range still gets git's rename detection.
+ */
+const DEFAULT_BASELINE = 'last-green';
+function makeChangeSource(root, a) {
+    if (a.base && a.head)
+        return new change_source_1.GitChangeSource(root, a.base, a.head);
+    // @implements A-SPEC-134 — verify against the provenance chain so a tampered baseline degrades to
+    // full scope instead of narrowing against a forged reference point.
+    return new change_source_1.SnapshotChangeSource(root, a.since ?? DEFAULT_BASELINE, {
+        isIgnored: (p) => (0, ignore_1.loadIgnore)(root).isIgnored(p),
+        verify: path.join(root, '.ax', 'ledger', 'provenance.jsonl'),
+    });
+}
+// ContentSource factory shared by context_bundle and review_prepare: specMap
+// SPEC:<id> -> title + section text, codeMap CODE:<qn>@<sourcePath> -> signature,
+// merged `?? null`.
+function buildContentSource(specs, scanned) {
+    const specMap = new Map(specs.map((s) => [
+        `SPEC:${s.id}`,
+        [s.title, ...Object.entries(s.sections).map(([k, v]) => `## ${k}\n${v}`)].join('\n'),
+    ]));
+    const codeMap = new Map();
+    for (const f of scanned) {
+        for (const sym of f.symbols) {
+            // A-SPEC-121.4: key by the FULL (source_path-qualified) node id — see
+            // RtmGraph/rtm-builder's A-SPEC-121.3 note — so this matches the actual
+            // graph node id and bundle content resolves instead of silently
+            // falling through to `?? null`.
+            codeMap.set(`CODE:${sym.qualifiedName}@${f.sourcePath}`, `${sym.qualifiedName} (${sym.kind}) @ ${f.sourcePath}`);
+        }
+    }
+    return (nodeId) => specMap.get(nodeId) ?? codeMap.get(nodeId) ?? null;
+}
+// Shared prologue of review_scope/review_prepare (and the guard+git+scan
+// part of rtm_reindex): guard the root, diff base..head, load specs, scan
+// the tree, and derive the changed-files/changed-symbols sets used to scope
+// the review/graph. `toolName` is passed through to assertRepoTopLevel so
+// the thrown error names the actual caller.
+async function deriveChangedContext(store, rootArg, a, toolName) {
+    const root = projectRootOf(rootArg);
+    const source = makeChangeSource(root, a);
+    const resolved = source.changes();
+    const changeSource = source.describe();
+    // UNAVAILABLE IS NOT "NOTHING CHANGED". Reading a missing reference point as an empty change set
+    // would narrow the scope against a baseline that was never taken — silently, and in the dangerous
+    // direction. The caller widens to full instead, the way computeTestScope already does when no
+    // anchored test resolves.
+    const changes = resolved ?? { added: [], modified: [], deleted: [], renamed: [] };
+    const specs = await store.list();
+    const { scanned, skipped } = cachedScanWithReport(root, root);
+    const bySourcePath = new Map(scanned.map((f) => [f.sourcePath, f]));
+    // Deletions have no post-change content to scan for symbols; renames
+    // are keyed by their post-change (`to`) path, matching scan()'s
+    // sourcePath tagging.
+    const changedFiles = [...changes.added, ...changes.modified, ...changes.renamed.map((r) => r.to)];
+    const changedSymbols = [
+        ...new Set(changedFiles.flatMap((relPath) => bySourcePath.get(relPath)?.symbols.map((s) => s.qualifiedName) ?? [])),
+    ];
+    // @implements A-SPEC-130
+    // Three-lane accounting: the symbol derivation above (lane 1) drops changed files that parse to
+    // zero symbols or are excluded from the scan — measured to zero out the impact set on a tree with
+    // five changed sources. Lanes 2/3 and the unresolved remainder are derived from the SAME
+    // collections; no new scan, no new I/O.
+    const account = (0, test_scope_1.accountChangedFiles)(changedFiles, (rel) => {
+        const s = bySourcePath.get(rel);
+        return s ? { implementsSpecs: s.implementsSpecs, symbolCount: s.symbols.length } : undefined;
+    });
+    // @implements A-SPEC-131
+    // A changed file the scan REPORTED as skipped is exactly a file whose impact cannot be proven —
+    // it joins the same unresolved lane, so the tier widens and the name rides in the answer. (The
+    // account already catches never-scanned scannable files; this catches ones with a stated reason.)
+    const skippedSet = new Set(skipped.map((s) => s.file));
+    const unresolvedFiles = [...new Set([...account.unresolvedFiles, ...changedFiles.filter((f) => skippedSet.has(f))])].sort();
+    return {
+        changes, changeSource, root, specs, scanned, bySourcePath, changedFiles, changedSymbols,
+        anchorImpactedSpecs: account.anchorImpactedSpecs,
+        changedTestFiles: account.changedTestFiles,
+        unresolvedFiles,
+        ...(resolved === null ? { scopeFallback: 'full' } : {}),
+    };
+}
+// @implements A-SPEC-100.2
+/**
+ * @implements A-SPEC-156
+ * The build this PROCESS loaded, resolved exactly once. Per-call hashing would buy I/O for no new
+ * information, and mtime would manufacture divergence on a checkout or a copy.
+ */
+const LOADED_BUILD = (0, basis_1.loadedBuildId)(path.resolve(__dirname, '..', '..', '..'));
+/**
+ * @implements A-SPEC-156
+ * Basis is attached HERE, in one place, rather than inside each handler. Measured reasoning: 25
+ * handlers edited by hand is 25 chances to forget, and the one that forgets is invisible — which is
+ * precisely how the surface came to answer confidently with nothing backing it. The coverage test
+ * walks the tool list for the same reason.
+ */
+function makeHandlers(store) {
+    const raw = makeRawHandlers(store);
+    const wrapped = {};
+    for (const [name, fn] of Object.entries(raw)) {
+        wrapped[name] = (0, basis_1.withBasis)(fn, (a) => basisFor(a?.root));
+    }
+    wrapped.basis_detail = async (a) => {
+        const b = basisFor(a?.root, true);
+        return { ...b, basis: (0, basis_1.basisDigest)(b) };
+    };
+    // The cast restores the per-handler signatures the loop erased. Without it every handler collapses
+    // to `(a: any) => Promise<unknown>`, so a caller writing `h.rtm_check()` — legal before this
+    // change — stops compiling. That is an ADR-013 tier-③ break, and adding a diagnostic field is not
+    // a licence to take one.
+    return wrapped;
+}
+/**
+ * Collects the axes. `withDisk` reads the on-disk build id — done only for `basis_detail` so a stat
+ * is not charged to every call. The comparison itself is left to the caller: a server that rendered
+ * its own staleness verdict would be running that verdict from the stale build.
+ */
+function basisFor(root, withDisk = false) {
+    const ctx = { loadedBuild: LOADED_BUILD };
+    if (withDisk)
+        ctx.root = path.resolve(__dirname, '..', '..', '..');
+    if (root) {
+        // Both axes are constant-I/O by construction. A semantic file count would cost a 69ms tree walk
+        // per call (measured), and a graph rebuild more — this module must not make every tool slower in
+        // order to describe itself.
+        ctx.scanFp = () => fs.statSync(path.join(root, '.ax', 'cpg_cache', 'scan-cache.json')).size;
+        // A COUNT would have missed the divergence that matters most: editing a spec leaves the count
+        // identical, so two answers computed on different corpora would carry the same basis. Folding
+        // size and mtime in costs 3ms against 2ms (measured) — one millisecond for the axis to mean what
+        // it claims.
+        ctx.specs = () => {
+            const dir = path.join(root, '.ax', 'specs');
+            let acc = 0;
+            for (const f of fs.readdirSync(dir, { recursive: true })) {
+                try {
+                    const st = fs.statSync(path.join(dir, f));
+                    acc = (acc + st.size + Math.floor(st.mtimeMs)) >>> 0;
+                }
+                catch { /* a file that vanished mid-walk contributes nothing; absence is not an error here */ }
+            }
+            return acc;
+        };
+    }
+    return (0, basis_1.collectBasis)(ctx);
+}
+function makeRawHandlers(store) {
+    const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
+    return {
+        async spec_create(a) {
+            // @implements A-SPEC-169
+            // `root` is a CONTROL argument. Without excluding it, the catch-all below stores it as
+            // frontmatter and a machine-local absolute path lands in a git-shared document. A blacklist,
+            // not a whitelist: domain fields (`priority`, `slice`, …) must keep flowing through without
+            // anyone maintaining a list of them.
+            const { type, id, title, depends_on = [], root: reqRoot, ...extra } = a;
+            // The server binds its spec store once, so a `root` naming another project cannot be honoured.
+            // Silently writing to this one is a data-integrity problem; refusing says so. Compared by
+            // resolved identity (A-SPEC-163) — `<root>//.` is the same directory, not a different project.
+            // @implements A-SPEC-189 §9 (round 11) — the question is "same PROJECT?", and this asked "does
+            // `<root>/.ax/specs` equal the bound store?" — the default layout hardcoded. On the first-class
+            // `--specs-dir docs/specs` deployment no root could ever satisfy it: measured, the project's own
+            // root was refused as another project's, so `spec_create` was unusable there. `spec_approve`
+            // learned this in round 3 and compares at project level; this is the same comparison.
+            // @implements A-SPEC-189 §16 (round 13) — the siblings all ask "did the derivation actually
+            // FIND a marker?" before speaking for a project (spec_approve, phase_status,
+            // foreignRootReason). Without it, a store whose derivation lands on itself (an absolute
+            // `--specs-dir` outside any `.ax` tree) calls itself the bound project and refuses the
+            // project's real root — the inverse defect rounds 3/9/11 fixed elsewhere.
+            // 파생은 이 분기 안에서만, 그리고 실패는 '표지를 못 찾았다'로 읽는다 — 스펙 트리를 이제
+            // 만들려는 참이라 스토어 경로가 아직 없을 수 있고, 그것이 예외가 되어선 안 된다.
+            const boundSpecsRoot = store instanceof spec_store_1.LocalMarkdownRepository ? store.specsRoot : null;
+            const derivedForCreate = (() => {
+                if (boundSpecsRoot === null)
+                    return null;
+                try {
+                    const d = projectRootOf(boundSpecsRoot);
+                    return fs.existsSync(path.join(d, '.ax')) ? d : null;
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (typeof reqRoot === 'string' && reqRoot !== '' && derivedForCreate !== null) {
+                const asked = (0, write_target_1.resolveTarget)(projectRootOf(reqRoot), '.');
+                const bound = (0, write_target_1.resolveTarget)(derivedForCreate, '.');
+                if (asked !== bound) {
+                    return {
+                        ok: false,
+                        // A-SPEC-169: 두 경로를 모두 이름한다 — 어느 저장소가 묶여 있는지 호출자가 보아야 한다.
+                        reason: `이 서버는 ${bound} 프로젝트(스펙 저장소 ${boundSpecsRoot})에 바인딩되어 있습니다`
+                            + ` — 요청한 root ${reqRoot}는 ${asked}를 가리킵니다.`
+                            + ' 다른 프로젝트를 조용히 수정하지 않기 위해 거부합니다.',
+                    };
+                }
+            }
+            // @implements A-SPEC-174
+            // Refuse what can never become valid; accept what is merely not filled in yet.
+            //
+            // Measured 2026-08-12 against the installed server: `REQ-7`, `hello`, `A-SPEC-7.1` and four
+            // more were all created and are all refused at approval on `bad-id`. The id IS the filename,
+            // so the author's only repair is to delete the spec and start over — after writing the body.
+            // The stubs below are the opposite case: they are placeholders BY DESIGN, and blocking
+            // approval until someone answers them is what they are for (A-SPEC-146).
+            //
+            // Every judgement here quotes SPEC_TYPES, which is what approval reads. A second statement of
+            // the rule drifts, and the drift is either this defect again or its worse inverse — refused
+            // at creation, accepted at approval.
+            const def = spec_types_1.SPEC_TYPES[type];
+            if (!def) {
+                return { ok: false, reason: `알 수 없는 스펙 타입 "${String(type)}" — 유효한 타입: ${spec_types_1.SPEC_ORDER.join(', ')}` };
+            }
+            if (!def.idRegex.test(String(id))) {
+                return {
+                    ok: false,
+                    reason: `id "${String(id)}"는 ${def.type}의 형식 ${def.idRegex}에 맞지 않습니다 — 예: ${def.example}.`
+                        + ' 승인 시점에 거부될 값이므로 지금 거부합니다(id는 파일명이라 나중에 고칠 수 없습니다).',
+                };
+            }
+            for (const pid of depends_on) {
+                // The parent is judged WITHOUT resolving it: not existing yet is a legitimate state an
+                // author reaches by creating the child first. A wrong type is wrong forever.
+                const ptype = (0, spec_types_1.specTypeOfId)(String(pid));
+                if (ptype === null) {
+                    return { ok: false, reason: `depends_on "${String(pid)}"는 어떤 스펙 타입의 id 형식에도 맞지 않습니다 — 그 id를 가진 스펙은 존재할 수 없습니다.` };
+                }
+                if (!def.parents.includes(ptype)) {
+                    return { ok: false, reason: `depends_on "${String(pid)}"는 ${ptype}입니다 — ${def.type}의 부모는 ${def.parents.join('|') || '없음(빈 depends_on)'}이어야 합니다.` };
+                }
+            }
+            // @implements A-SPEC-188
+            // Creation creates. Probed before this check existed: spec_create over an approved+sealed
+            // REQ returned {"created"} while the disk went draft / seal gone / prose gone — the sanctioned
+            // door destroying what risk_check guards every shell path against. Checked AFTER the format
+            // refusals on purpose: a malformed id must keep its own message (order is pinned by test).
+            // Legacy (typeless) documents count as existing too — overwriting one makes the store's
+            // orphan removal delete the differently-named original file along with its history.
+            const existing = (await store.list()).find((s) => s.id === id);
+            if (existing) {
+                const sealed = existing.status === 'approved' || Boolean(existing.frontmatter?.approved_digest);
+                const kind = existing.type ? `${existing.type} (status: ${existing.status})` : `옛 형식 문서 (status: ${existing.status})`;
+                return {
+                    ok: false,
+                    reason: `${id}은(는) 이미 존재합니다 — ${kind}. `
+                        + (sealed
+                            ? '봉인(approved)된 문서이므로, 내용을 바꾸려면 파일을 편집한 뒤 spec_approve로 재봉인하십시오. '
+                            : '그 문서를 고치려는 것이면 파일을 직접 편집하십시오. ')
+                        + '새 문서를 만들려는 것이면 다른 id를 쓰십시오. 생성은 아무것도 덮어쓰지 않습니다.',
+                };
+            }
+            const sections = Object.fromEntries(def.requiredSections.map((s) => [s, spec_types_1.FIELD_PLACEHOLDER]));
+            // Stub the required FRONTMATTER too, not just the sections. Without this every created spec
+            // fails the project's own `spec_validate` on `missing-field` the moment it is written, and
+            // the author has to rediscover the per-type field list by reading spec-types.ts. Caller-
+            // supplied values win; `coverage` needs a shaped default because T-SPEC reads its keys.
+            // `source` is a citation LIST, so a bare 'TODO' string would fail the shape check the moment
+            // the spec is written. The stub is validly shaped but obviously unfilled: it validates while
+            // the REQ is drafted and blocks approval until a real origin replaces the placeholder.
+            const stub = (f) => {
+                if (f === 'coverage')
+                    return { normal: false, corner: false, negative: false, boundary: false };
+                if (f === 'source')
+                    return [{ kind: 'other', ref: spec_types_1.CITATION_PLACEHOLDER, note: 'cite the real origin before approval' }];
+                return spec_types_1.FIELD_PLACEHOLDER;
+            };
+            const required = Object.fromEntries(def.requiredFields.filter((f) => !(f in extra)).map((f) => [f, stub(f)]));
+            // @implements A-SPEC-146
+            // Scaffolded but not required by `validateSpec` — see SpecTypeDef.stubOnlyFields for why the
+            // gap exists. The stub value is `TODO`, which is NOT an accepted grade, so the field is
+            // visible to the author while the approval still refuses until it is actually answered.
+            // Pre-filling `none` would be easier and would make the formulaic answer the default, which is
+            // exactly what ADR-013 recorded as its revisit trigger.
+            const stubOnly = Object.fromEntries((def.stubOnlyFields ?? []).filter((f) => !(f in extra)).map((f) => [f, stub(f)]));
+            const spec = { id, type, title, status: 'draft', dependsOn: depends_on, frontmatter: { ...required, ...stubOnly, ...extra }, sections };
+            // @implements A-SPEC-188 — existence is a PATH question, not only a list() question.
+            // Round-2 review probed the gap: list() drops unparseable files, so a prose note or
+            // broken-YAML document sitting at the exact target path was invisible to the id check above
+            // and got silently overwritten — with the refusal text elsewhere promising the opposite.
+            // A file the store cannot read as this id is a file a human must look at first.
+            if (store instanceof spec_store_1.LocalMarkdownRepository) {
+                const target = store.targetPathFor(spec);
+                if (fs.existsSync(target)) {
+                    return {
+                        ok: false,
+                        reason: `${id}의 목적지(${target})에 파일이 이미 있는데 스토어가 이 id의 스펙으로 읽지 못합니다`
+                            + ' — 손으로 쓰던 초안이거나 깨진 문서일 수 있습니다. 사람이 확인해 옮기거나 고치기 전까지 덮어쓰지 않습니다'
+                            + ' (doctor가 읽을 수 없는 스펙 파일을 보고합니다).',
+                    };
+                }
+            }
+            try {
+                await store.write(spec);
+            }
+            catch (e) {
+                // The pre-write path check above makes this a narrow race backstop; the store guard is the
+                // authority and this act relays it in the same wording the other writers use.
+                if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                    return {
+                        ok: false,
+                        reason: `${id}의 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다.`
+                            + ' 사람이 확인해 옮기거나 고친 뒤 다시 시도하십시오.',
+                    };
+                }
+                throw e;
+            }
+            return { created: id };
+        },
+        async spec_validate(a) {
+            const specs = await store.list();
+            const spec = specs.find((s) => s.id === a.id);
+            if (!spec)
+                return { ok: false, findings: [{ level: 'error', code: 'not-found', message: a.id }] };
+            return (0, validator_1.validateSpec)(spec, resolver(specs));
+        },
+        /**
+         * @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.
+         */
+        /**
+         * @implements A-SPEC-184
+         * Raise ONE named document from an older spec format to the current one.
+         *
+         * The compatibility policy this implements: older documents are read and left alone by default,
+         * and rise only when a human points at the one they intend to use. There is deliberately no bulk
+         * path — 155 documents here and 90 in the measured adoption target, and which of them are still
+         * live specifications is a judgement only a person holds.
+         *
+         * It declares a KIND. It does not confer approval: 37 of this repository's legacy documents read
+         * `status: Approved`, and carrying that across would mint approvals that never passed the sealing
+         * act. The old value is preserved as evidence and the document restarts at `draft`.
+         *
+         * Takes no `root`: the store is bound at server construction, exactly as `spec_create` is.
+         */
+        async spec_upgrade(a) {
+            // @implements A-SPEC-188 — same read-then-write shape as spec_approve, so the same window
+            // AND the same duplicate hazard: read() resolves the last-walked copy, and the write's orphan
+            // removal would delete the other. Refuse rather than pick a side.
+            if ((await store.list()).filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 보강 전에 거부합니다.`
+                        + ' doctor로 중복 파일을 확인해 하나로 정리한 뒤 다시 시도하십시오.',
+                };
+            }
+            const cur = await store.read(a.id);
+            if (!cur)
+                return { ok: false, reason: `spec ${a.id} not found` };
+            const spec = cur.spec;
+            const plan = (0, legacy_format_1.upgradePlan)(spec);
+            if (!plan) {
+                const why = (0, legacy_format_1.legacyMessage)(spec);
+                // No plan for two opposite reasons. Already current is success and writes nothing — a second
+                // run must not churn the file. An unsupported kind is a refusal, and its wording must not
+                // send the holder after a type that does not exist.
+                return why ? { ok: false, reason: why } : { ok: true, upgraded: false, reason: `${a.id}은(는) 이미 현행 양식입니다` };
+            }
+            const upgraded = {
+                ...spec,
+                type: plan.type,
+                status: 'draft',
+                frontmatter: (0, legacy_format_1.upgradedFrontmatter)(spec, plan),
+            };
+            try {
+                await store.write(upgraded, { expectedVersion: cur.version });
+            }
+            catch (e) {
+                if (e instanceof spec_store_2.SpecVersionConflictError) {
+                    return {
+                        ok: false,
+                        reason: `보강 진행 중 ${a.id}이(가) 바뀌었습니다 — 바뀐 내용을 확인하고 다시 시도하십시오.`
+                            + ' 이번 보강은 아무것도 쓰지 않았습니다.',
+                    };
+                }
+                // @implements A-SPEC-188 — the upgrade RELOCATES by design (legacy filename → canonical),
+                // so an unreadable file at the canonical path is the store's occupied-target refusal.
+                if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                    return {
+                        ok: false,
+                        reason: `${a.id}의 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다.`
+                            + ' 사람이 확인해 옮기거나 고친 뒤 다시 시도하십시오. 이번 보강은 아무것도 쓰지 않았습니다.',
+                    };
+                }
+                throw e;
+            }
+            // Report what still stands between this document and approval. Silence would read as "done",
+            // and a legacy document typically lacks most required sections.
+            const after = await store.list();
+            const remaining = (0, validator_1.validateSpec)(upgraded, resolver(after)).findings.filter((f) => f.level === 'error');
+            return { ok: true, upgraded: true, type: plan.type, legacyStatus: plan.legacyStatus, remaining };
+        },
+        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.
+            if (!(0, risk_gate_1.approvalCovers)(approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString())) {
+                return { ok: false, reason: '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)' };
+            }
+            // @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);
+            if (!cur)
+                return { ok: false, reason: `spec ${a.id} not found` };
+            const spec = cur.spec;
+            // @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 = [a.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
+            );
+            if (blocking.length > 0)
+                return { ok: false, reason: 'validation errors block approval', 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-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) };
+            }
+            // 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
+            // Detect seal MOVEMENT before overwriting: the prior on-disk seal, if any, is what "moved from".
+            const priorDigest = (0, spec_digest_1.sealOf)(spec).approvedDigest;
+            const digest = (0, spec_digest_1.specDigest)(candidate);
+            candidate.frontmatter.approved_digest = digest;
+            candidate.frontmatter.parent_digests = parentDigests;
+            // @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_2.SpecVersionConflictError) {
+                    return {
+                        ok: false,
+                        reason: `승인 진행 중 ${a.id}이(가) 바뀌었습니다 — 바뀐 내용을 확인하고 다시 승인하십시오.`
+                            + ' 이번 승인은 아무것도 쓰지 않았습니다.',
+                    };
+                }
+                // @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: approval.actor,
+                kind: 'spec-approved',
+                summary: `approved ${a.id} sealing ${digest}`,
+                inputs: [a.id, digest],
+                rationale: approval.rationale,
+                authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, 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: 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: approval.rationale, authorization: '',
+                    });
+                }
+                catch { /* a missed routing signal is not a broken seal */ }
+            }
+            return { approved: a.id, digest };
+        },
+        async spec_list(a) {
+            const specs = await store.list();
+            // @implements A-SPEC-186
+            // The parent travels with the id because a bare one cannot be read. Measured: a reader took
+            // `T-SPEC-1841` for a count of 1,841 documents. The old-habit ids this repository once held
+            // have since all been renamed or upgraded (measured 2026-08-15: zero remain), but ADOPTED
+            // repositories still write them, so the parent keeps traveling alongside.
+            //
+            // Read from `depends_on`, NEVER parsed out of the id — parsing would answer `A-SPEC-129` for
+            // a `T-SPEC-1291` that actually hangs off something else, which is the tool committing the
+            // very misreading this exists to prevent. Omitted rather than emptied when there is none:
+            // an empty value cannot be told apart from "we looked and failed".
+            const parentOf = (s) => {
+                // @implements A-SPEC-192 §6R (round 10) — the row became format-aware in the `legacy` field
+                // only; `parent` still keyed off the DECLARED type, so an old-format document that never
+                // declared one showed no parent even when its depends_on names one. The inferred kind
+                // answers the same question the legacy mark already asks.
+                const state = (0, legacy_format_1.formatStateOf)({ id: s.id, type: s.type });
+                const kind = s.type ?? (state.kind === 'legacy' ? state.inferred : undefined);
+                const kinds = (0, spec_types_1.specTypeDef)(kind)?.parents ?? [];
+                return s.dependsOn?.find((d) => kinds.some((k) => d.startsWith(`${k}-`)));
+            };
+            // @implements A-SPEC-192 — a non-canonical status must not dress like a governed row:
+            // measured 155 of 483 rows ('Approved', 'Proposed', 'deprecated'…) rendered identically to canonical
+            // ones, and an adopter read capital-A 'Approved' as an approval. Absence of the key marks the
+            // canonical row (the same omission convention as `parent` above). The set derives from the
+            // SPEC_STATUSES runtime list — a hand-copy here was a second truth the compiler cannot police.
+            const CANONICAL_STATUSES = new Set(spec_types_1.SPEC_STATUSES);
+            return {
+                specs: specs
+                    .filter((s) => !a?.type || s.type === a.type)
+                    .map((s) => {
+                    const parent = parentOf(s);
+                    // @implements A-SPEC-192 §5R (round 9) — the mark asks 'is this row a GOVERNED spec?',
+                    // and status alone could not answer it: an old-format document that never declared a
+                    // `type` came through with a lone `approved` and dressed exactly like a canonical row —
+                    // the misreading this REQ exists to prevent. Format and status are both grounds.
+                    const legacyFormat = (0, legacy_format_1.formatStateOf)({ id: s.id, type: s.type }).kind !== 'current';
+                    return {
+                        id: s.id, type: s.type, status: s.status,
+                        ...(parent ? { parent } : {}),
+                        ...(CANONICAL_STATUSES.has(s.status) && !legacyFormat ? {} : { legacy: true }),
+                    };
+                }),
+            };
+        },
+        async spec_next() {
+            const specs = await store.list();
+            // 다음에 작성 가능한 첫 미승인 단계
+            for (const t of spec_types_1.SPEC_ORDER) {
+                const has = specs.some((s) => s.type === t && s.status === 'approved');
+                if (!has)
+                    return { next: t };
+            }
+            return { next: null };
+        },
+        async rtm_check(a) {
+            const specs = await store.list();
+            // rtm_check runs on the GOVERNED set only (excludes archived legacy +
+            // JOB specs, which otherwise flood orphan/dangling results; see
+            // ADR-010).
+            const issues = (0, rtm_check_1.rtmCheck)((0, spec_types_1.filterGoverned)(specs));
+            // @implements A-SPEC-146 — a REPORT, not a verdict: ADR-013 named formulaic `none` a
+            // revisit trigger for a human, and `(unset)` shows how far the corpus has converged.
+            const breakingChangeDistribution_ = (0, breaking_change_1.breakingChangeDistribution)((0, spec_types_1.filterGoverned)(specs));
+            if (a?.root) {
+                // @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);
+                // Citation drift: a REQ's cited source may have been edited since it was read, which silently
+                // invalidates the requirement derived from it. Only refs that resolve to a file INSIDE the
+                // repo are re-hashed — an unresolvable ref (external ticket, no adapter configured) is not
+                // evidence of drift, and a path escaping the repo is not ours to read.
+                const readLocal = (ref) => {
+                    const abs = path.resolve(root, ref);
+                    if (!abs.startsWith(path.resolve(root) + path.sep))
+                        return null;
+                    try {
+                        return fs.readFileSync(abs, 'utf8');
+                    }
+                    catch {
+                        return null;
+                    }
+                };
+                for (const s of specs) {
+                    if (s.type !== 'REQ' || s.frontmatter.source == null)
+                        continue;
+                    for (const d of (0, validator_1.verifyCitationDigests)(s.frontmatter.source, readLocal)) {
+                        issues.push({ level: d.level, code: d.code, message: `${s.id}: ${d.message}` });
+                    }
+                }
+                const scanned = cachedScan(root, root);
+                // checkImplements checks @implements A-SPEC refs against the FULL
+                // spec id set (not filterGoverned) — it's an existence check: any
+                // existing spec id is a valid anchor target.
+                issues.push(...(0, rtm_check_1.checkImplements)(scanned, specs));
+                // L6 convergence gaps (ADVISORY, not issues): where implementation and the governed spec set
+                // have drifted apart — unimplemented approved specs, unanchored source, untested specs. Feeds
+                // the convergence loop's "pick next work"; an unimplemented spec is normal mid-development.
+                const gaps = (0, gap_analyzer_1.computeConvergenceGaps)(scanned, (0, spec_types_1.filterGoverned)(specs), (0, test_scope_1.scanTestAnchors)(root));
+                return { issues, gaps, breakingChangeDistribution: breakingChangeDistribution_ };
+            }
+            return { issues, breakingChangeDistribution: breakingChangeDistribution_ };
+        },
+        /**
+         * 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 = foreignRootReason(store, 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_2.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 };
+        },
+        async phase_status(a) {
+            // @implements A-SPEC-189 §6 — `root` was advertised and never read, so a call naming another
+            // project (or a path that does not exist) got THIS server's corpus in a success shape and the
+            // caller derived its phase from someone else's specs. Same anchor discipline as spec_approve.
+            if (typeof a?.root === 'string' && a.root !== '' && store instanceof spec_store_1.LocalMarkdownRepository) {
+                let asked;
+                let bound;
+                let derivationFoundMarker = false;
+                try {
+                    asked = (0, write_target_1.resolveTarget)(projectRootOf(a.root), '.');
+                    const derived = projectRootOf(store.specsRoot);
+                    derivationFoundMarker = fs.existsSync(path.join(derived, '.ax'));
+                    bound = (0, write_target_1.resolveTarget)(derived, '.');
+                }
+                catch (e) {
+                    return { ok: false, reason: `root를 해석할 수 없습니다: ${String(e.message)}` };
+                }
+                // @implements A-SPEC-189 §7 (round 10) — spec_approve's round-3 lesson, copied here at last:
+                // resolveProjectRoot returns its INPUT when no `.ax` ancestor exists, so a custom
+                // HOLMES_SPECS outside any project "derived" the spec store itself as the project and this
+                // guard then refused the CORRECT root. Only a derivation that actually found a marker
+                // speaks for a project.
+                if (derivationFoundMarker && asked !== bound) {
+                    return {
+                        ok: false,
+                        reason: `이 서버는 ${bound} 프로젝트에 바인딩되어 있습니다 — 요청한 root ${a.root}는 ${asked} 를 가리킵니다.`
+                            + ' 다른 프로젝트의 코퍼스를 이 서버가 대신 답하지 않습니다.',
+                    };
+                }
+            }
+            const specs = await store.list();
+            return { specs: specs.map((s) => ({ id: s.id, type: s.type, status: s.status })), note: 'derive phase via phase_check' };
+        },
+        async phase_check(a) {
+            const specs = await store.list();
+            const action = a.action ?? (0, phase_1.classifyAction)(a.target);
+            if (!action)
+                return { decision: 'allow', note: 'unclassified target' };
+            return (0, phase_1.phaseCheck)(action, { specs, targetAspecId: a.targetAspecId });
+        },
+        async cpg_scan(a) {
+            // @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-131
+            // The skip report is part of the answer: a caller cannot distinguish "clean tree" from "tree
+            // with casualties" by counts alone. Bounded listing (50), complete count.
+            const { scanned, skipped } = cachedScanWithReport(root);
+            const symbols = scanned.reduce((n, f) => n + f.symbols.length, 0);
+            return { files: scanned.length, symbols, skipped: skipped.slice(0, 50), skippedCount: skipped.length };
+        },
+        /**
+         * @implements A-SPEC-138
+         * Call-graph taint REACHABILITY screen: source-named functions that reach sink-named functions
+         * through call edges. A SCREENING signal that routes a security review, NOT a data-flow proof —
+         * the result always carries the honesty envelope (kind + limits) and phrases pairs as "reaches",
+         * never "vulnerable".
+         */
+        async taint_scan(a) {
+            const root = projectRootOf(a.root);
+            const scanned = cachedScan(root, root);
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(await store.list(), scanned, g);
+                const cfg = taint_1.DEFAULT_TAINT_CONFIG;
+                const { pairs, truncated } = (0, taint_1.taintReachability)(g, cfg);
+                return { kind: 'call-reachability', limits: [...taint_1.TAINT_LIMITS], maxPaths: cfg.maxPaths, truncated, pairs };
+            }
+            finally {
+                g.close();
+            }
+        },
+        async test_run(a) {
+            // Closes the decision->execution loop: scope -> run -> durable per-A-SPEC EXECUTION evidence
+            // (what the constitution's ART-4 prefers over the syntactic count).
+            const { root, specs, scanned, changedSymbols, changeSource, scopeFallback, anchorImpactedSpecs, changedTestFiles, unresolvedFiles } = await deriveChangedContext(store, a.root, a, 'test_run');
+            const g = new rtm_graph_1.RtmGraph();
+            let testScope;
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                const scope = (0, scope_1.computeReviewScope)(g, specs, changedSymbols);
+                // @implements A-SPEC-130
+                // Lane 2 widens the impacted set with file-anchor edges the symbol walk cannot see; lanes 3
+                // and the unresolved remainder ride in through extras. A nonempty change set can end in a
+                // scoped run or a full run — never in "nothing to do".
+                const widenedImpacted = [...new Set([...scope.impactedSpecs, ...anchorImpactedSpecs])];
+                testScope = (0, test_scope_1.computeTestScope)(widenedImpacted, (0, test_scope_1.scanTestAnchors)(root), specs, scope.coverageGaps, undefined, { changedTestFiles, unresolvedFiles });
+                // @implements A-SPEC-128
+                // No change set means no basis for narrowing. Widening is the same fail-safe direction
+                // computeTestScope already takes when no anchored test resolves — never a silently narrow run.
+                if (scopeFallback === 'full') {
+                    testScope = { ...testScope, tier: 'full', reason: `${changeSource.reason ?? 'no change set'} — cannot narrow safely, full regression` };
+                }
+            }
+            finally {
+                g.close();
+            }
+            const result = (0, test_runner_1.runTestScope)(testScope, root);
+            const anchors = (0, test_scope_1.scanTestAnchors)(root);
+            const executedByAspec = (0, test_evidence_1.computeExecutedByAspec)(result.executedByFile ?? {}, anchors);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+            }
+            catch { /* non-git */ }
+            // Record ONLY an actually-executed, GREEN run (review C4/C7): a red suite must not stand as
+            // coverage evidence at the moment the code is broken, and a no-op run must not overwrite a real
+            // record with a dishonest `passed: true` over an empty result.
+            const verified = (0, baseline_1.shouldRecordBaseline)(result);
+            if (verified) {
+                (0, test_evidence_1.writeTestEvidence)(root, { ts: new Date().toISOString(), head, tier: testScope.tier, passed: true, executedByAspec });
+            }
+            // @implements A-SPEC-128
+            // The baseline is written under EXACTLY the condition that already gates evidence: a run that
+            // actually executed and passed. A red or skipped run must never become the reference point for
+            // "since the last verified state" — that would silently narrow every later scope against a
+            // state nobody verified.
+            let baseline;
+            if (verified) {
+                baseline = a.mark ?? DEFAULT_BASELINE;
+                (0, baseline_1.writeBaseline)(root, baseline, (0, change_source_1.hashTree)(root, { isIgnored: (p) => (0, ignore_1.loadIgnore)(root).isIgnored(p) }));
+            }
+            return { tier: testScope.tier, mode: result.mode, passed: result.passed, skipped: result.skipped,
+                ranFiles: result.ranFiles, executedByAspec, tail: result.tail,
+                // @implements A-SPEC-130 — the remediation rides in the answer: these are the files to anchor.
+                unresolvedFiles: testScope.unresolvedFiles,
+                changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}) };
+        },
+        async issue_localize(a) {
+            // N1: deterministic localization report — CPG lexical match fused with the RTM spec hop.
+            // @implements A-SPEC-189 §14 (round 13) — `projectRootOf(a.root)` was called as a bare
+            // statement: its only effect was to throw on a bad path, and the advertised contract ("a
+            // subdirectory resolves up to it") was dropped on the floor. `taint_scan` one function away
+            // honours it, so the same argument answered about two different trees depending on which tool
+            // was asked. Bind the derivation and use it.
+            const root = projectRootOf(a.root);
+            const scanned = cachedScan(root, root);
+            const specs = await store.list();
+            return (0, localize_1.localizeIssue)(a.issue, scanned, (0, spec_types_1.filterGoverned)(specs), a.topN ?? 10);
+        },
+        async rtm_impact(a) {
+            // @implements A-SPEC-189 §14 (round 13) — `projectRootOf(a.root)` was called as a bare
+            // statement: its only effect was to throw on a bad path, and the advertised contract ("a
+            // subdirectory resolves up to it") was dropped on the floor. `taint_scan` one function away
+            // honours it, so the same argument answered about two different trees depending on which tool
+            // was asked. Bind the derivation and use it.
+            const root = projectRootOf(a.root);
+            const scanned = cachedScan(root);
+            const specs = await store.list();
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                // explainImpact, not impactedBy: the bounds and the breadth signal must reach the caller.
+                // An impact set is not just a list — a broad one means "review the contract", and a consumer
+                // that cannot tell the difference will try to bundle two hundred call sites.
+                const { specs: impacted, reachedByDepth, stoppedAt, seedIsHub } = (0, rtm_builder_1.explainImpact)(g, a.changed);
+                return {
+                    impacted,
+                    reachedByDepth,
+                    bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,
+                    ...(seedIsHub ? {
+                        breadthWarning: `a changed symbol has ${seedIsHub.callers} callers (hub threshold ${seedIsHub.threshold}) — this is a CONTRACT change; review the contract and its tests rather than bundling every impacted spec`,
+                    } : {}),
+                };
+            }
+            finally {
+                g.close(); // release native SQLite handle even if build/query throws
+            }
+        },
+        async rtm_reindex(a) {
+            // Removal/re-derivation of changedFiles/changedSymbols is not needed
+            // here (rtm_reindex works off changes/specs/scanned/bySourcePath
+            // directly), but the guard+diff+scan prologue is identical to
+            // review_scope/review_prepare — see deriveChangedContext.
+            const { root, changes, specs, scanned, bySourcePath, changeSource } = await deriveChangedContext(store, a.root, a, 'rtm_reindex');
+            const changed = changes.added.length + changes.modified.length + changes.deleted.length + changes.renamed.length;
+            const scanOne = (relPath) => bySourcePath.get(relPath) ?? null;
+            // HashCache skip: for add/modify entries, if the file's current content
+            // hash matches what's on record, the file is dropped from the set
+            // handed to applyIncremental — its subgraph is left untouched rather
+            // than being torn down and rebuilt for no reason (e.g. a spurious
+            // `git diff` entry, a mode-only change, or a re-run over the same
+            // range). Deletes and renames are always applied: a delete has no
+            // "content" to compare, and a rename's `from` side must be removed
+            // regardless of whether `to`'s content matches something previously
+            // hashed under a different path.
+            const cache = new hash_cache_1.HashCache(cacheDirFor(root)); // @implements A-SPEC-128 — project-root cache, no subdir leak
+            const skipUnchanged = (files) => files.filter((relPath) => {
+                let content;
+                try {
+                    content = fs.readFileSync(path.join(root, relPath), 'utf8');
+                }
+                catch {
+                    return true; // unreadable (e.g. already gone) — let applyIncremental/scanOne handle it
+                }
+                if (cache.unchanged(relPath, content))
+                    return false; // skip: content identical to last recorded hash
+                cache.put(relPath, content);
+                return true;
+            });
+            const changesToApply = {
+                added: skipUnchanged(changes.added),
+                modified: skipUnchanged(changes.modified),
+                deleted: changes.deleted,
+                renamed: changes.renamed,
+            };
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                // Scaffold note: `g` was just full-built at HEAD, so applying the
+                // diff on top of it is currently an idempotent no-op in practice
+                // (the affected subgraphs are already correct). This call exists to
+                // exercise/validate the incremental machinery end-to-end now, ahead
+                // of a FUTURE persisted-graph reindex — build the graph once, then
+                // apply diffs across calls without a full rebuild — that will
+                // actually depend on this path being correct. Not load-bearing today.
+                (0, incremental_1.applyIncremental)(g, changesToApply, { repoRoot: root, specs, scanOne });
+                return { changed, nodes: g.nodeCount(), edges: g.edgeCount(), changeSource };
+            }
+            finally {
+                g.close(); // release native SQLite handle even if build/apply throws
+            }
+        },
+        async context_bundle(a) {
+            const foreign = foreignRootReason(store, a.root);
+            if (foreign)
+                throw new HandlerRefusal(foreign);
+            const root = projectRootOf(a.root);
+            const specs = await store.list();
+            const scanned = cachedScan(root, root);
+            const content = buildContentSource(specs, scanned);
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                return new bundler_1.ContextBundler(g, content).getContextBundle(a.seedId, a.budget);
+            }
+            finally {
+                g.close(); // release native SQLite handle even if bundling throws
+            }
+        },
+        async review_scope(a) {
+            // Guard+diff+scan+changedFiles/changedSymbols prologue: see
+            // deriveChangedContext (shared with review_prepare/rtm_reindex).
+            const { root, specs, scanned, changedFiles, changedSymbols, changeSource, scopeFallback, anchorImpactedSpecs, changedTestFiles, unresolvedFiles } = await deriveChangedContext(store, a.root, a, 'review_scope');
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                const scope = (0, scope_1.computeReviewScope)(g, specs, changedSymbols);
+                // Intelligent regression test-scope (target-arch §5). Test files are scanned SEPARATELY for
+                // their @implements anchors (the CPG scan excludes tests), coverage gaps feed the safety
+                // fallback, and impactedSpecs are the graph's SPEC:-prefixed ids (stripped inside).
+                // @implements A-SPEC-130 — the same widened set as test_run, so review packaging and test
+                // scoping cannot disagree about what a change touches.
+                const widenedImpacted = [...new Set([...scope.impactedSpecs, ...anchorImpactedSpecs])];
+                const testScope = (0, test_scope_1.computeTestScope)(widenedImpacted, (0, test_scope_1.scanTestAnchors)(root), specs, scope.coverageGaps, undefined, { changedTestFiles, unresolvedFiles });
+                // Honest signal (REQ-124 gate 2a): which changed files the CpgScanner
+                // did NOT ingest (e.g. non-.ts files), computed from the same
+                // changedFiles/scanned already derived above — no new git/scan calls.
+                const { unscanned: unscannedChangedFiles } = (0, coverage_1.partitionChangedFiles)(changedFiles, scanned.map((f) => f.sourcePath));
+                return { ...scope, unscannedChangedFiles, testScope, changeSource, ...(scopeFallback ? { scopeFallback } : {}) };
+            }
+            finally {
+                g.close(); // release native SQLite handle even if scope computation throws
+            }
+        },
+        async review_prepare(a) {
+            // Guard+diff+scan+changedFiles/changedSymbols prologue: see
+            // deriveChangedContext (shared with review_scope/rtm_reindex).
+            const { root, specs, scanned, changedFiles, changedSymbols, changeSource, scopeFallback } = await deriveChangedContext(store, a.root, a, 'review_prepare');
+            // ContentSource factory shared with context_bundle: see buildContentSource.
+            const content = buildContentSource(specs, scanned);
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                const pkg = (0, package_1.assembleReviewPackage)(g, specs, changedSymbols, content, a.budget ?? 4000);
+                // Honest signal (REQ-124 gate 2a): which changed files the CpgScanner
+                // did NOT ingest, computed from the same changedFiles/scanned already
+                // derived above — no new git/scan calls.
+                const { unscanned: unscannedChangedFiles } = (0, coverage_1.partitionChangedFiles)(changedFiles, scanned.map((f) => f.sourcePath));
+                return { package: pkg, unscannedChangedFiles, changeSource, ...(scopeFallback ? { scopeFallback } : {}) };
+            }
+            finally {
+                g.close(); // release native SQLite handle even if assembly throws
+            }
+        },
+        async review_record(a) {
+            // @implements A-SPEC-189 §8 (round 11) — §15 shut the door the merge gate READS through and
+            // left the one it is WRITTEN through wide open. Measured: `review_record` joined the caller's
+            // `root` straight into a path and created `.ax/ledger/findings.jsonl` in any directory on the
+            // machine, answering `{recorded: N}` — while `review_status`, bound to this server's project,
+            // could never see those findings. An open critical filed at the wrong root is worse than none:
+            // it reads as recorded and gates nothing. The two doors now ask the same question.
+            const foreignWrite = foreignRootReason(store, a.root);
+            if (foreignWrite !== null)
+                throw new HandlerRefusal(`review_record: ${foreignWrite}`);
+            // MCP input is unvalidated JSON: an out-of-enum severity or status
+            // (e.g. a typo like "blocker") would land in the ledger as a stray
+            // value that review_status's counts never match, so it counts toward
+            // neither its own bucket nor `blocked` — a mislabeled critical could
+            // silently pass the gate. Validate up front so the gate's counts stay
+            // trustworthy.
+            const validSeverities = new Set(['critical', 'important', 'minor']);
+            const validStatuses = new Set(['open', 'resolved']);
+            for (const f of a.findings) {
+                if (!validSeverities.has(f.severity)) {
+                    throw new HandlerRefusal(`review_record: finding ${f.id} has invalid severity ${JSON.stringify(f.severity)} (must be one of critical|important|minor)`);
+                }
+                if (!validStatuses.has(f.status)) {
+                    throw new HandlerRefusal(`review_record: finding ${f.id} has invalid status ${JSON.stringify(f.status)} (must be one of open|resolved)`);
+                }
+            }
+            // @implements A-SPEC-191 (§4e) — the ledger's meaning is guarded at RECORD time, where the
+            // collision actually happens. Measured: conventional ids (C1…) recur across review rounds, so
+            // one round's resolve of "C1" silently lifted the gate over ANOTHER round's unfixed critical;
+            // and a severity-downgrade re-open cleared ART-7 with no resolution at all. Both die at one
+            // door: an id whose latest state is open cannot be opened again — resolve first, then
+            // re-record. Lifting an open CRITICAL requires the out-of-band approval channel (ART-5's
+            // principle): the blocked party must not be able to pull its own teeth in-band. A resolved
+            // record for an id never opened lifts nothing and stays approval-free (found-and-fixed audit
+            // records keep working).
+            // The guard and the append hold ONE lock (round-6: the read→judge→append section was a
+            // cross-process TOCTOU — two sessions both recorded open under the same id, silencing an
+            // open critical at both readers; consumeNonceExclusively already earned this discipline).
+            const findingsFile = boundFindingsLedger(store, a.root);
+            (0, ledger_lock_1.withLedgerLock)(findingsFile, () => {
+                const ledger = new findings_1.FindingsLedger(findingsFile);
+                const latest = new Map();
+                const liftedCriticals = [];
+                for (const f of ledger.list())
+                    latest.set(f.id, f);
+                for (const f of a.findings) {
+                    if (!f.id || !f.id.trim()) {
+                        throw new HandlerRefusal('review_record: finding id 가 비어 있습니다 — 모든 발견은 원장에서 유일하게 식별될 id 가 필요합니다');
+                    }
+                    // Round-5: pre-round-4 ads declared `message`, but the ledger whitelist persists only
+                    // `summary` — clients following the OLD ad lost their text with zero signal. A pointed
+                    // refusal turns that silent loss into the one-line fix it needs.
+                    // Round-9: `=== undefined` let `summary: null` through, so the ledger dropped the text
+                    // and the caller saw success — the very silence this guard exists to end. Absence is
+                    // null OR undefined here, as everywhere else in this validator's vocabulary.
+                    if ('message' in f && (f.summary === undefined || f.summary === null)) {
+                        throw new HandlerRefusal(`review_record: finding ${f.id} 의 message 는 폐지된 광고 키입니다 — 원장은 summary 만 보존합니다. 같은 내용을 summary 로 보내십시오`);
+                    }
+                    const last = latest.get(f.id);
+                    if (f.status === 'open' && last?.status === 'open') {
+                        throw new HandlerRefusal(`review_record: id ${f.id} 는 이미 미해소(open) 상태입니다 — 다른 발견이면 새 id 를 쓰고, 같은 발견의 갱신이면 먼저 resolved 를 기록한 뒤 재기록하십시오 (id 충돌이 남의 critical 을 침묵시키는 것을 막는 문입니다)`);
+                    }
+                    if (f.status === 'resolved' && last?.status === 'open' && last.severity === 'critical') {
+                        const raw = process.env.HOLMES_APPROVAL;
+                        let approval;
+                        try {
+                            approval = raw ? JSON.parse(raw) : undefined;
+                        }
+                        catch {
+                            approval = undefined;
+                        }
+                        // covers, not merely well-formed (round-2): A-SPEC-133 built the seam so one token is
+                        // not a master key — an EXPIRED or elsewhere-scoped approval must not lift a critical.
+                        // An unscoped {actor,token,rationale} stays the operator's session key (unchanged).
+                        const nowTs = new Date().toISOString();
+                        if (!(0, risk_gate_1.approvalCovers)(approval, { kind: 'review-resolve', target: f.id }, nowTs)) {
+                            throw new HandlerRefusal(`review_record: id ${f.id} 의 열린 치명 발견을 해소하는 기록은 이 행위를 덮는 유효한 대역외 승인이 필요합니다 — 차단당한 쪽이 스스로 이빨을 뽑을 수 없어야 하고, 만료·다른 범위의 승인은 덮지 않습니다. HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why fixed>"}' (범위를 쓰면 kind "review-resolve") 를 서버 환경에 설정하고 다시 기록하십시오`);
+                        }
+                        // @implements A-SPEC-191 §11 — 한 배치가 같은 id 를 다시 열고 다시 닫으면 lift 는 두 번
+                        // 일어난다. 소비는 호출당 1회이므로, 세 번의 호출이면 거부됐을 일이 한 배치에서는
+                        // 통과했다(실측: 최종 상태와 게이트 판정이 갈렸다).
+                        if (liftedCriticals.includes(f.id)) {
+                            throw new HandlerRefusal(`review_record: 한 배치에서 같은 발견(${f.id})의 치명 해소를 두 번 들 수 없습니다 — 승인은 행위마다 필요합니다`);
+                        }
+                        liftedCriticals.push(f.id);
+                    }
+                    latest.set(f.id, f); // 한 배치 안의 순서도 기록 순서다
+                }
+                // A-SPEC-133 promises nonce = single-use "consumed on the ledger, a replay is denied".
+                // Consumed AFTER the whole batch validates and ONCE per call (round-4: consuming inside
+                // the loop burned the grant when a LATER row failed validation — the audit trail asserted
+                // an act that never happened, the retry was refused, and two resolves in one batch would
+                // have double-spent). Consumption directly precedes the append; the only failure between
+                // them is the append itself, which throws loudly.
+                if (liftedCriticals.length > 0) {
+                    const raw = process.env.HOLMES_APPROVAL;
+                    let approval;
+                    try {
+                        approval = raw ? JSON.parse(raw) : undefined;
+                    }
+                    catch {
+                        approval = undefined;
+                    }
+                    if ((0, provenance_chain_1.blankNonce)(approval?.nonce)) {
+                        throw new HandlerRefusal('review_record: 승인이 단일 사용(nonce)을 선언했으나 값이 비어 있습니다 — 1회성을 집행할 수 없어 거부합니다');
+                    }
+                    // @implements A-SPEC-191 §13 — 1회용 승인은 한 번의 행위를 authorize 한다. 9라운드
+                    // 실측: 서로 다른 id 의 치명 해소 N 건이 한 배치에서 nonce 한 장으로 통과했고,
+                    // 같은 세 건을 세 호출로 나누면 두 번째부터 거부됐다 — 판정이 묶음 방식에 의존했다.
+                    if ((0, provenance_chain_1.nonceDeclared)(approval?.nonce) && liftedCriticals.length > 1) {
+                        throw new HandlerRefusal(`review_record: 단일 사용 승인(nonce)은 한 건의 치명 해소만 authorize 합니다 — 이 배치는 ${liftedCriticals.length}건(${liftedCriticals.join(', ')})을 듭니다. 한 건씩 보내십시오`);
+                    }
+                    if ((0, provenance_chain_1.nonceDeclared)(approval?.nonce)) {
+                        // @implements A-SPEC-191 §10 — the same bound anchor as risk_check: two consumers must
+                        // spend into ONE ledger, or a nonce spent here reopens the gate there (and back).
+                        const ledgerFile = boundNonceLedger(store);
+                        if (ledgerFile === null) {
+                            throw new HandlerRefusal('review_record: 단일 사용 승인(nonce)을 기록할 프로젝트 원장을 확정할 수 없습니다 — 1회성을 보장할 수 없어 거부합니다');
+                        }
+                        const won = (0, provenance_chain_1.consumeNonceExclusively)(String(approval.nonce), ledgerFile, {
+                            ts: new Date().toISOString(), actor: approval.actor, kind: 'nonce-consumed',
+                            summary: `consumed single-use approval for: review-resolve ${liftedCriticals.join(', ')}`.slice(0, 200),
+                            inputs: [(0, provenance_chain_1.nonceFingerprint)(String(approval.nonce))], rationale: approval.rationale,
+                            authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token),
+                        });
+                        if (!won) {
+                            throw new HandlerRefusal(`review_record: 단일 사용 승인(nonce)이 이미 소비되었습니다 — 재사용은 거부됩니다. 새 승인을 발급받으십시오`);
+                        }
+                    }
+                }
+                // @implements A-SPEC-157 — the server's OWN observation, not anything the caller sent.
+                // @implements A-SPEC-160 — the ONLY caller that reads the on-disk build, so the divergence
+                // marker can be sealed. Append INSIDE the same lock as the guard (round-6 TOCTOU).
+                ledger.record(a.findings, (0, basis_1.basisDigest)(basisFor(a.root, true)));
+            });
+            return { recorded: a.findings.length };
+        },
+        async review_status(a) {
+            // @implements A-SPEC-191 §15 — the merge gate must not answer about a project it did not read.
+            const foreign = foreignRootReason(store, a.root);
+            if (foreign !== null)
+                throw new HandlerRefusal(`review_status: ${foreign}`);
+            // @implements A-SPEC-191 (§4f) — counted on the LATEST record per id, the same folding the
+            // constitution's ART-7 uses. Line-based counting could never decrease on an append-only
+            // ledger, so the canonical exit (a resolved line) left `blocked: true` forever while the Stop
+            // gate passed — two official verdicts about one ledger, disagreeing permanently (measured).
+            const all = new findings_1.FindingsLedger(boundFindingsLedger(store, a.root)).list();
+            const latest = new Map();
+            // Severity of the LATEST open row per id — a forever-sticky "ever critical" set resurrected
+            // a properly-closed critical when a later minor re-finding got a diverged resolve (r6).
+            const lastOpenCritical = new Map();
+            for (const f of all) {
+                latest.set(f.id, f);
+                if (f.status === 'open')
+                    lastOpenCritical.set(f.id, f.severity === 'critical');
+            }
+            // SAME ledger meaning as ART-7 (round-3: the two official readers disagreed): a resolution
+            // sealed on a diverged build does not close a critical here either. What it keeps open is
+            // the CRITICAL it failed to close — bucketing by the resolved line's own severity let a
+            // severity-downgraded diverged resolve report blocked:false while the Stop gate blocked
+            // (round-4 HIGH), and a severity-less row minted an "undefined" bucket.
+            const counts = { critical: 0, important: 0, minor: 0 };
+            for (const f of latest.values()) {
+                if (f.status === 'open') {
+                    if (Object.prototype.hasOwnProperty.call(counts, f.severity))
+                        counts[f.severity]++; // in-체크는 프로토타입 키(toString)로 새었다(r6)
+                    continue;
+                }
+                if (f.status === 'resolved' && lastOpenCritical.get(f.id) === true && (0, basis_1.basisDiverged)(f.basis))
+                    counts.critical++;
+            }
+            // @implements A-SPEC-135
+            // Surface outstanding P4 routing signals: specs whose approved content moved, with the anchored
+            // files awaiting targeted review. This is a backlog to route human attention, NOT a hard block —
+            // the review layer decides severity — so it does not touch `blocked`.
+            // @implements A-SPEC-189 §12 (round 12) — the findings moved onto the bound project in §8 and
+            // this line stayed on the caller's raw root, so the SAME project answered with or without a
+            // P4 routing backlog depending on how its root was spelled (a subdirectory passes the
+            // project-level foreign check). One question, one tree.
+            const reviewNeeded = (0, review_targets_1.readReviewNeeded)(path.join(path.dirname(boundFindingsLedger(store, a.root)), 'provenance.jsonl'));
+            return { blocked: counts.critical > 0 || counts.important > 0, open: counts, reviewNeeded };
+        },
+        // @implements A-SPEC-125.4
+        async risk_check(a) {
+            const action = { ...a.action };
+            if (a.root && a.changedSymbols && a.changedSymbols.length) {
+                // @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);
+                const specs = await store.list();
+                const scanned = cachedScan(root, root);
+                const g = new rtm_graph_1.RtmGraph();
+                try {
+                    (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                    const impacted = (0, rtm_builder_1.impactedBy)(g, a.changedSymbols);
+                    action.blastRadius = { impactedSpecCount: impacted.length, hitsFoundational: impacted.some((id) => id.startsWith('SPEC:REQ-')) };
+                }
+                finally {
+                    g.close(); // release native SQLite handle even if build/query throws
+                }
+            }
+            const assessment = (0, risk_classifier_1.assessRisk)(action);
+            // @implements A-SPEC-133 — coverage (scope + expiry), not mere well-formedness, decides whether
+            // this approval authorizes THIS action. An out-of-scope or expired token no longer unblocks.
+            const coverTarget = { kind: action.kind, target: typeof action.target === 'string' ? action.target : String(action.target ?? '') };
+            let gate = (0, risk_gate_1.riskGate)(assessment, a.approval, a.enforcement, { action: coverTarget, now: a.ts });
+            const covers = (0, risk_gate_1.approvalCovers)(a.approval, coverTarget, a.ts);
+            // @implements A-SPEC-133 — the hard-hitl branch HONORS a nonce by SPENDING it (r7-191 HIGH:
+            // this consumer accepted single-use approvals and spent nothing — 'N-RISK' unblocked three
+            // times; a replayed approval must deny exactly as an absent one would).
+            // @implements A-SPEC-191 §13 — 승인이 실제로 문을 여는 경우에만 승인의 하자를 따진다.
+            // 9라운드 실측: 승인이 아예 필요 없던 낮은 판정까지 환경에 놓인 토큰의 모양 때문에
+            // 차단됐다 — 승인을 쥔 쪽이 안 쥔 쪽보다 나빠지는 역전이다.
+            const wouldBlockWithout = (0, risk_gate_1.riskGate)(assessment, undefined, a.enforcement, { action: coverTarget, now: a.ts }).blocked;
+            if (!gate.blocked && covers && wouldBlockWithout && (0, provenance_chain_1.blankNonce)(a.approval?.nonce)) {
+                gate = { ...gate, blocked: true, reasons: [...gate.reasons, '승인이 단일 사용(nonce)을 선언했으나 값이 비어 있거나 문자열이 아닙니다 — 1회성을 집행할 수 없어 거부합니다'] };
+            }
+            // 묶인 프로젝트가 없으면 개방을 기록할 수 없다 — 기록되지 않는 개방은 개방하지 않는다.
+            if (!gate.blocked && covers && wouldBlockWithout && boundNonceLedger(store) === null) {
+                gate = { ...gate, blocked: true, reasons: [...gate.reasons, '개방을 기록할 프로젝트 원장을 확정할 수 없습니다 — 기록 없는 개방은 하지 않습니다(.ax 를 가진 프로젝트에 바인딩된 서버에서 호출하십시오)'] };
+            }
+            if (assessment.level === 'hard-hitl' && !gate.blocked && covers && (0, provenance_chain_1.nonceDeclared)(a.approval?.nonce)) {
+                const ledgerFile = boundNonceLedger(store);
+                let won = false;
+                try {
+                    won = ledgerFile !== null && (0, provenance_chain_1.consumeNonceExclusively)(String(a.approval.nonce), ledgerFile, {
+                        ts: a.ts, actor: a.approval.actor, kind: 'nonce-consumed',
+                        summary: `consumed single-use approval for: ${coverTarget.kind} ${(0, provenance_chain_1.redactTarget)('command', coverTarget.target)}`.slice(0, 200),
+                        inputs: [(0, provenance_chain_1.nonceFingerprint)(String(a.approval.nonce))], rationale: a.approval.rationale,
+                        authorization: (0, provenance_chain_1.authorizationRef)(a.approval.actor, a.approval.token),
+                    });
+                }
+                catch {
+                    won = false;
+                } // 배타 확보 실패 = 허용 불가(fail-closed)
+                if (!won) {
+                    gate = { ...gate, blocked: true, reasons: [...gate.reasons, ledgerFile === null
+                                ? '단일 사용 승인(nonce)을 기록할 프로젝트 원장을 확정할 수 없습니다 — 1회성을 보장할 수 없어 거부합니다(.ax 를 가진 프로젝트에 바인딩된 서버에서 호출하십시오)'
+                                : '단일 사용 승인(nonce)이 이미 소비되었습니다 — 재사용은 부재와 같이 거부됩니다'] };
+                }
+            }
+            // Honest provenance: a confirm-level action that was NOT blocked but received no COVERING
+            // approval must NOT be recorded as 'approved' (nobody authorized it for this action) — it
+            // 'proceeded unconfirmed'. Only a genuine covering out-of-band approval yields 'approved'.
+            const decision = gate.blocked
+                ? 'blocked'
+                : covers
+                    ? 'approved'
+                    : gate.requiresApproval
+                        ? 'proceeded-unconfirmed'
+                        : 'auto';
+            const evt = { ts: a.ts, actor: a.actor ?? a.approval?.actor ?? 'unknown', action, level: assessment.level, decision, rationale: a.rationale ?? a.approval?.rationale ?? '', reasons: assessment.reasons };
+            // @implements A-SPEC-191 §10 — a bound server files its decisions in the project it is bound
+            // to. r8: the audit line for a nonce-replay opening landed in the caller's scratch directory,
+            // so the project whose gate was opened held no trace of it.
+            const bound = boundNonceLedger(store);
+            const decisionsFile = bound !== null
+                ? path.join(path.dirname(bound), 'decisions.jsonl')
+                : path.join(a.root ?? '.', '.ax', 'ledger', 'decisions.jsonl');
+            // @implements A-SPEC-191 §11 — an audit write must not swallow a verdict the caller already
+            // earned (the hook has said this since N3). The nonce is spent for an opening that DOES reach
+            // the caller; a disk failure here loses the record, not the decision.
+            try {
+                new decision_ledger_1.DecisionLedger(decisionsFile).record([evt]);
+            }
+            catch { /* 기록 실패가 이미 계산된 판정을 뒤집지 않는다 */ }
+            // @implements A-SPEC-133 — 'Every gate opening records a provenance approved-action entry.'
+            // r8: the promise was kept in the hook and broken here — a covering approval that unblocked a
+            // hard-hitl risk_check left only `nonce-consumed` (and nothing at all when it carried no
+            // nonce), so the master key's use was invisible in the chain the audit reads.
+            const wouldBlock = wouldBlockWithout;
+            const bnl = boundNonceLedger(store);
+            if (!gate.blocked && covers && wouldBlock && bnl !== null) {
+                try {
+                    new provenance_chain_1.ProvenanceChain(bnl).append({
+                        ts: a.ts, actor: a.approval?.actor ?? 'unknown', kind: 'approved-action',
+                        summary: `approved action: risk_check ${coverTarget.kind} ${(0, provenance_chain_1.redactTarget)('command', coverTarget.target)}`.slice(0, 300),
+                        inputs: ['risk_check', (0, provenance_chain_1.redactTarget)('command', coverTarget.target), (0, provenance_chain_1.approvalMarkers)(a.approval)],
+                        rationale: a.approval?.rationale ?? '',
+                        authorization: a.approval ? (0, provenance_chain_1.authorizationRef)(a.approval.actor, a.approval.token) : undefined,
+                    });
+                }
+                catch { /* 감사 기록 실패가 판정을 바꾸지 않는다 */ }
+            }
+            return { assessment, gate };
+        },
+        // @implements A-SPEC-126
+        // Brownfield reverse engineering. Three explicitly-invoked tools, nothing running as a side
+        // effect of an ordinary session, and every write path opt-in: scan writes nothing at all, draft
+        // and anchor are dry-run by DEFAULT.
+        /**
+         * Read-only inventory of a brownfield target: candidate clusters, coverage, and what the scan
+         * could not resolve. Deliberately does NOT call assertRepoTopLevel — a target that is not a git
+         * repository is a supported case here, reported as `isGit: false`.
+         */
+        async reverse_scan(a) {
+            // @implements A-SPEC-189 §10 (round 11) — `reverse_scan`/`reverse_draft` never call
+            // `projectRootOf`, so §7's refusal marker never reached them and their own POINTED sentence
+            // ("<root> is not a directory") arrived at the wire as a raw -32603 fault. A refusal about the
+            // caller's own argument is a refusal wherever it is authored.
+            assertReadableRoot('reverse_scan', a.root);
+            // `surfaceByCluster` is drafting evidence, not reading material. On the calibration target it
+            // is 11,460 characters across 15 clusters, and this response enters context on every scan —
+            // paying that to READ what only DRAFTING consumes. `reverse_draft` reads it in-process instead.
+            const { surfaceByCluster: _drafting, ...response } = (0, scan_1.reverseScan)(a.root, { maxFlagged: a.maxFlagged });
+            return response;
+        },
+        /**
+         * Draft H-SPEC/A-SPEC/T-SPEC documents for the recovered clusters under an EXISTING parent REQ.
+         *
+         * The REQ is the human's to write and this tool refuses without one — a requirement states
+         * business intent, which is not in the code. Everything emitted is `status: draft`, and writing
+         * requires an explicit `dryRun: false`.
+         *
+         * WHERE THE DOCUMENTS LAND: in the SERVER's configured spec store (`HOLMES_SPECS`, default
+         * `.ax/specs` relative to the server's working directory) — not inside `root`. In the intended
+         * adoption the two are the same directory, because the server runs inside the target it governs;
+         * pointing `root` at a different repository drafts that repository's slices into THIS store,
+         * which is a governance decision the caller has to make deliberately.
+         */
+        async reverse_draft(a) {
+            assertReadableRoot('reverse_draft', a.root);
+            if (typeof a.parentReqId !== 'string' || a.parentReqId.trim() === '') {
+                return {
+                    ok: false,
+                    reason: 'parentReqId is required. A REQ states business intent, which does not exist in the code ' +
+                        'and cannot be recovered from it — write the REQ first, then re-run with its id.',
+                };
+            }
+            const parentReqId = a.parentReqId.trim();
+            const specs = await store.list();
+            const req = specs.find((s) => s.id === parentReqId);
+            // An unresolvable parent would emit an orphan H-SPEC: a chain that only looks complete.
+            if (!req)
+                return { ok: false, reason: `parent REQ ${parentReqId} was not found in the spec store — create it first` };
+            // @implements A-SPEC-184
+            // A document with no `type:` is not a wrong-kind parent — it is an older-format one, and saying
+            // "is a undefined" left the adopter holding a visible document with nowhere to go. When the type
+            // IS declared, `legacyMessage` returns null and the original wording stands: that path was
+            // already accurate and REQ-184 does not touch it.
+            const formatWhy = (0, legacy_format_1.legacyMessage)(req);
+            if (formatWhy)
+                return { ok: false, reason: formatWhy };
+            if (req.type !== 'REQ')
+                return { ok: false, reason: `${parentReqId} is a ${req.type}; drafts must hang off a REQ` };
+            const report = (0, scan_1.reverseScan)(a.root);
+            // A cluster already drafted is recognised by the `reverse_cluster` key its documents carry, so
+            // re-running over the same tree never duplicates a slice.
+            const alreadyDrafted = new Set(specs.map((s) => s.frontmatter.reverse_cluster).filter((k) => typeof k === 'string'));
+            const selected = a.cluster ? report.clusters.filter((c) => (0, draft_1.clusterKeyOf)(c) === a.cluster) : report.clusters;
+            // A key that matches nothing must not read as success: "drafted 0" is indistinguishable from
+            // "everything was already drafted", so a mistyped key would silently skip the work.
+            if (a.cluster && selected.length === 0) {
+                const keys = report.clusters.map(draft_1.clusterKeyOf);
+                return {
+                    ok: false,
+                    reason: `no cluster matches key "${a.cluster}" — reverse_scan reports ${keys.length} cluster(s)`,
+                    availableClusters: keys.slice(0, 50),
+                };
+            }
+            let base = (0, draft_1.nextIdBase)(specs.map((s) => s.id));
+            const drafted = [];
+            const skipped = [];
+            const refused = [];
+            for (const cluster of selected) {
+                const key = (0, draft_1.clusterKeyOf)(cluster);
+                if (alreadyDrafted.has(key)) {
+                    skipped.push({ clusterKey: key, reason: 'already drafted' });
+                    continue;
+                }
+                const d = (0, draft_1.draftSpecs)(cluster, req.id, String(base), {
+                    surface: report.surfaceByCluster[key] ?? [],
+                    testFiles: cluster.testFiles ?? [],
+                    testsUnmatched: report.coverage.testsUnmatched,
+                });
+                if (!d.ok) {
+                    refused.push({ clusterKey: key, reason: d.reason });
+                    continue;
+                }
+                // Validate BEFORE writing: a draft that fails the project's own validator is not evidence of
+                // anything, and emitting one would put a broken document into the chain.
+                const known = [...specs, ...drafted.flatMap((x) => x.specs), ...d.specs];
+                const resolve = (id) => known.find((s) => s.id === id) ?? null;
+                const errors = d.specs.flatMap((s) => (0, validator_1.validateSpec)(s, resolve).findings.filter((f) => f.level === 'error').map((f) => ({ spec: s.id, ...f })));
+                if (errors.length) {
+                    refused.push({ clusterKey: key, reason: 'drafted documents failed validation', findings: errors });
+                    continue;
+                }
+                drafted.push(d);
+                base++;
+            }
+            const dryRun = a.dryRun !== false; // opt IN to writing
+            // @implements A-SPEC-188 — the minted id sits above every PARSEABLE id, but a file list()
+            // cannot read is invisible to nextIdBase, so its path can collide with a fresh draft. Same
+            // rule as spec_create: a path already occupied is a human's to look at, never overwritten.
+            // The whole cluster moves to `refused` — a partially-written chain only looks complete.
+            // Judged in the DRY RUN too (round-3): a preview that lists a cluster as drafted which the
+            // real run would refuse is a preview that lies.
+            const written = [];
+            for (const d of drafted) {
+                const clash = store instanceof spec_store_1.LocalMarkdownRepository
+                    ? d.specs.map((s) => store.targetPathFor(s)).find((p) => fs.existsSync(p))
+                    : undefined;
+                if (clash) {
+                    refused.push({ clusterKey: d.clusterKey, reason: `초안 목적지(${clash})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다. 사람이 확인해 옮기거나 고친 뒤 다시 실행하십시오.` });
+                    continue;
+                }
+                if (!dryRun) {
+                    try {
+                        for (const s of d.specs)
+                            await store.write(s);
+                    }
+                    catch (e) {
+                        if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                            refused.push({ clusterKey: d.clusterKey, reason: `초안 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다. 사람이 확인해 옮기거나 고친 뒤 다시 실행하십시오.` });
+                            continue;
+                        }
+                        throw e;
+                    }
+                }
+                written.push(d);
+            }
+            return { ok: true, dryRun, parentReqId: req.id, clusters: report.clusters.length, drafted: written, skipped, refused };
+        },
+        /**
+         * Insert `@implements` anchors into source files. Dry-run by DEFAULT, and anchoring to a
+         * non-approved A-SPEC is refused — a reverse-engineered draft describes code; description does
+         * not confer approval.
+         */
+        async reverse_anchor(a) {
+            const specs = await store.list();
+            const approved = specs.filter((s) => s.type === 'A-SPEC' && s.status === 'approved').map((s) => s.id);
+            const plan = (0, anchor_1.planAnchors)(a.root, a.mapping ?? [], approved);
+            // @implements A-SPEC-182
+            // The third place the harness refuses over an unapproved A-SPEC. Enriched HERE rather than
+            // inside planAnchors, which is a pure planner holding only the approved-id list — this is the
+            // boundary that has the spec objects, so the planner stays testable without them.
+            const byId = new Map(specs.map((s) => [s.id, s]));
+            // ONE payload per distinct A-SPEC, on a sibling field — not appended to every refused entry.
+            // Review measured the first attempt, which memoized only the COMPUTATION: 149 files mapped to
+            // one draft A-SPEC still concatenated the same 361-character sentence 149 times, 48 KB of pure
+            // duplication in a single tool result. The comment claimed a property the code did not have,
+            // which is how it survived a round of review — hence the size assertion in the test.
+            const blockers = {};
+            for (const r of plan.refused) {
+                if (!/is not approved$/.test(r.reason) || blockers[r.aspec] !== undefined)
+                    continue;
+                const why = (0, approval_blockers_1.blockerSummary)(byId.get(r.aspec), (id) => byId.get(id) ?? null, r.aspec);
+                if (why)
+                    blockers[r.aspec] = why.trim();
+            }
+            const applied = (0, anchor_1.applyAnchors)(a.root, plan.edits, { dryRun: a.dryRun !== false });
+            return { ...plan, ...applied, blockers };
+        },
+    };
+}