pi-plans 0.6.0 → 0.7.0

package/references/pi-planning-workflow.md

@@ -9,17 +9,17 @@ This skill set is written for the Pi coding agent's documented behavior:
 - the five skills are contributed by the pi-plans extension and loaded as Pi skills (also invokable as `/skill:<name>`);
 - skill references and helper sources are resolved relative to the directory containing `SKILL.md`;
 - Planning and reference analysis run with the extension tools `plans`, `ask_choice`, `refine`, `analyze_refs`, and `execute_plan`;
-- `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` for both roles when workspace `graph_enabled` is true) with isolated context; delegated Reviewer/Criticizer runs show a standalone aggregate overlay titled `Reviewer` or `Criticizer` (78% × 78% top-center, ≥72 cols, no input row), stream assistant/thinking/tool events into per-lane transcripts with follow-bottom scroll, dismiss on `Esc` (close-only — the refiner child keeps running and its result still flows back as tool output), replace any retained finished overlay when a new round begins, and return conclusions to the main session as tool output; `analyze_refs` spawns one read-only subagent per downloaded reference (cwd = that ref's directory) reusing the reviewer role gates, shows the same overlay titled `Refs` in batches of at most 3 lanes, and returns structured per-reference sections for `REF_ANALYSIS.md`;
+- `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` when workspace `graph_enabled` is true) with isolated context; delegated reviewer runs show a standalone aggregate overlay titled `Reviewer` (78% × 78% top-center, ≥72 cols, no input row), stream assistant/thinking/tool events into per-lane transcripts with follow-bottom scroll, dismiss on `Esc` (close-only — the refiner child keeps running and its result still flows back as tool output), replace any retained finished overlay when a new round begins, and return conclusions to the main session as tool output; `analyze_refs` spawns one read-only subagent per downloaded reference (cwd = that ref's directory) reusing the reviewer role gates, shows the same overlay titled `Refs` in batches of at most 3 lanes, and returns structured per-reference sections for `REF_ANALYSIS.md`;
 - when graph mode is enabled, graph-aware `read`/`edit` overrides are active for indexed source files: `read` returns a capped function digest (≤50 lines, synthetic anonymous entries folded) by default — drill in via `offset/limit` or `code_graph get-function`, and `full: true` is the only whole-file exit (small/zero-function files return full text; safety truncation matches native read); `write`/`edit` stage DB-first mutations until materialized via the `code_graph` tool's `apply` action (same planning/accepted gate as /apply-graph; refused for read-only refiner subagents via the PI_PLANS_REFINER marker; returns a per-file report with counts and a post-apply drift summary, and never changes run status); unexpected fallbacks (`not indexed` / `runtime unavailable` / `config read failed`) are marked at the top of the result while flag-off fallbacks stay unmarked;
-- the execution loop is extension-managed: remaining verifier items are injected each turn, implementation items emit `[I-###:current]`/`[I-###:implemented|validating]`, and `[DONE:VC-xxx]` markers are tracked with a bottom status bar;
+- the execution loop is extension-managed and task-tree driven: the current wave and remaining tasks are injected each turn, progress is reported exclusively through the `plans_update_task` tool (status + evidence / skipReason), the task dashboard tracks every task (compact widget; Ctrl+Shift+T expands the tree), and an independent completion auditor verifies the verification checks before the run completes;
 - execution and planning compaction keep Pi's SessionManager as the history owner; during active pi-plans runs, `session_before_compact` uses a deterministic no-LLM VCC-style summary with `[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, `[User Preferences]`, and a ranked brief transcript; Pi core owns manual `/compact`, threshold, and overflow scheduling, while pi-plans handles smart tail keep, `keep:N`, stats, and phase-specific run/plan/current-I/checklist context; in addition, creating a new planning run (`plans start-run`) proactively requests one pre-plan VCC compaction before the first planning question and resumes the planning turn with a hidden message (default on, `prePlanCompact` in `pi-vcc-config.json`);
 
 ## Planning Boundary
 
 - Treat the user's request as a planning target, not as write authorization.
-- Before the execution handoff, do not edit target source files, docs, configs, package metadata, generated assets, or tests outside the planning artifact directory and the pi-plans state under `.git/pi_plans/`. The extension enforces this for `edit` and `write` while a run is active: only `.git/pi_plans/`, the run's artifact directory, `~/.cache/pi-plans/`, and the configured refs root are writable. Bash is not machine-guarded — keep it read-only by discipline (inspection, `git init`, downloads into the cache).
-- The normal pre-handoff writes are `.git/pi_plans/` state plus planning artifacts under the configured artifact root (default `./docs/pi-plans/...`).
-- Downloaded references go to the workspace's configured refs root (`refs_root` in `.git/pi_plans/config.json`; unset → ask once via `ask_choice`, recommended `.git/pi-plans/refs/`, second `./refs/`, third `~/.cache/pi-plans/refs/`; persist with the `plans` tool, `set-refs-root`) and their paths and evidence are recorded in `REF_ANALYSIS.md`. References are not limited to GitHub repositories: papers (arXiv etc.), engineering blogs, and documentation sites are first-class, with per-medium qualified downloads (repo = clone; paper = full text — abstracts never qualify; blog/docs = full-article markdown) and one directory per reference; theoretical references count exactly as much as implementation references. plan-normal and plan-big may optionally cite 1–2 search-found references (URLs in the plan's Evidence section) without downloading them.
+- Before the execution handoff, do not edit target source files, docs, configs, package metadata, generated assets, or tests outside the planning artifact directory and the pi-plans state under `.git/pi-plans/`. The extension enforces this for `edit` and `write` while a run is active: only `.git/pi-plans/`, the run's artifact directory, `~/.cache/pi-plans/`, and the configured refs root are writable. Bash is not machine-guarded — keep it read-only by discipline (inspection, `git init`, downloads into the cache).
+- The normal pre-handoff writes are `.git/pi-plans/` state plus planning artifacts under the configured artifact root (default `./.git/pi-plans/plans/...`).
+- Downloaded references go to the workspace's configured refs root (`refs_root` in `.git/pi-plans/config.json`; unset → ask once via `ask_choice`, recommended `.git/pi-plans/refs/`, second `./refs/`, third `~/.cache/pi-plans/refs/`; persist with the `plans` tool, `set-refs-root`) and their paths and evidence are recorded in `REF_ANALYSIS.md`. References are not limited to GitHub repositories: papers (arXiv etc.), engineering blogs, and documentation sites are first-class, with per-medium qualified downloads (repo = clone; paper = full text — abstracts never qualify; blog/docs = full-article markdown) and one directory per reference; theoretical references count exactly as much as implementation references. plan-normal and plan-big may optionally cite 1–2 search-found references (URLs in the plan's Evidence section) without downloading them.
 - After the user explicitly approves the execution handoff, leave this planning workflow and execute in the extension-managed loop (see Execution Handoff).
 
 ## State And Settings
