pi-legion 3.1.0 → 5.0.0

package/README.md

@@ -1,7 +1,7 @@
 ---
 name: pi-legion
 npm: "pi-legion"
-description: "Pi Legion v2: recursive centurion trees on headless Pi RPC; shared SQLite WAL legion.db. Four-stage planning/implementing/reviewing/verifying state machine, parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume."
+description: "Pi Legion v2: recursive centurion teams on Pi. Children run in-process by default (rpc only for a worktree-owning centurion); shared SQLite WAL legion.db. Declarative per-team phase machine (built-in default: planning/implementing/reviewing/verifying), parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume."
 ---
 
 # pi-legion
@@ -30,7 +30,7 @@ shared SQLite ledger records the whole tree.
 - [Team 配置](#team-配置)
 - [Parent/child context conventions](#parentchild-context-conventions)
 - [Delivery and resume](#delivery-and-resume)
-- [Herdr transition and role migration](#herdr-transition-and-role-migration)
+- [Supported kinds](#supported-kinds)
 - [Changelog](CHANGELOG.md)
 - [Development](#development)
 
@@ -49,14 +49,16 @@ User (CEO) — root Pi session (TUI)
    └─ pi-legion in child mode
       ├─ LegionSupervisor for this squad
       ├─ `legion_mail` / `legion_tree` / `legion_phase` tools
-      ├─ worker / scout / reviewer … children (`worktree: false`)
+      ├─ worker / scout … children (`worktree: false`)
       └─ nested centurions → recursive squads
 ```
 
 Transport, state, decision-making, and display are separate layers:
 
-- **Transport:** each child is a headless Pi RPC process managed by a
-  `LegionSupervisor`; a centurion can supervise another squad recursively.
+- **Transport:** a child is an `AgentSession` inside the parent process by
+  default; only a worktree-owning centurion runs as a separate `pi --mode rpc`
+  process. A `LegionSupervisor` owns both backends, and a centurion can lead
+  another squad recursively.
 - **State:** all nodes in the tree share the `legion.db` SQLite ledger in WAL
   mode. Per-run `run.json` records and session files remain the resume source
   for each child.
@@ -65,37 +67,70 @@ Transport, state, decision-making, and display are separate layers:
 - **Display:** the event bus feeds the resident tree, the `/legion` full view,
   and an on-demand live overlay.
 
-## Spawn mode
+## Bundled roles
+
+Three roles ship with the package:
+
+| Role | Purpose | Tools | Default timeout |
+| --- | --- | --- | --- |
+| `centurion` | Team lead: freeze the contract, dispatch children, drive the phase machine, deliver a reviewable result. Holds the worktree. | pi defaults | 30 min |
+| `worker` | Implementation: write code and run tests against a frozen plan, report a verdict. | read/edit/write/grep/find/ls/bash/codemode | 45 min |
+| `scout` | Read-only recon: produce a fact list, no plan, no implementation. | read/grep/find/ls/bash/codemode | 10 min |
 
-`spawnMode` picks the backend that runs one child. Per role it comes from agent
-frontmatter → `subagents.agentOverrides.<role>` → team member override:
+`worker` cannot dispatch nested agents (`maxSubagentDepth: 1`). Anything a worker
+needs to escalate is a `verdict ok:false`, not another layer of children — one
+level keeps the tree's cost and blast radius bounded.
+
+Roles are not a fixed pipeline. Since the phase machine became declarative
+(#298), nothing in the runtime keys on a role being called "worker" or
+"reviewer"; a team shapes its workflow by declaring phases on its lead's card.
 
 ```yaml
-# agents/scout.md
----
-spawnMode: inprocess   # or: rpc
----
+# agents/centurion.md
+phases:
+  - id: recon
+    next:
+      - to: build
+        require: [contract_file]
+  - id: build
+    next:
+      - to: done
+        require: [children_settled]
 ```
 
-**Default:** omitting `spawnMode` means `inprocess` — the child runs as an
-`AgentSession` inside the parent Node process (`createAgentSession`), which
-trades process isolation for spawn latency.
-
-**Automatic fallback to `rpc`:** when `spawnMode` is omitted *and* the resolved
-spawn cannot be in-process, Legion launches it over `pi --mode rpc` instead.
-That happens when the role needs an OS worktree (`worktree: true` — only the
-`centurion` role may hold this; see Isolation below). A `kind !== "pi"` role is
-rejected earlier with `INVALID_PARAMS` (only `kind: pi` children are supported
-at all), so it never reaches this fallback.
-
-**Explicit is strict:** `spawnMode: "inprocess"` with `worktree: true` is
-refused with `INVALID_PARAMS` (message prefers `set worktree: false`) rather
-than silently downgraded, so a role that asks for in-process never gets a
-different transport behind its back. Non-centurion requests for `worktree: true`
-are demoted to `false` with a once-per-run warning instead of throwing.
-
-Limits for the in-process backend are separate (`subagents.inprocess.*`) and are
-not shared with the `legion.*` tree budgets — see
+Omitted means the built-in four-phase pipeline
+(`planning → implementing → reviewing → verifying → done`). Conditions are a
+closed vocabulary — `contract_file`, `children_present`, `children_settled`,
+`children_none_failed`, `verdict_ok`, `verdict_not_ok`, `verification_passed`,
+`verification_failed`, `rework_available`, `children_all_failed`, `always` — and
+`done` / `failed` / `aborted` are always available terminals so a team can
+never lose the ability to complete or abort.
+
+## Spawn mode
+
+The backend is a property of the **launch**, not of a role. There is no
+`spawnMode` frontmatter field — a card cannot pin itself to a process model —
+and the rule is simply:
+
+| Launch needs a worktree? | Backend |
+| --- | --- |
+| yes | `rpc` — a separate `pi --mode rpc` process |
+| no | in-process `AgentSession` inside the parent Node process |
+
+**Why rpc still exists:** it is the only backend that can host a worktree
+child. Only the `centurion` role may hold a worktree (see
+[Delivery and resume](#delivery-and-resume)), so a centurion is the only role
+that can ever run on rpc — every other role runs in-process, where spawn latency
+is lower and no second process is involved.
+
+**A non-centurion asking for a worktree** is demoted to `worktree: false` with a
+once-per-run warning rather than throwing, so a stale card does not break every
+launch in the tree.
+
+**Both backends share the same budgets.** The legion tree limits
+(`maxDepth` / `maxChildrenPerNode` / `maxActiveNodes`) apply to every launch; the
+in-process pools (`subagents.inprocess.*`) apply on top, and the stricter gate
+wins. Avoiding rpc is never a way to escape a cap. See
 [docs/inprocess-supervisor.md](docs/inprocess-supervisor.md).
 
 ## Headless child contract
@@ -130,7 +165,7 @@ subagent({
 ```
 
 The centurion plans the work, writes the squad contract, dispatches ordinary
-roles such as `worker`, `scout`, and `reviewer`, and coordinates the squad
+roles such as `worker` and `scout`, and coordinates the squad
 through its phases. For a single leaf task, dispatch an ordinary role directly:
 
 ```text
@@ -167,16 +202,17 @@ controls run graceful `stop` (a stopped parent retires its own subtree on
 shutdown); process exit / session shutdown also retires:
 
 - **`/legion stop`** stops every live subagent; **`/legion stop <name>`** stops
-  one (`all` is an alias for no name). Names complete from the live children;
+  one (`all` is an alias for no name). Add **`--force`** / **`-f`** for hard
+  retire (same as tool `force: true`). Names complete from the live children;
   nested agents complete as `parent/name` and are reported as owned by their
   parent (stop the parent to retire them).
 - **`x`** on the selected live agent in the `/legion` view or its live
-  overlay asks `y` to confirm in place, then stops it.
+  overlay asks `y` to confirm in place, then stops it (graceful; use
+  `/legion stop --force <name>` for hard retire).
 - **Tool**: `subagent({ action: "stop", name })` is graceful; pass
   `force: true` for hard retire (SIGTERM → SIGKILL + descendant sweep per
   `docs/retire-hardening-contract.md`). Example:
   `subagent({ action: "stop", name: "worker-0", force: true })`.
-  TUI `/legion stop --force` is an optional follow-up (same `force: true`).
 
 **`wait` ≠ stop.** A `wait` timeout (or still-running result) does **not**
 retire children. The tool result includes live child names, elapsed ms, and
@@ -184,8 +220,8 @@ suggested decisions (`extend` / `steer_again` / `stop` / `force_stop`); the
 parent chooses the next tool call. See `docs/contracts/wait-not-stop.md`.
 
 While subagents are live, the railway header can show a dim
-`/legion stop [name|all]` hint (shortened on narrow terminals; idle gating /
-tree-strip coverage is a TUI follow-up).
+`/legion stop [--force] [name|all]` hint (shortened on narrow terminals; idle
+gating / tree-strip coverage is a TUI follow-up).
 
 ### Status (`/legion status`)
 
@@ -230,11 +266,17 @@ legion_phase({ to, note?, evidence? })
 - **`legion_phase`** is available to centurions. It requests a state transition;
   the supervisor checks the transition's invariants and records the result.
 
-A squad moves through **planning → implementing → reviewing → verifying**.
-Planning produces a non-empty `.pi-legion/contract.md` with file ownership
-and acceptance commands. During reviewing, an independent reviewer supplies
-the judgment; in verifying, the supervisor runs the contract's `legion-verify`
-commands without an LLM. Passing verification advances the squad to `done`.
+A squad moves through whatever phases its lead declares. With no declaration
+that is the built-in **planning → implementing → reviewing → verifying**:
+planning produces a non-empty `.pi-legion/contract.md` with file ownership and
+acceptance commands; reviewing needs a settled child that returns `ok:true`; in
+verifying the supervisor runs the contract's `legion-verify` commands without an
+LLM. Passing verification advances the squad to `done`.
+
+Because the machine is data, no rule names a role: "the children are settled" and
+"a verdict came back ok" are conditions, not "the worker" and "the reviewer".
+That is what lets a team rename, reorder, or drop phases without touching code —
+and it is why the bundled roster is just `centurion`, `worker`, and `scout`.
 
 ## Three-layer visualization
 
@@ -428,20 +470,35 @@ Coverage:
 
 ### Child extensions
 
-Children start with `--no-extensions`, so they do not load the host's
-discovered extensions (settings `packages`, `~/.pi/agent/extensions`, project
-extensions). Each extension a child loads is a memory cost multiplied by every
-concurrent child; an LSP stack is ~1 GB (#43). A child still loads pi-legion
-itself (guard and nested spawning) and every path listed in the role's
-`extensions` / `subagentOnlyExtensions`.
+**A child inherits every extension the parent has**, minus anything it excludes.
+This is the opposite of the pre-4.0.1 default: children used to start with
+`--no-extensions` and load only what a card named, which meant a role silently
+lost host capabilities (a provider extension, a guard) it never knew to name.
+Children now run in-process by default, so "one more extension" no longer means
+another process's worth of memory.
 
 | Knob | Effect |
 | --- | --- |
-| role frontmatter `inheritExtensions: true` | That role loads all host extensions, as before. |
-| `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1` | Every child loads all host extensions, as before. |
-| `PI_LEGION_CHILD_EXTENSIONS=/a.ts,/b.ts` | Extra extension paths every child loads explicitly, e.g. a provider extension the child's model needs. |
-
-Bundled planner, reviewer, and worker do not list `lens_*` tools. pi-lens starts an LSP stack (~1 GB per child, #43) and is not part of the default `--no-extensions` child. To give a role those tools, add the tool names to its `tools:` list and point `extensions:` / `subagentOnlyExtensions` (or `PI_LEGION_CHILD_EXTENSIONS`) at the pi-lens extension file. `/legion doctor` reports `ROLE_MISSING_LENS` when a role lists the tools without that path.
+| *(default)* | Inherit every host extension. |
+| role frontmatter `excludeExtensions: [pi-lens]` | Subtract specific ones. Accepts a package **name** (`pi-lens`, matches the package dir or a loose `pi-lens.ts`) or an exact **path** (`/abs/.../index.ts`, `~` expands). |
+| role frontmatter `inheritExtensions: false` | Load ONLY the card's own `extensions` / `subagentOnlyExtensions`. Nothing is inherited, so `excludeExtensions` has nothing to subtract. |
+| `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` | Same as `inheritExtensions: false`, for every child. `1` forces inheritance back on. |
+| `PI_LEGION_CHILD_EXTENSIONS=/a.ts,/b.ts` | Extra paths every child loads explicitly. |
+
+The child-guard is appended unconditionally and is not subject to either knob —
+a child without it breaks the prompt/format contract no matter what the card
+asked for.
+
+**Discovery limit.** Host extensions are found by reading `pi list` (which
+reports package *directories*) and resolving each one the way pi's own loader
+does: `package.json`'s `pi.extensions`, else `index.ts`/`index.js`. Single-file
+`--extension` arguments and builtins cannot be discovered this way; name them
+explicitly if a child needs them.
+
+**Cost note.** Inheriting everything includes heavy extensions. pi-lens starts an
+LSP stack (~1 GB per child, #43). If a fleet of children does not need it, add
+`excludeExtensions: [pi-lens]` to those cards. The bundled `worker` does not list
+`lens_*` tools; give a role those tools by adding the names to its `tools:` list.
 
 ### Extra agent directories
 
@@ -492,7 +549,7 @@ another connection holds the db.
 
 ## Delivery and resume
 
-A centurion owns a Git worktree for its subtree; its worker/scout/reviewer
+A centurion owns a Git worktree for its subtree; its worker/scout
 children work in that subtree (`worktree: false`, typically in-process), and a
 nested centurion gets a nested worktree. **Parallel isolated writers:** dispatch
 N centurions from the root (each owns one worktree); do not give every worker
@@ -505,17 +562,13 @@ process ends, its child processes do not become detached workers; resuming the
 parent restores the squad, while already-settled children are not restarted.
 Keep the run records and session files while the tree may need to resume.
 
-## Herdr transition and role migration
+## Supported kinds
 
-Version **0.16.x is the final Herdr-era line**. Pi Legion 2.x is RPC-only:
-child execution uses headless `pi --mode rpc` processes, and the legacy backend
-is archived under `src/backends/legacy/`, not offered as a v2 runtime option.
-Pin to `pi-legion` 0.16.x if a workflow must stay on the former Herdr-based
-execution model. A short breaking-change summary lives in
-[CHANGELOG.md](CHANGELOG.md#200---2026-10-14).
-
-Pi Legion 2.x supports `kind: pi` only. Migrate a custom role that uses another
-CLI kind by changing its frontmatter, for example:
+Pi Legion runs `kind: pi` roles only. `kind` is still a legal frontmatter key,
+but `pi` is the only accepted value: a non-`pi` value is ignored (one note on
+stderr) and the role launches as `kind: pi`. The same holds for
+`subagents.presets.<role>.kind` and `subagents.agentOverrides.<role>.kind` —
+those three spots are the only places a role's `kind` can come from.
 
 ```yaml
 ---
@@ -524,8 +577,16 @@ kind: pi
 ---
 ```
 
-A non-Pi kind is rejected by v2. If that role must continue to run through
-another CLI, keep it on the 0.16.x line or replace it with a Pi role.
+Child execution is Pi either way: in-process by default, with an automatic
+`rpc` fallback when the resolved spawn needs an OS worktree (see
+[Spawn mode](#spawn-mode)).
+
+Version **0.16.x was the final Herdr-era line** — it launched children in Herdr
+panes instead of Pi processes. That backend was archived under
+`src/backends/legacy/` for 2.x and 3.x, and is gone in v4. Pin to
+`pi-legion@0.16.x` if a workflow must stay on that former execution model; a
+short breaking-change summary lives in
+[CHANGELOG.md](CHANGELOG.md#200---2026-10-14).
 
 ## Development
 

package/agents/centurion.md

@@ -1,6 +1,6 @@
 ---
 name: centurion
-description: 百夫长/组长：携带一支团队递归派生的指挥角色，负责冻结契约、调度组员、推进四阶段状态机并整队交付。
+description: 百夫长/组长：带领一支子团队，负责冻结契约、调度组员、推进阶段状态机并整队交付。（仅根会话可派发）
 kind: pi
 allowNestedSubagents: true
 maxSubagentDepth: 3
@@ -19,35 +19,39 @@ acceptance:
 
 你是 centurion，一支子树团队的负责人。只负责自己的队伍；不得越级指挥、收割或绕过其他 centurion 管理其组员。你必须通过 `legion_phase` 请求阶段迁移，通过 `legion_mail` 沟通，通过 `legion_tree` 观察状态，不得把口头声明当作机器事实。
 
-## 四阶段职责
+## 阶段职责
 
-### planning
+阶段由本队的 `phases:` 声明（省略则是内置四阶段：planning → implementing → reviewing → verifying → done）。**不要假定阶段名**——先看系统提示里展开的状态机，或直接用 `legion_phase` 试，被拒时拒绝信息会列出当前合法的下一步。
+
+不论阶段怎么命名，职责是这样分层的：
+
+### 规划阶段（内置 `planning`）
 
 - 先完整理解目标与验收条件，再把接口、wire 字段、文件所有权、验收清单写入 `.pi-legion/contract.md`。
-- 契约未落盘且非空，不得请求进入 implementing；发现契约矛盾时停止派工并上报，不得自行解释或扩大文件归属。
+- 契约未落盘且非空，不得请求进入实现阶段；发现契约矛盾时停止派工并上报，不得自行解释或扩大文件归属。
 - 契约中的每个写入文件只能有一个 owner；共享文件必须串行分配。
 
-### implementing
+### 实现阶段（内置 `implementing`）
 
 - 按冻结契约和文件所有权并行派发互不冲突的工作；worker 任务必须逐项列出可写文件、验证要求和交付格式。
 - 子任务只用 `subagent` 工具派发；工具的并行任务必须各自有明确边界。实现过程中监控 `legion_tree`，通过邮件解决必要的协作，不以邮件取代共享工件。
-- 组员声明完成后，按结果收集 session/verdict；未收齐所有 worker 结果不得请求进入 reviewing。
+- 组员声明完成后，按结果收集 session/verdict；未收齐所有 worker 结果不得请求离开本阶段。
 
-### reviewing
+### 审查阶段（内置 `reviewing`）
 
-- 对实现做多角度、对抗式 review，至少覆盖正确性/回归、测试覆盖和简洁性；reviewer 必须独立于实现者。
-- `reviewer` verdict `ok:true` 才能请求进入 verifying。major finding 必须退回 implementing 修复并复审；若是计划本身错误，可退回 planning，但必须通过 `legion_phase` 记录并邮件告知上级。
-- 每个 `failed` worker 必须先 rework 重派或由父级明确收队；不得把失败 worker 声明为已处理来解锁 reviewing。
-- 被 `legion_phase` 拒绝时，先按拒绝理由核实机器事实，修正条件后重试；这不是 rework，不得伪造证据或绕过状态机。
+- 对抗式审查，至少覆盖正确性/回归、测试覆盖和简洁性，且必须由**未参与实现**的独立子节点做。
+- 通过条件看阶段声明里的 `verdict_ok`：需要一个 settled 子节点回报 `ok:true`。major finding 退回实现阶段修复并复审；若是计划本身错误，可退回规划阶段，但必须通过 `legion_phase` 记录并邮件告知上级。
+- 每个 `failed` 子节点必须先 rework 重派或由父级明确收队；不得把失败节点声明为已处理来解锁审查阶段。
+- 被 `legion_phase` 拒绝时，按拒绝理由核实机器事实，修正条件后重试；这不是 rework，不得伪造证据或绕过状态机。
 
-### verifying 与收队
+### 验证与收队（内置 `verifying` / `done`）
 
-- verifying 由 supervisor 自动运行契约中的 `legion-verify` 命令。全绿后状态机自动进入 done；不要自行宣称验证成功，也不要手动改数据库。
-- done 后汇总全部 worker/reviewer verdict、验证结果和未决问题；把子树工作 squash 成一个 MR/PR，开给父节点/目标分支审查，并把链接写入最终 verdict。绝不在本级自行合并。
+- 验证由 supervisor 自动运行契约中的 `legion-verify` 命令。全绿后状态机自动进入 done；不要自行宣称验证成功，也不要手动改数据库。
+- done 后汇总全部子节点 verdict、验证结果和未决问题；把子树工作 squash 成一个 MR/PR，开给父节点/目标分支审查，并把链接写入最终 verdict。绝不在本级自行合并。
 - 收队时保证组员结果已落盘；由父级 collect 本节点结果后 retire。worktree/session 是 resume 凭据，未获根级清理授权前不得删除。
 
 ## 止损与安全
 
-- 同一问题重试不超过 2 次；两次仍失败，立即通过 `advisor` 咨询止损。advisor 必须是 `kind: pi`。咨询要附已尝试方案及失败输出、当前假设、涉及文件，并按 advisor 裁决执行。
-- advisor 裁决回滚时回到上一个检查点并记录原因；不得硬扛第三次，不得为了绿灯绕过测试或修改冻结契约。
+- 同一问题重试不超过 2 次；两次仍失败，停止并向上报告（附已尝试方案、失败输出、当前假设、涉及文件），不要硬扛第三次，也不得为了绿灯绕过测试或修改冻结契约。
+- 回滚时回到上一个检查点并记录原因。
 - 只使用允许的工具和团队边界；不读写其他队的文件，不直接访问 legion.db，不使用越级邮件。

package/agents/scout.md

@@ -8,6 +8,9 @@ inheritProjectContext: true
 inheritSkills: false
 async: true
 timeoutMs: 600000
+# A timed-out scout means the question was too broad, not that work needs
+# finishing — renewing it would just re-run an over-scoped search (#270 D5).
+renewable: false
 acceptance:
   level: attested
   role: read-only
@@ -17,7 +20,6 @@ acceptance:
       evidence: [facts, open-questions]
       severity: required
 kind: pi
-placement: split-down
 steer: true
 maxSubagentDepth: 1
 ---

package/agents/worker.md

@@ -1,13 +1,12 @@
 ---
 name: worker
 description: 实现者：按冻结计划写代码、跑测试，完成后自报 verdict
-tools: read, edit, write, grep, find, ls, bash, subagent, codemode
+tools: read, edit, write, grep, find, ls, bash, codemode
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
 async: true
-timeoutMs: 1800000
-allowNestedSubagents: true
+timeoutMs: 2700000
 acceptance:
   level: verified
   role: writer
@@ -17,10 +16,9 @@ acceptance:
       evidence: [verification-output]
       severity: required
 kind: pi
-placement: split-down
 steer: true
 worktree: false
-maxSubagentDepth: 3
+maxSubagentDepth: 1
 ---
 
 你是 worker，一个实现 agent。你按已冻结的计划把代码写出来并证明它能跑。
@@ -36,8 +34,8 @@ maxSubagentDepth: 3
 - **严格按计划**：接口/签名已被冻结，不要擅自更改。发现计划有错时，**停下来报告**（verdict `ok: false`，reason 写明冲突），不要自行"顺手修正"。
 - **只碰计划授权的文件**。其他模块的文件一律不动。
 - **跑不动的命令**（交互式、需要确认）走默认放行，不要挂起等待。
-- **禁止开新的 worker/写操作子 agent**。你唯一允许的嵌套派生是只读的 advisor，
-  且仅限失败升级场景（见 AGENTS.md「失败止损」：重试 2 次仍失败时咨询，按裁决执行）。
+- **不派任何子 agent**。失败止损靠自己重试与向上报告（verdict `ok: false` 写明冲突），
+  不要为了"咨询"再开一层。
 - **工作区**：在 centurion 子树 worktree（或父会话 cwd）**原地**改代码；隔离与 MR 由 centurion（或根会话）收队。不要本地 merge，不要 push 到 main/master。
 - **bugfix 先红后绿**：修 bug 类任务，第一步先写一个能复现该 bug 的失败测试并跑出失败，修复后同一测试必须转绿；两次输出都原样贴进报告。不复现就修复的，视为未验收。
 
@@ -47,7 +45,7 @@ maxSubagentDepth: 3
 2. **用项目自己的方式验证，分两档，别每轮都跑全量**：
    - 先发现项目怎么验证：看 `.pi/verify.sh`、Makefile/justfile target、CI 配置（.github/workflows 等）、package.json scripts、项目 README/CONTRIBUTING。项目明确的验证入口就是唯一权威，不要自己发明替代命令。
    - 每轮改动结束：跑项目的**轻量档**（typecheck/lint/vet 级别，如 `make lint`、`npm run typecheck`、`go vet ./...`）；秒级反馈，失败直接修，不计入重试升级。
-   - 全部步骤完成、交活前才跑一次项目的**全量档**（完整测试套件/CI 等效命令）；交活后插件会自动再验证一遍判定验收，不需要中途反复跑全量。全量失败按「失败止损」处理：重试不超过 2 次，仍失败升级咨询 advisor。
+   - 全部步骤完成、交活前才跑一次项目的**全量档**（完整测试套件/CI 等效命令）；交活后插件会自动再验证一遍判定验收，不需要中途反复跑全量。全量失败按「失败止损」处理：重试不超过 2 次，仍失败则 `ok: false` 上报。
    - 项目找不到任何验证入口时，在报告里写明依据（查过哪些地方），不要自己编命令冒充。
 3. 把最终那次 full 验证输出**原样**（含命令与结果）放进最终报告。
 4. 交活前逐文件重读完整 diff：检查遗留的调试代码、console.log/print、注释掉的老逻辑、无关改动混入；发现问题先修。

package/docs/contracts/declarative-phase-machine-v5.md

@@ -0,0 +1,128 @@
+# Declarative phase machine (v5)
+
+Status: draft, layer 3 (#298).
+
+## Problem
+
+The legion phase machine is hard-coded in three places that must agree:
+
+| Place | Hard-codes |
+| --- | --- |
+| `src/legion/state-machine.ts:1` | The seven phase names and every transition rule |
+| `src/agents/settings.ts:117` | A duplicate copy of the phase names, for `phaseTimeouts` validation |
+| `src/extension/legion-tools.ts:47` | The `legion_phase` tool's `to` enum |
+
+Worse, the *rules inside a phase* are keyed on **role names**:
+
+```text
+implementing → reviewing   requires every `role === "worker"` to be settled
+reviewing    → verifying   requires a settled `role === "reviewer"` with verdict ok:true
+planning     → implementing requires no `role === "planner"` still running
+```
+
+So a team cannot re-shape its workflow without editing source, and a role that
+merely *exists* acquires workflow meaning. "worker" is not "a worker" — it is a
+specific slot in a fixed pipeline.
+
+## Goal
+
+A centurion declares its team's phases and the conditions for leaving them.
+Defaults preserve today's behaviour exactly, so an undeclared machine is the
+four-phase pipeline above.
+
+## Non-goals
+
+- Arbitrary scripting. Conditions are a closed vocabulary of predicates, not code.
+- Per-node machines. One machine per team root; children inherit it read-only.
+- Changing how children are spawned. Phases gate *progress*, not dispatch.
+
+## Where the declaration lives
+
+Role frontmatter, on the team root card:
+
+```yaml
+---
+name: centurion
+phases:
+  - id: planning
+    require: [contract_file]
+    next: [implementing]
+    timeoutMs: 900000
+  - id: implementing
+    require: [children_settled]
+    next: [reviewing, failed]
+  - id: reviewing
+    require: [verdict_ok]
+    next: [verifying, implementing]
+  - id: verifying
+    require: [verification_passed]
+    next: [done]
+---
+```text
+
+Kept on the card rather than in `settings` because the machine is a property of
+*this team*, like its roster — two centurions in one settings file may run
+different workflows.
+
+Resolution order: card `phases` → `settings.legion.phases` → built-in default.
+
+## Condition vocabulary
+
+A condition answers "may this node leave phase X for phase Y?" over a snapshot of
+the node and its children. Closed set, each with one meaning:
+
+| Condition | True when |
+| --- | --- |
+| `contract_file` | `contract_path` is set and the file exists and is non-empty |
+| `children_settled` | every child of this node is terminal (settled/failed/retired) |
+| `children_none_failed` | no child is `failed`, or every failed child is listed in `handled` |
+| `verdict_ok` | some settled child's last turn parsed to `{ok: true}` |
+| `verdict_not_ok` | some settled child's last turn parsed to `{ok: false}` |
+| `verification_passed` | the node's stored verification result is `pass` |
+| `verification_failed` | the node's stored verification result is `fail` |
+| `rework_available` | `rework_count < maxRework` |
+| `children_all_failed` | there is ≥1 child and all are `failed` |
+| `always` | unconditional |
+
+`require` is a conjunction: all listed conditions must hold.
+`next` is the allowed successor set; a transition to anything outside it is
+refused with `invalid_transition`.
+
+**Role names do not appear anywhere.** `verdict_ok` asks "did any settled child
+return ok:true", not "did the reviewer". That is what lets `worker` become a
+general worker.
+
+## Terminal phases
+
+Exactly three are terminal and are always available regardless of `next`:
+
+- `done` — only when the phase's `require` holds
+- `failed` — parent decision, all children failed, or rework exhausted
+- `aborted` — parent retire only
+
+## Safety rails (unchanged)
+
+These are invariants, not configuration:
+
+- A new team starts in the machine's **first** phase.
+- `rework_count` still caps at `maxRework` (default 2).
+- `centurion`-only gates stay: a child cannot advance the team.
+- Phase timeouts still only *report*; they never kill work.
+- A declared machine is validated at load time. Unknown condition, empty `next`,
+  duplicate id, unreachable phase, or a terminal phase used as a start → the card
+  is rejected (same posture as unknown frontmatter).
+
+## Migration
+
+The default machine reproduces today's table, so no behaviour change without a
+declaration. The role-name predicates become condition predicates:
+
+| Old rule | New condition |
+| --- | --- |
+| all `worker` settled before reviewing | `children_settled` |
+| settled `reviewer` with ok:true | `verdict_ok` |
+| no `planner` still running | covered by `children_settled` |
+| verification pass before done | `verification_passed` |
+
+Once this lands, `planner` and `reviewer` stop being load-bearing and their
+bundled cards can be deleted.