@holmes-lab/holmes-kit 0.19.5 → 0.20.0

package/dist/holmes/mcp/handlers/review-queries.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReviewQueryHandlers = createReviewQueryHandlers;
+const rtm_graph_1 = require("../../rtm/rtm-graph");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const test_scope_1 = require("../../rtm/test-scope");
+const bundler_1 = require("../../context/bundler");
+const scope_1 = require("../../review/scope");
+const package_1 = require("../../review/package");
+const coverage_1 = require("../../review/coverage");
+function createReviewQueryHandlers(context) {
+    return {
+        async context_bundle(a) {
+            context.assertStoreReachable('context_bundle', a.root); // @implements A-SPEC-433
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            const specs = await context.listSpecs();
+            const scanned = context.cachedScan(root, root);
+            const content = context.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) {
+            context.assertStoreReachable('review_scope', 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 context.deriveChangedContext(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, architectureTouched: (0, test_scope_1.architectureGoverningFiles)(changedFiles), obligationGaps: scope.obligationGaps });
+                // 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) {
+            context.assertStoreReachable('review_prepare', 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 context.deriveChangedContext(a.root, a, 'review_prepare');
+            // ContentSource factory shared with context_bundle: see buildContentSource.
+            const content = context.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
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/risk-assessment.d.ts

@@ -0,0 +1,25 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { Approval, Enforcement } from '../../guardrail/risk-gate';
+import { RiskAction } from '../../guardrail/risk-types';
+export interface RiskAssessmentContext {
+    listSpecs(): Promise<Spec[]>;
+    projectRootOf(root: string): string;
+    cachedScan(root: string, repoRoot?: string): ScannedFile[];
+    boundNonceLedger(): string | null;
+}
+export declare function createRiskAssessmentHandlers(context: RiskAssessmentContext): {
+    risk_check(a: {
+        root?: string;
+        action: RiskAction;
+        approval?: Approval;
+        changedSymbols?: string[];
+        enforcement?: Enforcement;
+        ts: string;
+        actor?: string;
+        rationale?: string;
+    }): Promise<{
+        assessment: import("../../guardrail/risk-types").RiskAssessment;
+        gate: import("../../guardrail/risk-gate").GateResult;
+    }>;
+};

package/dist/holmes/mcp/handlers/risk-assessment.js

@@ -0,0 +1,181 @@
+"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.createRiskAssessmentHandlers = createRiskAssessmentHandlers;
+// @implements A-SPEC-607, A-SPEC-100.2, A-SPEC-128
+// @implements A-SPEC-642
+const path = __importStar(require("node:path"));
+const spec_parser_1 = require("../../spec/spec-parser");
+const rtm_graph_1 = require("../../rtm/rtm-graph");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const risk_classifier_1 = require("../../guardrail/risk-classifier");
+const risk_gate_1 = require("../../guardrail/risk-gate");
+const cspec_change_1 = require("../../guardrail/cspec-change");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+const ledger_store_1 = require("../../governance/ledger-store");
+const decision_ledger_1 = require("../../guardrail/decision-ledger");
+function createRiskAssessmentHandlers(context) {
+    return {
+        // @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 = context.projectRootOf(a.root);
+                const specs = await context.listSpecs();
+                const scanned = context.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
+                }
+            }
+            // @implements A-SPEC-225 — the flag that raises this action's risk is COMPUTED here, not
+            // taken from the party being judged. Measured 2026-08-22: nothing in the repository ever set
+            // `cspecConstraintChange`, so the hard-hitl branch guarding C-SPEC constraints could only fire
+            // if the actor changing them volunteered that they had. The precedent is one field away —
+            // `blastRadius` above is derived from the store rather than accepted from the caller — and the
+            // principle is the one `findings.ts` states for `basis`: a judge that stamps its own evidence
+            // turns the field into self-report.
+            //
+            // OR, never assignment: a caller may raise its own risk (that is their business) but may not
+            // lower the server's verdict.
+            const cspecId = (0, cspec_change_1.cspecTargetId)(typeof action.target === 'string' ? action.target : '');
+            if (cspecId !== null) {
+                const stored = (await context.listSpecs()).find((sp) => sp.id === cspecId);
+                const current = stored ? (0, spec_parser_1.serializeSpec)(stored) : null;
+                const proposed = typeof action.stagedContent === 'string' ? action.stagedContent : null;
+                action.cspecConstraintChange = (0, cspec_change_1.cspecConstraintChanged)(current, proposed) || action.cspecConstraintChange === true;
+            }
+            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 && context.boundNonceLedger() === null) {
+                gate = { ...gate, blocked: true, reasons: [...gate.reasons, '개방을 기록할 프로젝트 원장을 확정할 수 없습니다 — 기록 없는 개방은 하지 않습니다(.ax 를 가진 프로젝트에 바인딩된 서버에서 호출하십시오)'] };
+            }
+            // @implements A-SPEC-642 — an opening is refused, and nothing spent, while the merged ledger
+            // holds an unreconciled cross-replica double-spend; the reason names the nonce and the act.
+            if (!gate.blocked && covers && wouldBlockWithout) {
+                const bound = context.boundNonceLedger();
+                const conflict = bound === null ? null : (0, ledger_store_1.ledgerConflictReason)(path.dirname(bound));
+                if (conflict)
+                    gate = { ...gate, blocked: true, reasons: [...gate.reasons, conflict] };
+            }
+            if (assessment.level === 'hard-hitl' && !gate.blocked && covers && (0, provenance_chain_1.nonceDeclared)(a.approval?.nonce)) {
+                const ledgerFile = context.boundNonceLedger();
+                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),
+                    }, { isNonceConsumed: (0, ledger_store_1.nonceConsumedIn)(ledgerFile) });
+                }
+                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 = context.boundNonceLedger();
+            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 = context.boundNonceLedger();
+            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 };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/slice-orchestration.d.ts