@@ -30,13 +30,13 @@ Before the first planning question, read `references/state-and-config.md` and in
 { "action": "init", "workdir": "<target-workdir>" }
 ```
 
-State lives under the workspace's resolved git common dir as `.git/pi_plans/` (auto-ignored, no `.gitignore` entries; the tool auto-runs `git init` when the workdir safely has no repository). The target workspace is the current working directory unless the user explicitly names another repository.
+State lives under the workspace's resolved git common dir as `.git/pi-plans/` (auto-ignored, no `.gitignore` entries; the tool auto-runs `git init` when the workdir safely has no repository). The target workspace is the current working directory unless the user explicitly names another repository.
 
-If `language.tag` is missing from `.git/pi_plans/config.json`, ask the language setting question (via `ask_choice`) before any product question. Persist it with `plans` (`set-language`); this question does not count against the planning-question limit.
+If `language.tag` is missing from `.git/pi-plans/config.json`, ask the language setting question (via `ask_choice`) before any product question. Persist it with `plans` (`set-language`); this question does not count against the planning-question limit.
 
-If `artifact_root_source` is missing from `.git/pi_plans/config.json` or is `unset`, ask the planning docs location question (via `ask_choice`) before any product question. Persist it with `plans` (`set-artifact-root`); this question does not count against the planning-question limit.
+If `artifact_root_source` is missing from `.git/pi-plans/config.json` or is `unset`, ask the planning docs location question (via `ask_choice`) before any product question. Persist it with `plans` (`set-artifact-root`); this question does not count against the planning-question limit.
 
-Reviewer and criticizer settings also live in `config.json`. If a role's mode is missing/invalid or its `confirmed_at` is `null` when the role is about to run, ask the matching role-setting or model-confirmation question (via `ask_choice`), persist with `plans` (`set-role`), and then run the `refine` tool. The `refine` tool refuses to spawn until the gates pass.
+The reviewer role lives in the GLOBAL config (`~/.pi/pi-plans/config.json`, `PI_PLANS_GLOBAL_DIR` override — one confirmation for every workspace). If its mode is missing/invalid when a round is about to run, ask the role-setting question via `ask_choice` and persist with `plans` (`set-role`). The model + thinking level are confirmed at first use through NATIVE panels, not ask_choice: in TUI the `refine` gate itself pops a searchable model panel followed by an effort panel (Default row = no `--thinking` flag; other rows follow the chosen model's `thinkingLevelMap`) and continues the same invocation on completion; hasUI non-TUI sessions get native menus; UI-less sessions get text guidance embedding the available selectors. Esc cancels the whole gate (nothing persisted; do NOT re-ask via ask_choice — suggest `/config-pi-plans`). The `refine` tool refuses to spawn until `reviewerReady` passes (current-session, or delegated with a confirmed concrete `provider/model`). (v0.6.1: the criticizer role is gone — the reviewer emits findings AND questions in one round.)
 
 ## First-Turn Contract
 
@@ -59,7 +59,7 @@ When the recommended option depends on a web-verifiable claim, search first (web
 
 Every user-facing planning or refinement question goes through the `ask_choice` tool:
 
-- `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with a `description` of the form `✓ <advantage> / ✗ <drawback>` — **every option you author states both what it gains and what it costs**, in the configured language, tersely (≈8 words per half; write `—` when a side is genuinely absent). Both halves live in the single `description` string; there are no separate `pros`/`cons` fields. This rule covers every AI-written option, including the scope confirmation, the merged accept/execute handoff, and the implementation-review setup questions; only the tool-appended `Other…` / `Auto-complete` / `Auto-refine loop` rows are exempt;
+- `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with a `description` of the form `✓ <advantage> / ✗ <drawback>` — **every option you author states both what it gains and what it costs**, in the configured language, tersely (≈8 words per half; write `—` when a side is genuinely absent). Both halves live in the single `description` string; there are no separate `pros`/`cons` fields. This rule covers every AI-written option, including the scope confirmation and the merged accept/execute handoff; only the tool-appended `Other…` / `Auto-complete` rows are exempt;
 - do not add `Other` or `Auto-complete` yourself — the tool appends `Other…` second-last and `Auto-complete` last;
 - pass `autoComplete: false` for the merged accept/execute question — it contains the execution approval, so Auto-complete never appears there — and for any install waiver, publishing, deployment, merge, push, credential, or external-state question. Auto-complete may choose the recommended planning or refinement option only.
 - When the user selects Auto-complete, it remains active for the current planning run: later eligible questions use their recommended options automatically, and the extension queues one deduplicated follow-up if the model stops after an auto-completed answer. `/plans-autocomplete-stop` disables it; session restore may reactivate it only for the same active run while its status is `planning`.
@@ -74,9 +74,9 @@ Create a run only after initial read-only inspection makes the topic clear:
 { "action": "start-run", "workdir": "<target-workdir>", "topic": "<short topic>", "skill": "<skill-name>", "requestText": "<original request>" }
 ```
 
