@holmes-lab/holmes-kit 0.19.5 → 0.20.0

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

@@ -0,0 +1,339 @@
+"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.createSpecLifecycleHandlers = createSpecLifecycleHandlers;
+// @implements A-SPEC-628, A-SPEC-627.1, A-SPEC-621, A-SPEC-100.2, A-SPEC-128, A-SPEC-151, A-SPEC-222, A-SPEC-538.1, A-SPEC-255, A-SPEC-133, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245
+// @implements A-SPEC-638
+const path = __importStar(require("node:path"));
+const spec_store_1 = require("../../spec/spec-store");
+const transition_policy_1 = require("../../spec/transition-policy");
+const entity_store_1 = require("../../spec/entity-store");
+const entity_transaction_1 = require("../../spec/entity-transaction");
+const workspace_identity_1 = require("../../project/workspace-identity");
+const node_crypto_1 = require("node:crypto");
+const ledger_store_1 = require("../../governance/ledger-store");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+const approval_grants_1 = require("../../governance/approval-grants");
+const renumber_1 = require("../../spec/renumber");
+function createSpecLifecycleHandlers(context) {
+    const { store, resolveLedgerRoot } = context;
+    return {
+        /**
+         * Move a document to `outdated` — the only path there.
+         *
+         * @implements A-SPEC-222
+         * `outdated` was in SPEC_STATUSES with no code writing it and no document carrying it: a
+         * declared state nothing could reach. That mattered the moment 23 deprecated REQs needed
+         * cleaning up, because the only transition tool sends everything to `draft`, and calling a
+         * retired document "draft" is a worse lie than the non-canonical word it replaced.
+         *
+         * Retirement withdraws authority rather than granting it, so it does NOT need the approval key
+         * by default. Two cases invert that, and the threshold follows the RISK rather than the name of
+         * the act:
+         *
+         *  - A sealed document. The code gate demands an approved T-SPEC naming the target A-SPEC;
+         *    retiring that T-SPEC removes the demand. Unguarded, retirement is an approval bypass.
+         *  - A document an APPROVED spec depends on. That chain is holding something up right now.
+         */
+        async spec_retire(a) {
+            const all = await store.list();
+            if (all.filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 폐기 전에 거부합니다.`,
+                };
+            }
+            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-222 — a document with no `type:` cannot be filed: the store derives its
+            // folder from the kind, and there is none. Refuse rather than infer, because a wrongly
+            // inferred kind MOVES the document into another folder. Measured 2026-08-21: without this the
+            // store threw `Cannot read properties of undefined (reading 'folder')` on the first of the 23
+            // legacy documents this tool was built for — every unit fixture carried `type:`, which is how
+            // it got through. Declaring the kind is `spec_upgrade`'s job, so the refusal names it.
+            if (!spec.type) {
+                return {
+                    ok: false,
+                    reason: `${a.id}에는 \`type:\` 선언이 없습니다(구형식 문서) — 어느 폴더에 속하는지 알 수 없어 폐기할 수 없습니다.`
+                        + ' 종류를 추론하지 않는 이유는 잘못 추론한 종류가 문서를 다른 폴더로 옮기기 때문입니다.'
+                        + ` 먼저 spec_upgrade({ id: "${a.id}" })로 형식을 올린 뒤 다시 폐기하십시오 — 그 도구가 이전 status를 legacy_status로 보존합니다.`,
+                };
+            }
+            // Idempotent, and it writes NOTHING on the second call: overwriting the first retirement's
+            // reason would make the record graffiti rather than history.
+            if (spec.status === 'outdated') {
+                return { ok: true, retired: false, id: a.id, dependents: [], reason: `${a.id}은(는) 이미 outdated 입니다` };
+            }
+            const approvalRaw = process.env.HOLMES_APPROVAL;
+            let approval;
+            try {
+                approval = approvalRaw ? JSON.parse(approvalRaw) : undefined;
+            }
+            catch {
+                approval = undefined;
+            }
+            const retireResolved = context.resolveHandlerApproval(a.root, approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            const covered = retireResolved !== undefined;
+            const sealed = typeof spec.frontmatter.approved_digest === 'string';
+            if (sealed && !covered) {
+                return {
+                    ok: false,
+                    reason: `${a.id}은(는) 봉인된 문서입니다 — 폐기는 이 행위를 덮는 유효한 대역외 HOLMES_APPROVAL 이 필요합니다.`
+                        + ' 코드 게이트를 막고 있는 approved T-SPEC 을 폐기하면 그 게이트가 열리므로, 폐기가 승인 우회 경로가 되지 않도록 fail-closed 로 막습니다.'
+                        + ' (범위를 쓰면 kind "spec-approve")'
+                        + context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '봉인된 스펙의 폐기' }),
+                };
+            }
+            // @implements A-SPEC-245 — a grant that authorized breaking a seal is spent by it.
+            if (sealed && retireResolved?.source === 'grant' && retireResolved.root && retireResolved.approval.nonce) {
+                (0, approval_grants_1.consumeGrantFile)(retireResolved.root, retireResolved.approval.nonce);
+            }
+            const prepared = (0, transition_policy_1.prepareLifecycleSpec)(spec, all, 'retire', a.reason);
+            if (!prepared.ok)
+                return prepared;
+            const { dependents, candidate } = prepared;
+            // Destination BEFORE the write, the order A-SPEC-188 fixed for spec_approve: a resolution
+            // failure must leave nothing behind.
+            const dest = resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const ledgerRoot = dest.root;
+            // Blank is omitted, never written: `retired_reason: ""` asserts a ground that does not exist,
+            // the same rule `legacy_status` follows. A document already carrying `superseded_by` has
+            // answered "why" already and is not asked twice.
+            const reason = typeof a.reason === 'string' ? a.reason.trim() : '';
+            try {
+                await store.write(candidate, { expectedVersion: cur.version });
+            }
+            catch (e) {
+                if (e instanceof spec_store_1.SpecVersionConflictError) {
+                    return { ok: false, reason: `폐기 진행 중 ${a.id}이(가) 바뀌었습니다 — 확인 후 다시 시도하십시오. 이번 폐기는 아무것도 쓰지 않았습니다.` };
+                }
+                throw e;
+            }
+            new ledger_store_1.FileLedgerStore(path.join(ledgerRoot, '.ax', 'ledger')).append({
+                ts: new Date().toISOString(),
+                actor: approval?.actor ?? 'unattributed',
+                kind: 'spec-retired',
+                summary: `retired ${a.id}${reason ? ` — ${reason}` : ''}`,
+                inputs: [a.id],
+                rationale: reason || (approval?.rationale ?? 'retired'),
+                ...(approval ? { authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token) } : {}),
+            });
+            return { ok: true, retired: true, id: a.id, dependents: dependents.map((s) => s.id) };
+        },
+        // @implements A-SPEC-255 — the WIRING only. The judgment is `planRenumber`, which is pure and
+        // tested directly; this handler adds no rules of its own. Re-sealing is deliberately absent:
+        // `spec_approve` is the only sealer, so the plan reports the two ORDERS and the caller runs them.
+        // @implements A-SPEC-255 — WIRING only. The judgment lives in `planRenumber`, which is pure and
+        // tested directly; nothing here adds a rule. Re-sealing is deliberately absent: `spec_approve`
+        // is the only sealer (a second sealer becomes a second truth), so the plan reports the two
+        // ORDERS and the caller runs them. `dryRun` defaults to true — a renumber is read before it runs.
+        async spec_renumber(a) {
+            const specsRoot = store.specsRoot;
+            if (typeof specsRoot !== 'string')
+                return { ok: false, reason: '파일 스토어에 묶인 서버에서만 리넘버할 수 있습니다.' };
+            const run = (journaled) => {
+                try {
+                    if ((0, entity_store_1.inspectEntityStore)(specsRoot).state === 'active')
+                        return { ok: false, reason: 'An activated store requires entity_renumber to preserve entity UUIDs and references; raw legacy renumber is unavailable.' };
+                }
+                catch (error) {
+                    // Unmarked legacy file stores retain the existing API. Corrupt or pending entity state never falls back.
+                    if (!(error instanceof entity_transaction_1.EntityStoreError) || error.code !== 'missing-workspace') {
+                        if (error instanceof entity_transaction_1.EntityStoreError)
+                            return { ok: false, reason: error.message };
+                        throw error;
+                    }
+                }
+                const projectRoot = path.resolve(specsRoot, '..', '..');
+                const plan = (0, renumber_1.planRenumber)({
+                    specs: (0, renumber_1.readSpecsForRenumber)(specsRoot),
+                    sources: (0, renumber_1.readSourcesForRenumber)(projectRoot),
+                    oldBase: String(a.oldBase), newBase: String(a.newBase),
+                });
+                if (plan.refusal)
+                    return { ok: false, reason: plan.refusal };
+                if (a.dryRun !== false)
+                    return { ok: true, dryRun: true, plan };
+                // @implements A-SPEC-638 — in a registered workspace the raw publication is preceded by a
+                // rollback journal holding the original bytes of every file it will touch, so an interrupted
+                // run is inspectable and reversible through entity_store recovery.
+                let retire;
+                const identity = journaled ? (0, workspace_identity_1.workspaceIdentity)(journaled.root) : undefined;
+                if (journaled && identity && identity.state === 'registered') {
+                    const operationId = (0, node_crypto_1.randomUUID)();
+                    const rel = (abs) => path.relative(journaled.root, abs).split(path.sep).join('/');
+                    const touched = [...new Set([
+                            ...plan.moves.flatMap((m) => [rel(path.join(specsRoot, m.from)), rel(path.join(specsRoot, m.to))]),
+                            ...plan.dependsOn.map((d) => rel(path.join(specsRoot, d.file))),
+                            ...plan.slices.map((s) => rel(path.join(specsRoot, s.file))),
+                            ...plan.anchors.map((anchor) => rel(path.join(projectRoot, anchor.file))),
+                        ])].sort();
+                    const changes = touched.map((locator) => ({ locator, before: (0, entity_transaction_1.readEntityBytes)(path.join(journaled.root, locator))?.toString('base64') ?? null }));
+                    const text = JSON.stringify({ schema: entity_store_1.LEGACY_RENUMBER_JOURNAL_SCHEMA, operationId, workspaceId: identity.workspaceId, storeLocator: journaled.locator, oldBase: String(a.oldBase), newBase: String(a.newBase), changes }) + '\n';
+                    (0, entity_transaction_1.publishEntityRecord)(journaled.root, '.ax/state/entity-transactions/' + operationId + '/journal.json', text);
+                    retire = () => (0, entity_transaction_1.retireEntityOperation)(journaled.root, operationId, journaled.locator, (0, entity_transaction_1.entityContentVersion)(text));
+                }
+                const movedSpecs = (0, renumber_1.applyRenumber)(specsRoot, { ...plan, anchors: [] });
+                (0, renumber_1.applyRenumber)(projectRoot, { ...plan, moves: [], dependsOn: [], slices: [] });
+                new ledger_store_1.FileLedgerStore(path.join(projectRoot, '.ax', 'ledger')).append({
+                    ts: new Date().toISOString(),
+                    actor: 'spec_renumber',
+                    kind: 'spec-renumbered',
+                    summary: `renumbered base ${a.oldBase} -> ${a.newBase}: ${movedSpecs} spec(s), ${plan.anchors.length} anchored file(s), ${plan.proseCandidates.length} prose candidate(s) left for a human`,
+                    inputs: plan.moves.map((m) => `${m.oldId}->${m.newId}`),
+                });
+                retire?.();
+                return { ok: true, dryRun: false, movedSpecs, plan };
+            };
+            if (a.dryRun !== false)
+                return run();
+            let bound;
+            try {
+                bound = (0, entity_store_1.entityStoreBinding)(specsRoot);
+            }
+            catch (error) {
+                if (error instanceof entity_transaction_1.EntityStoreError && error.code === 'missing-workspace')
+                    return run();
+                if (error instanceof entity_transaction_1.EntityStoreError)
+                    return { ok: false, reason: error.message };
+                throw error;
+            }
+            try {
+                // Adoption uses the same store ownership. Recheck activation within this hold.
+                return (0, entity_transaction_1.withEntityStoreLock)(bound.root, bound.locator, () => run({ root: bound.root, locator: bound.locator }));
+            }
+            catch (error) {
+                if (error instanceof entity_transaction_1.EntityStoreError)
+                    return { ok: false, reason: error.message };
+                throw error;
+            }
+        },
+        /**
+         * @implements A-SPEC-538.1
+         * The inverse of spec_approve: returns a SEALED (approved) spec to an editable `draft`, clearing
+         * `approved_digest` and `parent_digests` in ONE act, and records `spec-unsealed`. Hand-editing
+         * only `status` leaves seal residue that later trips validation; this atomizes the reverse.
+         *
+         * Un-sealing WITHDRAWS a seal, so — like retiring a sealed document — it demands a covering
+         * out-of-band HOLMES_APPROVAL (fail-closed): un-sealing an approved T-SPEC removes the code
+         * gate's demand, so an unguarded un-seal would be an approval bypass. And it refuses when an
+         * APPROVED spec depends on the target, because that dependent's `parent_digests` — the snapshot
+         * drift detection compares against — would silently go stale.
+         */
+        async spec_unseal(a) {
+            const all = await store.list();
+            if (all.filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 봉인 해제 전에 거부합니다.`,
+                };
+            }
+            const cur = await store.read(a.id);
+            if (!cur) {
+                const dir = store.specsRoot;
+                const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
+                return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
+            }
+            const spec = cur.spec;
+            if (!spec.type) {
+                return {
+                    ok: false,
+                    reason: `${a.id}에는 \`type:\` 선언이 없습니다(구형식 문서) — 어느 폴더에 속하는지 알 수 없어 봉인 해제할 수 없습니다.`
+                        + ` 먼저 spec_upgrade({ id: "${a.id}" })로 형식을 올린 뒤 다시 시도하십시오.`,
+                };
+            }
+            // Sealed ⇔ carries approved_digest. Un-sealing an already-draft spec writes NOTHING (a second
+            // un-seal is history, not graffiti) — mirrors spec_retire's idempotent no-op.
+            const sealed = typeof spec.frontmatter.approved_digest === 'string';
+            if (!sealed) {
+                return { ok: true, unsealed: false, id: a.id, dependents: [], reason: `${a.id}은(는) 이미 미봉인(draft) 상태입니다` };
+            }
+            const approvalRaw = process.env.HOLMES_APPROVAL;
+            let approval;
+            try {
+                approval = approvalRaw ? JSON.parse(approvalRaw) : undefined;
+            }
+            catch {
+                approval = undefined;
+            }
+            const resolved = context.resolveHandlerApproval(a.root, approval, { kind: 'spec-approve', target: a.id }, new Date().toISOString());
+            if (resolved === undefined) {
+                return {
+                    ok: false,
+                    reason: `${a.id}은(는) 봉인된 문서입니다 — 봉인 해제는 이 행위를 덮는 유효한 대역외 HOLMES_APPROVAL 이 필요합니다.`
+                        + ' 봉인을 해제하면 코드 게이트가 요구하던 approved 스펙의 봉인이 사라지므로, 해제가 승인 우회 경로가 되지 않도록 fail-closed 로 막습니다.'
+                        + ' (범위를 쓰면 kind "spec-approve")'
+                        + context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '봉인된 스펙의 해제' }),
+                };
+            }
+            // @implements A-SPEC-245 — a grant that authorized breaking a seal is spent by it.
+            if (resolved.source === 'grant' && resolved.root && resolved.approval.nonce) {
+                (0, approval_grants_1.consumeGrantFile)(resolved.root, resolved.approval.nonce);
+            }
+            const prepared = (0, transition_policy_1.prepareLifecycleSpec)(spec, all, 'unseal');
+            if (!prepared.ok)
+                return prepared;
+            const { dependents, candidate } = prepared;
+            // Destination BEFORE the write (A-SPEC-188 order): a resolution failure leaves nothing behind.
+            const dest = resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const ledgerRoot = dest.root;
+            try {
+                await store.write(candidate, { expectedVersion: cur.version });
+            }
+            catch (e) {
+                if (e instanceof spec_store_1.SpecVersionConflictError) {
+                    return { ok: false, reason: `봉인 해제 진행 중 ${a.id}이(가) 바뀌었습니다 — 확인 후 다시 시도하십시오. 이번 해제는 아무것도 쓰지 않았습니다.` };
+                }
+                throw e;
+            }
+            new ledger_store_1.FileLedgerStore(path.join(ledgerRoot, '.ax', 'ledger')).append({
+                ts: new Date().toISOString(),
+                actor: approval?.actor ?? 'unattributed',
+                kind: 'spec-unsealed',
+                summary: `unsealed ${a.id}`,
+                inputs: [a.id],
+                rationale: approval?.rationale ?? 'unsealed',
+                ...(approval ? { authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token) } : {}),
+            });
+            return { ok: true, unsealed: true, id: a.id, dependents: dependents.map((s) => s.id) };
+        },
+    };
+}

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

