@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/mcp/tool-schemas.js

@@ -0,0 +1,394 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
+const spec_types_1 = require("../spec/spec-types");
+const phase_1 = require("../guardrail/phase");
+const str = (description) => ({ type: 'string', description });
+const num = (description) => ({ type: 'number', description });
+const strArray = (description) => ({ type: 'array', items: { type: 'string' }, description });
+// @implements A-SPEC-189 §10 (round 11) — this said "must equal `git rev-parse --show-toplevel`",
+// and A-SPEC-128 had already replaced `assertRepoTopLevel` with `resolveProjectRoot`: measured,
+// `phase_status` answers normally on a tree with no `.git` at all. The git top-level is required by
+// the CHANGE SOURCE when a range is supplied, not by the root argument — an advertisement that
+// demands more than the tool does sends callers looking for a repository they do not need.
+const ROOT = str('Absolute path to the project root (resolution anchors on the `.ax/` directory; a subdirectory resolves up to it). Version control is optional here — a supplied git range additionally requires the repository top-level.');
+/**
+ * A root that does NOT have to be a git repository. Resolution anchors on the `.ax/` marker, so a
+ * purely local project works; a git range, when one is supplied, still requires the top-level.
+ */
+const ROOT_ANY = str('Absolute path to the project root. Version control is optional — resolution anchors on the `.ax/` directory, and a subdirectory resolves up to it.');
+// Tools whose governance is enforced by hooks (PreToolUse phase/risk gates + the Stop-hook rtm/spec
+// gate) and which are therefore NOT advertised in tools/list by default — their schemas would tax
+// every session's context for no gain (benchmark: all schemas loaded, 0/143 ever invoked). They stay
+// callable by name. `HOLMES_MCP_PROFILE=full` re-advertises them.
+//
+// Lives here rather than in server.ts (A-SPEC-129 rev.2): server.ts connects a StdioServerTransport
+// at module scope, so anything importing it for this constant attaches to stdio. This module holds
+// the rest of the tool metadata and has no import side effects.
+exports.HOOK_ENFORCED_TOOLS = new Set(['phase_check', 'risk_check', 'rtm_check', 'spec_validate']);
+exports.TOOL_SCHEMAS = {
+    // @implements A-SPEC-156
+    // The full basis behind every other answer. It is a separate tool, not a field, because carrying
+    // the whole object on all responses is what REQ-122 forbids — the digest rides along, the detail
+    // is fetched only when a caller has seen two digests disagree.
+    basis_detail: {
+        description: 'The full basis behind this server\'s answers: which build it loaded, which build is on disk now, and fingerprints of the scan and spec corpus. Compare loadedBuild against diskBuild to see whether the running server predates the installed code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string', description: 'Absolute path to the project root. Optional — omit for build identity only.' },
+            },
+        },
+    },
+    spec_create: {
+        description: 'Create a new spec (.md) of the given kind with its required sections stubbed as TODO. Extra keys are stored as frontmatter.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: str('Spec kind, e.g. REQ | H-SPEC | A-SPEC | C-SPEC | T-SPEC.'),
+                // @implements A-SPEC-174
+                // The rule belongs HERE, where the caller reads it before choosing a value. Stating only an
+                // example left `REQ-1` looking reasonable, and the id is the filename — a wrong one costs
+                // the author the whole document. The guard in the handler is the backstop, not the teacher.
+                id: str('Spec id. The number must be at least 3 digits: REQ-001, H-SPEC-001, A-SPEC-001 '
+                    + '(A-SPEC may add a dot suffix for a sub-slice, e.g. A-SPEC-125.4). Shorter numbers are refused.'),
+                title: str('Human-readable spec title.'),
+                // The relation is GENERATED, not restated — a hand-written copy drifted and prose assertions
+                // could not detect it.
+                depends_on: strArray(`Ids of the PARENT specs. The kind is fixed: ${(0, spec_types_1.parentRuleText)()}. `
+                    + 'A parent that does not exist yet is fine; a parent of the wrong kind is refused.'),
+                // @implements A-SPEC-189 §6 — CONTROL arguments must be declared even where extra keys are
+                // data. `additionalProperties: true` exempts this tool from typo judgement (caller-wins
+                // frontmatter), so an undeclared `root` meant a misspelled `rot: /Users/<name>/…` was
+                // written into a git-shared document as frontmatter — a machine-local absolute path,
+                // silently, with no refusal. Declaring it makes the control surface visible; the data
+                // exemption stays for genuine frontmatter.
+                root: ROOT,
+            },
+            required: ['type', 'id', 'title'],
+            additionalProperties: true,
+        },
+    },
+    spec_validate: {
+        description: 'Validate a single spec by id against its kind rules and dependency chain; returns { ok, findings }.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: str('Id of the spec to validate.') },
+            required: ['id'],
+        },
+    },
+    spec_upgrade: {
+        description: 'Raise ONE named spec from an older format to the current one: declare `type:` (inferred from the id), preserve the previous status as `legacy_status`, and restart at `status: draft`. Does NOT confer approval, and never touches a document you did not name — there is no bulk path. Refuses a kind this tool does not have.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: str('Id of the spec to raise to the current format.') },
+            required: ['id'],
+        },
+    },
+    spec_approve: {
+        description: 'Approve a spec as a sealing ACT: confirm the ledger destination BEFORE sealing → validate (zero errors) → record approved_digest + parent_digests snapshots → status: approved (written only at the version this act read; a concurrent edit wins and the approval is refused for retry) → append spec-approved to the provenance ledger. Requires a valid out-of-band HOLMES_APPROVAL in the SERVER environment (fail-closed; nothing in the request can substitute). Refuses an unsealed approved parent — seal parents first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: str('Optional when the server is bound to a file store — the ledger location is derived from the store itself; if supplied it must resolve to the SAME project, otherwise the approval is refused before anything is written.'),
+                id: str('Id of the spec to approve and seal.'),
+            },
+            required: ['id'],
+        },
+    },
+    spec_list: {
+        description: `List all specs (id, type, status; plus parent when depends_on names one, and legacy: true when the status is outside the canonical ${spec_types_1.SPEC_STATUSES.join('|')} union — absence of legacy speaks only to the STATUS being canonical, not to governance), optionally filtered to a single kind.`,
+        inputSchema: {
+            type: 'object',
+            properties: { type: str('Optional spec kind to filter by (e.g. A-SPEC).') },
+        },
+    },
+    spec_next: {
+        description: 'Return the next spec kind in the pipeline that has no approved instance yet ({ next }).',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    citation_pin: {
+        description: "Compute and record the content digest (sha256) of a REQ's cited sources that resolve inside the repo, so a citation's rev is derived from what is actually on disk. Dry-run by default; never overwrites an existing digest.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                id: { type: 'string', description: 'REQ id whose citations should be pinned, e.g. REQ-126.' },
+                dryRun: { type: 'boolean', description: 'Default true — pass false to write the digests into the spec.' },
+            },
+            required: ['root', 'id'],
+        },
+    },
+    rtm_check: {
+        description: 'Check the governed spec set for RTM integrity (orphans, duplicate ids, dangling/wrong-kind @implements). With root, also checks code @implements anchors.',
+        inputSchema: {
+            type: 'object',
+            properties: { root: ROOT },
+        },
+    },
+    phase_status: {
+        description: 'Return every spec with its id/type/status (raw material for deriving phase via phase_check). '
+            + 'The corpus is the store this server is BOUND to; a root naming a different project is refused rather than answered '
+            + "with this server's specs (round-9: it was advertised, ignored, and answered success-shaped for someone else's root).",
+        inputSchema: {
+            type: 'object',
+            properties: { root: ROOT },
+        },
+    },
+    phase_check: {
+        description: 'Gate an edit against the No-Spec-No-Code phase machine for a target path; returns an allow/deny decision with remediation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: str('Repo-relative path of the file about to be written/edited.'),
+                action: {
+                    type: 'string',
+                    // The handler's own runtime list — a hand-copied literal here was a second truth that
+                    // drifts (round-3: two members deleted survived the suite while the wire falsely refused
+                    // actions phaseCheck accepts).
+                    enum: [...phase_1.ACTIONS],
+                    description: 'Optional pre-classified Action; omit to classify from `target`.',
+                },
+                targetAspecId: str('A-SPEC id this edit implements (e.g. A-SPEC-121.1).'),
+            },
+            required: ['target'],
+        },
+    },
+    cpg_scan: {
+        description: 'Scan the repository tree with tree-sitter across the 8 supported languages; returns { files, symbols } counts plus the skip report ({ skipped, skippedCount }) naming any claimed file the scan could not ingest — an empty report distinguishes a clean tree from one with casualties.',
+        inputSchema: {
+            type: 'object',
+            properties: { root: ROOT },
+            required: ['root'],
+        },
+    },
+    taint_scan: {
+        description: 'Call-graph taint REACHABILITY screen: source-named functions (getenv/argv/req.body/…) that reach sink-named functions (exec/eval/query/…) through call edges. Returns { kind:"call-reachability", limits, maxPaths, truncated, pairs } where each pair is a source→sink candidate call path. This is a SCREENING signal that routes a security review — NOT a data-flow proof and NOT a vulnerability verdict (no def-use, no sanitizers, name-based matching, call-edge-only, as the limits state).',
+        inputSchema: {
+            type: 'object',
+            properties: { root: ROOT },
+            required: ['root'],
+        },
+    },
+    test_run: {
+        description: 'Compute the intelligent regression scope, RUN the selected tier (jest or pytest), and record per-A-SPEC EXECUTION evidence. Scopes against a git range when given, otherwise against a baseline — so it works on a project with no version control. A passing run records the baseline the next run scopes against.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                base: str('Base rev (e.g. HEAD~1). Optional — omit to compare against a baseline.'),
+                head: str('Head rev (e.g. HEAD). Optional — omit to compare against a baseline.'),
+                since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'),
+                mark: str('Baseline label to record when the run passes (default `last-green`). Nothing is recorded for a red or skipped run.'),
+            },
+            required: ['root'],
+        },
+    },
+    issue_localize: {
+        description: 'N1 localization: free-text issue -> structured, ranked candidate locations (files+symbols+evidence) fusing CPG lexical match with the RTM spec link ({ terms, hits, matchedSpecs }).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                issue: str('Free-text issue/bug/task description to localize.'),
+                topN: num('Max ranked hits to return (default 10).'),
+            },
+            required: ['root', 'issue'],
+        },
+    },
+    rtm_impact: {
+        description: 'Given changed symbol qualified-names, return the impacted SPEC node ids reachable through @implements/depends_on edges ({ impacted }).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                changed: strArray('Changed symbol qualified-names (e.g. ["CpgScanner","CpgScanner.scan"]) — NOT file paths.'),
+            },
+            required: ['root', 'changed'],
+        },
+    },
+    rtm_reindex: {
+        description: 'Rebuild the RTM graph over base..head changes and exercise the incremental machinery; returns { changed, nodes, edges }.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                base: str('Base git ref of the diff range. Optional — omit to compare against a baseline.'),
+                head: str('Head git ref of the diff range. Optional — omit to compare against a baseline.'),
+                since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'),
+            },
+            required: ['root'],
+        },
+    },
+    context_bundle: {
+        description: 'Assemble a JIT context bundle rooted at a seed node id within a token budget (graph-scoped spec+code slice).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT,
+                seedId: str('Seed node id to expand from, e.g. SPEC:A-SPEC-121.1 or CODE:CpgScanner@src/holmes/cpg/cpg-scanner.ts.'),
+                budget: num('Token budget for the assembled bundle.'),
+            },
+            required: ['root', 'seedId', 'budget'],
+        },
+    },
+    review_scope: {
+        description: 'Compute the graph-scoped review scope for base..head (impacted specs/tests + unscanned changed files).',
+        inputSchema: {
+            type: 'object',
+            properties: { root: ROOT_ANY, base: str('Base git ref. Optional — omit to compare against a baseline instead.'), head: str('Head git ref. Optional — omit to compare against a baseline instead.'), since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'), },
+            required: ['root'],
+        },
+    },
+    review_prepare: {
+        description: 'Assemble the full review package for base..head within a token budget ({ package, unscannedChangedFiles }).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                base: str('Base git ref. Optional — omit to compare against a baseline instead.'),
+                head: str('Head git ref. Optional — omit to compare against a baseline instead.'),
+                since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'),
+                budget: num('Optional token budget for the review package (default 4000).'),
+            },
+            required: ['root'],
+        },
+    },
+    review_record: {
+        description: 'Append review findings to the findings ledger; severities must be critical|important|minor and statuses open|resolved.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT,
+                findings: {
+                    type: 'array',
+                    description: 'Findings to record.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: str('Finding id.'),
+                            severity: { type: 'string', enum: ['critical', 'important', 'minor'], description: 'Finding severity.' },
+                            status: { type: 'string', enum: ['open', 'resolved'], description: 'Finding status.' },
+                            // 'summary' matches what the ledger actually persists — the advertised 'message'
+                            // was silently DROPPED by the serializer's whitelist, so clients following the ad
+                            // lost their text (round-2 finding; same schema-vs-handler class as phase_check).
+                            summary: str('Finding description — persisted to the ledger and quoted by ART-7 violations.'),
+                            category: str('Finding category (e.g. correctness, security) — persisted to the ledger; round-5: it was persisted but never advertised, so ad-following clients wrote category-less audit lines.'),
+                            // Round-9: the same defect class as `category`, two keys further — both survive the
+                            // ledger whitelist, neither was advertised, so ad-following clients wrote findings
+                            // that could not be located.
+                            file: str('File the finding is in — persisted to the ledger.'),
+                            specRef: str('Spec id the finding is about — persisted to the ledger.'),
+                        },
+                        required: ['id', 'severity', 'status'],
+                    },
+                },
+            },
+            required: ['root', 'findings'],
+        },
+    },
+    review_status: {
+        description: 'Summarize open findings by severity and whether the review is blocked ({ blocked, open }).',
+        inputSchema: {
+            type: 'object',
+            properties: { root: ROOT },
+            required: ['root'],
+        },
+    },
+    // @implements A-SPEC-126
+    reverse_scan: {
+        description: 'Brownfield inventory: scan a legacy target read-only and return candidate A-SPEC clusters, cohesion evidence, and an honest coverage report (unresolved wiring, uncalibrated languages). Writes nothing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: str('Absolute path to the target repository root. Unlike the other tools this need not be a git repository — a non-git tree is scanned whole and reported as isGit:false.'),
+                maxFlagged: num('Cap on the listed dynamic-wiring files (default 50). Counts stay complete.'),
+            },
+            required: ['root'],
+        },
+    },
+    reverse_draft: {
+        description: "Draft H-SPEC/A-SPEC/T-SPEC documents for the recovered clusters under an EXISTING parent REQ. Refuses without one — a REQ states business intent, which is not in the code. Everything is emitted as status:draft; dry-run by default. Documents land in the SERVER's spec store (HOLMES_SPECS, default .ax/specs), which is the target's own store only when the server runs inside it.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: str('Absolute path to the target repository root.'),
+                parentReqId: str('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 (e.g. REQ-126). No code path creates a REQ.'),
+                cluster: str('Optional cluster key (its directory, or the file itself for a per-file split) to draft only that slice.'),
+                dryRun: { type: 'boolean', description: 'Default true — pass false to write the drafted documents into the spec store.' },
+            },
+            required: ['root', 'parentReqId'],
+        },
+    },
+    reverse_anchor: {
+        description: 'Insert `@implements` anchors into source files for a file→A-SPEC mapping. Dry-run by default; anchoring to a non-approved A-SPEC is refused.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: str('Absolute path to the target repository root.'),
+                mapping: {
+                    type: 'array',
+                    description: 'File→A-SPEC pairs to anchor.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            file: str('Repo-root-relative POSIX path of the file to anchor.'),
+                            aspec: str('Target A-SPEC id. Must be approved.'),
+                        },
+                        required: ['file', 'aspec'],
+                    },
+                },
+                dryRun: { type: 'boolean', description: 'Default true — pass false to actually write the anchors.' },
+            },
+            required: ['root', 'mapping'],
+        },
+    },
+    risk_check: {
+        description: 'Assess a risk Action, apply the graded HITL gate, and record a DecisionLedger entry; returns { assessment, gate }.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'object',
+                    description: 'The action to assess.',
+                    properties: {
+                        kind: str('Action kind, e.g. shell | file.'),
+                        target: str('Action target (e.g. the shell command string or file path).'),
+                        command: str('Full shell command, when kind is shell.'),
+                    },
+                    required: ['kind', 'target'],
+                },
+                ts: str('ISO-8601 timestamp for the DecisionLedger entry.'),
+                root: ROOT_ANY,
+                changedSymbols: strArray('Optional changed symbol qualified-names, to compute a blast-radius axis via impact analysis.'),
+                // @implements A-SPEC-189 §6 — the ad declared {actor, rationale}, but the gate requires
+                // `token` too (isValidApproval): an approval built exactly as advertised was IGNORED in
+                // silence, and the caller read the resulting block as a policy decision. The ad now names
+                // every field the gate reads, and says which ones narrow it.
+                approval: {
+                    type: 'object',
+                    description: 'Optional out-of-band approval token (never settable from AI/tool-input). '
+                        + 'actor, token and rationale are ALL required for the gate to honor it; scope/expires/nonce narrow it '
+                        + '(scope entries are {kind, pattern} full-match, expires is an ISO instant, nonce makes it single-use).',
+                    properties: {
+                        actor: str('Approving actor.'),
+                        token: str('Approval token — REQUIRED; an approval without it is ignored by the gate.'),
+                        rationale: str('Approval rationale.'),
+                        expires: str('Optional ISO instant after which the approval is refused (unparseable values fail closed).'),
+                        nonce: str('Optional single-use marker — spent once, then refused like an absent approval. A blank value is refused.'),
+                        scope: {
+                            type: 'array',
+                            description: 'Optional narrowing: the approval covers only these {kind, pattern} entries (full match; trailing "/" is a directory prefix).',
+                            items: { type: 'object', properties: { kind: str('Action kind, or "*".'), pattern: str('Target pattern; "*" is a wildcard run.') }, required: ['kind', 'pattern'] },
+                        },
+                    },
+                    required: ['actor', 'token', 'rationale'],
+                },
+                enforcement: { ...str('Optional enforcement mode override.'), enum: ['block', 'warn', 'off'] },
+                actor: str('Actor attributed in the ledger entry.'),
+                rationale: str('Rationale attributed in the ledger entry.'),
+            },
+            required: ['action', 'ts'],
+        },
+    },
+};