pi-plans 0.5.7 → 0.7.0

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"];
+	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 {
@@ -131,7 +142,7 @@ function validatePackageMetadata(): void {
 	if (!skills.has("./skills")) fail("package.json: pi.skills must include ./skills");
 
 	const files = new Set((pkg.files ?? []).map(normalizePackageEntry));
-	for (const required of ["README.md", "LICENSE", "index.ts", "agents", "references", "scripts", "skills", "src", "tests", "tools"]) {
+	for (const required of ["README.md", "LICENSE", "CONTRIBUTING.md", "index.ts", "agents", "references", "scripts", "skills", "src", "tests", "tools"]) {
 		if (!files.has(required)) fail(`package.json: files must include ${required}`);
 	}
 	for (const excluded of ["!scripts/bench/vendor", "!scripts/bench/results"]) {
@@ -153,6 +164,7 @@ const PACK_BLACKLIST_PREFIXES = ["scripts/bench/vendor/", "scripts/bench/results
 const REQUIRED_PACK_ENTRIES = [
 	"README.md",
 	"LICENSE",
+	"CONTRIBUTING.md",
 	"index.ts",
 	"package.json",
 	"agents/reviewer.md",
@@ -234,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,13 +9,13 @@ 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
 
 1. Inspect available evidence first: repository files, logs, tests, command output, stack traces, recent diffs, CI output, environment details, and user-provided symptoms.
 2. Produce an in-message RCA summary before asking whether to plan. Use at most 5 Whys. Stop with `unknown` when evidence is insufficient; do not invent a cause.
-3. Ask one `ask_choice` question in the configured language whose preamble includes the RCA summary, with these options:
+3. Ask one `ask_choice` question in the configured language whose preamble includes the RCA summary, with these options. Every option you write carries a `description` of `✓ <advantage> / ✗ <drawback>` in the configured language, kept terse:
    1. `Create the scoped fix plan` — recommended when evidence supports a planning path.
    2. `Stop after RCA` — keep the diagnosis only.
    3. `Other` / 4. `Auto-complete` are added by the tool.
@@ -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,16 +9,16 @@ 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
 
 - Inspect the target Git repo read-only before the first product question.
-- Ask at least 10 planning questions; no maximum — stop only when the decision tree is genuinely resolved. Each via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last). Phase them in batches of up to 8: submit ONE `questions: [...]` form call per phase, think about the answers, then continue with the next batch or follow-ups.
+- Ask at least 10 planning questions; no maximum — stop only when the decision tree is genuinely resolved. Each 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. Phase them in batches of up to 8: submit ONE `questions: [...]` form call per phase, think about the answers, then continue with the next batch or follow-ups.
 - 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.
+- 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,16 +9,16 @@ 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
 
 - Inspect the target Git repo read-only before the first product question.
-- Ask 5 to 10 planning questions via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last). Submit the first batch of up to 8 as ONE `questions: [...]` form call, think about the answers, then follow up in later batches (2+ related questions) or single-question calls.
+- Ask 5 to 10 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. Submit the first batch of up to 8 as ONE `questions: [...]` form call, think about the answers, then follow up in later batches (2+ related questions) or single-question calls.
 - 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.
+- 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). With 2-3 ready questions, batch them into ONE `questions: [...]` form call; a single question uses the classic `question` form.
+- 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
 

package/skills/plan-with-refs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-with-refs
-description: Research references before creating a Pi plan. Use when repo-change planning needs downloaded projects, articles, papers, docs, per-reference analysis, adoption questions, language settings, and reviewer or criticizer refinement; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+description: Research references before creating a Pi plan. Use when repo-change planning needs downloaded projects, articles, papers, docs, per-reference analysis, adoption questions, language settings, and reviewer refinement (findings plus questions); exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
 ---
 
 # Plan With Refs
@@ -9,22 +9,22 @@ Use this skill when external references must shape the plan before implementatio
 
 ## 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 and adoption 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 and adoption questions into one `questions: [...]` form call, 2-8 items; scope/handoff stays single-question with `autoComplete: false`); run refinement rounds with the `refine` tool.
 
 ## Required Reference Flow
 
 1. Inspect the target Git repo read-only before external research so search terms match the actual codebase and constraints.
-2. Create the `.git/pi_plans` run state and planning artifact directory once the topic is clear (`plans` action `start-run`).
+2. Create the `.git/pi-plans` run state and planning artifact directory once the topic is clear (`plans` action `start-run`).
 3. Search proactively for related projects, articles, papers, docs, and prior art. Prefer a websearch skill when installed; otherwise use bash tools such as `curl` or `gh` when already available.
-4. Before the first download, check `refs_root` in `.git/pi_plans/config.json` (`plans` action `show`). If it is unset, ask exactly one `ask_choice` question — recommended `.git/pi-plans/refs/` (inside the git dir, never tracked), second `./refs/`, third `~/.cache/pi-plans/refs/` — and persist with `plans` (`set-refs-root`); this question does not count against the planning-question limit. Then download or clone at least 3 credible references before writing `PLAN_v1.md`, under the configured refs root (create per-ref subdirectories). Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
-5. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and in the run's `refs.jsonl` (via `plans` action `record-ref`): title, URL, kind, retrieval method, date accessed, local path, coverage, and evidence gaps.
+4. Before the first download, check `refs_root` in `.git/pi-plans/config.json` (`plans` action `show`). If it is unset, ask exactly one `ask_choice` question — recommended `.git/pi-plans/refs/` (inside the git dir, never tracked), second `./refs/`, third `~/.cache/pi-plans/refs/` — with each option's `description` set to `✓ <advantage> / ✗ <drawback>` in the configured language, kept terse, and persist with `plans` (`set-refs-root`); this question does not count against the planning-question limit. Then download at least 3 credible references across at least 2 distinct origins before writing `PLAN_v1.md`, under the configured refs root (one subdirectory per reference — `analyze_refs` requires directories). References are NOT limited to GitHub repositories: papers (e.g. arXiv), engineering blog posts, and documentation sites are first-class, and theoretical references count exactly as much as implementation references. A download is qualified per medium: repo = clone (full working tree); paper = the full text (arXiv HTML preferred, else the PDF with extracted text into `paper.txt`/`paper.md`; an abstract alone never qualifies); blog/docs site = the full-article readable markdown saved locally (single-page posts are fine — they ARE the source; only fragments or teasers fail). Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
+5. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and in the run's `refs.jsonl` (via `plans` action `record-ref`): title, URL, kind (`project` for repos, `paper` for papers, `article` for blog posts, `docs` for documentation sites), retrieval method, date accessed, local path, coverage, and evidence gaps.
 6. For every reference, run the `analyze_refs` tool (required path — it replaces manual structured reads): one independent read-only subagent per reference deep-reads it and returns structured sections (Overview / Key Mechanisms And Design Tradeoffs / Adoptable Ideas For The Target Repo / Pitfalls And Anti-Patterns / Evidence Citations / Coverage / Evidence Gaps). Paste each analysis into `REF_ANALYSIS.md` and fill `coverage` and `gaps` in `refs.jsonl` via `plans` (`record-ref`) before asking adoption questions.
-7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both). Batch one reference's adoption questions into a single `questions: [...]` form call.
+7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both). Every option you write carries a `description` of `✓ <advantage> / ✗ <drawback>` in the configured language, kept terse — adoption choices trade a real gain against a real cost, so state both. Batch one reference's adoption questions into a single `questions: [...]` form call.
 8. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum. `Auto-complete` cannot grant this waiver.
-9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round, then a criticizer round), no refinement limit, at most five high-priority comments or questions per refinement 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.
+9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round carrying findings and questions), no refinement limit, at most five high-priority comments or questions per refinement 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.
 
 ## REF_ANALYSIS.md
 
-Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; configured refs root and local download paths; the per-reference `analyze_refs` structured analyses (pasted verbatim, one section per reference); adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.
+Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; configured refs root and local download paths; the per-reference `analyze_refs` structured analyses (pasted verbatim, one section per reference); adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and reviewer settings used.
 
 Reference ideas are not eligible for `PLAN_v1.md` until their adoption question answers are recorded.

package/skills/planning/SKILL.md

@@ -19,4 +19,4 @@ Use this skill when a task is planning-related but the right specialist is not o
 
 ## Pi Setup
 
-Use the same language, `ask_choice`, `refine`, reviewer, criticizer, Auto-complete, and `.git/pi_plans` rules as the selected specialist skill and the shared workflow. Questions prefer the 0.4.0 batch form: one `ask_choice` call with `questions: [...]` (2-8) opens a tabbed multiple-choice form; scope confirmation and execution handoff stay single-question with `autoComplete: false`.
+Use the same language, `ask_choice`, `refine`, reviewer, Auto-complete, and `.git/pi-plans` rules as the selected specialist skill and the shared workflow — including the per-option `✓ <advantage> / ✗ <drawback>` descriptions, which every option you write carries in the configured language, kept terse. Questions prefer the 0.4.0 batch form: one `ask_choice` call with `questions: [...]` (2-8) opens a tabbed multiple-choice form; scope confirmation and execution handoff stay single-question with `autoComplete: false`.