@@ -0,0 +1,30 @@
+import { Spec } from '../../spec/spec-parser';
+export interface SpecQueryContext {
+    listSpecs(): Promise<Spec[]>;
+    assertStoreReachable(tool: string, root: unknown): void;
+    resolver(specs: Spec[]): (id: string) => Spec | null;
+}
+export declare function createSpecQueryHandlers(context: SpecQueryContext): {
+    spec_validate(a: any): Promise<{
+        ok: boolean;
+        findings: {
+            level: string;
+            code: string;
+            message: any;
+        }[];
+    }>;
+    spec_list(a: any): Promise<{
+        specs: {
+            legacy?: boolean | undefined;
+            parent?: string | undefined;
+            id: string;
+            type: import("../../spec/spec-types").SpecType;
+            status: "draft" | "review" | "approved" | "outdated";
+        }[];
+    }>;
+    spec_next(): Promise<{
+        next: import("../../spec/spec-types").SpecType;
+    } | {
+        next: null;
+    }>;
+};

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

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpecQueryHandlers = createSpecQueryHandlers;
+const validator_1 = require("../../spec/validator");
+const legacy_format_1 = require("../../spec/legacy-format");
+const spec_types_1 = require("../../spec/spec-types");
+function createSpecQueryHandlers(context) {
+    return {
+        async spec_validate(a) {
+            const specs = await context.listSpecs();
+            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, context.resolver(specs));
+        },
+        async spec_list(a) {
+            context.assertStoreReachable('spec_list', a.root); // @implements A-SPEC-419
+            const specs = await context.listSpecs();
+            // @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 context.listSpecs();
+            // 다음에 작성 가능한 첫 미승인 단계
+            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 };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/taint-screening.d.ts

@@ -0,0 +1,48 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+export interface TaintScreeningContext {
+    listSpecs(): Promise<Spec[]>;
+    foreignRootReason(root?: string): string | null;
+    projectRootOf(root: string): string;
+    cachedScan(root: string, repoRoot?: string): ScannedFile[];
+}
+export declare function createTaintScreeningHandlers(context: TaintScreeningContext): {
+    /**
+     * @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".
+     */
+    taint_scan(a: {
+        root: string;
+        dataFlow?: boolean;
+    }): Promise<{
+        kind: string;
+        limits: ("name-based matching" | "no def-use" | "no sanitizers" | "call-edge-only")[];
+        maxPaths: number | undefined;
+        truncated: number;
+        pairs: import("../../rtm/taint").TaintPair[];
+    } | {
+        ok: boolean;
+        reason: string;
+    } | {
+        dataFlow: {
+            findings: Record<string, unknown>[];
+            /** Findings the reaching-definition evidence positively refuted (dead or fully sanitized). */
+            refutedByReachingDefs: number;
+            limits: ("no field sensitivity (obj.a and obj.b are one value)" | "no aliasing" | "no path sensitivity" | "no container/element tracking" | "no reflection or dynamic dispatch" | "sink matching is by callee NAME with no receiver type — RE.exec(s) is indistinguishable from child_process.exec(s)" | "no anonymous-function parameters (arrow/function-expression params are not bound)" | "not statement-order sensitive — a variable tainted anywhere in a function is tainted throughout it" | "reports reachability of tainted data to a sink, never exploitability")[];
+            converged: boolean;
+            truncated: number;
+            /** Which languages this run could actually judge, so a zero is readable. */
+            languagesAnalysed: (string | null)[];
+        };
+        kind: string;
+        limits: ("name-based matching" | "no def-use" | "no sanitizers" | "call-edge-only")[];
+        maxPaths: number | undefined;
+        truncated: number;
+        pairs: import("../../rtm/taint").TaintPair[];
+        ok?: undefined;
+        reason?: undefined;
+    }>;
+};