-The tool creates the configured artifact directory root (default `./docs/pi-plans/YYYY-MM-DD-<topic>/`) and the private run state `.git/pi_plans/runs/<run-id>/`, and stores the active run pointer. Use a short lowercase slug for the topic. Keep paths stable once written.
+The tool creates the configured artifact directory root (default `./.git/pi-plans/plans/YYYY-MM-DD-<topic>/`) and the private run state `.git/pi-plans/runs/<run-id>/`, and stores the active run pointer. Use a short lowercase slug for the topic. Keep paths stable once written.
 
-`DECISIONS.md` records: original request; repository evidence inspected; each question, options, selected answer, and whether it came from the user or Auto-complete; assumptions still open; external sources consulted; language, reviewer, and criticizer settings used.
+`DECISIONS.md` records: original request; repository evidence inspected; each question, options, selected answer, and whether it came from the user or Auto-complete; assumptions still open; external sources consulted; language and reviewer settings used.
 
 ## Final Scope Confirmation
 
@@ -91,15 +91,15 @@ If the user adds requirements, resolve only the necessary follow-up questions, t
 
 ## Plan Artifact Requirements
 
-Every `PLAN_vN.md` must include stable IDs that are never recycled across revisions: goals and non-goals; requirements and constraints; implementation items; affected paths; dependencies and sequencing; risks and mitigations; acceptance criteria; verification steps; repo and external evidence; resolved decisions; revision ledger.
+Every `PLAN_vN.md` must include stable IDs that are never recycled across revisions: `Task-N` tasks (with deps/files/wave and one subtask level), `VC-###` verification checks, and the revision ledger. Everything else the workflow needs lives in the run state (decisions ledger, review rounds, refs), not in the plan file.
 
-Every plan version must include a dedicated `## Verifier Checklist` section. Each item is a Markdown checkbox of the exact shape:
+Every plan version's body is exactly two sections — `## Tasks` and `## Verification Checks` — plus the metadata header (see `references/plan-artifact-template.md` for the full microsyntax: `Task-N` ids, one subtask level, inline `deps:`/`files:`/`wave:` fields, the `### Execution Waves` subsection, and lint rules). Each verification check is a Markdown checkbox of the exact shape:
 
 ```markdown
-- [ ] `VC-001` covers `I-001`; pass condition: ...; evidence: ...; metric: <threshold or reason not quantified>.
+- [ ] `VC-001` covers `Task-1`; pass condition: ...; evidence: ...; metric: <threshold or reason not quantified>.
 ```
 
