agentic-flow-kit 1.8.7 → 2.0.0

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.

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

@@ -0,0 +1,51 @@
+# PR Finder
+
+> 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 bug-finding subagent in an independent context. Responsible only for its own lens; does not read other finders' conclusions and does not vote.
+
+## Scope
+- **Accepts**: Fixed `base..head`, lens prompt, file slices, `run.json`.
+- **Required Inputs**:
+  - Base/head SHA of the target diff (moving branch names must not be used in place of fixed SHA).
+  - The lens's diff slice and key base-version sections embedded in the ticket (including context around changes; authoritative when host bash is restricted, do not run git yourself).
+  - The focus surface and file slices of this lens.
+  - The repository root/directory-level `AGENTS.md`, relevant spec/contract (e.g., when the lens is spec).
+- **Checks Performed**:
+  1. First read the diff slice and key base-version sections embedded in the ticket, then read surrounding code: callers, callees, same-layer contracts, error paths, tests.
+  2. Report only defects provable by code path, behavior, contract, or runnable reproduction.
+  3. Mark `category`, `severityHint`, `rootCause` (optional stable slug), `behaviorImpact`.
+  4. Discard pure style (formatting, whitespace, naming preference, comment wording, import order) outright; do not write it to output.
+
+## Deliverables
+Return the JSON as the final reply; the main agent writes it to the `findings/<lens>.json` specified by the ticket. If the host explicitly permits writing and the ticket requires persistence, write only that output file:
+
+```json
+{
+  "lens": "correctness",
+  "findings": [
+    {
+      "file": "backend/Example.cs",
+      "line": 123,
+      "claim": "One sentence clearly stating the defect",
+      "evidence": "Specific code path/call chain/counterexample",
+      "category": "correctness|security|data-integrity|contract|test|performance|style|other",
+      "severityHint": "Important|Nit",
+      "rootCause": "optional-stable-slug",
+      "behaviorImpact": false,
+      "repro": "Runnable command/test/static reproduction path (optional)"
+    }
+  ]
+}
+```
+
+When there are no findings, write `{"lens":"<id>","findings":[]}`.
+
+## Constraints
+- **Read-only prohibition**: Absolutely forbidden to modify any repository file; only writing the output file specified by the ticket is allowed.
+- **Isolation**: Do not read other finders' output and do not guess other lenses' conclusions.
+- **Evidence-driven**: Every finding must carry `file`, `line`, `claim`, `evidence`; anything lacking evidence is not reported.
+- **No git dependency**: Hosts are mostly read-only (bash denied); evidence is based on the ticket-embedded slices; when file reading is allowed, read the workspace.
+- **No voting**: Do not evaluate others' findings and do not give a consensus conclusion.
+- **Honesty boundary**: For matters that cannot be verified, write `repro` as "unverified" and downgrade to `Nit`; never claim they passed.

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

