@holmes-lab/holmes-kit 0.2.0 → 0.3.0

package/dist/holmes/mcp/handlers.js

@@ -35,11 +35,32 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HandlerRefusal = void 0;
 exports.isHandlerRefusal = isHandlerRefusal;
+exports.unreadableAmong = unreadableAmong;
 exports.makeHandlers = makeHandlers;
+// @implements A-SPEC-293
+// @implements A-SPEC-292
+// @implements A-SPEC-290
+// @implements A-SPEC-283
+// @implements A-SPEC-277
+// @implements A-SPEC-269
+// @implements A-SPEC-267
 const fs = __importStar(require("node:fs"));
+const assoc_arm_1 = require("../assoc/assoc-arm");
+// @implements A-SPEC-478 — the semantic tier runtime, resolved HERE (the async edge) and injected
+// into the sync analysis; the replay harness injects nothing, keeping every pin untouched.
+const tier_1 = require("../semantic/tier");
+const vector_cache_1 = require("../semantic/vector-cache");
+const embedder_1 = require("../semantic/embedder");
+// @implements A-SPEC-496 — policy parity: the direct localization path reranks with the exact
+// A-SPEC-478 math, extracted pure.
+const hit_rerank_1 = require("../semantic/hit-rerank");
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const crypto = __importStar(require("node:crypto"));
+// @implements A-SPEC-378
+const temporal_prior_1 = require("../review/temporal-prior");
+// @implements A-SPEC-388
+const commit_text_1 = require("../review/commit-text");
 const node_child_process_1 = require("node:child_process");
 const spec_parser_1 = require("../spec/spec-parser");
 const validator_1 = require("../spec/validator");
@@ -49,6 +70,9 @@ 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 maintenance_analyze_1 = require("./maintenance-analyze");
+const maintenance_evidence_1 = require("./maintenance-evidence");
+const impact_gate_1 = require("../guardrail/impact-gate");
 const phase_1 = require("../guardrail/phase");
 const spec_types_1 = require("../spec/spec-types");
 const legacy_format_1 = require("../spec/legacy-format");
