pi-plans 0.5.7 → 0.7.0

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.

package/references/state-and-config.md

@@ -1,18 +1,20 @@
 # State And Config
 
-pi-plans stores all planning preferences and run state in the target workspace's git directory as `<git-common-dir>/pi_plans/` — in an ordinary repository this is simply `.git/pi_plans/` — resolving the git common dir with `git rev-parse --git-common-dir` from the workspace. Because the state lives inside the git dir, git never tracks it and no `.gitignore` entries are needed. The target workspace is the current working directory unless the user explicitly names another repository.
+pi-plans stores planning preferences and run state in the target workspace's git directory as `<git-common-dir>/pi-plans/` — in an ordinary repository this is simply `.git/pi-plans/` — resolving the git common dir with `git rev-parse --git-common-dir` from the workspace. Because the state lives inside the git dir, git never tracks it and no `.gitignore` entries are needed. The target workspace is the current working directory unless the user explicitly names another repository.
 
-Do not store pi-plans preferences in Pi's own settings (`~/.pi/agent/settings.json`); pi-plans uses `.git/pi_plans/config.json` for its state.
+The one workspace-independent piece is the **reviewer role** (v0.7.0): it lives in the global config `~/.pi/pi-plans/config.json` (override the directory with `PI_PLANS_GLOBAL_DIR`), confirmed once and shared across every workspace. It is a standalone pi-plans file, never Pi's own settings.
+
+Do not store pi-plans preferences in Pi's own settings (`~/.pi/agent/settings.json`); pi-plans uses `.git/pi-plans/config.json` for workspace state and `~/.pi/pi-plans/config.json` for the reviewer role.
 
 ## State Root Resolution
 
 - Git runs with `GIT_DIR`, `GIT_COMMON_DIR`, and `GIT_WORK_TREE` scrubbed from the environment, so leaked env vars cannot misdirect state into an unrelated repository. Relative results (`.git`, `../.git`) resolve against the workdir.
-- Granularity is **per enclosing repository**: running from a subdirectory uses the enclosing repo's git dir (a one-line notice names that repo). Linked worktrees share one common dir; run directories are unique, but `active.json` may race across concurrent worktrees.
-- State does not travel with clones: a fresh clone starts with empty state while committed `./docs/pi-plans/` artifacts persist in the repository.
+- Granularity is **per enclosing repository**: running from a subdirectory uses the enclosing repo's git dir (a one-line notice names that repo). Linked worktrees share one common dir; run directories are unique, and since v0.6.0 the run registry is derived from `runs/` (no shared pointer to race). The legacy `active.json` is deprecated: reads fall back to it only when no `runs/` entries exist (pre-0.6.0 migration).
+- State does not travel with clones: a fresh clone starts with empty state, and the default plan artifacts live in the git dir with it. Point `artifact_root` at `./docs/pi-plans` when you want the plans committed and public instead.
 
 ## Auto Git Init
 
-When a mutating state action (`init`, `set-language`, `set-role`, `start-run`, record-*) runs in a workdir that is not a git repository, the helper auto-runs `git init` there (with a one-line notice) and then creates the state dir. It never creates commits. Auto-init runs only when ALL of the following hold:
+When a mutating state action (`init`, `set-language`, `set-artifact-root`, `set-refs-root`, `set-graph-enabled`, `start-run`, record-*) runs in a workdir that is not a git repository, the helper auto-runs `git init` there (with a one-line notice) and then creates the state dir. It never creates commits. `set-role` is deliberately NOT in this list: it writes only the global config and never triggers auto-init or any workspace write. Auto-init runs only when ALL of the following hold:
 
 - the workdir has no `.git` entry (a pre-existing `.git` file or directory that git cannot resolve is a fatal error, never a silent reinit);
 - the workdir is not inside any git work tree (a subdirectory of a repo uses the enclosing repo instead);