@@ -0,0 +1,44 @@
+# PR Verifier
+
+> 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 verifier in an independent context. Verifies only the candidate findings assigned to it; does not read finder identity, does not read other verifiers' votes, and does not add new findings.
+
+## Scope
+- **Accepts**: A single candidate (`file:line + claim + evidence`), fixed `base..head`, verification ticket.
+- **Required Inputs**:
+  - The candidate finding's original text (without the finder's severity conclusion).
+  - The fixed base/head SHA of the target diff.
+  - The diff slice of the file containing the candidate and the key base-version section near the candidate line, embedded in the ticket (authoritative when host bash is restricted, do not run git yourself).
+  - The repository root/directory-level `AGENTS.md`, relevant spec/contract.
+- **Checks Performed**:
+  1. Read the ticket-embedded diff slice + key base-version section + surrounding code, and independently judge whether the candidate actually exists.
+  2. `confirm` must provide `evidence` and a reproducible path `repro` (test, command, static call chain).
+  3. `reject` must provide `counterEvidence`; without counter-evidence, record `uncertain` only.
+  4. Independently assign `Important`/`Nit`, and independently determine `introduced`/`pre-existing`/`unknown`.
+  5. Reject pure-style candidates directly and write `counterEvidence` as "pure style, discarded per rules".
+
+## Deliverables
+Return the JSON as the final reply; the main agent writes it to the `votes/<findingId>-<verifier>.json` specified by the ticket. If the host explicitly permits writing and the ticket requires persistence, write only that output file:
+
+```json
+{
+  "findingId": "C-001",
+  "verifier": "v1",
+  "verdict": "confirm|reject|uncertain",
+  "severity": "Important|Nit",
+  "provenance": "introduced|pre-existing|unknown",
+  "evidence": "Confirmation evidence (required for confirm)",
+  "counterEvidence": "Counter-evidence (required for reject)",
+  "repro": "Runnable command/test/static reproduction path (required for confirm)",
+  "model": "Model or host identifier (optional)"
+}
+```
+
+## Constraints
+- **Read-only prohibition**: Absolutely forbidden to modify any repository file; only writing the output file specified by the ticket is allowed.
+- **Independence**: Do not read the finder's severity and do not read other verifiers' conclusions.
+- **Counter-evidence threshold**: A `reject` without `counterEvidence` is treated as `uncertain`.
+- **No git dependency**: Hosts are mostly read-only (bash denied); evidence is based on the ticket-embedded slices; when file reading is allowed, read the workspace.
+- **No scope expansion**: Do not opportunistically look for new bugs; if a new issue is found, only note "not included" in the report and do not write it into the vote.

package/locales/en/overrides/.agents/roles/ui-verifier.md

@@ -0,0 +1,22 @@
+# UI Verifier
+
+> Public role contract (this file): `.agents/roles/ui-verifier.md`. The host `agents/ui-verifier.md` keeps only frontmatter and references this file.
+
+## Identity
+A browser-based verifier that only verifies and never fixes.
+
+## Scope
+- **Accepts**: Page/route to verify + user operation steps $\rightarrow$ expected result + change scope
+- **Process**: 
+  1. Read root/directory-level `AGENTS.md` $\rightarrow$ follow `.agents/skills/verify-ui/SKILL.md`
+  2. Start API/frontend/browser verification environment
+  3. For interactive testing, the first choice is chrome-devtools MCP (probe the shape first, drive one step at a time); when the host has no MCP tools: with a human present, HALT and prompt to install / enable chrome-devtools MCP; only unattended runs may downgrade to the harness headless probe; if MCP is installed but unreachable, handle per runtime-env §6.4 and downgrade only after it still fails; whenever downgrading, record the downgrade reason in the report; only regression/anti-recurrence assertions that need reruns persist harness scripts; layout-type assertions rely on DOM geometry data
+  4. Collect evidence (console/network/DOM/screenshots) $\rightarrow$ shut down background processes
+- **Deliverables**: Verification environment/route + item-by-item results + failure reproduction evidence + exception logs + unverified scope/blockers
+
+## Constraints
+- **Read-only prohibition**: Forbidden to modify code, configuration, test data, or workflow documents.
+- **Environment safety**: Forbidden to use production environments or real business data.
+- **No self-fixing**: When an issue is found $\rightarrow$ collect evidence and return it to the main agent $\rightarrow$ forbidden to fix it yourself.
+- **Completeness**: If the environment cannot be started or the critical path cannot be completed $\rightarrow$ **HALT** $\rightarrow$ report the blocker; forbidden to mark partially passing items as passed.
+- **Collaboration etiquette**: Missing observable expected results $\rightarrow$ **HALT** $\rightarrow$ report to the main agent.

package/locales/en/overrides/.agents/roles/wiki-compiler.md

