agentic-flow-kit 1.8.7 → 2.1.0

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

@@ -0,0 +1,256 @@
+---
+description: "L2/L3 staged flow (four-in-one): Plan files intent → Design drafts spec → Build drafts plan + implements code → Test static gates + UI verification + review + closeout; L1 uses the new-task.md fast track"
+stage:
+  - Plan
+  - Design
+  - Build
+  - Test
+triggers:
+  - "start an intent"
+  - "file an intent"
+  - "start a spec"
+  - "continue with the spec"
+  - "intent reviewed"
+  - "walk through the spec"
+  - "start a plan"
+  - "spec is fine"
+  - "start writing"
+  - "get to work"
+  - "plan is good"
+  - "run verify"
+  - "changes done"
+  - "run verify and see"
+  - "verify it"
+delegation:
+  - role: independent-reviewer
+    instructions: .agents/roles/independent-reviewer.md
+    when: L2 / L3 spec draft complete and before user confirmation (Design §3); L2 or L3 changes complete and diff fixed (Test §4)
+    required: true
+    attach:
+      - acceptance criteria of the same-named spec
+      - fixed git range: git rev-parse <baseline> resolves, and git diff <baseline>...<HEAD> is non-empty
+      - level is L2 or L3
+      - new session, not the same context as the implementation
+      - conclusion's first line is `reviewed by <model name>`
+      - persistence line written by the main agent into the document's "Confirmation and Review" per .agents/roles/independent-reviewer.md
+      - do not modify any repository file
+  - role: ui-verifier
+    instructions: .agents/roles/ui-verifier.md
+    when: UI changes involved and static gates have passed
+    required: true
+    fallback: main
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: plan and change-file list both confirmed, and the work-package boundary meets the role contract
+    required: false
+    fallback: main
+approval_required: true
+next: chapter order Plan → Design → Build → Test; after Test, L2/L3 merge (PR review merge) → .agents/commands/deploy.md; L1 → .agents/commands/new-task.md §L1 Fast Track
+---
+
+<!-- 2026-11-08 tier 2-F four-in-one (formerly plan/design/build/test.md), see git for history -->
+
+L1's filing, implementation, verification, and closeout are all in `.agents/commands/new-task.md` §L1 Fast Track; this file's four chapters Plan → Design → Build → Test serve only the L2/L3 staged flow. L1 opens it only when Plan §1 finds an existing same-named in-flight document, to align progress, then returns to the fast track.
+
+# Plan · L2/L3 File Intent
+
+The level is already set by `new-task.md`; this chapter branches by level and must not re-grade.
+
+## 1. Admission and Shortcuts
+**Input**: user's raw requirement text + already-assigned level
+**Process**:
+1. **Shortcut check (also session re-entry, session-context)**: L1 checks whether `workflow/plans/` already has a same-named plan; L2/L3 checks whether `workflow/intents/` already has an approved intent. Existing and **terminal** → jump per `next`; existing and **in flight** (draft/approved, checked ≠ complete) → this is re-entry, not a new creation: read the plan's check states and `git status` to align subsequent work, do not file a new document. L1 returns to the fast track and does not enter the Build chapter.
+2. **Similar-case search**: `node .agents/scripts/kb-search.mjs "<keyword>" --scope workflow --type intents,plans,specs` $\rightarrow$ on a same-kind hit, read the conclusion and acceptance criteria first
+**Output**: confirmed no same-kind entry / existing approved entry
+
+## 3. L2/L3: Draft Intent
+**Process**:
+1. **Generate draft**: `node .agents/scripts/fill-intent.mjs --module <module> --level <L2|L3> --topic <topic> --output workflow/intents/<date>-<topic>.md --notes "<note>"`
+2. **Fill in**: background and problem / historical lessons and recurrence prevention / goals / non-goals / constraints / impact surface / touched red lines / acceptance criteria
+3. **Red-line check**: against root `AGENTS.md` and directory-level `AGENTS.md`. If not touched, do not check.
+**Output**: `workflow/intents/{name}.md` (Status: Draft)
+**Next**: Design chapter
+
+## 4. Confirmation and State Transition
+**Process**:
+1. **HALT**: output the full draft $\rightarrow$ wait for user confirmation
+2. **Status transition**: $\text{draft} \rightarrow \text{approved}$ (policy per `new-task.md` Fast Track step 4)
+3. **Trace commit**: L2/L3 immediately commit separately as `docs(workflow)`; **L1 single commit** — after verification is green, jump to done; plan(done)+code+confirmation shard+credentials land in the tree in the same commit, with no separate closeout commit (policy single source `new-task.md` Fast Track steps 4/6).
+**Next**: L1 $\rightarrow$ `.agents/commands/new-task.md` §L1 Fast Track / L2,L3 $\rightarrow$ Design chapter
+
+## 🚫 Prohibitions
+| Operation | Machine behavior | Exception |
+|---|---|---|
+| Force-check red lines | check-loop judges "red-line under-grading" | Must be actually touched to check |
+| Force-fill criteria | Acceptance criteria untestable | If unclear, must HALT and clarify |
+| Directly edit status | Status transition disabled | Must go through `confirm-doc` |
+
+## 🛠️ Auxiliary Tools
+- **Requirement grilling**: `grilling` (backfill the 6 sections after answering)
+
+# Design · Draft Spec
+
+## 1. Admission and Level Judgment
+**Input**: `workflow/intents/{name}.md` (Approved) or a confirmed incident draft. Level is L2 or L3.
+**Process**:
+1. **L1 forbidden in this stage**: on encountering L1 $\rightarrow$ **HALT** $\rightarrow$ return to `.agents/commands/new-task.md` §L1 Fast Track. This stage drafts only L2/L3 specs
+2. **Pre-check**: if the entry document has not passed the confirmation gate $\rightarrow$ **HALT** $\rightarrow$ return to the Plan chapter / `maintain.md` (exit 2)
+3. **Level determination** (against `new-task.md` two questions):
+   - **L2** (rule/contract): must draft a spec $\rightarrow$ **mandatory independent review** (independent subagent or new session)
+   - **L3** (structure/Schema): must draft a spec $\rightarrow$ **mandatory independent review** (same as above, cross-model preferred)
+**Output**: determined design level (L2/L3)
+
+## 2. Draft Spec
+**Input**: selected level + entry document
+**Required inputs (complete before drafting; missing any one means HALT and return to this section to read; comparison results go into "Constraint Compliance Mapping" and "Assumptions and Inferences")**:
+1. Search `wiki/INDEX.md` for task documents related to this topic (product requirements / development plans / project rules / data dictionary / user features) — on a hit, read fully and write the basis into the relevant spec sections as path references (the source of the policy for feature behavior / data flow); if no hit, state the search terms and conclusion
+2. The full text of `backend/AGENTS.md` (§6 hard constraints / §7 machine-gate checklist) — **regardless of whether this change touches the backend**
+3. The full text of `frontend/AGENTS.md` (gates G-2~G-3 / contract rules / list-page state rules)
+**Process**:
+0. **Check before creating**: if a same-feature spec already exists (including archived) / `verify-ui/features` $\rightarrow$ revise the original, do not create new (single source `workflow/README.md` "same-feature continuation")
+1. **Generate draft**: run `node .agents/scripts/fill-spec.mjs --level <L2|L3> --topic <topic> --output workflow/specs/<date>-<topic>.md`
+2. **Fill in content**: copy `_TEMPLATE.md` $\rightarrow$ fill in [feature behavior / data flow / system changes / constraint compliance mapping / risk assessment]
+3. **Constraint check**: against red lines in root `AGENTS.md` and directory-level `AGENTS.md`, explain how each is satisfied
+4. **Interaction confirmation**: explicitly mark the entry form (form/selector/dialog); do not presume
+5. **Entry verification**: [frontend-specific] search button events $\rightarrow$ trace router/Drawer $\rightarrow$ locate the actual rendering file $\rightarrow$ mark **entry evidence (file+line)** in the "System Change List"
+6. **Solution tradeoffs**: with multiple solutions $\rightarrow$ list [solution comparison table (tradeoff + recommendation)] $\rightarrow$ **HALT** $\rightarrow$ user selects. When branches are real and reasoning cannot decide (contract shape / data flow / performance tradeoff), first open **2 parallel solution routes** (a subagent per solution, read-only on the repository, output into the conversation or `tmp/`, no repository file changes), compare per "solution | key tradeoff | risk | evidence"; cap at 2 routes, do not run when reasoning can decide, and do not consume implementation-surface delegation concurrency
+7. **Ambiguity scan**: write an "ambiguity checklist", one line per 6 dimensions — state and boundaries / data policy / failure paths / contract symmetry / existing data / acceptance testability. Column order `dimension | conclusion | basis | status`.
+   - Experimentable $\rightarrow$ experiment first, write the experiment result as the basis, **do not ask the user**.
+   - Cannot be decided by experiment $\rightarrow$ status `待澄清` (to be clarified), ask in the current round.
+   - Upper bound: ≤2 lines per dimension, ≤12 total, ≤5 questions per round.
+   - Inferential conclusions $\rightarrow$ record separately in "Assumptions and Inferences".
+   - Missing section / missing dimension / 待澄清 ≠ 0 / empty basis / out of bounds → confirmation gate rejects.
+8. **Premise interrogation**: write a "premise interrogation" table — list the interpretive premises on which the spec's argument rests (e.g. "display need vs storage rewrite"), counter-question the opposing interpretation for each, and write the chosen basis; for small items with no interpretation risk, write one line "no key premises" + reason. Missing section / empty table / placeholder / missing counter-question or missing basis → confirmation gate rejects (anchored at premiseSince; the plug for the 10-23 identity-overwrite three-layer same-source failure)
+**Output**: `workflow/specs/{name}.md` (Status: Draft)
+
+## 3. Independent Review (L2/L3 Mandatory)
+L2/L3 mandatory: delegate `independent-reviewer`; trigger, form, required inputs, and persistence policy follow `.agents/roles/independent-reviewer.md` "Review Policy" (not restated here)
+**Output**: review failed $\rightarrow$ return to §2 to revise the spec
+
+## 4. Confirmation and State Transition
+**Process**:
+1. **HALT**: output the full spec $\rightarrow$ wait for user confirmation. Before confirmation, self-check the ambiguity checklist and premise interrogation: 待澄清 zeroed, 6 dimensions complete, every line has a basis, premises have counter-questions and chosen bases (otherwise the transition is rejected)
+2. **Status transition**: $\text{draft} \rightarrow \text{approved}$
+3. **State entry point**: run `node .agents/scripts/confirm-doc.mjs <path>` (policy per `new-task.md` Fast Track step 4, not restated here)
+4. **Trace commit**: immediately commit separately as `docs(workflow)`
+**Next**: Build chapter
+
+## 🚫 Prohibitions
+| Operation | Consequence / machine behavior | Exception |
+|---|---|---|
+| Routing guesses the entry | → whole-round rework | Must provide measured evidence with file+line |
+| Presuming interaction | → UI does not match requirements | Form must be confirmed by the user |
+| L3 self-check masquerade | `.agents/skills/shipyard-workflow-closeout/SKILL.md` §0.3 HALT. check-loop only WARNs on missing review context | Must be executed by `independent-reviewer` |
+| Passing the confirmation gate with "待澄清" unresolved | `confirm-doc` rejects (ambiguity unresolved, exit 2, no persistence, no accounting); missing dimension / empty basis also rejected | Ask the user for a decision before transitioning |
+| Premises entering the fact source without interrogation | `confirm-doc` rejects (premise interrogation missing section / empty / placeholder / missing counter-question or basis, exit 2) | If there is no interpretation risk, write a "no key premises" line with a reason |
+| Asking the user about experimentable items | Extra round of confirmation tax, and the answer is obtainable by running | Query DB / run eval / prototype first; write the experiment conclusion as the basis |
+| "Decided" without writing a basis | `confirm-doc` rejects (equivalent to not having thought) | The basis must be identifiable (section number / code path / DB query result) |
+| Skipping required inputs / constraint mapping missing backend/frontend AGENTS entries | → independent review rejects and reworks (a missing mapping source counts as not doing the constraint check) | The two directory specs are the repository-wide contract baseline, independent of this change's surface; wiki no-hit may exempt item 1 (must state the search terms) |
+
+# Build · Draft Plan + Write Code
+
+L1 does not draft a plan in this chapter; return to `.agents/commands/new-task.md` §L1 Fast Track step 4; this chapter is only for L2/L3 implementation, or delegating implementer (§3), handling plan deviations.
+
+## 1. Draft Plan
+**Input**: `workflow/intents/{name}.md` (Approved) + `workflow/specs/{name}.md` (Approved)
+**Process**:
+1. **Create document**: copy `_TEMPLATE.md` $\rightarrow$ `workflow/plans/{name}.md`, fill in the change approach / task breakdown (each step with "files" and criteria) / execution order / verification plan
+2. **HALT**: output the just-drafted full plan $\rightarrow$ wait for the user's item-by-item confirmation.
+**Output**: `workflow/plans/{name}.md` (Status: Approved)
+**Gates**:
+- **Confirmation gate (confirm-doc)**: $\text{draft} \rightarrow \text{approved}$ (policy per `new-task.md` Fast Track step 4)
+- **Basis**: `workflow/papercuts.md`
+
+## 2. Enter Plan Mode and List Changes
+**Input**: `workflow/plans/{name}.md` (Approved)
+**Process**:
+1. **Pitfall search**: `node .agents/scripts/kb-search.mjs --scope workflow --module <module> "<keyword>"` $\rightarrow$ extract incident root causes into self-check items
+2. **List**: specify the [read-then-modify/new] file list + [action $\rightarrow$ object] execution steps
+3. **Sync audit**: when changes hit `.agents/commands/` or `.agents/roles/`, change only the authoritative source body; host shells stay pointers (see §🛠️ Auxiliary and Sync)
+4. **Red-line check**: against root `AGENTS.md` and directory-level `AGENTS.md`, mark touched red lines
+5. **Generate overview + start dashboard**: first `node .agents/scripts/gen-dev-tour.mjs workflow/plans/{name}.md --strict` to pass the per-step file gate (implementation steps missing `- 文件：` are rejected; pure verification steps are marked "验证步骤"), then `node .agents/scripts/auto-tour.mjs workflow/plans/{name}.md` to start the dashboard (idempotent, failures only warn). For snapshots, run gen-dev-tour separately; verify "actual changes outside the document", backfill/rollback out-of-bounds first; policy see dev-tour/SKILL.md. Layer fallback (defaults to 0) = heading contract violation, regenerate after normalizing
+6. **HALT**: output the change list $\rightarrow$ wait for user confirmation
+**Output**: confirmed change list $\rightarrow$ **backfill into the plan's "change surface/task breakdown"** (session-context: conversation traces are for the current session only; on re-entry the plan is authoritative — change surface + task check state + git status = the three session re-entry anchors). **After persisting, rerun `node .agents/scripts/auto-tour.mjs workflow/plans/{name}.md`** — the real purpose is to ensure the dashboard process is running (idempotent, reuse if already running); if running, the live page redraws automatically (SSE push + 5s fallback polling), and the persisted change surface enters the graph
+
+## 3. Implementation and Self-Verification
+**Input**: `workflow/plans/{name}.md` (Approved, including the persisted change surface and task list)
+**Process**:
+1. **Session re-entry** (mandatory for compaction / new session / handover continuation): read the plan task list check states + compare with `git status` / `git diff` on the ground $\rightarrow$ rebuild progress then continue. If check states do not match the working tree (checked but uncommitted / committed but unchecked) $\rightarrow$ align first, then write new code; when the change list exists only in the conversation, use the plan change surface + working tree as authoritative and backfill the plan
+2. **Drive implementation**: execute tasks by dependency — **frontier = tasks whose "dependency" line has no unresolved blocker**, dispatched in parallel (multiple worktrees with their own branches / delegating "new + merge scope"), a pure sequential chain goes top-down; **immediately backfill the task list checks and traces after each item completes** (commit SHA / test name / measured output), and unlock downstream tasks that depend on it (after each item, refresh `/tour?file=workflow/plans/{name}.md`, confirming there are no "actual changes outside the document"). When the `.agents/roles/implementer.md` boundary is met, `implementer` may be delegated (model from `model-roles.json`, local override preferred, both empty = host default)
+3. **Architecture constraints**: strictly forbid inventing bypass data access; must follow root/directory-level `AGENTS.md` red lines
+4. **L3 special case**: schema changes must follow the project's agreed maintenance method; do not introduce a migration mechanism arbitrarily
+5. **Change control**: if a plan deviation is needed (change public interface / touch unlisted files / add new dependency) $\rightarrow$ **HALT** $\rightarrow$ continue after confirmation
+6. **Self-verification loop**: run [project build / type check / automated tests] (details in Test chapter §1); scope reconciliation `node .agents/scripts/check-scope.mjs workflow/plans/{name}.md` — out-of-bounds items must be closed out (backfill the plan or roll back); **L2/L3 must pass with `--strict` before closeout**, L1 stays advisory (at push time, check-scope-range hard-blocks by old..new range)
+**Output**: implemented code changes + self-verification pass evidence
+
+## 4. Wind Down After Confirmation
+**Process**:
+1. **Status transition**: the plan stays `approved`, not set to `done` here. Closeout happens in Test chapter §5, set to `done` via confirm-doc.
+2. **Commit trace**: intent/spec are committed separately as `docs(workflow)` after design confirmation. The plan is likewise committed separately after confirmation, not in the same commit as code. Conventional Commits in Chinese.
+3. **Scripted rewrite**: to modify workflow documents or ledgers, use `node .agents/scripts/rewrite-file.mjs <file> --find <literal string> --replace <literal string>`. Prohibit `node -e` with `writeFileSync` (on CRLF checkouts it silently does nothing yet prints success).
+**Next**: Test chapter
+
+## 🚫 Prohibitions
+| Operation | Machine behavior | Exception |
+|---|---|---|
+| Directly edit frontmatter | Status transition disabled | Must go through `confirm-doc` |
+| draft $\rightarrow$ done | check-loop 15 blocks | Must pass through approved |
+| Summary confirmation | confirm-doc rejects | Must review the full text |
+
+## 🛠️ Auxiliary and Sync
+- **Hosts are pointer shells**: when changing `.agents/commands/` or `.agents/roles/`, do not copy the body into opencode / trae / codebuddy. Shells keep only host frontmatter and state the authoritative path. The machine check only covers the five check-loop hard sections, not host shells; manually verify whether shells are disconnected/too thick.
+- **Change-surface discipline**: the plan change surface lists authoritative source paths. If host shells are unchanged, do not write `wf-*.md` into the change surface.
+- **Self-check**: after changing check-loop, run `node .agents/scripts/check-loop.mjs`
+
+# Test · Static Gates + UI Verification
+
+This chapter is for L2/L3, DB-switch smoke tests, flaky, and independent review.
+
+## 1. Static Gates
+**Input**: code changes to verify
+**Process**:
+1. **Run gates**: `node .agents/scripts/verify.mjs` (tier policy per the verify.mjs header note, not restated here). The single source for project build, test, and type-check command lists is `.agents/hooks/commit-check.config.json`.
+2. **Failure handling**: any failure $\rightarrow$ **HALT**. L1 returns to `.agents/commands/new-task.md` Fast Track step 5 to change code. L2/L3 return to the Build chapter to fix. For intermittent/cross-layer issues use `diagnosing-bugs` diagnosis. A full-suite first run red with an isolated rerun green does not count as green: file it as flaky (papercut/incident) and fix it; do not close out just because a rerun is green.
+3. **Tier by task subtype**: pure docs/business surface → default tier (product gates cut by diff surface); cross-surface or before release → `--full`. The engine surface has no test gate; `*.test.mjs` is not checked in and does not run automatically (cleared 2026-10-29); manual tool — merge-semantics probe `node .agents/scripts/check-loop-rev-semantics.mjs` (runs automatically at the end of FULL mode).
+**Output**: static-gate all-green evidence
+**Note**: runtime environment details in `.agents/notes/runtime-env.md` §1, §2; for long gate commands (verify full / `dotnet test`) **wait in segments + report progress per segment**, do not block to the timeout limit — policy in §6.4 "retrieving results of long background tasks"
+
+## 2. DB Smoke Test
+**Trigger**: changed the project DB connection config or added a target database
+**Process**:
+1. **Schema comparison**: actual target-DB schema $\leftrightarrow$ code expectation (recent change scripts + base tables)
+2. **Endpoint liveness**: run the smoke script $\rightarrow$ verify 6 core endpoints $\text{HTTP 200}$
+**Output**: liveness pass evidence
+**Fact**: smoke script path in `.agents/notes/runtime-env.md` §6.1
+**Fail**: any non-200 $\rightarrow$ **HARD-BLOCK** $\rightarrow$ stop at this step, no deployment.
+
+## 3. UI Verification
+**Trigger**: frontend changes involved $\text{AND}$ static gates have passed
+**Process**:
+1. **Invoke skill**: use `.agents/skills/verify-ui/SKILL.md` to perform verification.
+2. **Environment config**: details in `.agents/notes/runtime-env.md` §4 and §6.3
+**Output**: UI verification report (screenshots/DOM evidence)
+
+## 4. Independent Review (L2/L3 Mandatory)
+1. **Delegate review**: hand to `independent-reviewer` (must attach the role's `attach` from the file header; missing any one means do not dispatch; this section's scenario = independent review before closeout). Trigger, form, review package, persistence, opinion-level ledger, and cross-model policy follow `.agents/roles/independent-reviewer.md` "Review Policy" (not restated here)
+2. **Review classification**: based on the review opinions $\rightarrow$ adopt $\rightarrow$ return to the Build chapter to modify $\rightarrow$ rerun this stage
+**Output**: review conclusion (Approved / Reject) + opinion-level ledger line; signature and persistence policy per the role's "Review Policy"
+
+## 5. Closeout After Confirmation (Closure)
+L1 closeout is the single commit in `.agents/commands/new-task.md` Fast Track step 6 (by default the closeout skill is not opened; it is opened only for the plan-independent-closeout scenario — policy single source new-task.md step 6); this section starts from L2/L3 new requirements and fix-type work.
+**Process**:
+1. **Verify and close out**: per `.agents/skills/shipyard-workflow-closeout/SKILL.md`.
+2. **Acceptance check-off**:
+   - **L2/L3 new requirement**: check off the intent's "acceptance criteria" one by one $\rightarrow$ backfill evidence $\rightarrow$ intent $\text{approved} \rightarrow \text{done}$
+   - **Fix-type**: verify recurrence-prevention landing $\rightarrow$ incident $\text{open} \rightarrow \text{fixed} \rightarrow \text{closed}$
+3. **Same-family cleanup**: plans with the same name as L2/L3 and fix-type work are also set to `done`. Do not leave `approved` orphans.
+4. **Trace record**: delegated tasks go into the `workflow/delegations.md` delegation results table; L2/L3 self-performed work goes into the self-performed task results table. Self-performed L1 is not written. Run `node .agents/scripts/agg-delegations.mjs --write` only after a row is written.
+5. **Opportunistic backfeed (advisory)**: if there is friction, record it in `workflow/papercuts.md`; if not, write "no candidates" in the closeout reply.
+**Next**: L2/L3 $\rightarrow$ `.agents/commands/deploy.md`
+
+## 🚫 Prohibitions
+| Operation | Machine behavior | Exception |
+|---|---|---|
+| Opportunistic code changes | Violates the Test stage definition | Must return to the Build chapter to fix $\rightarrow$ rerun Test |
+| Partial pass | `ui-verifier` report blocked | Do not mark partially passed items as passed |
+| Checking without evidence | check-loop blocks | Must provide specific evidence (screenshot/SHA/Log) |

