pattern-mcp 0.5.0 → 0.6.0

package/README.md

@@ -32,7 +32,7 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes seven tools:
+It exposes eight tools:
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
@@ -57,6 +57,10 @@ It exposes seven tools:
 - `check_ledger_liveness` — checks whether a ledger entry's recorded
   `file_path` still exists and still references its `chosen_candidate` --
   see [Tool: `check_ledger_liveness`](#tool-check_ledger_liveness).
+- `export_ledger_provenance` — formats one ledger entry as a stable
+  markdown block (checklist, candidates, verdict, `snapshot_ref`) you can
+  paste into a PR or issue by hand -- see [Tool:
+  `export_ledger_provenance`](#tool-export_ledger_provenance).
 
 ## How it works
 
@@ -959,6 +963,55 @@ there's nothing to check. Results here are also layered onto
 entries afterward -- `check_ledger_liveness` is the only thing that
 advances those fields past their write-time defaults.
 
+## Tool: `export_ledger_provenance`
+
+Formats one ledger entry -- requirements checklist, candidates compared,
+verdict, confidence, `snapshot_ref` -- as a single markdown block: a
+stable, portable record of that decision you can paste into a PR
+description or issue by hand. See [Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance) for the full
+design and its deliberate limits.
+
+Pure and deterministic: the same entry always produces byte-identical
+markdown, since the function reads nothing but its input (no live system
+time, no disk state). This only formats and returns text -- it does not
+post anything to GitHub or anywhere else; that's a separate action, not
+yet built.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "ledger_entry_id": "a1b2c3d4-..."
+}
+```
+
+Both fields are required -- unlike `check_ledger_liveness`, there's no
+"every entry for this project" mode, since a provenance artifact is
+inherently about one specific decision.
+
+### Output
+
+```json
+{
+  "ledger_entry_id": "a1b2c3d4-...",
+  "markdown": "## Pattern decision: cancellation policy display with refund tiers by date\n\n- **Verdict:** use_existing (confidence: high)\n- **Reason:** scored\n- **Coverage:** 5/8 (62.5%)\n- **Domain:** Airbnb-style rental marketplace\n- **Framework:** React + Tailwind\n- **Snapshot:** `9f3a1c7e2b0d4f5a6b7c8d9e0f1a2b3c4d5e6f70`\n- **Judged at:** 2026-08-29T19:50:47.073Z\n\n### Requirements checked\n- ...\n\n### Candidates compared\n| Source | Name | Coverage | Chosen |\n| --- | --- | --- | --- |\n| ReUI (reui.io) | Timeline | 62.5 | ✓ |\n\n_Generated by Pattern (`export_ledger_provenance`) from ledger entry `a1b2c3d4-...`._"
+}
+```
+
+Errors (as `isError: true`, not a thrown exception) when `ledger_entry_id`
+doesn't match any entry for that `project_id` -- including when the id is
+real but belongs to a different project, since entries are always scoped
+per `project_id`.
+
+For a `custom_build` verdict, the candidates section explains that gap in
+prose instead of an empty table -- Pattern doesn't persist the
+custom-build reference (Mobbin/Figma) to the ledger (see
+[`distillCandidate`](#data-minimization)), so it can't reproduce it here.
+A `null` `snapshot_ref` (project root wasn't a git repository at judgment
+time) renders as prose too, not the literal word `null`.
+
 ## Feature cost attribution
 
 Every `recommend_component` call that writes to the ledger -- a fresh
@@ -1126,8 +1179,14 @@ cache-hit line was written*, not the original judgment's -- to see the
 original judgment's snapshot, look up the entry named in its
 `ledger_entry_id`/`original_verdict_timestamp` fields instead.
 
-Not yet built (P1-P3 of Feature 2): a markdown export of one entry's full
-record for attaching to a PR/issue, and the GitHub posting action itself.
+[`export_ledger_provenance`](#tool-export_ledger_provenance) packages one
+entry's full record -- checklist, candidates, verdict, `snapshot_ref` --
+into a markdown block you can paste into a PR or issue by hand.
+
+Not yet built (P2-P3 of Feature 2): the MCP action to post that artifact
+to a GitHub PR/issue automatically (blocked on an open question -- personal
+token vs. GitHub App -- see BACKLOG.md), and provenance backfill for
+entries that predate `snapshot_ref`.
 
 ### Referential integrity: `file_path` / `live_status`
 

package/dist/index.js

@@ -442,6 +442,7 @@ const READ_LEDGER_TOOL_NAME = "read_ledger";
 const REPORT_BUILD_COST_TOOL_NAME = "report_build_cost";
 const REPORT_OUTCOME_PROXY_TOOL_NAME = "report_outcome_proxy";
 const CHECK_LEDGER_LIVENESS_TOOL_NAME = "check_ledger_liveness";
+const EXPORT_LEDGER_PROVENANCE_TOOL_NAME = "export_ledger_provenance";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -677,6 +678,20 @@ const CHECK_LEDGER_LIVENESS_INPUT_SCHEMA = {
     },
     required: ["project_id"],
 };
+const EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in the recommend_component call that produced this ledger entry.",
+        },
+        ledger_entry_id: {
+            type: "string",
+            description: "The specific entry to export, from read_ledger or check_ledger_liveness.",
+        },
+    },
+    required: ["project_id", "ledger_entry_id"],
+};
 // Shared between buildSystemPrompt's own step 2 and
 // buildExtractionSystemPrompt (the extract_requirements tool's standalone
 // prompt) -- the extraction *instructions* are one piece of text reused
@@ -1541,6 +1556,54 @@ function findLedgerMatches(projectId, componentNeed, limit = 20) {
     entries.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
     return entries.slice(0, limit);
 }
+// Feature 2 / Decision Provenance, P1: renders one ledger entry as a
+// stable markdown block -- "stable" meaning a pure function of the entry
+// alone (never Date.now(), never anything read live off disk), so the
+// same entry always produces byte-identical markdown. That determinism is
+// what makes verify-provenance-artifact.mjs's snapshot test meaningful:
+// a diff in the generated markdown for a fixed fixture means the format
+// changed, not that time passed. Markdown, not JSON, per the spec --
+// PRs/issues render it natively (P2, not built here, attaches this to
+// one).
+export function formatProvenanceArtifact(entry) {
+    const lines = [];
+    lines.push(`## Pattern decision: ${entry.component_need}`);
+    lines.push("");
+    lines.push(`- **Verdict:** ${entry.verdict} (confidence: ${entry.confidence})`);
+    lines.push(`- **Reason:** ${entry.reason}`);
+    lines.push(`- **Coverage:** ${entry.coverage ?? "n/a"}`);
+    lines.push(`- **Domain:** ${entry.domain}`);
+    lines.push(`- **Framework:** ${entry.framework}`);
+    lines.push(`- **Snapshot:** ${entry.snapshot_ref ? "`" + entry.snapshot_ref + "`" : "not available (project root wasn't a git repository at judgment time)"}`);
+    lines.push(`- **Judged at:** ${entry.timestamp}${entry.cache_hit ? " (served from ledger cache hit)" : ""}`);
+    lines.push("");
+    lines.push("### Requirements checked");
+    if (entry.checklist.length === 0) {
+        lines.push("_No checklist recorded for this entry._");
+    }
+    else {
+        for (const item of entry.checklist)
+            lines.push(`- ${item}`);
+    }
+    lines.push("");
+    lines.push("### Candidates compared");
+    if (entry.candidates_evaluated.length === 0) {
+        lines.push(entry.verdict === "custom_build"
+            ? "_No existing candidate met the bar -- Pattern recommended a custom build. Pattern doesn't persist the custom-build reference (Mobbin/Figma) to the ledger, so it isn't reproducible here._"
+            : "_No candidates recorded for this entry._");
+    }
+    else {
+        lines.push("| Source | Name | Coverage | Chosen |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const c of entry.candidates_evaluated) {
+            const chosen = c.name !== null && c.name === entry.chosen_candidate ? "✓" : "";
+            lines.push(`| ${c.source ?? "n/a"} | ${c.name ?? "n/a"} | ${c.coverage_pct ?? "n/a"} | ${chosen} |`);
+        }
+    }
+    lines.push("");
+    lines.push(`_Generated by Pattern (\`export_ledger_provenance\`) from ledger entry \`${entry.id}\`._`);
+    return lines.join("\n");
+}
 // report_build_cost (cost-attribution build plan, 1.3) -- self-reported
 // build cost, cheapest option first, since Pattern has no visibility into
 // what happens after judgeComponent returns a verdict (1.4's