-The execution loop parses `- [ ] \`VC-###\`` items and tracks `[DONE:VC-###]` markers, so keep IDs on the checkbox line. Use `references/plan-artifact-template.md` when drafting.
+The execution loop parses `- [ ] \`VC-###\`` checks and the task tree, so keep IDs on the checkbox line and the task grammar exact; task progress flows through `plans_update_task` and the completion auditor reads these checks. Use `references/plan-artifact-template.md` when drafting.
 
 ## Refinement
 
@@ -109,78 +109,62 @@ After each plan version, ask one merged accept/execute question via `ask_choice`
 2. `Accept PLAN_vN, don't execute yet` — mark accepted; resume later via `/plans-execute`.
 3. `Run another round: <the level's default next refine mode>` — only while the level's default sequence is unfinished.
 
-The recommended option follows the skill level's default sequence: while the default rounds are unfinished it is option 3's default next mode (`plan-small`: `Criticizer`; `plan-normal`: `Reviewer` then `Criticizer`; `plan-big`: three concurrent reviewers (`refine` with `reviewers: 3`) then `Criticizer`); once the default sequence is complete it is option 1.
+The recommended option follows the skill level's default sequence: while the default round is unfinished it is option 3 (`plan-small` / `plan-normal`: one reviewer round; `plan-big` / `plan-with-refs`: three concurrent reviewers via `refine` with `reviewers: 3`); once the default round is complete it is option 1. Every round returns findings (`F-###`) and up to five questions (`Q-1..Q-5`) in the same output.
 
-If the user selects `Reviewer` or `Criticizer`, run the `refine` tool with the plan path and any focus. Reviewer output consolidates into `PLAN_vN_reviewer_comments.md` with findings IDs, severity, affected plan IDs, evidence, impact, recommended fix, and disposition. Revise the next plan only for findings accepted on evidence.
+If the user selects another round, run the `refine` tool with the plan path and any focus. Reviewer output consolidates into `PLAN_vN_reviewer_comments.md` with findings IDs, severity, affected plan IDs, evidence, impact, recommended fix, and disposition. Revise the next plan only for findings accepted on evidence.
 
 ### Concurrent Reviewers (big plans)
 
 A big-plan reviewer round runs three independent reviewer subagents (`reviewers: 3`); each gets its own emphasis lens but forms its own priorities. After they return, merge and dedupe their findings into one consolidated `PLAN_vN_reviewer_comments.md`, keeping each finding's source reviewer, severity, evidence, and disposition, and surface at most five high-priority comments to the user. Treat agreement between independent reviewers as stronger evidence, not as authority; every accepted finding still needs repo or reference evidence.
 
-### Criticizer Rounds
+### Reviewer Questions
 
-Present each criticizer question with `ask_choice` (one call per question, in the configured language). Before each question, summarize the original criticism in at most three sentences and highlight the most important point. Do not revise the plan until every criticizer question has a recorded answer.
+Merge the rounds' `Questions` sections into one deduped list and ask EVERY question with `ask_choice` (one batched `questions: [...]` form or one call per question, in the configured language, stable questionIds). Do not revise the plan until every reviewer question has a recorded answer.
 
 ### Round Lifecycle
 
-A refinement round is complete when all reviewer outputs have returned or all criticizer questions have answers. In the same turn: consolidate, accept or reject each finding on evidence (the user may override any disposition), revise to `PLAN_v(N+1).md` when accepted items require it (copy, edit only the new version, update the revision ledger and verifier checklist), then immediately ask the next merged accept/execute question. Never end a turn merely because a round completed.
+A refinement round is complete when all reviewer lanes have returned; each lane's output carries findings (`F-###`) and up to five questions (`Q-1..Q-5`). In the same turn: consolidate, accept or reject each finding on evidence (the user may override any disposition), revise to `PLAN_v(N+1).md` when accepted items require it (copy, edit only the new version, update the revision ledger and verifier checklist), then immediately ask the next merged accept/execute question. Never end a turn merely because a round completed.
 
 ## Execution Handoff
 
-When the user picks `✓ Accept PLAN_vN and execute it now` in the merged question, mark the plan accepted and call the `execute_plan` tool (or the user runs `/plans-execute`). It re-confirms with the user, asks which runtime executes the plan (v0.6.0), then the extension enters execution mode:
+When the user picks `✓ Accept PLAN_vN and execute it now` in the merged question, mark the plan accepted and call the `execute_plan` tool (or the user runs `/plans-execute`). It re-confirms with the user (never auto-completed), then the extension enters task-tree execution mode:
 
