@wardrail/plugin 0.1.5 → 0.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wardrail",
   "displayName": "Wardrail",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Keep your coding agent on the rails: consult your project's Wardrail contract while it writes code, plus a checkpoint->clear->resume workflow with checkpoints that are machine-verified, not self-reported.",
   "author": { "name": "Ghostables Ltd", "url": "https://wardrail.ghostables.io" },
   "homepage": "https://wardrail.ghostables.io",

package/README.md

@@ -10,12 +10,17 @@ The **Wardrail plugin for Claude Code**. One install gives your coding agent two
    toolset: consult your project's guardrails before editing, pull the latest security findings, get
    an independent verdict on a diff, and **query the code graph** (who calls what, blast radius)
    instead of reading files. The agent stays on the rails *before* a violation lands.
-2. **A context-saving workflow** — `/task` and `/checkpoint` slash commands, a SessionStart resume
-   listing, and a machine **verifier** so a checkpoint *can't lie*: it reconciles a task file's
-   claims against `git`, a real test run, and a diff scan before it can be marked done.
+2. **A context-saving workflow that makes `/compact` safe** — `/task` and `/checkpoint` commands, plus
+   hooks that wrap compaction itself: the moment Claude compacts (manual **or** auto), a `PreCompact`
+   hook captures verified **ground truth** to disk (branch, commits, working tree, your task's next
+   step), and `SessionStart` re-injects it afterwards — so the compacted session trusts reality, not
+   a lossy summary. A machine **verifier** means a checkpoint *can't lie*: it reconciles a task
+   file's claims against `git`, a real test run, a typecheck, and a diff scan before it can be marked
+   done.
 
 The same anti-drift, verify-don't-trust thesis Wardrail applies to your *code*, turned on the
-agent's own working memory. Zero-knowledge: your key and code stay on your machine.
+agent's own working memory. `/compact` summarizes and hopes; this re-grounds every compaction in
+checked facts. Zero-knowledge: your key and code stay on your machine.
 
 ## Install
 
@@ -47,9 +52,10 @@ fails its checks is downgraded to FAIL — so "done" actually means done.
 .claude-plugin/plugin.json   manifest + setup prompts
 skills/task/SKILL.md         /task new|resume <slug>
 skills/checkpoint/SKILL.md   /checkpoint  (runs the verifier)
-hooks/hooks.json             SessionStart → resume listing
-hooks/tasks-session-start.mjs
-hooks/verify-checkpoint.mjs  the machine verifier
+hooks/hooks.json             SessionStart + PreCompact wiring
+hooks/tasks-session-start.mjs   resume listing, repo reality + blast radius, post-compact re-inject
+hooks/precompact-snapshot.mjs   captures verified ground truth before any compaction
+hooks/verify-checkpoint.mjs     the machine verifier (git · tests · typecheck · honesty)
 .mcp.json                    the Wardrail MCP server (npx -y @wardrail/mcp)
 ```
 

package/hooks/hooks.json

@@ -1,15 +1,26 @@
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/tasks-session-start.mjs"]
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/tasks-session-start.mjs"]
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/precompact-snapshot.mjs"]
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/precompact-snapshot.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// PreCompact hook — capture verified ground truth the moment before Claude compacts context
+// (manual /compact OR automatic when the window fills). A hook can't author intent, but it CAN
+// snapshot reality: branch, recent commits, working-tree state, diff stat, and the active task's
+// next step. That's exactly what /compact's lossy summary gets wrong. The SessionStart hook
+// (source: compact) re-injects this file afterwards, so the compacted session trusts reality over
+// the summary. Pure side effect — writes .wardrail/last-checkpoint.md, prints nothing, never throws.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+let cwd = process.cwd();
+let trigger = "";
+try {
+  const input = JSON.parse(readStdin() || "{}");
+  if (input.cwd) cwd = input.cwd;
+  trigger = input.trigger || input.matcher || "";
+} catch {
+  // non-JSON stdin — fall back to defaults
+}
+
+const git = (args) => {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+};
+const isRepo = git(["rev-parse", "--is-inside-work-tree"]) === "true";
+
+// Active task's next step, if the tasks workflow is in use.
+let nextStep = "";
+const tasksDir = join(cwd, "tasks");
+if (existsSync(tasksDir)) {
+  for (const name of readdirSync(tasksDir)) {
+    if (!name.endsWith(".md")) continue;
+    let text = "";
+    try {
+      text = readFileSync(join(tasksDir, name), "utf8");
+    } catch {
+      continue;
+    }
+    const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm || !/^status:\s*active\s*$/m.test(fm[1])) continue;
+    const ns = text.match(/##\s*Next step\s*\r?\n+([^\r\n]+)/);
+    nextStep = `${name.replace(/\.md$/, "")} — ${ns ? ns[1].trim() : "(no next step recorded)"}`;
+    break;
+  }
+}
+
+const stamp = new Date().toISOString();
+const lines = [
+  `# Wardrail checkpoint snapshot (${trigger || "compact"} · ${stamp})`,
+  ``,
+  `Machine-captured ground truth from the moment before context was compacted. Trust this over the`,
+  `summary if they disagree.`,
+  ``,
+];
+if (!isRepo) {
+  lines.push(`(not a git repository — no repo state to capture)`);
+} else {
+  lines.push(`**Branch:** ${git(["rev-parse", "--abbrev-ref", "HEAD"]) || "(unknown)"}`);
+  if (nextStep) lines.push(``, `**Active task:** ${nextStep}`);
+  lines.push(``, `**Recent commits:**`, "```", git(["log", "--oneline", "-8"]) || "(none)", "```");
+  lines.push(``, `**Uncommitted changes:**`, "```", git(["status", "--porcelain"]) || "(clean working tree)", "```");
+  const stat = git(["diff", "--stat", "HEAD"]);
+  if (stat) lines.push(``, `**Diff stat (vs HEAD):**`, "```", stat, "```");
+}
+
+try {
+  mkdirSync(join(cwd, ".wardrail"), { recursive: true });
+  writeFileSync(join(cwd, ".wardrail", "last-checkpoint.md"), lines.join("\n") + "\n", "utf8");
+} catch {
+  // best-effort — a snapshot failure must never break compaction
+}
+process.exit(0);

