signoff-cli 0.0.0-stage → 4.0.1

package/docs/trust.md

@@ -0,0 +1,72 @@
+# 信任模型：这个提交当时真的过了？
+
+同类工具通常只给你一个"通过"，落印给你**一串可以互相校验的证据**。每一层都能单独被打假，
+合起来才构成"事后可核对"。
+
+## 四层证据
+
+| 层 | 内容 | 打假方式 |
+| --- | --- | --- |
+| 1. marker | `.signoff/passed` = `{tree, mode, ts}`，tree 是 `git write-tree` 的 40 位哈希 | 改动暂存内容后 tree 变，marker 失效 |
+| 2. trailer | 提交信息尾部 `Signoff-Pass: <tree12>` + `Signoff-Key` + `Signoff-Sig` | 签名覆盖完整 40 位 tree，改一个字就验不过 |
+| 3. 账本 | `.signoff/audit.log`，每条记录 `hash = sha256(prev + body)` | 改内容 → 本条 hash 对不上；改顺序 → prev 对不上 |
+| 4. 检查点 | `.signoff/checkpoint.json` = `{seq, head, root, key, sig}`，root 是记录哈希的 Merkle 根 | 删掉末尾记录 → seq 与 root 对不上 |
+
+第 4 层解决的是前三层的盲区：**删掉最后几条记录，链本身依然是自洽的**。
+检查点写死了"第 N 条之后的样子"，并在仓库外留一行锚点：
+
+```
+signoff1:12:9f2c1ab34d0e:71b0c9d2e4a85f61
+```
+
+## 三种篡改，三种答复
+
+| 攻击 | 结果 |
+| --- | --- |
+| 改提交信息里的 trailer | `audit --verify` 报 `bad-signature` |
+| 改账本某条记录的内容 | `p4 verify` 报 `content hash mismatch (edited after the fact)` |
+| 删掉账本末尾记录 | `p4 verify --checkpoint` 报 `records were removed` |
+| 换一把 key 重新签 | 只有 key 在 `.signoff/allowed_signers` 里才算 `verified`，否则是 `self-signed` |
+| 把锚点贴到别处对不上 | `p4 verify --checkpoint --anchor <那行>` 报锚点不匹配 |
+
+## 怎么用
+
+```bash
+# 每个仓库一次：写第一个检查点
+signoff p4 checkpoint
+
+# 之后每次 guard 通过都会自动续签（同一份账本不重复签）
+signoff guard
+
+# 把锚点发布出去：发版说明、CI 步骤摘要、同事的消息，任选其一
+signoff p4 anchor
+
+# 事后核对
+signoff p4 verify --checkpoint --anchor signoff1:12:9f2c1ab34d0e:71b0c9d2e4a85f61
+```
+
+CI 里：
+
+```yaml
+- run: signoff p4 checkpoint
+- run: echo "signoff1:$(...)" >> "$GITHUB_STEP_SUMMARY"
+```
+
+## 它不证明什么
+
+诚实地写明边界，比多给三个绿色对勾有用：
+
+- **不证明"是谁"**：默认是仓库内自签。要绑定身份，把公钥写进 `.signoff/allowed_signers`。
+- **不证明"活是真人干的"**：测试可以是假的，落印只证明"当时这套命令过了"。
+- **不防 key 泄露**：拿到私钥的人可以重新签；锚点只能让"重写历史"变得可见，不能阻止。
+- **同时重写账本与检查点并重新签名**，且没有发布过锚点——这种情况下本地无法察觉。
+  锚点一旦发布到仓库之外，这条路就断了。
+
+## 和同类的位置
+
+- gitleaks / Vale / diff-cover：只有单关结论，没有账本。
+- pre-commit / husky / lefthook：只负责"跑"，不负责"留下可核对的记录"。
+- in-toto：有规范化的 attestation 与供应链验证，但要求 layout、签名密钥与验证器一整套基础设施。
+- 落印：一条命令给出"提交 + 账本 + 检查点 + 可发布锚点"，代价是自签、格式私有。
+
+一句话：**in-toto 的严谨性它没有，in-toto 的部署成本它也没有。**

package/gates/guard.py

