pi-plans 0.6.0 → 0.7.0

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, 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 while committed `./docs/pi-plans/` artifacts persist in the repository.
+- 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      # 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-id>/      # note: the refs root is a sibling — .git/pi-plans/refs (hyphenated), not under pi-plans/
       run.json
       decisions.jsonl
       subagents.jsonl
@@ -41,25 +43,13 @@ Bare repositories are refused with a clear error. A missing `git` executable is
 
 ## 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`); its `kind` field is `project` (repos), `paper` (arXiv etc.), `article` (blog posts), or `docs` (documentation sites).
+`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, falling back to the registry's newest non-terminal run (v0.6.0 — the shared `active.json` pointer is deprecated). Delegated executor children pin their run via `PI_PLANS_RUN_ID` and are exempt from the planning write guard (`PI_PLANS_EXECUTOR=1`).
+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) {

package/scripts/validate.ts

@@ -17,7 +17,7 @@ const EXPECTED_SKILLS = new Set([
 	"debug-and-plan",
 ]);
 const REQUIRED_REFERENCES = ["pi-planning-workflow.md", "plan-artifact-template.md", "state-and-config.md"];
-const REQUIRED_AGENTS = ["reviewer.md", "criticizer.md"];
+const REQUIRED_AGENTS = ["reviewer.md"];
 const REQUIRED_TOOL_FILES = [
 	"tools/plans.ts",
 	"tools/ask-choice.ts",
@@ -26,6 +26,7 @@ const REQUIRED_TOOL_FILES = [
 	"tools/execute-plan.ts",
 	"tools/code-graph.ts",
 	"src/state.ts",
+	"src/global-state.ts",
 	"src/guard.ts",
 	"src/plan.ts",
 	"src/subagent.ts",
@@ -69,7 +70,7 @@ function validateSkill(dir: string): void {
 	if (!description || description.length > 1024) fail(`${file}: invalid description length`);
 	if (!/Use|MUST USE/.test(description)) fail(`${file}: description should include routing language`);
 
-	const requiredPhrases = ["Auto-complete", "ask_choice", "refine", "language", "reviewer", "criticizer", ".git/pi_plans", "drawback"];
+	const requiredPhrases = ["Auto-complete", "ask_choice", "refine", "language", "reviewer", ".git/pi-plans", "drawback"];
 	for (const phrase of requiredPhrases) {
 		if (!text.includes(phrase)) fail(`${file}: missing required phrase ${phrase!}`);
 	}
@@ -77,14 +78,24 @@ function validateSkill(dir: string): void {
 
 function validateDefaultConfig(): void {
 	const source = fs.readFileSync(path.join(ROOT, "src", "state.ts"), "utf8");
-	if (!source.includes('"pi-plans-reviewer"') || !source.includes('"pi-plans-criticizer"')) {
-		fail("src/state.ts: name_prefix defaults missing");
-	}
-	if (source.includes("effort")) fail("src/state.ts: per-role effort must not exist");
-	if (!source.includes('"delegated-subagent"')) fail("src/state.ts: delegated-subagent default missing");
 	if (!source.includes('artifact_root: DEFAULT_ARTIFACT_ROOT')) fail("src/state.ts: artifact_root default missing");
 	if (!source.includes('artifact_root_source: "unset"')) fail("src/state.ts: artifact_root_source default missing");
 	if (!source.includes('artifact_root_updated_at: null')) fail("src/state.ts: artifact_root_updated_at default missing");
+	// The reviewer role defaults live in the GLOBAL config module (v0.7.0):
+	// one reviewer, one file, shared across workspaces.
+	const globalSource = fs.readFileSync(path.join(ROOT, "src", "global-state.ts"), "utf8");
+	if (!globalSource.includes('"pi-plans-reviewer"')) {
+		fail("src/global-state.ts: reviewer name_prefix default missing");
+	}
+	if (!globalSource.includes('"delegated-subagent"')) {
+		fail("src/global-state.ts: delegated-subagent default missing");
+	}
+	if (!globalSource.includes('thinking_level')) {
+		fail("src/global-state.ts: reviewer thinking_level field missing");
+	}
+	if (!globalSource.includes("PI_PLANS_GLOBAL_DIR")) {
+		fail("src/global-state.ts: PI_PLANS_GLOBAL_DIR override missing");
+	}
 }
 
 interface PackageJson {
@@ -235,8 +246,8 @@ function main(): void {
 	for (const ref of REQUIRED_REFERENCES) {
 		const file = path.join(ROOT, "references", ref);
 		if (!fs.existsSync(file)) fail(`missing reference ${ref}`);
-		if (!fs.readFileSync(file, "utf8").includes(".git/pi_plans")) {
-			fail(`${ref}: missing .git/pi_plans state location`);
+		if (!fs.readFileSync(file, "utf8").includes(".git/pi-plans")) {
+			fail(`${ref}: missing .git/pi-plans state location`);
 		}
 	}
 

package/skills/debug-and-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-and-plan
-description: Diagnose failures before creating a Pi plan. MUST USE for bugs, CI failures, test failures, regressions, incidents, broken behavior, root cause, RCA, or debug-why requests before deciding whether to plan; preserve language, reviewer, and criticizer settings in `.git/pi_plans/config.json`; exclude ordinary feature planning, direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+description: Diagnose failures before creating a Pi plan. MUST USE for bugs, CI failures, test failures, regressions, incidents, broken behavior, root cause, RCA, or debug-why requests before deciding whether to plan; preserve the workspace language settings in `.git/pi-plans/config.json` and the reviewer role in the global config (`~/.pi/pi-plans/config.json`); exclude ordinary feature planning, direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
 ---
 
 # Debug And Plan
@@ -9,7 +9,7 @@ Use this skill for problem or failure inputs that need diagnosis before planning
 
 ## Pi Setup
 
-Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool (batch related questions into one `questions: [...]` form call, 2-8 items; scope/handoff stays single-question with `autoComplete: false`); run refinement rounds with the `refine` tool.
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi-plans/`. Ask every question with the `ask_choice` tool (batch related questions into one `questions: [...]` form call, 2-8 items; scope/handoff stays single-question with `autoComplete: false`); run refinement rounds with the `refine` tool.
 
 ## Diagnostic Workflow
 
