@mdferdousalam/agentic-sdlc 0.0.0-stage → 3.0.0

package/bin/sdlc

@@ -0,0 +1,2747 @@
+#!/usr/bin/env python3
+"""sdlc — the machine half of the agentic SDLC pipeline.
+
+The agents are prose: they persuade a model. This is the part that does not negotiate. It
+detects the project, records each stage's verdict as a receipt bound to a commit and a clock,
+and — as a PreToolUse hook — refuses the actions that would skip a stage.
+
+    sdlc init [--write]          detect the stack and write sdlc.config.json
+    sdlc config                  print the effective configuration
+    sdlc receipt write KIND --verdict V [--subject S] [--detail D]
+    sdlc receipt check KIND [--verdict V] [--max-age-min N]
+    sdlc receipt show  KIND
+    sdlc status                  where this unit of work stands
+    sdlc guard                   PreToolUse hook: reads tool JSON on stdin, exit 2 blocks
+    sdlc doctor                  check the install, the config and the repo
+
+Python 3.8+, standard library only, no network. Exit codes: 0 fine, 1 a check failed,
+2 blocked (the hook contract), 3 misuse.
+"""
+from __future__ import annotations
+
+import argparse
+import calendar
+import fnmatch
+import glob
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+CONFIG_NAMES = ("sdlc.config.json", ".opencode/sdlc.json")
+RECEIPT_DIR = ".sdlc/receipts"
+RECEIPT_KINDS = ("spec", "verification", "review", "security", "quality", "gate",
+                 "readiness", "approval_merge", "approval_release", "approval_exception",
+                 "release", "postdeploy")
+AUDIT_LOG = ".sdlc/audit.log"
+FEEDBACK = ".sdlc/feedback.json"
+DEFAULT_MAX_AGE_MIN = 180
+FINDING_DIR = ".sdlc/findings"
+BASELINE = ".sdlc/baseline.json"
+BUDGET = ".sdlc/budget.json"
+CHECKPOINT = ".sdlc/checkpoint.json"
+
+# The finding vocabularies. Severity is how bad it is if real; confidence is how sure we are
+# that it is real. They are separate axes on purpose — see docs/control-spec.md §1.
+SEVERITIES = ("critical", "high", "medium", "low", "advisory")
+CONFIDENCES = ("high", "medium", "low")
+DETECTIONS = ("deterministic", "test", "runtime", "llm")
+FINDING_OUTCOMES = ("open", "fixed", "refused", "deferred", "unexecuted", "escalated")
+EXPLOITABILITY = ("remote", "local", "authenticated", "theoretical", "not-applicable")
+
+# The repair policy, as a table rather than as a paragraph an agent can reinterpret.
+# True: an agent may repair it unattended. False: report or escalate. "repro": only once the
+# finding has a reproduction, because at medium confidence the finding itself is in question.
+# docs/control-spec.md §2 is the readable copy; a test keeps the two from drifting.
+AUTOFIX = {
+    ("critical", "high"): True,   ("critical", "medium"): False, ("critical", "low"): False,
+    ("high", "high"): True,       ("high", "medium"): "repro",   ("high", "low"): False,
+    ("medium", "high"): True,     ("medium", "medium"): True,    ("medium", "low"): False,
+    ("low", "high"): True,        ("low", "medium"): True,       ("low", "low"): False,
+    ("advisory", "high"): False,  ("advisory", "medium"): False, ("advisory", "low"): False,
+}
+
+# --------------------------------------------------------------------------------------- git
+
+
+def git(*args: str, cwd: str | None = None) -> str:
+    try:
+        p = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, timeout=20)
+        return p.stdout.strip()
+    except Exception:
+        return ""
+
+
+def repo_root(start: str | None = None) -> str:
+    r = git("rev-parse", "--show-toplevel", cwd=start or os.getcwd())
+    return r or (start or os.getcwd())
+
+
+def head(root: str) -> str:
+    return git("rev-parse", "HEAD", cwd=root)
+
+
+def branch(root: str) -> str:
+    return git("rev-parse", "--abbrev-ref", "HEAD", cwd=root)
+
+
+def tree_clean(root: str) -> bool:
+    return git("status", "--porcelain", "--untracked-files=no", cwd=root) == ""
+
+
+# ------------------------------------------------------------------------------------ config
+
+
+def exists(root: str, *names: str) -> bool:
+    return any(os.path.exists(os.path.join(root, n)) for n in names)
+
+
+def which(name: str) -> bool:
+    return shutil.which(name) is not None
+
+
+def config_path(root: str) -> str | None:
+    for n in CONFIG_NAMES:
+        p = os.path.join(root, n)
+        if os.path.exists(p):
+            return p
+    return None
+
+
+def load_config(root: str) -> dict:
+    p = config_path(root)
+    if not p:
+        return {}
+    try:
+        return json.load(open(p))
+    except Exception as e:
+        print(f"sdlc: {p} is not valid JSON: {e}", file=sys.stderr)
+        return {}
+
+
+def detect_trunk(root: str) -> str:
+    ref = git("symbolic-ref", "--short", "refs/remotes/origin/HEAD", cwd=root)
+    if ref:
+        return ref.split("/")[-1]
+    for cand in ("main", "master", "develop", "Development"):
+        if git("rev-parse", "--verify", "--quiet", f"refs/heads/{cand}", cwd=root):
+            return cand
+    return branch(root) or "main"
+
+
+# Cross-cutting standards worth proposing, by what the repository evidently does. Proposed,
+# never imposed: a concern the maintainers did not choose produces noise on every review, which
+# is how a review tool gets switched off.
+CONCERN_HINTS = (
+    ("concurrency", (r"\bgo\s+func\b", r"\basync\s+def\b", r"\bawait\b", r"\bthread\b",
+                     r"\bMutex\b", r"\btokio\b", r"\bgoroutine\b", r"sync\.")),
+    ("data", (r"\bCREATE\s+TABLE\b", r"\bALTER\s+TABLE\b", r"\bmigrations?\b",
+              r"\bprisma\b", r"\bsqlalchemy\b", r"\bdiesel\b", r"\bgorm\b")),
+    ("memory", (r"\bunsafe\b", r"\bmalloc\b", r"\bfree\(", r"\braw pointer\b",
+                r"#include <stdlib", r"\bBox::leak\b")),
+)
+
+
+def suggest_concerns(root: str) -> list:
+    """Which cross-cutting profiles this repository looks like it needs.
+
+    A shallow scan of tracked source, because a wrong guess here costs a reviewer's noise
+    budget. The maintainer edits the list; detection never overwrites it (see cmd_init).
+    """
+    names = [n for n in git("ls-files", cwd=root).splitlines()
+             if re.search(r"\.(go|rs|py|ts|tsx|js|jsx|java|kt|c|cc|cpp|h|sql|rb|cs|swift)$", n)]
+    if not names:
+        return []
+    sample, found = names[:400], []
+    for concern, patterns in CONCERN_HINTS:
+        hits = 0
+        for n in sample:
+            try:
+                body = open(os.path.join(root, n), errors="replace").read(20000)
+            except OSError:
+                continue
+            if any(re.search(pat, body, re.I) for pat in patterns):
+                hits += 1
+                if hits >= 2:  # one match is a coincidence
+                    found.append(concern)
+                    break
+    return found
+
+
+def detect(root: str) -> dict:
+    """Infer the project's bindings. Everything here is a guess the user may correct."""
+    pm = monorepo = None
+    stack = "unknown"
+    test = {}
+    verify = []
+
+    if exists(root, "pnpm-lock.yaml"):
+        pm = "pnpm"
+    elif exists(root, "yarn.lock"):
+        pm = "yarn"
+    elif exists(root, "bun.lockb", "bun.lock"):
+        pm = "bun"
+    elif exists(root, "package-lock.json"):
+        pm = "npm"
+    elif exists(root, "package.json"):
+        pm = "npm"
+
+    if pm:
+        stack = "node"
+        monorepo = ("turbo" if exists(root, "turbo.json") else
+                    "nx" if exists(root, "nx.json") else
+                    "lerna" if exists(root, "lerna.json") else
+                    "workspaces" if exists(root, "pnpm-workspace.yaml") else None)
+        pkg = {}
+        try:
+            pkg = json.load(open(os.path.join(root, "package.json")))
+        except Exception:
+            pass
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        scripts = pkg.get("scripts", {})
+        for runner in ("vitest", "jest", "mocha", "ava", "node:test"):
+            if runner.split(":")[0] in deps:
+                test["unit"] = runner
+                break
+        for e2e in ("playwright", "@playwright/test", "cypress"):
+            if e2e in deps:
+                test["e2e"] = e2e.replace("@playwright/test", "playwright")
+                break
+        for s in ("lint", "typecheck", "type-check", "test"):
+            if s in scripts:
+                verify.append(f"{pm} run {s}" if s != "test" else f"{pm} test")
+    elif exists(root, "Cargo.toml"):
+        stack, pm = "rust", "cargo"
+        test["unit"] = "cargo test"
+        verify = ["cargo fmt --all -- --check",
+                  "cargo clippy --all-targets --all-features -- -D warnings",
+                  "cargo test --workspace"]
+    elif exists(root, "go.mod"):
+        stack, pm = "go", "go"
+        test["unit"] = "go test"
+        verify = ["gofmt -l .", "go vet ./...", "go test ./..."]
+    elif exists(root, "pyproject.toml", "setup.cfg", "requirements.txt"):
+        stack = "python"
+        pm = "uv" if exists(root, "uv.lock") else "poetry" if exists(root, "poetry.lock") else "pip"
+        test["unit"] = "pytest"
+        verify = (["ruff check ."] if exists(root, "ruff.toml") or which("ruff") else []) + ["pytest -q"]
+    elif exists(root, "pom.xml"):
+        stack, pm, verify = "java", "maven", ["mvn -q verify"]
+    elif exists(root, "build.gradle", "build.gradle.kts"):
+        stack, pm, verify = "java", "gradle", ["./gradlew check"]
+    elif exists(root, "Gemfile"):
+        stack, pm, verify = "ruby", "bundler", ["bundle exec rubocop", "bundle exec rspec"]
+    elif exists(root, "composer.json"):
+        stack, pm, verify = "php", "composer", ["composer test"]
+    elif exists(root, "book.toml"):
+        stack, verify = "mdbook", ["mdbook build"]
+    elif exists(root, "action.yml", "action.yaml"):
+        stack = "github-action"
+
+    engine = "openspec" if exists(root, "openspec") or which("openspec") else "prd-frd"
+
+    commits = "conventional" if exists(
+        root, "commitlint.config.js", "commitlint.config.cjs", "commitlint.config.mjs",
+        ".commitlintrc", ".commitlintrc.json", ".husky") else "descriptive"
+
+    secret_scan = ('gitleaks git --no-banner --redact --log-opts="-n 50"' if which("gitleaks")
+                   else "trufflehog git file://. --since-commit HEAD~50 --fail" if which("trufflehog")
+                   else None)
+
+    cfg = {
+        "$schema": "./schema/sdlc.config.schema.json",
+        "version": 2,
+        "trunk": detect_trunk(root),
+        "stack": stack,
+        "pm": pm,
+        "monorepo": monorepo,
+        "commits": commits,
+        "test": test,
+        "spec": {
+            "engine": engine,
+            "docsRoot": "openspec/changes" if engine == "openspec" else "docs/specs",
+            "strict": True,
+        },
+        "branchScheme": "{kind}/{slug}",
+        "verifyCmd": " && ".join(verify) if verify else None,
+        "gateCmd": None,
+        "secretScan": secret_scan,
+        "heavy": None,
+        "profile": None,
+        "concerns": suggest_concerns(root),
+        "quality": {
+            "cmd": None,
+            "coverageNewPct": None,
+            "note": "Deterministic analysis on NEW code. Research on agent-written code reports "
+                    "rising warnings and complexity, so the budget is on what this change adds, "
+                    "not on the whole repository.",
+        },
+        "release": {
+            "deployCmd": None,
+            "smokeCmd": None,
+            "rollbackCmd": None,
+            "environments": [],
+        },
+        "approvals": {"merge": "agent", "release": "human"},
+        "attributeCommits": True,
+        "reviewers": ["sdlc-code-reviewer"] + (["sdlc-security-reviewer"] if stack in ("rust", "go", "node", "python", "java") else []),
+        "protected": ["main", "master", "release/*"],
+        "receipts": {"maxAgeMin": DEFAULT_MAX_AGE_MIN},
+        "enforce": {
+            "pushToTrunkNeedsGate": True,
+            "mergeNeedsReadiness": True,
+            "branchNeedsApprovedSpec": True,
+            "blockDestructiveGit": True,
+            "blockPublishing": True,
+            "blockCredentialReads": True,
+        },
+        "neverByAgent": ["tag", "release", "publish", "force-push", "deploy"],
+    }
+    return cfg
+
+
+# ---------------------------------------------------------------------------------- receipts
+
+
+def receipt_path(root: str, kind: str) -> str:
+    return os.path.join(root, RECEIPT_DIR, f"{kind}.json")
+
+
+def subject_digest(root: str, subject: str) -> str | None:
+    if not subject:
+        return None
+    p = os.path.join(root, subject)
+    h = hashlib.sha256()
+    if os.path.isfile(p):
+        h.update(open(p, "rb").read())
+    elif os.path.isdir(p):
+        for dirpath, dirnames, names in os.walk(p):
+            dirnames.sort()
+            for n in sorted(names):
+                f = os.path.join(dirpath, n)
+                h.update(os.path.relpath(f, p).encode())
+                try:
+                    h.update(open(f, "rb").read())
+                except OSError:
+                    pass
+    else:
+        return None
+    return "sha256:" + h.hexdigest()[:16]
+
+
+def audit(root: str, event: str, detail: str) -> None:
+    """Append-only record of everything the pipeline decided. Never rotated by this tool."""
+    try:
+        p = os.path.join(root, AUDIT_LOG)
+        os.makedirs(os.path.dirname(p), exist_ok=True)
+        line = "\t".join([
+            time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            event,
+            (head(root) or "")[:9],
+            branch(root) or "-",
+            os.environ.get("CLAUDE_AGENT") or os.environ.get("OPENCODE_AGENT") or "-",
+            re.sub(r"\s+", " ", str(detail))[:400],
+        ])
+        with open(p, "a") as fh:
+            fh.write(line + "\n")
+    except Exception:
+        pass
+
+
+def receipt_write(root: str, kind: str, verdict: str, subject: str, detail: str, by: str) -> int:
+    r = {
+        "kind": kind,
+        "verdict": verdict,
+        "commit": head(root),
+        "branch": branch(root),
+        "subject": subject or None,
+        "subjectDigest": subject_digest(root, subject),
+        "detail": detail,
+        "by": by,
+        "at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "treeClean": tree_clean(root),
+        "env": environment(root),
+    }
+    p = receipt_path(root, kind)
+    os.makedirs(os.path.dirname(p), exist_ok=True)
+    with open(p, "w") as fh:
+        json.dump(r, fh, indent=2)
+        fh.write("\n")
+    audit(root, f"receipt.{kind}", f"{verdict} by {by}: {detail}")
+    print(f"{kind}: {verdict}  ->  {os.path.relpath(p, root)}")
+    return 0
+
+
+def receipt_problem(root: str, kind: str, verdict: str | None, max_age_min: int,
+                    require_commit: bool = True) -> str | None:
+    """Why this receipt does not hold, or None."""
+    p = receipt_path(root, kind)
+    if not os.path.exists(p):
+        return f"there is no {kind} receipt"
+    try:
+        r = json.load(open(p))
+    except Exception as e:
+        return f"the {kind} receipt is unreadable ({e})"
+    if verdict and r.get("verdict") != verdict:
+        return f'the {kind} receipt says "{r.get("verdict")}", not "{verdict}"'
+    if require_commit:
+        h = head(root)
+        if r.get("commit") != h:
+            return (f"the {kind} receipt is for {str(r.get('commit'))[:9]} but HEAD is {h[:9]} — "
+                    f"the work changed after it was granted")
+    if r.get("subject") and r.get("subjectDigest"):
+        now = subject_digest(root, r["subject"])
+        if now and now != r["subjectDigest"]:
+            return (f"the {kind} receipt is for a different version of {r['subject']} — "
+                    f"it was edited after approval")
+    try:
+        age = (time.time() - calendar.timegm(time.strptime(r["at"], "%Y-%m-%dT%H:%M:%SZ"))) / 60
+    except Exception:
+        return f"the {kind} receipt has no readable timestamp"
+    if age > max_age_min:
+        return f"the {kind} receipt is {int(age)} minutes old (limit {max_age_min})"
+    return None
+
+
+# ------------------------------------------------------------------------------------- guard
+
+DESTRUCTIVE = [
+    (r"\bgit\s+stash\b(?!\s+(list|show))", "git stash hides uncommitted work; commit path-scoped instead"),
+    (r"\bgit\s+reset\s+(--hard|--merge|--keep)\b", "git reset --hard destroys uncommitted work"),
+    (r"\bgit\s+clean\b", "git clean deletes untracked files"),
+    (r"\bgit\s+(checkout|restore)\s+(--\s+)?\.(\s|$)", "this discards every uncommitted change"),
+    (r"\bgit\s+(push|branch)\b[^|;&\n]*--force(-with-lease)?\b", "force-push rewrites published history"),
+    (r"\bgit\s+filter-(branch|repo)\b", "history rewriting is the maintainer's decision"),
+    (r"\brm\s+(-[a-zA-Z]*\s+)*(-rf|-fr)\s+(/|~|\$HOME)(\s|$)", "refusing rm -rf of a root or home path"),
+]
+PUBLISHING = [
+    (r"\bgit\s+tag\b(?!\s+(-l|--list|-n))", "a tag is a public promise — the maintainer's call"),
+    (r"\bgit\s+push\b[^|;&\n]*(--tags|\brefs/tags/)", "pushing tags is the maintainer's call"),
+    (r"\b(npm|pnpm|yarn|bun)\s+publish\b", "publishing is the maintainer's call"),
+    (r"\bcargo\s+publish\b", "publishing is the maintainer's call"),
+    (r"\b(twine|poetry)\s+(upload|publish)\b", "publishing is the maintainer's call"),
+    (r"\bgh\s+release\s+(create|edit|delete|upload)\b", "cutting a release is the maintainer's call"),
+    (r"\bdocker\s+push\b", "pushing an image is a deploy — the maintainer's call"),
+]
+STAGING = [
+    (r"\bgit\s+add\s+(-A|--all|\.)(\s|$)", "commit path-scoped: git add <explicit paths>"),
+    (r"\bgit\s+commit(\s+-{1,2}[\w-]+)*\s+(-[a-zA-Z]*a[a-zA-Z]*|--all)(\s|$)",
+     "git commit -a stages the whole tree; stage explicit paths"),
+]
+# Commands that put a change in front of users. Detected conservatively: a false positive costs
+# one approval, a false negative costs an unreviewed deployment.
+DEPLOY_PATTERNS = [
+    r"\b(kubectl|helm)\s+(apply|rollout|upgrade|install|delete)\b",
+    r"\b(terraform|tofu)\s+(apply|destroy)\b",
+    r"\b(serverless|sls)\s+deploy\b",
+    r"\baws\s+(deploy|ecs|lambda|cloudformation|s3\s+sync)\b",
+    r"\b(gcloud|az)\s+\w+\s+deploy\b",
+    r"\b(flyctl|fly|vercel|netlify|heroku|railway|render)\s+(deploy|releases?)\b",
+    r"\bdocker\s+(compose\s+)?(up|stack\s+deploy)\b[^|;&\n]*(prod|production)",
+    r"\bansible-playbook\b",
+    r"\bgh\s+workflow\s+run\b[^|;&\n]*(deploy|release|prod)",
+]
+
+CREDENTIALS = [
+    # [^|;&\n] rather than [^|;&]: the negated class matched newlines, so in a multi-line
+    # command a reader verb on line 1 paired with a credential word forty lines later. The
+    # verb list stays to tools whose whole job is to emit a file's contents -- adding
+    # interpreters made it fire on any script that merely mentions one.
+    (r"(^|[\s;|&(])(cat|bat|less|more|head|tail|strings|xxd|od|cp|scp|rsync|curl)\b[^|;&\n]*"
+     r"(\.env(?!\.(?:example|sample|template|dist))[\w.-]*|/\.ssh/|/\.aws/|/\.gnupg/|/\.kube/|"
+     r"/\.docker/|\.npmrc|\.pypirc|\.netrc|id_rsa|id_ed25519|\.pem|\.p12|\.kdbx|"
+     r"credentials(\.json)?|secrets?\.ya?ml|service[-_]account[\w.-]*\.json)",
+     "reading a credential file is forbidden"),
+    (r"(^|[\s;|&(])(printenv|env)\b[^|;&\n]*\b\w*(SECRET|TOKEN|PASSWORD|PASSWD|"
+     r"API[-_]?KEY|PRIVATE[-_]?KEY|CREDENTIAL)\w*",
+     "printing a secret from the environment is forbidden"),
+    (r"(^|[\s;|&(])echo\s+\"?\$\{?\w*(SECRET|TOKEN|PASSWORD|API[-_]?KEY|"
+     r"PRIVATE[-_]?KEY)\w*",
+     "echoing a secret from the environment is forbidden"),
+    (r"\b(sk-[A-Za-z0-9]{12,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{12,})",
+     "a credential appears in this command line"),
+]
+
+
+def guard_problem(root: str, command: str, cfg: dict) -> str | None:
+    enforce = cfg.get("enforce") or {}
+    groups = []
+    if enforce.get("blockDestructiveGit", True):
+        groups += DESTRUCTIVE + STAGING
+    if enforce.get("blockPublishing", True):
+        groups += PUBLISHING
+    if enforce.get("blockCredentialReads", True):
+        groups += CREDENTIALS
+    for pattern, why in groups:
+        if re.search(pattern, command):
+            return f"{why}."
+
+    protected = cfg.get("protected") or ["main", "master"]
+    trunk = cfg.get("trunk") or "main"
+    prot_re = "|".join(re.escape(p).replace(r"\*", r"[^\s]*") for p in set(protected + [trunk]))
+    max_age = int(((cfg.get("receipts") or {}).get("maxAgeMin")) or DEFAULT_MAX_AGE_MIN)
+    approvals = cfg.get("approvals") or {}
+    cur = branch(root)
+
+    if enforce.get("pushToTrunkNeedsGate", True) and re.search(r"\bgit\s+push\b", command):
+        named = re.search(r"\bgit\s+push\b\s+\S+\s+\S", command)
+        targets_protected = bool(re.search(rf"\b({prot_re})\b", command)) or (
+            not named and re.fullmatch(rf"({prot_re})", cur or "") is not None)
+        if targets_protected:
+            why = receipt_problem(root, "gate", "passed", max_age)
+            if why:
+                return (f"pushing a protected branch needs a passed gate receipt, and {why}.\n"
+                        f"Run `/agentic-sdlc:gate` (the mechanical checks and the secret scan), or "
+                        f"push a feature branch and open a pull request instead — that needs no "
+                        f"receipt.")
+
+    if enforce.get("mergeNeedsReadiness", True):
+        merging = re.search(r"\bgh\s+pr\s+merge\b", command) or (
+            re.search(r"\bgit\s+merge\b", command)
+            and not re.search(r"--(abort|continue|quit)\b", command)
+            and re.fullmatch(rf"({prot_re})", cur or "") is not None)
+        if merging:
+            why = receipt_problem(root, "readiness", "ready", max_age)
+            if why:
+                return (f"merging needs a READY readiness receipt, and {why}.\n"
+                        f"Run `/agentic-sdlc:readiness`. It runs the reviewers, the secret scan and "
+                        f"the verify command, and checks every acceptance criterion against evidence.")
+            if approvals.get("merge") == "human":
+                why = receipt_problem(root, "approval_merge", "granted", max_age)
+                if why:
+                    return (f"this project requires a human to approve a merge, and {why}.\n"
+                            f"A person runs:  sdlc approve merge --as '<their name>'\n"
+                            f"An agent must not run it for them — the approval records who is "
+                            f"accountable, and an agent approving its own work records nothing.")
+
+    # X7: a ceiling the agent cannot raise for itself. Checked last, so a destructive command
+    # is still refused for the right reason when the budget also happens to be spent.
+    over = budget_problem(root, cfg)
+    if over:
+        return over
+
+    # Deployment is a separate authority from merging, and defaults to a human's.
+    deploying = any(re.search(pat, command) for pat in DEPLOY_PATTERNS)
+    if deploying:
+        if approvals.get("release", "human") == "human":
+            why = receipt_problem(root, "approval_release", "granted", max_age)
+            if why:
+                return (f"deploying needs a human approval, and {why}.\n"
+                        f"A person runs:  sdlc approve release --as '<their name>'\n"
+                        f"Deployment changes what users are running. No agent grants itself that.")
+        why = receipt_problem(root, "readiness", "ready", max_age)
+        if why:
+            return f"deploying needs a READY readiness receipt, and {why}."
+    return None
+
+
+def cmd_guard(args) -> int:
+    """The refusal point. Reads a host's tool JSON on stdin, or one command with --command.
+
+    The same rules serve every host: Claude Code, Codex and Cline send the same wire shape,
+    opencode's plugin reshapes into it, and the git hooks pass --command.
+    """
+    if getattr(args, "command", None):
+        root = repo_root()
+        problem = guard_problem(root, args.command, load_config(root))
+        if problem:
+            audit(root, "blocked", f"{problem.splitlines()[0]} :: {args.command}")
+            print(f"BLOCKED by agentic-sdlc: {problem}", file=sys.stderr)
+            return 2
+        return 0
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return 0  # never break a session over a malformed payload
+    tool = payload.get("tool_name") or payload.get("tool") or ""
+    inp = payload.get("tool_input") or payload.get("input") or {}
+    cwd = payload.get("cwd") or os.getcwd()
+    root = repo_root(cwd)
+    cfg = load_config(root)
+
+    if tool in ("Bash", "bash", "shell"):
+        command = str(inp.get("command", ""))
+        if not command:
+            return 0
+        problem = guard_problem(root, command, cfg)
+        if problem:
+            audit(root, "blocked", f"{problem.splitlines()[0]} :: {command}")
+            print(f"BLOCKED by agentic-sdlc: {problem}\n"
+                  f"This is a pipeline rule, not a preference. Do not work around it — choose "
+                  f"another route or stop and report.", file=sys.stderr)
+            return 2
+    elif tool in ("Edit", "Write", "NotebookEdit", "edit", "write"):
+        path = str(inp.get("file_path") or inp.get("path") or "")
+        if re.search(r"(^|/)(\.env(\.(?!example|sample|template)[\w.-]+)?|credentials\.json|"
+                     r"secrets\.ya?ml|id_rsa|id_ed25519|.*\.pem)$|(^|/)\.(ssh|aws)/", path):
+            print(f"BLOCKED by agentic-sdlc: {path} holds credentials.", file=sys.stderr)
+            return 2
+    return 0
+
+
+# ------------------------------------------------------------------------------- subcommands
+
+
+def cmd_init(args) -> int:
+    root = repo_root()
+    cfg = detect(root)
+    existing = load_config(root)
+    if existing:
+        # Keep what a human has set; only fill what detection newly knows.
+        for k, v in existing.items():
+            if k != "$schema":
+                cfg[k] = v
+        cfg.setdefault("version", 2)
+    out = json.dumps(cfg, indent=2) + "\n"
+    target = os.path.join(root, "sdlc.config.json")
+    if not args.write:
+        print(out, end="")
+        print(f"\n# not written — re-run with --write to save {os.path.relpath(target, root)}",
+              file=sys.stderr)
+        return 0
+    open(target, "w").write(out)
+    print(f"wrote {os.path.relpath(target, root)}")
+    if cfg["spec"]["engine"] == "openspec" and not os.path.isdir(os.path.join(root, "openspec")):
+        print("openspec is available but this repo has no openspec/ — run: openspec init")
+    if not cfg.get("verifyCmd"):
+        print("no verify command could be detected — set \"verifyCmd\" by hand; the pipeline "
+              "cannot gate anything without it")
+    return 0
+
+
+def cmd_config(_args) -> int:
+    root = repo_root()
+    p = config_path(root)
+    if not p:
+        print("no sdlc.config.json — run: sdlc init --write", file=sys.stderr)
+        return 1
+    print(f"# {os.path.relpath(p, root)}")
+    print(json.dumps(load_config(root), indent=2))
+    return 0
+
+
+def cmd_receipt(args) -> int:
+    root = repo_root()
+    if args.receipt_action == "write":
+        if not args.verdict:
+            print("sdlc receipt write needs --verdict", file=sys.stderr)
+            return 3
+        return receipt_write(root, args.kind, args.verdict, args.subject, args.detail, args.by)
+    if args.receipt_action == "show":
+        p = receipt_path(root, args.kind)
+        if not os.path.exists(p):
+            print(f"no {args.kind} receipt", file=sys.stderr)
+            return 1
+        print(open(p).read(), end="")
+        return 0
+    cfg = load_config(root)
+    max_age = args.max_age_min or int(((cfg.get("receipts") or {}).get("maxAgeMin")) or DEFAULT_MAX_AGE_MIN)
+    why = receipt_problem(root, args.kind, args.verdict, max_age, require_commit=not args.any_commit)
+    if why:
+        print(f"{args.kind} receipt does not hold: {why}", file=sys.stderr)
+        return 1
+    print(f"{args.kind} receipt holds")
+    return 0
+
+
+def fingerprint_line(env: dict) -> str:
+    keys = [k for k in ("os", "arch", "python", "node", "go", "cargo", "git") if k in env]
+    return "  ".join(f"{k} {env[k]}" for k in keys)
+
+
+def cmd_status(_args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    print(f"repo      {os.path.basename(root)}")
+    print(f"branch    {branch(root)}   (trunk: {cfg.get('trunk', '?')})")
+    print(f"head      {head(root)[:9]}  tree {'clean' if tree_clean(root) else 'DIRTY'}")
+    spec = cfg.get("spec") or {}
+    print(f"spec      engine {spec.get('engine', '?')}, root {spec.get('docsRoot', '?')}")
+    print(f"verify    {cfg.get('verifyCmd') or '(none set — the gate cannot run)'}")
+    if cfg.get("gateCmd"):
+        print(f"gate      {cfg['gateCmd']}")
+    print("receipts")
+    for kind in RECEIPT_KINDS:
+        p = receipt_path(root, kind)
+        if not os.path.exists(p):
+            continue
+        try:
+            r = json.load(open(p))
+        except Exception:
+            continue
+        why = receipt_problem(root, kind, None, 10 ** 9)
+        mark = "stale" if why else "current"
+        print(f"  {kind:<13} {r.get('verdict','?'):<18} {str(r.get('commit',''))[:9]}  {r.get('at','')}  {mark}")
+    print(f"toolchain  {fingerprint_line(environment(root))}")
+    return 0
+
+
+def cmd_doctor(_args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    problems, notes = [], []
+
+    if not git("rev-parse", "--is-inside-work-tree", cwd=root):
+        problems.append("not inside a git repository — the pipeline needs git")
+    if not cfg:
+        problems.append("no sdlc.config.json — run: sdlc init --write")
+    else:
+        if not cfg.get("verifyCmd"):
+            problems.append('"verifyCmd" is not set — nothing can be gated')
+        if not cfg.get("secretScan"):
+            notes.append('"secretScan" is not set — install gitleaks and re-run `sdlc init`')
+        if not (cfg.get("quality") or {}).get("cmd"):
+            notes.append('"quality.cmd" is not set — the gate has no deterministic analysis on '
+                         "new code, so maintainability and complexity are reviewed by reading "
+                         "only. An LLM reviewer is a complement to a static analyser, not a "
+                         "substitute for one.")
+        engine = (cfg.get("spec") or {}).get("engine")
+        if engine == "openspec":
+            if not which("openspec"):
+                problems.append('spec.engine is "openspec" but the openspec CLI is not installed')
+            elif not os.path.isdir(os.path.join(root, "openspec")):
+                problems.append("openspec is configured but this repo has no openspec/ — run: openspec init")
+        if cfg.get("trunk") and cfg["trunk"] != detect_trunk(root):
+            notes.append(f'config says trunk "{cfg["trunk"]}" but git says "{detect_trunk(root)}"')
+
+    present = detect_platforms()
+    here = [k for k, v in present.items() if v]
+    print(f"toolchain       {fingerprint_line(environment(root))}")
+    print(f"hosts detected  {', '.join(here) if here else 'none'}")
+    installed = []
+    for rel, label in ((".cursor/rules/agentic-sdlc.mdc", "cursor"),
+                       (".github/copilot-instructions.md", "copilot"),
+                       (".clinerules/agentic-sdlc.md", "cline"),
+                       (".roo/rules/agentic-sdlc.md", "roo"),
+                       (".kilocode/rules/agentic-sdlc.md", "kilo"),
+                       (".windsurf/rules/agentic-sdlc.md", "windsurf"),
+                       (".continue/rules/agentic-sdlc.md", "continue"),
+                       (".gemini/policies/agentic-sdlc.toml", "gemini"),
+                       ("AGENTS.md", "agents.md"),
+                       (".github/workflows/sdlc-gate.yml", "ci")):
+        if os.path.exists(os.path.join(root, rel)):
+            installed.append(label)
+    hooks_dir = git("rev-parse", "--git-path", "hooks", cwd=root) or ".git/hooks"
+    if not os.path.isabs(hooks_dir):
+        hooks_dir = os.path.join(root, hooks_dir)
+    hooked = [n for n in ("pre-commit", "pre-push")
+              if os.path.exists(os.path.join(hooks_dir, n))
+              and "agentic-sdlc" in open(os.path.join(hooks_dir, n), errors="replace").read()]
+    if hooked:
+        installed.append("git-hooks(" + ",".join(hooked) + ")")
+    print(f"installed here  {', '.join(installed) if installed else 'nothing yet — run: sdlc install'}")
+    missing = [h for h in here if h in TARGETS and TARGETS[h][0] and h not in " ".join(installed)]
+    if missing:
+        notes.append(f"detected but not installed: {', '.join(missing)} — run `sdlc install "
+                     f"{' '.join(missing)}`")
+    if not hooked:
+        notes.append("no git hooks — they are the only local enforcement on hosts without a "
+                     "tool hook (Cursor, Copilot, Windsurf). Run `sdlc install git-hooks`")
+    if not os.path.exists(os.path.join(root, ".github/workflows/sdlc-gate.yml")):
+        notes.append("no CI gate — the only layer an agent cannot reach. Run `sdlc install ci`")
+
+    openf = [f for f in finding_load_all(root) if f.get("outcome") in ("open", "unexecuted")]
+    if openf:
+        crit = sum(1 for f in openf
+                   if (f.get("classification") or {}).get("severity") in ("critical", "high"))
+        notes.append(f"{len(openf)} finding(s) still open or unexecuted"
+                     + (f", {crit} of them critical or high" if crit else "")
+                     + " — see `sdlc finding list --open`")
+
+    hooks = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "hooks", "hooks.json")
+    if os.path.exists(hooks):
+        notes.append(f"hooks shipped at {hooks} — enforcement is active when the plugin is installed")
+    else:
+        problems.append("hooks/hooks.json is missing — the pipeline would be advisory only")
+
+    for name, why in (("git", "required"), ("gh", "pull requests"), ("gitleaks", "secret scanning"),
+                      ("openspec", "the OpenSpec engine")):
+        if not which(name):
+            (problems if why == "required" else notes).append(f"{name} not found ({why})")
+
+    for n in notes:
+        print(f"note     {n}")
+    for p in problems:
+        print(f"PROBLEM  {p}")
+    print("doctor: ok" if not problems else f"doctor: {len(problems)} problem(s)")
+    return 0 if not problems else 1
+
+
+
+
+# ============================================================================== install
+#
+# One pipeline, many hosts. The canonical sources are agents/, commands/ and docs/rules.md;
+# every adapter below is a pure mapping from those into one platform's layout. Nothing is
+# authored twice, so nothing can drift.
+#
+# Three enforcement layers, because platforms differ in what they allow:
+#   1. a native tool hook  — Claude Code, Codex, Cline, opencode: refuses before the action
+#   2. git hooks           — everywhere, because every agent shells out to git
+#   3. CI                  — the only layer an agent cannot reach at all
+# What a platform cannot do is written down in docs/platforms.md rather than implied away.
+
+BEGIN = "BEGIN agentic-sdlc (generated — edit docs/rules.md or sdlc.config.json, then re-run)"
+END = "END agentic-sdlc"
+
+
+def plugin_root() -> str:
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def read_plugin(*parts: str) -> str:
+    try:
+        return open(os.path.join(plugin_root(), *parts), errors="replace").read()
+    except OSError:
+        return ""
+
+
+class Writer:
+    """Collects writes so --dry-run can show them and nothing is half-applied."""
+
+    def __init__(self, dry: bool):
+        self.dry, self.written, self.skipped = dry, [], []
+        self.pending = {}   # several adapters write AGENTS.md; it is one file, not five
+
+    def put(self, path: str, content: str, mode: int = 0o644) -> None:
+        if path in self.pending:
+            self.skipped.append(path)
+            return
+        try:
+            old = open(path, errors="replace").read()
+        except OSError:
+            old = None
+        self.pending[path] = content
+        if old == content:
+            self.skipped.append(path)
+            return
+        self.written.append(path)
+        if self.dry:
+            return
+        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        with open(path, "w") as fh:
+            fh.write(content)
+        os.chmod(path, mode)
+
+    def block(self, path: str, body: str, comment: str = "<!-- {} -->") -> None:
+        """Write our section into a file we do not own, leaving everything else alone."""
+        begin, end = comment.format(BEGIN), comment.format(END)
+        section = f"{begin}\n{body.strip()}\n{end}\n"
+        if path in self.pending:
+            old = self.pending[path]
+        else:
+            try:
+                old = open(path, errors="replace").read()
+            except OSError:
+                old = ""
+        if begin in old and end in old:
+            head, _, rest = old.partition(begin)
+            _, _, tail = rest.partition(end)
+            new = head + section + tail.lstrip("\n")
+        elif old.strip():
+            new = old.rstrip("\n") + "\n\n" + section
+        else:
+            new = section
+        self.put(path, new)
+
+    def report(self) -> None:
+        verb = "would write" if self.dry else "wrote"
+        for p in self.written:
+            print(f"  {verb} {p}")
+        if self.skipped:
+            print(f"  ({len(self.skipped)} already current)")
+
+
+def detect_platforms() -> dict:
+    """Which hosts are present. A binary on PATH or a config directory both count."""
+    home = os.path.expanduser("~")
+    checks = {
+        "claude-code": which("claude") or os.path.isdir(f"{home}/.claude"),
+        "opencode": which("opencode") or os.path.isdir(f"{home}/.config/opencode"),
+        "codex": which("codex") or os.path.isdir(f"{home}/.codex"),
+        "gemini": which("gemini") or os.path.isdir(f"{home}/.gemini"),
+        "cursor": which("cursor-agent") or which("cursor") or os.path.isdir(f"{home}/.cursor"),
+        "copilot": os.path.isdir(f"{home}/.vscode") or which("code"),
+        "cline": bool(glob.glob(f"{home}/.vscode/extensions/saoudrizwan.claude-dev-*")),
+        "roo": bool(glob.glob(f"{home}/.vscode/extensions/rooveterinaryinc.roo-cline-*")),
+        "kilo": bool(glob.glob(f"{home}/.vscode/extensions/kilocode.kilo-code-*")),
+        "windsurf": os.path.isdir("/Applications/Windsurf.app") or os.path.isdir(f"{home}/.codeium"),
+        "continue": os.path.isdir(f"{home}/.continue"),
+        "aider": which("aider"),
+        "zed": which("zed") or os.path.isdir(f"{home}/.config/zed"),
+        "amp": which("amp"),
+        "warp": os.path.isdir("/Applications/Warp.app"),
+        "factory": which("droid"),
+    }
+    return {k: bool(v) for k, v in checks.items()}
+
+
+def interpreter() -> str:
+    """The command that will run this CLI from a hook. Windows often lacks `python3`."""
+    for cand in ("python3", "python"):
+        if which(cand):
+            return cand
+    return sys.executable or "python3"
+
+
+def cli_path() -> str:
+    return os.path.join(plugin_root(), "bin", "sdlc")
+
+
+def guard_command() -> str:
+    return f'{interpreter()} "{cli_path()}" guard'
+
+
+
+# ---------------------------------------------------------------- what each platform is told
+
+def rules_body(cfg: dict) -> str:
+    """The pipeline's rules, plus this project's bindings. One source: docs/rules.md."""
+    rules = read_plugin("docs", "rules.md")
+    rules = re.sub(r"^# .*\n+", "", rules, count=1)  # the host file supplies the title
+    lines = ["## The agentic SDLC pipeline", "",
+             "This project uses the agentic-sdlc pipeline. Work moves through stages, each owned",
+             "by one agent and closed by a receipt bound to a commit. Do not skip a stage: on some",
+             "hosts the skip is refused outright, and on all of them a git hook and CI will catch",
+             "it later, more expensively.", ""]
+    if cfg:
+        lines += ["### This project", "",
+                  f"- trunk: `{cfg.get('trunk', 'main')}`",
+                  f"- verify: `{cfg.get('verifyCmd') or '(not set — set verifyCmd in sdlc.config.json)'}`"]
+        if cfg.get("gateCmd"):
+            lines.append(f"- gate: `{cfg['gateCmd']}`")
+        spec = cfg.get("spec") or {}
+        lines.append(f"- specifications: {spec.get('engine', 'prd-frd')} in `{spec.get('docsRoot', 'docs/specs')}`")
+        if cfg.get("profile"):
+            lines.append(f"- profile: `{cfg['profile']}` — its standards apply to reviews")
+        if cfg.get("heavy"):
+            lines.append(f"- heavy work: {cfg['heavy']}")
+        lines.append("")
+    lines += ["### Commands", "",
+              "```sh",
+              "sdlc status            # which stages have left evidence, which have not",
+              "sdlc trace             # requirement -> commit -> test -> receipts",
+              "sdlc receipt check readiness --verdict ready",
+              "sdlc feedback read     # why the last attempt failed, before you retry",
+              "```", ""]
+    return "\n".join(lines) + "\n" + rules.strip() + "\n"
+
+
+def stage_prompts() -> list:
+    """(name, description, body) for each pipeline stage, from commands/."""
+    out = []
+    for f in sorted(glob.glob(os.path.join(plugin_root(), "commands", "*.md"))):
+        text = open(f, errors="replace").read()
+        m = re.match(r"^---\n([\s\S]*?)\n---\n?", text)
+        fm, body = (m.group(1), text[m.end():]) if m else ("", text)
+        desc = ""
+        d = re.search(r"^description:\s*(.+)$", fm, re.M)
+        if d:
+            desc = d.group(1).strip()
+        # Shell injections and plugin-root paths mean nothing outside Claude Code.
+        body = re.sub(r"^!`.*`\s*$", "", body, flags=re.M)
+        body = body.replace("${CLAUDE_PLUGIN_ROOT}/bin/sdlc", "sdlc")
+        body = re.sub(r"\n{3,}", "\n\n", body).strip()
+        out.append((os.path.basename(f)[:-3], desc, body))
+    return out
+
+
+def agent_summary() -> str:
+    """Who owns what — so a host without subagents still knows the division of labour."""
+    rows = []
+    for f in sorted(glob.glob(os.path.join(plugin_root(), "agents", "*.md"))):
+        text = open(f, errors="replace").read()
+        m = re.search(r"^description:\s*>?\s*\n?([\s\S]*?)(?=^\w+:|^---)", text, re.M)
+        desc = re.sub(r"\s+", " ", m.group(1)).strip() if m else ""
+        rows.append(f"- **{os.path.basename(f)[:-3]}** — {desc[:160]}")
+    return "\n".join(rows)
+
+
+
+# ------------------------------------------------------------------------------- adapters
+#
+# Each adapter takes (root, cfg, w: Writer) and writes that platform's files. Every path is
+# verified against the real tool on 2026-10-25 — see docs/platforms.md for the evidence.
+
+def _agents_md(root: str, cfg: dict, w: Writer, name: str = "AGENTS.md") -> None:
+    """The universal layer: agents.md is read by 20+ hosts, so this is most tools' whole story."""
+    w.block(os.path.join(root, name), rules_body(cfg))
+
+
+def _rules_file(root: str, cfg: dict, w: Writer, relpath: str) -> None:
+    w.block(os.path.join(root, relpath), rules_body(cfg))
+
+
+def _prompt_files(root: str, w: Writer, directory: str, suffix: str = ".md",
+                  prefix: str = "sdlc-", frontmatter=None) -> None:
+    for name, desc, body in stage_prompts():
+        head = frontmatter(name, desc) if frontmatter else ""
+        w.put(os.path.join(root, directory, f"{prefix}{name}{suffix}"), head + body + "\n")
+
+
+def adapt_opencode(root: str, cfg: dict, w: Writer) -> None:
+    """opencode: agents with real permissions, commands, and a plugin that calls the guard."""
+    prefix = os.path.expanduser("~/.config/opencode")
+    for f in sorted(glob.glob(os.path.join(plugin_root(), "agents", "*.md"))):
+        text = open(f, errors="replace").read().replace("${CLAUDE_PLUGIN_ROOT}", plugin_root())
+        m = re.match(r"^---\n([\s\S]*?)\n---", text)
+        if m:
+            fm = m.group(1)
+            tools = re.search(r"^tools:\s*\[(.*?)\]\s*$", fm, re.M)
+            edits = True
+            if tools:
+                listed = [t.strip() for t in tools.group(1).split(",")]
+                edits = any(t in ("Write", "Edit", "NotebookEdit") for t in listed)
+                fm = re.sub(r"^tools:.*$\n?", "", fm, flags=re.M)
+            mode = "primary" if re.search(r"(implementer|spec-writer)", f) else "subagent"
+            text = (f"---\n{fm.rstrip()}\nmode: {mode}\ntemperature: 0.1\n"
+                    f"permission:\n  edit: {'allow' if edits else 'deny'}\n  bash: allow\n---"
+                    + text[m.end():])
+        w.put(os.path.join(prefix, "agents", os.path.basename(f)), text)
+    for f in sorted(glob.glob(os.path.join(plugin_root(), "commands", "*.md"))):
+        text = open(f, errors="replace").read().replace("${CLAUDE_PLUGIN_ROOT}", plugin_root())
+        w.put(os.path.join(prefix, "commands", "sdlc-" + os.path.basename(f)), text)
+    tpl = read_plugin("opencode", "plugin", "agentic-sdlc.ts")
+    w.put(os.path.join(prefix, "plugins", "agentic-sdlc.ts"),
+          tpl.replace("__PLUGIN_ROOT__", plugin_root()))
+    _agents_md(root, cfg, w)
+
+
+def adapt_codex(root: str, cfg: dict, w: Writer) -> None:
+    """Codex CLI: PreToolUse hooks with the same wire contract as Claude Code."""
+    hooks_path = os.path.expanduser("~/.codex/hooks.json")
+    try:
+        existing = json.load(open(hooks_path))
+    except Exception:
+        existing = {}
+    hooks = existing.setdefault("hooks", {})
+    entries = [e for e in hooks.get("PreToolUse", [])
+               if not any("sdlc" in (h.get("command") or "") for h in e.get("hooks", []))]
+    entries.append({"hooks": [{"type": "command", "command": guard_command(), "timeout": 10}]})
+    hooks["PreToolUse"] = entries          # every other event the user configured is untouched
+    w.put(hooks_path, json.dumps(existing, indent=2) + "\n")
+    _prompt_files(os.path.expanduser("~/.codex"), w, "prompts")
+    _agents_md(root, cfg, w)
+
+
+def adapt_gemini(root: str, cfg: dict, w: Writer) -> None:
+    """Gemini CLI: no PreToolUse, but a policy engine that denies static patterns."""
+    lines = ["# agentic-sdlc — generated. Gemini has no pre-tool hook, so only the static",
+             "# refusals live here; the receipt-dependent gates are enforced by the git hooks.",
+             "# Re-run `sdlc install gemini` to regenerate.", ""]
+    groups = [("destructive", DESTRUCTIVE), ("publishing", PUBLISHING), ("staging", STAGING),
+              ("credentials", CREDENTIALS)]
+    pri = 100
+    for label, rules in groups:
+        for pattern, why in rules:
+            lines += ["[[rules]]", 'toolName = "run_shell_command"',
+                      f"argsPattern = {json.dumps(pattern)}", 'decision = "deny"',
+                      f"priority = {pri}", f"# {label}: {why}", ""]
+            pri += 1
+    w.put(os.path.join(root, ".gemini", "policies", "agentic-sdlc.toml"), "\n".join(lines))
+    for name, desc, body in stage_prompts():
+        toml = (f'# agentic-sdlc — generated\ndescription = {json.dumps(desc or name)}\n'
+                f'prompt = """\n{body}\n"""\n')
+        w.put(os.path.join(root, ".gemini", "commands", "sdlc", f"{name}.toml"), toml)
+    _agents_md(root, cfg, w)
+    _agents_md(root, cfg, w, "GEMINI.md")
+
+
+def adapt_cline(root: str, cfg: dict, w: Writer) -> None:
+    """Cline: .clinerules, plus PreToolUse hooks as executables named for the event."""
+    _rules_file(root, cfg, w, os.path.join(".clinerules", "agentic-sdlc.md"))
+    hook = ("#!/bin/sh\n"
+            "# agentic-sdlc — refuses a tool call that would skip a pipeline stage.\n"
+            "# Cline runs this with the hook payload on stdin; exit 2 blocks the call.\n"
+            f'exec {interpreter()} "{cli_path()}" guard\n')
+    w.put(os.path.join(root, ".clinerules", "hooks", "PreToolUse"), hook, mode=0o755)
+    for name, desc, body in stage_prompts():
+        w.put(os.path.join(root, ".clinerules", "workflows", f"sdlc-{name}.md"),
+              f"# {desc or name}\n\n{body}\n")
+    _agents_md(root, cfg, w)
+
+
+def adapt_cursor(root: str, cfg: dict, w: Writer) -> None:
+    """Cursor: .cursor/rules/*.mdc with alwaysApply, and .cursor/commands/*.md."""
+    body = ("---\n"
+            "description: The agentic-sdlc pipeline — stages, receipts and what is refused\n"
+            "alwaysApply: true\n"
+            "---\n\n" + rules_body(cfg))
+    w.put(os.path.join(root, ".cursor", "rules", "agentic-sdlc.mdc"), body)
+    if cfg.get("profile"):
+        prof = read_plugin("profiles", f"{cfg['profile']}.md")
+        if prof:
+            w.put(os.path.join(root, ".cursor", "rules", f"agentic-sdlc-{cfg['profile']}.mdc"),
+                  f"---\ndescription: Standards for a {cfg['profile']} project\n"
+                  f"alwaysApply: true\n---\n\n{prof}")
+    _prompt_files(root, w, os.path.join(".cursor", "commands"))
+    _agents_md(root, cfg, w)
+
+
+def adapt_copilot(root: str, cfg: dict, w: Writer) -> None:
+    """GitHub Copilot: repository instructions plus prompt files."""
+    _rules_file(root, cfg, w, os.path.join(".github", "copilot-instructions.md"))
+    def fm(name, desc):
+        return f"---\nmode: agent\ndescription: {desc or name}\n---\n\n"
+    _prompt_files(root, w, os.path.join(".github", "prompts"), suffix=".prompt.md",
+                  frontmatter=fm)
+    _agents_md(root, cfg, w)
+
+
+def adapt_roo(root: str, cfg: dict, w: Writer) -> None:
+    _rules_file(root, cfg, w, os.path.join(".roo", "rules", "agentic-sdlc.md"))
+    _agents_md(root, cfg, w)
+
+
+def adapt_kilo(root: str, cfg: dict, w: Writer) -> None:
+    _rules_file(root, cfg, w, os.path.join(".kilocode", "rules", "agentic-sdlc.md"))
+    _agents_md(root, cfg, w)
+
+
+def adapt_windsurf(root: str, cfg: dict, w: Writer) -> None:
+    _rules_file(root, cfg, w, os.path.join(".windsurf", "rules", "agentic-sdlc.md"))
+    for name, desc, body in stage_prompts():
+        w.put(os.path.join(root, ".windsurf", "workflows", f"sdlc-{name}.md"),
+              f"---\ndescription: {desc or name}\n---\n\n{body}\n")
+    _agents_md(root, cfg, w)
+
+
+def adapt_continue(root: str, cfg: dict, w: Writer) -> None:
+    _rules_file(root, cfg, w, os.path.join(".continue", "rules", "agentic-sdlc.md"))
+    _agents_md(root, cfg, w)
+
+
+def adapt_aider(root: str, cfg: dict, w: Writer) -> None:
+    _rules_file(root, cfg, w, "CONVENTIONS.md")
+    _agents_md(root, cfg, w)
+
+
+def adapt_generic(root: str, cfg: dict, w: Writer) -> None:
+    """Zed, Amp, Warp, Junie, Factory, Devin, Jules and anything else that reads AGENTS.md."""
+    _agents_md(root, cfg, w)
+
+
+
+def adapt_git_hooks(root: str, cfg: dict, w: Writer) -> None:
+    """The only local enforcement every platform shares: every agent shells out to git.
+
+    An existing hook is never destroyed — our part goes in a guarded block, so a repo that
+    already uses husky or pre-commit keeps working.
+    """
+    hooks_dir = git("rev-parse", "--git-path", "hooks", cwd=root) or ".git/hooks"
+    if not os.path.isabs(hooks_dir):
+        hooks_dir = os.path.join(root, hooks_dir)
+    marker_begin = "# >>> agentic-sdlc >>>"
+    marker_end = "# <<< agentic-sdlc <<<"
+
+    bodies = {
+        "pre-commit": (
+            f'{marker_begin}\n'
+            f'# Staging hygiene and a secret scan on what is actually staged.\n'
+            f'staged=$(git diff --cached --name-only)\n'
+            f'[ -z "$staged" ] || {interpreter()} "{cli_path()}" guard --command '
+            f'"git commit" || exit 2\n'
+            f'{marker_end}\n'),
+        "pre-push": (
+            f'{marker_begin}\n'
+            f'# git feeds "<local ref> <local sha> <remote ref> <remote sha>" on stdin.\n'
+            f'while read -r _ _ remote_ref _; do\n'
+            f'  [ -n "$remote_ref" ] || continue\n'
+            f'  {interpreter()} "{cli_path()}" guard --command "git push origin ${{remote_ref##*/}}" '
+            f'|| exit 2\n'
+            f'done\n'
+            f'{marker_end}\n'),
+    }
+
+    for name, block in bodies.items():
+        path = os.path.join(hooks_dir, name)
+        try:
+            old = open(path, errors="replace").read()
+        except OSError:
+            old = ""
+        if marker_begin in old and marker_end in old:
+            head, _, rest = old.partition(marker_begin)
+            _, _, tail = rest.partition(marker_end)
+            new = head + block.rstrip("\n") + tail
+        elif old.strip():
+            new = old.rstrip("\n") + "\n\n" + block      # keep whatever was already there
+        else:
+            new = "#!/bin/sh\n" + block
+        w.put(path, new, mode=0o755)
+
+
+def adapt_ci(root: str, cfg: dict, w: Writer) -> None:
+    """The layer an agent cannot reach. It re-runs the checks rather than trusting receipts."""
+    verify = cfg.get("gateCmd") or cfg.get("verifyCmd") or "echo 'set verifyCmd in sdlc.config.json' && false"
+    secret = cfg.get("secretScan") or ""
+    quality = (cfg.get("quality") or {}).get("cmd") or ""
+    y = ["# agentic-sdlc — generated by `sdlc install ci`. The authoritative gate: it runs",
+         "# where no agent can reach it, and it re-runs the checks rather than trusting a",
+         "# receipt, because receipts are local to a working copy by design.",
+         "name: SDLC gate", "",
+         "on:", "  pull_request:", "  workflow_dispatch:", "",
+         "permissions:", "  contents: read", "",
+         "jobs:", "  gate:", "    runs-on: ubuntu-latest", "    steps:",
+         "      - uses: actions/checkout@v6", "        with:", "          fetch-depth: 0",
+         "      - name: Verify", f"        run: {verify}"]
+    if secret:
+        y += ["      - name: Secret scan", f"        run: {secret}"]
+    if quality:
+        y += ["      - name: Quality budget on new code", f"        run: {quality}"]
+    y += ["      - name: Traceability",
+          "        run: |",
+          '          python3 "$GITHUB_WORKSPACE/bin/sdlc" trace >> "$GITHUB_STEP_SUMMARY" 2>/dev/null \\',
+          '            || echo "sdlc not vendored in this repo; skipping the trace summary" >> "$GITHUB_STEP_SUMMARY"']
+    w.put(os.path.join(root, ".github", "workflows", "sdlc-gate.yml"), "\n".join(y) + "\n")
+
+
+TARGETS = {
+    "claude-code": (None, "the plugin itself — install it with /plugin install"),
+    "opencode": (adapt_opencode, "agents, commands and a plugin that calls the guard"),
+    "codex": (adapt_codex, "PreToolUse hook, prompts, AGENTS.md"),
+    "gemini": (adapt_gemini, "policy denies, TOML commands, GEMINI.md"),
+    "cline": (adapt_cline, "rules, PreToolUse hook, workflows"),
+    "cursor": (adapt_cursor, "always-on .mdc rules and commands"),
+    "copilot": (adapt_copilot, "repository instructions and prompt files"),
+    "roo": (adapt_roo, ".roo/rules"),
+    "kilo": (adapt_kilo, ".kilocode/rules"),
+    "windsurf": (adapt_windsurf, "rules and workflows"),
+    "continue": (adapt_continue, ".continue/rules"),
+    "aider": (adapt_aider, "CONVENTIONS.md and AGENTS.md"),
+    "generic": (adapt_generic, "AGENTS.md — Zed, Amp, Warp, Junie, Factory, Devin, Jules"),
+    "git-hooks": (adapt_git_hooks, "pre-commit and pre-push — the universal local floor"),
+    "ci": (adapt_ci, "a GitHub Actions gate that no agent can reach"),
+}
+
+# What each host can actually do. Stated here so --list cannot drift from the documentation.
+ENFORCEMENT = {
+    "claude-code": "refuses the tool call", "opencode": "refuses the tool call",
+    "codex": "refuses the tool call", "cline": "refuses the tool call",
+    "gemini": "static policy denies only", "git-hooks": "refuses the git command",
+    "ci": "fails the pull request",
+}
+
+
+def cmd_install(args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    present = detect_platforms()
+
+    if args.list:
+        print("target        enforcement                  what it writes")
+        for name, (fn, what) in TARGETS.items():
+            mark = "·" if not present.get(name, name in ("generic", "git-hooks", "ci")) else "✓"
+            print(f"{mark} {name:<12} {ENFORCEMENT.get(name, 'instructions only'):<28} {what}")
+        print("\n✓ = detected on this machine. Enforcement differs by host — see docs/platforms.md.")
+        return 0
+
+    targets = list(args.targets)
+    if not targets:
+        targets = [k for k, v in present.items() if v and k in TARGETS and TARGETS[k][0]]
+        if not targets:
+            targets = ["generic"]
+        print(f"detected: {', '.join(targets)}")
+    unknown = [t for t in targets if t not in TARGETS]
+    if unknown:
+        print(f"unknown target(s): {', '.join(unknown)}. Try `sdlc install --list`.", file=sys.stderr)
+        return 3
+    if not args.no_git_hooks and "git-hooks" not in targets:
+        targets.append("git-hooks")
+
+    w = Writer(args.dry_run)
+    for t in targets:
+        fn = TARGETS[t][0]
+        if fn is None:
+            print(f"{t}: nothing to install — {TARGETS[t][1]}")
+            continue
+        print(f"{t}:")
+        fn(root, cfg, w)
+    w.report()
+    if not args.dry_run:
+        audit(root, "install", ", ".join(targets))
+    if args.dry_run:
+        print("\nnothing was written — drop --dry-run to apply")
+    else:
+        print("\nNext: `sdlc doctor`, then read docs/platforms.md for what each host can "
+              "actually enforce.")
+    return 0
+
+
+def cmd_uninstall(args) -> int:
+    """Remove only our marker blocks and only files we own. Never a whole file we share."""
+    root = repo_root()
+    removed = []
+    owned = [".cursor/rules/agentic-sdlc.mdc", ".gemini/policies/agentic-sdlc.toml",
+             ".clinerules/hooks/PreToolUse", ".github/workflows/sdlc-gate.yml"]
+    for rel in owned:
+        p = os.path.join(root, rel)
+        if os.path.exists(p):
+            removed.append(rel)
+            if not args.dry_run:
+                os.remove(p)
+    for pattern in (".cursor/commands/sdlc-*", ".github/prompts/sdlc-*", ".gemini/commands/sdlc/*",
+                    ".clinerules/workflows/sdlc-*", ".windsurf/workflows/sdlc-*"):
+        for p in glob.glob(os.path.join(root, pattern)):
+            removed.append(os.path.relpath(p, root))
+            if not args.dry_run:
+                os.remove(p)
+    shared = ["AGENTS.md", "GEMINI.md", "CONVENTIONS.md", ".github/copilot-instructions.md",
+              ".clinerules/agentic-sdlc.md", ".roo/rules/agentic-sdlc.md",
+              ".kilocode/rules/agentic-sdlc.md", ".windsurf/rules/agentic-sdlc.md",
+              ".continue/rules/agentic-sdlc.md"]
+    for rel in shared:
+        p = os.path.join(root, rel)
+        if not os.path.exists(p):
+            continue
+        text = open(p, errors="replace").read()
+        if BEGIN not in text:
+            continue
+        head, _, rest = text.partition(f"<!-- {BEGIN} -->")
+        _, _, tail = rest.partition(f"<!-- {END} -->")
+        new = (head.rstrip() + "\n" + tail.lstrip("\n")).strip()
+        removed.append(f"{rel} (our block)")
+        if not args.dry_run:
+            if new:
+                open(p, "w").write(new + "\n")
+            else:
+                os.remove(p)
+    hooks_dir = git("rev-parse", "--git-path", "hooks", cwd=root) or ".git/hooks"
+    if not os.path.isabs(hooks_dir):
+        hooks_dir = os.path.join(root, hooks_dir)
+    for name in ("pre-commit", "pre-push"):
+        p = os.path.join(hooks_dir, name)
+        if not os.path.exists(p):
+            continue
+        text = open(p, errors="replace").read()
+        if "# >>> agentic-sdlc >>>" not in text:
+            continue
+        head, _, rest = text.partition("# >>> agentic-sdlc >>>")
+        _, _, tail = rest.partition("# <<< agentic-sdlc <<<")
+        new = (head.rstrip() + "\n" + tail.lstrip("\n")).strip()
+        removed.append(f".git/hooks/{name} (our block)")
+        if not args.dry_run:
+            if new.replace("#!/bin/sh", "").strip():
+                open(p, "w").write(new + "\n")
+            else:
+                os.remove(p)
+    verb = "would remove" if args.dry_run else "removed"
+    for r in removed:
+        print(f"  {verb} {r}")
+    print(f"{verb} {len(removed)} item(s)")
+    return 0
+
+
+# ------------------------------------------------------------------- the hybrid retry loop
+
+def cmd_feedback(args) -> int:
+    """Carry a gate's failure back to the agent as context, instead of as a dead end.
+
+    A first-pass failure is the normal shape of agentic work; the productive pattern is
+    candidate -> deterministic gate -> failure routed back as enriched context -> retry. Without
+    somewhere to put that context, each retry starts as ignorant as the attempt before it.
+    """
+    root = repo_root()
+    p = os.path.join(root, FEEDBACK)
+    if args.feedback_action == "clear":
+        if os.path.exists(p):
+            os.remove(p)
+        print("feedback cleared")
+        return 0
+    if args.feedback_action == "read":
+        if not os.path.exists(p):
+            print("no feedback — this is the first attempt")
+            return 0
+        d = json.load(open(p))
+        print(f"# Attempt {d['attempts'] + 1}. Previous attempts failed as follows — read this "
+              f"before changing anything.\n")
+        for i, e in enumerate(d["entries"], 1):
+            print(f"## Attempt {i} — {e['stage']} ({e['at']})")
+            print(e["detail"].strip())
+            print()
+        return 0
+    # write
+    d = {"attempts": 0, "entries": []}
+    if os.path.exists(p):
+        try:
+            d = json.load(open(p))
+        except Exception:
+            pass
+    d["attempts"] = d.get("attempts", 0) + 1
+    d["entries"] = (d.get("entries") or [])[-4:] + [{
+        "stage": args.stage,
+        "at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "commit": head(root),
+        "detail": args.detail,
+    }]
+    os.makedirs(os.path.dirname(p), exist_ok=True)
+    with open(p, "w") as fh:
+        json.dump(d, fh, indent=2)
+    audit(root, "feedback", f"{args.stage}: attempt {d['attempts']}")
+    print(f"feedback recorded — attempt {d['attempts']} at stage {args.stage}")
+    ceiling = int(budget_config(load_config(root)).get("maxRetries") or 3)
+    if d["attempts"] >= ceiling:
+        print(f"{d['attempts']} attempts at the same stage, and budget.maxRetries is "
+              f"{ceiling}. Stop and report rather than trying another: the specification or "
+              f"the approach is probably the problem, not the code.")
+    return 0
+
+
+# ------------------------------------------------------------------- budget and checkpoints
+#
+# X5 and X7: an agent that cannot stop is a cost centre with a git token. X10: a long task that
+# crashes halfway must not leave a half-applied refactor nobody can reason about.
+#
+# The honest limit, stated once: this process cannot see the host's token meter. It counts what
+# it can observe — tool calls through the hook, wall-clock since the task began, and repair
+# attempts — and refuses when a ceiling is reached. A ceiling that stops the work is worth more
+# than a token count that only describes it afterwards.
+
+DEFAULT_BUDGET = {"maxToolCalls": 0, "maxWallClockMin": 0, "maxRetries": 3, "stopPolicy": "refuse"}
+
+
+def budget_config(cfg: dict) -> dict:
+    b = dict(DEFAULT_BUDGET)
+    b.update(cfg.get("budget") or {})
+    return b
+
+
+def budget_state(root: str) -> dict:
+    try:
+        return json.load(open(os.path.join(root, BUDGET)))
+    except Exception:
+        return {"toolCalls": 0, "startedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "task": branch(root)}
+
+
+def budget_save(root: str, st: dict) -> None:
+    try:
+        p = os.path.join(root, BUDGET)
+        os.makedirs(os.path.dirname(p), exist_ok=True)
+        with open(p, "w") as fh:
+            json.dump(st, fh, indent=2)
+    except Exception:
+        pass
+
+
+def budget_problem(root: str, cfg: dict) -> str | None:
+    """Why this task must stop now, or None. Counts one tool call as a side effect."""
+    b = budget_config(cfg)
+    if not (b.get("maxToolCalls") or b.get("maxWallClockMin")):
+        return None
+    st = budget_state(root)
+    if st.get("task") != branch(root):  # a new branch is a new task
+        st = {"toolCalls": 0, "startedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+              "task": branch(root)}
+    st["toolCalls"] = st.get("toolCalls", 0) + 1
+    budget_save(root, st)
+
+    warn_only = (b.get("stopPolicy") or "refuse") == "warn"
+    limit = int(b.get("maxToolCalls") or 0)
+    if limit and st["toolCalls"] > limit and warn_only:
+        if st["toolCalls"] == limit + 1:  # say it once, not on every call after
+            print(f"agentic-sdlc: this task has passed its budget of {limit} tool calls. "
+                  f"stopPolicy is 'warn', so nothing is being refused — but nothing is "
+                  f"stopping a runaway either.", file=sys.stderr)
+        return None
+    if limit and st["toolCalls"] > limit:
+        return (f"this task has made {st['toolCalls']} tool calls and the budget is {limit}.\n"
+                f"Stop and report what is done, what is left and what it would cost. "
+                f"A person raises the ceiling in sdlc.config.json; an agent does not raise "
+                f"its own.\nReset with:  sdlc budget reset")
+    mins = int(b.get("maxWallClockMin") or 0)
+    if mins and not warn_only:
+        try:
+            began = calendar.timegm(time.strptime(st["startedAt"], "%Y-%m-%dT%H:%M:%SZ"))
+            spent = (time.time() - began) / 60
+            if spent > mins:
+                return (f"this task has run for {int(spent)} minutes and the budget is {mins}.\n"
+                        f"Stop and report. Reset with:  sdlc budget reset")
+        except Exception:
+            pass
+    return None
+
+
+def cmd_budget(args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    b, st = budget_config(cfg), budget_state(root)
+    if args.budget_action == "reset":
+        if not args.as_person:
+            print("sdlc budget reset needs --as '<your name>'.\n"
+                  "A ceiling an agent can clear for itself is not a ceiling — it is a pause. "
+                  "The reset records who accepted the extra cost, for the same reason "
+                  "`sdlc approve` does, and an agent must not run it on a person's behalf.",
+                  file=sys.stderr)
+            return 3
+        budget_save(root, {"toolCalls": 0, "task": branch(root),
+                           "startedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())})
+        audit(root, "budget.reset", f"by {args.as_person}")
+        print(f"budget reset for this task by {args.as_person}")
+        return 0
+    spent_min = ""
+    try:
+        began = calendar.timegm(time.strptime(st["startedAt"], "%Y-%m-%dT%H:%M:%SZ"))
+        spent_min = f"{int((time.time() - began) / 60)} min"
+    except Exception:
+        pass
+    print(f"task        {st.get('task')}")
+    print(f"tool calls  {st.get('toolCalls', 0)}" +
+          (f" of {b['maxToolCalls']}" if b.get("maxToolCalls") else " (no ceiling set)"))
+    print(f"elapsed     {spent_min}" +
+          (f" of {b['maxWallClockMin']} min" if b.get("maxWallClockMin") else " (no ceiling set)"))
+    print(f"retries     ceiling {b.get('maxRetries')}")
+    if not (b.get("maxToolCalls") or b.get("maxWallClockMin")):
+        print("\nNo ceiling is set, so nothing will stop a runaway task. Set budget.maxToolCalls "
+              "or budget.maxWallClockMin in sdlc.config.json.")
+    return 0
+
+
+def cmd_checkpoint(args) -> int:
+    """A resumable record of a long task.
+
+    The hard part of resuming is not storing the plan; it is knowing whether the plan still
+    applies. So a checkpoint records the repository state it assumed, and resuming re-checks it
+    — the same discipline receipts use, for the same reason.
+    """
+    root = repo_root()
+    p = os.path.join(root, CHECKPOINT)
+
+    if args.checkpoint_action == "write":
+        c = {
+            "task": args.task or branch(root),
+            "at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "commit": head(root),
+            "branch": branch(root),
+            "treeClean": tree_clean(root),
+            "done": args.done or [],
+            "next": args.next_step or "",
+            "note": args.note or "",
+            "files": {},
+            "env": environment(root),
+        }
+        for rel in (args.file or []):
+            d = subject_digest(root, rel)
+            if d:
+                c["files"][rel] = d
+        os.makedirs(os.path.dirname(p), exist_ok=True)
+        with open(p, "w") as fh:
+            json.dump(c, fh, indent=2)
+            fh.write("\n")
+        audit(root, "checkpoint.write", f"{c['task']}: {args.next_step or ''}")
+        print(f"checkpoint at {c['commit'][:9]}: {len(c['done'])} step(s) done, "
+              f"next: {c['next'] or '(unstated)'}")
+        if not c["treeClean"]:
+            print("note: the tree was dirty when this was taken, so resuming cannot verify "
+                  "the uncommitted part. Commit before checkpointing if you can.")
+        return 0
+
+    if not os.path.exists(p):
+        print("no checkpoint — this is the first attempt at this task")
+        return 1
+    c = json.load(open(p))
+
+    if args.checkpoint_action == "show":
+        print(json.dumps(c, indent=2))
+        return 0
+
+    # resume: a checkpoint is not automatically safe to resume
+    problems = []
+    if c.get("branch") != branch(root):
+        problems.append(f"it was taken on branch {c.get('branch')}, you are on {branch(root)}")
+    if c.get("commit") != head(root):
+        behind = subprocess.run(["git", "merge-base", "--is-ancestor", c["commit"], "HEAD"],
+                                cwd=root, capture_output=True).returncode == 0
+        problems.append(f"HEAD has moved to {head(root)[:9]}" +
+                        ("" if behind else " and the checkpoint's commit is not behind it — "
+                                           "the history was rewritten"))
+    for rel, digest in (c.get("files") or {}).items():
+        now = subject_digest(root, rel)
+        if now is None:
+            problems.append(f"{rel} no longer exists")
+        elif now != digest:
+            problems.append(f"{rel} changed since the checkpoint")
+    env_now = environment(root)
+    drift = [k for k in env_now if k in c.get("env", {}) and env_now[k] != c["env"][k]]
+    if drift:
+        problems.append(f"the toolchain changed ({', '.join(drift)})")
+
+    print(f"# Resuming {c['task']} — checkpointed {c['at']} at {c['commit'][:9]}\n")
+    if c.get("done"):
+        print("Already done, do not repeat:")
+        for step in c["done"]:
+            print(f"  - {step}")
+    print(f"\nNext: {c.get('next') or '(unstated)'}")
+    if c.get("note"):
+        print(f"Note: {c['note']}")
+    if problems:
+        print("\nThe repository is NOT in the state this checkpoint assumed:")
+        for why in problems:
+            print(f"  - {why}")
+        print("\nRe-establish the facts before editing anything. A checkpoint is a record of "
+              "what was true, not a licence to carry on as if it still is.")
+        audit(root, "checkpoint.resume", f"stale: {len(problems)} mismatch(es)")
+        return 1
+    print("\nThe repository matches what this checkpoint assumed. Safe to continue.")
+    audit(root, "checkpoint.resume", "clean")
+    return 0
+
+
+# --------------------------------------------------------------------------- suite integrity
+#
+# The one failure this whole pipeline exists to prevent: making the gate pass by lowering it.
+# Every agent prompt forbids deleting a test, weakening an assertion, suppressing a warning or
+# excluding a path — and a prompt is a request. This is the check that does not negotiate.
+#
+# It reads the diff textually, so it is a heuristic and says so. It is deliberately tuned to
+# over-report: a false positive costs one sentence of explanation in the pull request, and a
+# false negative costs a silently disarmed test suite.
+
+TEST_PATH_RE = re.compile(
+    r"(^|/)(tests?|spec|specs|__tests__|testdata)/|[._-](test|spec)\.[a-z]+$|_test\.|"
+    r"(^|/)test_[^/]+\.py$", re.I)
+
+# A line that declares a test. Losing one is losing a check.
+TEST_DECL = re.compile(
+    r"\b(def\s+test_\w+|func\s+Test\w+|#\[test\]|#\[tokio::test\]|@Test\b|"
+    r"\b(it|test|describe|context)\s*\(|\bTEST(_F|_P)?\s*\()", re.I)
+
+# A line that asserts something. Losing one usually means the test now proves less.
+ASSERT_RE = re.compile(
+    r"\b(assert\w*|expect|should|require\.\w+|must\w*|verify|ok\(|t\.(Error|Fatal)\w*)\b",
+    re.I)
+
+# A marker that stops a test running, or runs only one. Added, these are how a suite goes quiet.
+SKIP_ADDED = (
+    (re.compile(r"\.(skip|only)\s*\(|\bx(it|describe|test)\s*\("), "a test is skipped or isolated"),
+    (re.compile(r"@pytest\.mark\.(skip|xfail)"), "a test is skipped or expected to fail"),
+    (re.compile(r"\bt\.Skip\w*\("), "a Go test skips itself"),
+    (re.compile(r"#\[ignore\]"), "a Rust test is ignored"),
+    (re.compile(r"@(Disabled|Ignore)\b"), "a JVM test is disabled"),
+    (re.compile(r"\breturn\s*;?\s*//\s*(TODO|FIXME|skip)", re.I), "a test returns early"),
+)
+
+# Silencing a tool rather than satisfying it.
+SUPPRESS_ADDED = (
+    (re.compile(r"eslint-disable(-next-line)?"), "an eslint rule is disabled"),
+    (re.compile(r"#\s*noqa|#\s*type:\s*ignore|#\s*pylint:\s*disable"), "a Python check is silenced"),
+    (re.compile(r"#\[allow\("), "a Rust lint is allowed"),
+    (re.compile(r"//\s*nolint|//lint:ignore"), "a Go linter is silenced"),
+    (re.compile(r"@SuppressWarnings|@ts-(ignore|expect-error|nocheck)"), "a type or compiler check is suppressed"),
+    (re.compile(r"\bcontinue-on-error:\s*true"), "a CI step is allowed to fail"),
+    (re.compile(r"\|\|\s*true\s*$"), "a command's failure is swallowed"),
+)
+
+NUM_SETTING = re.compile(r"([A-Za-z_][\w.\- ]{2,40})\s*[:=]\s*(\d{1,3})(?:\.\d+)?\s*%?\s*$")
+
+# Markdown is scanned like anything else. In a plugin whose executable instructions ARE
+# markdown, `|| true` appended to a command in commands/gate.md is a real weakening.
+#
+# There is no content-based exemption left in this function. Three were tried — quote parity,
+# quotes on both sides, and "a line starting with + or - is a diff illustration" — and each
+# was defeated by editing the line: an apostrophe, a trailing quote, and a two-character list
+# prefix. A file that contains these patterns as subject matter rather than as behaviour
+# declares itself in suiteAudit.exclude, where a reviewer sees it.
+
+
+def diff_files(root: str, base: str):
+    """(path, added, removed) per changed file, or None if git could not tell us.
+
+    Each file is diffed on its own, with explicit prefixes. Parsing one combined diff let a
+    line of *content* beginning `++ b/x.md` pose as a file header and reassign every line
+    after it, and a developer's long-standing `diff.noprefix` setting removed the prefix this
+    parser keyed on — silently disabling the whole check. Neither is reachable per-file.
+    """
+    def run(*args):
+        return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+
+    # -z: NUL-separated and never C-quoted. With git's default core.quotePath a non-ASCII
+    # name came back quoted, matched no pathspec, and produced an empty diff with returncode
+    # 0 — so gutting that file reported nothing. Failing OPEN, the mode B1d removed.
+    r = run("diff", "--name-only", "-z", f"{base}...HEAD")
+    if r.returncode != 0:
+        r = run("diff", "--name-only", "-z", base)
+    if r.returncode != 0:
+        return None  # fail closed; the caller reports unexecuted, never "nothing found"
+
+    out = []
+    for path in [x for x in r.stdout.split("\0") if x.strip()]:
+        d = run("diff", "--no-color", "--unified=0", "--src-prefix=a/", "--dst-prefix=b/",
+                f"{base}...HEAD", "--", path)
+        if d.returncode != 0:
+            d = run("diff", "--no-color", "--unified=0", "--src-prefix=a/", "--dst-prefix=b/",
+                    base, "--", path)
+        if d.returncode != 0:
+            return None
+        added, removed, in_body = [], [], False
+        for line in d.stdout.splitlines():
+            if line.startswith("@@"):
+                in_body = True
+            elif in_body and line.startswith("+"):
+                added.append(line[1:])
+            elif in_body and line.startswith("-"):
+                removed.append(line[1:])
+        if not d.stdout.strip():
+            return None  # named as changed but produced no diff; that is not "clean"
+        out.append((path, added, removed))
+    return out
+
+
+def audit_excluded(cfg: dict, path: str) -> bool:
+    """Is this path declared exempt from the suite audit?
+
+    Content-based exemption was tried twice and is not defensible. Counting quote parity let
+    one apostrophe disarm a line; requiring a quote on both sides let `# noqa  # "` do it.
+    Anything decided from the text of a line can be forged by writing different text, and the
+    actor writing it is the one the control exists to constrain.
+
+    So exemption is declared in sdlc.config.json instead: visible in the diff, reviewable, and
+    not reachable by editing the line under suspicion. A file that genuinely *defines* these
+    patterns — this plugin's own detector, its fixtures — says so once, out loud. Adding to
+    the list is itself reported as a weakening, so the escape hatch cannot be used quietly.
+    """
+    for pat in ((cfg.get("suiteAudit") or {}).get("exclude") or []):
+        if fnmatch.fnmatch(path, pat) or path == pat:
+            return True
+    return False
+
+
+def suite_findings(root: str, base: str, cfg: dict = None):
+    """Everything in this diff that makes the gate easier to pass, or None if git failed."""
+    cfg = cfg if cfg is not None else load_config(root)
+    found = []
+
+    r = subprocess.run(["git", "diff", "--name-only", "-z", "--diff-filter=D",
+                        f"{base}...HEAD"], cwd=root, capture_output=True, text=True)
+    if r.returncode != 0:
+        return None
+    for path in r.stdout.split("\0"):
+        if path and TEST_PATH_RE.search(path):
+            found.append((path, "a test file was deleted", path))
+
+    files = diff_files(root, base)
+    if files is None:
+        return None
+
+    # Widening the exemption list is itself a weakening — otherwise the escape hatch IS the
+    # bypass: add one glob and the check goes quiet everywhere. Compared as parsed lists at
+    # the two revisions rather than by pattern-matching the diff, so reformatting the config
+    # neither hides an addition nor invents one.
+    cfg_path = config_path(root)
+    if cfg_path:
+        name = os.path.relpath(cfg_path, root)
+        before, after = set(), set()
+        r = subprocess.run(["git", "show", f"{base}:{name}"], cwd=root,
+                           capture_output=True, text=True)
+        if r.returncode == 0:
+            try:
+                before = set(((json.loads(r.stdout).get("suiteAudit") or {}).get("exclude")) or [])
+            except Exception:
+                pass
+        try:
+            after = set(((load_config(root).get("suiteAudit") or {}).get("exclude")) or [])
+        except Exception:
+            after = set()
+        for added_glob in sorted(after - before):
+            found.append((name, "a path was newly exempted from the suite audit's "
+                                "suppression-marker checks",
+                          f'suiteAudit.exclude += "{added_glob}"'))
+
+    for path, added, removed in files:
+        if TEST_PATH_RE.search(path or ""):
+            lost = sum(1 for l in removed if TEST_DECL.search(l))
+            gained = sum(1 for l in added if TEST_DECL.search(l))
+            if lost > gained:
+                found.append((path, f"{lost - gained} test(s) removed and not replaced",
+                              next(l.strip() for l in removed if TEST_DECL.search(l))))
+            lost_a = sum(1 for l in removed if ASSERT_RE.search(l))
+            gained_a = sum(1 for l in added if ASSERT_RE.search(l))
+            # One removed assertion counts. The old threshold of two meant a reviewer could
+            # drop exactly one check per commit forever and never be reported.
+            if lost_a - gained_a >= 1:
+                n = lost_a - gained_a
+                found.append((path, f"{n} assertion(s) removed and not replaced — the test "
+                                    f"may now prove less",
+                              next(l.strip() for l in removed if ASSERT_RE.search(l))))
+
+        exempt = audit_excluded(cfg, path or "")
+        for line in added:
+            if not exempt:
+                for pat, why in SKIP_ADDED + SUPPRESS_ADDED:
+                    if pat.search(line):
+                        found.append((path, why, line.strip()))
+                        break
+
+
+        was = {}
+        for line in removed:
+            m = NUM_SETTING.search(line.strip())
+            if m:
+                was[m.group(1).strip().lower()] = int(m.group(2))
+        for line in added:
+            m = NUM_SETTING.search(line.strip())
+            if m:
+                key = m.group(1).strip().lower()
+                if key in was and int(m.group(2)) < was[key]:
+                    found.append((path, f"a threshold was lowered: {key} "
+                                        f"{was[key]} -> {m.group(2)}", line.strip()))
+    return found
+
+
+def cmd_tests(args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    base = args.base or merge_base(root, cfg)
+    found = suite_findings(root, base, cfg)
+
+    if found is None:
+        print(f"suite integrity: UNEXECUTED — git could not produce a diff against "
+              f"'{base}'. This is not a pass. A check that did not run is `unexecuted`; "
+              f"fix the ref and run it again.", file=sys.stderr)
+        audit(root, "suite.unexecuted", f"git diff failed against {base}")
+        return 1
+
+    if not found:
+        print(f"suite integrity: nothing in this diff weakens a check (against {base[:9]})")
+        return 0
+
+    print(f"suite integrity: {len(found)} thing(s) in this diff make the gate easier to pass\n")
+    for path, why, evidence in found:
+        print(f"  {path}")
+        print(f"    {why}")
+        print(f"    > {evidence[:150]}")
+    print("\nEach of these may be correct. None of them is correct *by default*, and none may")
+    print("pass without a sentence in the commit message saying why. Deleting a failing test,")
+    print("weakening an assertion, skipping a case or lowering a threshold to make the gate")
+    print("pass is the one failure this pipeline exists to prevent.")
+
+    if args.acknowledge:
+        if not args.as_person:
+            print("\n--acknowledge needs --as '<your name>'. An acknowledgement with nobody "
+                  "behind it records nothing, which is the whole reason it exists.",
+                  file=sys.stderr)
+            return 3
+        audit(root, "suite.acknowledged",
+              f"{len(found)} weakening(s) accepted by {args.as_person} against {base[:9]}")
+        print(f"\nAcknowledged by {args.as_person} — recorded, not waived. The reviewers still "
+              f"see every one of these, and so does `sdlc metrics`.")
+        return 0
+
+    print("\nIf a suppression is genuinely the right resolution, say so in the commit and")
+    print("re-run with --acknowledge --as '<your name>' to record who decided.")
+    audit(root, "suite.weakened", f"{len(found)} weakening change(s) against {base[:9]}")
+    return 1
+
+
+# ------------------------------------------------------------------- environment + baseline
+#
+# Two blind spots with one shape: the pipeline judged a change without knowing what the
+# repository looked like before it, and without knowing what produced the result. A test that
+# was already red gets blamed on the patch; a missing binary looks like a defect. Both are
+# answered by recording the starting state and comparing against it.
+
+_ENV_CACHE = None
+
+# Probed in this order; absent tools are simply not reported. Version flags differ, so each
+# names its own.
+VERSION_PROBES = (
+    ("git", ["git", "--version"]),
+    ("python", [sys.executable, "--version"]),
+    ("node", ["node", "--version"]),
+    ("npm", ["npm", "--version"]),
+    ("pnpm", ["pnpm", "--version"]),
+    ("yarn", ["yarn", "--version"]),
+    ("bun", ["bun", "--version"]),
+    ("cargo", ["cargo", "--version"]),
+    ("go", ["go", "version"]),
+    ("uv", ["uv", "--version"]),
+    ("java", ["java", "-version"]),
+)
+
+
+def environment(root: str = "") -> dict:
+    """Which toolchain produced this result. Probed once per process — these are subprocesses.
+
+    Without it, 'the tests failed' cannot be told apart from 'this machine cannot run them',
+    and an agent will spend its retries editing code to fix a missing binary.
+    """
+    global _ENV_CACHE
+    if _ENV_CACHE is not None:
+        return _ENV_CACHE
+    env = {"os": sys.platform, "arch": os.uname().machine if hasattr(os, "uname") else "?"}
+    for name, cmd in VERSION_PROBES:
+        if not which(cmd[0]) and cmd[0] != sys.executable:
+            continue
+        try:
+            r = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
+            out = (r.stdout or r.stderr or "").strip().splitlines()
+            if out:
+                env[name] = re.sub(r"^[a-z]+ version |^v", "", out[0].strip())[:40]
+        except Exception:
+            pass
+    _ENV_CACHE = env
+    return env
+
+
+# Lines worth comparing between two runs: the ones a runner uses to say something went wrong.
+SIGNAL_RE = re.compile(
+    r"(?:^|\s)(?:error|errors?\[|fail(?:ed|ure|ures)?|warning|warn|panic|assert(?:ion)?|"
+    r"exception|traceback|FAILED|FAIL|✗|✕|×)\b", re.I)
+
+# Everything here changes between two runs of the same unchanged code, so it must not count as
+# a difference. Over-scrubbing can hide a real change, which is why the full output is kept.
+NOISE = (
+    (re.compile(r"\b\d+(\.\d+)?\s*(ms|s|sec|secs|seconds|m|min|minutes)\b", re.I), "<time>"),
+    (re.compile(r"\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}\S*"), "<ts>"),
+    (re.compile(r"0x[0-9a-fA-F]{4,}"), "<addr>"),
+    (re.compile(r"/(?:tmp|var/folders|private/var)/\S+"), "<tmp>"),
+    (re.compile(r":\d+:\d+"), ":<pos>"),
+    (re.compile(r"\b[0-9a-f]{7,40}\b"), "<sha>"),
+    (re.compile(r"\s+"), " "),
+)
+
+
+def signals(output: str) -> list:
+    """The normalised failure and warning lines in a command's output.
+
+    A heuristic over text, deliberately: parsing would mean a parser per test runner, and only
+    sdlc.config.json is allowed to know the stack.
+    """
+    out = []
+    for line in output.splitlines():
+        line = line.strip()
+        if not line or not SIGNAL_RE.search(line):
+            continue
+        for pat, rep in NOISE:
+            line = pat.sub(rep, line)
+        line = line.strip()
+        if line and line not in out:
+            out.append(line[:300])
+    return out
+
+
+def merge_base(root: str, cfg: dict) -> str:
+    trunk = cfg.get("trunk") or "main"
+    return (git("merge-base", "HEAD", f"origin/{trunk}", cwd=root)
+            or git("merge-base", "HEAD", trunk, cwd=root)
+            or git("rev-list", "--max-parents=0", "HEAD", cwd=root))
+
+
+# A verify command is long by nature; a runaway one is the longest thing the pipeline runs,
+# and the ceiling meant to stop a runaway could not stop it.
+VERIFY_TIMEOUT_S = 1800
+
+
+def run_verify(root: str, cfg: dict):
+    """Run the project's verify command — through the same refusals as any other command.
+
+    `verifyCmd` comes from sdlc.config.json, which docs/rules.md section 7 classifies as data,
+    not authority. Running it with shell=True without consulting guard_problem opened a route
+    around every refusal in this file: a publish, a credential read or a deploy written into a
+    config string executed unchallenged, from a stage the branch-opener runs automatically.
+    The guard sees it first now, and it cannot run forever.
+    """
+    cmd = cfg.get("gateCmd") or cfg.get("verifyCmd")
+    if not cmd:
+        return None, None, None
+    problem = guard_problem(root, cmd, cfg)
+    if problem:
+        audit(root, "blocked", f"verifyCmd: {problem.splitlines()[0]} :: {cmd}")
+        return cmd, 126, (f"REFUSED before running: the configured command is not allowed.\n"
+                          f"{problem}\n\nThis came from sdlc.config.json, which is data, not "
+                          f"authority. A command in a config file is held to the same rules "
+                          f"as one an agent types.")
+    try:
+        r = subprocess.run(cmd, shell=True, cwd=root, capture_output=True, text=True,
+                           timeout=VERIFY_TIMEOUT_S)
+    except subprocess.TimeoutExpired as e:
+        out = e.stdout if isinstance(e.stdout, str) else (e.stdout or b"").decode(errors="replace")
+        return cmd, 124, (f"{out}\nTIMED OUT after {VERIFY_TIMEOUT_S}s. That is `unexecuted` "
+                          f"— not a failure of the change, and not a pass.")
+    return cmd, r.returncode, (r.stdout or "") + (r.stderr or "")
+
+
+def cmd_baseline(args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    p = os.path.join(root, BASELINE)
+
+    if args.baseline_action == "show":
+        if not os.path.exists(p):
+            print("no baseline — run `sdlc baseline capture` before starting work")
+            return 1
+        b = json.load(open(p))
+        print(f"captured {b['at']} at base {b['base'][:9]} on {b.get('branch')}")
+        print(f"  command   {b['cmd']}")
+        print(f"  exit      {b['exit']} ({'green' if b['exit'] == 0 else 'ALREADY FAILING'})")
+        print(f"  signals   {len(b['signals'])}")
+        for sig in b["signals"][:20]:
+            print(f"    {sig[:120]}")
+        return 0
+
+    if args.baseline_action == "capture":
+        cmd, code, out = run_verify(root, cfg)
+        if cmd is None:
+            print("no verifyCmd in the config — nothing to baseline. Without one nothing can "
+                  "be gated either; see `sdlc doctor`.", file=sys.stderr)
+            return 3
+        base = merge_base(root, cfg)
+        b = {
+            "base": base,
+            "branch": branch(root),
+            "at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "cmd": cmd,
+            "exit": code,
+            "signals": signals(out),
+            "output": out[-20000:],
+            "env": environment(root),
+        }
+        os.makedirs(os.path.dirname(p), exist_ok=True)
+        with open(p, "w") as fh:
+            json.dump(b, fh, indent=2)
+            fh.write("\n")
+        audit(root, "baseline.capture", f"exit {code}, {len(b['signals'])} signals at {base[:9]}")
+        print(f"baseline captured at {base[:9]}: exit {code}, {len(b['signals'])} signal(s)")
+        if code != 0:
+            print("This repository was NOT green when the work started. That is worth knowing "
+                  "now rather than discovering it as a 'regression' later.")
+        return 0
+
+    # compare
+    if not os.path.exists(p):
+        print("no baseline: this comparison is `unexecuted`, not passed. Capture one at the "
+              "branch point with `sdlc baseline capture`.", file=sys.stderr)
+        return 1
+    b = json.load(open(p))
+    cmd, code, out = run_verify(root, cfg)
+    if cmd is None:
+        print("no verifyCmd in the config", file=sys.stderr)
+        return 3
+    now = signals(out)
+    was = b["signals"]
+    new = [x for x in now if x not in was]
+    gone = [x for x in was if x not in now]
+    kept = [x for x in now if x in was]
+
+    # A baseline goes stale when its base is no longer behind us — a rebase, or a trunk that
+    # moved under the branch. It does NOT go stale merely because we committed: that is the
+    # whole difference between a baseline and a receipt.
+    still_behind = subprocess.run(["git", "merge-base", "--is-ancestor", b["base"], "HEAD"],
+                                  cwd=root, capture_output=True).returncode == 0
+    if not still_behind:
+        print(f"note: the baseline's base {b['base'][:9]} is no longer an ancestor of HEAD — "
+              f"the branch was rebased or the trunk moved. Recapture it.")
+    env_now = environment(root)
+    drift = [k for k in env_now if k in b.get("env", {}) and env_now[k] != b["env"][k]]
+    if drift:
+        print(f"note: the toolchain changed since the baseline ({', '.join(drift)}). A failure "
+              f"may belong to the environment rather than to the change.")
+
+    print(f"baseline {b['exit']} -> now {code}   "
+          f"{len(new)} new, {len(kept)} pre-existing, {len(gone)} fixed")
+    if new:
+        print("\nNEW since the baseline — these belong to this change:")
+        for x in new[:30]:
+            print(f"  {x[:160]}")
+    if kept:
+        print(f"\nPre-existing ({len(kept)}) — already there before the work started, "
+              f"not caused by it:")
+        for x in kept[:10]:
+            print(f"  {x[:160]}")
+    if gone:
+        print(f"\nFixed ({len(gone)}) — present at the baseline, gone now.")
+    audit(root, "baseline.compare", f"{len(new)} new, {len(kept)} pre-existing, {len(gone)} fixed")
+    if code in (124, 126):
+        print(f"\nVerdict: UNEXECUTED. The verify command did not run, so this says nothing "
+              f"about the change — in either direction.\n{out.strip()[:600]}")
+        audit(root, "baseline.unexecuted", f"verify exit {code}")
+        return 1
+
+    if new or (code != 0 and b["exit"] == 0):
+        print("\nVerdict: this change introduced failures. Fix those; leave the pre-existing "
+              "ones alone unless the specification asked for them.")
+        return 1
+    if code != 0:
+        print("\nVerdict: still failing, but with nothing new. The failures predate this work — "
+              "do not spend attempts on them, and do not report them as caused by the change.")
+        return 0
+    print("\nVerdict: nothing new.")
+    return 0
+
+
+# ---------------------------------------------------------------------------------- findings
+#
+# A finding is a claim about the code. Prose carries the argument; this carries the parts that
+# have to be compared, counted and audited: what rule, how bad, how sure, on what evidence, by
+# whom. Validation here mirrors schema/finding.schema.json — two expressions of one contract,
+# because bin/sdlc has no dependencies and cannot run a JSON Schema validator. A test feeds the
+# same values through both so they cannot drift.
+
+
+def control_spec_body() -> str:
+    """The control specification's text, or stop.
+
+    This used to swallow a read error and return nothing, which meant a missing or renamed
+    docs/control-spec.md silently emptied both the rule table and the never-autofix set: any
+    invented rule validated, and TEST-SUITE-WEAKENED came back autofixable. A control whose
+    off-switch is an absent file is not a control, so this fails closed and loudly.
+    """
+    try:
+        body = read_plugin("docs", "control-spec.md")
+    except Exception:
+        body = ""
+    # read_plugin returns "" on a read error rather than raising, so checking for the
+    # exception alone was dead code: a missing file produced an empty policy in silence.
+    if not body.strip() or "| Rule ID |" not in body:
+        e = "missing, empty, or has no rule table"
+        print(f"agentic-sdlc: cannot read docs/control-spec.md ({e}).\n"
+              f"It is the normative rule table: without it no rule can be validated and no "
+              f"rule can be known to be un-autofixable. Refusing rather than proceeding with "
+              f"an empty policy.", file=sys.stderr)
+        raise SystemExit(3)
+    return body
+
+
+def known_rules() -> set:
+    """Rule IDs from the control specification's table — the one source of truth.
+
+    Parsed rather than duplicated, so adding a row to docs/control-spec.md is all it takes to
+    make a rule usable. An unreadable table means we skip the check rather than block work.
+    """
+    body = control_spec_body()
+    return set(re.findall(r"^\|\s*`([A-Z][A-Z0-9-]*)`\s*\|", body, re.M))
+
+
+def finding_id(rule: str, file: str, line, summary: str) -> str:
+    """Stable identity, so the same finding raised twice is one finding and not two.
+
+    Deduplication is not cosmetic: a wall of repeated comments is how a review tool gets turned
+    off (the brief's X9).
+    """
+    key = f"{rule}|{file}|{line or ''}|{summary}".encode()
+    return "F-" + hashlib.sha256(key).hexdigest()[:8]
+
+
+def never_autofix_rules() -> set:
+    """Rules the control spec does not mark autofixable, whatever the severity pair says.
+
+    Parsed from the same table as the rule IDs. Without this the matrix alone decided, and a
+    TEST-SUITE-WEAKENED finding at critical/high came back "eligible for automatic fix" — an
+    agent authorised to repair a disarmed test suite unattended, which is the exact thing the
+    rule exists to stop.
+    """
+    body = control_spec_body()
+    out = set()
+    for rule, rest in re.findall(r"^\|\s*`([A-Z][A-Z0-9-]*)`\s*\|(.*)$", body, re.M):
+        cols = [c.strip() for c in rest.split("|")]
+        # columns: domain | detection | default severity | autofix | evidence
+        autofix = cols[3].lower() if len(cols) > 3 else ""
+        # Only an explicit "yes" defers to the severity x confidence matrix. Reading only
+        # **never** let the 53 rows that say plain "no" — SEC-INJECTION-SQL, SEC-AUTHORITY,
+        # MEM-SAFETY among them — come back autofixable at critical/high, which is the
+        # permissive half of a document that contradicted itself.
+        if not autofix.startswith("yes"):
+            out.add(rule)
+    return out
+
+
+def autofix_eligible(severity: str, confidence: str, has_repro: bool,
+                     rule: str = "") -> bool:
+    if rule and rule in never_autofix_rules():
+        return False
+    policy = AUTOFIX.get((severity, confidence), False)
+    if policy == "repro":
+        return bool(has_repro)
+    return bool(policy)
+
+
+def finding_problems(rec: dict) -> list:
+    """Why this record is not a valid finding. Empty list means it is."""
+    out = []
+    for field in ("id", "category", "ruleId", "summary", "evidence", "classification",
+                  "outcome", "provenance"):
+        if not rec.get(field):
+            out.append(f'missing required field "{field}"')
+    if out:
+        return out
+
+    if not re.fullmatch(r"F-[0-9a-f]{8}", rec["id"]):
+        out.append(f'id "{rec["id"]}" is not F- plus 8 hex digits')
+    if not re.fullmatch(r"([A-U]\.(?:[1-9][0-9]{0,2})|X(?:[1-9]|1[0-2]))", rec["category"]):
+        out.append(f'category "{rec["category"]}" is not a taxonomy address '
+                   f'(a domain letter and a check number, like D.31, or X1 to X12)')
+    if not re.fullmatch(r"[A-Z][A-Z0-9]*(-[A-Z0-9]+)*", rec["ruleId"]):
+        out.append(f'ruleId "{rec["ruleId"]}" is not an upper-case rule identifier')
+    else:
+        rules = known_rules()
+        if rules and rec["ruleId"] not in rules:
+            out.append(f'ruleId "{rec["ruleId"]}" is not in the rule table in '
+                       f'docs/control-spec.md — add the row before raising findings under it')
+    if not (8 <= len(rec["summary"]) <= 200):
+        out.append("summary must be between 8 and 200 characters: one sentence, the defect")
+    if rec["outcome"] not in FINDING_OUTCOMES:
+        out.append(f'outcome "{rec["outcome"]}" is not one of: {", ".join(FINDING_OUTCOMES)}')
+
+    ev = rec.get("evidence") or {}
+    if not ev.get("file"):
+        out.append("evidence.file is required — a finding with no location is an opinion")
+    if ev.get("line") is not None and not (isinstance(ev["line"], int) and ev["line"] >= 1):
+        out.append("evidence.line must be a positive integer")
+
+    cl = rec.get("classification") or {}
+    if cl.get("severity") not in SEVERITIES:
+        out.append(f'severity "{cl.get("severity")}" is not one of: {", ".join(SEVERITIES)}')
+    if cl.get("confidence") not in CONFIDENCES:
+        out.append(f'confidence "{cl.get("confidence")}" is not one of: {", ".join(CONFIDENCES)}')
+    if cl.get("exploitability") and cl["exploitability"] not in EXPLOITABILITY:
+        out.append(f'exploitability "{cl["exploitability"]}" is not one of: '
+                   f'{", ".join(EXPLOITABILITY)}')
+
+    pr = rec.get("provenance") or {}
+    if not pr.get("agent"):
+        out.append("provenance.agent is required — a finding with no author cannot be disputed")
+    if pr.get("detection") and pr["detection"] not in DETECTIONS:
+        out.append(f'detection "{pr["detection"]}" is not one of: {", ".join(DETECTIONS)}')
+    return out
+
+
+def finding_load_all(root: str) -> list:
+    d = os.path.join(root, FINDING_DIR)
+    if not os.path.isdir(d):
+        return []
+    out = []
+    for name in sorted(os.listdir(d)):
+        if name.endswith(".json"):
+            try:
+                out.append(json.load(open(os.path.join(d, name))))
+            except Exception:
+                pass
+    return out
+
+
+def cmd_finding(args) -> int:
+    root = repo_root()
+
+    if args.finding_action == "write":
+        severity, confidence = args.severity, args.confidence
+        rid = finding_id(args.rule, args.file, args.line, args.summary)
+        rec = {
+            "id": rid,
+            "category": args.category,
+            "ruleId": args.rule,
+            "component": args.component or "",
+            "summary": args.summary,
+            "evidence": {
+                "file": args.file,
+                "line": args.line,
+                "endLine": None,
+                "code": args.code or None,
+                "toolOutput": args.tool_output or None,
+                "repro": args.repro or None,
+            },
+            "classification": {
+                "severity": severity,
+                "confidence": confidence,
+                "exploitability": args.exploitability or "not-applicable",
+                "impact": args.impact or None,
+            },
+            "rootCause": args.root_cause or None,
+            "proposedRepair": None,
+            "verificationPlan": args.verification_plan or None,
+            "outcome": "open",
+            "closedBy": None,
+            "provenance": {
+                "agent": args.by,
+                "model": os.environ.get("CLAUDE_MODEL") or None,
+                "detection": args.detection,
+                "toolVersion": args.tool_version or None,
+                "at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "commit": head(root),
+            },
+        }
+        # The agent proposes the change; the policy table decides whether it may make it.
+        # Recorded even when no repair was proposed, so the remediator always has the
+        # machine-readable answer and never has to re-derive it from the prose.
+        rec["proposedRepair"] = {
+            "change": args.repair or "",
+            "expectedBehaviour": args.expected or "",
+            "sideEffects": args.side_effects or None,
+            "autofixEligible": autofix_eligible(severity, confidence,
+                                                bool(args.repro), args.rule),
+        }
+        problems = finding_problems(rec)
+        if problems:
+            for why in problems:
+                print(f"invalid finding: {why}", file=sys.stderr)
+            return 3
+        d = os.path.join(root, FINDING_DIR)
+        os.makedirs(d, exist_ok=True)
+        existing = os.path.join(d, rid + ".json")
+        if os.path.exists(existing):
+            # The same finding raised again is one finding — but if it was closed and has
+            # come back, it is NOT still closed. Re-opening it is the honest record: a defect
+            # re-detected after a bad fix was previously written straight back as `fixed`,
+            # and the gate reads `finding list --open`, so it vanished.
+            try:
+                prev = json.load(open(existing))
+                was = prev.get("outcome", "open")
+                if was in ("fixed", "refused", "deferred"):
+                    rec["outcome"] = "open"
+                    rec["closedBy"] = None
+                    rec["reopened"] = int(prev.get("reopened", 0)) + 1
+                    print(f"  REOPENED — this was closed as {was} at "
+                          f"{str(prev.get('closedBy'))[:9]} and has been detected again.")
+                else:
+                    rec["outcome"] = was
+                    rec["closedBy"] = prev.get("closedBy")
+                    if prev.get("reopened"):
+                        rec["reopened"] = prev["reopened"]
+            except Exception:
+                pass
+        with open(existing, "w") as fh:
+            json.dump(rec, fh, indent=2)
+            fh.write("\n")
+        audit(root, "finding.write", f"{rid} {args.rule} {severity}/{confidence} by {args.by}")
+        auto = rec["proposedRepair"]["autofixEligible"]
+        print(f"{rid}  {args.rule}  {severity}/{confidence}  {args.file}"
+              f"{':' + str(args.line) if args.line else ''}")
+        if args.repair:
+            print("  repair: " + ("eligible for automatic fix"
+                                  if auto else "NOT eligible — report or escalate"))
+        return 0
+
+    if args.finding_action == "list":
+        rows = finding_load_all(root)
+        total = len(rows)
+        if args.open_only:
+            rows = [r for r in rows if r.get("outcome") == "open"]
+        if args.severity:
+            rows = [r for r in rows
+                    if (r.get("classification") or {}).get("severity") == args.severity]
+        if args.json:
+            print(json.dumps(rows, indent=2))
+            return 0
+        if not rows:
+            print("no findings" + (" open" if args.open_only else ""))
+            return 0
+        order = {s: i for i, s in enumerate(SEVERITIES)}
+        rows.sort(key=lambda r: order.get((r.get("classification") or {}).get("severity"), 9))
+        for r in rows:
+            cl = r.get("classification") or {}
+            ev = r.get("evidence") or {}
+            loc = ev.get("file", "?") + (f":{ev['line']}" if ev.get("line") else "")
+            print(f"  {r['id']}  {cl.get('severity','?'):<8} {cl.get('confidence','?'):<6} "
+                  f"{r.get('outcome','?'):<10} {r.get('ruleId','?'):<26} {loc}")
+            print(f"            {r.get('summary','')}")
+        allrows = finding_load_all(root)
+        openn = sum(1 for r in allrows if r.get("outcome") == "open")
+        unex = sum(1 for r in allrows if r.get("outcome") == "unexecuted")
+        shown = f"showing {len(rows)} of {total}" if len(rows) != total else f"{total} finding(s)"
+        print(f"\n{shown}; {openn} open, {unex} unexecuted, of {total} raised.")
+        if unex:
+            print("An unexecuted finding is not closed — the fix was never verified.")
+        return 0
+
+    if args.finding_action == "show":
+        p = os.path.join(root, FINDING_DIR, args.id + ".json")
+        if not os.path.exists(p):
+            print(f"no finding {args.id}", file=sys.stderr)
+            return 1
+        print(open(p).read().rstrip())
+        return 0
+
+    # close
+    p = os.path.join(root, FINDING_DIR, args.id + ".json")
+    if not os.path.exists(p):
+        print(f"no finding {args.id}", file=sys.stderr)
+        return 1
+    if args.outcome not in FINDING_OUTCOMES or args.outcome == "open":
+        print(f'outcome must be one of: {", ".join(w for w in FINDING_OUTCOMES if w != "open")}',
+              file=sys.stderr)
+        return 3
+    rec = json.load(open(p))
+    raiser = (rec.get("provenance") or {}).get("agent", "")
+    if raiser and args.by and raiser != args.by:
+        # Not refused — a remediator legitimately closes a reviewer's finding — but recorded,
+        # because "who closed this" was previously nowhere and any actor could close any
+        # finding silently.
+        print(f"note: {raiser} raised this; {args.by} is closing it.")
+    rec["outcome"] = args.outcome
+    rec["closedBy"] = args.commit or head(root)
+    rec["closedByActor"] = args.by
+    if args.detail:
+        rec["verificationPlan"] = rec.get("verificationPlan") or args.detail
+    with open(p, "w") as fh:
+        json.dump(rec, fh, indent=2)
+        fh.write("\n")
+    audit(root, "finding.close",
+          f"{args.id} outcome={args.outcome} by {args.by}: {args.detail or ''}")
+    print(f"{args.id}: {args.outcome}")
+    if args.outcome == "unexecuted":
+        print("unexecuted is not closed — the fix was not verified. It stays on the gate's list.")
+    return 0
+
+
+# ------------------------------------------------------------------------------- governance
+
+def cmd_metrics(args) -> int:
+    """What the pipeline actually did — from the audit log, not from anyone's impression."""
+    root = repo_root()
+    p = os.path.join(root, AUDIT_LOG)
+    if not os.path.exists(p):
+        print("no audit log yet — it fills as stages run")
+        return 0
+    rows = []
+    for line in open(p, errors="replace"):
+        parts = line.rstrip("\n").split("\t")
+        if len(parts) >= 6:
+            rows.append(dict(zip(("at", "event", "commit", "branch", "agent", "detail"), parts)))
+    if args.since:
+        rows = [r for r in rows if r["at"][:10] >= args.since]
+    if not rows:
+        print("no events in that window")
+        return 0
+
+    stages, blocks, agents = {}, {}, {}
+    for r in rows:
+        if r["event"].startswith("receipt."):
+            kind = r["event"].split(".", 1)[1]
+            verdict = r["detail"].split(" by ")[0]
+            stages.setdefault(kind, {}).setdefault(verdict, 0)
+            stages[kind][verdict] += 1
+        elif r["event"] == "blocked":
+            blocks[r["detail"][:70]] = blocks.get(r["detail"][:70], 0) + 1
+        if r["agent"] != "-":
+            agents[r["agent"]] = agents.get(r["agent"], 0) + 1
+
+    print(f"{len(rows)} events from {rows[0]['at'][:10]} to {rows[-1]['at'][:10]}\n")
+    print("stage outcomes")
+    for kind in RECEIPT_KINDS:
+        if kind in stages:
+            total = sum(stages[kind].values())
+            detail = ", ".join(f"{v} {k}" for k, v in sorted(stages[kind].items()))
+            good = stages[kind].get("passed", 0) + stages[kind].get("approved", 0) + \
+                stages[kind].get("ready", 0) + stages[kind].get("granted", 0) + \
+                stages[kind].get("pass", 0)
+            print(f"  {kind:<13} {total:>4} runs   {detail}   first-pass {100 * good // max(total, 1)}%")
+    if blocks:
+        print("\nrefusals (what the pipeline stopped)")
+        for why, n in sorted(blocks.items(), key=lambda x: -x[1])[:10]:
+            print(f"  {n:>4}x  {why}")
+    if agents:
+        print("\nactors")
+        for a, n in sorted(agents.items(), key=lambda x: -x[1]):
+            print(f"  {a:<24} {n} events")
+    findings = finding_load_all(root)
+    if findings:
+        sev, cat, outcome = {}, {}, {}
+        for f in findings:
+            cl = f.get("classification") or {}
+            sev[cl.get("severity", "?")] = sev.get(cl.get("severity", "?"), 0) + 1
+            dom = str(f.get("category", "?")).split(".")[0]
+            cat[dom] = cat.get(dom, 0) + 1
+            outcome[f.get("outcome", "?")] = outcome.get(f.get("outcome", "?"), 0) + 1
+        print("\nfindings by severity")
+        for k in SEVERITIES:
+            if k in sev:
+                print(f"  {k:<10} {sev[k]}")
+        print("findings by taxonomy domain")
+        for k, v in sorted(cat.items(), key=lambda x: -x[1])[:12]:
+            print(f"  {k:<10} {v}")
+
+        # The outcome measures the brief asks for, computed only from what is recorded.
+        # Each is labelled with what it actually counts, because a metric whose definition is
+        # unstated is how a dashboard starts lying.
+        closed = sum(outcome.get(w, 0) for w in ("fixed", "refused", "deferred", "escalated"))
+        attempted = outcome.get("fixed", 0) + outcome.get("unexecuted", 0)
+        print("\noutcomes")
+        print(f"  verified repair rate   "
+              f"{100 * outcome.get('fixed', 0) // max(attempted, 1)}%  "
+              f"({outcome.get('fixed', 0)} fixed with proof / {attempted} repairs attempted)")
+        print(f"  human intervention     "
+              f"{100 * outcome.get('escalated', 0) // max(len(findings), 1)}%  "
+              f"({outcome.get('escalated', 0)} escalated / {len(findings)} findings)")
+        repro = sum(1 for f in findings if (f.get("evidence") or {}).get("repro"))
+        print(f"  reproducible           "
+              f"{100 * repro // max(len(findings), 1)}%  "
+              f"({repro} carry a reproduction)")
+        unex = outcome.get("unexecuted", 0)
+        if unex:
+            print(f"  UNVERIFIED             {unex} finding(s) closed as unexecuted — the fix "
+                  f"was never proved. These are not closed.")
+        if outcome.get("open"):
+            print(f"  still open             {outcome['open']}")
+
+        # A finding re-raised after being closed as fixed did not stay fixed.
+        fixed_then, refixed = set(), 0
+        for r in rows:
+            # Matched on the structured field, not on free text: the old `" fixed" in detail`
+            # counted a close whose note said "could not be fixed yet" as a fix.
+            if r["event"] == "finding.close" and "outcome=fixed" in r["detail"]:
+                fixed_then.add(r["detail"].split()[0])
+            elif r["event"] == "finding.write" and r["detail"].split()[0] in fixed_then:
+                refixed += 1
+        if fixed_then:
+            print(f"  false-fix rate         "
+                  f"{100 * refixed // max(len(fixed_then), 1)}%  "
+                  f"({refixed} of {len(fixed_then)} came back after being closed fixed)")
+
+    regress = [r for r in rows if r["event"] == "baseline.compare"]
+    if regress:
+        withnew = sum(1 for r in regress if not r["detail"].startswith("0 new"))
+        print(f"\nattribution ({len(regress)} comparisons)")
+        print(f"  changes that introduced a new failure  "
+              f"{100 * withnew // max(len(regress), 1)}%  ({withnew} of {len(regress)})")
+    weakened = [r for r in rows if r["event"] == "suite.weakened"]
+    if weakened:
+        print(f"  diffs that weakened a check            {len(weakened)}")
+
+    print("\nA low first-pass rate is not a problem by itself — it is the gate doing its job.\n"
+          "A first-pass rate of 100% means the gate is not checking anything.")
+    if findings:
+        print("Detection precision and recall are NOT here: they need a corpus of seeded\n"
+              "defects with known answers, which no repository has about itself. See\n"
+              "docs/maturity.md for how to measure them if you need to.")
+    return 0
+
+
+def cmd_trace(args) -> int:
+    """Requirement -> commit -> test -> pull request, for an auditor or a future maintainer."""
+    root = repo_root()
+    cfg = load_config(root)
+    trunk = cfg.get("trunk", "main")
+    base = git("merge-base", "HEAD", f"origin/{trunk}", cwd=root) or \
+        git("rev-list", "--max-parents=0", "HEAD", cwd=root)
+    commits = [l for l in git("log", "--format=%H|%s", f"{base}..HEAD", cwd=root).splitlines() if l]
+    files = [l for l in git("diff", "--name-only", f"{base}..HEAD", cwd=root).splitlines() if l]
+    tests = [f for f in files if re.search(r"(^|/)(tests?|spec)/|[._-](test|spec)\.[a-z]+$|_test\.", f)]
+
+    spec_subject = None
+    try:
+        spec_subject = json.load(open(receipt_path(root, "spec"))).get("subject")
+    except Exception:
+        pass
+
+    out = {
+        "branch": branch(root),
+        "head": head(root),
+        "base": base,
+        "specification": spec_subject,
+        "commits": [{"sha": c.split("|")[0][:9], "subject": c.split("|", 1)[1]} for c in commits],
+        "files_changed": files,
+        "tests_touched": tests,
+        "receipts": {},
+    }
+    for kind in RECEIPT_KINDS:
+        rp = receipt_path(root, kind)
+        if os.path.exists(rp):
+            try:
+                r = json.load(open(rp))
+                out["receipts"][kind] = {"verdict": r.get("verdict"), "commit": str(r.get("commit"))[:9],
+                                         "at": r.get("at"), "by": r.get("by")}
+            except Exception:
+                pass
+    pr = git("config", "--get", "branch.%s.pr" % branch(root), cwd=root)
+    if pr:
+        out["pull_request"] = pr
+
+    if args.json:
+        print(json.dumps(out, indent=2))
+        return 0
+    print(f"# Traceability — {out['branch']}\n")
+    print(f"Specification: {out['specification'] or '(none recorded — the spec receipt is missing)'}")
+    print(f"Base: {base[:9]}   Head: {out['head'][:9]}\n")
+    print(f"Commits ({len(commits)})")
+    for c in out["commits"]:
+        print(f"  {c['sha']}  {c['subject'][:90]}")
+    print(f"\nFiles changed: {len(files)}   Tests touched: {len(tests)}")
+    if files and not tests:
+        print("  ⚠ no test file in this change — the verifier should treat every criterion as unexecuted")
+    print("\nReceipts")
+    for kind, r in out["receipts"].items():
+        mark = "current" if r["commit"] == out["head"][:9] else f"stale (for {r['commit']})"
+        print(f"  {kind:<13} {r['verdict']:<18} {mark}")
+    missing = [k for k in ("spec", "verification", "review", "readiness") if k not in out["receipts"]]
+    if missing:
+        print(f"\nNo receipt for: {', '.join(missing)} — those stages did not run.")
+    return 0
+
+
+def cmd_approve(args) -> int:
+    """A person records that they approved something. Deliberately a human-run command.
+
+    The tool cannot prove a human typed it — nothing short of a signing key can — so it records
+    *who claims* the approval, in an append-only log, and makes an unapproved action impossible
+    rather than merely discouraged. That is the honest limit of this control.
+    """
+    root = repo_root()
+    if not args.as_person:
+        print("sdlc approve needs --as '<your name>' — an approval with no one behind it is "
+              "not an approval", file=sys.stderr)
+        return 3
+    detail = f"{args.what}: {args.detail}" if args.detail else args.what
+    rc = receipt_write(root, f"approval_{args.what}", "granted", args.subject or "", detail,
+                       args.as_person)
+    audit(root, "approval", f"{args.what} granted by {args.as_person}")
+    print(f"Recorded: {args.as_person} approved {args.what} at {head(root)[:9]}.\n"
+          f"It expires with the next commit, which is the point.")
+    return rc
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="sdlc", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("init", help="detect the stack and write sdlc.config.json")
+    p.add_argument("--write", action="store_true")
+    p.set_defaults(fn=cmd_init)
+
+    sub.add_parser("config", help="print the effective configuration").set_defaults(fn=cmd_config)
+    sub.add_parser("status", help="where this unit of work stands").set_defaults(fn=cmd_status)
+    g = sub.add_parser("guard", help="PreToolUse hook (stdin JSON; exit 2 blocks)")
+    g.add_argument("--command", help="evaluate one shell command instead of reading stdin "
+                                     "— this is how the git hooks call it")
+    g.set_defaults(fn=cmd_guard)
+    sub.add_parser("doctor", help="check the install, the config and the repo").set_defaults(fn=cmd_doctor)
+
+    i = sub.add_parser("install", help="install the pipeline for one or more platforms")
+    i.add_argument("targets", nargs="*", help="omit to install for every detected platform")
+    i.add_argument("--list", action="store_true", help="what is supported, and what each gets")
+    i.add_argument("--dry-run", action="store_true")
+    i.add_argument("--no-git-hooks", action="store_true",
+                   help="skip the universal git-hook layer (it is installed by default)")
+    i.set_defaults(fn=cmd_install)
+
+    u = sub.add_parser("uninstall", help="remove our blocks and the files we own")
+    u.add_argument("--dry-run", action="store_true")
+    u.set_defaults(fn=cmd_uninstall)
+
+    a = sub.add_parser("approve", help="a person records an approval (merge, release, exception)")
+    a.add_argument("what", choices=("merge", "release", "exception"))
+    a.add_argument("--as", dest="as_person", help="who is approving — required")
+    a.add_argument("--subject", default="")
+    a.add_argument("--detail", default="")
+    a.set_defaults(fn=cmd_approve)
+
+    f = sub.add_parser("feedback", help="carry a failure back to the next attempt as context")
+    fs = f.add_subparsers(dest="feedback_action", required=True)
+    fw = fs.add_parser("write")
+    fw.add_argument("--stage", required=True)
+    fw.add_argument("--detail", required=True)
+    fs.add_parser("read")
+    fs.add_parser("clear")
+    f.set_defaults(fn=cmd_feedback)
+
+    m = sub.add_parser("metrics", help="what the pipeline did, from the audit log")
+    m.add_argument("--since", help="YYYY-MM-DD")
+    m.set_defaults(fn=cmd_metrics)
+
+    t = sub.add_parser("trace", help="requirement to commit to test to pull request")
+    t.add_argument("--json", action="store_true")
+    t.set_defaults(fn=cmd_trace)
+
+    r = sub.add_parser("receipt", help="write, show or check a stage receipt")
+    rs = r.add_subparsers(dest="receipt_action", required=True)
+    for action in ("write", "show", "check"):
+        q = rs.add_parser(action)
+        q.add_argument("kind", choices=RECEIPT_KINDS)
+        q.add_argument("--verdict")
+        q.add_argument("--subject", default="")
+        q.add_argument("--detail", default="")
+        q.add_argument("--by", default=os.environ.get("CLAUDE_AGENT", "agent"))
+        q.add_argument("--max-age-min", type=int, default=0)
+        q.add_argument("--any-commit", action="store_true",
+                       help="do not require the receipt to name the current HEAD")
+    r.set_defaults(fn=cmd_receipt)
+
+    fd = sub.add_parser("finding", help="raise, list and close a structured finding")
+    fds = fd.add_subparsers(dest="finding_action", required=True)
+
+    fw = fds.add_parser("write", help="raise a finding (validated against the contract)")
+    fw.add_argument("--rule", required=True, help="a ruleId from docs/control-spec.md")
+    fw.add_argument("--category", required=True, help="taxonomy address, e.g. D.31 or X7")
+    fw.add_argument("--summary", required=True, help="one sentence: the defect")
+    fw.add_argument("--file", required=True)
+    fw.add_argument("--line", type=int)
+    fw.add_argument("--severity", required=True, choices=SEVERITIES)
+    fw.add_argument("--confidence", required=True, choices=CONFIDENCES)
+    fw.add_argument("--detection", default="llm", choices=DETECTIONS)
+    fw.add_argument("--exploitability", choices=EXPLOITABILITY)
+    fw.add_argument("--component", default="")
+    fw.add_argument("--code", default="", help="the relevant lines, quoted")
+    fw.add_argument("--tool-output", default="", help="the deterministic output behind the claim")
+    fw.add_argument("--repro", default="", help="the smallest reproduction, as commands")
+    fw.add_argument("--impact", default="")
+    fw.add_argument("--root-cause", default="", help="why it exists, not the symptom")
+    fw.add_argument("--repair", default="", help="the minimal proposed change")
+    fw.add_argument("--expected", default="", help="what is true after the repair")
+    fw.add_argument("--side-effects", default="")
+    fw.add_argument("--verification-plan", default="",
+                    help="the check that would establish the repair worked")
+    fw.add_argument("--tool-version", default="")
+    fw.add_argument("--by", default=os.environ.get("CLAUDE_AGENT", "agent"))
+
+    fl = fds.add_parser("list", help="what has been found")
+    fl.add_argument("--open", dest="open_only", action="store_true")
+    fl.add_argument("--severity", choices=SEVERITIES)
+    fl.add_argument("--json", action="store_true")
+
+    fsh = fds.add_parser("show")
+    fsh.add_argument("id")
+
+    fc = fds.add_parser("close", help="record what became of a finding")
+    fc.add_argument("id")
+    fc.add_argument("--outcome", required=True,
+                    choices=[w for w in FINDING_OUTCOMES if w != "open"])
+    fc.add_argument("--commit", default="")
+    fc.add_argument("--detail", default="")
+    fc.add_argument("--by", default=os.environ.get("CLAUDE_AGENT", "agent"),
+                    help="who is closing it; recorded on the finding and in the audit log")
+    fd.set_defaults(fn=cmd_finding)
+
+    bl = sub.add_parser("baseline", help="what was already broken before the work started")
+    bls = bl.add_subparsers(dest="baseline_action", required=True)
+    bls.add_parser("capture", help="record the verify result at the branch point")
+    bls.add_parser("compare", help="classify each failure as new, pre-existing or fixed")
+    bls.add_parser("show", help="what was captured, and when")
+    bl.set_defaults(fn=cmd_baseline)
+
+    ts = sub.add_parser("tests", help="has this diff made the gate easier to pass?")
+    tss = ts.add_subparsers(dest="tests_action", required=True)
+    ta = tss.add_parser("audit", help="deleted tests, weakened assertions, skips, suppressions")
+    ta.add_argument("--base", default="", help="compare against this ref instead of the merge base")
+    ta.add_argument("--acknowledge", action="store_true",
+                    help="record that a human decided each of these is correct")
+    ta.add_argument("--as", dest="as_person", default="",
+                    help="who is accepting them; required with --acknowledge")
+    ts.set_defaults(fn=cmd_tests)
+
+    bg = sub.add_parser("budget", help="what this task has spent, and its ceiling")
+    bgs = bg.add_subparsers(dest="budget_action", required=True)
+    bgs.add_parser("show")
+    bgr = bgs.add_parser("reset", help="a person clears the counter for this task")
+    bgr.add_argument("--as", dest="as_person", default="")
+    bg.set_defaults(fn=cmd_budget)
+
+    cp = sub.add_parser("checkpoint", help="resume a long task without assuming it is safe to")
+    cps = cp.add_subparsers(dest="checkpoint_action", required=True)
+    cw = cps.add_parser("write")
+    cw.add_argument("--task", default="")
+    cw.add_argument("--done", action="append", help="a step already finished; repeatable")
+    cw.add_argument("--next", dest="next_step", default="", help="the next step")
+    cw.add_argument("--note", default="")
+    cw.add_argument("--file", action="append", help="a file whose state this assumes; repeatable")
+    cps.add_parser("resume", help="re-check the assumptions before continuing")
+    cps.add_parser("show")
+    cp.set_defaults(fn=cmd_checkpoint)
+
+    args = ap.parse_args()
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())