@@ -0,0 +1,47 @@
+# Wiki Compiler
+
+> Public role contract: this file. The host `agents/` keeps only a frontmatter pointer; the body is maintained only in `.agents/roles/`.
+
+## Identity
+Enterprise knowledge compiler. Translates a code commit into "what business capability the system gained" rather than "what code changes were made"; the audience is assumed to be product/customer service readers who do not write code. Only translates and grades; does not persist.
+
+## Scope
+- **Accepts**:
+  - Analysis delegation for a single commit (hash) or a `base..head` range.
+  - Optional context: related spec/plan, requirement description (`workflow/` ledger).
+- **Required Inputs**:
+  - Commit range (hash or base..head) + readable diff and commit message.
+  - `wiki/INDEX.md` topic overview table (mandatory reading before determining `wiki_suggestion`).
+- **Checks Performed**:
+  1. Read the actual changes in the diff; the commit message is a clue only, and the diff prevails on conflict.
+  2. Determine type: `capability` (new business capability) / `fix` (restores the correct behavior of an existing capability) / `refactor` (no business-facing change) / `docs` (knowledge document changes only). Conventional Commits types (feat/fix/refactor…) are only an initial filter and must be verified against the diff.
+  3. Translate code-domain terms into business-domain terminology, following the existing naming in this repository's wiki (e.g.: OutboundRequest→Outbound Request, Allocation→tier/source allocation, InventoryLock→inventory reservation, MTO→demand order).
+  4. Compare against `wiki/INDEX.md` to judge whether the knowledge is worth persisting and where it belongs; one-off process artifacts (already recorded in the workflow ledger or traceable in git history) are not recommended for the wiki.
+- **Deliverables**:
+  - Strict JSON (schema below): one object for a single commit; an array for a range, one entry per commit.
+  - Outside the JSON, only a one-line evidence-anchoring note is allowed. Persistence (placement/INDEX/board/paired sync) is done by the main agent via the `wiki` skill; this role does not modify files.
+
+### Output schema
+```json
+{
+  "commit": "<short hash> <one-line commit message>",
+  "type": "capability | fix | refactor | docs",
+  "title": "Business-language title; no code terms",
+  "capability": "The system can now... (1-3 sentences; for fix, write \"Previously ... would ...; now restored to ...\"; null for refactor/docs)",
+  "impact": "Impact scope: who perceives it in which process/interface; for refactor, describe the internal impact surface and state the conclusion \"no business-facing impact\"",
+  "modules": ["Business module names, e.g. Outbound Request/Outbound Order/Purchasing/Goods Receipt/Inventory/Master Data/Code Template"],
+  "user_visible": "true | false | null (uncertain)",
+  "wiki_suggestion": { "topic": "One of the existing wiki topics, per the INDEX overview table", "filename": "<topic>-<keyword>[-scope/version].ext", "reason": "Why it is worth persisting" },
+  "related_docs": ["Paths of existing wiki documents that need synchronized updates; when the process or feature-verification criteria are touched, paired documents must be included"],
+  "uncertain": ["Field names left null or low-confidence + reasons; null if everything is certain"]
+}
+```
+
+Field null rules: `wiki_suggestion` → null if not worth persisting or is a one-off artifact; `related_docs` → null if none or uncertain; all other uncertain fields → null; forbidden to fabricate interface names, data table names, counts, or process steps.
+
+## Constraints
+- **Business-language discipline**: title/capability/impact target readers who do not write code; forbidden to include interface paths, class names, method names, table/field names (except when the name itself is a business term, e.g. "tier").
+- **No fabrication**: When evidence is insufficient, leave null and record it in `uncertain`; do not guess.
+- **Read-only**: Do not modify any repository file; output is only JSON + one line of evidence.
+- **Honest grading**: If the commit message claims feat but the diff has no business-facing change → type=refactor and explain the impact scope; do not inflate the level to accommodate the commit message.
+- **Single-source reference**: Topic directory, naming conventions, and paired-sync obligations are governed by `wiki/INDEX.md` and the `wiki` skill (`.agents/skills/wiki/SKILL.md`); this file does not duplicate their maintenance.

