@adrkit/mcp 0.2.0 → 0.2.1

package/README.md

@@ -1,22 +1,126 @@
 # `@adrkit/mcp`
 
-A **local, read-only** [Model Context Protocol](https://modelcontextprotocol.io)
-server that exposes adrkit decision retrieval over stdio. It lets an agent harness
-ask "has this been decided?", "what governs these files?", and "what replaced this?"
-against one Git-backed ADR corpus — deterministically, offline, with no model,
-network, or write access.
+**Deterministic, offline, read-only decision memory for coding agents — including
+the decisions you already rejected.**
 
-> Part of [adrkit](https://adrkit.dev). The corpus lives in git as one Markdown
-> file per decision with typed YAML frontmatter (`@adrkit/core`); this server only
-> reads it.
+A local [Model Context Protocol](https://modelcontextprotocol.io) server that lets
+an agent harness query one Git-backed ADR (Architecture Decision Record) corpus
+over stdio: *"has this been decided?"*, *"what governs these files?"*, and *"what
+replaced this?"* It surfaces **superseded and rejected** decisions specifically so
+agents stop re-proposing paths the team already ruled out.
 
-## Install and run
+> **No model calls. No network calls. No writes.** The server reads Markdown files
+> from your repo and returns structured JSON. It never calls an LLM, never opens a
+> socket, and never mutates your corpus. Every tool is annotated
+> `readOnlyHint: true`, `openWorldHint: false`.
+
+Part of [adrkit](https://adrkit.dev). The corpus lives in git as one Markdown file
+per decision with typed YAML frontmatter (`@adrkit/core`); this server only reads
+it. Registry namespace: **`dev.adrkit/mcp`** (this is the Node/npm `@adrkit/mcp`
+package — unrelated to the `adr-kit` Python package on PyPI).
+
+## Maturity
+
+adrkit is **early**. Phases 0–6 are *landed / reference-verified* against
+[ADR-0014](https://github.com/mbeacom/adrkit/blob/main/docs/adr/0014-stage-phase-landing-evidence-across-a-three-rung-validation-ladder.md)
+rungs 1–2 (unit/contract/conformance plus maintainer-owned isolated
+reference-repository validation). It has **no external adopters or production users
+yet**, and rung-3 external/community validation is openly tracked as not-yet-met.
+The 4-tool surface is locked by a
+[surface test](https://github.com/mbeacom/adrkit/blob/main/packages/mcp/test/surface.test.ts).
+
+## Quick start
+
+The published binary is **`adrkit-mcp`**. Run it with `npx` (no install):
 
 ```sh
-bunx @adrkit/mcp                       # run the adrkit-mcp bin
-adrkit-mcp --cwd /path/to/repo --dir docs/adr
+npx -y @adrkit/mcp --cwd /path/to/your/repo --dir docs/adr
+```
+
+It speaks JSON-RPC over stdio, so you normally point an MCP client at it rather than
+running it by hand. Copy-pasteable client configs follow.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`). Claude launches
+servers from an arbitrary working directory, so set `ADRKIT_MCP_CWD` to your repo's
+absolute path:
+
+```json
+{
+  "mcpServers": {
+    "adrkit": {
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp"],
+      "env": {
+        "ADRKIT_MCP_CWD": "/absolute/path/to/your/repo",
+        "ADRKIT_MCP_DIR": "docs/adr"
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+Create `.vscode/mcp.json` in your workspace (VS Code uses the `servers` key and
+substitutes `${workspaceFolder}`):
+
+```json
+{
+  "servers": {
+    "adrkit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp", "--cwd", "${workspaceFolder}", "--dir", "docs/adr"]
+    }
+  }
+}
 ```
 
+### Cursor
+
+Create `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "adrkit": {
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp"],
+      "env": {
+        "ADRKIT_MCP_CWD": "/absolute/path/to/your/repo",
+        "ADRKIT_MCP_DIR": "docs/adr"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot CLI
+
+Add to `~/.copilot/mcp-config.json` (user-level) or `./.copilot/mcp-config.json`
+(per-repo). Copilot CLI runs servers from the trusted repo directory, so the default
+`cwd` usually resolves correctly:
+
+```json
+{
+  "mcpServers": {
+    "adrkit": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp", "--dir", "docs/adr"],
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+You can also add it interactively with `/mcp add` inside a `copilot` session.
+
+### Configuration reference
+
 | Option | Env | Default | Meaning |
 |---|---|---|---|
 | `--cwd <path>` | `ADRKIT_MCP_CWD` | `process.cwd()` | Repository root; must canonicalize to a directory containing a readable `.git` entry (a normal clone or a linked-worktree `.git` file). |
@@ -27,6 +131,148 @@ configuration exits non-zero with a diagnostic on **stderr** (`2` for an
 unparseable flag, `1` for an invalid root/directory) and never starts a transport.
 **stdout is reserved for JSON-RPC protocol frames only.**
 
+## The four tools
+
+Exactly four tools, all read-only. Each shares fixed annotations
+(`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`,
+`openWorldHint: false`), returns a deterministic human-readable summary line in
+`content[0].text`, and carries a `findings` page with the corpus's own
+parse/validation findings. Every substantive response also includes a
+`corpusHealth` sibling: `{ fingerprint, recordCount, excludedCount }`.
+
+Shapes below are the real input/output contracts (see
+[`packages/mcp/src/tools`](https://github.com/mbeacom/adrkit/tree/main/packages/mcp/src/tools)).
+Each tool's structured output is `{ corpusHealth?, result }`; the objects shown
+under "output" are the members of that discriminated `result` union (keyed on
+`outcome`). `findings` and every growing array are cursor-paginated (see
+[Pagination](#pagination-and-cursor-restart)); `findings` and repeated pagination
+fields are elided here for brevity.
+
+### `search_decisions`
+
+Normalized literal substring search over id, title, tags, and body (the graveyard of
+superseded/rejected records is included by default). Filters are ANDed:
+`status`/`scope` match any-of; `tags` matches all-of.
+
+```jsonc
+// input
+{
+  "query": "postgres",          // required, 1–256 code units, non-empty after trim
+  "status": ["accepted"],        // optional, ≤6, any-of
+  "tags": ["database"],          // optional, ≤32 tags × ≤64 chars, all-of
+  "scope": ["backend"]           // optional, ≤3, any-of
+}
+// output → single "results" branch (empty results use the same branch)
+{
+  "outcome": "results",
+  "items": [
+    {
+      "id": "0007",
+      "title": "Adopt Postgres",
+      "status": "accepted",
+      "sourcePath": "docs/adr/0007-adopt-postgres.md",
+      "matchedFields": ["title", "body"]   // subset of id | title | tag | body
+    }
+  ],
+  "cursor": null
+}
+```
+
+### `get_decision`
+
+The complete typed frontmatter + body for one ref.
+
+```jsonc
+// input
+{ "ref": "0007" }               // AdrRef, 1–128 chars (local id, or a "log:id" federated ref)
+// output → discriminated on "outcome"
+// found (the full record is nested under "decision"):
+{
+  "outcome": "found",
+  "decision": {
+    "requestedRef": "0007",
+    "id": "0007",
+    "title": "Adopt Postgres",
+    "status": "accepted",
+    "sourcePath": "docs/adr/0007-adopt-postgres.md",
+    "frontmatter": { /* typed YAML: status, tags, affects, relations, ... */ },
+    "body": "## Context\n..."
+  }
+}
+// other outcomes:
+// { "outcome": "not-found", "requestedRef": "9999" }
+// { "outcome": "ambiguous-local-id", "requestedRef": "0007", "candidates": [ /* DecisionSummary[] */ ] }
+// { "outcome": "federated-log-unavailable", "requestedRef": "core:12", "log": "core", "id": "12" }
+```
+
+A `log:id` federated ref is recognized but **never resolved or substituted** — this
+server reads exactly one local corpus.
+
+### `get_decision_context`
+
+Governing / active-proposal / historical decisions for repo-relative `files[]`, via
+each record's own `affects` matchers. **Paths are compared against patterns only —
+never opened.**
+
+```jsonc
+// input
+{
+  "files": ["src/db/pool.ts", "src/db/schema.sql"]
+  // 1–256 entries; each POSIX, 1–1024 chars; no leading "/", no "..", no drive, no "\"
+}
+// output → single "matches" branch (all three arrays; empty is the same branch)
+{
+  "outcome": "matches",
+  "governing": [
+    {
+      "id": "0007",
+      "title": "Adopt Postgres",
+      "status": "accepted",
+      "sourcePath": "docs/adr/0007-adopt-postgres.md",
+      "firedMatchers": [ { "type": "path", "pattern": "src/db/**" } ],
+      "relations": { "supersedes": [], "supersededBy": null, "relatesTo": [], "conflictsWith": [] }
+    }
+  ],
+  "activeProposals": [],
+  "history": []
+}
+```
+
+### `list_superseded`
+
+Every superseded record with its **direct** local replacement state — the tool that
+keeps agents from re-proposing rejected paths.
+
+```jsonc
+// input (pagination only)
+{}
+// output → single "entries" branch
+{
+  "outcome": "entries",
+  "items": [
+    {
+      "id": "0003",
+      "title": "Use MySQL",
+      "status": "superseded",
+      "sourcePath": "docs/adr/0003-use-mysql.md",
+      "supersededBy": {            // one of four states:
+        "resolved": true,
+        "target": { "id": "0007", "title": "Adopt Postgres", "status": "accepted", "sourcePath": "docs/adr/0007-adopt-postgres.md" }
+      }
+      // unresolved states:
+      //   { "resolved": false, "targetRef": "0099", "reason": "dangling" }
+      //   { "resolved": false, "targetRef": "0007", "reason": "ambiguous", "candidateCount": 2 }
+      //   { "resolved": false, "targetRef": "core:1", "reason": "federated-unavailable", "log": "core", "id": "1" }
+    }
+  ],
+  "cursor": null
+}
+```
+
+Relation refs (`supersedes`, `supersededBy`, `relatesTo`, `conflictsWith`) are
+surfaced verbatim and never expanded — follow them with a second `get_decision`
+call. Supersession is reported one hop deep; there is no transitive traversal.
+
 ## Library surface
 
 The package root exports only a sealed lifecycle factory. There is no way to reach
@@ -44,24 +290,6 @@ await server.close();
 `createAdrkitMcpServer(options?)` performs no filesystem access at construction and
 returns a frozen, null-prototype handle with exactly `start()` and `close()`.
 
-## The four tools
-
-All four share fixed annotations (`readOnlyHint: true`, `destructiveHint: false`,
-`idempotentHint: true`, `openWorldHint: false`), a `corpusHealth`
-(`fingerprint`/`recordCount`/`excludedCount`) sibling on every substantive
-response, and a `findings` page carrying the corpus's own parse/validation findings.
-
-| Tool | Answers | Notable outcomes |
-|---|---|---|
-| `search_decisions` | Normalized literal substring search over id, title, tags, and body (graveyard included by default). Filters: `status`/`scope` (any-of), `tags` (all-of), ANDed. | `results` (empty is the same branch) |
-| `get_decision` | The complete typed frontmatter + body for one ref. | `found`, `not-found`, `ambiguous-local-id` (duplicate ids), `federated-log-unavailable` (a `log:id` ref is recognized, never resolved or substituted) |
-| `get_decision_context` | Governing / active-proposal / historical decisions for repo-relative `files[]`, via the corpus's own `affects` matchers. Paths are compared against patterns only — never opened. | `matches` (all three arrays; empty is the same branch) |
-| `list_superseded` | Every superseded record with its **direct** local replacement state. | `entries` with `resolved` / `dangling` / `ambiguous` (`candidateCount` only) / `federated-unavailable` targets |
-
-Relation refs (`supersedes`, `supersededBy`, `relatesTo`, `conflictsWith`) are
-surfaced verbatim and never expanded — follow them with a second `get_decision`
-call.
-
 ## Limits
 
 `query` 1–256 code units (non-empty after trimming); `ref` 1–128; `files[]` 1–256
@@ -80,7 +308,8 @@ an unchanged corpus; otherwise the response is a non-error `invalid-cursor` outc
 (`corpus-changed`, `query-mismatch`, `wrong-channel`, `offset-out-of-range`,
 `cursor-not-applicable`, `version-unsupported`, or `decode-failed`) and you should
 restart the walk from no cursor. The primary-result and `findings` channels page
-independently.
+independently. A `corpus-unavailable` outcome is returned when the ADR directory
+cannot be read.
 
 ## Boundaries (out of scope by design)
 

package/dist/bin.js

@@ -8,15 +8,13 @@ import { resolve as resolve2 } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/corpus/ordering.ts
-function compareCodeUnits(a, b) {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-function compareFindings(a, b) {
-  return compareCodeUnits(a.rule, b.rule) || compareCodeUnits(a.id ?? "", b.id ?? "") || compareCodeUnits(a.pattern ?? "", b.pattern ?? "") || compareCodeUnits(a.path ?? "", b.path ?? "") || compareCodeUnits(a.field ?? "", b.field ?? "") || compareCodeUnits(a.message, b.message);
-}
-function sortFindingsCanonical(findings) {
-  return [...findings].sort(compareFindings);
-}
+import {
+  compareByIdThenPath,
+  compareCodeUnits,
+  compareFindings,
+  sortByIdThenPath,
+  sortFindingsCanonical
+} from "@adrkit/core";
 
 // src/search/normalize.ts
 function normalize(value) {
@@ -107,9 +105,13 @@ import { AdrFrontmatter, AdrRef, Status, Scope } from "@adrkit/core";
 
 // src/corpus/projection.ts
 import { access, constants as FS, lstat, realpath, stat } from "node:fs/promises";
-import { createHash as createHash2 } from "node:crypto";
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { discoverAdrFiles, lintCorpus, normalizeDisplayPath } from "@adrkit/core";
+import {
+  discoverAdrFiles,
+  fingerprintOf,
+  lintCorpus,
+  normalizeDisplayPath
+} from "@adrkit/core";
 var MAX_SOURCE_BYTES = 64 * 1024;
 
 class CorpusUnavailableError extends Error {
@@ -207,29 +209,6 @@ async function verifyRoots(options) {
     fail("root-not-found");
   return roots;
 }
-function canonicalStringify(value) {
-  if (value === null || value === undefined)
-    return "null";
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "string") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value))
-    return `[${value.map(canonicalStringify).join(",")}]`;
-  if (typeof value === "object") {
-    const record = value;
-    const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort(compareCodeUnits);
-    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`).join(",")}}`;
-  }
-  return "null";
-}
-function fingerprintOf(records, corpusFindings, recordCount, excludedCount) {
-  const projection = {
-    records: records.map((record) => ({ sourcePath: record.path, frontmatter: record.frontmatter, body: record.body })),
-    corpusFindings,
-    corpusHealth: { recordCount, excludedCount }
-  };
-  return createHash2("sha256").update(canonicalStringify(projection), "utf8").digest("hex");
-}
 async function loadCorpusProjection(options) {
   const roots = await verifyRoots(options);
   let candidates;
@@ -845,13 +824,9 @@ function registerGetDecision(server, config) {
 }
 
 // src/tools/get-decision-context.ts
-import { resolveAffects } from "@adrkit/core";
+import { decisionBucketFor, resolveAffects } from "@adrkit/core";
 function bucketFor(status) {
-  if (status === "accepted")
-    return "governing";
-  if (status === "draft" || status === "proposed")
-    return "activeProposals";
-  return "history";
+  return decisionBucketFor(status);
 }
 function contextEntry(record, firedMatchers) {
   return { ...toSummary(record), firedMatchers, relations: toRelationRefs(record.frontmatter) };
@@ -1018,7 +993,7 @@ function registerListSuperseded(server, config) {
 }
 
 // src/server.ts
-var SERVER_INFO = { name: "@adrkit/mcp", version: "0.1.0" };
+var SERVER_INFO = { name: "@adrkit/mcp", version: "0.2.1" };
 function buildRegisteredServer(config) {
   const server = new McpServer(SERVER_INFO);
   registerSearchDecisions(server, config);

package/dist/corpus/ordering.d.ts

@@ -1,17 +1,8 @@
 /**
- * @adrkit/mcp — the one locale-independent comparator and the canonical orderings
- * every channel uses. Never `String.prototype.localeCompare` (research §R6).
+ * @adrkit/mcp — re-export shim.
+ *
+ * The comparator and canonical orderings were promoted to `@adrkit/core`
+ * (`packages/core/src/ordering/index.ts`). This module preserves every existing
+ * `../corpus/ordering` import site while the single implementation now lives in core.
  */
-import type { Finding } from '@adrkit/core';
-/** The sole code-unit comparator: `a < b ? -1 : a > b ? 1 : 0` over UTF-16 units. */
-export declare function compareCodeUnits(a: string, b: string): number;
-export interface OrderedSummary {
-    readonly id: string;
-    readonly sourcePath: string;
-}
-/** Canonical `(id, sourcePath)` ascending order; sourcePath is the unique tiebreak. */
-export declare function compareByIdThenPath(a: OrderedSummary, b: OrderedSummary): number;
-/** Canonical finding order using `sortFindings`' field tuple with the code-unit comparator. */
-export declare function compareFindings(a: Finding, b: Finding): number;
-export declare function sortFindingsCanonical(findings: readonly Finding[]): Finding[];
-export declare function sortByIdThenPath<T extends OrderedSummary>(items: readonly T[]): T[];
+export { compareByIdThenPath, compareCodeUnits, compareFindings, sortByIdThenPath, sortFindingsCanonical, type OrderedSummary, } from '@adrkit/core';

package/dist/index.js

@@ -6,15 +6,13 @@ import { resolve as resolve2 } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/corpus/ordering.ts
-function compareCodeUnits(a, b) {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-function compareFindings(a, b) {
-  return compareCodeUnits(a.rule, b.rule) || compareCodeUnits(a.id ?? "", b.id ?? "") || compareCodeUnits(a.pattern ?? "", b.pattern ?? "") || compareCodeUnits(a.path ?? "", b.path ?? "") || compareCodeUnits(a.field ?? "", b.field ?? "") || compareCodeUnits(a.message, b.message);
-}
-function sortFindingsCanonical(findings) {
-  return [...findings].sort(compareFindings);
-}
+import {
+  compareByIdThenPath,
+  compareCodeUnits,
+  compareFindings,
+  sortByIdThenPath,
+  sortFindingsCanonical
+} from "@adrkit/core";
 
 // src/search/normalize.ts
 function normalize(value) {
@@ -105,9 +103,13 @@ import { AdrFrontmatter, AdrRef, Status, Scope } from "@adrkit/core";
 
 // src/corpus/projection.ts
 import { access, constants as FS, lstat, realpath, stat } from "node:fs/promises";
-import { createHash as createHash2 } from "node:crypto";
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { discoverAdrFiles, lintCorpus, normalizeDisplayPath } from "@adrkit/core";
+import {
+  discoverAdrFiles,
+  fingerprintOf,
+  lintCorpus,
+  normalizeDisplayPath
+} from "@adrkit/core";
 var MAX_SOURCE_BYTES = 64 * 1024;
 
 class CorpusUnavailableError extends Error {
@@ -205,29 +207,6 @@ async function verifyRoots(options) {
     fail("root-not-found");
   return roots;
 }
-function canonicalStringify(value) {
-  if (value === null || value === undefined)
-    return "null";
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "string") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value))
-    return `[${value.map(canonicalStringify).join(",")}]`;
-  if (typeof value === "object") {
-    const record = value;
-    const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort(compareCodeUnits);
-    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`).join(",")}}`;
-  }
-  return "null";
-}
-function fingerprintOf(records, corpusFindings, recordCount, excludedCount) {
-  const projection = {
-    records: records.map((record) => ({ sourcePath: record.path, frontmatter: record.frontmatter, body: record.body })),
-    corpusFindings,
-    corpusHealth: { recordCount, excludedCount }
-  };
-  return createHash2("sha256").update(canonicalStringify(projection), "utf8").digest("hex");
-}
 async function loadCorpusProjection(options) {
   const roots = await verifyRoots(options);
   let candidates;
@@ -843,13 +822,9 @@ function registerGetDecision(server, config) {
 }
 
 // src/tools/get-decision-context.ts
-import { resolveAffects } from "@adrkit/core";
+import { decisionBucketFor, resolveAffects } from "@adrkit/core";
 function bucketFor(status) {
-  if (status === "accepted")
-    return "governing";
-  if (status === "draft" || status === "proposed")
-    return "activeProposals";
-  return "history";
+  return decisionBucketFor(status);
 }
 function contextEntry(record, firedMatchers) {
   return { ...toSummary(record), firedMatchers, relations: toRelationRefs(record.frontmatter) };
@@ -1016,7 +991,7 @@ function registerListSuperseded(server, config) {
 }
 
 // src/server.ts
-var SERVER_INFO = { name: "@adrkit/mcp", version: "0.1.0" };
+var SERVER_INFO = { name: "@adrkit/mcp", version: "0.2.1" };
 function buildRegisteredServer(config) {
   const server = new McpServer(SERVER_INFO);
   registerSearchDecisions(server, config);

package/dist/server.d.ts

@@ -10,7 +10,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ToolConfig } from './tools/shared.js';
 export declare const SERVER_INFO: {
     readonly name: "@adrkit/mcp";
-    readonly version: "0.1.0";
+    readonly version: "0.2.1";
 };
 /** Package-internal: build the concrete server with exactly the four ratified tools. */
 export declare function buildRegisteredServer(config: ToolConfig): McpServer;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@adrkit/mcp",
-  "version": "0.2.0",
+  "mcpName": "dev.adrkit/mcp",
+  "version": "0.2.1",
   "description": "Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.",
   "type": "module",
   "license": "Apache-2.0",
@@ -44,7 +45,7 @@
     "typecheck": "tsc --noEmit --customConditions bun --project ../../tsconfig.json"
   },
   "dependencies": {
-    "@adrkit/core": "0.2.0",
+    "@adrkit/core": "0.2.1",
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4"
   },

package/src/corpus/ordering.ts

@@ -1,41 +1,16 @@
 /**
- * @adrkit/mcp — the one locale-independent comparator and the canonical orderings
- * every channel uses. Never `String.prototype.localeCompare` (research §R6).
+ * @adrkit/mcp — re-export shim.
+ *
+ * The comparator and canonical orderings were promoted to `@adrkit/core`
+ * (`packages/core/src/ordering/index.ts`). This module preserves every existing
+ * `../corpus/ordering` import site while the single implementation now lives in core.
  */
 
-import type { Finding } from '@adrkit/core';
-
-/** The sole code-unit comparator: `a < b ? -1 : a > b ? 1 : 0` over UTF-16 units. */
-export function compareCodeUnits(a: string, b: string): number {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-
-export interface OrderedSummary {
-  readonly id: string;
-  readonly sourcePath: string;
-}
-
-/** Canonical `(id, sourcePath)` ascending order; sourcePath is the unique tiebreak. */
-export function compareByIdThenPath(a: OrderedSummary, b: OrderedSummary): number {
-  return compareCodeUnits(a.id, b.id) || compareCodeUnits(a.sourcePath, b.sourcePath);
-}
-
-/** Canonical finding order using `sortFindings`' field tuple with the code-unit comparator. */
-export function compareFindings(a: Finding, b: Finding): number {
-  return (
-    compareCodeUnits(a.rule, b.rule) ||
-    compareCodeUnits(a.id ?? '', b.id ?? '') ||
-    compareCodeUnits(a.pattern ?? '', b.pattern ?? '') ||
-    compareCodeUnits(a.path ?? '', b.path ?? '') ||
-    compareCodeUnits(a.field ?? '', b.field ?? '') ||
-    compareCodeUnits(a.message, b.message)
-  );
-}
-
-export function sortFindingsCanonical(findings: readonly Finding[]): Finding[] {
-  return [...findings].sort(compareFindings);
-}
-
-export function sortByIdThenPath<T extends OrderedSummary>(items: readonly T[]): T[] {
-  return [...items].sort(compareByIdThenPath);
-}
+export {
+  compareByIdThenPath,
+  compareCodeUnits,
+  compareFindings,
+  sortByIdThenPath,
+  sortFindingsCanonical,
+  type OrderedSummary,
+} from '@adrkit/core';

package/src/corpus/projection.ts

@@ -8,9 +8,15 @@
  */
 
 import { access, constants as FS, lstat, realpath, stat } from 'node:fs/promises';
-import { createHash } from 'node:crypto';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
-import { discoverAdrFiles, lintCorpus, normalizeDisplayPath, type Adr, type Finding } from '@adrkit/core';
+import {
+  discoverAdrFiles,
+  fingerprintOf,
+  lintCorpus,
+  normalizeDisplayPath,
+  type Adr,
+  type Finding,
+} from '@adrkit/core';
 import { compareCodeUnits, sortFindingsCanonical } from './ordering.ts';
 
 export const MAX_SOURCE_BYTES = 64 * 1024;
@@ -169,31 +175,6 @@ async function verifyRoots(options: LoadCorpusProjectionOptions): Promise<Canoni
   return roots;
 }
 
-function canonicalStringify(value: unknown): string {
-  if (value === null || value === undefined) return 'null';
-  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'string') {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) return `[${value.map(canonicalStringify).join(',')}]`;
-  if (typeof value === 'object') {
-    const record = value as Record<string, unknown>;
-    const keys = Object.keys(record)
-      .filter((key) => record[key] !== undefined)
-      .sort(compareCodeUnits);
-    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`).join(',')}}`;
-  }
-  return 'null';
-}
-
-function fingerprintOf(records: readonly Adr[], corpusFindings: readonly Finding[], recordCount: number, excludedCount: number): string {
-  const projection = {
-    records: records.map((record) => ({ sourcePath: record.path, frontmatter: record.frontmatter, body: record.body })),
-    corpusFindings,
-    corpusHealth: { recordCount, excludedCount },
-  };
-  return createHash('sha256').update(canonicalStringify(projection), 'utf8').digest('hex');
-}
-
 /** The one entry point every tool handler calls, fresh, at the start of its execution. */
 export async function loadCorpusProjection(options: LoadCorpusProjectionOptions): Promise<CorpusProjection> {
   const roots = await verifyRoots(options);

package/src/server.ts

@@ -14,7 +14,7 @@ import { registerGetDecisionContext } from './tools/get-decision-context.ts';
 import { registerListSuperseded } from './tools/list-superseded.ts';
 import type { ToolConfig } from './tools/shared.ts';
 
-export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.1.0' } as const;
+export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.2.1' } as const;
 
 /** Package-internal: build the concrete server with exactly the four ratified tools. */
 export function buildRegisteredServer(config: ToolConfig): McpServer {

package/src/tools/get-decision-context.ts

@@ -8,7 +8,7 @@
  */
 
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { resolveAffects, type Adr, type Finding, type FiredMatcher } from '@adrkit/core';
+import { decisionBucketFor, resolveAffects, type Adr, type Finding, type FiredMatcher } from '@adrkit/core';
 import { compareCodeUnits, sortFindingsCanonical } from '../corpus/ordering.ts';
 import { paginate, queryShapeHash } from '../pagination/cursor.ts';
 import {
@@ -37,10 +37,12 @@ interface GetDecisionContextArgs {
 
 type Bucket = 'governing' | 'activeProposals' | 'history';
 
+/**
+ * Delegates to `@adrkit/core`'s `decisionBucketFor` so this tool and the CLI/Action
+ * cannot drift apart on what counts as governing (#39).
+ */
 function bucketFor(status: string): Bucket {
-  if (status === 'accepted') return 'governing';
-  if (status === 'draft' || status === 'proposed') return 'activeProposals';
-  return 'history';
+  return decisionBucketFor(status);
 }
 
 function contextEntry(record: Adr, firedMatchers: readonly FiredMatcher[]): ContextEntry {