@@ -23,12 +25,12 @@ Bare repositories are refused with a clear error. A missing `git` executable is
 ## Directory Layout
 
 ```text
-<git-common-dir>/pi_plans/
+<git-common-dir>/pi-plans/
   config.json
   pi-vcc-config.json
-  active.json
-  runs/            # note: the refs root is a sibling — .git/pi-plans/refs (hyphenated), not under pi_plans/
-    <run-id>/
+  active.json      # deprecated (v0.6.0): legacy pointer, read only when runs/ is empty
+  runs/            # the run registry derives from runs/<run-id>/run.json
+    <run-id>/      # note: the refs root is a sibling — .git/pi-plans/refs (hyphenated), not under pi-plans/
       run.json
       decisions.jsonl
       subagents.jsonl
@@ -37,29 +39,17 @@ Bare repositories are refused with a clear error. A missing `git` executable is
   cache/
 ```
 
-`config.json` is stable workspace preference state. `pi-vcc-config.json` is the repo-private compaction config used only by pi-plans' VCC-style compact hook. `active.json` and `runs/` are run state. Reference downloads go to the configured `refs_root` (asked once per workspace when unset; the recommended `.git/pi-plans/refs/` sits inside the git dir so git never tracks it), with metadata recorded in the run state and public artifacts.
+`config.json` is stable workspace preference state. `pi-vcc-config.json` is the repo-private compaction config used only by pi-plans' VCC-style compact hook. `runs/` is the run state and the source of the run registry: `listRuns` scans `runs/<run-id>/run.json` (sorted by `updated_at` desc, corrupt entries skipped) and the un-bound "active" resolution is the newest NON-TERMINAL run (null when every run is done/abandoned). Multiple concurrent planning runs in one workdir are supported: each session binds to the run it started (binding first, registry fallback after), and `/plans-abandon`, `/plans-execute`, and `/resume-plans` open a descriptive run-picker form when more than one candidate exists. Reference downloads go to the configured `refs_root` (asked once per workspace when unset; the recommended `.git/pi-plans/refs/` sits inside the git dir so git never tracks it), with metadata recorded in the run state and public artifacts.
 
 ## Config Schema
 
