@precode/mcp 0.2.0 → 0.3.1

package/README.md

@@ -15,14 +15,28 @@ At the end it writes an **`IMPLEMENTATION.md`** (what was built) and a **`TODO_F
 
 ## Install
 
-Runs over stdio. Point any MCP host at it.
+Runs over stdio. Point any MCP host at `npx -y @precode/mcp`. Full per-host copy-paste configs: [useprecode.vercel.app/mcp](https://useprecode.vercel.app/mcp).
 
-**Cursor** — `.cursor/mcp.json`:
+| Host | Config location | How |
+|------|-----------------|-----|
+| **Cursor** | `.cursor/mcp.json` | JSON — see below |
+| **Claude Code** | `.mcp.json` (project) | `claude mcp add --env PRECODE_TELEMETRY_DISABLED=1 --transport stdio --scope project precode -- npx -y @precode/mcp` |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` | JSON — same shape as Cursor |
+| **Codex CLI** | `~/.codex/config.toml` | `codex mcp add precode -- npx -y @precode/mcp` |
+| **VS Code** | `.vscode/mcp.json` | JSON — uses `"servers"` not `"mcpServers"` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | JSON — same shape as Cursor |
+| **Antigravity** | `~/.gemini/antigravity/mcp_config.json` | Agent panel → Manage MCP Servers → View raw config |
+
+**Cursor / Claude Desktop / Windsurf / Antigravity** — `mcpServers` JSON:
 
 ```json
 {
   "mcpServers": {
-    "precode": { "command": "npx", "args": ["-y", "@precode/mcp"] }
+    "precode": {
+      "command": "npx",
+      "args": ["-y", "@precode/mcp"],
+      "env": { "PRECODE_TELEMETRY_DISABLED": "1" }
+    }
   }
 }
 ```
@@ -30,10 +44,30 @@ Runs over stdio. Point any MCP host at it.
 **Claude Code:**
 
 ```bash
-claude mcp add precode -- npx -y @precode/mcp
+claude mcp add --env PRECODE_TELEMETRY_DISABLED=1 --transport stdio --scope project precode -- npx -y @precode/mcp
+```
+
+**Codex CLI:**
+
+```bash
+codex mcp add precode -- npx -y @precode/mcp
 ```
 
-**Codex / Antigravity / VS Code** — add the same `command: npx`, `args: ["-y", "@precode/mcp"]` to their MCP config.
+**VS Code** — note `"servers"` wrapper and optional `"cwd": "${workspaceFolder}"`:
+
+```json
+{
+  "servers": {
+    "precode": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@precode/mcp"],
+      "cwd": "${workspaceFolder}",
+      "env": { "PRECODE_TELEMETRY_DISABLED": "1" }
+    }
+  }
+}
+```
 
 The server reads `.precode/` from the directory the host runs it in (`PRECODE_ROOT` overrides). Local stdio only — the build loop needs your filesystem.
 
@@ -52,13 +86,14 @@ Telemetry is off unless `PRECODE_TELEMETRY_URL` is set. When enabled, the server
 npm run test:stdio
 ```
 
-The smoke test launches the built MCP server over stdio, verifies the tool list, confirms failed checks keep a task open, confirms passing checks mark it done, reads `precode://docs`, and writes the final `TODO_FOR_YOU.md`.
+The smoke test launches the built MCP server over stdio, verifies the tool list, runs a real executable check, confirms a failing check (and a fabricated passing report) keep the task open, confirms the task closes only once the real check passes, reads `precode://docs`, and writes the final `TODO_FOR_YOU.md`. `npm test` runs the full edge-case suite (`test/run.mjs`).
 
 ## Tools
 
 | Tool | Does |
 |------|------|
 | `precode.get_goal` | Re-anchor on the goal + progress |
+| `precode.status` | Read-only snapshot of tasks, checks, and deferred work |
 | `precode.next_phase` | Alias for the next phased build step |
 | `precode.next_task` | Pull the next step + acceptance criteria |
 | `precode.verify` | **Runs** the task's `checks.json` checks; marks done only on real exit-0 |