@@ -74,6 +98,10 @@ const cacheDirFor = (root) => {
         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)}`);
 };
+// @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
+// by an older build is rebuilt rather than read with new assumptions.
+const RTM_GRAPH_SCHEMA = 'rtm-graph/2';
+const RTM_EXTRACTOR_VERSION = 'holmes-rtm/1';
 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,
@@ -87,6 +115,7 @@ 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 graph_store_1 = require("../rtm/graph-store");
 const hash_cache_1 = require("../cpg/hash-cache");
 const bundler_1 = require("../context/bundler");
 const scope_1 = require("../review/scope");
@@ -95,6 +124,7 @@ 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 yaml_scalar_1 = require("../spec/yaml-scalar");
 const findings_1 = require("../review/findings");
 const package_1 = require("../review/package");
 const risk_classifier_1 = require("../guardrail/risk-classifier");
@@ -235,6 +265,72 @@ function foreignRootReason(store, root) {
         return `root를 해석할 수 없습니다: ${String(e.message)}`;
     }
 }
+/**
+ * @implements A-SPEC-418
+ * The server binds its spec store to a RELATIVE path, so the store follows the process's cwd. Start
+ * it inside the project and `maintenance_analyze` reads 1199 specs; start it anywhere else and it
+ * reads NONE — and then answers the same request with zero candidates, no warning, a normal success
+ * shape, and the root's 378 files still scanned, so it reads as working. Found by installing the
+ * tarball and speaking JSON-RPC to the packaged server; no test in this repository saw it.
+ *
+ * `foreignRootReason` deliberately stays quiet here: it compares two projects, and when the store's
+ * own directory has no `.ax` marker there is nothing to compare. That judgement is right, and the
+ * silence it leaves is what this fills.
+ *
+ * Keyed on the BINDING, not on the count. Zero specs because a project's specs are all drafts is a
+ * different fact from zero because none were read, and warning on the first would fire on every
+ * young project.
+ */
+function specStoreBlindReason(store, root, loaded) {
+    if (loaded > 0 || !(store instanceof spec_store_1.LocalMarkdownRepository))
+        return null;
+    if (!fs.existsSync(path.join(root, '.ax', 'specs')))
+        return null; // 스펙이 없는 프로젝트는 무고하다
+    // Compared through realpath: on macOS a temp root is `/var/...` while the same directory resolves
+    // to `/private/var/...`, and a plain string compare calls the correctly-bound store foreign.
+    const real = (p) => { try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    } };
+    const bound = real(store.specsRoot);
+    if (bound === real(path.join(root, '.ax', 'specs')))
+        return null;
+    return `이 서버는 ${bound} 에 바인딩되어 스펙을 하나도 읽지 못했습니다 — 분석 대상 ${root} 에는`
+        + ' 스펙 저장소가 있습니다. 아래 결과는 스펙 층 없이 어휘와 그래프만으로 계산된 것이며,'
+        + ' 스펙 매칭에 의존하는 요청은 조용히 0개를 받습니다. 서버를 프로젝트 루트에서 시작하거나'
+        + ' HOLMES_SPECS 로 스펙 경로를 지정하십시오.';
+}
+/**
+ * @implements A-SPEC-419
+ * `phase_status` refuses when this server's spec directory cannot be resolved; the tools whose whole
+ * answer is about specs did not, and answered EMPTY instead. From a cwd outside the project the
+ * installed server returned `{"specs":[]}` for a repository holding 1199 of them, empty impacted
+ * specs for review, no hits for localization, and rewrote the RTM index with no spec nodes at all —
+ * every one a success shape. The cause is one line in `LocalMarkdownRepository.list`: its walk
+ * returns quietly when the directory is missing, so an ABSENT store is indistinguishable from an
+ * empty one.
+ *
+ * Keyed on a MISMATCH, never on a count: a project that has not run `init` yet has no specs anywhere
+ * and must keep getting its empty answer, or this guard becomes the next defect.
+ */
+function assertSpecStoreReachable(tool, store, root) {
+    if (typeof root !== 'string' || root === '')
+        return;
+    if (!(store instanceof spec_store_1.LocalMarkdownRepository))
+        return;
+    if (fs.existsSync(store.specsRoot))
+        return;
+    if (!fs.existsSync(path.join(root, '.ax', 'specs')))
+        return; // 어디에도 스펙이 없으면 무고하다
+    // The tool name is NOT prefixed here: the raw-handler wrapper already prefixes it, and doing it
+    // twice produced `spec_list: spec_list: ...` in the installed server (seen in the probe).
+    void tool;
+    throw new HandlerRefusal(`이 서버가 바인딩된 스펙 디렉터리 ${store.specsRoot} 가 존재하지 않습니다 —`
+        + ` 요청한 root ${root} 에는 스펙 저장소가 있습니다. 빈 답을 돌려주면 '스펙이 없다'로 읽히므로`
+        + ' 거부합니다. 서버를 프로젝트 루트에서 시작하거나 HOLMES_SPECS 로 스펙 경로를 지정하십시오.');
+}
 /**
  * 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)
@@ -416,6 +512,15 @@ async function deriveChangedContext(store, rootArg, a, toolName) {
  * 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-299
+ * Ids that were written but cannot be read back. The store drops documents it cannot parse, so
+ * absence from `list()` — not an exception — is the signal.
+ */
+function unreadableAmong(listed, created) {
+    const present = new Set(listed.map((s) => s.id));
+    return created.filter((id) => !present.has(id));
+}
 function makeHandlers(store, opts) {
     const raw = makeRawHandlers(store, opts);
     const wrapped = {};
@@ -465,6 +570,74 @@ function basisFor(root, withDisk = false) {
     }
     return (0, basis_1.collectBasis)(ctx);
 }
+/**
+ * @implements A-SPEC-277
+ * sha256 of a repo-relative file as it is on disk right now, or null when it cannot be read. Null is
+ * a real answer — a deleted or not-yet-created target genuinely cannot be compared against what an
+ * analysis recorded, and the gate treats that as unverifiable rather than as unchanged.
+ */
+function fileDigestOf(root, rel) {
+    try {
+        const resolved = path.resolve(root, rel);
+        // Never digest something outside the project: the path arrives from a tool caller.
+        if (resolved !== root && !resolved.startsWith(root + path.sep))
+            return null;
+        if (!fs.statSync(resolved).isFile())
+            return null;
+        return `sha256:${crypto.createHash('sha256').update(fs.readFileSync(resolved)).digest('hex')}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @implements A-SPEC-293
+ * Read `.ax/decisions/*.md` and find who cites them. Citation is the link, chosen by measurement:
+ * `governs` resolves 9 of 65 names to symbols while 37 source files and 71 spec files cite an ADR.
+ * Failure here is never fatal — a project with no decisions directory simply has no decisions.
+ */
+function collectDecisions(root, scanned, specs) {
+    const dir = path.join(root, '.ax', 'decisions');
+    const decisions = [];
+    try {
+        for (const name of fs.readdirSync(dir).sort()) {
+            if (!name.endsWith('.md'))
+                continue;
+            const text = fs.readFileSync(path.join(dir, name), 'utf8');
+            const front = text.split('---')[1] ?? '';
+            const id = (front.match(/^id:\s*(\S+)/m) ?? [])[1];
+            if (!id)
+                continue;
+            const supersedes = (front.match(/^supersedes:\s*(.+)$/m) ?? [])[1]?.trim() ?? '';
+            decisions.push({
+                id,
+                title: ((front.match(/^title:\s*(.+)$/m) ?? [])[1] ?? '').trim(),
+                status: ((front.match(/^status:\s*(\S+)/m) ?? [])[1] ?? '').trim(),
+                supersedes: supersedes && supersedes !== 'null' ? supersedes : null,
+            });
+        }
+    }
+    catch {
+        return { decisions: [], citations: [] };
+    }
+    const ids = new Set(decisions.map((d) => d.id));
+    const cite = (text, from, out) => {
+        for (const m of text.matchAll(/\bADR-\d{3}\b/g))
+            if (ids.has(m[0]))
+                out.push({ from, adr: m[0] });
+    };
+    const citations = [];
+    for (const f of scanned) {
+        try {
+            cite(fs.readFileSync(path.join(root, f.sourcePath), 'utf8'), `FILE:${f.sourcePath}`, citations);
+        }
+        catch { /* unreadable now — the scan is a snapshot, the tree can move */ }
+    }
+    for (const spec of specs) {
+        cite(`${spec.title} ${Object.values(spec.sections ?? {}).join(' ')}`, `SPEC:${spec.id}`, citations);
+    }
+    return { decisions, citations };
+}
 function makeRawHandlers(store, opts) {
     const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
     // @implements A-SPEC-263.1
@@ -579,6 +752,42 @@ function makeRawHandlers(store, opts) {
                     };
                 }
             }