-- every agent turn is injected with the remaining verifier checklist and execution rules (layered simplest implementation, waiting for subprocess-backed verification with backoff 5s -> 10s -> 20s -> 40s -> 80s, then keep polling at 80s and restart at 5s for each new subprocess, no stopgaps, dependency and library discipline, minimum tests);
-- the runtime question offers ① the current session (recommended — injected checklist loop) and ② switching to another model; switching lists at least three `provider/model` switch targets (session-visible models plus the model registry, deduped, current excluded — `Other` free input when fewer exist) and runs ONE delegated executor subagent for the whole plan: native write tools, `PI_PLANS_EXECUTOR=1` + pinned `PI_PLANS_RUN_ID`, progress streamed into an `Executor` overlay while the parent parses `[DONE:VC-xxx]` markers from the child's full-text messages; Esc or `/plans-stop` kills the child and marks the run `stopped` (resumable under either runtime); under auto-approve or no-UI the question is skipped (current session, `[auto-approve]` recorded); implementation-review rounds keep the configured reviewer model;
-- execution-phase compaction is handled only when Pi core emits manual `/compact`, threshold, or overflow events; summaries are deterministic VCC-style summaries, include session-derived plan/current-I/checklist context, use smart tail keep and `keep:N`, and never call a model or request proactive current-I compaction;
+- every agent turn is injected with the current wave's open tasks, the remaining task list, verification-check summary, and execution rules (wave order, `plans_update_task` reporting with status + evidence / skipReason, subprocess polling backoff 5s -> 10s -> 20s -> 40s -> 80s then keep polling at 80s, no stopgaps, dependency and library discipline, minimum tests);
+- task progress flows exclusively through the `plans_update_task` tool: one call per task closing it as `complete` (with evidence) or `skipped` (with skipReason); closed statuses are immutable outside the audit-authorized rollback channel; subtasks close before their parent;
+- the task dashboard tracks the whole tree live: a compact aboveEditor widget (current task ▸, progress bar, ✓/· counts, VC pass count, wave indicator, pause state, audit-failure line) and the Ctrl+Shift+T expanded tree view (✓/▸/~/· markers, current-task anchor, VC list with audit state, width-adaptive layout);
+- a stall watchdog pauses execution after three consecutive settled rounds without any task-status change (genuine user input or `/plans-execute` resumes without losing progress);
+- when every task reaches a terminal state, an independent read-only completion auditor verifies each check against the worktree: failed checks roll their covered tasks (children cascade, skipped tasks reopen) back to pending and inject the audit report; the audit re-runs as tasks re-close; after three failed rounds the run pauses for the user — under auto-approve/headless it terminates as `stopped` with the audit report so pipelines never hang; checks whose covered tasks are all skipped pass as skipped-pass; checks covering no task never enter the audit;
+- execution-phase compaction is handled only when Pi core emits manual `/compact`, threshold, or overflow events; summaries are deterministic VCC-style summaries, include session-derived plan/current-task/checklist context, use smart tail keep and `keep:N`, and never call a model;
 - the read-only guard lifts: full write access returns;
-- the run status moves to `executing`, then `done` when the last `[DONE:VC-xxx]` marker lands;
+- the run status moves to `executing`, then `done` when the completion audit passes;
 - `/plans-stop` stops execution; `/plans` shows progress.
 
 If the user declines, stay in planning (or stop, per their choice). Never start implementation without the approved handoff.
 
-### Execution Goal-Wait
+### Continuation Between Turns
 
-In TUI/RPC, automatic goal-wait is evaluated only at `agent_settled`, after
+In TUI/RPC, automatic continuation is evaluated only at `agent_settled`, after
 Pi has finished natural tool continuation, retries, and compaction. The
-extension rechecks that the same execution is active and incomplete, the
+extension rechecks that the same execution is active with open tasks, the
 session is idle, and neither pending input nor compaction owns continuation.
 Each eligible settled cycle can send at most one hidden custom message with
-the current execution rules and remaining VC checklist. Tool `turn_end`
-events only update progress; they never prequeue goal-wait reminders.
-
-No-progress and literal `waiting for` counters advance only on eligible
-settled cycles. Real marker progress resets both; thresholds remain 3 and 6.
-User interruption and final model errors also pause continuation. Genuine
-interactive/RPC user input or `/plans-execute` can resume a paused active
-execution without losing verified VCs; extension input cannot unpause it.
-New-plan handoffs and the `execute_plan` tool still require explicit approval.
-Completion, stop, and session replacement invalidate the extension's wake
-identity without clearing user or other-extension queues. Print/JSON
-single-shot sessions keep VC tracking and completion but never auto-wake;
+the current execution rules. Tool `turn_end` events only update usage; they
+never prequeue continuation reminders. The stall watchdog counts settled
+cycles without task-state change (threshold 3) and pauses instead of waking;
+user interruption and final model errors pause too. Genuine interactive/RPC
+user input or `/plans-execute` resumes a paused active execution without
+losing task progress; extension input cannot unpause it. New-plan handoffs
+and the `execute_plan` tool still require explicit approval. Print/JSON
+single-shot sessions keep task tracking and completion but never auto-wake;
 use RPC for persistent headless execution.
 
