@holmes-lab/holmes-kit 0.19.5 → 0.20.0

package/dist/holmes/mcp/handlers/adoption.d.ts

@@ -0,0 +1,118 @@
+import { Spec } from '../../spec/spec-parser';
+import { SpecStore } from '../../spec/spec-store';
+import { DraftResult } from '../../reverse/draft';
+import { AnchorMapping } from '../../reverse/anchor';
+export interface AdoptionContext {
+    listSpecs(): Promise<Spec[]>;
+    writeSpec: SpecStore['write'];
+    assertReadableRoot(tool: string, root: string): void;
+    occupiedTarget(specs: Spec[]): string | undefined;
+}
+export declare function createAdoptionHandlers(context: AdoptionContext): {
+    /**
+     * Read-only inventory of a brownfield target: candidate clusters, coverage, and what the scan
+     * could not resolve. Deliberately does NOT call assertRepoTopLevel — a target that is not a git
+     * repository is a supported case here, reported as `isGit: false`.
+     */
+    reverse_scan(a: {
+        root: string;
+        maxFlagged?: number;
+    }): Promise<{
+        root: string;
+        isGit: boolean;
+        scanned: number;
+        droppedUntracked: number;
+        candidates: number;
+        anchored: number;
+        unanchored: number;
+        clusters: import("../../reverse/cluster").Cluster[];
+        testClusters: import("../../reverse/cluster").Cluster[];
+        coverage: {
+            structurallyResolved: number;
+            inTestClusters: number;
+            cohesionUnmeasured: number;
+            testsMatched: number;
+            testsUnmatched: number;
+            withDynamicIndicators: number;
+            indicators: Partial<Record<import("../../reverse/dynamic-wiring").Indicator, number>>;
+            uncalibratedIndicatorLanguages: string[];
+            ignoreUnsupportedPatterns: string[];
+        };
+        needsHumanConfirmation: import("../../reverse/scan").FlaggedFile[];
+        tests: import("../../reverse/test-map").TestMapping;
+    }>;
+    /**
+     * Draft H-SPEC/A-SPEC/T-SPEC documents for the recovered clusters under an EXISTING parent REQ.
+     *
+     * The REQ is the human's to write and this tool refuses without one — a requirement states
+     * business intent, which is not in the code. Everything emitted is `status: draft`, and writing
+     * requires an explicit `dryRun: false`.
+     *
+     * WHERE THE DOCUMENTS LAND: in the SERVER's configured spec store (`HOLMES_SPECS`, default
+     * `.ax/specs` relative to the server's working directory) — not inside `root`. In the intended
+     * adoption the two are the same directory, because the server runs inside the target it governs;
+     * pointing `root` at a different repository drafts that repository's slices into THIS store,
+     * which is a governance decision the caller has to make deliberately.
+     */
+    reverse_draft(a: {
+        root: string;
+        parentReqId?: string;
+        cluster?: string;
+        dryRun?: boolean;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        availableClusters?: undefined;
+        dryRun?: undefined;
+        parentReqId?: undefined;
+        clusters?: undefined;
+        drafted?: undefined;
+        skipped?: undefined;
+        refused?: undefined;
+    } | {
+        ok: boolean;
+        reason: string;
+        availableClusters: string[];
+        dryRun?: undefined;
+        parentReqId?: undefined;
+        clusters?: undefined;
+        drafted?: undefined;
+        skipped?: undefined;
+        refused?: undefined;
+    } | {
+        ok: boolean;
+        dryRun: boolean;
+        parentReqId: string;
+        clusters: number;
+        drafted: DraftResult[];
+        skipped: {
+            clusterKey: string;
+            reason: string;
+        }[];
+        refused: {
+            clusterKey: string;
+            reason: string;
+            findings?: unknown[];
+        }[];
+        reason?: undefined;
+        availableClusters?: undefined;
+    }>;
+    /**
+     * Insert `@implements` anchors into source files. Dry-run by DEFAULT, and anchoring to a
+     * non-approved A-SPEC is refused — a reverse-engineered draft describes code; description does
+     * not confer approval.
+     */
+    reverse_anchor(a: {
+        root: string;
+        mapping: AnchorMapping[];
+        dryRun?: boolean;
+    }): Promise<{
+        blockers: Record<string, string>;
+        applied: number;
+        dryRun: boolean;
+        would: number;
+        failed: import("../../reverse/anchor").RefusedAnchor[];
+        edits: import("../../reverse/anchor").AnchorEdit[];
+        refused: import("../../reverse/anchor").RefusedAnchor[];
+    }>;
+};

package/dist/holmes/mcp/handlers/adoption.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdoptionHandlers = createAdoptionHandlers;
+const spec_store_1 = require("../../spec/spec-store");
+const validator_1 = require("../../spec/validator");
+const legacy_format_1 = require("../../spec/legacy-format");
+const approval_blockers_1 = require("../../spec/approval-blockers");
+const scan_1 = require("../../reverse/scan");
+const draft_1 = require("../../reverse/draft");
+const anchor_1 = require("../../reverse/anchor");
+function createAdoptionHandlers(context) {
+    return {
+        // @implements A-SPEC-126
+        // Brownfield reverse engineering. Three explicitly-invoked tools, nothing running as a side
+        // effect of an ordinary session, and every write path opt-in: scan writes nothing at all, draft
+        // and anchor are dry-run by DEFAULT.
+        /**
+         * Read-only inventory of a brownfield target: candidate clusters, coverage, and what the scan
+         * could not resolve. Deliberately does NOT call assertRepoTopLevel — a target that is not a git
+         * repository is a supported case here, reported as `isGit: false`.
+         */
+        async reverse_scan(a) {
+            // @implements A-SPEC-189 §10 (round 11) — `reverse_scan`/`reverse_draft` never call
+            // `projectRootOf`, so §7's refusal marker never reached them and their own POINTED sentence
+            // ("<root> is not a directory") arrived at the wire as a raw -32603 fault. A refusal about the
+            // caller's own argument is a refusal wherever it is authored.
+            context.assertReadableRoot('reverse_scan', a.root);
+            // `surfaceByCluster` is drafting evidence, not reading material. On the calibration target it
+            // is 11,460 characters across 15 clusters, and this response enters context on every scan —
+            // paying that to READ what only DRAFTING consumes. `reverse_draft` reads it in-process instead.
+            const { surfaceByCluster: _drafting, ...response } = (0, scan_1.reverseScan)(a.root, { maxFlagged: a.maxFlagged });
+            return response;
+        },
+        /**
+         * Draft H-SPEC/A-SPEC/T-SPEC documents for the recovered clusters under an EXISTING parent REQ.
+         *
+         * The REQ is the human's to write and this tool refuses without one — a requirement states
+         * business intent, which is not in the code. Everything emitted is `status: draft`, and writing
+         * requires an explicit `dryRun: false`.
+         *
+         * WHERE THE DOCUMENTS LAND: in the SERVER's configured spec store (`HOLMES_SPECS`, default
+         * `.ax/specs` relative to the server's working directory) — not inside `root`. In the intended
+         * adoption the two are the same directory, because the server runs inside the target it governs;
+         * pointing `root` at a different repository drafts that repository's slices into THIS store,
+         * which is a governance decision the caller has to make deliberately.
+         */
+        async reverse_draft(a) {
+            context.assertReadableRoot('reverse_draft', a.root);
+            if (typeof a.parentReqId !== 'string' || a.parentReqId.trim() === '') {
+                return {
+                    ok: false,
+                    reason: 'parentReqId is required. A REQ states business intent, which does not exist in the code ' +
+                        'and cannot be recovered from it — write the REQ first, then re-run with its id.',
+                };
+            }
+            const parentReqId = a.parentReqId.trim();
+            const specs = await context.listSpecs();
+            const req = specs.find((s) => s.id === parentReqId);
+            // An unresolvable parent would emit an orphan H-SPEC: a chain that only looks complete.
+            if (!req)
+                return { ok: false, reason: `parent REQ ${parentReqId} was not found in the spec store — create it first` };
+            // @implements A-SPEC-184
+            // A document with no `type:` is not a wrong-kind parent — it is an older-format one, and saying
+            // "is a undefined" left the adopter holding a visible document with nowhere to go. When the type
+            // IS declared, `legacyMessage` returns null and the original wording stands: that path was
+            // already accurate and REQ-184 does not touch it.
+            const formatWhy = (0, legacy_format_1.legacyMessage)(req);
+            if (formatWhy)
+                return { ok: false, reason: formatWhy };
+            if (req.type !== 'REQ')
+                return { ok: false, reason: `${parentReqId} is a ${req.type}; drafts must hang off a REQ` };
+            const report = (0, scan_1.reverseScan)(a.root);
+            // A cluster already drafted is recognised by the `reverse_cluster` key its documents carry, so
+            // re-running over the same tree never duplicates a slice.
+            const alreadyDrafted = new Set(specs.map((s) => s.frontmatter.reverse_cluster).filter((k) => typeof k === 'string'));
+            const selected = a.cluster ? report.clusters.filter((c) => (0, draft_1.clusterKeyOf)(c) === a.cluster) : report.clusters;
+            // A key that matches nothing must not read as success: "drafted 0" is indistinguishable from
+            // "everything was already drafted", so a mistyped key would silently skip the work.
+            if (a.cluster && selected.length === 0) {
+                const keys = report.clusters.map(draft_1.clusterKeyOf);
+                return {
+                    ok: false,
+                    reason: `no cluster matches key "${a.cluster}" — reverse_scan reports ${keys.length} cluster(s)`,
+                    availableClusters: keys.slice(0, 50),
+                };
+            }
+            let base = (0, draft_1.nextIdBase)(specs.map((s) => s.id));
+            const drafted = [];
+            const skipped = [];
+            const refused = [];
+            for (const cluster of selected) {
+                const key = (0, draft_1.clusterKeyOf)(cluster);
+                if (alreadyDrafted.has(key)) {
+                    skipped.push({ clusterKey: key, reason: 'already drafted' });
+                    continue;
+                }
+                const d = (0, draft_1.draftSpecs)(cluster, req.id, String(base), {
+                    surface: report.surfaceByCluster[key] ?? [],
+                    testFiles: cluster.testFiles ?? [],
+                    testsUnmatched: report.coverage.testsUnmatched,
+                });
+                if (!d.ok) {
+                    refused.push({ clusterKey: key, reason: d.reason });
+                    continue;
+                }
+                // Validate BEFORE writing: a draft that fails the project's own validator is not evidence of
+                // anything, and emitting one would put a broken document into the chain.
+                const known = [...specs, ...drafted.flatMap((x) => x.specs), ...d.specs];
+                const resolve = (id) => known.find((s) => s.id === id) ?? null;
+                const errors = d.specs.flatMap((s) => (0, validator_1.validateSpec)(s, resolve).findings.filter((f) => f.level === 'error').map((f) => ({ spec: s.id, ...f })));
+                if (errors.length) {
+                    refused.push({ clusterKey: key, reason: 'drafted documents failed validation', findings: errors });
+                    continue;
+                }
+                drafted.push(d);
+                base++;
+            }
+            const dryRun = a.dryRun !== false; // opt IN to writing
+            // @implements A-SPEC-188 — the minted id sits above every PARSEABLE id, but a file list()
+            // cannot read is invisible to nextIdBase, so its path can collide with a fresh draft. Same
+            // rule as spec_create: a path already occupied is a human's to look at, never overwritten.
+            // The whole cluster moves to `refused` — a partially-written chain only looks complete.
+            // Judged in the DRY RUN too (round-3): a preview that lists a cluster as drafted which the
+            // real run would refuse is a preview that lies.
+            const written = [];
+            for (const d of drafted) {
+                const clash = context.occupiedTarget(d.specs);
+                if (clash) {
+                    refused.push({ clusterKey: d.clusterKey, reason: `초안 목적지(${clash})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다. 사람이 확인해 옮기거나 고친 뒤 다시 실행하십시오.` });
+                    continue;
+                }
+                if (!dryRun) {
+                    try {
+                        for (const s of d.specs)
+                            await context.writeSpec(s);
+                    }
+                    catch (e) {
+                        if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                            refused.push({ clusterKey: d.clusterKey, reason: `초안 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다. 사람이 확인해 옮기거나 고친 뒤 다시 실행하십시오.` });
+                            continue;
+                        }
+                        throw e;
+                    }
+                }
+                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 };
+        },
+        /**
+         * Insert `@implements` anchors into source files. Dry-run by DEFAULT, and anchoring to a
+         * non-approved A-SPEC is refused — a reverse-engineered draft describes code; description does
+         * not confer approval.
+         */
+        async reverse_anchor(a) {
+            const specs = await context.listSpecs();
+            const approved = specs.filter((s) => s.type === 'A-SPEC' && s.status === 'approved').map((s) => s.id);
+            const plan = (0, anchor_1.planAnchors)(a.root, a.mapping ?? [], approved);
+            // @implements A-SPEC-182
+            // The third place the harness refuses over an unapproved A-SPEC. Enriched HERE rather than
+            // inside planAnchors, which is a pure planner holding only the approved-id list — this is the
+            // boundary that has the spec objects, so the planner stays testable without them.
+            const byId = new Map(specs.map((s) => [s.id, s]));
+            // ONE payload per distinct A-SPEC, on a sibling field — not appended to every refused entry.
+            // Review measured the first attempt, which memoized only the COMPUTATION: 149 files mapped to
+            // one draft A-SPEC still concatenated the same 361-character sentence 149 times, 48 KB of pure
+            // duplication in a single tool result. The comment claimed a property the code did not have,
+            // which is how it survived a round of review — hence the size assertion in the test.
+            const blockers = {};
+            for (const r of plan.refused) {
+                if (!/is not approved$/.test(r.reason) || blockers[r.aspec] !== undefined)
+                    continue;
+                const why = (0, approval_blockers_1.blockerSummary)(byId.get(r.aspec), (id) => byId.get(id) ?? null, r.aspec);
+                if (why)
+                    blockers[r.aspec] = why.trim();
+            }
+            const applied = (0, anchor_1.applyAnchors)(a.root, plan.edits, { dryRun: a.dryRun !== false });
+            return { ...plan, ...applied, blockers };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/entity-integration.d.ts

@@ -0,0 +1,100 @@
+import { type DerivedRebuild } from '../../spec/entity-integration-discharge';
+import { EntityIntegrationPlan } from '../../spec/entity-integration-transaction';
+export type IntegrationSealTransition = {
+    kind: 'spec-unsealed';
+    id: string;
+} | {
+    kind: 'spec-approved';
+    id: string;
+    digest: string;
+};
+/**
+ * @implements A-SPEC-635 — the seal transitions an integration performs, derived from its plan: every
+ * `unseal` step withdraws a seal, every `approve` step issues one whose digest is read from the
+ * published document bytes and must be that document's own `specDigest` (otherwise the seal is not
+ * what the transition policy computed → `audit-conflict`). Through the public tool a forged step is
+ * already refused `plan-changed` by step revalidation; this check is the audit's own invariant.
+ */
+/**
+ * @implements A-SPEC-645
+ * The `entity:`/`old-id:`/`new-id:` inputs for every mapping step whose record changes its display id,
+ * so an integration's renumbers are readable from the ledger like entity_renumber's. Without them the
+ * evidence consumers had no way to follow a document an integration renamed.
+ */
+export declare function renumberedMappingInputs(steps: ReadonlyArray<{
+    phase: string;
+    entityId?: string;
+    change: {
+        locator: string;
+        before: string | null;
+        after: string | null;
+    };
+}>, renames?: ReadonlyArray<{
+    entityId: string;
+    oldDisplayId: string;
+    newDisplayId: string;
+}>): string[];
+export declare function integrationSealTransitions(operation: EntityIntegrationPlan): IntegrationSealTransition[];
+export declare function createEntityIntegrationHandlers(context: {
+    storeRoot?: string;
+    rebuildFor?: (root: string) => DerivedRebuild;
+}): {
+    entity_integrate(a: {
+        root?: string;
+        operation?: string;
+        base?: string;
+        left?: string;
+        right?: string;
+        operationId?: string;
+        plan?: unknown;
+    }): Promise<{
+        ok: true;
+        state: "completed";
+        operationId: string;
+    } | {
+        ok: true;
+        state: "abandoned";
+        operationId: string;
+        restored: string[];
+        untouched: string[];
+        preserved: string[];
+    } | {
+        ok: true;
+        record: import("../../spec/entity-integration-discharge").DerivedDischargeRecord;
+        alreadyDischarged: boolean;
+    } | {
+        ok: boolean;
+        obligations: import("../../spec/entity-integration-discharge").DerivedObligationStatus[];
+        plan?: undefined;
+        target?: undefined;
+        executable?: undefined;
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        ok: boolean;
+        plan: import("../../spec/entity-integration-transaction").EntityIntegrationRecoveryInspection;
+        target: string;
+        executable: boolean;
+        obligations?: undefined;
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        blockers: string[];
+        target?: string | undefined;
+        plan?: EntityIntegrationPlan | undefined;
+        preview: import("../../spec/entity-integration-transaction").EntityIntegrationCandidate;
+        ok: boolean;
+        executable: boolean;
+        obligations?: undefined;
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        ok: boolean;
+        code: string;
+        reason: string;
+        obligations?: undefined;
+        plan?: undefined;
+        target?: undefined;
+        executable?: undefined;
+    }>;
+};