harald/zeroclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3

feat(proxy): add scoped proxy configuration and docs runbooks

Browse source 
- add scope-aware proxy schema and runtime wiring for providers/channels/tools

- add agent callable proxy_config tool for fast proxy setup

- standardize docs system with index, template, and playbooks
This commit is contained in:
Chummy 2026-02-18 21:09:01 +08:00
parent 13ee9e6398
commit ce104bed45
36 changed files with 2025 additions and 323 deletions
Download patch file Download diff file Expand all files Collapse all files

63
docs/doc-template.md Normal file
View file

@ -0,0 +1,63 @@
# Documentation Template (Operational)
Use this template when adding a new operational or engineering document under `docs/`.
Keep sections that apply; remove non-applicable placeholders before merging.
---
## 1. Summary
- **Purpose:** <one sentence about why this document exists>
- **Audience:** <operators | reviewers | contributors | maintainers>
- **Scope:** <what this doc covers>
- **Non-goals:** <what this doc intentionally does not cover>
## 2. Prerequisites
- <required environment>
- <required permissions>
- <required tools/config>
## 3. Procedure
### 3.1 Baseline Check
1. <step>
2. <step>
### 3.2 Main Workflow
1. <step>
2. <step>
3. <step>
### 3.3 Verification
- <expected output or success signal>
- <validation command/log/checkpoint>
## 4. Safety, Risk, and Rollback
- **Risk surface:** <which components may be impacted>
- **Failure modes:** <what can go wrong>
- **Rollback plan:** <concrete rollback command/steps>
## 5. Troubleshooting
- **Symptom:** <error/signal>
- **Cause:** <likely cause>
- **Fix:** <action>
## 6. Related Docs
- [README.md](./README.md) — documentation taxonomy and navigation.
- <related-doc-1.md>
- <related-doc-2.md>
## 7. Maintenance Notes
- **Owner:** <team/persona/area>
- **Update trigger:** <what changes should force this doc update>
- **Last reviewed:** <YYYY-MM-DD>

220
docs/pr-workflow.md
View file

