receipts-cli 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaheer Shoaib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# receipts
+
+**Agents need receipts.**
+
+Your AI coding agent just told you it fixed the bug. Did it?
+
+`receipts` is a verification layer for AI-written code. It does not make your agent
+faster or more autonomous - the whole industry is already building that. It does the
+opposite: it **re-proves the agent's claim before you trust it.** An agent can type
+"Fixed ✅"; it cannot fake the reported symptom still being there when `receipts`
+re-runs it.
+
+> Everyone is shipping gas: faster agents, bigger swarms. This ships brakes.
+
+---
+
+## The problem
+
+An agent fixes a bug, runs the tests, sees green, and closes the ticket: "Fixed."
+The tests passed. The code looks right. CI is happy. And the bug is still there -
+because the test exercised the wrong thing, or the fix landed on the wrong surface,
+or the change painted correctly in dev and broke in prod, or it patched the symptom
+and not the cause.
+
+Real example this was built from: a "modal is cut off" report was read as a vertical
+clip. A height cap was written, tested, deployed, and "verified" green - while the
+real bug was the modal being too *narrow*. The wrong axis shipped. Only a human
+caught it. Every team using AI to write code is hitting some version of this, daily.
+
+The missing referee is simple to state and hard to enforce: **a fix is not done
+because the agent says so. It is done when the reported symptom is observably gone
+on the deployed build.**
+
+## The core move: don't trust, re-verify
+
+A "looks fixed" screenshot is not a receipt - an agent can produce one for a bug it
+never fixed. A *receipt* is the symptom's own acceptance test, re-run against the
+real build, coming back clean. `receipts` re-runs it. The agent does not get to
+grade its own homework.
+
+## How it works: the Seven Gates
+
+The Seven Gates (`spec/SEVEN-GATES.md`) are the standard a fix must clear. Each one
+exists because skipping it shipped a wrong or unverified "fix" at least once - every
+gate carries the real scar that motivated it.
+
+They split into two kinds:
+
+| Gate | Job | Where it lives |
+|---|---|---|
+| **G0** reproduce the symptom (it IS your acceptance test) | verify | PR / CI (re-run) |
+| **G1** assert the rendered VALUE, not a placeholder | verify | PR / CI (re-run) |
+| **G3** verify on the build that carries YOUR commit | verify | PR / CI |
+| **G5** drive the flow to its TERMINAL action | verify | PR / CI (re-run) |
+| **G2** pin the EXACT flow / component | target | agent-side |
+| **G4** land on the surface the reporter SEES | target | agent-side |
+| **G6** sweep the changed pattern's parallel TWINS | target | agent-side |
+
+The **verify** gates (did you actually prove it works) are enforceable at the one
+chokepoint every team shares regardless of which agent they use: the PR. The
+**target** gates (did you fix the *right* thing) live inside the agent's loop, and
+ship as adapters.
+
+## What's in here
+
+- **`spec/`** - the Seven Gates standard. The IP. Each gate + its real scar.
+- **`enforcer/`** - the universal piece: a GitHub Action that fails a "fixed" PR
+  unless it carries, and *survives*, the receipt (the changed test must be red on
+  base, green on head). Agent-agnostic - works no matter who or what wrote the code.
+- **`plugin/`** - a Claude Code plugin (the agent adapter): teaches your agent to
+  produce receipts as it works, so its PRs pass the gate naturally.
+- **`plugin/mcp/trajectory-kb/`** - the memory layer: what was tried on a surface and
+  how it turned out, so the gates *learn* and stop the team repeating the same trap.
+
+## Install
+
+Two independent paths - use either or both.
+
+**Enforce it at the PR (any agent):**
+```yaml
+# .github/workflows/receipts.yml  (full template: enforcer/example-workflow.yml)
+on: pull_request
+jobs:
+  receipts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4    # + your deps install (swap per stack)
+      - uses: shaheershoaib/receipts/enforcer@main
+```
+
+**Teach your agent to pass it (Claude Code):**
+```bash
+claude plugin marketplace add shaheershoaib/receipts
+claude plugin install receipts
+```
+
+**Configure it for your project (any stack, any platform):**
+```bash
+npx receipts-cli init   # detects your stack + deploy target, confirms, writes receipts.config.json
+# not published to npm yet? run it straight from the repo, no install:
+# npx github:shaheershoaib/receipts init
+```
+
+It works across any repo because the gate *logic* ships generic and only the project
+*plumbing* (how to test, where it deploys, what marks a fix-claim) is detected per
+project. See [enforcer/GENERALIZATION.md](enforcer/GENERALIZATION.md) for how,
+[enforcer/INIT.md](enforcer/INIT.md) for what `init` detects vs asks, and
+[receipts.config.example.json](receipts.config.example.json) for the output.
+
+## Status
+
+Honest: the *discipline* is battle-tested - it has run a production codebase's bug
+pipeline for months and caught real money-path regressions.
+
+Built and working today:
+- the Seven Gates spec (`spec/SEVEN-GATES.md`)
+- the focused `seven-gates` agent skill + two Stop-hook backstops (the Claude Code adapter)
+- the `trajectory-kb` memory MCP
+- `receipts init` - detects stack + deploy target, confirms, writes `receipts.config.json`
+- the **CI enforcer** (`enforcer/`) - the red->green re-verification at the PR, as a GitHub Action
+
+Next: `verify.live_drive` for symptoms a test can't express (drive the deployed app),
+and an `examples/` demo of a caught wrong-fix.
+
+## License
+
+MIT. (The verification discipline should be free and everywhere.)