@@ -32,4 +32,4 @@ Do not ask the user to choose the level unless the evidence supports two materia
 
 ## PROBLEM_ANALYSIS.md
 
-After opt-in, create the selected planning run's `.git/pi_plans` state and public artifact directory (`plans` action `start-run`), then write `PROBLEM_ANALYSIS.md` before `PLAN_v1.md`. Include: original problem; symptoms and reproduction status; evidence inspected; RCA summary and 5 Whys (ending early with `unknown` when evidence stops); suspected root cause and confidence; planning skill selected and why; language, reviewer, and criticizer settings used; open diagnostic gaps the plan must address. Pass the original problem, RCA summary, evidence, and `PROBLEM_ANALYSIS.md` path into the selected planning skill.
+After opt-in, create the selected planning run's `.git/pi-plans` state and public artifact directory (`plans` action `start-run`), then write `PROBLEM_ANALYSIS.md` before `PLAN_v1.md`. Include: original problem; symptoms and reproduction status; evidence inspected; RCA summary and 5 Whys (ending early with `unknown` when evidence stops); suspected root cause and confidence; planning skill selected and why; language, reviewer, and reviewer settings used; open diagnostic gaps the plan must address. Pass the original problem, RCA summary, evidence, and `PROBLEM_ANALYSIS.md` path into the selected planning skill.

package/skills/plan-big/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-big
-description: Create a large Pi plan before implementation. Use for open-ended or high-risk repo efforts needing 10 or more planning questions, web research, concurrent reviewer or criticizer refinement, and refinement until convergence; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+description: Create a large Pi plan before implementation. Use for open-ended or high-risk repo efforts needing 10 or more planning questions, web research, concurrent reviewer refinement (findings plus questions), and refinement until convergence; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
 ---
 
 # Plan Big
@@ -9,7 +9,7 @@ Use this skill when the user wants a large, high-risk, or open-ended plan before
 
 ## Pi Setup
 
-Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi-plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
 
 ## Depth Contract
 