@@ -0,0 +1,55 @@
+import { Spec } from '../../spec/spec-parser';
+import { SpecStore } from '../../spec/spec-store';
+export interface SliceOrchestrationContext {
+    listSpecs(): Promise<Spec[]>;
+    unreadableAmong(listed: ReadonlyArray<{
+        id: string;
+    }>, created: readonly string[]): string[];
+    rawHandlersForStore(store: SpecStore): {
+        spec_approve(a: {
+            root: string;
+            id: string;
+        }): Promise<unknown>;
+        spec_slice_approve(a: {
+            root: string;
+            sliceName: string;
+        }): Promise<unknown>;
+    };
+}
+export declare function createSliceOrchestrationHandlers(context: SliceOrchestrationContext): {
+    spec_slice_init(a: {
+        root?: string;
+        sliceName: string;
+        title: string;
+        objective: string;
+        filesToTouch: string[];
+    }): Promise<{
+        ok: boolean;
+        specsCreated: string[];
+        unreadable: string[];
+    }>;
+    spec_slice_approve(a: {
+        root?: string;
+        sliceName: string;
+    }): Promise<{
+        ok: boolean;
+        approvedSpecs: string[];
+        alreadySealed: string[];
+        refused: {
+            id: string;
+            reason: string;
+        }[];
+    }>;
+    spec_remediate(a: {
+        root?: string;
+        targetFile?: string;
+        aspecId?: string;
+    }): Promise<{
+        ok: boolean;
+        actionsTaken: string[];
+        refused: {
+            id: string;
+            reason: string;
+        }[];
+    }>;
+};

package/dist/holmes/mcp/handlers/slice-orchestration.js

