signoff-cli 0.0.0-stage → 4.0.1

package/lib/detect.js

@@ -0,0 +1,169 @@
+"use strict";
+// Detect the command that actually runs this repo's tests.
+//
+// The point is not to guess cleverly; it is to never stay silent. A repo with a
+// `tests/` folder but no installed runner used to print "not detected (p1 will be
+// skipped)", which reads like a pass. `detect()` therefore returns a hint when it
+// found tests but no way to run them, and callers show that hint.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch (e) {
+    return false;
+  }
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch (e) {
+    return null;
+  }
+}
+
+// A python that can import pytest, in the same order the gates use: SIGNOFF_PYTHON,
+// then `python3`/`python`/`py -3`, then the usual Windows install locations.
+function pythonCandidates() {
+  const out = [];
+  if (process.env.SIGNOFF_PYTHON) out.push(process.env.SIGNOFF_PYTHON);
+  out.push("python3", "python", "py");
+  if (process.platform === "win32") {
+    const home = process.env.USERPROFILE || process.env.HOME || "";
+    if (home) {
+      out.push(path.join(home, ".openviking", "venv", "Scripts", "python.exe"));
+    }
+  }
+  return out;
+}
+
+function hasPytest() {
+  for (const exe of pythonCandidates()) {
+    const args = exe === "py" ? ["-3", "-c", "import pytest"] : ["-c", "import pytest"];
+    const r = spawnSync(exe, args, { encoding: "utf8", windowsHide: true });
+    if (r.status === 0) return exe === "py" ? "py -3" : exe;
+  }
+  return null;
+}
+
+const PY_TEST = /(^test_.*\.py$|.*_test\.py$)/;
+
+function hasPythonTests(root) {
+  // An empty `tests/` folder is not a suite: require at least one python file under it,
+  // otherwise every scaffold prints "pytest" and p1 fails with "no tests ran".
+  let underTests = false;
+  const scanTests = (dir, depth) => {
+    if (depth > 2 || underTests) return;
+    let list = [];
+    try {
+      list = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const e of list) {
+      if (e.isFile() && e.name.endsWith(".py")) underTests = true;
+      else if (e.isDirectory()) scanTests(path.join(dir, e.name), depth + 1);
+    }
+  };
+  if (isDir(path.join(root, "tests"))) scanTests(path.join(root, "tests"), 0);
+  if (underTests) return true;
+  let hits = 0;
+  const walk = (dir, depth) => {
+    if (depth > 3 || hits > 0) return;
+    let list = [];
+    try {
+      list = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const e of list) {
+      if (hits > 0) return;
+      if (e.name === "node_modules" || e.name === ".git" || e.name === "venv" || e.name === ".venv") continue;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p, depth + 1);
+      else if (PY_TEST.test(e.name)) hits += 1;
+    }
+  };
+  walk(root, 0);
+  return hits > 0;
+}
+
+function hasTarget(file, target) {
+  try {
+    return new RegExp("^" + target + "\\s*:", "m").test(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    return false;
+  }
+}
+
+// Returns {cmd, source, hint}. `cmd` runs the suite; `hint` explains why there is no
+// command even though something looked testable. Both null means "nothing here".
+function detect(root, cfg) {
+  cfg = cfg || {};
+  if (cfg.test_cmd) return { cmd: String(cfg.test_cmd), source: "signoff config", hint: "" };
+
+  const pkg = readJson(path.join(root, "package.json"));
+  if (pkg) {
+    const scripts = pkg.scripts || {};
+    if (scripts.test && !String(scripts.test).includes("no test specified")) {
+      return { cmd: "npm test --silent", source: "package.json scripts.test", hint: "" };
+    }
+    // A known runner in the dependency list beats a missing npm script: `npx --no-install`
+    // fails loudly instead of downloading something unrelated.
+    const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+    for (const [name, cmd] of [
+      ["vitest", "npx --no-install vitest run"],
+      ["jest", "npx --no-install jest"],
+      ["mocha", "npx --no-install mocha"],
+    ]) {
+      if (deps[name]) return { cmd, source: name, hint: "" };
+    }
+  }
+
+  if (exists(path.join(root, "Cargo.toml"))) return { cmd: "cargo test --quiet", source: "Cargo.toml", hint: "" };
+  if (exists(path.join(root, "go.mod"))) return { cmd: "go test ./...", source: "go.mod", hint: "" };
+  for (const name of ["Makefile", "makefile"]) {
+    if (hasTarget(path.join(root, name), "test")) return { cmd: "make test", source: name, hint: "" };
+  }
+
+  if (hasPythonTests(root)) {
+    const py = hasPytest();
+    if (py) return { cmd: `"${py}" -m pytest -q`, source: "pytest", hint: "" };
+    // unittest discovery needs no dependency and covers `tests/test_*.py`.
+    for (const exe of pythonCandidates()) {
+      const args = exe === "py" ? ["-3", "-c", "import sys"] : ["-c", "import sys"];
+      if (spawnSync(exe, args, { encoding: "utf8", windowsHide: true }).status === 0) {
+        return { cmd: `"${exe}" -m unittest discover -q`, source: "unittest (pytest not installed)", hint: "" };
+      }
+    }
+    return {
+      cmd: null,
+      source: "",
+      hint: "python tests found but no python interpreter; install one or set --test-cmd",
+    };
+  }
+  return { cmd: null, source: "", hint: "" };
+}
+
+// One line for `init` / `status`: what will run, or why nothing will.
+function describe(root, cfg) {
+  const d = detect(root, cfg);
+  if (d.cmd) return `${d.cmd}  (${d.source})`;
+  if (d.hint) return d.hint;
+  return "none (nothing testable found; p1 is skipped)";
+}
+
+module.exports = { detect, describe, pythonCandidates, hasPytest };

package/lib/doctor.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+"use strict";
+// signoff doctor — one command that answers "why didn't the guard do what I expected?".
+//
+// Every check is read-only: the doctor never installs, rewrites or deletes anything. It
+// composes the commands that already exist (`status`, `audit`, `p4 verify`) instead of
+// re-deriving their logic, so a doctor that says `ok` and a gate that runs later cannot
+// disagree about what "installed" or "missing" means.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const core = require("./core");
+const p4 = require("./p4");
+const detect = require("./detect");
+
+const DISPATCHER = path.join(__dirname, "..", "bin", "signoff.js");
+const STATE = ".signoff";
+const HOOK_MARK = "# generated by signoff-cli";
+const LEGACY_HOOK_MARK = "# generated by dsh-signoff";
+function markedByUs(text) {
+  const t = String(text || "");
+  return t.includes(HOOK_MARK) || t.includes(LEGACY_HOOK_MARK);
+}
+const STAGES = ["pre-commit", "commit-msg", "pre-push"];
+
+const USAGE = `usage: signoff doctor [-h] [--json] [--quiet] [--fix]
+
+Why is (or isn't) this repo guarded? Read-only: nothing is installed, changed or deleted.
+
+options:
+  -h, --help   show this help message and exit
+  --json       machine-readable result
+  --fix        repair what can be proved: reinstall the hooks when they are
+               missing or foreign, and chmod +x on our hooks under POSIX
+  --quiet      only print checks that are not ok
+`;
+
+function cli(args) {
+  const r = spawnSync(process.execPath, [DISPATCHER, ...args], { encoding: "utf8" });
+  return { code: r.status === null ? 127 : r.status, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch (e) {
+    return null;
+  }
+}
+
+function onPath(exe) {
+  const dirs = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  const names = process.platform === "win32" ? [`${exe}.cmd`, `${exe}.ps1`, `${exe}.exe`, exe] : [exe];
+  for (const d of dirs) {
+    for (const n of names) {
+      if (fs.existsSync(path.join(d, n))) return path.join(d, n);
+    }
+  }
+  return "";
+}
+
+function repoTop() {
+  const r = core.git(["rev-parse", "--show-toplevel"]);
+  return r.code === 0 ? r.out.trim() : "";
+}
+
+function run(argv) {
+  const args = core.parseArgs(argv || [], {});
+  if (args.help || args._.indexOf("-h") !== -1) {
+    console.log(USAGE);
+    return 0;
+  }
+  const asJson = !!args.json;
+  const quiet = !!args.quiet;
+  const fix = !!args.fix;
+  const fixed = [];
+
+  const checks = [];
+  const add = (id, status, detail, fix) => checks.push({ id, status, detail, fix: fix || "" });
+
+  // --- environment (the old `doctor` rows, now with verdicts) -----------------
+  const major = Number(process.version.replace(/^v/, "").split(".")[0]);
+  add("node", major >= 18 ? "ok" : "fail", process.version, major >= 18 ? "" : "install Node 18 or newer");
+  const gitBin = onPath("git");
+  add("git", gitBin ? "ok" : "fail", gitBin || "not on PATH", gitBin ? "" : "install git and put it on PATH");
+  const engine = process.env.SIGNOFF_ENGINE === "python" ? "python" : "node";
+  add("engine", "ok", engine);
+
+  const top = repoTop();
+  if (!top || core.git(["rev-parse", "--git-dir"]).code !== 0) {
+    add("repo", "fail", process.cwd(), "run inside a git repository");
+    return report(checks, asJson, quiet, 2);
+  }
+  add("repo", "ok", top);
+
+  // --- installation -----------------------------------------------------------
+  const st = readJsonOr(() => JSON.parse(cli(["status", "--json"]).out), null);
+  const version = st && st.version ? st.version : "";
+  add("version", version ? "ok" : "warn", version || "unknown", version ? "" : "reinstall: npm i -g signoff-cli");
+
+  const hooksDir = path.join(top, ".git", "hooks");
+  for (const stage of STAGES) {
+    const p = path.join(hooksDir, stage);
+    const exists = fs.existsSync(p);
+    const ours = exists && markedByUs(fs.readFileSync(p, "utf8"));
+    if (!ours) {
+      add(`hook:${stage}`, "fail", exists ? "a foreign hook is there" : "missing", "run: signoff init");
+      continue;
+    }
+    let mode = "ok";
+    if (process.platform !== "win32") {
+      if ((fs.statSync(p).mode & 0o111) === 0) mode = "fail";
+    }
+    add(`hook:${stage}`, mode, mode === "ok" ? "installed" : "not executable", mode === "ok" ? "" : `chmod +x ${p}`);
+    const backup = path.join(hooksDir, `${stage}.signoff-backup`);
+    if (fs.existsSync(backup)) {
+      add(`hook-backup:${stage}`, "warn", "old hook saved, not chained", "wire it manually or rerun init after moving it");
+    }
+  }
+
+  const hookText = fs.existsSync(path.join(hooksDir, "pre-commit"))
+    ? fs.readFileSync(path.join(hooksDir, "pre-commit"), "utf8")
+    : "";
+  const resolvable = onPath("signoff");
+  if (hookText && hookText.indexOf("signoff") !== -1) {
+    add(
+      "hook:path",
+      resolvable ? "ok" : "warn",
+      resolvable || "signoff not on PATH for non-interactive shells",
+      resolvable ? "" : "hooks that call `signoff` fail silently when PATH differs; reinstall globally"
+    );
+  }
+  // --- configuration ----------------------------------------------------------
+  const cfgPath = path.join(top, STATE, "config.json");
+  const cfg = fs.existsSync(cfgPath) ? readJson(cfgPath) : null;
+  if (!cfg) {
+    add("config", fs.existsSync(cfgPath) ? "fail" : "warn", fs.existsSync(cfgPath) ? "unreadable" : "missing", "run: signoff init");
+  } else {
+    const bad = [];
+    if (typeof cfg.version !== "number") bad.push("version");
+    if (cfg.docs !== undefined && !Array.isArray(cfg.docs)) bad.push("docs");
+    if (cfg.test_cmd !== undefined && cfg.test_cmd !== null && typeof cfg.test_cmd !== "string") bad.push("test_cmd");
+    if (cfg.budget !== undefined && !(typeof cfg.budget === "number" && cfg.budget > 0)) bad.push("budget");
+    add("config", bad.length ? "fail" : "ok", bad.length ? `bad field(s): ${bad.join(", ")}` : JSON.stringify(cfg).slice(0, 80), bad.length ? "fix or delete .signoff/config.json, then rerun signoff init" : "");
+    if (typeof cfg.test_cmd === "string" && cfg.test_cmd) {
+      const exe = cfg.test_cmd.split(/\s+/)[0];
+      const found = exe.includes(path.sep) || exe.includes("/") ? fs.existsSync(path.join(top, exe)) : !!onPath(exe);
+      add("test-cmd", found ? "ok" : "warn", cfg.test_cmd, found ? "" : "p1 will fail to start it; check the command or PATH");
+    }
+    const det = detect.detect(top, cfg);
+    if (det.cmd) {
+      add("test-runner", "ok", det.cmd + (det.source ? ` (${det.source})` : ""), "");
+    } else if (det.hint) {
+      add("test-runner", "warn", det.hint, "set --test-cmd, or install the runner");
+    } else {
+      add("test-runner", "ok", "nothing testable; p1 is skipped", "");
+    }
+  }
+
+  // --- install point ----------------------------------------------------------
+  const ipPath = path.join(top, STATE, "installed.json");
+  const ip = fs.existsSync(ipPath) ? readJson(ipPath) : null;
+  if (!ip || !ip.sha) {
+    add("install-point", "warn", "not recorded", "run: signoff init (records it; re-init keeps the first)");
+  } else if (core.git(["cat-file", "-e", `${ip.sha}^{commit}`]).code !== 0) {
+    add("install-point", "fail", `${ip.sha.slice(0, 12)} not in history (rewritten?)`, "reinstall after the rewrite: signoff init");
+  } else {
+    add("install-point", "ok", `${ip.sha.slice(0, 12)} (${ip.ts || "no ts"})`);
+  }
+  if (ip && ip.version && version && ip.version !== version) {
+    add("install-version", "warn", `installed ${ip.version}, CLI ${version}`, "upgrade in place: npm i -g signoff-cli && signoff init");
+  }
+
+  // --- leftover state ---------------------------------------------------------
+  const marker = path.join(top, STATE, "passed");
+  if (fs.existsSync(marker)) {
+    const m = readJson(marker);
+    add("marker", "warn", `leftover ${m && m.mode ? m.mode : "?"} record`, "a commit was interrupted; the next pre-commit overwrites it");
+  } else {
+    add("marker", "ok", "none");
+  }
+  const skipsPath = path.join(top, STATE, "skips.log");
+  if (fs.existsSync(skipsPath)) {
+    const n = fs.readFileSync(skipsPath, "utf8").split(/\r?\n/).filter(Boolean).length;
+    add("skips", "warn", `${n} recorded skip(s)`, "inspect: .signoff/skips.log; audit --strict fails on them");
+  } else {
+    add("skips", "ok", "none");
+  }
+
+  // --- ledger -----------------------------------------------------------------
+  const ledger = p4.ledgerPath();
+  if (!fs.existsSync(ledger)) {
+    add("ledger", "ok", "empty (nothing recorded yet)");
+  } else {
+    let entries = [];
+    try {
+      entries = p4.entries();
+    } catch (e) {
+      add("ledger", "fail", "unreadable", "inspect or move it away, then re-record");
+    }
+    const key = p4.repoKey();
+    const foreign = entries.filter((e) => e && e.repo && key && e.repo !== key).length;
+    const v = readJsonOr(() => JSON.parse(cli(["p4", "verify", "--json"]).out), null);
+    if (!v) {
+      add("ledger", "fail", "verify did not return JSON", "run: signoff p4 verify");
+    } else {
+      add(
+        "ledger",
+        v.ok ? (foreign ? "warn" : "ok") : "fail",
+        `${entries.length} entries, ${foreign} from other repos${v.problems && v.problems.length ? `, ${v.problems.length} problem(s)` : ""}`,
+        v.ok ? "" : "the chain is broken or a rollback point is gone; inspect .signoff/audit.log"
+      );
+      for (const p of (v.problems || []).slice(0, 3)) add("ledger:problem", "fail", String(p));
+    }
+  }
+
+  // --- what actually landed ----------------------------------------------------
+  const audit = readJsonOr(() => {
+    const r = cli(["audit", "--since-install", "--json"]);
+    return r.out ? JSON.parse(r.out) : null;
+  }, null);
+  if (!audit) {
+    add("audit", "warn", "--since-install unavailable (no install point)", "signoff audit --range A..B");
+  } else {
+    const c = audit.counts || {};
+    add(
+      "audit",
+      c.missing ? "fail" : c.skip ? "warn" : "ok",
+      `pass=${c.pass || 0} skip=${c.skip || 0} missing=${c.missing || 0}`,
+      c.missing ? "commits without a trailer: they bypassed the hook (--no-verify) or predate the install point" : ""
+    );
+  }
+
+  // --- --fix: only repairs that are provably safe ----------------------------
+  if (fix) {
+    const hooksDir = path.join(top, ".git", "hooks");
+    const installBroken = checks.some(
+      (c) => /^hook:/.test(c.id) && c.status === "fail" && /missing|foreign/.test(c.detail)
+    );
+    if (installBroken) {
+      // The documented fix for a missing or foreign hook *is* `signoff init`; run it
+      // instead of telling the user to, then re-check rather than trusting the exit code.
+      const guard = require("./guard");
+      const rc = guard.main(["init", "--quiet"]);
+      fixed.push(`reinstalled hooks (signoff init, rc=${rc})`);
+    }
+    for (const stage of STAGES) {
+      const p2 = path.join(hooksDir, stage);
+      if (!fs.existsSync(p2) || !markedByUs(fs.readFileSync(p2, "utf8"))) continue;
+      if (process.platform !== "win32" && (fs.statSync(p2).mode & 0o111) === 0) {
+        try {
+          fs.chmodSync(p2, 0o755);
+          fixed.push(`chmod +x .git/hooks/${stage}`);
+        } catch (e) {
+          add(`fix:hook:${stage}`, "warn", String(e.message || e), "chmod it yourself");
+        }
+      }
+    }
+    const marker = path.join(top, STATE, "passed");
+    const staged = core.git(["diff", "--cached", "--name-only"]).out.trim();
+    if (fs.existsSync(marker) && !staged) {
+      try {
+        fs.rmSync(marker, { force: true });
+        fixed.push(`removed stale ${STATE}/passed (nothing staged)`);
+      } catch (e) {
+        add("fix:marker", "warn", String(e.message || e), "delete it yourself");
+      }
+    }
+    if (fixed.length) {
+      if (!asJson && !quiet) console.log(`fixed: ${fixed.join("; ")}`);
+      return run((argv || []).filter((a) => a !== "--fix"));
+    }
+    if (!asJson && !quiet) console.log("fixed: nothing to repair");
+  }
+
+  return report(checks, asJson, quiet, checks.some((c) => c.status === "fail") ? 1 : 0);
+}
+
+function readJsonOr(fn, fallback) {
+  try {
+    return fn();
+  } catch (e) {
+    return fallback;
+  }
+}
+
+function report(checks, asJson, quiet, code) {
+  const fails = checks.filter((c) => c.status === "fail").length;
+  const warns = checks.filter((c) => c.status === "warn").length;
+  if (asJson) {
+    core.json({ ok: fails === 0, fails, warns, checks });
+    return code;
+  }
+  for (const c of checks) {
+    if (quiet && c.status === "ok") continue;
+    console.log(`${c.status.padEnd(5)}${c.id.padEnd(20)}${c.detail}`);
+    if (c.fix) console.log(`${"".padEnd(5)}${"".padEnd(20)}→ ${c.fix}`);
+  }
+  console.log(`doctor: ${fails ? `${fails} fail` : "no failures"}, ${warns} warning(s)`);
+  return code;
+}
+
+module.exports = { run, USAGE };

package/lib/editor.js

@@ -0,0 +1,97 @@
+"use strict";
+// Editor integration: the gate should be runnable from the window the developer
+// already has open, and a failure should land in the Problems panel, not the log.
+
+const fs = require("fs");
+const path = require("path");
+const core = require("./core");
+
+// The guard prints `[secrets] path:line  rule  match` and `[cov] 42.8% 3/7 file`.
+// One matcher per shape; `$signoff-gate` is the aggregate the tasks use.
+const MATCHERS = {
+  "signoff-secret": {
+    owner: "signoff",
+    fileLocation: ["relative", "${workspaceFolder}"],
+    pattern: [
+      {
+        regexp: "^\\[secrets\\] (.+?):(\\d+)\\s+(\\S+)\\s+(.*)$",
+        file: 1,
+        line: 2,
+        code: 3,
+        message: 4,
+      },
+    ],
+  },
+  "signoff-cov": {
+    owner: "signoff",
+    fileLocation: ["relative", "${workspaceFolder}"],
+    severity: "warning",
+    pattern: [
+      {
+        regexp: "^\\[cov\\]\\s+([\\d.]+)%\\s+(\\d+)/(\\d+)\\s+(.+)$",
+        file: 4,
+        message: 1,
+      },
+    ],
+  },
+};
+
+function tasks(signoff) {
+  const run = (label, args, matcher, extra) =>
+    Object.assign(
+      {
+        label,
+        type: "shell",
+        command: signoff,
+        args,
+        group: "test",
+        presentation: { reveal: "always", panel: "dedicated", clear: true },
+        problemMatcher: matcher ? [matcher] : [],
+      },
+      extra || {}
+    );
+  return {
+    version: "2.0.0",
+    tasks: [
+      run("signoff: guard", ["guard"], "signoff-secret"),
+      run("signoff: all gates", ["all"], "signoff-secret"),
+      run("signoff: secrets", ["secrets", "--all"], "signoff-secret"),
+      run("signoff: coverage", ["cov", "--diff"], "signoff-cov"),
+      run("signoff: audit", ["audit", "--verify"], null, { group: "none", problemMatcher: [] }),
+      run("signoff: status", ["status"], null, { group: "none", problemMatcher: [] }),
+    ],
+  };
+}
+
+// Merge instead of overwrite: a repo may already have tasks, and losing them is
+// not a thing a "make it convenient" flag is allowed to do.
+function vscode(root, opts) {
+  const o = opts || {};
+  const dir = path.join(root, ".vscode");
+  const file = path.join(dir, "tasks.json");
+  fs.mkdirSync(dir, { recursive: true });
+  const wanted = tasks(o.command || "signoff");
+  let existing = null;
+  if (fs.existsSync(file)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (e) {
+      // A tasks.json with comments (jsonc) is not parseable; appending a second
+      // tasks.json would be worse than leaving the user's file alone.
+      return { ok: false, file, reason: "existing tasks.json is not plain JSON (jsonc?); left untouched" };
+    }
+  }
+  const base = existing && Array.isArray(existing.tasks) ? existing : { version: "2.0.0", tasks: [] };
+  const labels = new Set((base.tasks || []).map((t) => t && t.label));
+  // Problem matchers live in a user-level file; the task references them by owner
+  // name, so the JSON we write stays valid for VS Code as-is.
+  for (const t of wanted.tasks) {
+    if (!labels.has(t.label)) base.tasks.push(t);
+  }
+  fs.writeFileSync(file, JSON.stringify(base, null, 2) + "\n", "utf8");
+  const matcherFile = path.join(dir, "signoff-problem-matchers.json");
+  fs.writeFileSync(matcherFile, JSON.stringify(MATCHERS, null, 2) + "\n", "utf8");
+  return { ok: true, file, matcherFile, added: base.tasks.length - (existing ? (existing.tasks || []).length : 0) };
+}
+
+module.exports = { vscode, MATCHERS, tasks };

package/lib/explain.js

@@ -0,0 +1,73 @@
+"use strict";
+
+// `signoff explain <gate>` — what a gate checks and how it decides. Kept next to the
+// gates themselves so the answer comes from the same repo, not from memory.
+
+const USAGE = `usage: signoff explain [-h] [--json] {p1,p2,p3,p4,p5}`;
+
+const GATES = {
+  p1: {
+    name: "tests",
+    checks: "Runs the repository's own test command and fails if it exits non-zero.",
+    decides:
+      "Command precedence: .signoff/config.json test_cmd, then package.json scripts.test (npm test --silent), " +
+      "then vitest/jest/mocha via npx --no-install, then cargo test, go test ./..., make test, then pytest " +
+      "(if a .py file exists under tests/), then python -m unittest discover.",
+    fix: "Fix the failing test, or pin the real command: signoff init --lock-test (or --test-cmd \"...\").",
+  },
+  p2: {
+    name: "coverage",
+    checks: "Reads the scenario table and counts scenarios and assertions against the thresholds.",
+    decides:
+      "Fails when scenarios < --min-scenario or assertions < --min-assertions; --strict also fails on " +
+      "a scenario that claims success without assertions.",
+    fix: "Add the missing scenarios or assertions, or lower the thresholds in .signoff/config.json on purpose.",
+  },
+  p3: {
+    name: "queue",
+    checks: "Reads tasks/<id>/card.json statuses and refuses to call work done while cards are not finished.",
+    decides: "Fails when a card is missing a status, has an unknown status, or is not done; records the run in .signoff/p3.json.",
+    fix: "Finish the card, set its status honestly, or remove the card if the task is gone.",
+  },
+  p4: {
+    name: "ledger",
+    checks: "Verifies the append-only ledger: every record hashes its predecessor, and every rollback point still exists.",
+    decides: "Fails on a broken hash chain, a missing field, or a rollback commit that is not in the repository.",
+    fix: "Do not edit .signoff/audit.log by hand; re-record the action with signoff p4 confirm.",
+  },
+  p5: {
+    name: "anti-slop",
+    checks: "Scans added documents for empty claims: TODO/TBD/FIXME placeholders and AI-filler words.",
+    decides:
+      "Fails on a placeholder outside a word boundary (so \"TODO\" in code comments counts but 待补 inside a " +
+      "bigger word does not) and on filler phrases that assert progress without evidence.",
+    fix: "Replace the claim with what was actually verified, or delete the placeholder.",
+  },
+};
+
+function run(argv) {
+  const list = argv || [];
+  if (list.indexOf("-h") !== -1 || list.indexOf("--help") !== -1) {
+    console.log(USAGE);
+    return 0;
+  }
+  // Only `--json` exists here, so the gate is simply the one token that is not a flag.
+  const asJson = list.indexOf("--json") !== -1;
+  const which = String(list.filter((a) => !String(a).startsWith("-"))[0] || "").toLowerCase();
+  if (!GATES[which]) {
+    console.error(USAGE);
+    return 2;
+  }
+  const g = GATES[which];
+  if (asJson) {
+    console.log(JSON.stringify({ gate: which, name: g.name, checks: g.checks, decides: g.decides, fix: g.fix }));
+    return 0;
+  }
+  console.log(`${which} — ${g.name}`);
+  console.log(`  checks   ${g.checks}`);
+  console.log(`  decides  ${g.decides}`);
+  console.log(`  fix      ${g.fix}`);
+  return 0;
+}
+
+module.exports = { run, USAGE, GATES };