signoff-cli 0.0.0-stage → 4.0.0

package/gates/p2_coverage.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""SignOff gate 2 - coverage has a level, not a vibe.
+
+Walks app directories, reads verify/scenarios/*.json, counts real assertions and
+assigns one of four levels (scenario / harness / smoke / missing). "There is a
+dev page" is not coverage; a scenario with N checks is.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path.cwd()
+OUT = ROOT / ".signoff"
+LEVELS = {"missing": 0, "smoke": 1, "harness": 2, "scenario": 3}
+
+
+def app_dirs() -> list[Path]:
+    found = []
+    if (ROOT / "package.json").exists() or (ROOT / "verify").is_dir():
+        found.append(ROOT)
+    for base in (ROOT, ROOT / "packages", ROOT / "apps"):
+        if not base.is_dir():
+            continue
+        for d in sorted(base.iterdir()):
+            if not d.is_dir() or d.name.startswith(".") or d.name in {"node_modules", "docs", "gates", "bin", "test"}:
+                continue
+            if (d / "package.json").exists() or (d / "verify").is_dir():
+                found.append(d)
+    return found
+
+
+def scenario_checks(path: Path) -> int:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return -1
+    checks = data.get("checks")
+    return len(checks) if isinstance(checks, list) else -1
+
+
+def inspect(app: Path) -> dict:
+    sdir = app / "verify" / "scenarios"
+    scenarios = []
+    if sdir.is_dir():
+        for f in sorted(sdir.glob("*.json")):
+            scenarios.append({"file": f.name, "checks": scenario_checks(f)})
+    broken = [s for s in scenarios if s["checks"] < 0]
+    if scenarios and not broken:
+        level = "scenario"
+    elif (app / "verify").is_dir():
+        level = "harness"
+    elif (app / "package.json").exists():
+        level = "smoke"
+    else:
+        level = "missing"
+    assertions = sum(s["checks"] for s in scenarios if s["checks"] > 0)
+    return {
+        "app": app.name,
+        "level": level,
+        "scenarios": scenarios,
+        "assertions": assertions,
+        "broken": [s["file"] for s in broken],
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="signoff p2")
+    ap.add_argument("--min-scenario", type=int, default=0, help="require at least N scenario-level apps")
+    ap.add_argument("--min-assertions", type=int, default=0)
+    ap.add_argument("--strict", action="store_true", help="fail on missing/harness/broken")
+    ap.add_argument("--md", metavar="FILE", help="write a markdown table")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args()
+
+    apps = app_dirs()
+    rows = [inspect(d) for d in apps]
+    scenario_apps = [r for r in rows if r["level"] == "scenario"]
+    assertions = sum(r["assertions"] for r in rows)
+    broken = [r for r in rows if r["broken"]]
+    ok = (
+        len(scenario_apps) >= a.min_scenario
+        and assertions >= a.min_assertions
+        and not broken
+        and (not a.strict or all(r["level"] == "scenario" for r in rows))
+    )
+
+    header = f"{'app':34} {'level':9} {'scenarios':22} assertions"
+    lines = [header, "-" * len(header)]
+    for r in rows:
+        names = ", ".join(f"{s['file'][:-5]}({s['checks']})" for s in r["scenarios"]) or "-"
+        lines.append(f"{r['app'][:33]:34} {r['level']:9} {names[:21]:22} {r['assertions']}")
+
+    if a.md:
+        md = ["| app | level | scenarios | assertions |", "| --- | --- | --- | --- |"]
+        for r in rows:
+            names = ", ".join(f"{s['file'][:-5]}({s['checks']})" for s in r["scenarios"]) or "-"
+            md.append(f"| {r['app']} | {r['level']} | {names} | {r['assertions']} |")
+        Path(a.md).write_text("\n".join(md) + "\n", encoding="utf-8")
+        lines.append(f"[p2] table written: {a.md}")
+
+    payload = {
+        "gate": "p2",
+        "ok": ok,
+        "apps": len(rows),
+        "scenarioApps": len(scenario_apps),
+        "assertions": assertions,
+        "broken": [{"app": b["app"], "files": b["broken"]} for b in broken],
+        "rows": rows,
+    }
+    OUT.mkdir(exist_ok=True)
+    (OUT / "p2.json").write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    if a.json:
+        print(json.dumps({k: payload[k] for k in ("gate", "ok", "apps", "scenarioApps", "assertions")}, ensure_ascii=False))
+    else:
+        print("\n".join(lines))
+        print(
+            f"[p2] {'PASS' if ok else 'FAIL'} apps={len(rows)} scenario={len(scenario_apps)} assertions={assertions} broken={len(broken)}"
+        )
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/gates/p3_queue.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""SignOff gate 3 - parallel work, no collisions.
+
+A task card says what a worker may touch, what proves it done and where the
+rollback point is. `plan` turns a pile of cards into waves: cards whose scopes
+overlap never share a wave. `collect` checks the diff back against the scopes and
+names both kinds of failure - a file nobody owns, and a card that shipped nothing.
+"""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path.cwd()
+OUT = ROOT / ".signoff"
+REQUIRED = ("id", "goal", "scope", "acceptance", "rollback")
+
+
+def load_cards(cards_dir: Path) -> list[dict]:
+    cards = []
+    for f in sorted(cards_dir.rglob("card.json")) if cards_dir.is_dir() else []:
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            cards.append({"id": str(f), "broken": f"unreadable: {exc}"})
+            continue
+        data["_file"] = str(f.relative_to(ROOT)) if f.is_relative_to(ROOT) else str(f)
+        cards.append(data)
+    return cards
+
+
+def validate(cards: list[dict]) -> list[str]:
+    problems: list[str] = []
+    seen: dict[str, str] = {}
+    for c in cards:
+        cid = c.get("id", "?")
+        if c.get("broken"):
+            problems.append(f"{cid}: {c['broken']}")
+            continue
+        for key in REQUIRED:
+            if not c.get(key):
+                problems.append(f"{cid}: missing '{key}'")
+        scope = c.get("scope")
+        if isinstance(scope, list):
+            for pat in scope:
+                if not isinstance(pat, str) or not pat.strip():
+                    problems.append(f"{cid}: bad scope entry {pat!r}")
+        elif "scope" in c:
+            problems.append(f"{cid}: scope must be a list")
+        if cid in seen:
+            problems.append(f"duplicate id {cid} ({seen[cid]} vs {c['_file']})")
+        seen[cid] = c.get("_file", "")
+    return problems
+
+
+def prefix(glob: str) -> str:
+    for i, ch in enumerate(glob):
+        if ch in "*?[":
+            return glob[:i].rstrip("/\\")
+    return glob.rstrip("/\\")
+
+
+def conflicts(a: dict, b: dict) -> bool:
+    for pa in a.get("scope") or []:
+        for pb in b.get("scope") or []:
+            if pa == pb:
+                return True
+            fa, fb = prefix(pa).replace("\\", "/"), prefix(pb).replace("\\", "/")
+            if not fa or not fb:
+                return True
+            if fa.startswith(fb) or fb.startswith(fa):
+                return True
+    return False
+
+
+def plan(cards: list[dict]) -> list[dict]:
+    waves: list[list[dict]] = []
+    for card in cards:
+        if card.get("broken"):
+            continue
+        placed = False
+        for wave in waves:
+            if not any(conflicts(card, other) for other in wave):
+                wave.append(card)
+                placed = True
+                break
+        if not placed:
+            waves.append([card])
+    return waves
+
+
+def card_owns(card: dict, path: str) -> bool:
+    path = path.replace("\\", "/")
+    for pat in card.get("scope") or []:
+        pat = pat.replace("\\", "/")
+        if fnmatch.fnmatch(path, pat) or path == prefix(pat):
+            return True
+        pre = prefix(pat)
+        if pre and path.startswith(pre.rstrip("/") + "/"):
+            return True
+    return False
+
+
+def git_changed() -> list[str]:
+    files: list[str] = []
+    for args in (["git", "diff", "--name-only", "HEAD"], ["git", "ls-files", "--others", "--exclude-standard"]):
+        try:
+            r = subprocess.run(args, capture_output=True, text=True, errors="replace")
+        except OSError:
+            continue
+        if r.returncode == 0:
+            files.extend([ln.strip() for ln in r.stdout.splitlines() if ln.strip()])
+    return sorted(set(files))
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="signoff p3")
+    ap.add_argument("cmd", choices=["validate", "plan", "collect"])
+    ap.add_argument("--cards", default="tasks")
+    ap.add_argument("--changed", nargs="*", default=None)
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args()
+
+    cards = load_cards(ROOT / a.cards)
+    problems = validate(cards)
+
+    if a.cmd == "validate":
+        ok = not problems
+        payload = {"gate": "p3", "cmd": "validate", "ok": ok, "cards": len(cards), "problems": problems}
+        OUT.mkdir(exist_ok=True)
+        (OUT / "p3.json").write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        if a.json:
+            print(json.dumps({k: payload[k] for k in ("gate", "cmd", "ok", "cards")}, ensure_ascii=False))
+        else:
+            for p in problems:
+                print(f"[p3] {p}")
+            print(f"[p3] {'PASS' if ok else 'FAIL'} cards={len(cards)} problems={len(problems)}")
+        return 0 if ok else 1
+
+    if a.cmd == "plan":
+        waves = plan(cards)
+        ok = not problems and bool(waves)
+        payload = {"gate": "p3", "cmd": "plan", "ok": ok, "waves": [[c.get("id") for c in w] for w in waves], "problems": problems}
+        OUT.mkdir(exist_ok=True)
+        (OUT / "p3.json").write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        if a.json:
+            print(json.dumps(payload, ensure_ascii=False))
+        else:
+            for i, wave in enumerate(waves, 1):
+                print(f"[p3] wave {i}: " + ", ".join(c.get("id", "?") for c in wave))
+            print(f"[p3] {'PASS' if ok else 'FAIL'} waves={len(waves)} cards={len(cards)}")
+        return 0 if ok else 1
+
+    changed = a.changed if a.changed is not None else git_changed()
+    owners = {f: [c.get("id") for c in cards if not c.get("broken") and card_owns(c, f)] for f in changed}
+    unowned = [f for f, ids in owners.items() if not ids]
+    missing = [c.get("id") for c in cards if not c.get("broken") and not any(card_owns(c, f) for f in changed)]
+    ok = not problems and not unowned
+    payload = {
+        "gate": "p3",
+        "cmd": "collect",
+        "ok": ok,
+        "changed": len(changed),
+        "unowned": unowned,
+        "cardsWithoutChange": missing,
+        "problems": problems,
+    }
+    OUT.mkdir(exist_ok=True)
+    (OUT / "p3.json").write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if a.json:
+        print(json.dumps({k: payload[k] for k in ("gate", "cmd", "ok", "changed")}, ensure_ascii=False))
+    else:
+        for f in unowned:
+            print(f"[p3] unowned change: {f}")
+        for cid in missing:
+            print(f"[p3] card shipped nothing: {cid}")
+        print(f"[p3] {'PASS' if ok else 'FAIL'} changed={len(changed)} unowned={len(unowned)} empty={len(missing)}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/gates/p4_ledger.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""SignOff gate 4 - risky actions leave a ledger.
+
+Three categories are gated: config, profile, publish. A ticket is minted first
+(`ask`), it is single-use and expires, and only then does `confirm` append a
+hash-chained entry carrying the rollback point. `verify` recomputes the chain and
+checks that every rollback point still exists - a free-text rollback is rejected.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import secrets
+import subprocess
+import time
+from pathlib import Path
+
+ACTIONS = ("config", "profile", "publish")
+BODY_KEYS_V1 = ("ts", "action", "target", "detail", "rollback", "decision")
+# 3.3.0 records also hash their repository; pre-3.3.0 records have no `repo` key and keep
+# verifying under the v1 tuple. Mirrors lib/p4.js so the two engines stay byte-compatible.
+BODY_KEYS_V2 = BODY_KEYS_V1 + ("repo",)
+
+
+def repo_root() -> Path | None:
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"], capture_output=True, text=True, errors="replace"
+        )
+    except OSError:
+        return None
+    if r.returncode != 0:
+        return None
+    return Path(r.stdout.strip())
+
+
+def repo_key() -> str:
+    root = repo_root()
+    if root is None:
+        return ""
+    out = str(root).replace("\\", "/").rstrip("/")
+    return out.lower() if os.name == "nt" else out
+
+
+def signoff_dir() -> Path:
+    override = os.environ.get("SIGNOFF_HOME")
+    if override:
+        return Path(override)
+    root = repo_root()
+    return (root / ".signoff") if root is not None else (Path.home() / ".signoff")
+
+
+def ledger_path() -> Path:
+    return signoff_dir() / "audit.log"
+
+
+def tickets_dir() -> Path:
+    return signoff_dir() / "tickets"
+
+
+def body_for(rec: dict) -> dict:
+    keys = BODY_KEYS_V2 if "repo" in rec else BODY_KEYS_V1
+    return {k: rec.get(k) for k in keys}
+
+
+def seed_ledger() -> None:
+    target = ledger_path()
+    if target.exists() or os.environ.get("SIGNOFF_HOME"):
+        return
+    legacy = Path.home() / ".signoff" / "audit.log"
+    if legacy.resolve() == target.resolve() or not legacy.exists():
+        return
+    lines = [line.strip() for line in legacy.read_text(encoding="utf-8").splitlines() if line.strip()]
+    if not lines:
+        return
+    for line in lines:
+        try:
+            rec = json.loads(line)
+        except ValueError:
+            return
+        rb = rec.get("rollback") or ""
+        if not rb or rb == "no-git":
+            continue
+        if " " in rb:
+            return
+        try:
+            r = subprocess.run(
+                ["git", "rev-parse", "--verify", "--quiet", rb], capture_output=True, text=True, errors="replace"
+            )
+        except OSError:
+            continue
+        if r.returncode != 0:
+            return
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("w", encoding="utf-8", newline="") as fh:
+        fh.write(os.linesep.join(lines) + os.linesep)
+
+
+def entries() -> list[dict]:
+    seed_ledger()
+    log = ledger_path()
+    if not log.exists():
+        return []
+    out = []
+    for line in log.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            out.append(json.loads(line))
+    return out
+
+
+def digest(prev: str, body: dict) -> str:
+    payload = json.dumps(body, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256((prev + payload).encode("utf-8")).hexdigest()
+
+
+def git_describe() -> str:
+    try:
+        r = subprocess.run(["git", "describe", "--tags", "--always"], capture_output=True, text=True, errors="replace")
+        return r.stdout.strip() if r.returncode == 0 else "no-git"
+    except OSError:
+        return "no-git"
+
+
+def ask(action: str, target: str, ttl: int) -> int:
+    tickets_dir().mkdir(parents=True, exist_ok=True)
+    token = secrets.token_hex(4)
+    (tickets_dir() / f"{token}.json").write_text(
+        json.dumps({"token": token, "action": action, "target": target, "expires": time.time() + ttl}, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    print(f"ticket {token}  action={action}  target={target}  ttl={ttl}s")
+    print(f'confirm with: signoff p4 confirm --ticket {token} --decision allow --detail "..."')
+    return 0
+
+
+def confirm(ticket: str, decision: str, detail: str, rollback: str) -> int:
+    path = tickets_dir() / f"{ticket}.json"
+    if not path.exists():
+        print(f"[p4] unknown or already used ticket {ticket}")
+        return 2
+    try:
+        meta = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        print(f"[p4] unreadable ticket {ticket}")
+        return 2
+    if meta.get("expires", 0) < time.time():
+        path.unlink(missing_ok=True)
+        print(f"[p4] ticket {ticket} expired")
+        return 2
+    path.unlink(missing_ok=True)
+
+    chain = entries()
+    prev = chain[-1]["hash"] if chain else "genesis"
+    body = {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "action": meta["action"],
+        "target": meta.get("target", ""),
+        "detail": detail,
+        "rollback": rollback,
+        "decision": decision,
+        "repo": repo_key(),
+    }
+    record = dict(body, prev=prev, hash=digest(prev, body))
+    ledger_path().parent.mkdir(parents=True, exist_ok=True)
+    with ledger_path().open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+    print(json.dumps({"ok": decision == "allow", "hash": record["hash"], "rollback": rollback}, ensure_ascii=False))
+    return 0 if decision == "allow" else 1
+
+
+def verify() -> int:
+    chain = entries()
+    current = repo_key()
+    problems: list[str] = []
+    prev = "genesis"
+    for i, rec in enumerate(chain, 1):
+        body = body_for(rec)
+        if rec.get("prev") != prev:
+            problems.append(f"line {i}: prev hash mismatch")
+        if rec.get("hash") != digest(prev, body):
+            problems.append(f"line {i}: content hash mismatch (edited after the fact)")
+        prev = rec.get("hash", "")
+        owner = rec.get("repo") or ""
+        if owner and current and owner != current:
+            continue
+        rb = rec.get("rollback") or ""
+        if not rb:
+            problems.append(f"line {i}: no rollback point recorded")
+        elif rb != "no-git":
+            if " " in rb:
+                problems.append(f"line {i}: rollback point '{rb}' is not a git ref")
+            else:
+                try:
+                    r = subprocess.run(["git", "rev-parse", "--verify", "--quiet", rb], capture_output=True, text=True, errors="replace")
+                except OSError:
+                    r = None
+                if r is not None and r.returncode != 0:
+                    problems.append(f"line {i}: rollback point '{rb}' no longer exists")
+    print(json.dumps({"ok": not problems, "entries": len(chain), "problems": problems}, ensure_ascii=False))
+    return 0 if not problems else 1
+
+
+def export(out: str) -> int:
+    chain = entries()
+    lines = ["# SignOff ledger", "", "| # | action | target | decision | rollback | hash |", "| --- | --- | --- | --- | --- | --- |"]
+    for i, r in enumerate(chain, 1):
+        lines.append(
+            f"| {i} | {r.get('action','')} | {r.get('target','')} | {r.get('decision','')} | {r.get('rollback','')} | {str(r.get('hash',''))[:12]} |"
+        )
+    Path(out).write_text("\n".join(lines) + "\n", encoding="utf-8")
+    print(f"[p4] {len(chain)} entries written to {out}")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="signoff p4")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    a = sub.add_parser("ask")
+    a.add_argument("--action", choices=ACTIONS, required=True)
+    a.add_argument("--target", default="")
+    a.add_argument("--ttl", type=int, default=600)
+
+    c = sub.add_parser("confirm")
+    c.add_argument("--ticket", required=True)
+    c.add_argument("--decision", choices=["allow", "deny"], default="allow")
+    c.add_argument("--detail", default="")
+    c.add_argument("--rollback", default=None)
+
+    sub.add_parser("verify")
+
+    e = sub.add_parser("export")
+    e.add_argument("--out", default="docs/signoff-ledger.md")
+
+    args = ap.parse_args()
+    if args.cmd == "ask":
+        return ask(args.action, args.target, args.ttl)
+    if args.cmd == "confirm":
+        return confirm(args.ticket, args.decision, args.detail, args.rollback or git_describe())
+    if args.cmd == "verify":
+        return verify()
+    return export(args.out)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/gates/p5_slop.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""SignOff gate 5 - empty words are a failure.
+
+Six rules over markdown. Code fences and table rows are skipped so a legitimate
+example cannot be reported as slop; the point is documents that claim progress
+without a number behind it.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path.cwd()
+OUT = ROOT / ".signoff"
+
+AI_WORDS = (
+    "赋能", "闭环", "抓手", "颗粒度", "底层逻辑", "组合拳", "全链路", "护城河",
+    "打通", "沉淀", "体系化", "复用", "生态位", "范式", "维度上", "协同增效",
+)
+ABSOLUTE = ("100%", "零缺陷", "永不", "绝对", "完美", "彻底", "极致", "无缝", "彻底解决")
+ADVERBS = ("极其", "非常", "十分", "相当", "大幅")
+CLAIMS = re.compile(r"(已验证|已覆盖|全部通过|全绿|都验证过)")
+PLACEHOLDER = re.compile(r"\b(TODO|TBD|FIXME)\b|待补|待定")
+
+
+def scan(text: str) -> list[tuple[str, int, str]]:
+    hits: list[tuple[str, int, str]] = []
+    in_fence = False
+    for n, raw in enumerate(text.splitlines(), 1):
+        line = raw.strip()
+        if line.startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence or line.startswith("|") or not line:
+            continue
+        # A document may legitimately quote a banned word: `赋能` in backticks is
+        # an example, not a claim.
+        line = re.sub(r"`[^`]*`", "", line).strip()
+        if not line:
+            continue
+        if PLACEHOLDER.search(line):
+            hits.append(("placeholder", n, "unfinished marker"))
+        for w in AI_WORDS:
+            if w in line:
+                hits.append(("ai-word", n, w))
+        for w in ABSOLUTE:
+            if w in line:
+                hits.append(("absolute-claim", n, w))
+        if CLAIMS.search(line) and not re.search(r"\d", line):
+            hits.append(("claim-without-number", n, "verification claim with no figure"))
+        adverbs = sum(line.count(w) for w in ADVERBS)
+        if adverbs >= 2:
+            hits.append(("empty-adverbs", n, f"{adverbs} intensifiers in one line"))
+    counts: dict[str, int] = {}
+    for kind, _, word in hits:
+        if kind in ("ai-word", "empty-adverbs"):
+            counts[word] = counts.get(word, 0) + 1
+    return hits
+
+
+def targets(args: list[str]) -> list[Path]:
+    if args:
+        out = []
+        for a in args:
+            p = Path(a)
+            if p.is_dir():
+                out.extend(sorted(p.rglob("*.md")))
+            elif p.exists():
+                out.append(p)
+        return out
+    found = [ROOT / "README.md", ROOT / "CHANGELOG.md"]
+    if (ROOT / "docs").is_dir():
+        found.extend(sorted((ROOT / "docs").rglob("*.md")))
+    return [p for p in found if p.exists()]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="signoff p5")
+    ap.add_argument("paths", nargs="*")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--allow", action="append", default=[], help="rule id to ignore")
+    a = ap.parse_args()
+
+    files = targets(a.paths)
+    report = []
+    for f in files:
+        hits = [h for h in scan(f.read_text(encoding="utf-8", errors="replace")) if h[0] not in a.allow]
+        rel = str(f.relative_to(ROOT)) if f.is_relative_to(ROOT) else str(f)
+        for kind, line, word in hits:
+            report.append({"file": rel, "line": line, "rule": kind, "hit": word})
+
+    ok = not report
+    payload = {"gate": "p5", "ok": ok, "files": len(files), "hits": report}
+    OUT.mkdir(exist_ok=True)
+    (OUT / "p5.json").write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if a.json:
+        print(json.dumps({"gate": "p5", "ok": ok, "files": len(files), "hits": len(report)}, ensure_ascii=False))
+    else:
+        for h in report:
+            print(f"[p5] {h['file']}:{h['line']}  {h['rule']}  {h['hit']}")
+        print(f"[p5] {'PASS' if ok else 'FAIL'} files={len(files)} hits={len(report)}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())