package/hooks/tasks-session-start.mjs

@@ -1,58 +1,179 @@
-#!/usr/bin/env node
-// SessionStart hook for the tasks plugin.
-// Prints active task files in the current project's ./tasks/ so resuming is one step.
-// Silent (no output) when there is no ./tasks/ dir or no active task — costs nothing
-// in projects that don't use the workflow.
-
-import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
-
-function readStdin() {
-  try {
-    return readFileSync(0, "utf8");
-  } catch {
-    return "";
-  }
-}
-
-let cwd = process.cwd();
-try {
-  const input = JSON.parse(readStdin() || "{}");
-  if (input.cwd) cwd = input.cwd;
-} catch {
-  // no/!json stdin — fall back to process.cwd()
-}
-
-const tasksDir = join(cwd, "tasks");
-if (!existsSync(tasksDir)) process.exit(0);
-
-const active = [];
-for (const name of readdirSync(tasksDir)) {
-  if (!name.endsWith(".md")) continue;
-  let text;
-  try {
-    text = readFileSync(join(tasksDir, name), "utf8");
-  } catch {
-    continue;
-  }
-  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!fm || !/^status:\s*active\s*$/m.test(fm[1])) continue;
-
-  const slug = name.replace(/\.md$/, "");
-  const next = text.match(/##\s*Next step\s*\r?\n+([^\r\n]+)/);
-  // Last machine verdict from the checkpoint verifier, if any — surfaced so a resume
-  // sees up front whether the prior checkpoint left open issues (WARN/FAIL).
-  const verdict = text.match(/^-\s*Verdict:\s*(\S+)\s*(PASS|WARN|FAIL)/m);
-  active.push({ slug, next: next ? next[1].trim() : "", verdict: verdict ? `${verdict[1]} ${verdict[2]}` : "" });
-}
-
-if (active.length === 0) process.exit(0);
-
-const lines = ["Active task file(s) in ./tasks/ — resume cheaply with `/task resume <slug>`:"];
-for (const t of active) {
-  let line = `- ${t.slug}`;
-  if (t.verdict) line += ` [last checkpoint: ${t.verdict}]`;
-  if (t.next) line += ` — next: ${t.next}`;
-  lines.push(line);
-}
-process.stdout.write(lines.join("\n") + "\n");
+#!/usr/bin/env node
+// SessionStart hook for the tasks plugin — resume cheaply and stay grounded in reality.
+// Fires on startup / resume / clear / compact (distinguished by `source`):
+//   - compact  → re-inject the verified ground-truth snapshot the PreCompact hook wrote, so the
+//                compacted session trusts reality over the (lossy) summary.
+//   - resume/startup → list active tasks (the project's work index), then re-ground the session in
+//                the current repo state and the code-graph blast radius of the task's files, so a
+//                fresh window restarts on the rails instead of guessing.
+// Silent when there's nothing to say — costs nothing in projects that don't use the workflow.
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+let cwd = process.cwd();
+let source = "";
+try {
+  const input = JSON.parse(readStdin() || "{}");
+  if (input.cwd) cwd = input.cwd;
+  source = input.source || "";
+} catch {
+  // non-JSON stdin — fall back to defaults
+}
+
+const out = [];
+
+// ---- on compaction: re-inject the verified snapshot captured before compaction ----
+const snapPath = join(cwd, ".wardrail", "last-checkpoint.md");
+if (source === "compact" && existsSync(snapPath)) {
+  try {
+    out.push(
+      "Context was just compacted — the summary above may have dropped or distorted detail. The following is machine-captured ground truth from the moment before compaction; trust it over the summary:\n",
+    );
+    out.push(readFileSync(snapPath, "utf8").trim());
+  } catch {
+    // snapshot unreadable — fall through to the normal listing
+  }
+}
+
+// ---- collect active tasks (also serves as the project work index) ----
+function parseFiles(text) {
+  const sec = text.match(/##\s*Files touched\s*\r?\n([\s\S]*?)(?:\r?\n##\s|\s*$)/);
+  const files = [];
+  if (sec) {
+    for (const line of sec[1].split(/\r?\n/)) {
+      const m = line.match(/^\s*-\s+(.+?)(?:\s+[—-]\s.*)?$/);
+      if (!m) continue;
+      const p = m[1].trim();
+      if (!p || p.startsWith("(")) continue;
+      files.push(p.replace(/\\/g, "/"));
+    }
+  }
+  return files;
+}
+
+const tasksDir = join(cwd, "tasks");
+const active = [];
+let doneCount = 0;
+if (existsSync(tasksDir)) {
+  for (const name of readdirSync(tasksDir)) {
+    if (!name.endsWith(".md")) continue;
+    let text = "";
+    try {
+      text = readFileSync(join(tasksDir, name), "utf8");
+    } catch {
+      continue;
+    }
+    const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm) continue;
+    if (/^status:\s*done\s*$/m.test(fm[1])) {
+      doneCount++;
+      continue;
+    }
+    if (!/^status:\s*active\s*$/m.test(fm[1])) continue;
+    const slug = name.replace(/\.md$/, "");
+    const next = text.match(/##\s*Next step\s*\r?\n+([^\r\n]+)/);
+    const verdict = text.match(/^-\s*Verdict:\s*(\S+)\s*(PASS|WARN|FAIL)/m);
+    active.push({ slug, next: next ? next[1].trim() : "", verdict: verdict ? `${verdict[1]} ${verdict[2]}` : "", files: parseFiles(text) });
+  }
+}
+
+if (active.length) {
+  out.push("\nActive task file(s) in ./tasks/ — resume with `/task resume <slug>`:");
+  for (const t of active) {
+    let line = `- ${t.slug}`;
+    if (t.verdict) line += ` [last checkpoint: ${t.verdict}]`;
+    if (t.next) line += ` — next: ${t.next}`;
+    out.push(line);
+  }
+  if (doneCount) out.push(`(${doneCount} completed task file(s) also in ./tasks/.)`);
+}
+
+// ---- on startup/resume: re-ground in current repo reality + code-graph blast radius ----
+if (source !== "compact" && active.length) {
+  const git = (args) => {
+    try {
+      return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {
+      return "";
+    }
+  };
+  if (git(["rev-parse", "--is-inside-work-tree"]) === "true") {
+    const recent = git(["log", "--oneline", "-5"]);
+    const status = git(["status", "--porcelain"]);
+    if (recent || status) {
+      out.push("\nCurrent repo state (resume on reality, not assumptions):");
+      if (recent) out.push("Recent commits:\n" + recent);
+      out.push(status ? "Uncommitted changes:\n" + status : "Working tree: clean");
+    }
+  }
+  const blast = blastRadius(cwd, active.flatMap((t) => t.files));
+  if (blast) out.push("\nCode-graph blast radius for this task's files (what depends on them — check before you change):\n" + blast);
+}
+
+// Zero-dependency read of .wardrail/codegraph.json → dependent files of the given source files.
+// Mirrors the server-side impact-of-diff walk; absent graph or files → empty (no-op).
+function blastRadius(root, files) {
+  const unique = [...new Set(files)];
+  if (!unique.length) return "";
+  const p = join(root, ".wardrail", "codegraph.json");
+  if (!existsSync(p)) return "";
+  let g;
+  try {
+    g = JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return "";
+  }
+  const DEP = new Set(["calls", "references", "imports", "extends", "implements"]);
+  const nodeById = new Map();
+  const inEdges = new Map();
+  for (const n of g.nodes ?? []) nodeById.set(n.id, n);
+  for (const e of g.edges ?? []) {
+    if (!DEP.has(e.kind)) continue;
+    let a = inEdges.get(e.to);
+    if (!a) {
+      a = [];
+      inEdges.set(e.to, a);
+    }
+    a.push(e.from);
+  }
+  const lines = [];
+  for (const f of unique) {
+    const symIds = (g.nodes ?? []).filter((n) => n.kind !== "file" && n.filePath === f).map((n) => n.id);
+    if (!symIds.length) continue;
+    const seen = new Set(symIds);
+    const dependents = new Set();
+    let frontier = symIds.slice();
+    for (let d = 0; d < 6 && frontier.length; d++) {
+      const nextFrontier = [];
+      for (const id of frontier) {
+        for (const from of inEdges.get(id) ?? []) {
+          if (seen.has(from)) continue;
+          seen.add(from);
+          const node = nodeById.get(from);
+          if (node) {
+            dependents.add(node.filePath);
+            nextFrontier.push(from);
+          }
+        }
+      }
+      frontier = nextFrontier;
+    }
+    dependents.delete(f);
+    if (dependents.size) {
+      lines.push(`  ${f} → ${dependents.size} dependent file(s): ${[...dependents].slice(0, 6).join(", ")}${dependents.size > 6 ? " …" : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+if (out.length) process.stdout.write(out.join("\n").trim() + "\n");

package/hooks/verify-checkpoint.mjs

@@ -155,6 +155,49 @@ if (testCmd === false) {
   }
 }
 
+// ---- check 4: typecheck (optional; from tasks/.verify.json or a package.json `typecheck` script) ----
+let typeCmd = null;
+if (existsSync(cfgPath)) {
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    if (cfg.typecheck === false) typeCmd = false;
+    else if (typeof cfg.typecheck === "string") typeCmd = cfg.typecheck;
+  } catch { /* ignore malformed config */ }
+}
+if (typeCmd === null && existsSync(join(cwd, "package.json"))) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+    if (pkg.scripts && pkg.scripts.typecheck) typeCmd = "npm run typecheck";
+  } catch { /* ignore */ }
+}
+
+let typeLine, typeOk = true;
+if (typeCmd === false) {
+  typeLine = "⏭️ typecheck skipped (disabled in tasks/.verify.json)";
+} else if (!typeCmd) {
+  typeLine = "⏭️ no typecheck command found — not checked";
+} else {
+  try {
+    execSync(typeCmd, { cwd, encoding: "utf8", timeout: 120000, stdio: ["ignore", "pipe", "pipe"] });
+    typeLine = `✅ \`${typeCmd}\` passed`;
+  } catch (e) {
+    typeOk = false;
+    const tail = String(e.stdout || e.stderr || "").trim().split(/\r?\n/).filter(Boolean).pop() || "";
+    typeLine = e.killed
+      ? `❌ \`${typeCmd}\` timed out after 120s`
+      : `❌ \`${typeCmd}\` failed (exit ${e.status})${tail ? ": " + tail.slice(0, 160) : ""}`;
+  }
+}
+
+// ---- check 5 (advisory): is the Next step concrete? a vague handoff resumes badly ----
+const nextMatch = doc.match(/##\s*Next step\s*\r?\n+([\s\S]*?)(?:\r?\n##\s|\s*$)/);
+const nextText = nextMatch ? nextMatch[1].replace(/\s+/g, " ").trim() : "";
+const vague = /^(tbd|todo|wip|continue|finish(\s+it)?|make\s+it\s+work|keep\s+going|n\/?a|none)\.?$/i;
+let nextLine;
+if (!nextText) nextLine = "⚠️ no Next step recorded — a resume won't know where to start";
+else if (vague.test(nextText) || nextText.length < 12) nextLine = `⚠️ Next step is vague ("${nextText.slice(0, 60)}") — make it one concrete action`;
+else nextLine = "✅ Next step is concrete";
+
 // ---- check 3: honesty scan of the diff ------------------------------------
 let honestyLine, honestyOk = true;
 if (!isRepo) {
@@ -180,7 +223,7 @@ if (!isRepo) {
 }
 
 // ---- verdict --------------------------------------------------------------
-const allOk = filesOk && testsOk && honestyOk;
+const allOk = filesOk && testsOk && typeOk && honestyOk;
 let verdict;
 if (allOk) verdict = "✅ PASS";
 else if (status === "done") verdict = "❌ FAIL — marked `done` but checks above did not pass";
@@ -191,7 +234,9 @@ const block =
   `## Verification (machine-checked ${stamp})\n` +
   `- Files touched: ${filesLine}\n` +
   `- Tests: ${testsLine}\n` +
+  `- Typecheck: ${typeLine}\n` +
   `- Honesty scan: ${honestyLine}\n` +
+  `- Next step: ${nextLine}\n` +
   `- Verdict: ${verdict}\n`;
 
 // replace any existing Verification section, else append

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardrail/plugin",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Wardrail Claude Code plugin — consult your project's contract while coding (MCP) plus a checkpoint->clear->resume workflow with machine-verified checkpoints.",
   "type": "module",
   "files": [