@@ -2477,6 +2540,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "entries afterward.",
             inputSchema: CHECK_LEDGER_LIVENESS_INPUT_SCHEMA,
         },
+        {
+            name: EXPORT_LEDGER_PROVENANCE_TOOL_NAME,
+            description: "Formats one ledger entry (requirements checklist, candidates " +
+                "compared, verdict, confidence, snapshot_ref) as a single markdown " +
+                "block -- a stable, portable record of that decision you can paste " +
+                "into a PR description or issue by hand. Pure and deterministic: " +
+                "the same entry always produces the same markdown, nothing here " +
+                "reads live system time or disk state. This only formats and " +
+                "returns text; it does not post anything to GitHub or anywhere " +
+                "else -- that's a separate, not-yet-built action.",
+            inputSchema: EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -2621,6 +2696,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === EXPORT_LEDGER_PROVENANCE_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const entry = readLedgerEntries(args.project_id).find((e) => e.id === args.ledger_entry_id);
+            if (!entry) {
+                throw new Error(`No ledger entry with id "${args.ledger_entry_id}" found for project_id "${args.project_id}". Use read_ledger to list entries and their ids.`);
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ledger_entry_id: entry.id, markdown: formatProvenanceArtifact(entry) }) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
     throw new Error(`Unknown tool: ${request.params.name}`);
 });
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP tool that judges whether a UI component need should be met with an existing shadcn/ui, 21st.dev, or ReUI component or requires a custom build, using field/requirement coverage scored against real component code.",
   "type": "module",
   "main": "dist/index.js",