pi-plans 0.6.0 → 0.8.0

package/scripts/validate.ts

@@ -17,7 +17,12 @@ 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", "execution-reviewer.md"];
+// Root-level docs that must exist and must be entirely English (see AGENTS.md).
+const REQUIRED_ROOT_DOCS = ["AGENTS.md", "CHANGELOG.md"];
+// CJK ideographs plus full-width CJK punctuation. Ideographs alone are not
+// enough: a file can read untranslated while carrying full-width punctuation.
+const CJK_RE = /[　-〿一-鿿＀-￯]/;
 const REQUIRED_TOOL_FILES = [
 	"tools/plans.ts",
 	"tools/ask-choice.ts",
@@ -26,6 +31,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 +75,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 +83,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 +147,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", "CONTRIBUTING.md", "index.ts", "agents", "references", "scripts", "skills", "src", "tests", "tools"]) {
+	for (const required of ["README.md", "LICENSE", "CONTRIBUTING.md", "AGENTS.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"]) {
@@ -154,6 +170,7 @@ const REQUIRED_PACK_ENTRIES = [
 	"README.md",
 	"LICENSE",
 	"CONTRIBUTING.md",
+	"AGENTS.md",
 	"index.ts",
 	"package.json",
 	"agents/reviewer.md",
@@ -235,8 +252,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`);
 		}
 	}
 
@@ -252,13 +269,24 @@ function main(): void {
 		if (!fs.existsSync(path.join(ROOT, tool))) fail(`missing ${tool}`);
 	}
 
+	for (const doc of REQUIRED_ROOT_DOCS) {
+		const file = path.join(ROOT, doc);
+		if (!fs.existsSync(file)) {
+			fail(`missing root doc ${doc}`);
+			continue;
+		}
+		if (CJK_RE.test(fs.readFileSync(file, "utf8"))) {
+			fail(`${doc}: must be entirely English (no CJK ideographs or full-width CJK punctuation)`);
+		}
+	}
+
 	if (!fs.existsSync(path.join(ROOT, "index.ts"))) fail("missing index.ts");
 
 	validateDefaultConfig();
 	validatePlansTool();
 	validatePackageMetadata();
 	validatePackageArtifact();
-	console.log(`validated ${EXPECTED_SKILLS.size} skills, ${REQUIRED_REFERENCES.length} references, ${REQUIRED_AGENTS.length} agents, ${REQUIRED_TOOL_FILES.length} tools`);
+	console.log(`validated ${EXPECTED_SKILLS.size} skills, ${REQUIRED_REFERENCES.length} references, ${REQUIRED_AGENTS.length} agents, ${REQUIRED_TOOL_FILES.length} tools, ${REQUIRED_ROOT_DOCS.length} docs`);
 }
 
 main();

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
 

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/` — 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.
+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). 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 — 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`.
+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,227 @@
+/**
+ * Execution reviewer (v0.8): 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 review flow). The
+ * loop is bounded at REVIEW_MAX_ROUNDS committed rounds; exhaustion pauses
+ * the run for the user in every mode (fail-closed, never a hang and never a
+ * silent stop) — only an explicit /plans-execute confirmation grants a fresh
+ * budget.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { auditableChecks, skippedPassCheckIds, type TaskView } from "./tasks.ts";
+import type { CheckItem } from "./plan.ts";
+import { messaging } from "./messaging.ts";
+
+/** Budget cap: committed rounds per user-granted budget. Discarded (fingerprint-changed) attempts do not count. */
+export const REVIEW_MAX_ROUNDS = 5;
+
+/** Legacy alias for one release: checkpoints and old builds still know this name. */
+export const AUDIT_MAX_ROUNDS = REVIEW_MAX_ROUNDS;
+
+export interface AuditOutcome {
+	round: number;
+	passed: string[];
+	failed: string[];
+	/** Checks whose report carried no readable verdict, or whose evidence was
+	 * inconclusive. Never treated as `failed`: see src/exec.ts. */
+	undeterminable: string[];
+	report: string;
+}
+
+/** Parse the verdict lines of an audit report against the checks that are
+ * still pending. A pending check with no readable verdict is
+ * `undeterminable`, never `failed` — the caller must be able to tell "the
+ * work is wrong" apart from "I could not read the answer". */
+export interface ParsedAudit {
+	passed: string[];
+	failed: string[];
+	undeterminable: string[];
+}
+
+/** Checks this round must judge: auditable (covering at least one task) and
+ * not already done. The brief and the coverage self-check both use this, so a
+ * well-formed round-2 report that omits an already-done check is not mistaken
+ * for a contract violation. */
+export function auditablePendingChecks(checklist: CheckItem[], tasks: TaskView[]): CheckItem[] {
+	return auditableChecks(checklist, tasks).filter((item) => !item.done);
+}
+
+/** 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 = auditablePendingChecks(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 and checks already satisfied in an earlier round are excluded):
+
+${checks}
+
+Output: Markdown with exactly one section per check, in the order above:
+
+- \`VC-###\` — verdict: pass | fail | undeterminable; evidence: <repo path/command proving it>; note: <one line>.
+
+Emit every listed check exactly once. \`undeterminable\` is a legitimate answer: use it whenever the evidence is missing, unreadable, ambiguous, or beyond your read-only reach. Report \`fail\` only when you can point at the specific thing that breaks the condition — never report \`fail\` for want of evidence.`;
+}
+
+/** Parse the audit subagent's verdict lines. Exported for tests. */
+export function parseAuditReport(report: string, pendingVcIds: string[]): ParsedAudit {
+	const passed: string[] = [];
+	const failed: string[] = [];
+	const known = new Set(pendingVcIds.map((id) => id.toUpperCase()));
+	// The auditor writes Markdown, so a verdict may carry emphasis
+	// (`**pass**`, `*pass*`, `_pass_`, `` `pass` ``). Requiring a bare token
+	// silently discarded such verdicts, and the caller's fail-closed rule then
+	// marked every check failed and rolled the whole run back -- reporting
+	// correct work as failure. Tolerate the markers; \b keeps `passed` and
+	// `passing` from matching.
+	for (const match of report.matchAll(/`?(VC-\d+)`?[^\n]*?verdict:\s*[*_`~]*\s*(pass|fail|undeterminable)\b/gi)) {
+		const id = match[1].toUpperCase();
+		if (!known.has(id)) continue;
+		const verdict = match[2].toLowerCase();
+		if (verdict === "pass") passed.push(id);
+		else if (verdict === "fail") failed.push(id);
+	}
+	// A check with conflicting verdicts resolves to fail: the reader saw both.
+	for (const id of [...new Set(passed)]) if (failed.includes(id)) passed.splice(passed.indexOf(id), 1);
+	const undecided = new Set(known);
+	for (const id of [...passed, ...failed]) undecided.delete(id);
+	return { passed: [...new Set(passed)], failed: [...new Set(failed)], undeterminable: [...undecided] };
+}
+
+/** Pure decision core: classify a parsed report into the audit outcome. It
+ * touches neither the checklist nor the task tree — the caller owns writing
+ * `done` and computing the rollback set, so there is exactly one authority for
+ * both. Exported for tests. */
+export function applyAuditOutcome(round: number, parsed: ParsedAudit, report: string): AuditOutcome {
+	return {
+		round,
+		passed: parsed.passed,
+		failed: parsed.failed,
+		undeterminable: parsed.undeterminable,
+		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 classify its report. Returns `{ cancelled: true }`
+ * when the child was aborted (session shutdown, stop, restore, tree switch) —
+ * such a round burns no budget and sends no wake; `null` when the subagent
+ * itself failed to run (treated as an all-undeterminable committed round; the
+ * caller counts it against the round cap). */
+export type AuditRoundResult = AuditOutcome | { cancelled: true } | null;
+
+export async function runCompletionAudit(
+	ctx: ExtensionContext,
+	opts: {
+		planPath: string;
+		checklist: CheckItem[];
+		tasks: TaskView[];
+		round: number;
+		model?: string;
+		thinkingLevel?: string;
+		timeoutMs?: number;
+		signal?: AbortSignal;
+		onProgress?: (event: import("./subagent.ts").SubagentProgressEvent) => void;
+	},
+): Promise<AuditRoundResult> {
+	const { runPiSubagent } = await import("./subagent.ts");
+	const pending = auditablePendingChecks(opts.checklist, opts.tasks);
+	const task = buildAuditTask(opts.planPath, opts.checklist, opts.tasks, opts.round);
+	// agents/auditor.md, not agents/reviewer.md: the reviewer prompt mandates a
+	// plan-review shape (`## Findings` / `## Questions`, F-###) and never says
+	// "verdict", so auditing under it produced reports this parser could not
+	// read at all -- every check then fell through to fail-closed.
+	// v0.8: a missing agent definition is a hard error — the silent inline
+	// fallback once swapped in a minimal prompt that produced unparsable
+	// reports and burned whole audit budgets as undeterminable.
+	const agentPrompt = fs.readFileSync(new URL("../agents/execution-reviewer.md", import.meta.url), "utf8");
+	const result = await runPiSubagent({
+		systemPrompt: agentPrompt,
+		task,
+		cwd: ctx.cwd,
+		model: opts.model,
+		thinkingLevel: opts.thinkingLevel,
+		timeoutMs: opts.timeoutMs,
+		tools: ["read", "grep", "find", "ls"],
+		signal: opts.signal,
+		onProgress: opts.onProgress,
+	});
+	if (!result.ok) {
+		if (result.cancelled === true) return { cancelled: true };
+		return null;
+	}
+	const parsed = parseAuditReport(result.output, pending.map((item) => item.id));
+	messaging().appendEntry("pi-plans-audit", {
+		planPath: opts.planPath,
+		round: opts.round,
+		passed: parsed.passed,
+		failed: parsed.failed,
+		undeterminable: parsed.undeterminable,
+	});
+	return applyAuditOutcome(opts.round, parsed, result.output);
+}
+
+/** Persist one review-round attempt under `<run-dir>/execution-review/`.
+ * The attempt index (not the budget round) names the file, so a discarded
+ * attempt's evidence survives its re-run: round-<budgetRound>-attempt-<k>.md.
+ * These files are the only cross-session record of what a round saw — the
+ * in-flight marker itself is memory-only. Best-effort: an unwritable run dir
+ * must never fail the loop itself. */
+export function writeReviewRoundReport(
+	runDir: string,
+	entry: {
+		budgetRound: number;
+		attempt: number;
+		outcome: "passed" | "failed" | "undeterminable" | "discarded" | "spawn-failed" | "cancelled";
+		passed: string[];
+		failed: string[];
+		undeterminable: string[];
+		discardedReason?: string;
+		fingerprintCaptured?: string;
+		fingerprintFound?: string;
+		coveredTaskIds: string[];
+		report: string;
+	},
+): string | null {
+	try {
+		const dir = path.join(runDir, "execution-review");
+		fs.mkdirSync(dir, { recursive: true });
+		const file = path.join(dir, `round-${entry.budgetRound}-attempt-${entry.attempt}.md`);
+		const lines = [
+			`# Execution review round ${entry.budgetRound} (attempt ${entry.attempt})`,
+			"",
+			`- outcome: ${entry.outcome}`,
+			`- passed: ${entry.passed.join(", ") || "(none)"}`,
+			`- failed: ${entry.failed.join(", ") || "(none)"}`,
+			`- undeterminable: ${entry.undeterminable.join(", ") || "(none)"}`,
+			...(entry.discardedReason ? [`- discarded: ${entry.discardedReason}`] : []),
+			`- fingerprint (captured): ${entry.fingerprintCaptured ?? "(n/a)"}`,
+			`- fingerprint (at resolve): ${entry.fingerprintFound ?? "(n/a)"}`,
+			`- covered tasks: ${entry.coveredTaskIds.join(", ") || "(none)"}`,
+			"",
+			"## Report",
+			"",
+			entry.report,
+			"",
+		];
+		fs.writeFileSync(file, lines.join("\n"), "utf8");
+		return file;
+	} catch {
+		return null;
+	}
+}

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". */