@@ -0,0 +1,474 @@
+#!/usr/bin/env python3
+"""SignOff auto-guard: install once, then the gates run themselves.
+
+`guard.py init` wires the five gates into git hooks and CI so that a normal
+`git commit` / `git push` / pull request cannot get past a red gate without
+leaving a trace. `guard.py hook <stage>` is what the hooks call.
+
+Design rules:
+  * stdlib only, no network;
+  * quiet on success (one line), full gate output only when something fails;
+  * a pass is cached per staged tree, so re-running the same commit is ~0 ms;
+  * fail closed: a missing CLI or a red gate blocks, and the only way past is
+    an explicit, recorded skip (SIGNOFF_SKIP=1) or `git commit --no-verify`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+GATES = Path(__file__).resolve().parent
+HOOK_MARK = "# generated by dsh-signoff"
+STATE = ".signoff"
+DEFAULT_CONFIG = {
+    "version": 2,
+    "docs": ["README.md", "docs"],
+    "test_cmd": None,
+    "budget": 180,
+    "tasks": "tasks",
+    "pre_push": True,
+    "ci": True,
+}
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def sh(args, cwd=None, timeout=None):
+    return subprocess.run(
+        args, cwd=None if cwd is None else str(cwd), capture_output=True, text=True, errors="replace", timeout=timeout
+    )
+
+
+def repo_root(cwd: Path | None = None) -> Path:
+    r = sh(["git", "rev-parse", "--show-toplevel"], cwd=cwd)
+    if r.returncode != 0:
+        raise SystemExit("signoff: not a git repository (run inside a repo)")
+    return Path(r.stdout.strip())
+
+
+def state_dir(root: Path) -> Path:
+    d = root / STATE
+    d.mkdir(exist_ok=True)
+    return d
+
+
+def load_config(root: Path) -> dict:
+    p = root / STATE / "config.json"
+    cfg = dict(DEFAULT_CONFIG)
+    if p.exists():
+        try:
+            cfg.update(json.loads(p.read_text(encoding="utf-8")))
+        except Exception:
+            pass
+    return cfg
+
+
+def save_config(root: Path, cfg: dict) -> None:
+    (root / STATE).mkdir(exist_ok=True)
+    (root / STATE / "config.json").write_text(
+        json.dumps(cfg, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def package_version() -> str:
+    try:
+        pkg = json.loads((GATES.parent / "package.json").read_text(encoding="utf-8"))
+        return str(pkg.get("version", "0"))
+    except Exception:
+        return "0"
+
+
+# ---------------------------------------------------------------- install
+
+
+def hook_body(stage: str) -> str:
+    return f"""#!/bin/sh
+{HOOK_MARK} {package_version()} -- remove with: signoff uninstall
+ROOT=$(git rev-parse --show-toplevel) || exit 1
+if command -v signoff >/dev/null 2>&1; then
+  exec signoff hook {stage}
+fi
+if [ -f "$ROOT/node_modules/dsh-signoff/bin/signoff.js" ]; then
+  exec node "$ROOT/node_modules/dsh-signoff/bin/signoff.js" hook {stage}
+fi
+echo "[signoff] CLI not found: npm i -g dsh-signoff (or add it as a devDependency)" >&2
+echo "[signoff] this repo is guarded; install the CLI, or bypass this once with --no-verify" >&2
+exit 1
+"""
+
+
+CI_BODY = """# generated by dsh-signoff -- remove with: signoff uninstall
+name: signoff
+on: [push, pull_request]
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: npx --yes dsh-signoff@latest guard --ci
+"""
+
+
+def write_exec(path: Path, text: str) -> None:
+    path.write_text(text, encoding="utf-8", newline="\n")
+    try:
+        os.chmod(path, 0o755)
+    except OSError:
+        pass
+
+
+def cmd_init(args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    if args.test_cmd:
+        cfg["test_cmd"] = args.test_cmd
+    if args.budget:
+        cfg["budget"] = args.budget
+    if args.docs:
+        cfg["docs"] = args.docs
+    cfg["pre_push"] = not args.no_push
+    cfg["ci"] = not args.no_ci
+    cfg["version"] = 2
+
+    hooks = root / ".git" / "hooks"
+    targets = [("pre-commit", "pre-commit")]
+    if cfg["pre_push"]:
+        targets.append(("pre-push", "pre-push"))
+
+    if args.dry_run:
+        for name, _ in targets:
+            print(f"would write {hooks / name}")
+        if cfg["ci"]:
+            print(f"would write {root / '.github/workflows/signoff.yml'}")
+        print(f"would write {root / STATE / 'config.json'}")
+        return 0
+
+    hooks.mkdir(parents=True, exist_ok=True)
+    notes = []
+    for name, stage in targets:
+        target = hooks / name
+        if target.exists() and HOOK_MARK not in target.read_text(encoding="utf-8", errors="replace"):
+            backup = hooks / f"{name}.signoff-backup"
+            if not backup.exists():
+                backup.write_text(target.read_text(encoding="utf-8", errors="replace"), encoding="utf-8")
+                notes.append(f"  saved old hook -> .git/hooks/{backup.name}")
+        write_exec(target, hook_body(stage))
+
+    if cfg["ci"]:
+        ci = root / ".github" / "workflows"
+        ci.mkdir(parents=True, exist_ok=True)
+        write_exec(ci / "signoff.yml", CI_BODY)
+
+    gi = root / ".gitignore"
+    line = f"{STATE}/"
+    if gi.exists():
+        txt = gi.read_text(encoding="utf-8", errors="replace")
+        if line not in txt.splitlines():
+            gi.write_text(txt.rstrip("\n") + "\n" + line + "\n", encoding="utf-8")
+    else:
+        gi.write_text(line + "\n", encoding="utf-8")
+
+    save_config(root, cfg)
+
+    print(f"signoff {package_version()} installed in {root.name}")
+    for n in notes:
+        print(n)
+    for name, _ in targets:
+        print(f"  hook      .git/hooks/{name}")
+    if cfg["ci"]:
+        print("  ci        .github/workflows/signoff.yml")
+    print(f"  config    {STATE}/config.json")
+    print(f"  test      {cfg['test_cmd'] or detect_test(root, cfg) or 'not detected (p1 will be skipped)'}")
+    print("  next      git commit as usual; a red gate stops the commit")
+    return 0
+
+
+# ---------------------------------------------------------------- run
+
+
+def detect_test(root: Path, cfg: dict) -> str | None:
+    if cfg.get("test_cmd"):
+        return str(cfg["test_cmd"])
+    pkg = root / "package.json"
+    if pkg.exists():
+        try:
+            scripts = json.loads(pkg.read_text(encoding="utf-8")).get("scripts", {})
+            test = scripts.get("test")
+            if test and "no test specified" not in test:
+                return "npm test --silent"
+        except Exception:
+            pass
+    has_py = (root / "tests").is_dir() or any(root.glob("test_*.py")) or any(root.glob("**/test_*.py"))
+    if has_py:
+        probe = sh([sys.executable, "-c", "import pytest"])
+        if probe.returncode == 0:
+            return f'"{sys.executable}" -m pytest -q'
+    return None
+
+
+def staged_files(root: Path) -> list[str]:
+    r = sh(["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd=root)
+    return [ln.strip() for ln in r.stdout.splitlines() if ln.strip()]
+
+
+def tree_key(root: Path) -> str:
+    r = sh(["git", "write-tree"], cwd=root)
+    base = r.stdout.strip() if r.returncode == 0 else ""
+    r2 = sh(["git", "diff", "--cached", "--name-only"], cwd=root)
+    return base + "|" + ",".join(sorted(r2.stdout.split()))
+
+
+def staged_docs(files: list[str], cfg: dict) -> list[str]:
+    docs = cfg.get("docs") or []
+    out = []
+    for f in files:
+        if not f.endswith((".md", ".mdx", ".txt")):
+            continue
+        for d in docs:
+            d = str(d).rstrip("/")
+            if f == d or f.startswith(d + "/"):
+                out.append(f)
+                break
+    return out
+
+
+def ledger_path() -> Path:
+    home = os.environ.get("SIGNOFF_HOME")
+    return (Path(home) / "audit.log") if home else (Path.home() / ".signoff" / "audit.log")
+
+
+def docs_files(root: Path, cfg: dict) -> list[str]:
+    out: list[str] = []
+    for d in cfg.get("docs") or []:
+        base = d.rstrip("/")
+        target = root / base
+        if target.is_file():
+            out.append(base)
+        elif target.is_dir():
+            out.extend(
+                str(p.relative_to(root)).replace("\\", "/") for p in sorted(target.rglob("*.md"))
+            )
+    return out
+
+
+def plan(root: Path, cfg: dict, files: list[str], full: bool) -> list[tuple[str, list[str]]]:
+    steps: list[tuple[str, list[str]]] = []
+    docs = staged_docs(files, cfg)
+    if docs:
+        steps.append(("p5", docs))
+    cmd = detect_test(root, cfg)
+    if cmd:
+        steps.append(("p1", ["--run", cmd, "--budget", str(cfg.get("budget", 180))]))
+    # P2 only joins when the repo actually has scenario fixtures; a repo without
+    # them is not "low coverage", it is simply not using this gate.
+    if (root / "verify" / "scenarios").is_dir() or cfg.get("apps"):
+        steps.append(("p2", ["--strict"]))
+    if ledger_path().exists():
+        steps.append(("p4", ["verify"]))
+    return steps
+
+
+GATE_FILES = {
+    "p1": "p1_verify.py",
+    "p2": "p2_coverage.py",
+    "p3": "p3_queue.py",
+    "p4": "p4_ledger.py",
+    "p5": "p5_slop.py",
+}
+
+
+def run_gate(name: str, args: list[str], root: Path, timeout: float) -> tuple[int, float, str]:
+    t0 = time.time()
+    try:
+        r = sh([sys.executable, str(GATES / GATE_FILES[name]), *args], cwd=root, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        return 1, time.time() - t0, f"{name}: timed out after {timeout:.0f}s"
+    return r.returncode, time.time() - t0, (r.stdout or "") + (r.stderr or "")
+
+
+def cmd_guard(args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    files = staged_files(root)
+    full = args.full or args.ci
+
+    if not files and not full:
+        print("signoff guard: nothing staged")
+        return 0
+
+    key = tree_key(root)
+    cache = root / STATE / "cache.json"
+    if not full and cache.exists():
+        try:
+            c = json.loads(cache.read_text(encoding="utf-8"))
+            if c.get("key") == key and c.get("ok"):
+                print(f"signoff guard: cached pass ({c.get('seconds', 0):.2f}s)")
+                return 0
+        except Exception:
+            pass
+
+    if os.environ.get("SIGNOFF_SKIP") == "1":
+        sd = state_dir(root)
+        (sd / "skips.log").open("a", encoding="utf-8").write(f"{now()} skipped {len(files)} file(s) via SIGNOFF_SKIP=1\n")
+        print("signoff guard: SKIPPED (SIGNOFF_SKIP=1, recorded in .signoff/skips.log)")
+        return 0
+
+    steps = plan(root, cfg, files, full)
+    if args.ci:
+        # CI has no index: check every configured doc, not just the staged ones.
+        all_docs = docs_files(root, cfg)
+        if all_docs:
+            steps = [("p5", all_docs)] + [s for s in steps if s[0] != "p5"]
+    if not steps:
+        print("signoff guard: no gate applies to this change")
+        return 0
+
+    budget = float(cfg.get("budget", 180))
+    print(f"signoff guard: {len(files)} file(s) staged, {len(steps)} gate(s)")
+    t0 = time.time()
+    failed: list[tuple[str, str]] = []
+    for name, gargs in steps:
+        rc, secs, out = run_gate(name, gargs, root, max(budget, 60))
+        print(f"  {name:<4} {'ok  ' if rc == 0 else 'FAIL'} {secs:6.2f}s")
+        if rc != 0:
+            failed.append((name, out))
+    total = time.time() - t0
+
+    if failed:
+        sd = state_dir(root)
+        (sd / "hook.log").write_text("\n\n".join(f"== {n} ==\n{o}" for n, o in failed), encoding="utf-8")
+        print(f"signoff guard: FAIL ({total:.2f}s)")
+        for n, out in failed:
+            tail = [ln for ln in out.strip().splitlines() if ln.strip()][-8:]
+            print(f"-- {n} --")
+            for ln in tail:
+                print(f"  {ln}")
+        print(f"  full output: {STATE}/hook.log")
+        print("  bypass once: SIGNOFF_SKIP=1 git commit ... (recorded) or git commit --no-verify")
+        return 1
+
+    save = root / STATE / "cache.json"
+    save.write_text(json.dumps({"key": key, "ok": True, "ts": now(), "seconds": round(total, 3)}) + "\n", encoding="utf-8")
+    print(f"signoff guard: PASS ({total:.2f}s)")
+    return 0
+
+
+# ---------------------------------------------------------------- status
+
+
+def installed(root: Path) -> dict:
+    hooks = root / ".git" / "hooks"
+    out = {}
+    for name in ("pre-commit", "pre-push"):
+        p = hooks / name
+        out[name] = bool(p.exists() and HOOK_MARK in p.read_text(encoding="utf-8", errors="replace"))
+    ci = root / ".github" / "workflows" / "signoff.yml"
+    out["ci"] = bool(ci.exists() and HOOK_MARK in ci.read_text(encoding="utf-8", errors="replace"))
+    out["config"] = (root / STATE / "config.json").exists()
+    c = root / STATE / "cache.json"
+    if c.exists():
+        try:
+            d = json.loads(c.read_text(encoding="utf-8"))
+            out["last_run"] = {"ok": d.get("ok"), "ts": d.get("ts"), "seconds": d.get("seconds")}
+        except Exception:
+            pass
+    return out
+
+
+def cmd_status(args) -> int:
+    root = repo_root()
+    cfg = load_config(root)
+    st = installed(root)
+    if args.json:
+        print(json.dumps({"root": str(root), "version": package_version(), "installed": st, "config": cfg}, ensure_ascii=False))
+        return 0
+    print(f"repo        {root}")
+    print(f"version     {package_version()}")
+    for k in ("pre-commit", "pre-push", "ci"):
+        print(f"{k:<12}{'installed' if st[k] else 'missing'}")
+    print(f"{'config':<12}{'present' if st['config'] else 'missing'}")
+    print(f"{'test':<12}{detect_test(root, cfg) or 'not detected'}")
+    lr = st.get("last_run")
+    print(f"{'last run':<12}{lr['ts'] + (' PASS' if lr['ok'] else ' FAIL') if lr else 'never'}")
+    return 0
+
+
+def cmd_uninstall(args) -> int:
+    root = repo_root()
+    removed = []
+    for name in ("pre-commit", "pre-push"):
+        p = root / ".git" / "hooks" / name
+        if p.exists() and HOOK_MARK in p.read_text(encoding="utf-8", errors="replace"):
+            p.unlink()
+            removed.append(f".git/hooks/{name}")
+    ci = root / ".github" / "workflows" / "signoff.yml"
+    if ci.exists() and HOOK_MARK in ci.read_text(encoding="utf-8", errors="replace"):
+        ci.unlink()
+        removed.append(".github/workflows/signoff.yml")
+    if args.all:
+        p = root / STATE / "config.json"
+        if p.exists():
+            p.unlink()
+            removed.append(f"{STATE}/config.json")
+    print("removed: " + (", ".join(removed) if removed else "nothing"))
+    return 0
+
+
+def cmd_hook(args) -> int:
+    return cmd_guard(argparse.Namespace(full=args.stage == "pre-push", ci=False))
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="signoff guard", description="install and run the automatic gates")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    i = sub.add_parser("init", help="install git hooks + CI workflow")
+    i.add_argument("--test-cmd", default=None)
+    i.add_argument("--budget", type=float, default=None)
+    i.add_argument("--docs", nargs="*", default=None)
+    i.add_argument("--no-ci", action="store_true")
+    i.add_argument("--no-push", action="store_true")
+    i.add_argument("--dry-run", action="store_true")
+
+    g = sub.add_parser("guard", help="run the gates now (what the hooks call)")
+    g.add_argument("--full", action="store_true")
+    g.add_argument("--ci", action="store_true")
+    g.add_argument("--json", action="store_true")
+
+    h = sub.add_parser("hook", help="internal: called by git hooks")
+    h.add_argument("stage", choices=["pre-commit", "pre-push"])
+
+    s = sub.add_parser("status", help="show whether this repo is guarded")
+    s.add_argument("--json", action="store_true")
+
+    u = sub.add_parser("uninstall", help="remove hooks and CI workflow")
+    u.add_argument("--all", action="store_true", help="also remove .signoff/config.json")
+
+    args = ap.parse_args(argv)
+    if args.cmd == "init":
+        return cmd_init(args)
+    if args.cmd == "guard":
+        return cmd_guard(args)
+    if args.cmd == "hook":
+        return cmd_hook(args)
+    if args.cmd == "status":
+        return cmd_status(args)
+    if args.cmd == "uninstall":
+        return cmd_uninstall(args)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/gates/p1_verify.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""SignOff gate 1 - verify before you speak.
+
+Runs the project's own checks, times them, parses the case count and writes
+.signoff/p1.json. Exit code is the verdict: 0 only when every command passed
+inside the time budget. Output is ASCII on purpose: a GBK console must not be
+able to turn a real PASS into mojibake.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path.cwd()
+OUT = ROOT / ".signoff"
+
+
+def default_commands() -> list[str]:
+    if (ROOT / "tests").is_dir():
+        return [f'"{sys.executable}" -m pytest tests -q']
+    if (ROOT / "package.json").exists():
+        return ["npm test --silent"]
+    return []
+
+
+def count_cases(text: str) -> int | None:
+    for pat in (r"(\d+)\s+passed", r"(\d+)\s+tests?\b", r"(\d+)\s+checks?\b", r"(\d+)\s+assertions?\b"):
+        hits = re.findall(pat, text)
+        if hits:
+            return max(int(h) for h in hits)
+    return None
+
+
+def install_hook() -> int:
+    hooks = ROOT / ".git" / "hooks"
+    if not hooks.is_dir():
+        print("[p1] not a git repository (no .git/hooks)")
+        return 2
+    hook = hooks / "pre-commit"
+    hook.write_text("#!/bin/sh\n# installed by SignOff / dsh-signoff\nexec signoff p1\n", encoding="utf-8")
+    try:
+        hook.chmod(0o755)
+    except OSError:
+        pass
+    print(f"[p1] hook installed: {hook}")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="signoff p1")
+    ap.add_argument("--run", action="append", default=[], help="command to run (repeatable)")
+    ap.add_argument("--budget", type=float, default=180.0, help="seconds for all commands together")
+    ap.add_argument("--install-hook", action="store_true")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--quiet", action="store_true")
+    a = ap.parse_args()
+
+    if a.install_hook:
+        return install_hook()
+
+    cmds = a.run or default_commands()
+    if not cmds:
+        print("[p1] nothing to run: no tests/ and no package.json")
+        return 2
+
+    started = time.perf_counter()
+    results = []
+    for cmd in cmds:
+        t0 = time.perf_counter()
+        proc = subprocess.run(cmd, shell=True, capture_output=True, text=True, errors="replace")
+        ms = round((time.perf_counter() - t0) * 1000)
+        out = (proc.stdout or "") + (proc.stderr or "")
+        results.append(
+            {
+                "cmd": cmd,
+                "rc": proc.returncode,
+                "ms": ms,
+                "cases": count_cases(out),
+                "tail": out.strip().splitlines()[-3:],
+            }
+        )
+        if not a.quiet:
+            print(f"[p1] rc={proc.returncode} {ms} ms  {cmd}")
+
+    elapsed = round((time.perf_counter() - started) * 1000)
+    ok = all(r["rc"] == 0 for r in results) and elapsed <= a.budget * 1000
+    total_cases = sum(r["cases"] or 0 for r in results)
+    payload = {
+        "gate": "p1",
+        "ok": ok,
+        "elapsedMs": elapsed,
+        "budgetMs": int(a.budget * 1000),
+        "cases": total_cases,
+        "results": results,
+    }
+    OUT.mkdir(exist_ok=True)
+    (OUT / "p1.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", "elapsedMs", "budgetMs", "cases")}, ensure_ascii=False))
+    else:
+        print(f"[p1] {'PASS' if ok else 'FAIL'} {elapsed} ms (budget {int(a.budget * 1000)} ms), cases={total_cases}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())