@ -11,10 +11,66 @@ This document defines how ZeroClaw handles high PR volume while maintaining:
Related references:
- [`docs/ci-map.md`](ci-map.md) for per-workflow ownership, triggers, and triage flow.
- [`docs/reviewer-playbook.md`](reviewer-playbook.md) for day-to-day reviewer execution.
- [`docs/README.md`](./README.md) for documentation taxonomy and navigation.
- [`docs/ci-map.md`](./ci-map.md) for per-workflow ownership, triggers, and triage flow.
- [`docs/reviewer-playbook.md`](./reviewer-playbook.md) for day-to-day reviewer execution.
## 1) Governance Goals
## 0. Summary
- **Purpose:** provide a deterministic, risk-based PR operating model for high-throughput collaboration.
- **Audience:** contributors, maintainers, and agent-assisted reviewers.
- **Scope:** repository settings, PR lifecycle, readiness contracts, risk routing, queue discipline, and recovery protocol.
- **Non-goals:** replacing branch protection configuration or CI workflow source files as implementation authority.
---
## 1. Fast Path by PR Situation
Use this section to route quickly before full deep review.
### 1.1 Intake is incomplete
1. Request template completion and missing evidence in one checklist comment.
2. Stop deep review until intake blockers are resolved.
Go to:
- [Section 5.1](#51-definition-of-ready-dor-before-requesting-review)
### 1.2 `CI Required Gate` failing
1. Route failure through CI map and fix deterministic gates first.
2. Re-evaluate risk only after CI returns coherent signal.
Go to:
- [docs/ci-map.md](./ci-map.md)
- [Section 4.2](#42-step-b-validation)
### 1.3 High-risk path touched
1. Escalate to deep review lane.
2. Require explicit rollback, failure-mode evidence, and security boundary checks.
Go to:
- [Section 9](#9-security-and-stability-rules)
- [docs/reviewer-playbook.md](./reviewer-playbook.md)
### 1.4 PR is superseded or duplicate
1. Require explicit supersede linkage and queue cleanup.
2. Close superseded PR after maintainer confirmation.
Go to:
- [Section 8.2](#82-backlog-pressure-controls)
---
## 2. Governance Goals and Control Loop
### 2.1 Governance goals
1. Keep merge throughput predictable under heavy PR load.
2. Keep CI signal quality high (fast feedback, low false positives).
@ -22,18 +78,20 @@ Related references:
4. Keep changes easy to reason about and easy to revert.
5. Keep repository artifacts free of personal/sensitive data leakage.
### Governance Design Logic (Control Loop)
### 2.2 Governance design logic (control loop)
This workflow is intentionally layered to reduce reviewer load while keeping accountability clear:
1. **Intake classification**: path/size/risk/module labels route the PR to the right review depth.
2. **Deterministic validation**: merge gate depends on reproducible checks, not subjective comments.
3. **Risk-based review depth**: high-risk paths trigger deep review; low-risk paths stay fast.
4. **Rollback-first merge contract**: every merge path includes concrete recovery steps.
1. **Intake classification:** path/size/risk/module labels route the PR to the right review depth.
2. **Deterministic validation:** merge gate depends on reproducible checks, not subjective comments.
3. **Risk-based review depth:** high-risk paths trigger deep review; low-risk paths stay fast.
4. **Rollback-first merge contract:** every merge path includes concrete recovery steps.
Automation assists with triage and guardrails, but final merge accountability remains with human maintainers and PR authors.
## 2) Required Repository Settings
---
## 3. Required Repository Settings
Maintain these branch protection rules on `main`:
@ -45,9 +103,11 @@ Maintain these branch protection rules on `main`:
- Dismiss stale approvals when new commits are pushed.
- Restrict force-push on protected branches.
## 3) PR Lifecycle
---
### Step A: Intake
## 4. PR Lifecycle Runbook
### 4.1 Step A: Intake
- Contributor opens PR with full `.github/pull_request_template.md`.
- `PR Labeler` applies scope/path labels + size labels + risk labels + module labels (for example `channel:telegram`, `provider:kimi`, `tool:shell`) and contributor tiers by merged PR count (`trusted` >=5, `experienced` >=10, `principal` >=20, `distinguished` >=50), while de-duplicating less-specific scope labels when a more specific module label is present.
@ -58,27 +118,29 @@ Maintain these branch protection rules on `main`:
- Managed label colors are arranged by display order to create a smooth gradient across long label rows.
- `PR Auto Responder` posts first-time guidance, handles label-driven routing for low-signal items, and auto-applies issue contributor tiers using the same thresholds as `PR Labeler` (`trusted` >=5, `experienced` >=10, `principal` >=20, `distinguished` >=50).
### Step B: Validation
### 4.2 Step B: Validation
- `CI Required Gate` is the merge gate.
- Docs-only PRs use fast-path and skip heavy Rust jobs.
- Non-doc PRs must pass lint, tests, and release build smoke check.
### Step C: Review
### 4.3 Step C: Review
- Reviewers prioritize by risk and size labels.
- Security-sensitive paths (`src/security`, `src/runtime`, `src/gateway`, and CI workflows) require maintainer attention.
- Large PRs (`size: L`/`size: XL`) should be split unless strongly justified.
### Step D: Merge
### 4.4 Step D: Merge
- Prefer **squash merge** to keep history compact.
- PR title should follow Conventional Commit style.
- Merge only when rollback path is documented.
## 4) PR Readiness Contracts (DoR / DoD)
---
### Definition of Ready (before requesting review)
## 5. PR Readiness Contracts (DoR / DoD)
### 5.1 Definition of Ready (DoR) before requesting review
- PR template fully completed.
- Scope boundary is explicit (what changed / what did not).
@ -87,7 +149,7 @@ Maintain these branch protection rules on `main`:
- Privacy/data-hygiene checks are completed and test language is neutral/project-scoped.
- If identity-like wording appears in tests/examples, it is normalized to ZeroClaw/project-native labels.
### Definition of Done (merge-ready)
### 5.2 Definition of Done (DoD) merge-ready
- `CI Required Gate` is green.
- Required reviewers approved (including CODEOWNERS paths).
@ -95,7 +157,11 @@ Maintain these branch protection rules on `main`:
- Migration/compatibility impact is documented.
- Rollback path is concrete and fast.
## 5) PR Size Policy
---
## 6. PR Size and Batching Policy
### 6.1 Size tiers
- `size: XS` <= 80 changed lines
- `size: S` <= 250 changed lines
@ -103,93 +169,104 @@ Maintain these branch protection rules on `main`:
- `size: L` <= 1000 changed lines
- `size: XL` > 1000 changed lines
Policy:
### 6.2 Policy
- Target `XS/S/M` by default.
- `L/XL` PRs need explicit justification and tighter test evidence.
- If a large feature is unavoidable, split into stacked PRs.
Automation behavior:
### 6.3 Automation behavior
- `PR Labeler` applies `size:*` labels from effective changed lines.
- Docs-only/lockfile-heavy PRs are normalized to avoid size inflation.
## 6) AI/Agent Contribution Policy
---
## 7. AI/Agent Contribution Policy
AI-assisted PRs are welcome, and review can also be agent-assisted.
Required:
### 7.1 Required
1. Clear PR summary with scope boundary.
2. Explicit test/validation evidence.
3. Security impact and rollback notes for risky changes.
Recommended:
### 7.2 Recommended
1. Brief tool/workflow notes when automation materially influenced the change.
2. Optional prompt/plan snippets for reproducibility.
We do **not** require contributors to quantify AI-vs-human line ownership.
Review emphasis for AI-heavy PRs:
### 7.3 Review emphasis for AI-heavy PRs
- Contract compatibility
- Security boundaries
- Error handling and fallback behavior
- Performance and memory regressions
- Contract compatibility.
- Security boundaries.
- Error handling and fallback behavior.
- Performance and memory regressions.
## 7) Review SLA and Queue Discipline
---
## 8. Review SLA and Queue Discipline
- First maintainer triage target: within 48 hours.
- If PR is blocked, maintainer leaves one actionable checklist.
- `stale` automation is used to keep queue healthy; maintainers can apply `no-stale` when needed.
- `pr-hygiene` automation checks open PRs every 12 hours and posts a nudge when a PR has no new commits for 48+ hours and is either behind `main` or missing/failing `CI Required Gate` on the head commit.
Backlog pressure controls:
### 8.1 Queue budget controls
- Use a review queue budget: limit concurrent deep-review PRs per maintainer and keep the rest in triage state.
- For stacked work, require explicit `Depends on #...` so review order is deterministic.
### 8.2 Backlog pressure controls
- If a new PR replaces an older open PR, require `Supersedes #...` and close the older one after maintainer confirmation.
- Mark dormant/redundant PRs with `stale-candidate` or `superseded` to reduce duplicate review effort.
Issue triage discipline:
### 8.3 Issue triage discipline
- `r:needs-repro` for incomplete bug reports (request deterministic repro before deep triage).
- `r:support` for usage/help items better handled outside bug backlog.
- `invalid` / `duplicate` labels trigger **issue-only** closing automation with guidance.
Automation side-effect guards:
### 8.4 Automation side-effect guards
- `PR Auto Responder` deduplicates label-based comments to avoid spam.
- Automated close routes are limited to issues, not PRs.
- Maintainers can freeze automated risk recalculation with `risk: manual` when context demands human override.
## 8) Security and Stability Rules
---
## 9. Security and Stability Rules
Changes in these areas require stricter review and stronger test evidence:
- `src/security/**`
- runtime process management
- gateway ingress/authentication behavior (`src/gateway/**`)
- filesystem access boundaries
- network/authentication behavior
- GitHub workflows and release pipeline
- tools with execution capability (`src/tools/**`)
- Runtime process management.
- Gateway ingress/authentication behavior (`src/gateway/**`).
- Filesystem access boundaries.
- Network/authentication behavior.
- GitHub workflows and release pipeline.
- Tools with execution capability (`src/tools/**`).
Minimum for risky PRs:
### 9.1 Minimum for risky PRs
- threat/risk statement
- mitigation notes
- rollback steps
- Threat/risk statement.
- Mitigation notes.
- Rollback steps.
Recommended for high-risk PRs:
### 9.2 Recommended for high-risk PRs
- include a focused test proving boundary behavior
- include one explicit failure-mode scenario and expected degradation
- Include a focused test proving boundary behavior.
- Include one explicit failure-mode scenario and expected degradation.
For agent-assisted contributions, reviewers should also verify the author demonstrates understanding of runtime behavior and blast radius.
## 9) Failure Recovery
---
## 10. Failure Recovery Protocol
If a merged PR causes regressions:
@ -199,7 +276,9 @@ If a merged PR causes regressions:
Prefer fast restore of service quality over delayed perfect fixes.
## 10) Maintainer Checklist (Merge-Ready)
---
## 11. Maintainer Merge Checklist
- Scope is focused and understandable.
- CI gate is green.
@ -210,11 +289,13 @@ Prefer fast restore of service quality over delayed perfect fixes.
- Rollback plan is explicit.
- Commit title follows Conventional Commits.
## 11) Agent Review Operating Model
---
To keep review quality stable under high PR volume, we use a two-lane review model:
## 12. Agent Review Operating Model
### Lane A: Fast triage (agent-friendly)
To keep review quality stable under high PR volume, use a two-lane review model.
### 12.1 Lane A: fast triage (agent-friendly)
- Confirm PR template completeness.
- Confirm CI gate signal (`CI Required Gate`).
@ -223,7 +304,7 @@ To keep review quality stable under high PR volume, we use a two-lane review mod
- Confirm privacy/data-hygiene section and neutral wording requirements are satisfied.
- Confirm any required identity-like wording uses ZeroClaw/project-native terminology.
### Lane B: Deep review (risk-based)
### 12.2 Lane B: deep review (risk-based)
Required for high-risk changes (security/runtime/gateway/CI):
@ -232,15 +313,17 @@ Required for high-risk changes (security/runtime/gateway/CI):
- Validate backward compatibility and migration impact.
- Validate observability/logging impact.
## 12) Queue Priority and Label Discipline
---
Triage order recommendation:
## 13. Queue Priority and Label Discipline
1. `size: XS`/`size: S` + bug/security fixes
2. `size: M` focused changes
3. `size: L`/`size: XL` split requests or staged review
### 13.1 Triage order recommendation
Label discipline:
1. `size: XS`/`size: S` + bug/security fixes.
2. `size: M` focused changes.
3. `size: L`/`size: XL` split requests or staged review.
### 13.2 Label discipline
- Path labels identify subsystem ownership quickly.
- Size labels drive batching strategy.
@ -249,7 +332,9 @@ Label discipline:
- `risk: manual` allows maintainers to preserve a human risk judgment when automation lacks context.
- `no-stale` is reserved for accepted-but-blocked work.
## 13) Agent Handoff Contract
---
## 14. Agent Handoff Contract
When one agent hands off to another (or to a maintainer), include:
@ -259,3 +344,20 @@ When one agent hands off to another (or to a maintainer), include:
4. Suggested next action.
This keeps context loss low and avoids repeated deep dives.
---
## 15. Related Docs
- [README.md](./README.md) — documentation taxonomy and navigation.
- [ci-map.md](./ci-map.md) — CI workflow ownership and triage map.
- [reviewer-playbook.md](./reviewer-playbook.md) — reviewer execution model.
- [actions-source-policy.md](./actions-source-policy.md) — action source allowlist policy.
---
## 16. Maintenance Notes
- **Owner:** maintainers responsible for collaboration governance and merge quality.
- **Update trigger:** branch protection changes, label/risk policy changes, queue governance updates, or agent review process changes.
- **Last reviewed:** 2026-02-18.

229
docs/proxy-agent-playbook.md Normal file
View file

@ -0,0 +1,229 @@
# Proxy Agent Playbook
This playbook provides copy-paste tool calls for configuring proxy behavior via `proxy_config`.
Use this document when you want the agent to switch proxy scope quickly and safely.
## 0. Summary
- **Purpose:** provide copy-ready agent tool calls for proxy scope management and rollback.
- **Audience:** operators and maintainers running ZeroClaw in proxied networks.
- **Scope:** `proxy_config` actions, mode selection, verification flow, and troubleshooting.
- **Non-goals:** generic network debugging outside ZeroClaw runtime behavior.
---
## 1. Fast Path by Intent
Use this section for quick operational routing.
### 1.1 Proxy only ZeroClaw internal traffic
1. Use scope `zeroclaw`.
2. Set `http_proxy`/`https_proxy` or `all_proxy`.
3. Validate with `{"action":"get"}`.
Go to:
- [Section 4](#4-mode-a--proxy-only-for-zeroclaw-internals)
### 1.2 Proxy only selected services
1. Use scope `services`.
2. Set concrete keys or wildcard selectors in `services`.
3. Validate coverage using `{"action":"list_services"}`.
Go to:
- [Section 5](#5-mode-b--proxy-only-for-specific-services)
### 1.3 Export process-wide proxy environment variables
1. Use scope `environment`.
2. Apply with `{"action":"apply_env"}`.
3. Verify env snapshot via `{"action":"get"}`.
Go to:
- [Section 6](#6-mode-c--proxy-for-full-process-environment)
### 1.4 Emergency rollback
1. Disable proxy.
2. If needed, clear env exports.
3. Re-check runtime and environment snapshots.
Go to:
- [Section 7](#7-disable--rollback-patterns)
---
## 2. Scope Decision Matrix
| Scope | Affects | Exports env vars | Typical use |
|---|---|---|---|
| `zeroclaw` | ZeroClaw internal HTTP clients | No | Normal runtime proxying without process-level side effects |
| `services` | Only selected service keys/selectors | No | Fine-grained routing for specific providers/tools/channels |
| `environment` | Runtime + process environment proxy variables | Yes | Integrations that require `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` |
---
## 3. Standard Safe Workflow
Use this sequence for every proxy change:
1. Inspect current state.
2. Discover valid service keys/selectors.
3. Apply target scope configuration.
4. Verify runtime and environment snapshots.
5. Roll back if behavior is not expected.
Tool calls:
```json
{"action":"get"}
{"action":"list_services"}
```
---
## 4. Mode A — Proxy Only for ZeroClaw Internals
Use when ZeroClaw provider/channel/tool HTTP traffic should use proxy, without exporting process-level proxy env vars.
Tool calls:
```json
{"action":"set","enabled":true,"scope":"zeroclaw","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":["localhost","127.0.0.1"]}
{"action":"get"}
```
Expected behavior:
- Runtime proxy is active for ZeroClaw HTTP clients.
- `HTTP_PROXY` / `HTTPS_PROXY` process env exports are not required.
---
## 5. Mode B — Proxy Only for Specific Services
Use when only part of the system should use proxy (for example specific providers/tools/channels).
### 5.1 Target specific services
```json
{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request","channel.telegram"],"all_proxy":"socks5h://127.0.0.1:1080","no_proxy":["localhost","127.0.0.1",".internal"]}
{"action":"get"}
```
### 5.2 Target by selectors
```json
{"action":"set","enabled":true,"scope":"services","services":["provider.*","tool.*"],"http_proxy":"http://127.0.0.1:7890"}
{"action":"get"}
```
Expected behavior:
- Only matched services use proxy.
- Unmatched services bypass proxy.
---
## 6. Mode C — Proxy for Full Process Environment
Use when you intentionally need exported process env vars (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) for runtime integrations.
### 6.1 Configure and apply environment scope
```json
{"action":"set","enabled":true,"scope":"environment","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":"localhost,127.0.0.1,.internal"}
{"action":"apply_env"}
{"action":"get"}
```
Expected behavior:
- Runtime proxy is active.
- Environment variables are exported for the process.
---
## 7. Disable / Rollback Patterns
### 7.1 Disable proxy (default safe behavior)
```json
{"action":"disable"}
{"action":"get"}
```
### 7.2 Disable proxy and force-clear env vars
```json
{"action":"disable","clear_env":true}
{"action":"get"}
```
### 7.3 Keep proxy enabled but clear environment exports only
```json
{"action":"clear_env"}
{"action":"get"}
```
---
## 8. Common Operation Recipes
### 8.1 Switch from environment-wide proxy to service-only proxy
```json
{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request"],"all_proxy":"socks5://127.0.0.1:1080"}
{"action":"get"}
```
### 8.2 Add one more proxied service
```json
{"action":"set","scope":"services","services":["provider.openai","tool.http_request","channel.slack"]}
{"action":"get"}
```
### 8.3 Reset `services` list with selectors
```json
{"action":"set","scope":"services","services":["provider.*","channel.telegram"]}
{"action":"get"}
```
---
## 9. Troubleshooting
- Error: `proxy.scope='services' requires a non-empty proxy.services list`
- Fix: set at least one concrete service key or selector.
- Error: invalid proxy URL scheme
- Allowed schemes: `http`, `https`, `socks5`, `socks5h`.
- Proxy does not apply as expected
- Run `{"action":"list_services"}` and verify service names/selectors.
- Run `{"action":"get"}` and check `runtime_proxy` and `environment` snapshot values.
---
## 10. Related Docs
- [README.md](./README.md) — Documentation index and taxonomy.
- [network-deployment.md](./network-deployment.md) — end-to-end network deployment and tunnel topology guidance.
- [resource-limits.md](./resource-limits.md) — runtime safety limits for network/tool execution contexts.
---
## 11. Maintenance Notes
- **Owner:** runtime and tooling maintainers.
- **Update trigger:** new `proxy_config` actions, proxy scope semantics, or supported service selector changes.
- **Last reviewed:** 2026-02-18.

197
docs/reviewer-playbook.md
View file

@ -1,39 +1,93 @@
# Reviewer Playbook
This playbook is the operational companion to [`docs/pr-workflow.md`](pr-workflow.md).
Use it to reduce review latency without reducing quality.
This playbook is the operational companion to [`docs/pr-workflow.md`](./pr-workflow.md).
For broader documentation navigation, use [`docs/README.md`](./README.md).
## 1) Review Objectives
## 0. Summary
- Keep queue throughput predictable.
- Keep risk review proportionate to change risk.
- Keep merge decisions reproducible and auditable.
- **Purpose:** define a deterministic reviewer operating model that keeps review quality high under heavy PR volume.
- **Audience:** maintainers, reviewers, and agent-assisted reviewers.
- **Scope:** intake triage, risk-to-depth routing, deep-review checks, automation overrides, and handoff protocol.
- **Non-goals:** replacing PR policy authority in `CONTRIBUTING.md` or workflow authority in CI files.
## 2) 5-Minute Intake Triage
---
For every new PR, do a fast intake pass:
## 1. Fast Path by Review Situation
Use this section to route quickly before reading full detail.
### 1.1 Intake fails in first 5 minutes
1. Leave one actionable checklist comment.
2. Stop deep review until intake blockers are fixed.
Go to:
- [Section 3.1](#31-five-minute-intake-triage)
### 1.2 Risk is high or unclear
1. Treat as `risk: high` by default.
2. Require deep review and explicit rollback evidence.
Go to:
- [Section 2](#2-review-depth-decision-matrix)
- [Section 3.3](#33-deep-review-checklist-high-risk)
### 1.3 Automation output is wrong/noisy
1. Apply override protocol (`risk: manual`, dedupe comments/labels).
2. Continue review with explicit rationale.
Go to:
- [Section 5](#5-automation-override-protocol)
### 1.4 Need review handoff
1. Handoff with scope/risk/validation/blockers.
2. Assign concrete next action.
Go to:
- [Section 6](#6-handoff-protocol)
---
## 2. Review Depth Decision Matrix
| Risk label | Typical touched paths | Minimum review depth | Required evidence |
|---|---|---|---|
| `risk: low` | docs/tests/chore, isolated non-runtime changes | 1 reviewer + CI gate | coherent local validation + no behavior ambiguity |
| `risk: medium` | `src/providers/**`, `src/channels/**`, `src/memory/**`, `src/config/**` | 1 subsystem-aware reviewer + behavior verification | focused scenario proof + explicit side effects |
| `risk: high` | `src/security/**`, `src/runtime/**`, `src/gateway/**`, `src/tools/**`, `.github/workflows/**` | fast triage + deep review + rollback readiness | security/failure-mode checks + rollback clarity |
When uncertain, treat as `risk: high`.
If automated risk labeling is contextually wrong, maintainers can apply `risk: manual` and set the final `risk:*` label explicitly.
---
## 3. Standard Review Workflow
### 3.1 Five-minute intake triage
For every new PR:
1. Confirm template completeness (`summary`, `validation`, `security`, `rollback`).
2. Confirm labels (`size:*`, `risk:*`, scope labels such as `provider`/`channel`/`security`, module-scoped labels such as `channel: *`/`provider: *`/`tool: *`, and contributor tier labels when applicable) are present and plausible.
2. Confirm labels are present and plausible:
- `size:*`, `risk:*`
- scope labels (for example `provider`, `channel`, `security`)
- module-scoped labels (`channel:*`, `provider:*`, `tool:*`)
- contributor tier labels when applicable
3. Confirm CI signal status (`CI Required Gate`).
4. Confirm scope is one concern (reject mixed mega-PRs unless justified).
5. Confirm privacy/data-hygiene and neutral test wording requirements are satisfied.
If any intake requirement fails, leave one actionable checklist comment instead of deep review.
## 3) Risk-to-Depth Matrix
| Risk label | Typical touched paths | Minimum review depth |
|---|---|---|
| `risk: low` | docs/tests/chore, isolated non-runtime changes | 1 reviewer + CI gate |
| `risk: medium` | `src/providers/**`, `src/channels/**`, `src/memory/**`, `src/config/**` | 1 subsystem-aware reviewer + behavior verification |
| `risk: high` | `src/security/**`, `src/runtime/**`, `src/gateway/**`, `src/tools/**`, `.github/workflows/**` | fast triage + deep review, strong rollback and failure-mode checks |
When uncertain, treat as `risk: high`.
If automated risk labeling is contextually wrong, maintainers can apply `risk: manual` and set the final risk label explicitly.
## 4) Fast-Lane Checklist (All PRs)
### 3.2 Fast-lane checklist (all PRs)
- Scope boundary is explicit and believable.
- Validation commands are present and results are coherent.
@ -45,17 +99,31 @@ If automated risk labeling is contextually wrong, maintainers can apply `risk: m
- If identity-like wording exists, it uses ZeroClaw/project-native roles (not personal or real-world identities).
- Naming and architecture boundaries follow project contracts (`AGENTS.md`, `CONTRIBUTING.md`).
## 5) Deep Review Checklist (High Risk)
### 3.3 Deep review checklist (high risk)
For high-risk PRs, verify at least one example in each category:
For high-risk PRs, verify at least one concrete example in each category:
- **Security boundaries**: deny-by-default behavior preserved, no accidental scope broadening.
- **Failure modes**: error handling is explicit and degrades safely.
- **Contract stability**: CLI/config/API compatibility preserved or migration documented.
- **Observability**: failures are diagnosable without leaking secrets.
- **Rollback safety**: revert path and blast radius are clear.
- **Security boundaries:** deny-by-default behavior preserved, no accidental scope broadening.
- **Failure modes:** error handling is explicit and degrades safely.
- **Contract stability:** CLI/config/API compatibility preserved or migration documented.
- **Observability:** failures are diagnosable without leaking secrets.
- **Rollback safety:** revert path and blast radius are clear.
## 6) Issue Triage Playbook
### 3.4 Review comment outcome style
Prefer checklist-style comments with one explicit outcome:
- **Ready to merge** (say why).
- **Needs author action** (ordered blocker list).
- **Needs deeper security/runtime review** (state exact risk and requested evidence).
Avoid vague comments that create avoidable back-and-forth latency.
---
## 4. Issue Triage and Backlog Governance
### 4.1 Issue triage label playbook
Use labels to keep backlog actionable:
@ -63,28 +131,9 @@ Use labels to keep backlog actionable:
- `r:support` for usage/support questions better routed outside bug backlog.
- `duplicate` / `invalid` for non-actionable duplicates/noise.
- `no-stale` for accepted work waiting on external blockers.
- Request redaction if logs/payloads include personal identifiers or sensitive data.
- Request redaction when logs/payloads include personal identifiers or sensitive data.
## 7) Review Comment Style
Prefer checklist-style comments with one of these outcomes:
- **Ready to merge** (explicitly say why).
- **Needs author action** (ordered list of blockers).
- **Needs deeper security/runtime review** (state exact risk and requested evidence).
Avoid vague comments that create back-and-forth latency.
## 8) Automation Override Protocol
Use this when automation output creates review side effects:
1. **Incorrect risk label**: add `risk: manual`, then set the intended `risk:*` label.
2. **Incorrect auto-close on issue triage**: reopen issue, remove route label, and leave one clarifying comment.
3. **Label spam/noise**: keep one canonical maintainer comment and remove redundant route labels.
4. **Ambiguous PR scope**: request split before deep review.
### PR Backlog Pruning Protocol
### 4.2 PR backlog pruning protocol
When review demand exceeds capacity, apply this order:
@ -93,18 +142,50 @@ When review demand exceeds capacity, apply this order:
3. Mark dormant PRs as `stale-candidate` before stale closure window starts.
4. Require rebase + fresh validation before reopening stale/superseded technical work.
## 9) Handoff Protocol
---
## 5. Automation Override Protocol
Use this when automation output creates review side effects:
1. **Incorrect risk label:** add `risk: manual`, then set intended `risk:*` label.
2. **Incorrect auto-close on issue triage:** reopen issue, remove route label, leave one clarifying comment.
3. **Label spam/noise:** keep one canonical maintainer comment and remove redundant route labels.
4. **Ambiguous PR scope:** request split before deep review.
---
## 6. Handoff Protocol
If handing off review to another maintainer/agent, include:
1. Scope summary
2. Current risk class and why
3. What has been validated already
4. Open blockers
5. Suggested next action
1. Scope summary.
2. Current risk class and rationale.
3. What has been validated already.
4. Open blockers.
5. Suggested next action.
## 10) Weekly Queue Hygiene
---
## 7. Weekly Queue Hygiene
- Review stale queue and apply `no-stale` only to accepted-but-blocked work.
- Prioritize `size: XS/S` bug/security PRs first.
- Convert recurring support issues into docs updates and auto-response guidance.
---
## 8. Related Docs
- [README.md](./README.md) — documentation taxonomy and navigation.
- [pr-workflow.md](./pr-workflow.md) — governance workflow and merge contract.
- [ci-map.md](./ci-map.md) — CI ownership and triage map.
- [actions-source-policy.md](./actions-source-policy.md) — action source allowlist policy.
---
## 9. Maintenance Notes
- **Owner:** maintainers responsible for review quality and queue throughput.
- **Update trigger:** PR policy changes, risk-routing model changes, or automation override behavior changes.
- **Last reviewed:** 2026-02-18.