@@ -18,7 +18,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 - Batch protocol (0.4.0): when a round has several questions, submit them together as one `ask_choice` call with `questions: [...]` (2-8 items, recommended option first per question) — the tool opens one tabbed multiple-choice form with a submit page instead of asking one at a time. After the batch returns, think about the answers, then follow up in later calls (batch again for 2+ related follow-ups; single `question` for one). `Esc` on the form returns the answered subset as partial answers — continue with what you got and re-ask only what matters. The final scope confirmation and the execution handoff are ALWAYS single-question calls with `autoComplete: false`; batches reject those questions.
 - Use web research during both brainstorming and refinement when outside facts, patterns, or ecosystem constraints matter, and cite sources in the plan. Optionally (never required) you may also search 1–2 named references — a paper (e.g. arXiv), an engineering blog post, or another repository — whose technique or measurements strengthen the plan's reasoning; cite their URLs in the plan's Evidence section. This optional reference search does not count against the planning-question limit and never requires downloading or analyzing material (that is plan-with-refs' job).
 - Ask the final scope confirmation, then write `PLAN_v1.md` per `../../references/plan-artifact-template.md`.
-- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default sequence: one `Reviewer` round as three concurrent independent reviewers (`refine` with `reviewers: 3`, consolidated by the main agent per the shared workflow), then one `Criticizer` round; afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question. Beyond the default sequence, refine until convergence on high-priority findings, unresolved questions, or evidence gaps; surface at most five per round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
+- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default sequence: one reviewer round as three concurrent independent reviewers (`refine` with `reviewers: 3`), each returning findings (`F-###`) and up to five questions (`Q-1..Q-5`); consolidate per the shared workflow, ask every question with `ask_choice`, record the answers, then revise. Afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question. Beyond the default sequence, refine until convergence on high-priority findings, unresolved questions, or evidence gaps; surface at most five per round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 
 ## Fit
 

package/skills/plan-normal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-normal
-description: Create a researched Pi plan before implementation. Use for broad or risky repo changes needing 5 to 10 planning questions, web research, reviewer or criticizer refinement, and bounded refinement; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+description: Create a researched Pi plan before implementation. Use for broad or risky repo changes needing 5 to 10 planning questions, web research, reviewer refinement (findings plus questions), and bounded refinement; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
 ---
 
 # Plan Normal
@@ -9,7 +9,7 @@ Use this skill when the user wants a substantive plan before a repository change
 
 ## Pi Setup
 
-Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi-plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
 
 ## Depth Contract
 
@@ -18,7 +18,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 - Batch protocol (0.4.0): when a round has several questions, submit them together as one `ask_choice` call with `questions: [...]` (2-8 items, recommended option first per question) — the tool opens one tabbed multiple-choice form with a submit page instead of asking one at a time. After the batch returns, think about the answers, then follow up in later calls (batch again for 2+ related follow-ups; single `question` for one). `Esc` on the form returns the answered subset as partial answers — continue with what you got and re-ask only what matters. The final scope confirmation and the execution handoff are ALWAYS single-question calls with `autoComplete: false`; batches reject those questions.
 - Use web research whenever outside library behavior, ecosystem precedent, UX convention, protocol semantics, or compatibility affects the recommendation (websearch skill when installed; otherwise `curl`/`gh` via bash), and cite sources in the plan. Optionally (never required) you may also search 1–2 named references — a paper (e.g. arXiv), an engineering blog post, or another repository — whose technique or measurements strengthen the plan's reasoning; cite their URLs in the plan's Evidence section. This optional reference search does not count against the planning-question limit and never requires downloading or analyzing material (that is plan-with-refs' job).
 - Ask the final scope confirmation, then write `PLAN_v1.md` per `../../references/plan-artifact-template.md`.
-- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default sequence: one `Reviewer` round, then one `Criticizer` round; afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question. Up to five rounds total, continuing only for high-priority findings or unresolved criticizer questions; surface at most five per round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
+- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default sequence: one reviewer round (findings `F-###` plus up to five questions `Q-1..Q-5` in the same output); ask every question with `ask_choice`, record the answers, then revise. Afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question. Up to five rounds total, continuing only for high-priority findings or unresolved reviewer questions; surface at most five per round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 
 ## Fit
 

package/skills/plan-small/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-small
-description: Create a small Pi plan before implementation. Use for small scoped repo changes needing 1 to 3 planning questions and one criticizer refinement pass; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+description: Create a small Pi plan before implementation. Use for small scoped repo changes needing 1 to 3 planning questions and one reviewer refinement pass; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
 ---
 
 # Plan Small
@@ -9,15 +9,15 @@ Use this skill when the user wants a compact plan before a repository change.
 
 ## Pi Setup
 
-Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run the refinement round with the `refine` tool.
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi-plans/`. Ask every question with the `ask_choice` tool; run the refinement round with the `refine` tool.
 
 ## Depth Contract
 
 - Inspect the target Git repo read-only before the first product question.
 - Ask 1 to 3 planning questions via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last). Every option you write carries a `description` of `✓ <advantage> / ✗ <drawback>` in the configured language, kept terse — the user chooses by weighing what each option gains against what it costs. With 2-3 ready questions, batch them into ONE `questions: [...]` form call; a single question uses the classic `question` form.
 - Batch protocol (0.4.0): when a round has several questions, submit them together as one `ask_choice` call with `questions: [...]` (2-8 items, recommended option first per question) — the tool opens one tabbed multiple-choice form with a submit page instead of asking one at a time. After the batch returns, think about the answers, then follow up in later calls (batch again for 2+ related follow-ups; single `question` for one). `Esc` on the form returns the answered subset as partial answers — continue with what you got and re-ask only what matters. The final scope confirmation and the execution handoff are ALWAYS single-question calls with `autoComplete: false`; batches reject those questions.
-- Ask the final scope confirmation, then write `PLAN_v1.md` under the artifact root (normally the configured workspace root, default `./docs/pi-plans/YYYY-MM-DD-topic/`) per `../../references/plan-artifact-template.md`.
-- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default: exactly one round, recommended mode `Criticizer`; afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round), then the `execute_plan` tool.
+- Ask the final scope confirmation, then write `PLAN_v1.md` under the artifact root (normally the configured workspace root, default `./.git/pi-plans/plans/YYYY-MM-DD-topic/`) per `../../references/plan-artifact-template.md`.
+- After each plan version, ask the merged accept/execute question via `ask_choice` with `autoComplete: false` — never run `refine` unless the user picked another round at that question. Default: exactly one reviewer round (findings plus up to five questions); afterwards the recommended option is `✓ Accept & execute now` in the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round), then the `execute_plan` tool.
 
 ## Fit