+            // @implements A-SPEC-420
+            // The branch above steps aside when the server's spec directory does not exist yet, so that a
+            // project can create its first spec. Right intent, but the gap let something else through:
+            // measured against the INSTALLED server from a cwd outside any project, `spec_create` with
+            // `root` naming an established other project wrote REQ-990 into the SERVER's directory and
+            // answered `{"created":"REQ-990"}`. The caller's project gained nothing and was told it had.
+            //
+            // Layout-independent on purpose: the test is not "<root>/.ax/specs equals my store" — that
+            // hardcodes the default layout and, as the note above records, made `--specs-dir docs/specs`
+            // deployments refuse their own root. It is "you named a project that already exists, and my
+            // store is not inside it", which is true whatever the specs directory is called.
+            if (typeof reqRoot === 'string' && reqRoot !== '' && derivedForCreate === null && boundSpecsRoot !== null) {
+                const real = (p2) => { try {
+                    return fs.realpathSync(p2);
+                }
+                catch {
+                    return path.resolve(p2);
+                } };
+                let askedRoot = null;
+                try {
+                    askedRoot = real(projectRootOf(reqRoot));
+                }
+                catch {
+                    askedRoot = null;
+                }
+                if (askedRoot !== null && fs.existsSync(path.join(askedRoot, '.ax'))
+                    && !real(boundSpecsRoot).startsWith(askedRoot + path.sep)) {
+                    return {
+                        ok: false,
+                        reason: `이 서버의 스펙 저장소 ${boundSpecsRoot} 는 아직 만들어지지 않았고 ${askedRoot} 안에도`
+                            + ' 있지 않습니다 — 요청한 root 는 이미 스펙 저장소를 가진 다른 프로젝트입니다.'
+                            + ' 여기서 만들면 파일은 호출자가 지정한 곳이 아니라 이 서버 쪽에 생깁니다.'
+                            + ' 서버를 그 프로젝트에서 시작하거나 HOLMES_SPECS 로 그 프로젝트의 스펙 경로를 지정하십시오.',
+                    };
+                }
+            }
             // @implements A-SPEC-174
             // Refuse what can never become valid; accept what is merely not filled in yet.
             //