-The default config is:
+The default workspace config is (no `reviewer` key — the role lives globally since v0.7.0):
 
 ```json
 {
   "schema": 1,
   "language": { "tag": null, "source": "unset", "updated_at": null },
-  "reviewer": {
-    "mode": "delegated-subagent",
-    "model_selector": null,
-    "name_prefix": "pi-plans-reviewer",
-    "confirmed_at": null
-  },
-  "criticizer": {
-    "mode": "delegated-subagent",
-    "model_selector": null,
-    "name_prefix": "pi-plans-criticizer",
-    "confirmed_at": null
-  },
-  "artifact_root": "./docs/pi-plans",
+  "artifact_root": "./.git/pi-plans/plans",
   "artifact_root_source": "unset",
   "artifact_root_updated_at": null,
   "refs_root": null,
@@ -72,18 +62,42 @@ Rules:
 
 - `schema` must be `1`.
 - `language.tag` is a BCP47-style tag such as `zh-Hans`, `en`, or `zh-Hant`, or `null` before selection; `language.source` is `user`, `auto`, or `unset`.
-- `reviewer.mode` and `criticizer.mode` are `delegated-subagent` or `current-session`.
-- `model_selector` is `null` to inherit the dispatching session's model, or an exact `provider/model` selector matching Pi's model registry.
-- `confirmed_at` is `null` until the user has confirmed the role's model at first use; see below.
+- A legacy workspace `reviewer` block (pre-0.7.0, and the removed v0.6.0 `criticizer` key) is read-tolerated: the first mutating state call seeds the global config from intent blocks and the next workspace write strips the key. Read-only paths resolve the effective reviewer in memory (global first, legacy block second) and never write.
 - `artifact_root` is relative to the target workspace unless absolute.
 - `artifact_root_source` is `user`, `auto`, or `unset`.
 - `artifact_root_updated_at` is the selection timestamp or `null` before confirmation.
 - `refs_root` is where plan-with-refs downloads references, relative to the target workspace unless absolute, or `null` before selection; `refs_root_source` is `user`, `auto`, or `unset`; `refs_root_updated_at` is the selection timestamp or `null`.
-- There is intentionally no `effort` field: subagents inherit the dispatching session's model and thinking level unless an exact selector is stored. The real lever is the main session's thinking level at refine time.
+
+## Global Reviewer Config (v0.7.0)
+
+The reviewer role is stored in `~/.pi/pi-plans/config.json` (`PI_PLANS_GLOBAL_DIR` overrides the directory; tests, CI, and bench containers rely on it):
+
+```json
+{
+  "schema": 1,
+  "reviewer": {
+    "mode": "delegated-subagent",
+    "model_selector": "devin/claude-sonnet-5.5",
+    "thinking_level": null,
+    "name_prefix": "pi-plans-reviewer",
+    "confirmed_at": "2026-09-30T07:54:12Z"
+  }
+}
+```
+
+Rules:
+
+- `mode` is `delegated-subagent` or `current-session`.
+- `model_selector` is an exact `provider/model` selector. There is no inherit entry point anymore: after first-use confirmation the delegated reviewer always runs a concrete model (`modelSelector: "inherit"` in `set-role` is a full reset — it clears the selector AND `confirmed_at`).
+- `thinking_level` is `null` (default — spawn WITHOUT `--thinking`, letting the child pi resolve its own chain: per-model settings → `defaultThinkingLevel` → `medium`, then model clamping) or an explicit level (`off | minimal | low | medium | high | xhigh | max`; the domain comes from the chosen model's `thinkingLevelMap` via pi-ai's `getSupportedThinkingLevels`). `"off"` is a real level and deliberately distinct from `null`. Changing `modelSelector` without passing `thinkingLevel` resets the level.
+- `confirmed_at` is stamped only by a real confirmation. `reviewerReady(role)` = current-session, or delegated with `confirmed_at` set AND a concrete `model_selector` — a confirmed null selector can never pass (the old confirmed-inherit state is unreachable).
+- A corrupt or wrong-schema global file yields defaults plus a notice and is NEVER clobbered by reads.
+- Migration (Q-1=A): the first mutating pi-plans call in a workspace with a legacy intent block (`confirmed_at` set, an explicit selector, or a non-default mode) seeds the global file once — first touched workspace wins; other workspaces get a one-time "ignored" notice. A confirmed-inherit block seeds with the selector null and NO confirmation, so the next `refine` re-asks once via the native panel. Scaffold-only blocks are dropped silently.
+- The completion auditor's spawns are NOT governed by this role: it runs its own model; `subagents.jsonl` records the reviewer/ref-analyst thinking level actually passed (`thinking_level` field, older entries have none).
 
 ## VCC Compact Config
 
-`pi-vcc-config.json` is scaffolded under the resolved `<git-common-dir>/pi_plans/` state root when an active planning or execution compaction hook first needs it. It is independent from `config.json` so planning preferences, run state, and compact policy can evolve separately.
+`pi-vcc-config.json` is scaffolded under the resolved `<git-common-dir>/pi-plans/` state root when an active planning or execution compaction hook first needs it. It is independent from `config.json` so planning preferences, run state, and compact policy can evolve separately.
 
 Default values:
 
@@ -117,7 +131,7 @@ Before the first product planning question, check the persisted config (`plans`
 4. `Other` — user provides a BCP47 tag.
 5. `Auto-complete` — select the recommended language.
 
-Persist with `plans` (`set-language`, `languageSource: "user"`). Use the selected language for visible questions, choices, review summaries, criticizer questions, and Markdown artifacts. Keep IDs, file paths, command names, JSON keys, and protocol labels stable in English.
+Persist with `plans` (`set-language`, `languageSource: "user"`). Use the selected language for visible questions, choices, review summaries, reviewer questions, and Markdown artifacts. Keep IDs, file paths, command names, JSON keys, and protocol labels stable in English.
 
 ## Code Graph Enabled
 
@@ -125,13 +139,13 @@ Persist with `plans` (`set-language`, `languageSource: "user"`). Use the selecte
 
 ## `/config-pi-plans`
 
-`/config-pi-plans` is an interactive workspace configuration wizard. It re-asks the workspace language, planning docs root, refs root, code graph toggle, reviewer mode/model, and criticizer mode/model, then writes the chosen defaults back to `.git/pi_plans/config.json`. When code graph is enabled, the extension also overrides built-in `read`/`write`/`edit` for indexed source files so graph-backed source reads and DB-first edits happen automatically. Model pickers can reuse the current session model, any available selector surfaced by `ctx.scopedModels` or the model registry, or a manually entered exact `provider/model` string. If a run is already active, only the workspace defaults change; the active run's `artifact_dir` and `language_tag` stay unchanged.
+`/config-pi-plans` is an interactive workspace configuration wizard. It re-asks the workspace language, planning docs root, refs root, and code graph toggle (written to `.git/pi-plans/config.json`), plus the reviewer mode and model. The reviewer steps live in the GLOBAL config: the mode switch persists immediately, and the model step shows a keep/change entry menu — `Keep current (provider/model · level)` or `Choose model & thinking level…`. When the mode is `current-session` the model step is skipped entirely (an existing selector is never cleared). Choosing opens the native model panel + effort panel in TUI, or model/effort menus otherwise; Esc keeps the current role and the wizard CONTINUES instead of discarding earlier answers. A failed global write is reported explicitly while workspace settings still save. When code graph is enabled, the extension also overrides built-in `read`/`write`/`edit` for indexed source files so graph-backed source reads and DB-first edits happen automatically. If a run is already active, only the workspace defaults change; the active run's `artifact_dir` and `language_tag` stay unchanged.
 
 
 Before the first product planning question, check the persisted config again. If `artifact_root_source` is missing or `unset`, ask exactly one `ask_choice` question:
 
-1. `./docs/pi-plans` — recommended; planning docs live in the repository and are public.
-2. `./.git/pi_plans/plans` — private to the repository; not published.
+1. `./.git/pi-plans/plans` — recommended; the default. Planning docs stay private to the repository and are never tracked.
+2. `./docs/pi-plans` — planning docs live in the working tree, are public, and can be committed with the repository.
 3. `Other` — user provides a custom path.
 4. `Auto-complete` — select the recommended path.
 
@@ -147,27 +161,29 @@ Before downloading any reference in a plan-with-refs flow, check the persisted c
 Persist with `plans` (`set-refs-root`, `refsRoot: <selected path>`, `refsRootSource: "user"` or `"auto"`). Download references under this root. This question does not count against the planning-question limit.
 
 
-Before running a `refine` round, read the role setting from the persisted config.
+Before running a `refine` round, read the role setting from the persisted global config.
 
-If the role's `mode` is missing or invalid, ask exactly one `ask_choice` question and persist:
+If the role's `mode` is missing or invalid, ask exactly one `ask_choice` question and persist (the mode question stays agent-mediated):
 
 1. `Delegated subagent` — recommended; read-only `pi` subprocess with isolated context.
 2. `Current session` — run the read-only pass in the current foreground session.
 3. `Other` / 4. `Auto-complete` — select the recommended delegated subagent.
 
-Independently, each role's **model** is confirmed once, at that role's first actual use: when `confirmed_at` is `null` and a `refine` round is about to run, ask exactly one `ask_choice` question:
+The **model + thinking level** are confirmed once, at first actual use, through NATIVE panels — not ask_choice:
+
+- **TUI**: the gate itself pops a `/model`-style searchable model panel (pi's `ModelSelectorComponent`; the runtime adapter maps the public model registry facade — `getAvailable`/`find`/`getError`/`refresh` — onto the four runtime methods, with the private `.runtime` field as a secondary attempt and menus as the construction fallback), then a `/thinking`-style effort panel whose first row is `Default (no --thinking flag: the child pi resolves per-model settings → defaultThinkingLevel → medium)` followed by the chosen model's `thinkingLevelMap` levels. Both panels must complete; the result persists to the global config (`modelSelector` + `thinkingLevel`, `confirmed: true`) only then, and the same invocation continues with the returned values.
+- **hasUI non-TUI (RPC/ACP)**: native `ctx.ui.select` menus over the same data (model list, then effort list).
+- **UI-less (print/json/bench)**: the gate returns text guidance embedding the available selectors and the exact `set-role` call; persist that way. Automation may also pre-write `~/.pi/pi-plans/config.json` directly.
 
-1. `Inherit the main agent's model` — recommended; stores `model_selector: null`.
-2. `Choose a model` — pick from the models available in this Pi install (check `/model` or `ctx.scopedModels`); persist the exact `provider/model` selector; do not invent model names.
-3. `Other` / 4. `Auto-complete` — select inherit.
+Pressing Esc on either panel CANCELS the whole gate: nothing is persisted and the tool returns a dedicated error (`details.cancelled`) instructing the agent NOT to re-ask via ask_choice and NOT to retry unless the user asks — suggest `/config-pi-plans` instead. Cheap validations (plan path, refs) run BEFORE any panel so a typo never walks the user through panels.
 
