@precode/mcp 0.3.0 → 0.3.1

package/README.md

@@ -121,7 +121,8 @@ 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` (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.
-- **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` writes such placeholders on purpose so a fresh spec can't be "verified" until you point the gate at something real.
+- **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

@@ -161,14 +161,16 @@ server.tool("precode.verify", "Close the done-gate for the current task. The MCP
         const autoSpecs = specs.filter((c) => checkKind(c) === "auto");
         const manualSpecs = specs.filter((c) => checkKind(c) === "manual");
         const placeholderSpecs = specs.filter((c) => checkKind(c) === "skip");
-        // Route manual checks to the human TODO when the task closes — never auto-passed.
+        // 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) => {
@@ -178,16 +180,16 @@ server.tool("precode.verify", "Close the done-gate for the current task. The MCP
                 `## 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}).`
@@ -219,7 +221,16 @@ server.tool("precode.verify", "Close the done-gate for the current task. The MCP
             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",
@@ -322,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",
@@ -391,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",
@@ -468,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

@@ -383,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",
@@ -404,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.3.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",