# Review Gate > Layered code quality gate by risk (L1/L2/L3). - Skill: `jajabong/review-gate` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add jajabong/review-gate` - Raw SKILL.md: https://api.skillmd.com/api/skills/jajabong/review-gate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: jajabong (https://skillmd.com/u/jajabong) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/jajabong/review-gate --- # Review Gate — Layered Code Quality Gate Queen-mode 的分层代码质量门。Codex 实现后，以风险匹配 L1 确定性检查、L2 OpenCode 独立 review、必要时 L3 Pi/Anchor 复审；Queen 只读结构化摘要和证据。 ## When to use - Codex 或其他实现 agent 完成代码改动后 - 用户要求 code review / quality gate / security review - 多文件功能、业务逻辑、API、依赖或配置变化 - 高风险 auth/crypto/schema/concurrency/production 变更 ## Native tools and fleet 使用 Hermes 原生工具：`terminal`、`read_file`、`search_files`、`skill_view`、`todo`、`delegate_task`、`execute_code`。可复用 `queen-dispatch`，但 reviewer 与实现者必须隔离；同一 reviewer 不得修改并批准自己的改动。 ## CLI discovery — 每次运行先做 不要硬编码未经本机验证的参数。先运行： ```bash opencode run --help pi --help codex exec --help codex review --help ``` 当前本机已验证的调用形态： ```bash # Implementation: writable sandbox codex exec -C -s workspace-write --skip-git-repo-check --ephemeral "" # L2: OpenCode supports --dir and --format json; it does NOT support --allow-read. # Read-only is enforced by prompt and by omitting --auto. opencode run --dir -m opencode/deepseek-v4-flash-free \ --format json "" # L3: Pi has explicit read-only built-in tool allowlist. pi -p --provider anchor --model anchor \ --tools read,grep,find,ls --no-session "" ``` CLI help 变化时，更新调用方式；不得继续使用失效参数。 ## Artifact contract 所有产物写到： ```text ~/.hermes/artifacts/review// ├── manifest.json ├── implementation-summary.md ├── l1.json ├── l1.log ├── l2-review.json 或 l2-review.md ├── l3-review.json 或 l3-review.md └── decision.md ``` 用 `scripts/review_gate.py init` 创建目录和 manifest；用 `classify` 做风险分类；用 `validate` 检查 schema；用 `route` 查看应运行的层级。 ### manifest.json required fields - `run_id` - `project_root` - `goal` - `acceptance_criteria` - `base_ref` - `head_ref` - `changed_files` - `risk_level` - `risk_reasons` - `started_at` - `completed_at` - `status` ### L2 finding schema ```json { "severity": "blocker|high|medium|low|info", "category": "spec|correctness|security|performance|concurrency|compatibility|testing|maintainability", "title": "...", "evidence": ["path/to/file.py:42"], "impact": "...", "recommendation": "...", "confidence": 0.0 } ``` L2 报告还必须包含： - `verdict` - `findings` - `commands_reviewed` - `tests_missing` - `escalation_required` - `escalation_reasons` 无 `path:line` 证据的 finding 必须降为 `info`。 ### L3 report additions - `reviewed_l2_findings` - `confirmed_findings` - `rejected_findings` - `new_findings` - `critical_invariants` - `final_recommendation` ## Risk classification ### LOW - 文档、注释、格式 - 局部测试补充 - 无行为变化的小重构 Route：L1 必须；L2 单路快速 review；不启动 L3。 ### MEDIUM - 普通业务逻辑 - 多文件功能 - API 内部实现变化 - 新依赖或配置变化 Route：L1 + 单路完整 L2；L3 仅在冲突、证据不足或 high finding 时升级。 ### HIGH - auth / authorization / crypto / secrets / 支付 / 计费 - migration / schema / 数据删除 / 不可逆操作 - 并发 / 锁 / 事务 / 缓存一致性 / 分布式系统 - 远程命令执行 / 文件权限 / 网络边界 / 用户输入执行 - public API / 协议 / 持久化格式 / 向后兼容性变化 - production hotfix / release blocker - 无法完整测试的生产路径 - L1 缺失关键验证 - L2 blocker/high、结论冲突、低置信度或明确请求升级 Route：L1 + L2 + L3。 Agent 数量随风险和模块独立性增加，不固定三路 swarm。LOW 不运行多 reviewer 共识；多个 reviewer 不得重复读取同一完整 diff。 ## Workflow ### 0. Learning-loop preflight 陌生框架、协议、安全机制或项目领域： 1. `skills_list()` 查本地 skill 2. 未命中则 `skill_view("learning-loop")` 3. 从官方文档和高质量 GitHub 项目提取可证伪验收条件 4. 检查 license、活跃度、兼容性、安全边界；不要直接复制 ### 1. Scope and manifest 先用 shell 获取范围，不把完整 stdout 塞入对话： ```bash git -C diff --stat ... git -C diff --name-only ... ``` 创建 run： ```bash python3 ~/.hermes/skills/review-gate/scripts/review_gate.py init \ --project-root --goal "" \ --acceptance "" --base-ref --head-ref \ --changed-file path/a.py --changed-file path/b.py ``` ### 2. Implementation — Codex 使用 `workspace-write` 或本机 `codex exec --help` 显示的等价安全模式。实现 agent 必须把简短摘要写入 `implementation-summary.md`，包含 files changed、关键决策、已知限制。Codex 自带 review 只算实现者自检，不能代替 L2/L3。 ### 3. L1 — deterministic gate 先读项目 `AGENTS.md`、`README`、package scripts、`pyproject.toml`、Makefile、CI 配置，识别真实命令。按项目适用性运行 targeted/full tests、lint、typecheck、build、`git diff --check`、已有安全扫描。 完整日志写 `l1.log`；摘要写 `l1.json`。L1 失败立即回派原实现 agent，不进入 L2。 ### 4. L2 — independent OpenCode review 默认单 reviewer，只读，不修改代码。只传：目标/验收、项目根、diff 范围、L1 摘要、重点 `path:line`。OpenCode 当前支持 `--format json`，优先收集 JSON event stream，再让 reviewer 将最终结构化报告写到 artifact；若不能可靠输出 JSON，写 Markdown。 Review：spec、correctness、边界条件、回归、错误/资源处理、测试质量、安全、性能、并发、兼容性、无关改动、过度设计。 ### 5. Escalation decision 以下任一条件触发 L3：HIGH 分类；L1 缺关键验证；L2 blocker/high；证据冲突；低置信度；reviewer 要求升级；用户明确要求 security/architecture/deep review。 ### 6. L3 — Pi/Anchor read-only 使用本机已验证的只读工具白名单：`read,grep,find,ls`。不启用 edit/write/bash。L3 只验证 L2 高风险 finding、关键不变量、威胁/失败模型、测试缺口、可交付性，不重新实现。 ### 7. Queen decision Queen 只读：implementation summary、changed files、L1 summary、L2 findings、L3 report（若有）、最终 diff 摘要。 - `PASS`：无 blocker/high，所有必需验证通过 - `PASS_WITH_NOTES`：仅 non-blocking medium/low，列出技术债 - `CHANGES_REQUIRED`：可修复 blocker/high 或验证失败 - `BLOCKED`：缺凭据、环境、需求决策或无法验证 问题回派原实现 agent；只传未解决 findings。受影响的 L1/L2 重跑，最多两轮；仍失败则报告用户。 ## Token rules - 先 diff stat / changed-file list / targeted context - reviewer 按文件或模块分片，禁止重复读全仓库 - 完整日志落盘，Queen 只收必要证据摘要 - 每个 finding 必须带 `path:line`；否则降为 info - 无风险信号不启动 L3 - 修复轮只传 unresolved findings - 外部 agent final 简短，详细证据写 artifact - Queen 不把 worker stdout 原样塞回对话 ## Verification ```bash python3 ~/.hermes/skills/software-development/review-gate/scripts/test_review_gate.py hermes skills list | grep review-gate ``` ## Dispatcher integration (L1 + L2) Use `queen-dispatch` to run review-gate without putting LLM in the scheduler loop. Canonical DAG: 1. implement (codex write) — optional if code already changed 2. `l1_collect` (shell) — deterministic checks → `~/.hermes/artifacts/review//` 3. `l2-review` (opencode read_only) — independent review 4. `l2_collect` (shell) — normalize opencode JSONL → `l2-review.json` + `decision.md` Scripts: ```bash python3 ~/.hermes/skills/software-development/review-gate/scripts/l1_collect.py --project-root --run-id --goal "..." --acceptance "..." --changed-file path.py --risk-level MEDIUM --command "python3 -m pytest -q" python3 ~/.hermes/skills/software-development/review-gate/scripts/l2_from_opencode.py --run-id --stdout ~/.hermes/artifacts/queen//tasks/l2-review/stdout.log ``` Example plan: ```bash ~/.hermes/skills/queen-dispatch/scripts/dispatcher.py --plan ~/.hermes/skills/queen-dispatch/examples/review-gate-l1-l2-plan.json --dry-run ``` Rules: - L1 failure blocks L2 (`on_failure=block`) - L2 is always read_only; never pass `--auto` to opencode - L3 is not in this default plan; escalate only when route/risk says HIGH - Queen reads `status.json` + `~/.hermes/artifacts/review//{l1.json,l2-review.json,decision.md}` ## Dispatcher integration (HIGH → Pi L3) For HIGH risk, extend the L1+L2 plan with: 1. `l3-pi-review` (`engine=pi`, `role=review`, `execution_mode=read_only`) 2. `l3-collect` (`engine=shell`) → `l3-review.json` + final `decision.md` The dispatcher forces Pi review tasks to: ```bash pi-anchor -p --provider anchor --model anchor --mode json --no-session --tools read,grep,find,ls "" ``` Pi L3 reviews L2 findings and critical invariants only. It must not re-implement. Normalize output: ```bash python3 ~/.hermes/skills/software-development/review-gate/scripts/l3_from_pi.py --run-id --stdout ~/.hermes/artifacts/queen//tasks/l3-pi-review/stdout.log ``` Example: `~/.hermes/skills/queen-dispatch/examples/review-gate-high-l3-plan.json`.