@@ -84,9 +119,10 @@ Declare checks in `.precode/checks.json`. Each `auto` check is **run by the MCP*
 ```
 
 - `kind: "auto"` — executed; pass = exit 0 (and `expect` substring/`/regex/` matches output if set). Optional `timeoutMs` (default 120s).
-- `kind: "manual"` — never auto-passed; surfaced as a human gate in `TODO_FOR_YOU.md`.
+- `kind: "manual"` — never auto-passed; surfaced as a human gate in `TODO_FOR_YOU.md` (a manual-only task closes with its gate routed to you).
 - `taskIndex` — scope a check to one task; omit for a global check that runs on every task.
-- No auto check for a task? `verify` falls back to your self-reported results but stamps the pass **UNVERIFIED**, so it's never mistaken for a machine-verified one.
+- **A task never closes on a self-reported pass.** Reported `checkResults` are advisory only. A check declared with an empty `cmd` is treated as unconfigured and **HOLDs** the task — wire a real command, mark it `manual`, or `precode.defer_task`.
+- **`adopt_spec` infers real commands** from your project (`package.json` scripts, `Cargo.toml`, `go.mod`) so a fresh spec is verifiable out of the box. Only when nothing is detected does it write empty placeholders that HOLD until you fill them. Failure advice references the actual command that ran, and `defer_task` is refused if the task's checks actually pass (so it can't be used to dodge verifiable work). Global `manual` gates are listed once in `TODO_FOR_YOU.md`, not repeated per task.
 
 **Security:** the runner only executes commands you put in your own repo's `checks.json` — the same trust level as the agent already running your build. Commands run with a timeout and captured output. Because `checks.json` lives in your repo, gate tampering shows up in your diff.
 

package/dist/index.js

@@ -2,9 +2,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { createRequire } from "node:module";
 import { PrecodeStore, adoptSpec } from "./store.js";
 import { checkKind, runChecks } from "./checks.js";
 import { recordTelemetry, taskTelemetry } from "./telemetry.js";
+// Single source of truth for the version the handshake reports — read from
+// package.json so it can never drift from the published package again.
+const VERSION = createRequire(import.meta.url)("../package.json")
+    .version ?? "0.0.0";
 /**
  * @precode/mcp — drives a phased build → recheck → fix loop over a `.precode/`
  * package. Fixes the loop/goal failure other spec MCPs ship with:
@@ -22,7 +27,15 @@ function text(s) {
 }
 const NO_STORE = text("No `.precode/` package found in this directory. Either drop a PreCode export here, " +
     "or call `precode.adopt_spec` to map a plain SPEC.md / .specify / .spec-workflow folder into one.");
-const server = new McpServer({ name: "precode", version: "0.1.0" });
+const server = new McpServer({ name: "precode", version: VERSION }, {
+    instructions: "PreCode drives a spec → build → verify loop with a hard, SELF-EXECUTING done-gate. " +
+        "Flow: ensure a .precode/ package exists (precode.adopt_spec maps any SPEC.md / .specify / .spec-workflow). " +
+        "Then loop: precode.get_goal to anchor on the goal → precode.next_task → build ONLY that task → precode.verify. " +
+        "On verify the MCP itself RUNS the commands in .precode/checks.json; a task closes only on real exit-0, so self-reported results cannot fake a pass. " +
+        "A failing or unconfigured check keeps the task OPEN with concrete fixes. If a check genuinely cannot pass here (needs a secret/deploy/external service), call precode.defer_task with a reason. " +
+        "When every task is done, call precode.finalize. Call precode.status anytime for a read-only progress snapshot. " +
+        "Resources precode://goal, ://tasks, ://docs, ://acceptance, ://progress are re-readable each phase.",
+});
 // --- Tool: get the goal (anti-drift anchor) -------------------------------
 server.tool("precode.get_goal", "Re-read the project goal and progress. Call this at the start of every phase so the build does not drift from the spec.", {}, async () => {
     const s = await store();
@@ -31,6 +44,37 @@ server.tool("precode.get_goal", "Re-read the project goal and progress. Call thi
     await recordTelemetry({ eventName: "mcp_get_goal", root: ROOT });
     return text(await s.goal());
 });
+// --- Tool: status (read-only snapshot) ------------------------------------
+server.tool("precode.status", "Read-only snapshot of the build: task counts, the current open task, deferred tasks, and whether real checks are configured. Has no side effects — safe to call anytime.", {}, async () => {
+    const s = await store();
+    if (!s)
+        return NO_STORE;
+    const tasks = await s.tasks();
+    const deferred = await s.deferredEntries();
+    const deferredSet = new Set(deferred.map((e) => e.index));
+    const done = tasks.filter((t) => t.done).length;
+    const open = tasks.filter((t) => !t.done && !deferredSet.has(t.index));
+    const next = open[0];
+    const allChecks = await s.checks();
+    const autoConfigured = allChecks.filter((c) => checkKind(c) === "auto").length;
+    const placeholders = allChecks.filter((c) => checkKind(c) === "skip").length;
+    const manual = allChecks.filter((c) => checkKind(c) === "manual").length;
+    return text([
+        `Tasks: ${done}/${tasks.length} done, ${open.length} open, ${deferred.length} deferred.`,
+        next ? `Next open task: #${next.index} — ${next.text}` : "No open tasks — call precode.finalize.",
+        `Checks in checks.json: ${autoConfigured} auto (executed), ${manual} manual, ${placeholders} unconfigured placeholder(s).`,
+        placeholders > 0
+            ? "WARNING: placeholder checks have no command — tasks they apply to will HOLD until you set a real cmd, mark them manual, or defer."
+            : autoConfigured === 0 && manual === 0
+                ? "WARNING: no checks defined — add an auto check with a real cmd so the gate can verify."
+                : "Gate is backed by real executed checks.",
+        deferred.length
+            ? `Deferred: ${deferred.map((e) => `#${e.index} (${e.reason})`).join("; ")}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n"));
+});
 // --- Tool: next task ------------------------------------------------------
 server.tool("precode.next_task", "Pull the next unchecked build step plus the goal and acceptance criteria. Build ONLY this task, then call precode.verify. Do not skip ahead.", {}, async () => {
     const s = await store();
@@ -91,7 +135,7 @@ server.tool("precode.next_phase", "Alias for precode.next_task. Pulls the next p
     ].join("\n"));
 });
 // --- Tool: verify (the hard done-gate + fix loop) -------------------------