package/locales/en/overrides/.agents/notes/pr-review-cost-discipline.md

@@ -0,0 +1,48 @@
+# Review Cost Discipline: Run the Panel Only Once, Assign Slots to Concurrent Sessions
+
+> **Retirement note (2026-11-09, owner directive)**: the automatic PR panel gate has been dismantled — pre-push / CI / pr-create no longer enforce the review ledger.
+> This page is retained as the cost discipline for **manually running the panel**; the measured fast-tier data stays on record; the orchestration entry point has moved to `.agents/commands/pr-review.md`.
+
+Source: the 2026-11-07/08 outbound header attachment delivery (four panel rounds in runs `pr-8fb73ea` / `pr-9e50909` / `pr-741f609` / `pr-6b535e0`, measured at ~2.5 hours, of which two rounds were entirely wasted). The `pr-review` script documents only "how to run"; this page documents "when to run and how many times" — **process constraints, not a repeat of tool details**.
+
+## Rules
+
+1. **One-review principle**: run the panel review for the same delivery batch **only once**. The fixed order is
+   **all fixes landed → commit → `plan` → finder/verifier → `dispose` → `summary` → push**.
+   "Review while changing" is forbidden: `run.json`'s `diffHash` binds base..head; once head changes the ledger is invalidated and the whole round must be rerun.
+2. **After receiving findings, finish all changes before reopening**: apply this round's confirmed items (`confirmed`) in one pass and commit, then start a new round against the **new head**;
+   "change one → re-review → change another" is not allowed (3 lenses per round, reduced under the 2026-11-08 tier 3).
+3. **Check the dispose verdict before deciding whether to change anything**: items marked `waived` / `deferred` / `rejected` produce no code changes;
+   do not change head for them (doing so wastes a whole round).
+4. **Concurrent sessions must use separate slots**: when multiple sessions/agents run in parallel on the same machine, each sets its own `SHIPYARD_SLOT`
+   (single source for port slots and derivation rules: `runtime-env.md` §6.1b). Sharing one slot collides on both "workspace files" and "branch HEAD";
+   head drift during a review = ledger invalidation (in this run, another session appended `a4b347a02` / `02d269a79` / `c77f50b44` on the same branch).
+5. **Engine-surface commits do not run the panel**: when the scope lands only in `.agents/` `.githooks/` `.codebuddy/` `.trae/` `workflow/` `wiki/` `docs/`
+   and root config, it is not worth starting the panel (the former pre-push engine-surface exemption was retired along with the 2026-11-09 automatic gate, and is now a manual judgment);
+   if you discover before manually starting the panel that the scope is purely engine/docs → that is a documentation task, do not run the panel.
+
+## Checklist (answer each item before starting the panel)
+
+- [ ] Are all changes for this round **already committed**? Does the working tree contain only files from other tasks unrelated to this batch?
+- [ ] Are there **no** confirmed findings still pending changes? (If yes → fix first, do not start the panel)
+- [ ] Does this session exclusively own the port slot / branch? (If not → set `SHIPYARD_SLOT` first or switch branches)
+- [ ] Does the change scope really include the business surface? (Purely engine/docs → not worth running the panel)
+
+If any item is "no", starting the panel is a waste.
+
+## Cost Facts (for judgment; measured 2026-11-08)
+
+| Action | Duration | Notes |
+|---|---|---|
+| Single-round panel finder (6 lenses; reduced to 3 lenses from 2026-11-08) | 8–27 min (measured with 6 lenses) | largest single brief 131 KB (embedded diff 80 KB + base 50 KB) |
+| Single-round panel verifier | 12–21 min | after change: 1 vote by default, +1 vote for Important/security |
+| `pre-push` local gate | before change 110–130 s / after change 15–20 s | integration tier defaults to CI (`PREPUSH_RUN_INTEGRATION=1` reproduces locally) |
+| One "re-review right after changing" rework | +15–30 min | this run wasted two rounds due to inverted ordering (~33 min) |
+| Fast-tier single-round panel (--fast; single lens, single vote, target ≤5 min) | **measured 377s** (zero repo reads: finder 2 tool calls 343s + script 34s; first run including queue 640s) | model latency is the floor; overruns above the hard cap are cut off by fast-timeout; criteria and orchestration contract: header-note fast-tier section of `.agents/scripts/pr-review.mjs` + config `fast` section |
+
+## Related Single Sources
+
+- Review panel mechanics and commands: `.agents/scripts/pr-review.mjs` (--help) + `.agents/commands/pr-review.md`
+- Confirmation gate and three-piece-set ordering: `.agents/notes/process-order-rule.md`
+- Port slots and concurrency: `.agents/notes/runtime-env.md` §6.1b (**this page does not restate the port values**)
+- Gate checkpoint overview: `.agents/notes/engine-map.md`

