@wardrail/plugin 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "wardrail",
+  "displayName": "Wardrail",
+  "version": "0.1.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.io" },
+  "homepage": "https://wardrail.io",
+  "license": "UNLICENSED",
+  "keywords": ["wardrail", "guardrails", "mcp", "checkpoint", "context", "ai"],
+  "userConfig": {
+    "WARDRAIL_URL": {
+      "type": "string",
+      "title": "Wardrail URL",
+      "description": "Your Wardrail server. Leave the default unless self-hosting.",
+      "default": "https://wardrail.io",
+      "required": false
+    },
+    "WARDRAIL_INGEST_TOKEN": {
+      "type": "string",
+      "title": "Wardrail ingest token",
+      "description": "Project-scoped token from Wardrail -> Trust -> Attest from CI. Scopes reads to exactly one project; never grants account access.",
+      "sensitive": true,
+      "required": true
+    },
+    "ANTHROPIC_API_KEY": {
+      "type": "string",
+      "title": "Anthropic API key (optional)",
+      "description": "Only needed for wardrail_review_diff. Stays on your machine and goes straight to Anthropic; Wardrail never sees it.",
+      "sensitive": true,
+      "required": false
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "wardrail": {
+      "command": "npx",
+      "args": ["-y", "@wardrail/mcp"],
+      "env": {
+        "WARDRAIL_URL": "${user_config.WARDRAIL_URL}",
+        "WARDRAIL_INGEST_TOKEN": "${user_config.WARDRAIL_INGEST_TOKEN}",
+        "ANTHROPIC_API_KEY": "${user_config.ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}

package/README.md

@@ -0,0 +1,52 @@
+# @wardrail/plugin
+
+The **Wardrail Claude Code plugin**. One install gives your coding agent two things:
+
+1. **The Wardrail contract, while it codes** — the four [`@wardrail/mcp`](https://www.npmjs.com/package/@wardrail/mcp)
+   tools (`get_contract`, `check_path`, `get_findings`, `review_diff`), so 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's allowed to
+   be marked done.
+
+This is the same anti-drift, verify-don't-trust thesis Wardrail applies to your *code*,
+turned on the agent's own working memory.
+
+## Install
+
+```bash
+# add the marketplace (served by Wardrail), then install the plugin
+claude plugin marketplace add https://wardrail.io/marketplace.json
+claude plugin install wardrail@wardrail
+```
+
+At enable time you'll be asked for:
+
+| Value | Required | What it is |
+|---|---|---|
+| `WARDRAIL_URL` | no | Your Wardrail server. Defaults to `https://wardrail.io`. |
+| `WARDRAIL_INGEST_TOKEN` | **yes** | Project-scoped token from Wardrail → **Trust → Attest from CI**. Scopes reads to one project; never grants account access. |
+| `ANTHROPIC_API_KEY` | no | Only for `wardrail_review_diff`. Stays on your machine; Wardrail never sees it. |
+
+These feed the bundled MCP server's environment via `${user_config.*}`. The `@wardrail/mcp`
+server is fetched on demand by `npx`.
+
+## What's in the box
+
+```
+.claude-plugin/plugin.json   manifest + userConfig 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
+.mcp.json                    the Wardrail MCP server (npx -y @wardrail/mcp)
+```
+
+## The workflow
+
+`/checkpoint` → `/clear` → `/task resume <slug>`. Task files live per-project in
+`./tasks/<slug>.md` and carry a small, honest snapshot so a fresh session rehydrates from
+~3k tokens instead of a 150k transcript. `/checkpoint` stamps a tamper-evident
+`## Verification` block; `status: done` over a failed check is downgraded to FAIL.

package/hooks/hooks.json

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

package/hooks/tasks-session-start.mjs

@@ -0,0 +1,58 @@
+#!/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");

package/hooks/verify-checkpoint.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// verify-checkpoint.mjs — machine-produced verification for the tasks plugin.
+//
+// Reconciles a task file's CLAIMS against ground truth, then stamps a tamper-evident
+// `## Verification` block into the file. The model does not narrate this — the script
+// observes git, runs the tests, and scans the diff itself, so a checkpoint cannot claim
+// work that didn't happen. A `status: done` task with any failed check is downgraded to
+// FAIL.
+//
+// Usage:  node verify-checkpoint.mjs [slug]
+//   cwd must be the project root. With no slug, auto-detects the single active task.
+//
+// v1 checks: (1) git Files-touched reconciliation, (2) real test run
+// (tasks/.verify.json override, else package.json `test`), (3) honesty scan of the diff
+// for TODO/FIXME/placeholder. Each check degrades gracefully and never reports a pass
+// it didn't observe.
+
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+
+const cwd = process.cwd();
+const tasksDir = join(cwd, "tasks");
+
+function fail(msg) {
+  process.stderr.write(msg + "\n");
+  process.exit(1);
+}
+
+// ---- locate the task file -------------------------------------------------
+let slug = process.argv[2];
+if (!slug) {
+  if (!existsSync(tasksDir)) fail("No ./tasks/ directory and no slug given.");
+  const active = readdirSync(tasksDir).filter((n) => {
+    if (!n.endsWith(".md")) return false;
+    const fm = readFileSync(join(tasksDir, n), "utf8").match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    return fm && /^status:\s*active\s*$/m.test(fm[1]);
+  });
+  if (active.length === 1) slug = active[0].replace(/\.md$/, "");
+  else fail(`Need a slug — ${active.length} active tasks found.`);
+}
+const taskPath = join(tasksDir, `${slug}.md`);
+if (!existsSync(taskPath)) fail(`No task file at tasks/${slug}.md`);
+let doc = readFileSync(taskPath, "utf8");
+
+// ---- parse claims ---------------------------------------------------------
+const status = (doc.match(/^status:\s*(\w+)/m) || [, "active"])[1];
+
+const ftSection = doc.match(/##\s*Files touched\s*\r?\n([\s\S]*?)(?:\r?\n##\s|\s*$)/);
+const claimedFiles = [];
+if (ftSection) {
+  for (const line of ftSection[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; // skip parenthetical notes / placeholders — real paths never start with "("
+    claimedFiles.push(p.replace(/\\/g, "/"));
+  }
+}
+
+// ---- helpers --------------------------------------------------------------
+const git = (cmd) => execSync(`git ${cmd}`, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+const isRepo = (() => {
+  try {
+    return git("rev-parse --is-inside-work-tree").trim() === "true";
+  } catch {
+    return false;
+  }
+})();
+
+// Resolve a claimed path to an absolute, forward-slashed path (expanding a leading ~).
+const resolveClaim = (claim) => {
+  let p = claim;
+  if (p === "~" || p.startsWith("~/")) p = join(homedir(), p.slice(1));
+  else if (!isAbsolute(p)) p = join(cwd, p);
+  return p.replace(/\\/g, "/");
+};
+// Repo root (toplevel) — used to tell in-repo claims from ones the verifier can't see.
+const repoRoot = (() => {
+  if (!isRepo) return cwd.replace(/\\/g, "/");
+  try { return git("rev-parse --show-toplevel").trim().replace(/\\/g, "/"); }
+  catch { return cwd.replace(/\\/g, "/"); }
+})();
+const insideRepo = (abs) => (abs + "/").startsWith(repoRoot.replace(/\/+$/, "") + "/");
+
+// ---- check 1: files-touched reconciliation --------------------------------
+let filesLine, filesOk = true;
+if (!isRepo) {
+  filesLine = "⏭️ not a git repo — file claims unverified";
+} else {
+  const changed = [];
+  for (const raw of git("status --porcelain").split(/\r?\n/)) {
+    if (!raw.trim()) continue;
+    let p = raw.slice(3).trim().replace(/^"|"$/g, "");
+    if (p.includes(" -> ")) p = p.split(" -> ")[1];
+    p = p.replace(/\\/g, "/");
+    if (p.startsWith("tasks/")) continue; // ignore the task file & its sidecars
+    changed.push(p);
+  }
+  const matches = (claim, real) => real === claim || real.endsWith("/" + claim) || claim.endsWith("/" + real) || real.endsWith(claim);
+  const unmetAll = claimedFiles.filter((c) => !changed.some((r) => matches(c, r)));
+  // A claim git can't reconcile is only a contradiction if it's missing or in-repo-but-unchanged.
+  // One that exists on disk but outside this repo is unverifiable here, not a lie — don't fail on it.
+  const unmet = [], unverifiable = [];
+  for (const c of unmetAll) {
+    const abs = resolveClaim(c);
+    if (existsSync(abs) && !insideRepo(abs)) unverifiable.push(c);
+    else unmet.push(c);
+  }
+  const unclaimed = changed.filter((r) => !claimedFiles.some((c) => matches(c, r)));
+  const parts = [];
+  if (claimedFiles.length === 0) parts.push("no files claimed");
+  if (unmet.length) { parts.push("❌ claimed but not changed: " + unmet.join(", ")); filesOk = false; }
+  if (unverifiable.length) parts.push("⏭️ claimed but outside this repo — unverifiable here: " + unverifiable.join(", "));
+  if (unclaimed.length) parts.push("⚠️ changed but not claimed: " + unclaimed.join(", "));
+  if (filesOk && !unverifiable.length && !unclaimed.length && claimedFiles.length)
+    parts.push(`✅ all ${claimedFiles.length} claimed path(s) present in the working tree`);
+  filesLine = parts.join("; ");
+}
+
+// ---- check 2: tests -------------------------------------------------------
+let testCmd = null;
+const cfgPath = join(tasksDir, ".verify.json");
+if (existsSync(cfgPath)) {
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    if (cfg.test === false) testCmd = false;
+    else if (typeof cfg.test === "string") testCmd = cfg.test;
+  } catch { /* ignore malformed config */ }
+}
+if (testCmd === null && existsSync(join(cwd, "package.json"))) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+    if (pkg.scripts && pkg.scripts.test) testCmd = "npm test";
+  } catch { /* ignore */ }
+}
+
+let testsLine, testsOk = true;
+if (testCmd === false) {
+  testsLine = "⏭️ tests skipped (disabled in tasks/.verify.json)";
+} else if (!testCmd) {
+  testsLine = "⏭️ no test command found — test status unverified";
+} else {
+  try {
+    execSync(testCmd, { cwd, encoding: "utf8", timeout: 120000, stdio: ["ignore", "pipe", "pipe"] });
+    testsLine = `✅ \`${testCmd}\` passed`;
+  } catch (e) {
+    testsOk = false;
+    const tail = String(e.stdout || e.stderr || "").trim().split(/\r?\n/).filter(Boolean).pop() || "";
+    testsLine = e.killed
+      ? `❌ \`${testCmd}\` timed out after 120s`
+      : `❌ \`${testCmd}\` failed (exit ${e.status})${tail ? ": " + tail.slice(0, 160) : ""}`;
+  }
+}
+
+// ---- check 3: honesty scan of the diff ------------------------------------
+let honestyLine, honestyOk = true;
+if (!isRepo) {
+  honestyLine = "⏭️ not a git repo — diff not scanned";
+} else {
+  let diff = "";
+  try { diff = git("diff HEAD"); } catch { try { diff = git("diff"); } catch { /* no diff */ } }
+  const pat = /\b(TODO|FIXME|XXX|HACK)\b|not implemented|placeholder/i;
+  const hits = [];
+  let file = "";
+  for (const line of diff.split(/\r?\n/)) {
+    if (line.startsWith("+++ b/")) { file = line.slice(6); continue; }
+    if (line.startsWith("+") && !line.startsWith("+++") && pat.test(line)) {
+      hits.push(`${file}: ${line.slice(1).trim().slice(0, 80)}`);
+    }
+  }
+  if (hits.length) {
+    honestyOk = false;
+    honestyLine = `❌ ${hits.length} unfinished marker(s) in diff — ` + hits.slice(0, 3).join(" | ") + (hits.length > 3 ? " …" : "");
+  } else {
+    honestyLine = "✅ no TODO/FIXME/placeholder in the diff";
+  }
+}
+
+// ---- verdict --------------------------------------------------------------
+const allOk = filesOk && testsOk && honestyOk;
+let verdict;
+if (allOk) verdict = "✅ PASS";
+else if (status === "done") verdict = "❌ FAIL — marked `done` but checks above did not pass";
+else verdict = "⚠️ WARN — open issues above (acceptable while `status: active`)";
+
+const stamp = new Date().toISOString();
+const block =
+  `## Verification (machine-checked ${stamp})\n` +
+  `- Files touched: ${filesLine}\n` +
+  `- Tests: ${testsLine}\n` +
+  `- Honesty scan: ${honestyLine}\n` +
+  `- Verdict: ${verdict}\n`;
+
+// replace any existing Verification section, else append
+doc = doc.replace(/\n##\s*Verification[\s\S]*?(?=\n##\s|\s*$)/, "").replace(/\s*$/, "\n");
+writeFileSync(taskPath, doc + "\n" + block, "utf8");
+
+process.stdout.write(`Verification stamped into tasks/${slug}.md\n\n${block}`);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@wardrail/plugin",
+  "version": "0.1.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": [
+    ".claude-plugin",
+    "skills",
+    "hooks",
+    ".mcp.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "wardrail",
+    "claude-code",
+    "claude-code-plugin",
+    "mcp",
+    "guardrails",
+    "checkpoint"
+  ],
+  "license": "UNLICENSED",
+  "private": false
+}

package/skills/checkpoint/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: checkpoint
+description: "Write the current working state into the active task file right before a /clear, so a fresh session can resume cheaply. This is the critical step in the checkpoint→clear→resume workflow — run it whenever a long session is getting expensive and the work isn't finished. Pairs with the `task` skill."
+---
+
+# Checkpoint
+
+Capture everything the next session needs into `./tasks/<slug>.md`, then hand off. The
+flow this completes is: **`/checkpoint` → `/clear` → `/task resume <slug>`**. After the
+checkpoint, the transcript is disposable; the task file carries the state.
+
+## Steps
+
+1. **Find the active task.** Look in `./tasks/` for files with `status: active`.
+   - Exactly one → use it.
+   - Several → ask which one (or checkpoint the one this session was actually working
+     on, if that's unambiguous).
+   - None → offer to run `/task new <slug>` first.
+
+2. **Update the file to reflect reality now.** Edit in place:
+   - **Objective** — sharpen only if it genuinely changed; don't churn it.
+   - **Decisions** — append choices settled this session, each with its one-line reason,
+     so the next session doesn't relitigate them.
+   - **Files touched** — add/adjust the paths changed this session with a short note.
+   - **Next step** — the single most important thing: the exact next concrete action,
+     specific enough to start cold. One action, not a list.
+
+3. **Be honest.** Write only what is actually true right now. Do not record planned
+   work as done, do not claim a passing test you didn't run. A false checkpoint is
+   worse than none — it makes the next session build on a lie.
+
+4. **Redirect heavy outputs.** If this session generated large tool outputs (build logs,
+   test dumps) worth keeping, note their file path in the task file and `tail` them —
+   don't paste them in. Big outputs are a top context cost.
+
+5. **Verify against ground truth — do not self-attest.** From the project root, run:
+   `node "${CLAUDE_PLUGIN_ROOT}/hooks/verify-checkpoint.mjs" <slug>`. It reconciles the
+   file's claims against `git`, a real test run, and a diff scan, then writes a
+   `## Verification` block into the task file itself. Then:
+   - Read the verdict. If it is **not PASS**, the checkpoint is not done: either fix the
+     underlying issue and re-run, or keep `status: active` and point Next step at exactly
+     what the verdict flagged. **Never set `status: done` over a FAIL.**
+   - Do not hand-edit the `## Verification` block — it is the machine's record, not
+     yours. Surface the verdict to the user in your handoff.
+   - If verification can't apply (not a git repo, files live outside this repo, no
+     tests), say so plainly rather than implying a pass.
+
+6. **Drop the clear-ready sentinel.** Write the active task's slug into
+   `./tasks/.clear-ready` (overwrite; create if missing). This is a transient marker the
+   `Stop` hook consumes once to back up the clear nudge — it deletes itself, so it
+   normally won't linger in the working tree.
+
+7. **Hand off.** Confirm the path written, the verification verdict, and the Next step,
+   then tell the user it's safe to `/clear` and later run `/task resume <slug>`.
+
+## Why manual
+
+Auto-clearing is unsafe: judging whether work is at a clean stopping point needs
+judgment. Two keystrokes (`/checkpoint`, then `/clear`) is the target — deliberate, not
+automatic. This cannot beat `/compact` *within* a session; it makes the boundary
+between sessions cheap. See [task] for the file format and resume step.

package/skills/task/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: task
+description: "Manage long-session task files for the checkpoint→clear→resume workflow. Invoke as `/task new <slug>` to scaffold a task file, or `/task resume <slug>` to rehydrate a fresh session from one. Task files live in ./tasks/ in the current project. The point is to make /clear cheap: resume reloads a ~3k-token brief instead of carrying a 150k transcript."
+---
+
+# Task files
+
+A task file at `./tasks/<slug>.md` (relative to the current project) is a small,
+honest snapshot of in-flight work. It exists so a long session can be `/clear`-ed and
+a fresh one rehydrated from ~3k tokens instead of the whole transcript. The savings
+happen at the boundary between sessions, not within one.
+
+The model is stateless and the harness re-sends the full transcript every turn — you
+cannot make the AI "read less from the top." The only lever is a smaller window. Task
+files are that lever: cheap rehydration after `/clear`.
+
+## File format
+
+```markdown
+---
+status: active        # active | done
+related: []           # other task slugs this depends on, e.g. [auth-rework]
+---
+
+# <One-line objective title>
+
+## Objective
+What "done" means, stated so it can be verified (a test, a command, an observable
+behaviour). Not "make it work."
+
+## Decisions
+- Settled choices not to relitigate, each with the one-line reason.
+
+## Files touched
+- path/to/file — what changed / what it's for
+
+## Next step
+The single next concrete action. One thing, not a list.
+```
+
+## Dispatch on the argument
+
+### `/task new <slug>`
+
+1. Ensure `./tasks/` exists (create it if not).
+2. If `./tasks/<slug>.md` already exists, stop and say so — do not overwrite.
+3. Write the scaffold above. Fill **Objective** from the current conversation if there
+   is enough context to state it verifiably; otherwise leave a one-line prompt for the
+   user to complete. Leave Decisions / Files touched / Next step minimal but real —
+   never invent progress that hasn't happened.
+4. Tell the user the path and that `/checkpoint` will keep it current before a `/clear`.
+
+### `/task resume <slug>`
+
+1. Read `./tasks/<slug>.md`. If `status: done`, say so and ask whether to reopen.
+2. Read each task listed in `related:` (those files only).
+3. Read **only** the files named under "Files touched" that you actually need for the
+   Next step — not the whole repo. CLAUDE.md and memory are already auto-loaded; do not
+   re-read them.
+4. Give the user a 3–5 line orientation: the Objective, the key Decisions, and the
+   Next step you're about to take. Then proceed with that Next step.
+
+Load nothing beyond the above. Pulling in extra context defeats the purpose.
+
+## Honesty
+
+A stale or optimistic task file is worse than none — it misleads the next session into
+building on work that didn't happen. Everything written must be true at write time.
+See [checkpoint] for the write-before-clear step.