-Persist with `plans` (`set-role`, `confirmed: true`, `modelSelector: <selector or "inherit">`). `confirmed_at` is set only by this confirmation flow; a mode-only edit never forges or discards a confirmation, and a confirmed inherit (`model_selector: null` plus a stamp) is distinguishable from never-confirmed.
+The confirmation applies only to `delegated-subagent` mode (current-session runs in the main session and needs no model). If a stored selector is missing from the registry at spawn time, TUI re-opens the panel; other modes return an error naming the selector — reset with `set-role` (`resetConfirmation: true`) and re-confirm.
 
-If a spawn later fails because the stored selector is unavailable, reset the marker (`set-role`, `resetConfirmation: true`) and re-ask the confirmation question.
+`set-role` invariants: `confirmed: true` requires a concrete `provider/model` selector in delegated mode; `modelSelector: "inherit"` resets BOTH the selector and `confirmed_at`; `thinkingLevel: "default"` stores `null`; changing `modelSelector` without `thinkingLevel` resets the level.
 
 ## Subagent Spawning
 
-When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` subprocess (`--mode json -p --no-session --tools read,grep,find,ls`) whose system prompt comes from `agents/reviewer.md` or `agents/criticizer.md`. In TUI mode, delegated runs also show a standalone `Reviewer` or `Criticizer` overlay with live lane/tool status; the child is awaited and the overlay is closed before the tool result returns. The subagent:
+When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` subprocess (`--mode json -p --no-session --tools read,grep,find,ls`, plus `--model <provider/model>` and — only when `thinking_level` is set — `--thinking <level>`) whose system prompt comes from `agents/reviewer.md`. In TUI mode, delegated runs also show a standalone `Reviewer` overlay with live lane/tool status (header label `provider/model:level`); the child is awaited and the overlay is closed before the tool result returns. The subagent:
 
 - performs read-only analysis and never edits files;
 - receives the full plan text and a review/criticism brief;