-### Post-Execution Continuation
-
-When execution completes in an interactive session, the completion message attaches a goal-running continuation block and triggers a new agent turn so the model can enter the implementation-review loop immediately. The interactive-only trigger keeps headless sessions silent (no unconsented subagent cost). The same behavior applies on both completion call sites (the normal `turn_end` completion and the `restoreFromSession` recovery path).
-
-The agent then asks two `ask_choice` questions (each single-question, `autoComplete: false`) to configure the implementation-review loop:
-
-1. **Termination condition** (questionId `termination-condition`, recommended first: goal wait) — options: 1. goal wait: continue until no unpassed VCs remain (auto-continue each round) 2. until no high-severity finding (hard cap 5 rounds) 3. 1 round 4. 2 rounds 5. 3 rounds.
-2. **Reviewer count** (questionId `impl-review-reviewer-count`, `allowOther: false`, pure digit labels `1`/`2`/`3`, recommended first): "How many concurrent reviewers should each implementation-review round use?" The recommended default follows the run's skill: `plan-big` / `plan-with-refs` → 3, others → 1.
-
-Both of these setup questions are AI-written options like any other: give each one a `description` of the form `✓ <advantage> / ✗ <drawback>` in the configured language (goal-wait buys thoroughness at the cost of a long run; more concurrent reviewers buy coverage at the cost of tokens), so the trade-off is visible before the user answers.
-
-Both answers persist TOGETHER in one `plans record-checkpoint` (`transition: "implementation-review-configured"`, `terminationCondition` + `reviewerCount`). Each refinement round calls `refine` with `role: "reviewer", target: "implementation", reviewers: <configured reviewerCount>`; an omitted `reviewers` falls back to the run's configured `reviewerCount` from the checkpoint, so restarts and worktree migrations never silently revert 2/3 to 1. Each round accepts findings on evidence, applies fixes, re-runs relevant tests, and records progress. The hard cap is 5 rounds regardless of the chosen termination condition. Multi-reviewer rounds (2 or 3) consolidate like big-plan rounds: merge and dedupe findings into one `PLAN_vN_reviewer_comments.md`, keep each finding's source reviewer, severity, evidence, and disposition, and surface at most five high-priority findings. Crash recovery: if the process dies after one or both answers were recorded in `decisions.jsonl` but before the combined write, `/resume-plans` rebuilds the answered configuration from the ledger, asks only the missing question(s), and then performs the single combined write (the re-ask guard rejects duplicate configuration writes while the fields are already set).
-- Round audit trail: `decisions.jsonl`, `subagents.jsonl`, and `pi-plans-ameliorate` entries (one at goal start, then one per round) carry `currentRound` for post-hoc verification.
-- Headless sessions skip the prompt entirely; no `pi-plans-ameliorate` entry is appended.
-
 `refine` records each round and lane outcome durably (successful outputs are persisted to run-state files before the tool result returns) and accepts `resumeRoundId` to resume an interrupted round lane-by-lane: completed lanes are reused from their persisted outputs and never re-run; a round id is never reused across plan versions.
 
 ## Resuming (`/resume-plans`)
 
-After a restart or in a fresh session, `/resume-plans` (interactive only) restores the repository's working plan in the current session: the unfinished active run wins; otherwise a unique candidate resumes directly and multiple candidates get a chooser. It resumes unfinished planning (re-asks the pending question with the same `questionId`, never re-asks answered decisions), reviewing (resumes interrupted rounds via `refine resumeRoundId`, consolidates completed ones), execution (durable approval: unchanged plan digest keeps the authorization — a changed HEAD re-verifies old VCs first; legacy runs without checkpoints must re-approve), and the implementation-review loop (asks the termination condition and reviewer count only when they were never chosen — answered decisions are rebuilt from the ledger, never re-asked). While the loop is live, the pi-plans panel stays alive as a compact impl-review box (round count, reviewer count or "config pending", termination condition) and the status line mirrors it; once the checkpoint phase flips to `completed` the panel unregisters and the status line shows `(done)`. Linked worktrees share candidates; cross-worktree resumes confirm, copy artifacts without overwriting, reset approval and VC validity, and restart round counts. Record semantic boundaries with `plans record-checkpoint` (`plan-written`, `review-consolidated`, `implementation-review-configured`, `implementation-round-finished`, `completed` with evidence).
+After a restart or in a fresh session, `/resume-plans` (interactive only) restores the repository's working plan in the current session: the unfinished active run wins; otherwise a unique candidate resumes directly and multiple candidates get a chooser. It resumes unfinished planning (re-asks the pending question with the same `questionId`, never re-asks answered decisions), reviewing (resumes interrupted rounds via `refine resumeRoundId`, consolidates completed ones), and execution (durable approval: unchanged plan digest keeps the authorization — a changed HEAD re-opens previously closed tasks for re-verification; an unverifiable approval HEAD behaves the same; legacy runs without checkpoints must re-approve; v0.6.0 delegated-executor orphans require a fresh handoff approval; a legacy `implementation-review` phase maps to done — its historical acceptance stands). Linked worktrees share candidates; cross-worktree resumes confirm, copy artifacts without overwriting, reset approval and VC validity, and restart round counts. Record semantic boundaries with `plans record-checkpoint` (`plan-written`, `review-consolidated`, `completed` with evidence).
 