@@ -1159,6 +1368,7 @@ function makeRawHandlers(store, opts) {
             return { approved: a.id, digest };
         },
         async spec_list(a) {
+            assertSpecStoreReachable('spec_list', store, a.root); // @implements A-SPEC-419
             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
@@ -1215,6 +1425,15 @@ function makeRawHandlers(store, opts) {
             return { next: null };
         },
         async rtm_check(a) {
+            // @implements A-SPEC-461 — a root that names a different project would check THIS project's
+            // specs against THAT project's files and report clean — A-SPEC-191 §15. foreignRootReason
+            // returns null for an absent or matching root, so the spec-only and correct-root paths are
+            // unaffected. Shared guard (citation_pin/maintenance_analyze use it), not a copy (A-SPEC-449).
+            {
+                const foreign = foreignRootReason(store, a?.root);
+                if (foreign)
+                    return { ok: false, reason: foreign };
+            }
             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
@@ -1403,6 +1622,13 @@ function makeRawHandlers(store, opts) {
          * never "vulnerable".
          */
         async taint_scan(a) {
+            // @implements A-SPEC-461 — same §15 defence as rtm_check: refuse a root that is not this
+            // server's project rather than scanning it against the bound store's specs.
+            {
+                const foreign = foreignRootReason(store, a.root);
+                if (foreign)
+                    return { ok: false, reason: foreign };
+            }
             const root = projectRootOf(a.root);
             const scanned = cachedScan(root, root);
             const g = new rtm_graph_1.RtmGraph();
@@ -1450,7 +1676,7 @@ function makeRawHandlers(store, opts) {
             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', env: (0, root_1.cleanSubprocessEnv)() }).trim();
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
             }
             catch { /* non-git */ }
             // Record ONLY an actually-executed, GREEN run (review C4/C7): a red suite must not stand as
@@ -1479,6 +1705,7 @@ function makeRawHandlers(store, opts) {
                 changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}) };
         },
         async issue_localize(a) {
+            assertSpecStoreReachable('issue_localize', store, a.root); // @implements A-SPEC-419
             // 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
@@ -1488,9 +1715,270 @@ function makeRawHandlers(store, opts) {
             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);
+            const governed = (0, spec_types_1.filterGoverned)(specs);
+            const report = (0, localize_1.localizeIssue)(a.issue, scanned, governed, a.topN ?? 10);
+            // @implements A-SPEC-496 — parity with A-SPEC-478: the SAME uncited gate, the SAME math
+            // (cached vectors only, set fixed, covered hits move, why-line attached). Any missing
+            // signal — no tier, no key, cold cache, embed failure — leaves the report untouched;
+            // localization itself never fails because of the semantic layer.
+            try {
+                if (report.hits.length > 1
+                    && (0, localize_1.citationsIn)(a.issue, new Set(governed.map((s) => s.id))).cited.length === 0) {
+                    const rt = (0, embedder_1.makeTierEmbedder)((0, tier_1.resolveSemanticTier)(), new vector_cache_1.VectorCache(root));
+                    if (rt !== null) {
+                        const qv = await rt.embedQuery(a.issue);
+                        const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
+                            (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+                        (0, hit_rerank_1.rerankHitsBySemantic)(report.hits, qv, (file) => {
+                            const dt = docTextOf.get(file);
+                            return dt !== undefined ? rt.cachedDocVector(dt) : null;
+                        }, rt.label);
+                    }
+                }
+            }
+            catch { /* semantic layer is additive — never block the report */ }
+            return report;
+        },
+        async maintenance_analyze(a) {
+            const foreign = foreignRootReason(store, a.root);
+            if (foreign)
+                throw new HandlerRefusal(foreign);
+            const root = projectRootOf(a.root);
+            // This tool is advertised as read-only. Do not attach ScanFileCache: its normal save/prune
+            // behavior mutates `.ax/cpg_cache` even though the analysis itself is observational.
+            const scanner = new cpg_scanner_1.CpgScanner();
+            const scanned = scanner.scan(root, root);
+            const skipped = scanner.scanSkipped();
+            const specs = (0, spec_types_1.filterGoverned)(await store.list());
+            const anchors = (0, test_scope_1.scanTestAnchors)(root);
+            const detail = basisFor(root, true);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            const supportedExtensions = new Set(cpg_scanner_1.SCANNABLE_EXTENSIONS);
+            const knownCodeExtensions = new Set(['.rb', '.php', '.kt', '.kts', '.swift', '.scala', '.sh', '.ex', '.exs', '.lua', '.r']);
+            const unsupportedLanguages = new Set();
+            try {
+                const files = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: 8 * 1024 * 1024 }).split('\0');
+                for (const file of files) {
+                    const ext = path.extname(file).toLowerCase();
+                    if (knownCodeExtensions.has(ext) && !supportedExtensions.has(ext))
+                        unsupportedLanguages.add(ext);
+                }
+            }
+            catch {
+                // A non-git tree cannot be enumerated cheaply without reimplementing the scanner's ignore
+                // rules. Surface the missing axis rather than claiming every language was covered.
+                unsupportedLanguages.add('not-enumerated(non-git)');
+            }
+            const graph = new rtm_graph_1.RtmGraph();
+            try {
+                // @implements A-SPEC-292 — the resolution loop's own tally of what it declined to link.
+                const { resolution } = (0, rtm_builder_1.buildRtm)(specs, scanned, graph);
+                // @implements A-SPEC-293 — what constrains this change, not just what it touches.
+                const { decisions, citations } = collectDecisions(root, scanned, specs);
+                (0, rtm_builder_1.addDecisionEdges)(decisions, citations, graph);
+                const common = {
+                    request: a.request,
+                    scanned,
+                    specs,
+                    graph,
+                    testAnchors: anchors,
+                    basis: {
+                        head,
+                        loadedBuild: detail.loadedBuild,
+                        diskBuild: detail.diskBuild ?? 'unknown',
+                        specFingerprint: `count:${specs.length}/fp:${detail.specs ?? 'unknown'}`,
+                    },
+                    changedFiles: a.changedFiles,
+                    // @implements A-SPEC-290 — the stored run record. Freshness is judged inside the analysis
+                    // against its own basis, so a record from another commit is reported as stale rather than
+                    // quietly used.
+                    runtimeEvidence: (0, test_evidence_1.readTestEvidence)(root),
+                    resolution,
+                    coverage: {
+                        scannedFiles: scanned.length,
+                        skippedFiles: skipped.map((entry) => entry.file),
+                        unsupportedLanguages: [...unsupportedLanguages],
+                        historyStatus: 'not-requested',
+                    },
+                };
+                // @implements A-SPEC-478 — resolve the tier and precompute the query vector at the
+                // async edge; the sync analysis receives only a closure over cached vectors. Any failure
+                // (no tier, no module, no key, embed error) leaves `semantic` undefined = today's behavior.
+                let semantic;
+                try {
+                    const rt = (0, embedder_1.makeTierEmbedder)((0, tier_1.resolveSemanticTier)(), new vector_cache_1.VectorCache(root));
+                    if (rt !== null) {
+                        const qv = await rt.embedQuery(a.request);
+                        semantic = { label: rt.label, queryVector: qv, cachedDocVector: rt.cachedDocVector };
+                    }
+                }
+                catch { /* the hot path never breaks on the semantic layer */ }
+                const preliminary = (0, maintenance_analyze_1.analyzeMaintenance)({ ...common, history: [], semantic });
+                const candidateFiles = preliminary.candidates.map((candidate) => candidate.file);
+                const limit = Math.max(0, Math.min(100, Math.floor(a.historyLimit ?? 20)));
+                const history = [];
+                let historyStatus = limit === 0 || candidateFiles.length === 0 ? 'not-requested' : 'unavailable';
+                if (limit > 0 && candidateFiles.length > 0) {
+                    try {
+                        const raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'log', `-${limit}`, '--date=short', '--format=%H%x00%ad%x00%s', '--name-only', '--', ...candidateFiles], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: 2 * 1024 * 1024 });
+                        let current = null;
+                        for (const line of raw.split('\n')) {
+                            if (line.includes('\0')) {
+                                const [commit, date, subject] = line.split('\0');
+                                current = { commit, date, subject, files: [] };
+                                history.push(current);
+                            }
+                            else if (current && line.trim() !== '') {
+                                // git C-quotes any non-ASCII pathname here (core.quotepath). Left raw, it never
+                                // matched a candidate file, so the rationale came back empty while historyStatus
+                                // still reported `available` — a silent false negative with confident provenance.
+                                current.files.push((0, maintenance_analyze_1.unquoteGitPath)(line.trim()));
+                            }
+                        }
+                        historyStatus = 'available';
+                    }
+                    catch { /* history is evidence enrichment, not a prerequisite */ }
+                }
+                // Preserve localization rank for context: `impacts.direct` is deliberately sorted for a
+                // stable evidence contract, but sorting is not relevance. Seeding from it once selected a
+                // lexically earlier vendored symbol while the first ranked hit correctly named live code.
+                const directSeed = preliminary.candidates
+                    .flatMap((candidate) => candidate.symbols)
+                    .flatMap((qualifiedName) => graph.codeNodeIds(qualifiedName))[0];
+                const specSeed = preliminary.candidateSpecs.find((id) => id.startsWith('A-SPEC-'));
+                const seedId = directSeed ?? (specSeed ? `SPEC:${specSeed}` : undefined);
+                const budget = Math.max(100, Math.min(10_000, Math.floor(a.contextBudget ?? 2_000)));
+                const contextBundle = seedId
+                    ? new bundler_1.ContextBundler(graph, buildContentSource(specs, scanned)).getContextBundle(seedId, budget)
+                    : null;
+                // @implements A-SPEC-378
+                // Change recency over a WIDE window and ALL files — the enrichment history above is
+                // deliberately narrow (candidate files, 20 commits) and cannot serve as a prior: a file the
+                // lexical layer never ranked has no history there, which is precisely the file recency is
+                // supposed to promote. Failure is silent and total: no prior means the previous ranking,
+                // never a partial one, because a prior built from half the history would reorder on evidence
+                // nobody could audit.
+                const changePrior = {};
+                try {
+                    const prior = (0, temporal_prior_1.temporalPrior)(root, 'HEAD', 300);
+                    for (const [file, age] of prior.recency)
+                        changePrior[file] = 1 + Math.pow(0.5, age / 10);
+                }
+                catch { /* no history, no prior — the ranking falls back to lexical evidence alone */ }
+                // @implements A-SPEC-388
+                // What each file's commits have SAID, normalised to 0..1. Measured on history sampled away
+                // from the benchmarker's own recent work (A-SPEC-387): Top-1 0.244 -> 0.333 here and 0.400 ->
+                // 0.500 on a second repository, Top-10 recall 0.393 -> 0.601 there. Precision falls on both,
+                // and that is the trade, not a footnote to it.
+                const commitTextBoost = {};
+                try {
+                    const profile = (0, commit_text_1.commitTextProfile)(root, 'HEAD', 400);
+                    const ranked = (0, commit_text_1.rankByCommitText)(a.request, profile, 300);
+                    const top = ranked[0]?.score ?? 0;
+                    if (top > 0)
+                        for (const hit of ranked)
+                            commitTextBoost[hit.file] = hit.score / top;
+                }
+                catch { /* no history, no boost — the ranking falls back to lexical evidence alone */ }
+                const analysis = (0, maintenance_analyze_1.analyzeMaintenance)({
+                    semantic,
+                    ...common,
+                    coverage: { ...common.coverage, historyStatus },
+                    history,
+                    changePrior,
+                    commitTextBoost,
+                    contextBundle,
+                    groundTruth: a.groundTruth,
+                });
+                // @implements A-SPEC-268 — persistence is OPT-IN. The tool is advertised read-only, and a
+                // regression pins that a cold project gains no `.ax/cpg_cache`; writing evidence by default
+                // would break that contract for every caller who only wanted to look.
+                // One shape either way: `persistedTo` is present-or-undefined rather than a union, so a
+                // caller never has to narrow the result to ask whether anything was written.
+                const result = { ...analysis };
+                // @implements A-SPEC-418 — first line, because everything below it was computed without specs.
+                const blind = specStoreBlindReason(store, root, specs.length);
+                if (blind !== null)
+                    result.unknowns = [blind, ...result.unknowns];
+                if (a.persist) {
+                    // @implements A-SPEC-277 — record WHAT WAS ANALYSED, not just which paths. HEAD cannot see
+                    // an uncommitted edit to the analysed file; a content digest can.
+                    const fileDigests = {};
+                    for (const file of analysis.impacts.files) {
+                        const digest = fileDigestOf(root, file);
+                        if (digest)
+                            fileDigests[file] = digest;
+                    }
+                    result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests));
+                }
+                return result;
+            }
+            finally {
+                graph.close();
+            }
+        },
+        // @implements A-SPEC-268
+        async maintenance_outcome(a) {
+            const foreign = foreignRootReason(store, a.root);
+            if (foreign)
+                throw new HandlerRefusal(foreign);
+            const root = projectRootOf(a.root);
+            return (0, maintenance_evidence_1.recordOutcome)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), a.digest, {
+                actualFiles: a.actualFiles,
+                actualSymbols: a.actualSymbols,
+                actualTests: a.actualTests,
+                actualClassification: a.actualClassification,
+            }, new Date().toISOString());
+        },
+        // @implements A-SPEC-277
+        async impact_gate_check(a) {
+            const foreign = foreignRootReason(store, a.root);
+            if (foreign)
+                throw new HandlerRefusal(foreign);
+            const root = projectRootOf(a.root);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            let artifact = null;
+            if (a.digest) {
+                const file = path.join(root, maintenance_evidence_1.EVIDENCE_DIR, (0, maintenance_evidence_1.digestFilename)(a.digest));
+                // A digest naming an artifact this project never stored is NOT the same as no evidence at
+                // all — say which one happened rather than collapsing both into "refused".
+                if (!fs.existsSync(file))
+                    throw new HandlerRefusal(`이 프로젝트에 저장된 분석이 아닙니다: ${a.digest}`);
+                artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
+            }
+            return (0, impact_gate_1.evaluateEditEvidence)({
+                target: a.target.replace(/\\/g, '/'),
+                artifact,
+                currentHead: head,
+                currentTargetDigest: fileDigestOf(root, a.target),
+            });
+        },
+        // @implements A-SPEC-268
+        async maintenance_calibration(a) {
+            const foreign = foreignRootReason(store, a.root);
+            if (foreign)
+                throw new HandlerRefusal(foreign);
+            const root = projectRootOf(a.root);
+            const read = (0, maintenance_evidence_1.readArtifacts)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR));
+            // Corrupt and off-schema records travel WITH the score. A calibration that quietly dropped
+            // them would report a clean number over an unstated subset of the evidence.
+            return {
+                ...(0, maintenance_evidence_1.computeCalibration)(read.artifacts, { minSamples: a.minSamples }),
+                artifacts: read.artifacts.length,
+                unreadable: read.unreadable,
+                skippedSchema: read.skippedSchema,
+            };
         },
         async rtm_impact(a) {
+            assertSpecStoreReachable('rtm_impact', store, a.root); // @implements A-SPEC-433
             // @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
@@ -1499,15 +1987,46 @@ function makeRawHandlers(store, opts) {
             const root = projectRootOf(a.root);
             const scanned = cachedScan(root);
             const specs = await store.list();
-            const g = new rtm_graph_1.RtmGraph();
+            // @implements A-SPEC-283
+            // Reuse the persisted graph when its basis still holds. Measured: on the warm path the graph
+            // build is ~81% of the cost and reopening is ~0ms. `scanDigest` is the field that makes this
+            // safe — an uncommitted edit never moves HEAD, so a commit-only basis would happily serve a
+            // graph describing content the working tree no longer has.
+            let head = '';
             try {
-                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            const opened = (0, graph_store_1.openReusableGraph)(path.join(root, '.ax', 'rtm.sqlite'), {
+                graphSchema: RTM_GRAPH_SCHEMA,
+                extractorVersion: RTM_EXTRACTOR_VERSION,
+                sourceCommit: head,
+                specFingerprint: `n:${specs.length}/${specs.map((s) => `${s.id}:${s.status}`).sort().join(',')}`,
+                scanDigest: (0, graph_store_1.scanDigest)(scanned),
+            });
+            const g = opened.graph;
+            try {
+                if (!opened.reusable) {
+                    (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                    opened.commitBasis();
+                }
                 // 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);
+                // @implements A-SPEC-469 — the graded FILE surface beside the spec closure, same code path
+                // as the S-484 measurement (identity, not reimplementation). Seeds are the changed symbols'
+                // nodes; the files that own them are excluded — a prediction naming the change itself is
+                // vacuously true. The closure fields above stay exactly as they were: mass never enters a
+                // gate decision.
+                const riSeeds = new Map(a.changed.flatMap((qn) => g.codeNodeIds(qn)).map((id) => [id, 1]));
+                const riExclude = new Set([...riSeeds.keys()]
+                    .map((id) => (id.includes('@') ? id.slice(id.lastIndexOf('@') + 1) : ''))
+                    .filter((f) => f !== ''));
+                const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(g.dumpCanonical()), riSeeds, riExclude, assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
                 return {
                     impacted,
+                    rankedImpact,
                     reachedByDepth,
                     bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,
                     ...(seedIsHub ? {
@@ -1520,6 +2039,7 @@ function makeRawHandlers(store, opts) {
             }
         },
         async rtm_reindex(a) {
+            assertSpecStoreReachable('rtm_reindex', store, a.root); // @implements A-SPEC-419
             // 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
@@ -1566,14 +2086,33 @@ function makeRawHandlers(store, opts) {
                 // 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 };
+                // @implements A-SPEC-280 — the whole scan, so call edges are re-resolved and the reindexed
+                // graph equals what a full rebuild would have produced. Measured: without this, rtm_reindex
+                // returned a graph with no call edges at all.
+                (0, incremental_1.applyIncremental)(g, changesToApply, { repoRoot: root, specs, scanOne, allScanned: () => scanned });
+                // @implements A-SPEC-478 — the semantic cache WARMING lives here, in the explicit heavy
+                // operation, so the ranking hot path only ever LOOKS UP vectors. Idempotent through the
+                // cache; a tier of none (the shipped default) computes nothing.
+                let semanticWarm;
+                try {
+                    const tier = (0, tier_1.resolveSemanticTier)();
+                    const rt = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
+                    if (rt !== null) {
+                        const docTexts = scanned.map((f) => (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000));
+                        const w = await rt.warm(docTexts);
+                        semanticWarm = { tier: rt.label, ...w };
+                    }
+                }
+                catch { /* warming is best-effort; reindex's own result is unaffected */ }
+                return { changed, nodes: g.nodeCount(), edges: g.edgeCount(), changeSource,
+                    ...(semanticWarm !== undefined ? { semanticWarm } : {}) };
             }
             finally {
                 g.close(); // release native SQLite handle even if build/apply throws
             }
         },
         async context_bundle(a) {
+            assertSpecStoreReachable('context_bundle', store, a.root); // @implements A-SPEC-433
             const foreign = foreignRootReason(store, a.root);
             if (foreign)
                 throw new HandlerRefusal(foreign);
@@ -1591,6 +2130,7 @@ function makeRawHandlers(store, opts) {
             }
         },
         async review_scope(a) {
+            assertSpecStoreReachable('review_scope', store, a.root); // @implements A-SPEC-419
             // 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');
@@ -1616,6 +2156,7 @@ function makeRawHandlers(store, opts) {
             }
         },
         async review_prepare(a) {
+            assertSpecStoreReachable('review_prepare', store, a.root); // @implements A-SPEC-419
             // 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');
@@ -2202,6 +2743,12 @@ function makeRawHandlers(store, opts) {
                 }
                 written.push(d);
             }
+            // @implements A-SPEC-299
+            // Deliberately NOT changed. This looked like the same false pass as spec_slice_approve, but an
+            // approved store-integrity test pins `ok: true` for a run that refused every cluster because a
+            // destination held an unreadable file: nothing was written, nothing was damaged, and `ok` here
+            // means the call completed without harm. That is a defensible contract, and the case against
+            // it was analogy rather than an observed failure. Evidence beats symmetry.
             return { ok: true, dryRun, parentReqId: req.id, clusters: report.clusters.length, drafted: written, skipped, refused };
         },
         /**
@@ -2252,13 +2799,13 @@ function makeRawHandlers(store, opts) {
             const reqContent = `---
 source:
   - kind: user-request
-    ref: ${a.title}
+    ref: ${(0, yaml_scalar_1.yamlScalar)(a.title, 4)}
     retrieved: ${new Date().toISOString().split('T')[0]}
-    note: ${a.objective}
+    note: ${(0, yaml_scalar_1.yamlScalar)(a.objective, 4)}
 created: ${new Date().toISOString()}
 id: ${reqId}
 type: REQ
-title: ${a.title}
+title: ${(0, yaml_scalar_1.yamlScalar)(a.title)}
 status: draft
 depends_on: []
 ---
@@ -2282,7 +2829,7 @@ ${a.objective}
 created: ${new Date().toISOString()}
 id: ${hspecId}
 type: H-SPEC
-title: Functional Specification for ${a.title}
+title: ${(0, yaml_scalar_1.yamlScalar)(`Functional Specification for ${a.title}`)}
 status: draft
 req_type: functional
 owner: me
@@ -2319,7 +2866,7 @@ High level design for ${a.title}.
 created: ${new Date().toISOString()}
 id: ${aspecId}
 type: A-SPEC
-title: Architecture Specification for ${a.title}
+title: ${(0, yaml_scalar_1.yamlScalar)(`Architecture Specification for ${a.title}`)}
 status: draft
 slice: ${a.sliceName}
 priority: P1
@@ -2360,7 +2907,7 @@ coverage:
   boundary: true
 id: ${tspecId}
 type: T-SPEC
-title: Test Specification for ${a.title}
+title: ${(0, yaml_scalar_1.yamlScalar)(`Test Specification for ${a.title}`)}
 status: draft
 depends_on:
   - ${aspecId}
@@ -2394,7 +2941,16 @@ depends_on:
             fs.writeFileSync(path.join(specsDir, '02_h-spec', 'functional', `${hspecId}.md`), hspecContent);
             fs.writeFileSync(path.join(specsDir, '03_a-spec', `${aspecId}.md`), aspecContent);
             fs.writeFileSync(path.join(specsDir, '05_t-spec', `${tspecId}.md`), tspecContent);
-            return { ok: true, specsCreated: [reqId, hspecId, aspecId, tspecId] };
+            // @implements A-SPEC-299
+            // Read back what was just written. S-298 fixed one cause of unparseable frontmatter; this
+            // closes the class. `list()` silently skips documents it cannot parse, so "created" and
+            // "present in the store" can diverge without anything throwing — which is exactly how a
+            // requirement went missing on 2026-08-28 while the tool reported four specs created.
+            const specsCreated = [reqId, hspecId, aspecId, tspecId];
+            const unreadable = unreadableAmong(await new spec_store_1.LocalMarkdownRepository(specsDir).list(), specsCreated);
+            // The files stay on disk on purpose: deleting the evidence turns a diagnosable bug into a
+            // mystery, and a half-written slice is something a person should see.
+            return { ok: unreadable.length === 0, specsCreated, unreadable };
         },
         async spec_slice_approve(a) {
             const root = a.root ? (0, root_2.resolveProjectRoot)(a.root).root : process.cwd();
@@ -2428,13 +2984,32 @@ depends_on:
             }
             const rawHandlers = makeRawHandlers(rawStore);
             const approvedSpecs = [];
+            const refused = [];
+            if (idsToApprove.length === 0) {
+                // Reporting this as a success is how a caller ends up believing an unapproved slice was
+                // approved. Measured 2026-08-28: a broken-frontmatter REQ made the whole slice invisible
+                // here, and the tool answered `ok: true, approvedSpecs: []`.
+                return { ok: false, approvedSpecs, refused: [{ id: a.sliceName, reason: 'no specs matched this slice name' }] };
+            }
             for (const id of idsToApprove) {
                 const res = (await rawHandlers.spec_approve({ root, id }));
                 if (res.approved || res.ok) {
                     approvedSpecs.push(id);
+                    continue;
                 }
-            }
-            return { ok: true, approvedSpecs };
+                const findings = Array.isArray(res.findings)
+                    ? res.findings.map((f) => f.message).filter(Boolean).join('; ')
+                    : '';
+                refused.push({ id, reason: findings ? `${res.reason ?? 'refused'}: ${findings}` : (res.reason ?? 'refused') });
+                // The chain is topological: approving a child whose parent was refused would either fail
+                // again or, worse, succeed against an unsealed parent. Stop and say what is left.
+                break;
+            }
+            for (const id of idsToApprove.slice(approvedSpecs.length + refused.length)) {
+                refused.push({ id, reason: 'not attempted — an earlier spec in the chain was refused' });
+            }
+            // `ok` means the slice is approved. Anything less is not a success.
+            return { ok: refused.length === 0 && approvedSpecs.length > 0, approvedSpecs, refused };
         },
         async spec_remediate(a) {
             const root = a.root ? (0, root_2.resolveProjectRoot)(a.root).root : process.cwd();
@@ -2456,7 +3031,13 @@ depends_on:
             if (approveRes.approvedSpecs?.length > 0) {
                 actionsTaken.push(`Approved slice specs: ${approveRes.approvedSpecs.join(', ')}`);
             }
-            return { ok: true, actionsTaken };
+            // Same false-PASS as spec_slice_approve had, one layer up: this handler's whole purpose is to
+            // approve, so reporting success when approval was refused sends the caller into code with an
+            // unapproved slice behind it.
+            const refused = approveRes.refused ?? [];
+            for (const r of refused)
+                actionsTaken.push(`Refused ${r.id}: ${r.reason}`);
+            return { ok: refused.length === 0, actionsTaken, refused };
         },
     };
 }