|
| 1 | +# regress-guard |
| 2 | + |
| 3 | +> AI-coding governance gate for ZCode: **don't trust the agent's "done"** — the gate |
| 4 | +> re-runs your tests itself, blocks edits outside the declared change-scope, and |
| 5 | +> keeps human-only-calibrated telemetry on every interception. |
| 6 | +> |
| 7 | +> Design philosophy first: [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) (sixteen |
| 8 | +> principles and the real incidents behind them). Features age, principles don't. |
| 9 | +> Full workflow: [docs/WORKFLOW.md](docs/WORKFLOW.md) · 中文文档：[README_CN.md](README_CN.md) |
| 10 | +
|
| 11 | +## Why |
| 12 | + |
| 13 | +Agents report "done" confidently and cheaply. This plugin makes "done" a |
| 14 | +machine-verified claim, at the only surface that matters in a direct-to-main |
| 15 | +workflow: **the commit**. |
| 16 | + |
| 17 | +- **Completion re-verification (the core)**: a PreToolUse gate intercepts commit |
| 18 | + commands and runs the project's own test suite itself — agent self-reports are |
| 19 | + never trusted. EARS-style acceptance rows must be checked off with evidence |
| 20 | + before `done` is stamped. Same-tree retries hit a content-keyed result cache |
| 21 | + (0-second gates). |
| 22 | +- **Boundary guard**: edits/writes to files not declared in the active change |
| 23 | + manifest are blocked before they happen — the plan's file list *is* the boundary. |
| 24 | +- **Assumption ledger**: when reality falsifies a plan's assumption, the |
| 25 | + was→reality→evidence record is mandatory. |
| 26 | +- **Six-layer trust surface**: project-level notification channels require a |
| 27 | + human-granted trust table + content pinning; HOME/env-injection redirection is |
| 28 | + neutralized at the launcher allowlist. Cloned-repo injection surfaces are closed. |
| 29 | +- **FP-calibrated telemetry**: every interception is adjudicated later by the |
| 30 | + human (useful / false_positive / ignored) — the agent gets no vote on its own |
| 31 | + accuracy. Public benchmark: 82 cases / 13 families, see [benchmarks/](benchmarks/). |
| 32 | +- **Self-healing**: session start compares the installed copy against the source |
| 33 | + repo; version drift is announced, not silently tolerated. |
| 34 | + |
| 35 | +## Install |
| 36 | + |
| 37 | +**Marketplace (recommended)**: install `regress-guard` from the ZCode plugin |
| 38 | +marketplace — hooks activate via the host runtime, and the plugin can be |
| 39 | +toggled/upgraded natively. |
| 40 | + |
| 41 | +**Personal-source track**: add marketplace source |
| 42 | +`github:1339190177/regress-guard` in ZCode settings, then install. |
| 43 | + |
| 44 | +**Dev track**: clone this repo, then `bash install.sh` (or tell the AI |
| 45 | +`/regress:install`). Use one track at a time. |
| 46 | + |
| 47 | +Requirements: ZCode client + Python 3.10+. Runtime has **zero third-party |
| 48 | +Python dependencies** (`filelock` is optional — absent → degrades to lock-free |
| 49 | +atomic write, v1.95.1). To run this repo's own test suite: |
| 50 | +`pip install -r requirements-dev.txt` (pytest / anyio / filelock). |
| 51 | + |
| 52 | +## Five-minute start |
| 53 | + |
| 54 | +1. In any project, tell the AI: `/regress:init` |
| 55 | +2. Daily flow: state a requirement → the AI produces a plan card → you |
| 56 | + **approve / edit / cancel** → it works (with boundary enforcement) → on |
| 57 | + commit, the gate re-runs tests and blocks on failure or unchecked |
| 58 | + acceptance rows |
| 59 | +3. Project state and archaeology live in `.regress/` |
| 60 | + |
| 61 | +## Side-effects declaration (transparency contract) |
| 62 | + |
| 63 | +- **Execution**: all hooks are local Python 3.10+ processes (no prebuilt |
| 64 | + binaries, no obfuscated source) |
| 65 | +- **File writes**: `.regress/` inside projects (manifests/history/ledgers) and |
| 66 | + `~/.zcode/regress-guard-hooks` (installed copy) |
| 67 | +- **Command execution**: exactly two classes — the gate invoking the project's |
| 68 | + own test runner (pytest/jest/maven/gradle/go, auto-detected), and notification |
| 69 | + channel commands (**only for human-granted projects**; untrusted configs fall |
| 70 | + back to machine level, closing the cloned-repo injection surface) |
| 71 | +- **Network**: zero egress by default. Optional interception notifications via |
| 72 | + WeCom self-built apps — credentials require human trust-grant and the API base |
| 73 | + is pinned to the official domain. No MCP, no telemetry upload, no third-party |
| 74 | + analytics |
| 75 | +- **Hook surface**: PreToolUse (commit gate / boundary guard / execution valve), |
| 76 | + PostToolUse (manifest bridge), UserPromptSubmit (governance context), |
| 77 | + SessionStart (self-heal), Stop (end-of-turn notices) |
| 78 | +- **Escapes**: `/regress:bypass N` gives a time-boxed amnesty (audited); each |
| 79 | + feature has an independent env switch |
| 80 | + |
| 81 | +## Health & verification |
| 82 | + |
| 83 | +`bash validate.sh` (expect 5/5) · `python3 -m pytest tests/ -q` (expect green) |
| 84 | +· post-install smoke check runs automatically with `install.sh` |
| 85 | + |
| 86 | +## License |
| 87 | + |
| 88 | +MIT. Third-party: none at runtime (stdlib only). |
| 89 | + |
| 90 | +<!-- generated: reference start · 本区由 scripts/gen_reference.py 生成，勿手改 --> |
| 91 | + |
| 92 | +**实况（由 gen_reference.py 生成，勿手改本区）** |
| 93 | + |
| 94 | +- 命令：16 个 · hook 注册：11 个事件条目 · 测试函数：693 个 |
| 95 | + |
| 96 | +| 命令 | 说明 | |
| 97 | +|---|---| |
| 98 | +| `/regress:bypass` | 紧急绕过回归卡点（限时 + 审计日志），用于 hotfix 等紧急场景 | |
| 99 | +| `/regress:characterize` | 特征测试生成：改无测试老代码前先钉住现状行为（golden master——探针真跑取真值，不猜输出） | |
| 100 | +| `/regress:evolve` | 遇到难点时查社区经验→适配项目→沉淀为知识库（不再重复查） | |
| 101 | +| `/regress:finish` | 收尾流水线：track 回写 → verify 全证据 → 代谢沉淀 → 状态推进 → 汇总报告（一条命令走完收尾，人只出现在决策点） | |
| 102 | +| `/regress:init` | 初始化项目的 .regress/ 数据目录（代码已在全局级安装，这里只建数据） | |
| 103 | +| `/regress:install` | 一键安装 regress-guard 到用户级（零配置，装一次全局生效） | |
| 104 | +| `/regress:learn` | 分析历史+检测框架规则，输出项目洞察，写入 AGENTS.md | |
| 105 | +| `/regress:plan` | 需求→解析→消歧→改动清单。AI 先补全上下文再动手（不问能推断的，只问关键分歧） | |
| 106 | +| `/regress:quick` | 快速模式——机器判据达标的小改动专用（合并 plan+track 一步到位） | |
| 107 | +| `/regress:resume` | 从 .regress/ 产物层单侧重建工作现场（断点续作，不依赖对话历史） | |
| 108 | +| `/regress:stats` | 健康报表：门禁拦截/债务/规律命中/僵尸清单/钩子活性一屏读（观测期仪表盘，只读不改） | |
| 109 | +| `/regress:trace` | 查看交付链：需求→会话→事件→提交 的可追溯视图（文本版 Inspector） | |
| 110 | +| `/regress:track` | 对比 git diff 发现 F3 并直接回写（AI 完成修改后自动执行，不需用户手动触发） | |
| 111 | +| `/regress:uninstall` | 卸载 regress-guard（清理用户级配置 + hook + skill + 命令） | |
| 112 | +| `/regress:update` | 检查并更新 regress-guard 到最新版（手动触发；SessionStart 也会自动检测） | |
| 113 | +| `/regress:verify` | 跑测试预览结果（提交时 hook 也会自动跑；测试失败 AI 应自行修复重跑） | |
| 114 | + |
| 115 | +<!-- generated: reference end --> |
0 commit comments