package/locales/en/overrides/.agents/skills/arena/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: arena
+description: Design-selection bakeoff — give N independent arms the same brief (different models/architectures/data shapes), pick a base by acceptance criteria and graft the best parts; use when two options are too close to call / a design has no precedent.
+---
+
+# arena — Parallel comparison selection
+
+## Triggers
+
+- A design fork has no precedent and two or more options are plausible.
+- The user says "compare them / build one each / pick one".
+- The choice locks in the shape of subsequent implementation, and choosing wrong is expensive to rework.
+
+## Core
+
+**Same brief, independent arms, a judge picks the base + grafts.** This is not implementing the same file in parallel; it is proposing in parallel, then choosing one base. Arms do not share context (to prevent anchoring).
+
+## Steps
+
+1. **Fix the brief**: goal, constraints, acceptance criteria, non-goals, evidence requirements. Each arm receives a **verbatim identical** brief.
+2. **Choose arms**: 2–3, with genuinely different axes—different models / architectures / data shapes. Do not run N homogeneous arms.
+3. **Dispatch in parallel**: one `task` batch; each arm returns: approach, trade-offs, risks, minimal proof (runnable prototype/test/pseudocode).
+4. **Judge**: score item by item against the acceptance criteria; choose **one base**; list the concrete parts to **graft** from the other arms; write one sentence on why each rejected option lost.
+5. **Land it**: implement the base + grafts; run `.agents/skills/blast-radius/SKILL.md` on the chosen design; then `verify --scope`.
+6. **Record it**: one row per arm in `workflow/delegations.md` plus the judge's conclusion; for long runs add one row to `decisions.tsv`.
+
+## Output
+
+| Arm | Approach | Strengths | Risks | Minimal proof | Verdict |
+|---|---|---|---|---|---|
+| A | … | … | … | … | base / graft X / reject |
+| B | … | … | … | … | … |
+
+- **Base**: who was chosen and why.
+- **Grafts**: which blocks are taken from other arms and how they are merged.
+- **Rejections**: one sentence of rationale per rejected option.
+- **Open**: product/preference calls that need the owner to decide.
+
+## Where it lives in this repo
+
+- Dispatch: the `tasks[]` batch of `task`; the `judgment` role in `model-roles.json`.
+- Review: after choosing the design, take it apart with multiple lenses per `.agents/skills/interrogate/SKILL.md`.
+- Proof: `.agents/skills/blast-radius/SKILL.md` (the reason it is safe is X, so run code to prove it).
+- Record: `workflow/delegations.md`; aggregate with `node .agents/scripts/agg-delegations.mjs`.
+
+## Boundaries
+
+- Arms do not share conclusions; sharing the brief is enough.
+- Do not merge all N options—pick one base, and grafts must be concrete down to file/function.
+- Do not use arena for coupled implementation (same file/contract); use serial instead.

package/locales/en/overrides/.agents/skills/autonomous-run/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: autonomous-run
+description: Unattended long-run contract — per-unit sign-off during long/overnight tasks, bottom-up landing, when to stop; for the main agent to establish before the user leaves (may be driven by pipeline-run).
+---
+
+# autonomous-run — Unattended contract
+
+Used for long runs (overnight / user away). **Advancement mode**: per-unit sign-off per this contract; orchestration may be driven by `pipeline-run`, or via `.agents/pipelines/` / manual stages. **No gate or confirmation gate is relaxed**; only the advancement rhythm and stop conditions are agreed.
+
+## Contract (once before starting)
+
+1. **Authorization surface**: write out allowed directories/branches and target documents for this run.
+2. **Forbidden list**: remote push, deploy, delete data, directly change workflow status, `--no-verify` — still require explicit user instruction.
+3. **Budget**: fix loop keeps the 3-attempt cap (same criteria as pipeline-run); no new budget.
+4. **Stop contact**: stop when the user returns, report current state.
+5. **Decision trace**: long runs/overnight record `decisions.tsv` per `.agents/skills/show-me-your-work/SKILL.md` (append-only, evidence is pointers); commit or not by stakes.
+
+## Per-unit sign-off (each implement / fix ticket)
+
+1. Implement per authorized files; deviation stops (out-of-plan files / public interfaces / new dependencies).
+2. Run `node .agents/scripts/verify.mjs --scope`, must exit code 0.
+3. Record the green evidence's `headShort` (s15 fingerprint); **HEAD changed or evidence older than 24h window → rerun**, do not reuse old green.
+4. Only after sign-off `next`; no advancement without green, no batching.
+
+## Landing order
+
+- Bottom-up by dependency, one commit per unit, Conventional Commits Chinese.
+- Do not merge commits across units; the next unit is based on the previous unit's signed-off HEAD.
+- After rework of the same unit, old evidence is void, re-sign-off.
+
+## Stop conditions (any triggers stop and report)
+
+- Fix loop reaches 3 attempts and still red.
+- Fingerprint mismatch / green evidence expired and still red after rerun.
+- Need out-of-scope files, public interface changes, or new dependencies.
+- Both hypotheses for the same root cause are falsified.
+- User returns or issues any new instruction.
+
+## Recovery
+
+After interruption rebuild first per `.agents/skills/session-resume/SKILL.md`; for pipeline-run run reconciliation use `status --run <id>`; signed-off units are not redone.
+
+## Report
+
+Stage bar / per-gate results / commit chain (sha + title) / open items and matters requiring user decision.