package/locales/en/overrides/.agents/notes/process-order-rule.md

@@ -0,0 +1,21 @@
+# Ordering Red Line: Classify First → Three-Piece Set → Confirm → Then Act
+
+Source: the 2026-11-03 process-inversion incident (incident `workflow/incidents/2026-11-03-po-pml-outbound-guards.md`; same-day entry in `workflow/papercuts.md`). `new-task.md` keeps only a one-line pointer on its first screen; the body details live here.
+
+## Rules
+
+1. **Before acting**, run the two-question classification in `new-task.md` §1 (structural surface → L3; contract or shared convention → L2; neither → L1). When multiple defects are reported at once, **classify each item and take the highest**.
+2. If L2 / L3 is hit: first land a document in `workflow/incidents/` (defect type) or `workflow/intents/`, then `spec`, then `plan`, and **only after `confirm-doc` passes for each document in turn may code be changed**. L1 must also have a plan first (with explicit criteria).
+3. **No "change first, document later"**: the confirmation gate means "the plan the user approved must exist before the implementation". Backfilling documents afterwards cannot restore the time order = bypassing the confirmation gate; if it happens, it must be registered in both the incident's "gate-failure analysis" section and `workflow/papercuts.md`, and called out in the commit message.
+4. When classification is uncertain, default to **treating it as one level higher and documenting first**; do not write code first and backfill the level afterwards.
+
+## Why the document-status gate cannot stop this, and which gate can now
+
+- The level is a judgment, not a machine-detectable signal: the same change may be a "purely additive read-only field" (L1) or a "tightening of existing semantics" (L2), and a hook cannot infer the level from the diff.
+- The confirmation fingerprint validates only document status and the commitment surface, not the order of occurrence. If `confirm-doc` is called after implementation, the document gate still passes.
+- The machine signal for order is at commit time: `.agents/hooks/check-confirm-order.mjs` (invoked by `.githooks/commit-msg` since the 2026-11-08 tier 2-D — pre-commit cannot read the commit message; merge skipping is instead detected by the script probing the `MERGE_HEAD` status file). Staged `backend/` source, `frontend/src` vue/ts, `tests/**/*.cs`, and data-maintenance SQL must each appear in the body of a `workflow/plans/` document whose **status is approved**, or hit an exemption: (1) the L0 lane (message body contains a non-empty `L0:` line and ≤5 product files); (2) a coverage plan staged in the same batch (L1 single commit; `done` is also acceptable). A **historical** plan marked `done` does not count as coverage; `draft` does not either. squash, rebase, and cherry-pick skip this.
+- Classification itself still rests with the executor. If "change first, document later" bypasses this gate (paths not written into the plan, or commits not going through the git hook), it is still double-registered in incident + papercuts.
+
+## Reproduction trace (2026-11-03)
+
+- The implementation commit `302226b8` preceded the three-piece-set backfill in `83b7015f`; nothing blocked during check-loop (because the gate only looks at status), showing there is no machine protection on the ordering surface.