-`refine` accepts a `target` parameter (`"plan"` default, `"implementation"` for the post-execution loop). The implementation brief anchors findings to the plan's goals and acceptance criteria, explicitly assesses delivery maturity (MVP-only vs. long-term refinement: stopgaps, missing tests, technical debt, production readiness), and tags out-of-scope improvements as low severity.
+`refine` reviews the plan text (the v0.6.0 `target: "implementation"` post-execution loop is gone; the independent completion auditor now gates delivery).
 
 ## Red Flags
 
@@ -189,9 +173,9 @@ Stop and return to the workflow if any of these happen:
 - implementing before the approved execution handoff;
 - running `refine` without first asking the merged accept/execute question, or before the role gates pass;
 - ending a turn after a completed refinement round without asking the next merged accept/execute question;
-- storing planning settings outside the target workspace's `.git/pi_plans/` state directory;
+- storing planning settings outside the target workspace's `.git/pi-plans/` state directory;
 - asking multiple planning questions in one message, or asking them outside `ask_choice`;
 - writing `PLAN_v1.md` before final scope confirmation;
 - accepting vague answers that contradict repo or reference evidence;
-- treating a reviewer or criticizer as authority instead of evidence;
+- treating a reviewer as authority instead of evidence;
 - offering Auto-complete for execution, install, deploy, merge, push, or destructive cleanup approval.

package/references/plan-artifact-template.md

@@ -3,79 +3,90 @@
 Status: draft | reviewed | accepted
 Plan version: N
 Artifact directory: `<artifact_root>/YYYY-MM-DD-topic/`
-State directory: `.git/pi_plans/runs/<run-id>/` (resolved git common dir)
+State directory: `.git/pi-plans/runs/<run-id>/` (resolved git common dir)
 Language: `<BCP47 tag>`
 
 ## Original Request
 
-Summarize the user's request in one paragraph.
+One paragraph summarizing the user's request.
 
-## Goals
+## Tasks
 
-- `G-001`: Goal statement.
+- `Task-1`: <title> — deps: <Task-ids, optional>; files: <paths, optional>; wave: <number, optional>
+- `Task-2`: <title> — deps: Task-1; files: src/a.ts, src/b.ts; wave: 2
+  - `Task-2.1`: <subtask title> — deps: Task-1; files: src/a.ts
+- `Task-3`: <title> — deps: Task-1, Task-2; files: src/c.ts; wave: 3
 
-## Non-Goals
+### Execution Waves
 
-- `NG-001`: Explicitly excluded work.
+- wave 1: Task-1 — <why these can run first / in parallel>
+- wave 2: Task-2 — <files disjoint within the wave; deps satisfied by earlier waves>
+- wave 3: Task-3 — <serial finish>
 
-## Workspace State
+## Verification Checks
 
-- `STATE-001`: `.git/pi_plans/config.json` language, reviewer, and criticizer settings used for this run.
-- `STATE-002`: `.git/pi_plans/runs/<run-id>/run.json` and linked decision/subagent/ref ledgers.
-
-## Repo Evidence
-
-- `E-REPO-001`: Path or command inspected, what it proves, and any uncertainty.
-
-## External Evidence
-
-- `E-EXT-001`: URL or local ref path, what it supports, and date accessed.
-
-## Resolved Decisions
-
-- `D-001`: Question, chosen answer, answer source (user | Auto-complete), and rationale.
-
-## Requirements
-
-- `R-001`: Requirement tied to goals and decisions.
-
-## Constraints
-
-- `C-001`: Compatibility, style, interface, performance, safety, or ownership constraint.
-
-## Implementation Items
-
-- `I-001`: Work item with affected paths, dependencies, and expected code or doc changes.
-
-## Acceptance Criteria
-
-- `AC-001`: Observable result tied to one or more requirements.
-
-## Verification Plan
-
-- `V-001`: Command, manual check, screenshot, log review, or static inspection required after implementation.
-
-## Verifier Checklist
-
-- [ ] `VC-001` covers `I-001`; pass condition: describe pass condition; evidence: describe expected evidence; metric: threshold or reason not quantified.
-
-## Risks And Mitigations
-
-- `Risk-001`: Risk and mitigation.
-
-## Refinement Settings
-
-- Reviewer mode: `delegated-subagent | current-session`; model selector: `inherit | <selector>`.
-- Criticizer mode: `delegated-subagent | current-session`; model selector: `inherit | <selector>`.
+- [ ] `VC-001` covers `Task-1`; pass condition: <observable condition>; evidence: <expected evidence>; metric: <threshold or "not quantified">.
+- [ ] `VC-002` covers `Task-2` and `Task-2.1`; pass condition: …; evidence: …; metric: ….
 
 ## Execution Handoff Notes
 