package/bin/receipts.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * receipts CLI
+ *
+ * `receipts init` detects a project's plumbing (how it tests, where it deploys,
+ * what marks a fix-claim) AND its loop-skill harnesses (the skills that drive the
+ * trajectory-kb and that the Stop hooks watch), confirms with you, writes
+ * receipts.config.json, and - if the project has no fix/build loop skill - scaffolds
+ * one from the bundled template so a clean install reaches parity with no hand-edits.
+ *
+ * `receipts doctor` re-detects and reports drift against the current config.
+ *
+ * Zero dependencies - Node built-ins only - so it runs with `npx receipts` or a
+ * bare `node bin/receipts.js` and never needs an install step.
+ */
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+const HELP = `receipts - verification gates for AI-written code
+
+Usage:
+  receipts init [options]     Detect this project, confirm, write receipts.config.json
+                              (+ scaffold a loop-skill harness if none exists)
+  receipts doctor [options]   Re-detect and report drift against receipts.config.json
+
+Options:
+  --dir <path>   Target repo (default: current directory)
+  --yes, -y      Accept detected values, skip prompts (CI / scripted)
+  --print        Print the config to stdout, do not write a file (init)
+  --force        Overwrite an existing receipts.config.json (init)
+  --no-scaffold  Do not scaffold a loop-skill harness even if none is found (init)
+  --help, -h     Show this help
+`;
+
+const readText = (p) => { try { return fs.readFileSync(p, "utf8"); } catch { return null; } };
+const readJson = (p) => { const t = readText(p); if (!t) return null; try { return JSON.parse(t); } catch { return null; } };
+const exists = (p) => { try { fs.accessSync(p); return true; } catch { return false; } };
+const dedupe = (arr) => [...new Set(arr.filter(Boolean))];
+
+// Detect the project's plumbing + loop-skill harnesses from on-disk artifacts.
+// Never throws.
+function detect(dir) {
+  const at = (f) => path.join(dir, f);
+  const has = (f) => exists(at(f));
+  const hasExt = (ext) => { try { return fs.readdirSync(dir).some((f) => f.endsWith(ext)); } catch { return false; } };
+
+  // --- test runner ---
+  let stack = null, test_command = null, suite_command = null;
+  const pkg = readJson(at("package.json"));
+  if (pkg && pkg.scripts && pkg.scripts.test) {
+    const runner = has("pnpm-lock.yaml") ? "pnpm" : has("yarn.lock") ? "yarn" : "npm";
+    stack = "node";
+    suite_command = `${runner} test`;
+    test_command = runner === "npm" ? "npm test -- {test}" : `${runner} test {test}`;
+  } else if (has("manage.py")) {
+    stack = "django"; suite_command = "python manage.py test"; test_command = "python manage.py test {test}";
+  } else if (has("pyproject.toml") || has("pytest.ini") || has("setup.cfg") || has("tox.ini")) {
+    stack = "python"; suite_command = "pytest"; test_command = "pytest {test}";
+  } else if (has("go.mod")) {
+    stack = "go"; suite_command = "go test ./..."; test_command = "go test -run {test} ./...";
+  } else if (has("Gemfile")) {
+    stack = "ruby"; suite_command = "bundle exec rspec"; test_command = "bundle exec rspec {test}";
+  } else if (has("Cargo.toml")) {
+    stack = "rust"; suite_command = "cargo test"; test_command = "cargo test {test}";
+  } else if (has("pom.xml")) {
+    stack = "maven"; suite_command = "mvn test"; test_command = "mvn -Dtest={test} test";
+  } else if (has("build.gradle") || has("build.gradle.kts")) {
+    stack = "gradle"; suite_command = "gradle test"; test_command = "gradle test --tests {test}";
+  } else if (hasExt(".csproj") || hasExt(".sln") || hasExt(".fsproj")) {
+    stack = "dotnet"; suite_command = "dotnet test"; test_command = "dotnet test --filter {test}";
+  } else if (has("composer.json")) {
+    stack = "php"; suite_command = "vendor/bin/phpunit"; test_command = "vendor/bin/phpunit {test}";
+  } else if (has("mix.exs")) {
+    stack = "elixir"; suite_command = "mix test"; test_command = "mix test {test}";
+  } else if (has("Makefile") && /(^|\n)test:/.test(readText(at("Makefile")) || "")) {
+    stack = "make"; suite_command = "make test"; test_command = "make test";
+  }
+
+  // --- deploy platform ---
+  let platform = "none", sha_source = "none", deploy_host_patterns = [];
+  const platforms = [
+    ["vercel",  () => has("vercel.json") || has(".vercel"),            ["*.vercel.app"]],
+    ["railway", () => has("railway.json") || has("railway.toml"),      ["*.up.railway.app", "*.railway.app"]],
+    ["netlify", () => has("netlify.toml"),                            ["*.netlify.app"]],
+    ["fly",     () => has("fly.toml"),                                ["*.fly.dev"]],
+    ["render",  () => has("render.yaml"),                             ["*.onrender.com"]],
+    ["cloudflare", () => has("wrangler.toml") || has("wrangler.jsonc") || has("wrangler.json"), ["*.workers.dev", "*.pages.dev"]],
+  ];
+  for (const [name, test, hosts] of platforms) {
+    if (test()) { platform = name; deploy_host_patterns = hosts; break; }
+  }
+  if (platform !== "none") sha_source = "github-deployments";
+
+  // --- loop-skill harnesses (the skills that drive the trajectory-kb + the hooks
+  //     watch). Scan .claude/skills/*/SKILL.md; a skill whose name or body reads
+  //     like a fix/build loop is a candidate. ---
+  let loop_skills = [];
+  const skillsDir = at(".claude/skills");
+  try {
+    for (const name of fs.readdirSync(skillsDir)) {
+      const sk = path.join(skillsDir, name, "SKILL.md");
+      if (!exists(sk)) continue;
+      // Scan the NAME + the frontmatter description only - the body has incidental
+      // keywords ("fix"/"build") that over-match (an audit skill is not a loop).
+      const txt = readText(sk) || "";
+      const fm = (txt.match(/^---\s*[\r\n]([\s\S]*?)[\r\n]---/) || ["", ""])[1];
+      const desc = ((fm.match(/description:\s*([\s\S]*)/i) || ["", ""])[1] || "").slice(0, 400);
+      const nameHay = name.toLowerCase();
+      if (/loop|retest|feedback|parity|cycle/.test(nameHay + " " + desc.toLowerCase()) || /fix/.test(nameHay)) {
+        loop_skills.push(name);
+      }
+    }
+  } catch { /* no .claude/skills dir */ }
+
+  const repo_name = (pkg && pkg.name) || path.basename(dir);
+  return { stack, test_command, suite_command, platform, sha_source, deploy_host_patterns, loop_skills, repo_name };
+}
+
+function buildConfig(d, a) {
+  const cfg = {
+    version: 1,
+    claim: {
+      issue_link: "closes #(\\d+)",
+      downgrade_tags: ["unverified-reasoned", "speculative", "reverted"],
+    },
+    build: {
+      sha_source: d.sha_source,
+      platform: d.platform,
+      deploy_host_patterns: dedupe([...(d.deploy_host_patterns || []), ...(a.extra_hosts || [])]),
+      environments: a.environments || {},
+      verify_against: a.verify_against || (d.platform !== "none" ? "staging" : "none"),
+    },
+    verify: {
+      test_command: a.test_command || d.test_command || "REPLACE_ME: how to run ONE acceptance test (use {test} for the path)",
+      suite_command: d.suite_command || null,
+      live_drive: null,
+    },
+    degrade: {
+      on_no_receipt: "require-downgrade-tag",
+      on_unreachable_build: "sha-bind-only",
+    },
+    agent: {
+      // "seven-gates" (the shipped loop) is always watched; project loops merge in.
+      loop_skills: dedupe(["seven-gates", ...(a.loop_skills || d.loop_skills || [])]),
+      staging_query_patterns: a.staging_query_patterns || [],
+      closeout_fixed_statuses: a.closeout_fixed_statuses || ["Pending Retest", "Verified"],
+      repo_name: a.repo_name || d.repo_name,
+    },
+  };
+  // Agent-home (skills + cwd, no tests and no deploy): keep only version/claim/agent;
+  // the enforcer config (build/verify) belongs in the code repos.
+  if (!(a.test_command || d.test_command) && d.platform === "none") {
+    delete cfg.build; delete cfg.verify; delete cfg.degrade;
+    delete cfg.agent.repo_name; // no single repo at the agent home; each append names its repo
+  }
+  return cfg;
+}
+
+// Fill the bundled loop-skill template and write it into the project's skills dir.
+function scaffoldHarness(dir, vars) {
+  const tmplPath = path.join(__dirname, "..", "plugin", "templates", "loop-skill", "SKILL.md.tmpl");
+  let tmpl = readText(tmplPath);
+  if (!tmpl) return null;
+  for (const [k, v] of Object.entries(vars)) tmpl = tmpl.split(`{{${k}}}`).join(v);
+  const outDir = path.join(dir, ".claude", "skills", vars.loop_name);
+  try {
+    fs.mkdirSync(outDir, { recursive: true });
+    const outPath = path.join(outDir, "SKILL.md");
+    if (exists(outPath)) return outPath; // don't clobber an existing skill
+    fs.writeFileSync(outPath, tmpl);
+    return outPath;
+  } catch { return null; }
+}
+
+const ask = (rl, q, def) =>
+  new Promise((res) => rl.question(def ? `${q} [${def}] ` : `${q} `, (x) => res((x || "").trim() || def || "")));
+const list = (s) => (s || "").split(",").map((x) => x.trim()).filter(Boolean);
+
+async function init(opts) {
+  const dir = path.resolve(opts.dir || process.cwd());
+  if (!exists(dir)) { console.error(`No such directory: ${dir}`); process.exit(1); }
+  const outPath = path.join(dir, "receipts.config.json");
+  if (exists(outPath) && !opts.force && !opts.print) {
+    console.error("receipts.config.json already exists. Re-run with --force to overwrite, --print to preview, or `receipts doctor` to check drift.");
+    process.exit(1);
+  }
+
+  const d = detect(dir);
+  // Agent-home = skills + session cwd with no tests and no deploy (e.g. a skills
+  // project separate from the code repos): write an agent-only config (no build/verify).
+  const agentHome = !d.test_command && d.platform === "none";
+  // Diagnostics go to stderr so --print keeps stdout pure JSON.
+  console.error(`receipts init - scanning ${dir}\n`);
+  console.error("  detected:");
+  console.error(`    stack       ${d.stack || (agentHome ? "agent-home (skills, no code)" : "unknown")}`);
+  console.error(`    tests       ${d.test_command || (agentHome ? "none here (enforcer config lives in the code repos)" : "NOT DETECTED (you'll set verify.test_command)")}`);
+  console.error(`    deploy      ${d.platform === "none" ? "none" : d.platform}`);
+  console.error(`    loop skills ${d.loop_skills.length ? d.loop_skills.join(", ") : "none found (seven-gates ships with the plugin)"}`);
+  console.error("");
+
+  const a = {};
+  if (!opts.yes) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+      if (!d.test_command && !agentHome) a.test_command = await ask(rl, "How do you run ONE test? (use {test} for the path)", "");
+      if (d.platform !== "none") {
+        const env = await ask(rl, "Which environment should receipts re-verify on?", "staging");
+        const url = await ask(rl, `URL of '${env}'? (blank to fill in later)`, "");
+        a.verify_against = env;
+        if (url) a.environments = { [env]: url };
+      }
+      // Loop-skill harnesses: which skills the trajectory hooks watch + that drive the kb.
+      const loopDef = dedupe(["seven-gates", ...d.loop_skills]).join(", ");
+      a.loop_skills = list(await ask(rl, "Which skills are your fix/build loops? (comma-separated)", loopDef));
+      // Offer to scaffold one if the project has no loop skill of its own.
+      const hasProjectLoop = a.loop_skills.some((s) => s !== "seven-gates");
+      if (!hasProjectLoop && !opts["no-scaffold"]) {
+        const yn = await ask(rl, `No project loop skill found. Scaffold one (${d.repo_name}-fix-loop) from the template?`, "Y");
+        if (/^y(es)?$/i.test(yn)) a._scaffold = true;
+      }
+      const xh = list(await ask(rl, "Extra deploy/prod hosts beyond detected? (comma-separated, blank to skip)", ""));
+      if (xh.length) a.extra_hosts = xh;
+      const sq = list(await ask(rl, "By-value query hosts/tools (e.g. a DB proxy host)? (blank to skip)", ""));
+      if (sq.length) a.staging_query_patterns = sq;
+      const go = await ask(rl, "Write receipts.config.json with the above?", "Y");
+      if (!/^y(es)?$/i.test(go)) { console.error("Aborted."); rl.close(); process.exit(1); }
+    } finally { rl.close(); }
+  } else {
+    // --yes: register the shipped loop + any detected project loops; scaffold if none.
+    a.loop_skills = dedupe(["seven-gates", ...d.loop_skills]);
+    if (!d.loop_skills.length && !opts["no-scaffold"]) a._scaffold = true;
+  }
+
+  // Scaffold the harness (before building config, so we can register its name).
+  if (a._scaffold && !opts.print) {
+    const loop_name = `${d.repo_name}-fix-loop`;
+    const written = scaffoldHarness(dir, {
+      loop_name,
+      repo_name: d.repo_name,
+      test_command: d.test_command || a.test_command || "<your test command>",
+      platform: d.platform,
+      verify_against_url:
+        (a.environments && a.verify_against && a.environments[a.verify_against]) ||
+        "your deployed build",
+    });
+    if (written) {
+      a.loop_skills = dedupe([...(a.loop_skills || []), loop_name]);
+      console.error(`\nScaffolded loop-skill harness: ${written}`);
+    }
+  }
+
+  const json = JSON.stringify(buildConfig(d, a), null, 2) + "\n";
+  if (opts.print) { process.stdout.write(json); return; }
+  fs.writeFileSync(outPath, json);
+  JSON.parse(fs.readFileSync(outPath, "utf8")); // round-trip validate
+  console.error(`\nWrote ${outPath}`);
+  if (agentHome) {
+    console.error("Agent-home config (skills + cwd, no build/verify). The Stop hooks read it for");
+    console.error("loop skills / hosts / fixed-statuses. Put it at ~/.claude/receipts.config.json to");
+    console.error("apply across every session, or in the project root. Run init in your CODE repos");
+    console.error("too - there it writes the enforcer's verify/build config.");
+  } else {
+    console.error("Review it, then commit. The Stop hooks read it (loop skills, hosts, fixed-statuses);");
+    console.error("the enforcer reads it (test command, sha source). Each fix still carries its own red->green receipt.");
+  }
+}
+
+function doctor(opts) {
+  const dir = path.resolve(opts.dir || process.cwd());
+  const cfg = readJson(path.join(dir, "receipts.config.json"));
+  if (!cfg) { console.error("No receipts.config.json here - run `receipts init`."); process.exit(1); }
+  const d = detect(dir);
+  const drift = [];
+  if (d.test_command && cfg.verify && cfg.verify.test_command && d.test_command !== cfg.verify.test_command)
+    drift.push(`test_command: config "${cfg.verify.test_command}" vs detected "${d.test_command}"`);
+  if (!cfg.verify || !cfg.verify.test_command || /REPLACE_ME/.test(cfg.verify.test_command || ""))
+    drift.push("verify.test_command is unset/placeholder");
+  if (d.platform !== "none" && cfg.build && d.platform !== cfg.build.platform)
+    drift.push(`platform: config "${cfg.build.platform}" vs detected "${d.platform}"`);
+  const cfgLoops = (cfg.agent && cfg.agent.loop_skills) || [];
+  const missing = (d.loop_skills || []).filter((s) => !cfgLoops.includes(s));
+  if (missing.length) drift.push(`loop skills on disk but not in config.agent.loop_skills: ${missing.join(", ")}`);
+  if (!cfg.agent) drift.push("config has no `agent` block - the Stop hooks will use generic defaults (re-init to bind project loops/hosts)");
+
+  if (!drift.length) { console.error("receipts doctor: config looks current."); return; }
+  console.error("receipts doctor: drift detected:\n  - " + drift.join("\n  - ") + "\n\nRe-run `receipts init --force` to refresh.");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const o = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const x = argv[i];
+    if (x === "--dir") o.dir = argv[++i];
+    else if (x === "--yes" || x === "-y") o.yes = true;
+    else if (x === "--print") o.print = true;
+    else if (x === "--force") o.force = true;
+    else if (x === "--no-scaffold") o["no-scaffold"] = true;
+    else if (x === "--help" || x === "-h") o.help = true;
+    else o._.push(x);
+  }
+  return o;
+}
+
+async function main() {
+  const o = parseArgs(process.argv.slice(2));
+  const cmd = o._[0];
+  if (o.help || !cmd) { process.stdout.write(HELP); return; }
+  if (cmd === "init") return init(o);
+  if (cmd === "doctor") return doctor(o);
+  console.error(`Unknown command: ${cmd}\n`);
+  process.stdout.write(HELP);
+  process.exit(1);
+}
+
+main().catch((e) => { console.error(e && e.message ? e.message : e); process.exit(1); });

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "receipts-cli",
+  "version": "0.1.3",
+  "description": "Verification gates for AI-written code - re-prove an agent's fix before you trust it.",
+  "bin": {
+    "receipts": "bin/receipts.js"
+  },
+  "scripts": {
+    "init": "node bin/receipts.js init"
+  },
+  "keywords": ["verification", "ai-agents", "code-review", "ci", "gates", "claude-code"],
+  "author": "Shaheer Shoaib <shaheershoaib11@gmail.com>",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/shaheershoaib/receipts.git" },
+  "files": ["bin", "plugin/templates", "receipts.config.schema.json", "receipts.config.example.json", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugin/README.md

@@ -0,0 +1,61 @@
+# plugin (the Claude Code adapter)
+
+Teaches a Claude Code agent to *produce receipts* as it works, so its fixes clear the
+Seven Gates before a PR is ever opened. This is the agent-side half of `receipts`
+(the PR-side half is `../enforcer`).
+
+## What it provides
+
+- **`skills/seven-gates/`** - the gates as an agent skill: reproduce-first (G0),
+  pin the exact flow (G2), verify by value on the deployed build (G1), land on the
+  surface the reporter sees (G4), drive to the terminal action (G5), sweep the twins
+  (G6), confirm the sha (G3), and write the red->green receipt. Project-agnostic by
+  design - a project supplies its own facts via `receipts.config.json`.
+- **`hooks/stop-verification-gate.py`** - the backstop: blocks a "fixed" close-out
+  that lacks deployed-build evidence (binding + observation). The local precursor to
+  the CI enforcer.
+- **`hooks/stop-trajectory-reminder.py`** - nudges the agent to record what was tried
+  on a surface and how it turned out, so the memory grows (and captures failures, not
+  just wins).
+- Pairs with the **`../mcp/trajectory-kb`** server (the verification memory).
+
+## Wiring
+
+Claude Code AUTO-DISCOVERS the components from the plugin root: `skills/`,
+`hooks/hooks.json` (the two Stop hooks, referenced via `${CLAUDE_PLUGIN_ROOT}`), and
+`.mcp.json` (the `trajectory-kb` server). The manifest does NOT declare these standard
+paths - declaring a path that resolves to an auto-loaded file fails the load with a
+"Duplicate ... detected" error, so `plugin.json` carries metadata only. Installing the
+plugin registers all three - no hand-editing of settings.json and no `claude mcp add`.
+`claude plugin validate` passes (note: it checks manifest SYNTAX, not the load-time
+duplicate-path error, which only surfaces in `claude plugin list`).
+
+## Project-specifics are config-driven (no hand-editing)
+
+The hooks ship sensible generic defaults and MERGE config overrides from
+`receipts.config.json` - the agent-home `~/.claude/receipts.config.json` as a base,
+with the nearest project `receipts.config.json` (walked up from the session cwd)
+merged over it. So a clean install + `receipts init` tunes them with no hand-editing,
+and a **split repo** - skills + session cwd separate from the code repos (e.g. a
+central skills project + several code repos) - is supported via the agent-home layer
+(run `receipts init` there to write an agent-only config; the code repos get the
+enforcer's verify/build config). With no config found the hooks fall back to the
+generic defaults, so a zero-config install still works:
+
+- `hooks/stop-verification-gate.py` extends, from config: the deployed-host patterns
+  (`build.deploy_host_patterns`), the by-value-query patterns
+  (`agent.staging_query_patterns`), the fixed-status values
+  (`agent.closeout_fixed_statuses`), and the downgrade tags (`claim.downgrade_tags`).
+- `hooks/stop-trajectory-reminder.py` reads which skills are fix/build loops from
+  `agent.loop_skills` (the shipped `seven-gates` plus any project loops), so the
+  reminder watches the project's actual loops, not just the bundled one.
+- `skills/seven-gates/` stays project-agnostic. For a project with its own loop,
+  `receipts init` registers it in `agent.loop_skills`; for a project with none, `init`
+  scaffolds one from `templates/loop-skill/SKILL.md.tmpl` (filled with the project's
+  facts) so the trajectory-kb is driven out of the box.
+
+## Roadmap
+
+- [x] `receipts.config.json` for host / loop-skill / fixed-status overrides - the hooks read it.
+- [x] `receipts init` detects + registers loop skills and scaffolds a harness when none exists; `receipts doctor` reports drift.
+- [ ] Install-test that the hooks + MCP auto-activate from the manifest in a real session.

package/plugin/templates/loop-skill/SKILL.md.tmpl

@@ -0,0 +1,58 @@
+---
+name: {{loop_name}}
+description: >-
+  Use when fixing a bug, addressing a tester or issue report, or claiming a change
+  is "done" / "fixed" on {{repo_name}}. The project fix/build loop: query past
+  trajectories, apply the Seven Gates (reproduce-first, fix the surface the reporter
+  sees, drive to the terminal action, carry a red->green receipt), and record the
+  outcome. A fix is done when the reported symptom is observably gone on the
+  deployed build, not because you say so.
+---
+
+# {{loop_name}}
+
+The {{repo_name}} fix/build loop. It rides on the **seven-gates** discipline (the
+full gate detail + scars live there) and adds the two trajectory-memory touchpoints
+plus this project's facts. Generated by `receipts init`; project facts live in
+`receipts.config.json`, never hardcoded here - re-run `receipts init` if they move.
+
+## At the start (before choosing a fix)
+1. **Query the trajectory memory** for this surface, to inherit prior dead-ends:
+   `query_trajectory({ surface: "<component/route>", text: "<symptom keyword>" })`.
+   A past `what_failed` is a wrong-surface / wrong-axis trap pre-recorded - the
+   cheapest way to not repeat it.
+2. **Reproduce the reported symptom (G0).** Observe it and record what you saw;
+   that observation is the acceptance test your fix must later show GONE.
+
+## While fixing
+3. Apply the **Seven Gates** (see the `seven-gates` skill): pin the exact flow the
+   reporter used (G2), land on the surface they SEE (G4), assert the rendered VALUE
+   not a placeholder (G1), drive the flow to its TERMINAL action (G5), and sweep the
+   pattern's parallel twins (G6).
+4. **Carry a receipt:** a red-before / green-after acceptance test in this project's
+   own framework, asserting the reporter's symptom (not a proxy).
+   - run one test: `{{test_command}}`
+
+## Verify (G3) on the build that carries YOUR commit
+- Confirm the deployed sha matches your push, then observe the symptom GONE on
+  `{{verify_against_url}}` ({{platform}}) by value - read the rendered value or run
+  a by-value query, not a "looks fixed" glance.
+
+## At close-out (EVERY exit, not just a clean fix)
+5. **Record the trajectory** with the HONEST outcome:
+   `append_trajectory({ repo: "{{repo_name}}", surface, surface_key, symptom,
+   root_cause, outcome, what_worked, what_failed, files })`.
+   - `outcome` = `fixed` only if reproduced and observably gone on the right build;
+     otherwise `unverified-reasoned` / `speculative` / `reverted` (the honesty
+     ladder). Failures are the most valuable entries - put the dead-end in
+     `what_failed` so the next loop on this surface inherits it.
+
+## The honesty ladder
+- **fixed** - reproduced and observably gone on the right build (the only success).
+- **unverified-reasoned** - real cause + a test on the path, but you could not
+  observe it; route to someone who can, not "fixed."
+- **speculative** - no confirmed cause; loudest flag, human sign-off on high-stakes
+  surfaces (money / auth / contracts / destructive migrations).
+- **reverted** - you backed the change out (e.g. wrong surface).
+
+"I could not verify this" is a respectable, tracked outcome. A false "fixed" is not.

package/receipts.config.example.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "./receipts.config.schema.json",
+  "version": 1,
+  "claim": {
+    "issue_link": "closes #(\\d+)",
+    "downgrade_tags": ["unverified-reasoned", "speculative", "reverted"]
+  },
+  "build": {
+    "sha_source": "github-deployments",
+    "platform": "vercel",
+    "deploy_host_patterns": ["*.vercel.app", "myapp.com"],
+    "environments": {
+      "staging": "https://myapp-staging.vercel.app",
+      "production": "https://myapp.com"
+    },
+    "verify_against": "staging"
+  },
+  "verify": {
+    "test_command": "npm test -- {test}",
+    "suite_command": "npm test",
+    "live_drive": null
+  },
+  "degrade": {
+    "on_no_receipt": "require-downgrade-tag",
+    "on_unreachable_build": "sha-bind-only"
+  },
+  "agent": {
+    "loop_skills": ["seven-gates", "myapp-fix-loop"],
+    "staging_query_patterns": ["proxy.rlwy.net"],
+    "closeout_fixed_statuses": ["Fixed - Pending Retest", "Verified"],
+    "repo_name": "myapp"
+  }
+}

package/receipts.config.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/shaheershoaib/receipts/receipts.config.schema.json",
+  "title": "receipts project config",
+  "description": "Project-specific plumbing for the receipts gates. Produced by `receipts init` (detect -> confirm -> write); rarely hand-authored. The gate LOGIC ships generic; this file only tells receipts how to build/test/reach THIS project and what marks a fix-claim.",
+  "type": "object",
+  "required": ["version"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1, "description": "Config schema version." },
+    "claim": {
+      "type": "object",
+      "description": "How a PR claims to fix an issue, and how it honestly downgrades.",
+      "additionalProperties": false,
+      "properties": {
+        "issue_link": {
+          "type": "string",
+          "description": "Regex matching how a PR links the issue it fixes.",
+          "default": "closes #(\\d+)"
+        },
+        "downgrade_tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tags that mark a PR as NOT claiming a clean fix (the honesty ladder); these pass the gate but are tracked, not treated as 'fixed'.",
+          "default": ["unverified-reasoned", "speculative", "reverted"]
+        }
+      }
+    },
+    "build": {
+      "type": "object",
+      "description": "How receipts binds to the build under test and (optionally) the deployed app.",
+      "additionalProperties": false,
+      "properties": {
+        "sha_source": {
+          "enum": ["github-deployments", "github-status", "ci-artifact", "none"],
+          "description": "How to confirm which commit the build/deploy carries (G3). 'none' = no deploy; verify against the built artifact + test run.",
+          "default": "github-deployments"
+        },
+        "platform": {
+          "type": "string",
+          "description": "Detected deploy platform (informational), e.g. vercel | railway | netlify | fly | render | none."
+        },
+        "deploy_host_patterns": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Host globs that count as 'pointed at the deployed build' (for optional live-drive)."
+        },
+        "environments": {
+          "type": "object",
+          "additionalProperties": { "type": "string", "format": "uri" },
+          "description": "Named environment URLs, e.g. {\"staging\": \"https://...\", \"production\": \"https://...\"}."
+        },
+        "verify_against": {
+          "type": "string",
+          "description": "Which environment the enforcer re-verifies on (a key of `environments`).",
+          "default": "staging"
+        }
+      }
+    },
+    "verify": {
+      "type": "object",
+      "description": "How to run the receipt: the carried red->green acceptance test. The PRIMARY verification; uses the project's own test framework + CI auth. Required for the ENFORCER (it errors without test_command); an agent-home config (skills + session cwd, no code repo) may omit this whole block - that is why `verify` is not a top-level required field.",
+      "required": ["test_command"],
+      "additionalProperties": false,
+      "properties": {
+        "test_command": {
+          "type": "string",
+          "description": "Run ONE carried acceptance test. `{test}` is substituted with the test path/selector.",
+          "examples": ["npm test -- {test}", "pytest {test}", "go test -run {test} ./..."]
+        },
+        "suite_command": {
+          "type": "string",
+          "description": "Run the full suite (regression check)."
+        },
+        "live_drive": {
+          "type": ["string", "null"],
+          "description": "OPTIONAL advanced: a command/script that drives the deployed app for symptoms a unit/e2e test can't cover. null = not used (the carried test is enough).",
+          "default": null
+        }
+      }
+    },
+    "degrade": {
+      "type": "object",
+      "description": "Honest behavior when the symptom cannot be re-verified. Never silent-pass; never block-all.",
+      "additionalProperties": false,
+      "properties": {
+        "on_no_receipt": {
+          "enum": ["require-downgrade-tag", "warn", "block"],
+          "description": "What to do when a fix-claim carries no re-runnable acceptance test.",
+          "default": "require-downgrade-tag"
+        },
+        "on_unreachable_build": {
+          "enum": ["sha-bind-only", "warn", "block"],
+          "description": "What to do when the deployed build can't be reached for re-verification.",
+          "default": "sha-bind-only"
+        }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "description": "How the agent-side Stop hooks bind to THIS project: which skills are fix/build loops (watched by the trajectory reminder + carrying the kb touchpoints), what extra by-value-query patterns count, and which tracker statuses mean 'fixed'. The hooks ship generic defaults; these MERGE OVER them (never replace the generics, so a clean install still works). Written by `receipts init`. Deploy-host patterns live in `build.deploy_host_patterns` (shared with the enforcer).",
+      "additionalProperties": false,
+      "properties": {
+        "loop_skills": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Skill names that are fix/build loops: the trajectory-reminder watches these (append-on-exit) and they carry the kb query/append touchpoints. The shipped 'seven-gates' plus any project loop skills.",
+          "default": ["seven-gates"]
+        },
+        "staging_query_patterns": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Extra substrings / MCP-tool names that count as a by-value query against the deployed build (e.g. a DB proxy host, a query tool), on top of the generic defaults."
+        },
+        "closeout_fixed_statuses": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tracker status strings that mean 'claimed fixed' (e.g. 'Fixed - Pending Retest', 'Verified', 'Closed'); the verification gate treats a status update to one of these as a fix close-out.",
+          "default": ["Pending Retest", "Verified"]
+        },
+        "repo_name": {
+          "type": "string",
+          "description": "Default repo tag for trajectory-kb appends (the agent may override per append)."
+        }
+      }
+    }
+  }
+}