agentic-flow-kit 1.8.7 → 2.1.0

package/locales/en/overrides/.agents/commands/maintain.md

@@ -0,0 +1,76 @@
+---
+description: "Maintain stage: file an incident + retrospective trio (fix / recurrence prevention / rule entry)"
+stage: Maintain
+triggers:
+  - "file an incident"
+  - "production is down"
+  - "log an incident"
+  - "something broke, root cause xxx"
+delegation:
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: the user has chosen the stop-the-bleeding or structural fix plan, the reproduction path and authorized files are clear, and the task meets the role contract
+    required: false
+    fallback: main
+approval_required: true
+next: .agents/commands/stages.md Plan chapter (if the retrospective needs a new intent)
+---
+
+# Maintain · File an Incident + Retrospective Trio
+
+For L1 that is not a production incident, a recurrence, data, or a contract change: do only §1 (file the document), then return to `.agents/commands/new-task.md` §L1 Fast Track. §0 stop-the-bleeding and §2 the retrospective trio are reserved for production incidents and L2/L3. An incident must still be filed.
+
+## 0. Active Incident (Emergency Stop-the-Bleeding)
+**Input**: failure symptoms / logs
+**Process**:
+1. **Diagnose**: read logs + code $\rightarrow$ provide [stop-the-bleeding options (revert/rollback/hotfix/degrade)] + [impact surface / time cost]
+2. **Execute**: the user decides the plan $\rightarrow$ AI only executes the chosen plan (no self-initiated pushing of fixes)
+3. **Verify**: after the hotfix, run `node .agents/scripts/verify.mjs --scope` (policy in the header note)
+**Output**: service restored $\rightarrow$ enter the retrospective flow
+
+## 1. Draft the Incident
+**Input**: failure context after stop-the-bleeding completes
+**Process**:
+1. **Similar-case search**: `node .agents/scripts/kb-search.mjs "<keyword>" --scope workflow --type incidents` $\rightarrow$ cite existing recurrence-prevention entries
+2. **Create document**: copy `_TEMPLATE.md` $\rightarrow$ `workflow/incidents/{name}.md`
+3. **Fill in content**: [timeline (discovery$\rightarrow$recovery)] / [impact surface] / [root cause (underlying reason)] / [gate-failure analysis]
+**Output**: `workflow/incidents/{name}.md` (Status: Draft)
+
+## 2. Draft the Retrospective Trio (The Trio)
+**Requirement**: all three items are mandatory; recurrence-prevention commitments must not remain only in documents.
+**Process**:
+1. **Structural fix**: record [fix commit SHA + file list] $\rightarrow$ decide whether a new intent is needed (if the root cause is a missing gate / unimplemented rule $\rightarrow$ mandatory `workflow/intents/`). **Attack the premise**: when under the same premise two fix approaches both fail the same verification, stop and write down the premise itself and test it directly — prevent "reskinned fixes" from slipping through the retrospective
+2. **Recurrence-prevention verification**: must land as [automated test case / `stages.md` Test chapter step / `regression-checklist.md` entry]; from the day a fixed/closed document is filed, check-loop §3x hard-blocks "no automated test case / regression-checklist reference" (no "manually verified")
+3. **Rule entry**: landing priority order: `regression-checklist.md` $\rightarrow$ `hooks/` $\rightarrow$ `skills/` $\rightarrow$ `notes/` $\rightarrow$ `commands/` (root `AGENTS.md` is prohibited). **Fix-strength ladder**: the landing order is positional; strength is judged separately — architectural consolidation/hooks/CI > automated test cases > rule text; when landing as rule text, the retrospective must state "why the stronger tier cannot block it"
+**Output**: landing verification plan + rule change record
+
+## 3. Confirmation & Landing
+This section starts from production incidents and L2/L3.
+**Process**:
+1. **HALT**: output the incident + trio drafts $\rightarrow$ wait for user confirmation
+2. **Stepwise confirmation**: incident draft / spec / plan confirmed independently (no combining)
+3. **Pre-check**: before L2/L3 confirmation $\rightarrow$ `fill-spec`/`confirm-doc` verifies that "the timeline includes user confirmation" is recorded $\rightarrow$ if not, backfill
+4. **Landing execution**:
+   - **Pair with plan**: must create a same-named `workflow/plans/{name}.md` (incident $\equiv$ intent, but plan cannot be omitted)
+   - **Implement the fix**: L1 $\rightarrow$ return to `.agents/commands/new-task.md` §L1 Fast Track (the same-named L1 plan is the entry; do not enter `stages.md`); L2/L3 $\rightarrow$ `stages.md` Design $\rightarrow$ Build $\rightarrow$ Test chapters
+   - **Land the trio**: execute the verification and rule changes from §2
+**Next**: if systemic issues need tracking $\rightarrow$ `.agents/commands/stages.md` Plan chapter to file a new intent
+
+## 4. Closeout After Confirmation
+**Process**:
+1. **Status transitions**: `open` $\rightarrow$ `fixed` (trio landed) $\rightarrow$ `closed` (recurrence-prevention verification passed)
+2. **State entry point**: `confirm-doc.mjs` migrates step by step (policy in `new-task.md` Fast Track step 4)
+3. **Reconciliation**: `check-loop 15` verifies the order of [closeout edit $\rightarrow$ closed confirmation]
+4. **Ruling backfill after closeout**: if a done/closed document genuinely needs a ruling backfilled $\rightarrow$ change the body and in the **same batch** append a **re-confirmation compensation line** to `.agents/confirmations.jsonl` — same doc+stage, fingerprint = post-edit content fingerprint (bindingSha256), prev uses the original line, quote = the user's ruling verbatim (source: chat-delegated); append-only, do not alter historical lines; check-loop 15 takes effect based on the last done line (re-confirmation scenario). Note that `confirm-doc` has no forward transition for terminal-state documents, so append the compensation line directly to the ledger. **Generator**: `node .agents/scripts/append-compensation.mjs <doc...> --quote "<user's verbatim words>"`; hand-crafted hashes are blocked by the s15 content-drift gate
+
+## 🚫 Prohibitions
+| Operation | Consequence / machine behavior | Exception |
+|---|---|---|
+| Commitment stays in documents | $\rightarrow$ treated as not closed | Must land as code/script/checklist |
+| Landing in root AGENTS | $\rightarrow$ violates single-source discipline | Must push down to notes/commands/hooks |
+| Single-hop status | check-loop 15 blocks | Must be fixed $\rightarrow$ closed |
+| Editing the body after closeout without backfill | check-loop 15 fingerprint-drift block | Ruling backfill must include re-confirmation compensation lines in the same batch (see §4.4) |
+
+## 🛠️ Auxiliary Tools
+- **Root-cause diagnosis**: `diagnosing-bugs` diagnostic loop
+- **Incident triage**: `triage` state-machine approach