@@ -175,19 +191,19 @@ When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` s
 
 The main agent consolidates the results, records dispositions, revises the plan, and asks the next merged accept/execute question — all in the same turn.
 
-The `analyze_refs` tool (plan-with-refs) uses the same spawning machinery with the **reviewer** role's gates (`mode` must be `delegated-subagent`; a confirmed `current-session` reviewer is refused with guidance to switch, since analysis is spawn-only) and the reviewer's model selector. Each downloaded reference gets one independent read-only subagent whose system prompt comes from `agents/ref-analyst.md` and whose working directory is that reference's own directory; lanes never get `code_graph`. Lanes run in sequential batches of at most 3 under a standalone overlay titled `Refs`; each batch's controller opens and closes exactly like a single refine round. Successful spawns are recorded best-effort in `subagents.jsonl` with role `ref-analyst` (skipped when no active run exists, e.g. adhoc calls). The structured per-reference sections come back as the tool result; the main agent owns `REF_ANALYSIS.md` and fills `coverage`/`gaps` in `refs.jsonl` via `plans` (`record-ref`).
+The `analyze_refs` tool (plan-with-refs) uses the same spawning machinery with the **reviewer** role's model confirmation from the global config — but NOT its mode (v0.7.0, Q-4): analysis is spawn-only by nature, so a `current-session` reviewer still gets spawned ref-analyst lanes (a one-time notice says the mode is ignored and unchanged) while the confirmed concrete model remains required. Each downloaded reference gets one independent read-only subagent whose system prompt comes from `agents/ref-analyst.md` and whose working directory is that reference's own directory; lanes never get `code_graph`. Lanes run in sequential batches of at most 3 under a standalone overlay titled `Refs`; each batch's controller opens and closes exactly like a single refine round. Successful spawns are recorded best-effort in `subagents.jsonl` with role `ref-analyst` and the thinking level actually passed (skipped when no active run exists, e.g. adhoc calls). The structured per-reference sections come back as the tool result; the main agent owns `REF_ANALYSIS.md` and fills `coverage`/`gaps` in `refs.jsonl` via `plans` (`record-ref`).
 
 ## Run State
 
-One run directory per planning request: `<git-common-dir>/pi_plans/runs/<YYYYMMDDTHHMMSSZ-topic>/` (second-precision; `-2`, `-3` suffixes on collision).
+One run directory per planning request: `<git-common-dir>/pi-plans/runs/<YYYYMMDDTHHMMSSZ-topic>/` (second-precision; `-2`, `-3` suffixes on collision).
 
 `run.json` includes: run ID; skill name; original request; target workspace; artifact directory; language tag; status (`planning` → `accepted` → `executing` → `done`, with `stopped`/`abandoned` as exits); timestamps.
 
-`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer/ref-analyst spawns. `refs.jsonl` records reference metadata via `plans` (`record-ref`).
+`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/ref-analyst spawns (legacy 0.6.0 entries with `criticizer` remain readable). `refs.jsonl` records reference metadata via `plans` (`record-ref`); its `kind` field is `project` (repos), `paper` (arXiv etc.), `article` (blog posts), or `docs` (documentation sites).
 
 ## Workflow Checkpoints (`/resume-plans`)
 
-Each run may carry a `checkpoint.json` — the durable, cross-session workflow state that `/resume-plans` restores in the current session. It records: logical `phase` (`planning | reviewing | executing | implementation-review | completed`), `nextAction`, the exact plan identity (path + version + SHA-256), pending/answered questions (stable `questionId`), review rounds with per-lane status and result-file references, execution approval evidence (plan digest, worktree, `git rev-parse HEAD` at approval, verified VC/I set, usage), the implementation-review termination condition and completed-round count, and ownership metadata. Full review outputs live in separate `reviews/` files; the checkpoint keeps only validated references.
+Each run may carry a `checkpoint.json` — the durable, cross-session workflow state that `/resume-plans` restores in the current session. It records: logical `phase` (`planning | reviewing | executing | completed`; the legacy 0.6.0 `implementation-review` phase is read-tolerated and maps to done), `nextAction`, the exact plan identity (path + version + SHA-256), pending/answered questions (stable `questionId`), review rounds with per-lane status and result-file references, execution approval evidence (plan digest, worktree, `git rev-parse HEAD` at approval, task progress map, audit rounds, verified VC set, usage), and ownership metadata. Full review outputs live in separate `reviews/` files; the checkpoint keeps only validated references.
 
 Rules:
 
@@ -200,4 +216,4 @@ Rules:
 
 ## Run Ownership
 
-A run may be held by at most one live owner (`owner.json`: host, pid, process start time via `ps -o lstart=`, session id, random process token, generation). Acquisition is an atomic exclusive create; takeovers require proof the previous owner is dead (process gone, or pid alive with a different start time — PID reuse). Foreign hosts, corrupt records, and unverifiable liveness are conservatively refused; `/resume-plans` never queues or interrupts. Sessions bind to the run they start/execute/resume (restored from `pi-plans-run-start` entries on the current branch), and attribution (tools, write guard, autocomplete, execution bookkeeping, code-graph apply gate) prefers the binding over the shared `active.json` pointer.
+A run may be held by at most one live owner (`owner.json`: host, pid, process start time via `ps -o lstart=`, session id, random process token, generation). Acquisition is an atomic exclusive create; takeovers require proof the previous owner is dead (process gone, or pid alive with a different start time — PID reuse). Foreign hosts, corrupt records, and unverifiable liveness are conservatively refused; `/resume-plans` never queues or interrupts. Sessions bind to the run they start/execute/resume (restored from `pi-plans-run-start` entries on the current branch), and attribution (tools, write guard, autocomplete, execution bookkeeping, code-graph apply gate) prefers the binding, falling back to the registry's newest non-terminal run (v0.6.0 — the shared `active.json` pointer is deprecated). The v0.6.0 delegated-executor env pins (`PI_PLANS_RUN_ID` / `PI_PLANS_EXECUTOR`) are gone; read-only subagent children carry `PI_PLANS_REFINER=1`.

package/scripts/bench/pi-adapter/pi_plans_bench.py

@@ -25,7 +25,7 @@ Usage with harbor::
 
 Fairness (D-010/D-020): both arms share one container image; the only
 difference is the agent-level configuration above. Seeded evaluation state
-lives under ``.git/pi_plans/`` with the artifact root pointed OUTSIDE the
+lives under ``.git/pi-plans/`` with the artifact root pointed OUTSIDE the
 graded tree (``/tmp/pi-plans-bench``); the pre-registered pre-oracle
 snapshot-diff restore was NOT implemented in this run — recorded as a
 limitation (TB oracles read /app artifacts only, so scoring impact is
@@ -63,27 +63,33 @@ TREATMENT_SYSTEM_PROMPT = (
     "it step by step with the verifier checklist."
 )
 
-# D-015 seeded config: deterministic, no first-use Q&A rounds, flash roles,
-# graph off, artifact root outside the graded workspace.
+# D-015 seeded configs: deterministic, no first-use Q&A rounds, graph off,
+# artifact root outside the graded workspace. Since v0.7.0 the reviewer role
+# lives in the GLOBAL config (~/.pi/pi-plans/config.json inside the
+# container) with a CONCRETE provider/model selector (inherit was removed);
+# the workspace config carries no reviewer/criticizer keys at all.
 SEEDED_CONFIG = {
     "schema": 1,
     "artifact_root": "/tmp/pi-plans-bench/docs",
     "artifact_root_source": "user",
     "language": {"tag": "en", "source": "user"},
-    "reviewer": {
-        "mode": "delegated-subagent",
-        "model_selector": None,  # None => inherit the main agent's model (flash)
-        "confirmed_at": "1970-01-01T00:00:00Z",
-    },
-    "criticizer": {
-        "mode": "delegated-subagent",
-        "model_selector": None,
-        "confirmed_at": "1970-01-01T00:00:00Z",
-    },
     "graph_enabled": False,
 }
 
 
+def _seeded_global_config(provider: str, model_id: str) -> dict:
+    return {
+        "schema": 1,
+        "reviewer": {
+            "mode": "delegated-subagent",
+            "model_selector": f"{provider}/{model_id}",
+            "thinking_level": None,  # default: child pi resolves its own chain
+            "name_prefix": "pi-plans-reviewer",
+            "confirmed_at": "1970-01-01T00:00:00Z",
+        },
+    }
+
+
 def _read_text(name: str) -> str:
     return (ADAPTER_DIR / name).read_text(encoding="utf-8")
 
@@ -199,20 +205,25 @@ class PiPlansBench(Pi):
             filename=".bench-system-prompt.md",
         )
 
-    async def _seed_pi_plans_config(self, environment: BaseEnvironment) -> None:
-        """Write the deterministic pi-plans config into the trial workdir (D-015).
+    async def _seed_pi_plans_config(self, environment: BaseEnvironment, provider: str, model_id: str) -> None:
+        """Write the deterministic pi-plans configs into the trial container (D-015).
 
-        The config lives under ``.git/pi_plans/`` (diff-allowlist path, removed
-        before oracle scoring) with the artifact root pointed at
-        ``/tmp/pi-plans-bench`` so plan artifacts never land in the graded tree.
+        The workspace config lives under ``.git/pi-plans/`` (diff-allowlist
+        path, removed before oracle scoring) with the artifact root pointed at
+        ``/tmp/pi-plans-bench`` so plan artifacts never land in the graded
+        tree. The reviewer role is seeded into the GLOBAL config under the
+        container's ``~/.pi/pi-plans/`` with the exact driver model (v0.7.0:
+        no inherit, no criticizer), so refine gates pass without any panel.
         """
         config = json.dumps(SEEDED_CONFIG, indent=2)
+        global_config = json.dumps(_seeded_global_config(provider, model_id), indent=2)
         await self.exec_as_agent(
             environment,
             command=(
                 "set -euo pipefail; "
-                "mkdir -p .git/pi_plans " f"{BENCH_CONFIG_DIR} && "
-                f"printf {shlex.quote(config)} > .git/pi_plans/config.json"
+                "mkdir -p .git/pi-plans ~/.pi/pi-plans " f"{BENCH_CONFIG_DIR} && "
+                f"printf {shlex.quote(config)} > .git/pi-plans/config.json && "
+                f"printf {shlex.quote(global_config)} > ~/.pi/pi-plans/config.json"
             ),
         )
 
@@ -224,7 +235,7 @@ class PiPlansBench(Pi):
         provider, model_id = self.model_name.split("/", 1)
 
         if self.arm == "treatment":
-            await self._seed_pi_plans_config(environment)
+            await self._seed_pi_plans_config(environment, provider, model_id)
 
         # printf interprets backslash escapes; ship sources base64-encoded so
         # the driver/task bytes survive verbatim.
@@ -291,7 +302,7 @@ class PiPlansBench(Pi):
         if subagent_usage is not None:
             metadata["pi_plans_subagent_usage"] = subagent_usage
             # Fold child tokens/cost into the top-level accounting so treatment
-            # totals are comparable (the extension's reviewer/criticizer calls).
+            # totals are comparable (the extension's reviewer/ref-analyst calls).
             totals = subagent_usage.get("totals") or {}
             context.n_input_tokens = (context.n_input_tokens or 0) + int(totals.get("input", 0))
             context.n_output_tokens = (context.n_output_tokens or 0) + int(totals.get("output", 0))

package/scripts/bench/pi-adapter/rpc_driver.mjs

@@ -184,11 +184,11 @@ function snapshotPlanArtifacts(dest) {
   if (!dest) return;
   // Plan artifact locations: the seeded artifact root (/tmp/pi-plans-bench/docs)
   // and pi-plans' own fallbacks — the repo-local docs/pi-plans and the state
-  // root .git/pi_plans/docs (where run plans actually land).
+  // root .git/pi-plans/docs (where run plans actually land).
   const roots = [
     "/tmp/pi-plans-bench/docs",
     path.join(process.cwd(), "docs", "pi-plans"),
-    path.join(process.cwd(), ".git", "pi_plans", "docs"),
+    path.join(process.cwd(), ".git", "pi-plans", "docs"),
   ];
   try {
     mkdirSync(dest, { recursive: true });
@@ -209,8 +209,8 @@ function snapshotPlanArtifacts(dest) {
 
 function snapshotSubagentUsage(dest) {
   if (!dest) return;
-  // pi-plans state root convention: <workdir>/.git/pi_plans/runs/<id>/subagents.jsonl
-  const stateRoots = [path.join(process.cwd(), ".git", "pi_plans", "runs")];
+  // pi-plans state root convention: <workdir>/.git/pi-plans/runs/<id>/subagents.jsonl
+  const stateRoots = [path.join(process.cwd(), ".git", "pi-plans", "runs")];
   const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, children: 0 };
   try {
     for (const root of stateRoots) {

package/scripts/run-tests.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
 const testDir = resolve("tests");
@@ -10,6 +11,15 @@ if (!existsSync(testDir)) {
   process.exit(1);
 }
 
+// Safety net (F-002): unless the caller pinned one, point the pi-plans
+// GLOBAL config at a throwaway directory so concurrent test files can never
+// clobber the developer's real ~/.pi/pi-plans/config.json. Individual suites
+// may still override per-test with their own PI_PLANS_GLOBAL_DIR.
+const env = { ...process.env };
+if (!env.PI_PLANS_GLOBAL_DIR) {
+  env.PI_PLANS_GLOBAL_DIR = mkdtempSync(join(tmpdir(), "pi-plans-global-"));
+}
+
 const tests = readdirSync(testDir)
   .filter((entry) => entry.endsWith(".test.ts"))
   .sort()
@@ -22,6 +32,7 @@ if (tests.length === 0) {
 
 const result = spawnSync(process.execPath, ["--experimental-strip-types", "--test", ...tests], {
   stdio: "inherit",
+  env,
 });
 
 if (result.error) {