-State anything the executor should know, including order of work, files to avoid, and verification commands. The merged accept/execute question still requires explicit user approval (ask_choice with `autoComplete: false`, then the `execute_plan` tool) and must never be auto-completed. Once approved, the extension-managed execution loop injects the remaining checklist every turn and completes when every `[DONE:VC-xxx]` marker has landed — keep this section concise enough to serve as the executor's brief.
-
-## Termination Recording (implementation review)
-
-When the post-execution implementation-review loop starts, the termination question is asked with `ask_choice` using `questionId: "termination-condition"` and persisted via `plans record-checkpoint` (`transition: "implementation-review-configured"`). Each disposed round records `implementation-round-finished`; the loop closes with `completed` plus evidence. These records make `/resume-plans` continue the loop with its original condition and round count.
+Ordering, files to avoid, verification commands, and anything the executor must know. The handoff still requires explicit user approval (`ask_choice` with `autoComplete: false`, then the `execute_plan` tool) and is never auto-completed. Once approved, execution mode tracks every task through the `plans_update_task` tool (status + evidence); when all tasks are terminal, the independent completion auditor verifies each check above before the run completes.
 
 ## Revision Ledger
 
-- `PLAN_v1`: Initial plan from resolved questions and evidence.
+- `PLAN_v1`: <one line per revision: what changed and why>.
+
+---
+
+## Format specification (normative)
+
+The plan body is exactly two sections plus the metadata header shown above:
+`## Original Request` (one paragraph), `## Tasks`, and `## Verification Checks`.
+Everything else the workflow needs lives in the run state (decisions ledger,
+review rounds, refs), not in the plan file. `## Execution Handoff Notes` and
+`## Revision Ledger` are the two permitted auxiliary sections.
+
+### Tasks microsyntax
+
+- Top-level task line: ``- `Task-N`: <title> — deps: <ids>; files: <paths>; wave: <n>``.
+  The separator between title and metadata is an em dash `—` (tolerated: `——`, `--`, `–`).
+  With no separator the whole body is the title (no fields).
+- Fields are separated by `;` (tolerated `；`); multi-values by `,`
+  (tolerated `，` `、`). All three fields are optional; missing `wave` values
+  derive from deps (1 + max(dep wave)), and the `### Execution Waves`
+  subsection wins over inline `wave:` on conflict (linted).
+- Subtasks: one indented bullet level, ``- `Task-N.M`: <title> — …``. Only one
+  nesting level is valid; deeper ids lint as drift. Subtasks may carry
+  `deps:`/`files:`; the wave is inherited from the parent (inline `wave:` on a
+  subtask is ignored with a lint notice).
+- `### Execution Waves` rows: ``- wave <n>: Task-1, Task-2 — <rationale>``.
+  The wave table is the authoritative parallel-execution order: within one
+  wave, top-level tasks' file sets must be disjoint (children roll up to their
+  parent), and every `deps:` target must sit in an earlier wave.
+
+### Verification Checks microsyntax
+
+- Row: ``- [ ] `VC-###` covers `Task-2` and `Task-3`; pass condition: …; evidence: …; metric: …``.
+- `covers` accepts multiple targets and `Task-N.M` subtask ids; the clause ends
+  at the first `;`. Checks covering zero tasks never enter the completion
+  audit; a check whose covered tasks are ALL skipped passes as skipped-pass.
+
+### Lint and compatibility
+
+- Planning-time lint (`lintPlanIntoNotices`): zero parsed tasks under an
+  existing `## Tasks` header, over-deep subtasks, non-consecutive top-level
+  numbering, unknown dep/coverage targets, same-wave file overlaps,
+  deps inside the same-or-later wave, inline-vs-subsection wave conflicts.
+  Lint notices are advisory while planning and hard-rejected at the execution gate.
+- Legacy compatibility: plans without `## Tasks` fall back to parsing
+  `## Implementation Items` (`I-001` → `Task-1`, `covers \`I-001\`` normalizes
+  the same way); checklist-only pre-0.5 artifacts synthesize one serial task
+  per check. The execution gate surfaces an upgrade notice on fallback.
+
+### Refinement
+
+One Reviewer role: each round returns findings (`F-###`) and up to five
+questions (`Q-1..Q-5`). Default sequences: plan-big → one round of three
+concurrent reviewers (questions included); plan-normal / plan-small → one
+reviewer round. The main agent asks every question with `ask_choice` and
+records the answers before revising the plan.