-server.tool("precode.verify", "Close the done-gate for the current task. If the project declares checks in .precode/checks.json, the MCP RUNS them itself and the verdict comes from real exit codes — your reported results cannot fake a pass. A task is marked done only when every auto check it runs passes. Otherwise the gaps come back and the task stays OPEN — fix and call precode.verify again.", {
+server.tool("precode.verify", "Close the done-gate for the current task. The MCP RUNS the task's auto checks from .precode/checks.json itself and the verdict comes from real exit codes — your reported results CANNOT fake a pass and never close a task on their own. A task is marked done only when every auto check passes (or it has only manual gates, which route to TODO). If a declared check has no command yet, or no check is defined, you get a HOLD telling you to wire a real command, mark it manual, or precode.defer_task. Fix and call precode.verify again.", {
     checkResults: z
         .array(z.object({
         name: z.string().describe("e.g. 'build', 'typecheck', 'lint', 'smoke test'"),
@@ -99,7 +143,7 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
         detail: z.string().optional(),
     }))
         .optional()
-        .describe("Optional supplementary notes about checks you ran. Authoritative only as a FALLBACK when checks.json defines no auto check for this task."),
+        .describe("ADVISORY ONLY. Never used to mark a task done — a task closes only when the MCP executes its checks.json checks and they pass (or via a manual gate / precode.defer_task)."),
     notes: z.string().optional(),
     task: z.string().optional().describe("Optional host-side task identifier or title."),
 }, async ({ checkResults, notes, task: taskLabel }) => {
@@ -116,14 +160,17 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
         const specs = await s.checksForTask(task.index);
         const autoSpecs = specs.filter((c) => checkKind(c) === "auto");
         const manualSpecs = specs.filter((c) => checkKind(c) === "manual");
-        // Route manual checks to the human TODO when the task closes — never auto-passed.
+        const placeholderSpecs = specs.filter((c) => checkKind(c) === "skip");
+        // Only TASK-SCOPED manual gates are routed per task. Global (project-level)
+        // manual gates are listed once by precode.finalize — not repeated per task.
+        const taskManual = manualSpecs.filter((c) => c.taskIndex === task.index);
         const routeManual = async () => {
-            if (!manualSpecs.length)
+            if (!taskManual.length)
                 return;
             await s.appendTodo([
                 `## Task #${task.index} — manual verification required`,
                 "",
-                ...manualSpecs.map((c) => `- [ ] ${c.name}`),
+                ...taskManual.map((c) => `- [ ] ${c.name}`),
             ].join("\n"));
         };
         const closeTask = async (verifiedLine) => {
@@ -133,16 +180,16 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
                 `## Task #${task.index}: ${task.text}`,
                 taskLabel ? `Host task: ${taskLabel}` : "",
                 verifiedLine,
-                manualSpecs.length
-                    ? `Manual gates routed to TODO_FOR_YOU.md: ${manualSpecs.map((c) => c.name).join(", ")}`
+                taskManual.length
+                    ? `Manual gates routed to TODO_FOR_YOU.md: ${taskManual.map((c) => c.name).join(", ")}`
                     : "",
                 notes ? `Notes: ${notes}` : "",
             ]
                 .filter(Boolean)
                 .join("\n"));
             const next = await s.nextOpenTask();
-            const manualNote = manualSpecs.length
-                ? ` ${manualSpecs.length} manual check(s) routed to TODO_FOR_YOU.md for you.`
+            const manualNote = taskManual.length
+                ? ` ${taskManual.length} manual check(s) routed to TODO_FOR_YOU.md for you.`
                 : "";
             return text((next
                 ? `PASS. Task #${task.index} marked done.${manualNote} Call precode.next_task for the next step (#${next.index}).`
@@ -174,7 +221,16 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
             const runs = await runChecks(autoSpecs, ROOT);
             const failed = runs.filter((r) => !r.passed);
             if (failed.length > 0) {
-                return await gateFailure(failed.map((r) => `${r.name}: FAILED — ${r.detail}`), failed.map((r) => `${r.name}: ${fixHint(r.name)}`));
+                const cmdById = new Map(autoSpecs.map((c) => [c.id, c.cmd ?? ""]));
+                return await gateFailure(failed.map((r) => `${r.name}: FAILED — ${r.detail}`), 
+                // Advice references the ACTUAL command that ran, never a guess from
+                // the check's display name (which may not match the command).
+                failed.map((r) => {
+                    const cmd = cmdById.get(r.id);
+                    return cmd
+                        ? `${r.name}: read the output above, fix the cause, then re-run \`${cmd}\`.`
+                        : `${r.name}: read the output above and fix the failure.`;
+                }));
             }
             await recordTelemetry({
                 eventName: "mcp_verify_pass",
@@ -184,26 +240,48 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
             });
             return await closeTask(`Verified by MCP execution: ${runs.map((r) => `${r.name} ✓ (exit ${r.exitCode})`).join(", ")}`);
         }
-        // --- Fallback: no auto check defined for this task. Self-report is
-        //     accepted but explicitly stamped UNVERIFIED so it is never mistaken
-        //     for a machine-verified pass. ---
+        // --- No auto check ran. A task NEVER closes on a self-reported pass. ---
         const reported = checkResults ?? [];
-        if (reported.length === 0) {
-            return text(`HOLD. Task #${task.index} has no executable check in .precode/checks.json and you reported none. ` +
-                "Add a real command to checks.json (preferred — then the gate runs it), or report the checks you ran. " +
-                "Nothing is marked done on an empty report.");
+        const reportedNote = reported.length
+            ? `Agent-reported (advisory, NOT used to close): ${reported
+                .map((c) => `${c.name}=${c.passed ? "pass" : "fail"}`)
+                .join(", ")}`
+            : "";
+        // Unconfigured placeholder checks (declared but no command) — hold and
+        // tell the agent to wire a real command, mark it manual, or defer.
+        if (placeholderSpecs.length > 0) {
+            return text([
+                `HOLD. Task #${task.index} is NOT done.`,
+                `${placeholderSpecs.length} declared check(s) have no command yet: ${placeholderSpecs
+                    .map((c) => c.name)
+                    .join(", ")}.`,
+                "A task never closes on a self-reported pass. Do ONE of these in .precode/checks.json:",
+                "- set a real shell `cmd` for each check (preferred — the gate then RUNS it), or",
+                '- set its `kind` to `manual` if only a human can verify it (routed to TODO_FOR_YOU.md), or',
+                "- call precode.defer_task if it genuinely cannot be verified in this environment.",
+                reportedNote,
+            ]
+                .filter(Boolean)
+                .join("\n"));
         }
-        const failedReported = reported.filter((c) => !c.passed);
-        if (failedReported.length > 0) {
-            return await gateFailure(failedReported.map((c) => `${c.name}: FAILED${c.detail ? ` — ${c.detail}` : ""}`), failedReported.map((c) => `${c.name}: ${fixHint(c.name)}`));
+        // Only explicit manual gates apply — a legitimate human-verified close.
+        if (manualSpecs.length > 0) {
+            await recordTelemetry({
+                eventName: "mcp_verify_pass",
+                root: ROOT,
+                task: taskTelemetry(task),
+                metadata: { checkCount: manualSpecs.length, executed: false, manualOnly: true },
+            });
+            return await closeTask("Closed with MANUAL gates only (no automatable check) — routed to TODO_FOR_YOU.md for your verification.");
         }
-        await recordTelemetry({
-            eventName: "mcp_verify_pass",
-            root: ROOT,
-            task: taskTelemetry(task),
-            metadata: { checkCount: reported.length, executed: false },
-        });
-        return await closeTask(`UNVERIFIED (self-reported, no checks.json command): ${reported.map((c) => `${c.name} ✓`).join(", ")}`);
+        // No check defined at all for this task.
+        return text([
+            `HOLD. Task #${task.index} has no check defined in .precode/checks.json, so it cannot be verified.`,
+            "A task never closes on a self-reported pass. Add at least one check (preferred: an `auto` check with a real `cmd` the gate runs), mark it `manual`, or call precode.defer_task.",
+            reportedNote,
+        ]
+            .filter(Boolean)
+            .join("\n"));
     }
     finally {
         await s.releaseLock();
@@ -255,11 +333,15 @@ server.tool("precode.finalize", "Write the handoff: confirm all tasks done and r
     const deferredSet = new Set(deferred.map((e) => e.index));
     const open = tasks.filter((t) => !t.done && !deferredSet.has(t.index));
     // Manual gates the human still owns, regenerated from checks.json for done tasks.
-    const manualGates = [];
+    // Global (project-level) manual gates appear ONCE; task-scoped ones per task.
+    const allChecks = await s.checks();
+    const manualGates = allChecks
+        .filter((c) => checkKind(c) === "manual" && c.taskIndex === undefined)
+        .map((c) => c.name);
     for (const t of tasks.filter((t) => t.done)) {
-        const manual = (await s.checksForTask(t.index)).filter((c) => checkKind(c) === "manual");
-        for (const c of manual)
+        for (const c of allChecks.filter((c) => checkKind(c) === "manual" && c.taskIndex === t.index)) {
             manualGates.push(`Task #${t.index}: ${c.name}`);
+        }
     }
     await recordTelemetry({
         eventName: "mcp_finalize",
@@ -324,6 +406,17 @@ server.tool("precode.defer_task", "Honest escape hatch for the CURRENT open task
     const task = await s.nextOpenTask();
     if (!task)
         return text("No open task to defer. Run precode.finalize.");
+    // Anti-dodge guard: if the task's real auto checks PASS right now, it is
+    // verifiable here — refuse the defer and make the agent verify instead.
+    const autoSpecs = (await s.checksForTask(task.index)).filter((c) => checkKind(c) === "auto");
+    if (autoSpecs.length > 0) {
+        const runs = await runChecks(autoSpecs, ROOT);
+        if (runs.every((r) => r.passed)) {
+            return text(`REFUSED. Task #${task.index} is verifiable here — its checks pass (${runs
+                .map((r) => `${r.name} ✓`)
+                .join(", ")}). Call precode.verify to close it; defer_task is only for checks that genuinely cannot run in this environment.`);
+        }
+    }
     await s.deferTask(task.index, reason);
     await recordTelemetry({
         eventName: "mcp_defer_task",
@@ -401,19 +494,3 @@ main().catch((err) => {
     console.error("[precode-mcp] fatal:", err);
     process.exit(1);
 });
-function fixHint(checkName) {
-    const lower = checkName.toLowerCase();
-    if (lower.includes("type") || lower.includes("tsc")) {
-        return "open the TypeScript diagnostics, fix the reported type errors, then rerun the same type-check command.";
-    }
-    if (lower.includes("lint") || lower.includes("eslint")) {
-        return "fix the reported lint violations without changing spec scope, then rerun lint.";
-    }
-    if (lower.includes("build")) {
-        return "inspect the build error, fix the first failing route/module/env issue, then rerun the production build.";
-    }
-    if (lower.includes("test") || lower.includes("smoke") || lower.includes("e2e")) {
-        return "reproduce the failing flow, align behavior to the acceptance criteria, then rerun the test.";
-    }
-    return "inspect the failing command output, make the smallest spec-aligned fix, then rerun this exact check.";
-}

package/dist/store.js

@@ -193,10 +193,14 @@ export class PrecodeStore {
         const project = manifest?.project ?? {};
         const tasks = await this.tasks();
         const done = tasks.filter((t) => t.done).length;
+        const deferred = await this.deferredIndices();
+        const docs = await this.listDocFiles();
         return [
             `Project: ${project.name ?? "(unknown)"} (${project.appType ?? "app"})`,
-            `Progress: ${done}/${tasks.length} tasks complete.`,
-            "Build strictly to the spec in `.precode/docs/`. Do not invent scope. Re-read the relevant doc before each task.",
+            `Progress: ${done}/${tasks.length} tasks complete${deferred.length ? `, ${deferred.length} deferred` : ""}.`,
+            docs.length
+                ? `Build strictly to the spec docs in .precode/: ${docs.join(", ")}. Re-read the relevant one before each task; do not invent scope.`
+                : "No spec docs found in .precode/docs/. Work from the tasks and acceptance criteria; do not invent scope.",
         ].join("\n");
     }
     async appendImplementation(entry) {
@@ -324,9 +328,13 @@ export async function adoptSpec(searchRoot, specPathHint) {
             error: "No spec found. Provide a SPEC.md, a .specify/.spec-workflow folder, or a docs/ folder of markdown.",
         };
     }
-    // Derive tasks: prefer explicit checkboxes; fall back to headings only when
-    // the spec has none, so heading text never pollutes a real task list.
+    // Derive tasks, in priority order so a real list is never collapsed into one:
+    //   1. explicit checkboxes  - [ ] ...
+    //   2. plain bullets / numbered items   - x   * x   1. x
+    //   3. section headings   ## / ###
+    //   4. a single catch-all when the spec has no structure at all.
     const checkboxes = [];
+    const bullets = [];
     const headings = [];
     for (const line of specBody.split("\n")) {
         const cb = TASK_RE.exec(line);
@@ -334,11 +342,21 @@ export async function adoptSpec(searchRoot, specPathHint) {
             checkboxes.push(`- [ ] ${cb[3]}`);
             continue;
         }
+        const bullet = /^\s*(?:[-*]|\d+[.)])\s+(.*\S)\s*$/.exec(line);
+        if (bullet) {
+            if (bullets.length < 40)
+                bullets.push(`- [ ] ${bullet[1]}`);
+            continue;
+        }
         const h = /^#{2,3}\s+(.*\S)\s*$/.exec(line);
         if (h && headings.length < 40)
             headings.push(`- [ ] Implement: ${h[1]}`);
     }
-    const tasks = checkboxes.length ? checkboxes : headings;
+    const tasks = checkboxes.length
+        ? checkboxes
+        : bullets.length
+            ? bullets
+            : headings;
     if (!tasks.length)
         tasks.push("- [ ] Implement the full spec, then verify.");
     await fs.mkdir(path.join(dir, "progress"), { recursive: true });
@@ -365,18 +383,25 @@ export async function adoptSpec(searchRoot, specPathHint) {
         "",
     ].join("\n"), "utf8");
     await fs.writeFile(path.join(dir, "manifest.json"), JSON.stringify({ project: { name: "Adopted spec", appType: "app" }, adoptedFrom: found }, null, 2), "utf8");
-    // Starter checks.json. Commands are commented placeholders the user edits to
-    // their real build — until then the gate runs nothing auto and stamps passes
-    // UNVERIFIED, so it never silently claims a verified build.
-    await fs.writeFile(path.join(dir, "checks.json"), JSON.stringify({
-        $comment: "Each 'auto' check is RUN by the MCP from the project root; the task is " +
-            "done only when its real exit code is 0. Replace cmd values with your " +
-            "build. 'manual' checks are surfaced for human verification, never auto-passed.",
-        checks: [
+    // checks.json: infer REAL commands from the project (package.json scripts,
+    // Cargo, Go) so a fresh spec is verifiable out of the box. Only fall back to
+    // empty placeholders (which HOLD a task until filled) when nothing is found.
+    const inferred = await inferAutoChecks(searchRoot);
+    const autoChecks = inferred.length
+        ? inferred
+        : [
             { id: "typecheck", name: "Type-check", kind: "auto", cmd: "" },
             { id: "lint", name: "Lint", kind: "auto", cmd: "" },
             { id: "build", name: "Production build", kind: "auto", cmd: "" },
             { id: "test", name: "Tests", kind: "auto", cmd: "" },
+        ];
+    await fs.writeFile(path.join(dir, "checks.json"), JSON.stringify({
+        $comment: "Each 'auto' check is RUN by the MCP from the project root; a task is done " +
+            "only when the real exit code is 0. Commands below were inferred from your " +
+            "project — edit/remove as needed. Empty cmd = unconfigured (the task HOLDs " +
+            "until you fill it, mark it manual, or defer). 'manual' = human gate, never auto-passed.",
+        checks: [
+            ...autoChecks,
             {
                 id: "secrets",
                 name: "Secrets & deploy env verified in real accounts",
@@ -386,3 +411,46 @@ export async function adoptSpec(searchRoot, specPathHint) {
     }, null, 2), "utf8");
     return { ok: true, dir };
 }
+/**
+ * Best-effort detection of real verification commands for the adopted project,
+ * so checks.json ships runnable instead of empty. Covers the common stacks.
+ */
+async function inferAutoChecks(root) {
+    const checks = [];
+    const has = async (rel) => fs.stat(path.join(root, rel)).then(() => true, () => false);
+    if (await has("package.json")) {
+        try {
+            const pkg = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+            const scripts = pkg.scripts ?? {};
+            const pick = (...names) => names.find((n) => typeof scripts[n] === "string");
+            const tc = pick("typecheck", "type-check", "tsc", "types");
+            if (tc)
+                checks.push({ id: "typecheck", name: "Type-check", kind: "auto", cmd: `npm run ${tc}` });
+            const lint = pick("lint", "eslint");
+            if (lint)
+                checks.push({ id: "lint", name: "Lint", kind: "auto", cmd: `npm run ${lint}` });
+            const build = pick("build", "compile");
+            if (build)
+                checks.push({ id: "build", name: "Build", kind: "auto", cmd: `npm run ${build}` });
+            const test = pick("test", "tests");
+            if (test)
+                checks.push({ id: "test", name: "Tests", kind: "auto", cmd: `npm test` });
+        }
+        catch {
+            /* malformed package.json — fall through to whatever else we detect */
+        }
+        return checks;
+    }
+    if (await has("Cargo.toml")) {
+        checks.push({ id: "build", name: "Cargo build", kind: "auto", cmd: "cargo build" });
+        checks.push({ id: "test", name: "Cargo test", kind: "auto", cmd: "cargo test" });
+        return checks;
+    }
+    if (await has("go.mod")) {
+        checks.push({ id: "build", name: "Go build", kind: "auto", cmd: "go build ./..." });
+        checks.push({ id: "vet", name: "Go vet", kind: "auto", cmd: "go vet ./..." });
+        checks.push({ id: "test", name: "Go test", kind: "auto", cmd: "go test ./..." });
+        return checks;
+    }
+    return checks;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@precode/mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Open, agent-agnostic MCP server that turns a spec (any SPEC.md, best with a PreCode .precode/ package) into a self-correcting, verified build. Drives a phased build → recheck → fix loop with hard definition-of-done gates and an implemented-vs-todo ledger.",
   "license": "MIT",
   "homepage": "https://useprecode.vercel.app/mcp",