@@ -0,0 +1,324 @@
+"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.createSliceOrchestrationHandlers = createSliceOrchestrationHandlers;
+// @implements A-SPEC-609, A-SPEC-100.2, A-SPEC-156, A-SPEC-203, A-SPEC-204, A-SPEC-298, A-SPEC-299, A-SPEC-536.1, A-SPEC-546.1, A-SPEC-565.2, A-SPEC-587.2, A-SPEC-501.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const spec_store_1 = require("../../spec/spec-store");
+const root_1 = require("../../project/root");
+const yaml_scalar_1 = require("../../spec/yaml-scalar");
+const draft_1 = require("../../reverse/draft");
+const anchor_comment_1 = require("../../rtm/anchor-comment");
+function createSliceOrchestrationHandlers(context) {
+    return {
+        async spec_slice_init(a) {
+            const root = a.root ? (0, root_1.resolveProjectRoot)(a.root).root : process.cwd();
+            const specsDir = path.join(root, '.ax', 'specs');
+            const existing = await context.listSpecs();
+            // @implements A-SPEC-546.1 — align with the sibling reverse-draft path (nextIdBase, floor 100)
+            // instead of a hard-coded 200 floor, so a fresh project starts at REQ-100, not REQ-201. Existing
+            // projects are unchanged: nextIdBase returns max(existing)+1, which dominates the floor.
+            const nextId = (0, draft_1.nextIdBase)(existing.map((s) => s.id));
+            const reqId = `REQ-${nextId}`;
+            const hspecId = `H-SPEC-${nextId}`;
+            const aspecId = `A-SPEC-${nextId}`;
+            const tspecId = `T-SPEC-${nextId}`;
+            const reqContent = `---
+source:
+  - kind: user-request
+    ref: ${(0, yaml_scalar_1.yamlScalar)(a.title, 4)}
+    retrieved: ${new Date().toISOString().split('T')[0]}
+    note: ${(0, yaml_scalar_1.yamlScalar)(a.objective, 4)}
+created: ${new Date().toISOString()}
+id: ${reqId}
+type: REQ
+title: ${(0, yaml_scalar_1.yamlScalar)(a.title)}
+status: draft
+depends_on: []
+---
+
+## Problem / Need
+${a.objective}
+
+## Desired Outcome
+${a.objective}
+
+## Constraints
+- Standard project governance rules.
+
+## Success Criteria
+
+## Out of Scope
+- Unrelated feature changes.
+`;
+            const hspecContent = `---
+created: ${new Date().toISOString()}
+id: ${hspecId}
+type: H-SPEC
+title: ${(0, yaml_scalar_1.yamlScalar)(`Functional Specification for ${a.title}`)}
+status: draft
+req_type: functional
+owner: me
+depends_on:
+  - ${reqId}
+---
+
+## Intent
+Implement ${a.title}.
+
+## Scope (In / Out)
+In Scope: ${a.title}.
+Out of Scope: None.
+
+## Design Overview
+High level design for ${a.title}.
+
+## Interfaces / Contracts
+- Target files: ${a.filesToTouch.join(', ')}
+
+## Acceptance Criteria
+- Code written and tests passing.
+
+## Non-Functional
+- Performance and stability maintained.
+
+## Assumptions
+- Environment configured properly.
+
+## Open Questions
+- None.
+`;
+            const aspecContent = `---
+created: ${new Date().toISOString()}
+id: ${aspecId}
+type: A-SPEC
+title: ${(0, yaml_scalar_1.yamlScalar)(`Architecture Specification for ${a.title}`)}
+status: draft
+slice: ${(0, yaml_scalar_1.yamlScalar)(a.sliceName)}
+priority: P1
+independent_test: true
+depends_on:
+  - ${hspecId}
+breaking_change: 'none'
+harness_impact: 'none: TODO — 3하네스(claude/codex/agy) 영향 검토 후 기술'
+os_impact: 'none: TODO — 3OS(windows/mac/linux) 영향 검토 후 기술'
+---
+
+## Objective
+${a.objective}
+
+## Component Design
+1. Target Component:
+   - Modifies ${a.filesToTouch.join(', ')}.
+
+## Inputs / Outputs
+- Inputs: Tool calls / developer modifications.
+- Outputs: Working implementation.
+
+## Behavior
+- Implements desired behavior cleanly.
+
+## Test Points
+- Unit tests in test suite.
+
+## Files to Touch
+${a.filesToTouch.map((f) => `- ${f}`).join('\n')}
+
+## Done When
+- All tests pass 100%.
+`;
+            const tspecContent = `---
+coverage:
+  normal: true
+  corner: true
+  negative: true
+  boundary: true
+id: ${tspecId}
+type: T-SPEC
+title: ${(0, yaml_scalar_1.yamlScalar)(`Test Specification for ${a.title}`)}
+status: draft
+depends_on:
+  - ${aspecId}
+---
+
+## Normal Cases
+- Given valid inputs
+  When operation is performed
+  Then correct behavior is observed
+
+## Corner Cases
+- Given edge cases
+  When operation is performed
+  Then system handles gracefully
+
+## Negative Cases
+- Given invalid inputs
+  When operation is performed
+  Then appropriate error is returned
+
+## Boundary Cases
+- Given boundary conditions
+  When operation is performed
+  Then boundary limits are respected
+`;
+            fs.mkdirSync(path.join(specsDir, '01_req'), { recursive: true });
+            fs.mkdirSync(path.join(specsDir, '02_h-spec', 'functional'), { recursive: true });
+            fs.mkdirSync(path.join(specsDir, '03_a-spec'), { recursive: true });
+            fs.mkdirSync(path.join(specsDir, '05_t-spec'), { recursive: true });
+            fs.writeFileSync(path.join(specsDir, '01_req', `${reqId}.md`), reqContent);
+            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);
+            // @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 = context.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_1.resolveProjectRoot)(a.root).root : process.cwd();
+            const rawStore = new spec_store_1.LocalMarkdownRepository(path.join(root, '.ax', 'specs'));
+            const specs = await rawStore.list();
+            const inSlice = specs.filter((s) => {
+                if (s.frontmatter?.slice === a.sliceName)
+                    return true;
+                if (s.id === a.sliceName)
+                    return true;
+                return false;
+            });
+            const idsToApprove = [];
+            if (inSlice.length > 0) {
+                const aspec = inSlice.find((s) => s.type === 'A-SPEC') ?? inSlice[0];
+                const mainId = (id) => id.split('.')[0].replace(/\D/g, '');
+                const req = specs.find((s) => aspec.dependsOn.includes(s.id) || mainId(s.id) === mainId(aspec.id));
+                const hspec = specs.find((s) => s.type === 'H-SPEC' && (s.dependsOn.includes(req?.id ?? '') || mainId(s.id) === mainId(aspec.id)));
+                const tspec = specs.find((s) => s.type === 'T-SPEC' && (s.dependsOn.includes(aspec.id) || mainId(s.id) === mainId(aspec.id)));
+                if (req)
+                    idsToApprove.push(req.id);
+                if (hspec)
+                    idsToApprove.push(hspec.id);
+                idsToApprove.push(aspec.id);
+                if (tspec)
+                    idsToApprove.push(tspec.id);
+            }
+            else {
+                const matches = specs.filter((s) => s.id.includes(a.sliceName));
+                idsToApprove.push(...matches.map((s) => s.id));
+            }
+            const rawHandlers = context.rawHandlersForStore(rawStore);
+            const approvedSpecs = [];
+            const alreadySealed = [];
+            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, alreadySealed, refused: [{ id: a.sliceName, reason: 'no specs matched this slice name' }] };
+            }
+            // @implements A-SPEC-587.2 — a sealed spec is SKIPPED, not re-sealed: re-approving asked the
+            // human the same question again (same request id back in the queue) and stopped the chain
+            // there, so the H-SPEC was never even attempted (measured 2026-09-10, three slices).
+            const sealed = (id) => {
+                const s = specs.find((x) => x.id === id);
+                return s?.status === 'approved' && typeof s.frontmatter?.approved_digest === 'string';
+            };
+            for (const id of idsToApprove) {
+                if (sealed(id)) {
+                    alreadySealed.push(id);
+                    continue;
+                }
+                const res = (await rawHandlers.spec_approve({ root, id }));
+                if (res.approved || res.ok) {
+                    approvedSpecs.push(id);
+                    continue;
+                }
+                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 + alreadySealed.length + refused.length)) {
+                refused.push({ id, reason: 'not attempted — an earlier spec in the chain was refused' });
+            }
+            // `ok` means the slice is approved — freshly or already. Anything less is not a success.
+            return { ok: refused.length === 0 && approvedSpecs.length + alreadySealed.length > 0, approvedSpecs, alreadySealed, refused };
+        },
+        async spec_remediate(a) {
+            const root = a.root ? (0, root_1.resolveProjectRoot)(a.root).root : process.cwd();
+            const actionsTaken = [];
+            if (a.targetFile && a.aspecId) {
+                const fullPath = path.isAbsolute(a.targetFile) ? a.targetFile : path.join(root, a.targetFile);
+                if (fs.existsSync(fullPath)) {
+                    // @implements A-SPEC-501.1 — BUG-4 (dogfooded twice): the old unconditional
+                    // `// @implements` broke Python/YAML targets outright AND produced anchors the scanner
+                    // could not read. The syntax comes from the one map the scanner is aligned with, an
+                    // unknown syntax is an honest refusal, and the containment check is form-agnostic so a
+                    // `#` anchor is not double-injected.
+                    const anchorTag = (0, anchor_comment_1.anchorLineFor)(fullPath, a.aspecId);
+                    const content = fs.readFileSync(fullPath, 'utf8');
+                    if (anchorTag === null) {
+                        actionsTaken.push(`앵커 주입 거부: ${path.basename(fullPath)} — 이 확장자의 주석 문법을 모릅니다. 파일 관례에 맞는 주석으로 1행에 '@implements ${a.aspecId}'를 직접 추가하십시오`);
+                    }
+                    else if (!content.includes(`@implements ${a.aspecId}`)) {
+                        fs.writeFileSync(fullPath, `${anchorTag}\n${content}`);
+                        actionsTaken.push(`Injected ${anchorTag} on line 1 of ${a.targetFile}`);
+                    }
+                }
+            }
+            const rawStore = new spec_store_1.LocalMarkdownRepository(path.join(root, '.ax', 'specs'));
+            const rawHandlers = context.rawHandlersForStore(rawStore);
+            const approveRes = await rawHandlers.spec_slice_approve({ root, sliceName: a.aspecId ?? 'slice' });
+            if (approveRes.approvedSpecs?.length > 0) {
+                actionsTaken.push(`Approved slice specs: ${approveRes.approvedSpecs.join(', ')}`);
+            }
+            // 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 };
+        },
+    };
+}