package/src/ask-form.ts

@@ -3,7 +3,7 @@
  *
  * The form is a tabbed dialog opened via ctx.ui.custom: one tab per question
  * (options always visible in the first frame — options-first fit contract from
- * pi-goal-x's questionnaire) plus a final submit page listing every Q/A, and a
+ * a guided multi-question questionnaire) plus a final submit page listing every Q/A, and a
  * custom-answer row per tab that switches into a Focusable single-line input
  * (CURSOR_MARKER + hardware cursor so zh-Hans IME composition works).
  *
@@ -69,7 +69,7 @@ export interface FormState {
 	custom: (string | null)[];
 	/** Whether the user explicitly confirmed an answer on tab i (Enter on an
 	 * option row or a committed custom answer). The cursor `selection` alone
-	 * never flips this — goal-x aligned ■/□ chips read this field. */
+	 * never flips this — the ■/□ chips read this field. */
 	confirmed: boolean[];
 	/** Current tab: 0..N-1 = question tabs, N = submit page. */
 	tab: number;
@@ -86,7 +86,7 @@ export function createFormState(questions: FormQuestion[], lang: UiLanguage = "e
 		// Cursor position per tab: pre-positioned on the recommended option
 		// where present. This is ONLY the highlight — an answer counts only
 		// after the user confirms it (Enter/custom submit), tracked in
-		// `confirmed` (pi-goal-x semantics: chips show □ until answered).
+		// `confirmed` semantics: chips show □ until answered.
 		selection: questions.map((q) => q.options.findIndex((o) => o.recommended === true)),
 		confirmed: questions.map(() => false),
 		custom: questions.map(() => null),
@@ -286,7 +286,7 @@ export const FORM_ROWS_RESERVE = 4;
 export const FORM_FALLBACK_ROWS = 30;
 
 /**
- * pi-goal-x aligned question-tab frame: accent borders, tab chips with a
+ * themed question-tab frame: accent borders, tab chips with a
  * selectedBg background on the active chip (■ answered / □ pending), colored
  * question line, dim key hints. Under a `rows` budget it degrades richest
  * first — descriptions, then blank separators, then the borders (the chips

package/src/auditor.ts

@@ -0,0 +1,126 @@
+/**
+ * Completion auditor (v0.6.1): when every task reaches a terminal state, an
+ * independent read-only subagent verifies the plan's verification checks
+ * against the worktree. Failed checks roll their covered tasks back to
+ * pending (exclusively inside the audit flow); three failed rounds pause the
+ * run for the user — or terminate it as stopped under auto-approve/headless
+ * so pipelines never hang.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import { auditRollbackSet, auditableChecks, skippedPassCheckIds, type TaskView } from "./tasks.ts";
+import type { CheckItem } from "./plan.ts";
+import { messaging } from "./messaging.ts";
+
+export const AUDIT_MAX_ROUNDS = 3;
+
+export interface AuditOutcome {
+	round: number;
+	passed: string[];
+	failed: string[];
+	/** Rolled-back task ids (empty when the audit passed). */
+	rolledBack: string[];
+	report: string;
+}
+
+/** Build the audit brief for the read-only subagent. Exported for tests. */
+export function buildAuditTask(planPath: string, checklist: CheckItem[], tasks: TaskView[], round: number): string {
+	const checks = auditableChecks(checklist, tasks)
+		.map((check) => `- \`${check.id}\`: ${check.text}`)
+		.join("\n");
+	return `Goal: verify that the implemented worktree satisfies the accepted plan's verification checks.
+
+Target plan: ${planPath} (audit round ${round})
+
+Authority boundary: read-only analysis only. Do not edit, write, delete, commit, push, or spawn subagents.
+
+Evidence: inspect the repository with read, grep, find, ls, and targeted commands (bash is not granted — rely on the read tools) before judging each check. Tests may be referenced from their recorded evidence; do not re-run them.
+
+Checks to verify (only these; checks covering no task are excluded):
+
+${checks}
+
+Output: Markdown with exactly one section per check, in checklist order:
+
+- \`VC-###\` — verdict: pass | fail; evidence: <repo path/command proving it>; note: <one line>.
+
+Every check needs a verdict backed by evidence you actually inspected. If the evidence is inconclusive, verdict is fail with what is missing.`;
+}
+
+/** Parse the audit subagent's verdict lines. Exported for tests. */
+export function parseAuditReport(report: string, checklist: CheckItem[]): { passed: string[]; failed: string[] } {
+	const passed: string[] = [];
+	const failed: string[] = [];
+	const known = new Set(checklist.map((item) => item.id));
+	for (const match of report.matchAll(/`?(VC-\d+)`?[^\n]*?verdict:\s*(pass|fail)/gi)) {
+		const id = match[1].toUpperCase();
+		if (!known.has(id)) continue;
+		(match[2].toLowerCase() === "pass" ? passed : failed).push(id);
+	}
+	// Dedupe, keep first occurrence order; a check with conflicting verdicts fails.
+	for (const id of [...passed]) if (failed.includes(id)) passed.splice(passed.indexOf(id), 1);
+	return { passed: [...new Set(passed)], failed: [...new Set(failed)] };
+}
+
+/** Pure decision core: given a parsed report, mutate the task tree with the
+ * rollback set. Returns the outcome (rolled-back ids). Exported for tests. */
+export function applyAuditOutcome(
+	checklist: CheckItem[],
+	tasks: TaskView[],
+	round: number,
+	passed: string[],
+	failed: string[],
+	report: string,
+): AuditOutcome {
+	for (const id of passed) {
+		const item = checklist.find((candidate) => candidate.id === id);
+		if (item) item.done = true;
+	}
+	const rolledBack: string[] = [];
+	for (const id of failed) {
+		rolledBack.push(...auditRollbackSet(tasks, checklist, id));
+	}
+	return { round, passed, failed, rolledBack, report };
+}
+
+/** Skipped-pass checks (all covered tasks skipped) pass without audit. */
+export function presolvedCheckIds(checklist: CheckItem[], tasks: TaskView[]): string[] {
+	return skippedPassCheckIds(checklist, tasks);
+}
+
+/** Spawn the audit subagent and apply its outcome. Returns null when the
+ * audit subagent itself failed to run (treated as a failed round with an
+ * empty rollback; the caller counts it against the round cap). */
+export async function runCompletionAudit(
+	ctx: ExtensionContext,
+	opts: {
+		planPath: string;
+		checklist: CheckItem[];
+		tasks: TaskView[];
+		round: number;
+		model?: string;
+		signal?: AbortSignal;
+	},
+): Promise<AuditOutcome | null> {
+	const { runPiSubagent } = await import("./subagent.ts");
+	const task = buildAuditTask(opts.planPath, opts.checklist, opts.tasks, opts.round);
+	let agentPrompt = "You are a read-only completion auditor for pi-plans.";
+	try {
+		agentPrompt = fs.readFileSync(new URL("../agents/reviewer.md", import.meta.url), "utf8");
+	} catch {
+		/* fall back to the inline prompt */
+	}
+	const result = await runPiSubagent({
+		systemPrompt: `${agentPrompt}\n\nYou are acting as the completion auditor; the task brief below defines the output contract.`,
+		task,
+		cwd: ctx.cwd,
+		model: opts.model,
+		tools: ["read", "grep", "find", "ls"],
+		signal: opts.signal,
+	});
+	if (!result.ok) return null;
+	const { passed, failed } = parseAuditReport(result.output, opts.checklist);
+	messaging().appendEntry("pi-plans-audit", { planPath: opts.planPath, round: opts.round, passed, failed });
+	return applyAuditOutcome(opts.checklist, opts.tasks, opts.round, passed, failed, result.output);
+}

package/src/auto-approve.ts

@@ -28,7 +28,7 @@ export function isAutoApproveEnabled(): boolean {
  * must answer interactively) while a false negative would silently bypass a
  * safety gate. Word-boundary anchored where short words could over-match.
  * NOTE: package *installation inside a disposable benchmark container* is
- * plan-lifecycle (the criticizer legitimately asks about installing deps);
+ * plan-lifecycle (the reviewer legitimately asks about installing deps);
  * only externally-visible state (publish/deploy/merge/push/credentials/...)
  * is hard-rejected. Install-permission waivers are still caught via
  * "waiver". */

package/src/autocomplete.ts

@@ -3,6 +3,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getRun, readActive } from "./state.ts";
 import { resolveActiveRun } from "./run-context.ts";