package/locales/en/overrides/.agents/commands/new-task.md

@@ -0,0 +1,89 @@
+# New Task · Closed-Loop Entry Point
+
+> **⛔ Order**: grade first → file the trio first → confirm each item → only then write code. "Change first, document later" is prohibited (= bypassing the confirmation gate; violators record both incident+papercuts). Details and strength rationale: `.agents/notes/process-order-rule.md`.
+
+## 1. Risk Grading (Step 0: Grade Before Routing)
+
+| Lane | Level | Criterion | Confirmation & audit policy |
+|---|---|---|---|
+| **Coordination lane** | **L1** implementation | Implementation-level change that misses L2/L3 | A single plan is the entry point (source / goal / red lines / changes / verification / acceptance). No separate intent. No synchronous prerequisite for independent review; `--batch` is L1-only |
+| **Defense lane** | **L2** rule/contract | See §L2 closed set | Synchronous confirmation gates: spec confirmation $\rightarrow$ plan confirmation $\rightarrow$ start work |
+| | **L3** data/runtime structure | schema / migration SQL / DI chain / auth and middleware pipeline | Same as L2 + spec independently reviewed in a new session; no go-ahead until confirmed |
+
+> **Two-question grading**: structural surface (schema / migration SQL / DI / auth pipeline) → L3; contract or shared policy → L2; neither → L1. Do not slide upward from L1 based on severity.
+> **Question typing**: if it can be run/checked out (behavior/timing/layout/output/existing data/eval distinguishable), prototype/query the DB/run eval first; do not stop to ask. Only product/preference judgments escalate to confirmation. Orthogonal to the STOP line (experimentation does not exempt red lines).
+> **Placement**: L1 is written into the plan frontmatter `级别`; L2/L3 into the intent.
+> **Under-grading block**: if an L1 plan or intent checks a touched red line → check-loop "red-line under-grading" hard block → escalate to L2/L3 and add a same-named spec.
+
+### L2 Touched Surface (Closed Set; Hitting Any One Means L2)
+
+| # | Category | Criterion |
+|---|---|---|
+| 1 | **Coding authority** | Coding/naming/numbering rules generated once and consumed in many places |
+| 2 | **Shared contract** | Cross-module shared base classes / DTO shapes / public interface signatures |
+| 3 | **Existing interface semantics** | Behavior changes to existing parameters or endpoints (disabled becomes enabled, default/clamping policy changes) |
+| 4 | **Global cross-cutting policy** | Error response exit points, pagination and validation policy, aggregate projection keys |
+
+> **Negative examples (fall to L1)**: pure page presentation/copy/layout/interaction implementation; purely new endpoints or parameters with unchanged behavior; single-module internal refactoring with no external contract change; purely new pages/routes with no shared contract; single-module internal component splitting; module-internal new types/constants not consumed across modules.
+> **Self-check sentence**: can you list $\ge 2$ actual consumers whose behavior is affected (module/endpoint/page; signature-only visibility with unchanged behavior does not count)? If yes $\rightarrow$ L2.
+> **Default tier**: if no red line is checked, it is L1. Grading only answers "does it hit the four L2 categories or an L3 structural surface".
+
+## 1b. Todo Seeding
+
+After grading and before starting work, **copy verbatim** the step headings of the chosen command into the first item of the todo list; do not write a separate summary. Keep skipped steps in the list and write `skip: <reason>`. The todo is the execution contract; the command file is the playbook — this page does not duplicate the step body (single source).
+
+## 1c. Stage Coupling Protocol (Load on Entry + Auto-Chaining)
+
+- **Load on entry**: when entering any stage command, first read the SKILL.md of the skill bound to that stage (the body lives single-source on the skill side; this table only holds pointers):
+
+| Stage | Load on entry |
+|---|---|
+| Plan (intent) | `grilling` (questioning to solidify background/goals/non-goals) |
+| Design (spec) | `grilling` (ambiguity checklist / solution stress test); `codebase-design` / `domain-modeling` as needed; `arena` for branching comparison; required inputs see `stages.md` Design §2 |
+| Build | No mandatory skill (implementation delegation goes through the `implementer` role) |
+| Test | `verify-ui` for frontend changes; `review-method` for L2/L3 independent review |
+| Deploy | None (follow the checklist and the go-live authorization gate) |
+| Maintain | `why` (root-cause evidence chain) |
+| Review (cross-cutting) | `review-method`; `interrogate` for high-risk diffs; `blast-radius` for impact surface |
+
+- **Auto-chaining**: after a stage completes (confirmation gate passed + trace commit landed), **automatically proceed to the next-stage command pointed to by the frontmatter `next`** without waiting for the user to prompt.
+- **Human gates are never crossed automatically**: automatic flow refers only to stage chaining and skill loading — every stage's HALT confirmation, pipeline-run's `await-confirm`, and go-live authorization (deploy's "上") stop at their points and wait for the user's verbatim go-ahead.
+
+## L0 Minimal Path
+
+Criteria (all machine-checkable): product surface ≤5 files; misses the §1 L2 closed set/L3 structural surface; not a data-maintenance SQL execution; no new dependencies/build steps (the engine/wiki surface is already exempt).
+Overlapping criteria: take L0.
+Flow: grade → change code → `node .agents/scripts/verify.mjs --face`/`--scope` green → single commit; the message body includes a line `L0: <criterion>` (machine-greppable).
+
+## L1 Fast Track
+
+If L2 or L3 is hit, leave this page. L1 stops at the following 6 steps and does not open `stages.md`.
+
+> **Takeover/resume**: first read `.agents/skills/session-resume/SKILL.md` to rebuild the current state, then follow the 6 steps below.
+
+1. **Grade**: use the two questions in §1 and the L2 closed set. If nothing is hit, it is L1; write `级别` in the plan frontmatter. Completion criterion: the level in the plan header matches the two-question conclusion.
+2. **Search**: `node .agents/scripts/kb-search.mjs --scope workflow --module <module> "<keyword>"`. Write the root causes of hit incidents into the self-check of the plan in the next step. Completion criterion: the command was run; hit root causes are prepared for the plan, and with no hits it is enough to paste the script output (no separate explanation needed). Hit same-feature spec / features $\rightarrow$ modify the original per `workflow/README.md` "same-feature continuation" instead of creating new.
+3. **File the plan**: `node .agents/scripts/fill-plan.mjs --level L1 --topic <topic> --output workflow/plans/<YYYY-MM-DD>-<topic>.md`. `--lite` may be added (three sections: entry / change approach / verification and acceptance; conditions: step 2 search has no incident hits and no red line is checked); the default remains five sections. Fill in the entry (source, goal, red lines), change approach, constraints and risks, verification plan, acceptance criteria, and write the step 2 search results into the self-check. Change the frontmatter `模块` to the leading module. Do not write an intent, do not write prediction fields. Completion criterion: each section of the chosen template has a body (five sections or lite's three), the search conclusion is in the plan; if acceptance cannot be written as a testable criterion, stop; red lines are either checked and escalated to L2/L3, or explicitly unchecked.
+4. **Start after confirmation**: `node .agents/scripts/confirm-doc.mjs <plan> --delegated "<user's verbatim words>"` moves draft to approved (confirmation gate policy single-source: call per item, no combining; use each item's own verbatim words, no reuse; migrate step by step, no single hop), then change code. Only change files listed in the plan. Four red lines: do not commit secrets or `.env`, do not use `--no-verify`, minimal change, stop first when deviating from the plan. **Commitment-surface lock**: after approval, changing the "commitment surface" (acceptance criteria text / red lines / goal / change approach) requires the user to nod again and re-record the commitment-surface fingerprint — the re-confirmation password is in `workflow/README.md` "commitment-surface binding"; otherwise closeout is rejected and push is hard-blocked by check 15 (checking acceptance + backfilling evidence does not count as changing commitments). Do not commit separately after changes: once verification (step 5) is green, jump to done per step 6 and commit in the same commit as the code. Before changing code, open the /tour overview and refresh it every batch (skills/dev-tour). Completion criterion: changes remain in the working tree, and the plan is still approved.
+5. **Verify**: `node .agents/scripts/verify.mjs --scope` (policy in the header note). If there are frontend changes, also open `.agents/skills/verify-ui/SKILL.md`. If it fails, change the code; do not change the gate on this page. Completion criterion: command exit code 0, and frontend changes additionally have measured evidence.
+6. **Closeout = single commit**: `node .agents/scripts/confirm-doc.mjs <plan> --delegated "<user's verbatim words>"` jumps one more step to move approved to done, then make a single commit — plan(done) + code + confirmation shard + verify credentials land in one commit; L1 has no separate closeout commit. Only in the plan-independent-closeout scenario (code already landed in a previous commit) open `.agents/skills/shipyard-workflow-closeout/SKILL.md`. Completion criterion: the plan is done and the single commit has landed.
+
+Only then open other files: delegate implementer → `stages.md` Build §3; changed DB connection → `stages.md` Test §2; full-suite first run red, isolated rerun green → `stages.md` Test §1; L2/L3 independent review → `stages.md` Test §4.
+
+## 2. Level Sub-Routing (Pointer Only)
+
+Task-type routing **single source** = root `AGENTS.md` §4. Fix-type level routing **single source** = `.agents/commands/maintain.md` §3 (after L1 files the document, return to this page §L1 Fast Track; L2/L3 go to `stages.md` Design → Build → Test chapters; if the root cause is a missing gate/rule, file a same-named intent separately).
+
+## 3. Intent Exemption Rules
+
+| Scenario | Criterion | Handling |
+|---|---|---|
+| **AI-Native engine surface** | Root `AGENTS.md` §4 engine-surface exemption policy | Exempt from the trio (intent/spec/plan and confirmation gates); commit directly with Conventional Commits; parts touching business code follow their level |
+| **wiki document adjustment** | Root `AGENTS.md` §4 "wiki exemption" | Exempt from the trio (intent/spec/plan and confirmation gates); commit directly with `docs(wiki)`; execution of data-maintenance SQL and business code are not exempt |
+| **bootstrap-type changes** | Introducing the rules themselves | Exempt from intent; explicitly declare `bootstrap` in the commit message |
+
+## 4. Closed-Loop Backstop
+
+- **Gate checklist**: refer to the header comments of `.githooks/` / `.agents/hooks/` / `.agents/scripts/check-loop.mjs` (not restated here).
+- **hard-block**: checklist single source = check-loop header comment; pairing breaks and loop gaps have been downgraded to WARN; self-check goes through closeout skill §0.
+- **Prohibition**: local hooks are local machine gates; `--no-verify` is prohibited (see root `AGENTS.md`).

package/locales/en/overrides/.agents/commands/pipeline-run.md

@@ -0,0 +1,56 @@
+---
+description: pipeline-run automated driver entry — single command drives the six-stage closed loop (work-order protocol + machine gates + verbatim recording); mutually exclusive with manual stage routing, do not mix
+stage: entry
+triggers:
+  - "pipeline-run"
+  - "run the executor"
+  - "run fully automated"
+approval_required: true
+fallback: the main agent personally fills the AI slot (work orders are completed by the main agent, with no dependency on subagents)
+next: loop and advance to done according to the run's stop points
+---
+
+# pipeline-run · Fully Automated Closed-Loop Executor Entry
+
+The stage machine is aligned with the commands manual. Mutually exclusive with manual stage routing; do not mix.
+
+> **Reserved for later use**: currently zero runs (`cache/pipeline-runs/` empty) but not retired; before enabling, run a small task once to validate the state machine.
+
+> **Division of labor**: deterministic parts are driven by the `pipeline-run.mjs` state machine (fill-* $\rightarrow$ confirm-doc $\rightarrow$ verify.mjs $\rightarrow$ git, all exit codes recorded); the AI slot executes per the work-order protocol; human gates stop on arrival and their words are recorded verbatim; the host must not change state on its own.
+
+## 1. Protocol
+
+**Input**: raw requirement text
+**Process**:
+1. **Start**: `node .agents/scripts/pipeline-run.mjs start "<raw requirement text>"` (may pre-judge and add `--hint "kind=… level=… module=…"`)
+2. **Loop reading stop points**: the last stdout line is the machine marker `PIPELINE-STOP <type> …` $\rightarrow$ branch by type:
+
+| Stop type | Action | Re-run command |
+|---|---|---|
+| `work-order <runId> <work-order id>` | Read the full work order $\rightarrow$ **work by the order** (see the table below) | `next` (implement/fix requires `--files "a,b"`) |
+| `await-confirm <runId> <doc>` | **Human gate**: relay key points and request confirmation $\rightarrow$ after the user gives the go-ahead | `next --delegated "<user's verbatim words>"` (verbatim words) |
+| `gate-fail <runId> <stage>` | Read the problems reason $\rightarrow$ fix, then rerun the same path | `next` (no gate bypass / no `--no-verify`) |
+| `done <runId>` | Report a summary (stage bar / gate count / commit chain) | Flow ends |
+| `aborted <runId>` | Report the abort state and archive location | Flow ends |
+
+### Work-Order Type Execution Matrix
+
+| Work-order type | Execution requirement | Load on entry (coupled, see new-task §1c) |
+|---|---|---|
+| **triage** | Grade and backfill `next --triage "kind=… level=… module=… topic=<English kebab>"` (choose the higher level when unsure) | None; kb search same as new-task §L1 Fast Track step 2 |
+| **draft** | Draft the specified document | intent→`grilling`; spec→`stages.md` Design §2 "Required Inputs" + `grilling` (branch comparison `arena`); plan→none |
+| **implement / fix** | Implement per the authorized files $\rightarrow$ **stop on deviation** (public interface / unplanned files / new dependencies $\rightarrow$ stop and report, do not self-approve) | No mandatory skill; for fix-type with an unclear root cause, run `why` first |
+| **review / closeout** | Produce per the order and write to the specified location (after review-only reporting, finish with `--done`) | review→`review-method` (high-risk diff +`interrogate`); closeout→`shipyard-workflow-closeout` (§0 closeout self-check) |
+
+3. **Abort**: the user explicitly declines $\rightarrow$ `abort --run <id> --to superseded|cancelled --delegated "<verbatim words>"` (approved documents go through confirm-doc --to one by one)
+4. **Observe** (optional): `status [--run <id>] [--json]` full event stream / `watch` terminal polling view
+
+## 🚫 Hard Discipline (violation breaks the protocol)
+
+| Operation | Consequence / machine behavior | Exception |
+|---|---|---|
+| Directly modify workflow status | $\rightarrow$ bypasses the only migration entry (confirm-doc) | The host never edits frontmatter directly |
+| Fabricate/reuse verbatim words | $\rightarrow$ exposed by cross-check against the ledger `confirmations.jsonl` | `--delegated` must be the current conversation's verbatim words |
+| Advance while broken | Fix loop exceeds the limit (3 times), stop and hand over to a human | Do not close out while verify is not green |
+| Write run files | $\rightarrow$ conflicts with machine facts | The host is read-only |
+| Auto-approve human gates | `await-confirm` must relay key points and only `next --delegated` after receiving the user's verbatim go-ahead | Auto-triggering only means stage chaining and skill loading (new-task §1c coupling protocol); human gates are never crossed automatically |

package/locales/en/overrides/.agents/commands/pr-review.md

@@ -0,0 +1,30 @@
+---
+description: PR panel review — multiple subagents find bugs + independent voting + ledger
+stage: review (cross-cutting)
+triggers:
+  - "review this PR"
+  - "run the PR panel review"
+  - "pr-review"
+---
+
+# PR Review · Panel Review
+
+## Trigger Rules
+
+If any one is met, run the panel review; if none are met, use the graded review in `.agents/commands/review.md`; do not run the panel:
+- The diff touches a trust boundary / data surface / public contract
+- Before merging to main
+- Hard regressions requiring multi-lens cross-validation
+
+## Flow
+
+Script: `.agents/scripts/pr-review.mjs` (subcommand details via `--help`). Execute in order; do not skip steps:
+
+1. `plan --base <ref> --head <ref>`; for high-risk quick checks add `--fast` (single-lens tier). Artifacts land in `.agents/tmp/pr-review/<runId>/` (run.json / briefs / tasks.json)
+2. Dispatch finder / verifier subagents in parallel per `tasks.json`; role contracts in `.agents/roles/pr-finder.md`, `pr-verifier.md`, `pr-adjudicator.md`
+3. Execute in order: `collect` → `verify` → `adjudicate` (escalated items) → `dispose` → `summary`
+
+## Ledger
+
+- Write the ledger artifact + a monthly line to `workflow/reviews.d/` (append-only).
+- For PRs that have run a review, append one line to the PR Evidence: `面板评审：<runId>（Important n / Nit n / Pre-existing n）`.

package/locales/en/overrides/.agents/commands/review.md

@@ -0,0 +1,93 @@
+---
+description: "Code review standard (graded by risk: machine backstop + AI self-check produces the list, the user decides classification and merge)"
+stage: review (cross-cutting: used before merge, not one of the 6 stages)
+triggers:
+  - "review it"
+  - "go through the review standard"
+  - "run through the review standard once"
+delegation:
+  - role: independent-reviewer
+    instructions: .agents/roles/independent-reviewer.md
+    when: machine gates are complete and the review target and diff baseline are fixed (L2 / L3 mandatory independent review: independent subagent or new session; cannot fall back to main-agent self-check)
+    required: true
+approval_required: true
+next: while P0/P1 are uncleared, L1 → .agents/commands/new-task.md §L1 Fast Track to change code; L2/L3 → .agents/commands/stages.md Build chapter. After clearing, merge with user confirmation
+---
+
+# Review · Graded Review
+
+> **Three-way division**: machine gates block automatically (no human guard needed) $\rightarrow$ AI review produces a graded list $\rightarrow$ the user classifies/merges; they may not substitute for each other (AI may not make the merge decision, the user may not be judged on their behalf).
+> **Independence**: L2/L3 must use an independent subagent or a new session; the original author's self-check may not masquerade as one.
+
+## P0 Must-Block (Block)
+
+| Check item | Criterion (Invariant) | Machine backstop | AI self-check |
+|---|---|---|---|
+| **Architecture red line** | Layered dependency direction constraints (domain/application layers must not reference infrastructure implementations) | `.agents/hooks/` architecture gate | References outside the exemption list |
+| **Audit fields** | Public audit fields are written automatically by shared infrastructure; business code must not write them by hand | Audit-field gate (compares newly added values) | None |
+| **Deletion interception** | Before deleting, check child/business references; when referenced, error per the shared policy | Deletion gate (call sites vs allowlist) | Verify delete-time reference checks at each call site |
+| **Input validation** | Required-field null checks, range validation, illegal input rejected per the shared policy | Project validation tests | Self-check coverage blind spots |
+| **L2/L3 without spec** | Reject; first return to `workflow/specs/` to file and confirm a spec | `confirm-doc` →done gate (L2/L3 intent must have a same-named confirmed spec) | None |
+
+## P1 Should-Block (Self-check)
+
+| Check item | Criterion (Invariant) | Note |
+|---|---|---|
+| **DB naming and migration** | Follow table/field/foreign-key naming conventions and the schema change process | Do not introduce an unused migration mechanism arbitrarily |
+| **Frontend form** | New/edit and large-volume selection follow component conventions | Overlay vs page navigation, selector form, table style |
+| **Forms** | Submit after normalizing empty values for optional fields | Do not change backend DTOs to evade validation |
+| **State management** | Store calls the API; components call only the store | None |
+| **API input boundary** | Write operations must not bind domain entities via `[FromBody]` (always DTOs) | Input DTOs must not contain primary keys or audit fields |
+| **Import trust boundary** | Import endpoints fully re-validate server-side; never trust the client | Parse failures go into the error-row summary; never silently drop |
+| **Create/Update same policy** | Create validation must apply the same policy to Update | Referenced identifier fields must not be changed |
+| **Pagination and state semantics** | Pagination parameter range validation + service-layer clamping | Separate illegal state from non-existent (400/404) |
+| **Spec commitment landing** | spec §test cases must actually land in tests or verification scripts | Persistent assertions must not be written as row-count constants that grow over time |
+| **Thin-adapter drift** | Host `agents/`, `commands/` remain pointer shells; the body lives only in `.agents/roles/` and `.agents/commands/` | Manually verify shells reference the authoritative paths and the body is not too thick |
+| **Impact-surface proof** | For a small diff, "safe because X" must be proven by running code, not by assertion | Follow `.agents/skills/blast-radius/SKILL.md`; proof scripts ship with the PR or land in `tmp/` |
+
+## P2 Advisory (Advisory)
+
+- Comment completeness (add comments at complex logic)
+- Conventional Commits in Chinese (feat / fix / docs / style / refactor / perf / chore)
+- Whether the retrospective trio for historical incidents of the same kind is complete
+- **Purely stylistic issues are discarded outright and not listed as P2**; only "naming/comments that cause wrong calls or contract misreading" are reported as behavioral issues.
+
+## Process
+
+**Input**: diff to review + fixed baseline (SHA/branch)
+**Process**:
+1. **Machine gates**: pre-commit / pre-push / `stages.md` Test static gates all pass (no human guard needed)
+2. **AI review**: delegate `independent-reviewer` $\rightarrow$ focus on items not covered by P0 + all P1 (P2 subject to capacity); independence, persistence, and cross-model policy follow `.agents/roles/independent-reviewer.md` "Review Policy" (this section's scenario = merge review; not restated here)
+   - **Method**: `.agents/skills/review-method/SKILL.md`
+   - **False-positive prevention**: every finding goes through `review-verification-protocol`
+   - **Model selection**: take `model-roles.json` (local override `.local.json` takes precedence; both empty = host default); cross-model ladder and downgrade follow `.agents/roles/independent-reviewer.md` Constraints. Before switching models, run 3 already-classified bug regressions per `delegations.md`
+   - **High-risk diff**: additionally apply `.agents/skills/interrogate/SKILL.md` (does not replace the single independent review above)
+3. **User decision**: issue classification (reject as false positive / P0 must-fix / P1,P2 discretionary) + merge timing
+**Output**: graded issue list + fix suggestions $\rightarrow$ user confirms merge
+**Next**: while P0/P1 are uncleared, L1 returns to `.agents/commands/new-task.md` §L1 Fast Track to change code; L2/L3 return to `stages.md` Build chapter. After clearing, merge with user confirmation.
+
+## PR Panel Review (pr-review, created 2026-11-06; automated gate retired 2026-11-09)
+
+> The panel is retired as a **manual tool** (owner instruction): pre-push / CI / pr-create no longer enforce a review ledger; the trigger policy follows `.agents/commands/pr-review.md`. The tiers Important/Nit/Pre-existing and the discard-purely-stylistic policy are unchanged.
+
+## PR Body Trio (Merge Narrative Convention)
+
+When opening a PR, the body has three fixed sections, each answering one merge-decision element and none may be omitted (Azure DevOps has no skill hook, so this section is the single source for the convention):
+
+| Section | Answers | Format |
+|---|---|---|
+| **Summary** | What change is this | 1-4 items: why change, what changed, pointing at key modules/files — must come from the actual diff; write actual behavior, not intent rhetoric |
+| **Evidence** | Where is the evidence | Actually run tests/builds/manual verification (Before/After contrast: red-before/green-after test pairs, same-viewpoint before/after screenshots); attach green credentials or measured-evidence paths that can be opened and re-checked; if not run, explicitly write "not run" and why; fabrication is prohibited. When a panel review was run, append one line: `面板评审：<runId>（Important n / Nit n / Pre-existing n；全部 fixed/waived/deferred/recorded）` |
+| **Merge Danger** | How big is the risk | **Door**: impact surface (API / DB / config / permission / compatibility), write "none" if no risk, do not omit; **Blast Radius**: one word (local / module / global); **Rollback**: rollback method and risk, required |
+
+If size exceeds budget (pre-push advisory; override requires `PR_SIZE_OK=1` and a reason in Tradeoffs), the diff is large, overlap is non-empty, or the change is irreversible → add a **Tradeoffs** section to the body: real diff size + why it is still done this way.
+
+If you cannot write "Door=none + local", this triggers one grading re-check.
+
+> Distribution skills (e.g. `tfs-pr`) come with an identical template; that is their **default for hosts without this convention**; this repository follows this section.
+
+## 🚫 Prohibitions
+| Operation | Consequence / machine behavior | Exception |
+|---|---|---|
+| L2/L3 main-agent self-check | $\rightarrow$ independence fails | Must delegate `independent-reviewer` or a new session |
+| Merge with P0 uncleared | $\rightarrow$ blocked | Must be zeroed and confirmed by the user |