agentic-flow-kit 1.8.7 → 2.0.0

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 |

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>