+import { messaging, tryMessaging } from "./messaging.ts";
 
 export const AUTOCOMPLETE_ENTRY = "pi-plans-autocomplete";
 const AUTOCOMPLETE_CONTINUE = "Continue the current planning workflow. Raise the next relevant question with ask_choice; do not stop after an auto-completed answer.";
@@ -22,12 +23,6 @@ type SessionWithAutoComplete = ExtensionContext["sessionManager"] & {
 	__piPlansAutoComplete?: AutoCompleteState;
 };
 
-let api: ExtensionAPI | null = null;
-
-export function setAutoCompleteApi(next: ExtensionAPI | null): void {
-	api = next;
-}
-
 function sessionState(ctx: ExtensionContext): AutoCompleteState | undefined {
 	return (ctx.sessionManager as SessionWithAutoComplete).__piPlansAutoComplete;
 }
@@ -39,9 +34,17 @@ function activePlanningRun(ctx: ExtensionContext): { runId: string } | null {
 	return run?.status === "planning" ? { runId: run.run_id } : null;
 }
 
-function appendState(runId: string, enabled: boolean, reason?: string): void {
-	if (!api) return;
-	api.appendEntry(AUTOCOMPLETE_ENTRY, { runId, enabled, ...(reason ? { reason } : {}) });
+function appendState(ctx: ExtensionContext, runId: string, enabled: boolean, reason?: string): void {
+	// Best-effort persistence: the in-memory session state is authoritative for
+	// the live turn; never let an unwired (tests) or stale (session swap) messaging
+	// surface break the ask_choice / handoff flows that call this.
+	const m = tryMessaging();
+	if (!m) return;
+	try {
+		m.appendEntry(AUTOCOMPLETE_ENTRY, { runId, enabled, ...(reason ? { reason } : {}) });
+	} catch {
+		/* session swap in flight; the entry is optional */
+	}
 }
 
 export function enableAutoComplete(ctx: ExtensionContext): boolean {
@@ -57,7 +60,7 @@ export function enableAutoComplete(ctx: ExtensionContext): boolean {
 		autoChoiceCount: 0,
 		planWritten: false,
 	};
-	appendState(run.runId, true);
+	appendState(ctx, run.runId, true);
 	return true;
 }
 
@@ -67,7 +70,7 @@ export function disableAutoComplete(ctx: ExtensionContext, reason = "disabled"):
 	const runId = state?.runId ?? run?.runId;
 	if (!runId && !state?.enabled) return false;
 	if (state) state.enabled = false;
-	if (runId) appendState(runId, false, reason);
+	if (runId) appendState(ctx, runId, false, reason);
 	return true;
 }
 