package/locales/en/overrides/.agents/notes/runtime-env.local.example.md

@@ -0,0 +1,21 @@
+# Runtime Environment Registry (machine-specific template — copy to `runtime-env.local.md` and fill in per actual conditions)
+
+> **This file is the checked-in template; the real file `runtime-env.local.md` is git-ignored — each machine registers its own, and it is not committed or shared.**
+> For the mechanics and resolution order see `runtime-env.md` §6.3. Consumers (they automatically read the "Tool" table rows at runtime):
+> 5 dwf workflows (`.zcode/workflows/*.dwf.ts`), `scripts/verify/e2e/browser-resolve.mjs`, `.agents/scripts/check-local-gates.mjs`.
+> Unregistered tools get built-in standard-install-location probing (node/dotnet/git tried candidate by candidate via `--version`, browser probed by filesystem existence);
+> **registration is only for overriding non-standard install locations** — after cloning, first run `node .agents/scripts/check-local-gates.mjs`,
+> and use its output to decide which tools need registration.
+
+| Tool | Local path | Notes |
+|---|---|---|
+| node | <example: D:/Program Files/NodeJs/node.exe> | standard install (C:/Program Files/nodejs) needs no registration |
+| npm-cli | <example: D:/Program Files/NodeJs/node_modules/npm/bin/npm-cli.js> | can be omitted: when dwf is unregistered it is derived automatically from the node directory |
+| dotnet | <example: C:/Program Files/dotnet/dotnet.exe> | standard location, no registration needed |
+| git | <example: C:/Program Files/Git/cmd/git.exe> | standard location, no registration needed |
+| bash | <example: C:/Program Files/Git/bin/bash.exe> | only needed on machines where `bash` is not on PATH; to get the exit code, run `& "<this path>" -c '…; echo EXIT=$?'` |
+| browser | <example: C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe> | only needed when the browser is installed in a non-standard location; alternatively use the env var `CHROME_PATH` |
+
+## Other machine-specific facts (for agents to read; no machine consumers)
+
+- <example: terminal defaults to PowerShell; local Chrome 83 engine too old and disabled; CPU core count and other measured facts>