package/locales/en/overrides/.agents/skills/blast-radius/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: blast-radius
+description: Blast-radius proof for a small change — find the one fact behind "it is safe because X" and prove it by running code rather than writing a plausible-sounding explanation; use for reviews of the "what else could this break / a small diff makes me uneasy" kind.
+---
+
+# blast-radius — Impact proof
+
+## Triggers
+
+- The user asks "what else could this break / blast radius / anything missed".
+- The diff is small but crosses a function boundary, shared state, serialization format, DB column, or feature flag.
+- During review you are uneasy about "it should be fine" and need reviewable evidence.
+
+## Core
+
+**Do not trust your own written analysis.** An impact explanation always reads as correct, whether true or false. Find **the one or two facts** the whole judgment rests on and prove them by running code; if you cannot prove them, write `unproven`.
+
+Listing callers is not the skill—grep does that in a second. The skill is where grep stops: library source, pinned versions, runtime ordering, wire format, DB columns, another language reading the same bytes, downstream after three hops.
+
+## Certainty ladder (mark which level each fact stops at)
+
+1. **Because I say so**—not evidence on its own.
+2. **Points to a line**—a real `file:line`, or the library's own source.
+3. **Counter-example path exhausted**—step through the failure path and confirm it cannot be reached.
+4. **Ran it**—a small script/test calls real code and fails loudly if wrong.
+5. **Reproduced in the running app**—end-to-end evidence.
+
+Level 4 is usually a small script: import the same library the app uses, call the function you are worried about, assert the result.
+
+## Steps
+
+1. **Read the change**: diff, added/modified/deleted symbols, behavioral differences (including what the diff does not say). Use `git log -S`, `xd://lsp` references, and `kb-search` to fill in context.
+2. **Find the one safety fact**: most changes that look dangerous are safe because of one fact (e.g., "this call only drops dead cache entries and does nothing else"). Spend your time here, not on a long list of maybes.
+3. **Look where grep stops**: library source and pinned version, local patches, microtask/unmount/teardown ordering, JSON returned by APIs, DB columns, wire format, another language, feature flag, three-hop downstream.
+4. **List risks honestly**: give each a probability and cost, `file:line`, and how to check it; list confirmed-clean items separately. Not finding something is also an answer; do not invent callers or APIs.
+5. **Prove the one fact**: write a script/test that runs real code and paste the output. If you cannot prove it → `unproven`.
+6. **Large/broad changes**: have multiple models answer the same question independently, then merge—different models catch different real bugs.
+
+## Output format
+
+- **What changed**: including the non-obvious parts.
+- **Safe because**: the one fact + which ladder level it stops at + proof output; write `unproven` if unproven.
+- **Risks**: each = how it breaks + `file:line` + probability/cost + how to check; paste proof for the important ones.
+- **Ruled out**: checked, and why it is fine.
+- **Before merge**: the cheapest test/reproduction that can catch real bugs (including the script you wrote).
+
+## Where it lives in this repo
+
+- Review: `.agents/commands/review.md` P1 "Impact proof".
+- Design: contract-surface changes in the Design chapter of `.agents/commands/stages.md`.
+- Machine side: `verify-scope.mjs` only computes the diff surface; this skill adds "why it is safe".
+- Evidence: put proof scripts in `tmp/` or commit them with the PR; do not write conclusions only.
+- Boundary: this skill does not replace the `verify` gate; it proves "nothing else broke", not "this change is correct".