@@ -110,12 +113,12 @@ export function shouldContinueAutoComplete(ctx: ExtensionContext): boolean {
 }
 
 export async function continueAutoComplete(ctx: ExtensionContext): Promise<boolean> {
-	if (!api || !shouldContinueAutoComplete(ctx)) return false;
+	if (!shouldContinueAutoComplete(ctx)) return false;
 	const state = sessionState(ctx);
 	if (!state) return false;
 	state.pendingFollowUp = true;
 	try {
-		await api.sendUserMessage(AUTOCOMPLETE_CONTINUE, { deliverAs: "followUp" });
+		await messaging().sendUserMessage(AUTOCOMPLETE_CONTINUE, { deliverAs: "followUp" });
 		return true;
 	} catch {
 		state.pendingFollowUp = false;
@@ -123,12 +126,11 @@ export async function continueAutoComplete(ctx: ExtensionContext): Promise<boole
 	}
 }
 
-export function registerAutoCompleteTurnHandlers(pi: ExtensionAPI): void {
-	setAutoCompleteApi(pi);
-	pi.on("turn_start", async (_event, ctx) => {
+export function registerAutoCompleteTurnHandlers(ext: ExtensionAPI): void {
+	ext.on("turn_start", async (_event, ctx) => {
 		resetAutoCompleteTurn(ctx);
 	});
-	pi.on("turn_end", async (event, ctx) => {
+	ext.on("turn_end", async (event, ctx) => {
 		const message = event.message as { role?: string } | undefined;
 		if (message?.role === "assistant") await continueAutoComplete(ctx);
 	});

package/src/code-graph/commands.ts

@@ -153,7 +153,7 @@ export async function initGraphCommand(args: string, ctx: CommandContext): Promi
 			"info",
 		);
 		try {
-			const reportPath = generateGraphReport(store, `${paths.gitCommonDir}/pi_plans/graph`, {
+			const reportPath = generateGraphReport(store, `${paths.gitCommonDir}/pi-plans/graph`, {
 				files: report.filesScanned,
 				functions: report.functionsIndexed,
 				ms: report.durationMs,
@@ -441,7 +441,7 @@ async function runChangedPathSync(
 		"info",
 	);
 	try {
-		generateGraphReport(store, `${paths.gitCommonDir}/pi_plans/graph`, {
+		generateGraphReport(store, `${paths.gitCommonDir}/pi-plans/graph`, {
 			files: report.filesScanned,
 			functions: report.functionsIndexed,
 			ms: report.durationMs,

package/src/code-graph/community.ts

@@ -164,7 +164,7 @@ export function computeCommunities(store: Store): {
 	return { communities: sortedGroups.length, nodes: order.length, godNodes };
 }
 
-/** Render GRAPH_REPORT.md (plan R-005) under `<gitCommonDir>/pi_plans/graph/`. */
+/** Render GRAPH_REPORT.md (plan R-005) under `<gitCommonDir>/pi-plans/graph/`. */
 export function generateGraphReport(store: Store, graphDir: string, baseline?: { files: number; functions: number; ms: number }): string {
 	const stats = computeCommunities(store);
 	const edgeStats = store.read(() =>

package/src/code-graph/paths.ts

@@ -34,7 +34,7 @@ export function resolveCanonicalWorktree(workdir: string): WorktreePaths {
 	}
 	const worktreeRoot = path.resolve(toplevel.stdout.trim());
 	const gitCommonDir = path.resolve(workdir, common.stdout.trim());
-	const stateRoot = path.join(gitCommonDir, "pi_plans");
+	const stateRoot = path.join(gitCommonDir, "pi-plans");
 	if (!resolveStateRootOrNull(workdir)) {
 		throw new PathError(`pi-plans state missing; run a planning init first`);
 	}

package/src/code-graph/watch.ts

@@ -4,7 +4,7 @@
  * pinned to the pi extension hooks — started by /watch-graph (or session_start
  * when the enabled marker is set), stopped by /unwatch-graph, disable-graph,
  * and an idempotent session_shutdown handler. A PID+heartbeat lock under
- * .git/pi_plans/graph/watch keeps a single writer per worktree across pi
+ * .git/pi-plans/graph/watch keeps a single writer per worktree across pi
  * sessions; per-file single-flight dedupes apply-trigger vs watch events.
  */
 
@@ -32,7 +32,7 @@ interface ActiveWatcher {
 const activeWatchers = new Map<string, ActiveWatcher>();
 
 function graphDir(paths: WorktreePaths): string {
-	return path.join(paths.gitCommonDir, "pi_plans", "graph");
+	return path.join(paths.gitCommonDir, "pi-plans", "graph");
 }
 
 function lockPath(paths: WorktreePaths): string {

package/src/compaction.ts

@@ -994,9 +994,9 @@ function phaseContextLines(context?: PiPlansVccPhaseContext): Partial<Record<typ
 	const outstandingContext: string[] = [];
 	if (context.phase === "execution") {
 		sessionGoal.push(context.planPath ? `Execute accepted plan ${context.planPath}` : "Execute the accepted pi-plans plan");
-		if (context.currentI) outstandingContext.push(`Current implementation item: ${context.currentI}`);
-		if (context.remainingVerifierIds?.length) outstandingContext.push(`Remaining verifier items: ${context.remainingVerifierIds.slice(0, 12).join(", ")}`);
-		if (context.implementationIds?.length) outstandingContext.push(`Implementation items: ${context.implementationIds.slice(0, 16).join(", ")}`);
+		if (context.currentI) outstandingContext.push(`Current task: ${context.currentI}`);
+		if (context.remainingVerifierIds?.length) outstandingContext.push(`Remaining verification checks: ${context.remainingVerifierIds.slice(0, 12).join(", ")}`);
+		if (context.implementationIds?.length) outstandingContext.push(`Plan tasks: ${context.implementationIds.slice(0, 24).join(", ")}`);
 	} else {
 		sessionGoal.push(context.runId ? `Continue active planning run ${context.runId}` : "Continue active pi-plans planning");
 		if (context.planPath) outstandingContext.push(`Latest plan path from session: ${context.planPath}`);