package/locales/en/overrides/.agents/pipelines/_TEMPLATE.md

@@ -0,0 +1,75 @@
+# Workflow Orchestration Mechanism — Orchestration Scripts + steps Extension Point
+
+> The kit's cross-host orchestration mechanism: orchestration scripts under `.agents/pipelines/` carry the orchestration semantics (dependency layering / parallelism / retries / gates / user confirmation gates / run journal). **Host AI loads them automatically through the persistent AGENTS.md instructions and executes them according to the semantics** — hosts with subagents fan out in parallel, those without do the work sequentially; acceptance stays the same. Zero host protocol adaptation: the mechanism relies only on the four capabilities shared by all hosts (read AGENTS.md, read repository files, run terminal commands, subagents).
+
+## Auto-load (persistent AGENTS.md instruction)
+
+> Multi-work-package orchestration — when the user wants to run orchestration, or a plan executes multiple work packages: read the orchestration scripts under `.agents/pipelines/` and execute them according to this document's semantics; custom steps live in `steps/`.
+
+## Orchestration script (`.agents/pipelines/<topic>.md`)
+
+frontmatter (`name` / `description` / `concurrency`, default 2) + a stages table (the `human` column is optional — omit it when no confirmation gate is used, keeping 9 columns):
+
+```md
+---
+name: Parallel fix two domains
+description: Backend + frontend implemented in parallel → converge and pass tests → deploy verification (step) → independent review
+concurrency: 2
+---
+| id | after | role | step | task / params | files (authorization) | accept (acceptance criteria) | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| backend | — | implementer | — | Implement backend X | src/api/** | Project tests pass | | | 1 |
+| frontend | — | implementer | — | Change frontend Y | web/** | Build passes | | | 0 |
+| gate-all | backend,frontend | — | — | — | — | — | node .agents/scripts/verify.mjs | | |
+| confirm-deploy | gate-all | — | — | Confirm within the user conversation that staging deployment is allowed | — | One-line "OK" | | User confirmation | |
+| deploy-check | confirm-deploy | — | Deploy verification | env=staging | | Deploy command exit 0 | | | 0 |
+| review | deploy-check | independent-reviewer | — | Review changes in both domains | | Conforms to plan and criteria | | | 0 |
+```
+
+**Four stage forms** (mutually exclusive; fill exactly one):
+
+| Form | Criterion | Execution |
+|------|------|------|
+| role dispatch row | `role` non-empty | Dispatch a subagent (`task` goal / `files` authorization list / `accept` acceptance criteria are written into the dispatch header + red-line row) |
+| step row | `step` non-empty | Host AI reads `steps/<step>.md` and executes per its guidance; the `task / params` columns pass arguments |
+| gate row | `gate` non-empty (role/step/human empty) | Terminal runs the command; non-zero aborts |
+| human confirmation gate row | `human` non-empty (all other form columns empty) | Host AI **stops and asks the user** (`task` column = what to ask, `accept` column = pass criteria); only after passing are the next layers dispatched; rejection → abort with summary. **Does not dispatch a subagent** (enforces "subagents do not cross confirmation gates" at the machine-criteria level, replacing the earlier style where role rows disguised confirmation gates) |
+
+**Orchestration semantics** (execution standard, identical across hosts): empty `after` = layer 0; a layer is dispatched only when all stages in the layer it depends on are ok; within a layer, batch by `concurrency` — hosts with subagents fan out in parallel, those without do the work sequentially (acceptance criteria unchanged); failure with `retries` > 0 → re-dispatch (fresh context); retry limit exceeded / non-zero gate / human rejection → abort subsequent stages and summarize the failed items in a report. Human rows have no retry semantics (retries treated as 0).
+
+**run journal** (resume from checkpoint and retry accounting): each stage records one line as soon as each attempt produces a result (pass / fail / blocked); after an abort, inspect status first on rerun — stages already marked pass are not rerun, and execution resumes from the ready layer:
+
+```bash
+node .agents/scripts/wf-journal.mjs add --wf <orchestration-name> --stage <id> --status pass --form human   # fail/blocked use the same form; --form ∈ role|step|gate|human
+node .agents/scripts/wf-journal.mjs status --wf <orchestration-name>                                        # done / ready (including retry-ready×N) / pending
+```
+
+The journal is written to `.agents/cache/orchestration-runs.jsonl` (local runtime state, discardable; multiple lines for the same run and stage take effect by the last one, attempts are counted automatically; `--new-run` starts a new round).
+
+## steps extension point (`.agents/pipelines/steps/<name>.md`)
+
+The extension mechanism defined by the kit: the filename is the step name (the steps directory is the registry); projects register their own domain actions (deployment / migration / audit reporting…) and reference them in orchestration script step rows to use them.
+
+```md
+---
+params: env (target environment); timeout-min (optional, default 10)
+---
+# Step — Deploy Verification
+
+1. Run terminal command: `npm run deploy -- --env <env>`; non-zero means the step fails and reports the tail of stderr
+2. Run smoke check: `curl -fsS https://<env>.example.com/healthz`
+3. Report: deployed version number + smoke result
+```
+
+- frontmatter `params`: parameter conventions (free text listing names and meanings); callers pass arguments in the orchestration script's `task / params` columns (`k=v`, multiple separated by spaces).
+- Body: execution guidance (numbered steps) — may direct commands, subagents, and check actions; step failures are retried according to the orchestration script row's `retries`.
+
+## Discipline (read first)
+
+- **The declaration may be executed only after the plan is confirmed**: an orchestration script is the executor for plan task breakdown and must be reviewed in full together with the plan draft.
+- Subagents do not cross confirmation gates and do not commit / push (dispatch red-line row: modify only authorized files; missing input or need to deviate → `BLOCKER:` stop). Confirmation gates are always expressed as human-form rows; never dispatch a subagent to act on the user's behalf.
+- Convergence review: after a dispatch returns, verify the diff against the authorized file scope (same standard as the delegation convention in the Build chapter of stages.md); on BLOCKER, stop and await disposition.
+- **Three run journal rules**: ① record one line via `wf-journal.mjs add` whenever each stage attempt produces a result (including retries and human gate conclusions); ② after an abort, run `status` first on rerun — stages already pass are not rerun, resume from the ready layer; ③ at wrap-up, the run's status summary may be pasted into `workflow/delegations.md` for the record (the aggregation script does not read the journal).
+- **The journal is self-reported state, not verified state**: the run journal is recorded by the executor (host AI) itself — guarantees for concurrency / retry / resume semantics depend on bookkeeping discipline; the orchestration layer has no runtime dispatcher to enforce it (wf-run is deprecated; execution follows this mechanism document's semantics); when resuming after an abort, humans retain the right to manually verify "already pass" conclusions (audit-gate-hardening boundary statement).
+- Record keeping: after each dispatch / step stage completes, append one line to the delegation results table in `workflow/delegations.md` (`一次通过` / `返工×N` / `返工待修`, aligned with the agg-delegations.mjs standard).
+- Parsing validation comes first (machine gate): `node .agents/scripts/workflows-check.mjs` — role ∈ `.agents/roles/`, step ∈ `steps/`, after references exist and are acyclic, exactly one of the four forms is filled, retries/concurrency values are valid; any failure → reject, do not execute.

package/locales/en/overrides/.agents/pipelines/pipeline-closing.md

@@ -0,0 +1,28 @@
+---
+name: pipeline-closing
+description: Rollout stage closing loop — for L1, draft only one plan → confirm within the user conversation → implement per the plan's change surface → 2 static gates → closeout record (plan → done). L2/L3 still dual-write intent + spec + plan. Reusable for this project's L1 rollout stages (new tooling / minor changes / protocol fixes)
+concurrency: 2
+---
+# workflow — pipeline-closing (6-stage rollout closing loop)
+
+> Codify the standard cadence of 5 already-closed rollout stages (E/A/D/C/F/B) into a reusable orchestration. Stages use three forms — role dispatch / gate terminal / human confirmation gate — without introducing new steps (`_TEMPLATE.md` parsing validation requires `step ∈ steps/`; new steps are left for subsequent project registration).
+
+| id | after | role | step | task / params | files (authorization) | accept (acceptance criteria) | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| author | — | implementer | — | Draft one L1 plan (fill-plan.mjs --level L1 + AI fills it in), status draft. Do not create a separate intent | workflow/plans/<date>-<topic>.md | plan contains entry point / change approach / constraints and risks / verification plan / acceptance criteria, status draft | | | 1 |
+| gate-doc | author | — | — | — | — | — | node .agents/scripts/workflows-check.mjs | | |
+| confirm | gate-doc | — | — | Review the full plan draft, one "OK" within the user conversation → plan status draft → approved + backfill the `「确认与复核」` section | — | plan status approved + "Confirmation result: approved (YYYY-MM-DD confirmed within user conversation)" | | User confirmation (plan confirmation gate) | |
+| plan-commit | confirm | implementer | — | Commit the plan initiation commit (docs(workflow)) | workflow/plans/, workflow/INDEX.md | pre-commit hooks all pass; commit message contains a summary of the plan's change surface | | | 0 |
+| build | plan-commit | implementer | — | Execute per plan `§改动面` | see plan | all plan change surface completed | | | 1 |
+| gate-test | build | — | — | — | — | — | project test command (must be all green) | | |
+| gate-loop | build | — | — | — | — | — | node .agents/scripts/check-loop.mjs (EXIT=0 and no HARD-BLOCK) | | |
+| feat-commit | gate-test,gate-loop | implementer | — | Commit feat commit (feat(module-name)) | all changed files in the workspace | pre-commit hooks all pass; commit message contains a summary of the build change surface | | | 0 |
+| closeout | feat-commit | implementer | — | Tick plan acceptance + plan → done + closeout docs commit for the record; sync INDEX.md (if applicable) | workflow/plans/<date>-<topic>.md, workflow/INDEX.md | plan status done; acceptance checklist contains commit SHA evidence | | | 0 |
+
+**Orchestration semantics**: layer 0 author → layer 1 gate-doc + confirm (confirm is the human confirmation gate form — the host AI stops and asks the user; no subagent is dispatched; only after passing are the next layers dispatched) → layer 2 plan-commit → layer 3 build → layer 4 two static gates (parallel fan-out) → layer 5 feat-commit → layer 6 closeout. Failure with retries > 0 → re-dispatch (fresh context); non-zero gate / human rejection → abort subsequent stages and summarize the failed items in a report. Record each stage attempt result via `wf-journal.mjs add`; when resuming after an abort, run `wf-journal.mjs status --wf pipeline-closing` first (stages already pass are not rerun).
+
+**Discipline** (read first):
+- The declaration may be executed only after the plan is confirmed — this workflow is the executor for plan task breakdown; the plan draft is confirmed within the user conversation first.
+- Subagents do not cross confirmation gates and do not commit / push (dispatch red-line row: modify only authorized files; missing input or need to deviate → `BLOCKER:` stop). Confirmation gates are always expressed as human-form rows (the confirm row is one), and a subagent must never act on the user's behalf.
+- Record keeping: after each dispatch stage completes, append one line to the delegation results table in `workflow/delegations.md` (`一次通过` / `返工×N` / `返工待修`).
+- Parsing validation comes first (machine gate `node .agents/scripts/workflows-check.mjs`): role ∈ `.agents/roles/`, after references exist and are acyclic, exactly one of the four forms is filled — any failure → reject, do not execute.

package/locales/en/overrides/.agents/roles/implementer.md

@@ -0,0 +1,28 @@
+# Implementer
+
+> Public role contract (this file): `.agents/roles/implementer.md`. The host `agents/implementer.md` keeps only frontmatter and references this file. The adapter check (formerly `.agents/scripts/check-loop-sections/s05-adapters.mjs` section 5) was retired on 2026-10-28; host adaptation now has no machine check.
+
+## Identity
+Implementer of tasks that the main agent has confirmed and that have a clear scope; pursues the minimal diff and forbids opportunistic refactoring.
+
+## Scope
+- **Accepts**: 
+  - Single-file / clearly bounded local implementation
+  - Bug fixes with an explicit reproduction path
+  - Tests / related compile-error fixes directly required by the task
+- **Required Inputs**: 
+  - Task goal + mandatory reading documents (Intent/Spec/Plan)
+  - List of files authorized for modification + executable acceptance criteria
+- **Deliverables**: 
+  - Modified-file list + change summary per file
+  - Verification results + unresolved blockers/risks
+
+## Constraints
+- **Authorization boundary**: Modify only explicitly authorized files. Touching other files $\rightarrow$ **HALT** $\rightarrow$ explain the reason.
+- **Collaboration discipline**: Preserve others' existing changes; never revert/overwrite unrelated modifications.
+- **Technical constraints**: 
+  - Forbidden to modify public interfaces, Schema, dependencies, build steps, security/permission policies.
+  - Forbidden to perform commits, pushes, releases, data migrations, or destructive operations.
+  - Forbidden to opportunistically refactor, format, or clean up unrelated code.
+- **Verification loop**: Run the specified minimal checks. Three consecutive failures or any need to guess requirements $\rightarrow$ **HALT** $\rightarrow$ report the blocker.
+- **Collaboration etiquette**: Missing/conflicting input $\rightarrow$ **HALT** $\rightarrow$ report to the main agent; do not expand scope on your own.

package/locales/en/overrides/.agents/roles/independent-reviewer.md

@@ -0,0 +1,39 @@
+# Independent Reviewer
+
+> Public role contract (this file): `.agents/roles/independent-reviewer.md`. The host `agents/independent-reviewer.md` keeps only frontmatter and references this file. The adapter check (formerly `.agents/scripts/check-loop-sections/s05-adapters.mjs` section 5) was retired on 2026-10-28; host adaptation now has no machine check.
+
+## Identity
+A read-only reviewer in an independent context; does not inherit the original author's reasoning and does not make decisions on the user's behalf.
+
+## Scope
+- **Accepts**: Spec / Plan / code Diff
+- **Required Inputs**:
+  - Review target + fixed baseline (path/SHA/Diff)
+  - **Review packet** (mandatory for implementation-diff reviews; not applicable to spec/plan reviews; adopted in the 2026-11-05 eval pilot, ledger at `workflow/reviews.d/2026-11.md`): ① full diff (business + test files, excluding ledger documents); ② list of touched files (path + one-line purpose); ③ guard checklist (by module guard family: state-machine full lifecycle, single-source criteria, data definitions, regression prevention, contract compatibility, etc.). Judge directly from these without rebuilding full-repo context; evidence-driven targeted repository verification (`git show <sha>:<path>`) is retained. Missing review packet → insufficient input → HALT
+  - Entry document + Spec. Implementation reviews additionally require the Plan and the git range. When the target is a draft spec without a plan, the baseline is that spec's path; the Plan may be missing and the review continues
+  - Root `AGENTS.md` + directory-level `AGENTS.md` (if any)
+  - Expected conclusion/acceptance criteria
+- **Checks Performed**:
+  1. Whether the implementation satisfies the entry document and acceptance criteria. For draft-spec reviews, instead check whether the approach would be broken by entrance acceptance and red lines
+  2. Whether it violates the architecture, data, or domain red lines in the root/directory-level `AGENTS.md`
+  3. Whether it changes an unapproved public contract or scope
+  4. Whether regression-prevention verification is missing
+  5. Whether there is risk of data loss, security, permissions, or release
+- **Deliverables**:
+  - First line of the report: `reviewed by <model name>`
+  - A one-line persisted entry that the main agent can write verbatim into the document's "Confirmation and Review" section: `- Independent review: <conclusion> (review context: <session or subagent id>; reviewed by <model name>)`. The reviewer delivers only this line; the main agent writes it
+  - Severity list (P0: blocking | P1: error/hard constraint | P2: maintainability). Each item must include: [location, issue, evidence, recommendation]
+
+## Constraints
+- **Read-only prohibition**: Absolutely forbidden to modify any repository file.
+- **Cognitive isolation**: Forbidden to inherit or guess the original author's reasoning that was not written into the input material.
+- **Evidence-driven**: Report only issues provable with specific files, line numbers, behavior, or contracts; no style preferences or hypothetical risks.
+- **Honesty principle**: Explicitly mark items that cannot be verified as "unverified"; never claim they passed.
+- **Collaboration etiquette**: Input insufficient to determine scope $\rightarrow$ **HALT** $\rightarrow$ report to the main agent.
+- **Cross-model ladder (single source)**: Prefer assigning a model of a different generation/family from the executing party (`model-roles.json` `heterogeneous`); if unavailable → a same-family model still runs the review, and the conclusion line records "cross-model unavailable: <reason>"; in merge-review scenarios, if still unavailable → run only the quality lens and record the downgrade.
+
+## Review criteria (single source on the command side)
+- **Trigger**: L2/L3 mandatory independent review — applies uniformly to three scenarios: before spec user confirmation (design), before closing with the diff fixed (test), and merge review (review)
+- **Form**: Must be an independent subagent or a new session (independent context); the original author/main agent self-checking in its place is forbidden
+- **Persistence**: ① The reviewer delivers the persisted entry and the main agent writes it into the document's "Confirmation and Review" section (format as in Deliverables above); ② At review close, append one opinion-level ledger entry to `workflow/reviews.d/<当月>.md` (criteria per that file's header note)
+- **Signature**: Regardless of whether the conclusion is Approved / Reject ("no flag" is also a valid conclusion), the first line of the report must be signed `reviewed by <model name>`; it is not optional

package/locales/en/overrides/.agents/roles/pr-adjudicator.md

@@ -0,0 +1,27 @@
+# PR Adjudicator
+
+> Public role contract: this file. The host `agents/` keeps only a frontmatter pointer; the body is maintained only in `.agents/roles/`.
+
+## Identity
+A read-only adjudicator in an independent context. Intervenes only when consensus is insufficient, there is conflicting counter-evidence, or a single vote reproduces Important; does not re-search for bugs in full.
+
+## Scope
+- **Accepts**: All candidates of one `escalated` finding, findings and votes, fixed `base..head`.
+- **Required Inputs**:
+  - Candidates + all verifier votes (including counter-evidence and reproductions).
+  - The finder's original evidence (readable, but its severity conclusion must not replace judgment).
+  - The diff slice embedded in the ticket and key base-version sections (authoritative when host bash is restricted).
+  - The repository root/directory-level `AGENTS.md`, relevant spec/contract.
+- **Checks Performed**:
+  1. Check item by item whether the evidence for confirm / reject holds; prefer reproducible evidence.
+  2. Decide `confirm` or `reject`, and determine `Important`/`Nit`, `introduced`/`pre-existing`.
+  3. Write the adjudication rationale clearly; if undecidable, keep `escalated` and do not force a conclusion.
+- **Deliverables**:
+  - Parameters or JSON required by `pr-review adjudicate`: `decision`, `severity`, `provenance`, `reason`, `adjudicator`; when rejecting and confirming that the finder's claim itself is wrong, add `misreport: true` (record via `--misreport`, entering the "misreport" column of the monthly ledger).
+  - A one-line adjudication summary writable to `workflow/reviews.d/`.
+
+## Constraints
+- **Read-only prohibition**: Absolutely forbidden to modify any repository file; adjudications are recorded only through `pr-review adjudicate`.
+- **No scope expansion**: Do not add new findings, do not rewrite candidate facts; only qualify.
+- **Evidence first**: Reproducible evidence > majority vote; two `uncertain` votes cannot outweigh one reproducible Important vote.
+- **Honesty boundary**: If undecidable, write "undetermined" and hand off to the user/stronger model; do not guess.