pi-plans 0.5.7 → 0.6.0

package/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to pi-plans
+
+Thanks for wanting to improve pi-plans. This guide covers the full path from a fresh clone to a merged pull request.
+
+## Expectations
+
+pi-plans is maintained by a single person in their spare time. Review may take a few days, and not every pull request gets merged — that is normal. Small fixes (typos, docs, tests, one-file bug fixes) are welcome as direct pull requests. For larger changes — new concepts, public API changes, or workflow changes — please open an issue first so we can agree on the approach before you invest time.
+
+## Ways to contribute
+
+You do not have to write code:
+
+- Reproduce a bug and post exact steps, versions, and logs in an issue
+- Fix or improve documentation (`README.md`, `references/`)
+- Improve skill copy or prompts (`skills/`, `agents/`)
+- Add or sharpen test cases (`tests/`)
+- Verify behavior on your platform (macOS, Linux, different terminals, kitty/SSH)
+
+Issues labeled `good first issue` are a good starting point.
+
+## Orientation
+
+```
+pi-plans/
+├── index.ts        # Extension entry: tools, commands, guard, execution loop
+├── tools/          # plans, ask-choice, refine, execute-plan, code-graph tools
+├── src/            # state, guard, plan parsing, subagent runner, refine UI, exec loop
+│   └── code-graph/ # SQLite schema/store, parsers, indexer, summary, materialize
+├── skills/         # Planning router plus five specialist planning skills
+├── references/     # Shared workflow, state/config, plan template (normative)
+├── agents/         # reviewer.md / criticizer.md subagent prompts (read-only)
+├── scripts/        # validate.ts (structure + package artifact guard), run-tests.ts
+└── tests/          # node:test suite
+```
+
+`npm run validate` enforces several invariants, so keep them intact:
+
+- every directory under `skills/` has a `SKILL.md` with frontmatter (`name` matching the directory, routing language in `description`) and the required phrases (`ask_choice`, `refine`, `.git/pi_plans`, ...)
+- the `reviewer` and `criticizer` agent prompts declare read-only tools and state the read-only contract
+- the npm artifact stays code-sized: no `scripts/bench/vendor|results` entries, unpacked < 5 MiB, packed < 3 MiB, and key entries present
+- `package.json` metadata (license, `pi-package` keyword, engines, scripts, required `files`) stays as asserted
+
+## Development setup
+
+Requirements: Node.js >= 22.6 (the suite runs with `--experimental-strip-types`). The code-graph tests need `node:sqlite`: Node >= 22.13 unflagged, or `--experimental-sqlite` on 22.6–22.12.
+
+If you don't have write access, fork the repository first and clone your fork.
+
+```bash
+git clone https://github.com/MaxInGaussian/pi-plans
+cd pi-plans
+npm install          # devDependencies only; nothing ships at runtime
+npm run validate     # structure + package artifact guard
+npm test             # node:test suite
+```
+
+There are no runtime dependencies, but `npm install` is still required: source modules and tests resolve `@earendil-works/pi-*` (the code-graph tests additionally need `tree-sitter`) from `node_modules` at runtime.
+
+To try the extension against a real session: `pi -e /path/to/pi-plans`.
+
+## Before you submit
+
+Run both checks locally — CI runs exactly these:
+
+```bash
+npm run validate
+npm test
+```
+
+Documentation duty: if your change alters behavior or the public API, update `README.md` or the relevant file under `references/` in the same pull request.
+
+## Commit messages
+
+Follow the existing style: `type: short imperative description` (a scope is optional, e.g. `fix(form): ...`).
+
+- `feat:` new feature
+- `fix:` bug fix
+- `docs:` documentation
+- `refactor:` no behavior change
+- `perf:` performance
+- `test:` tests only
+- `chore:` housekeeping
+- `ci:` CI changes
+
+Use the imperative mood ("fix race in ...", not "fixed ..."), keep the subject short, and use the body for motivation and evidence. Do not add generator or `Co-Authored-By` trailers.
+
+## Issues and pull requests
+
+- Small fixes, docs, and tests: open the pull request directly.
+- Larger changes (new concepts, public API or workflow changes): open an issue first and wait for a maintainer response.
+- Bug fixes: reference the issue in the title, e.g. `fix: handle empty plan path (fix #12)`.
+- Fill in the pull request template: Summary, Test Plan, and Docs sections.
+- Keep one logical change per PR when you can; multiple small commits are fine (they are squashed on merge).
+
+## Tests
+
+Every new behavior or bug fix must come with an executable test in `tests/` that fails without your change and passes with it. Tests run on `node:test` — no extra test framework is needed.
+
+## Dependencies
+
+pi-plans ships zero runtime dependencies on purpose. Before adding a dependency:
+
+- prefer a small, well-maintained package with no large transitive tree
+- add it to `devDependencies` unless it is genuinely required at runtime
+- explain in the pull request why it is needed and what you considered instead
+
+## Changelog
+
+Do not edit `CHANGELOG.md` — maintainers write release entries when publishing.
+
+## AI and agents
+
+Using AI assistance is fine, and most contributors here do. Two rules:
+
+- You must understand your change: be able to explain what it does and how it interacts with the rest of the system. Pull requests that cannot be explained will be closed.
+- Disclose AI assistance in the pull request (which tool, and to what extent). A real person must be behind every issue and PR; fully automated submissions with no human involvement may be closed.
+
+Please write pull request descriptions and review replies yourself — short and specific beats long and generated.
+
+## Code of conduct
+
+Be kind and constructive. This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## License
+
+By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE).

package/README.md

@@ -51,6 +51,7 @@ at <b>7.6× fewer tokens per solved task</b>.
 - [Safety model](#safety-model)
 - [Verification](#verification)
 - [FAQ](#faq)
+- [Contributing](#contributing)
 - [License](#license)
 
 ## How it works
@@ -127,18 +128,19 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | Capability | In short |
 |---|---|
 | Planning router + five specialist skills | Start with `/skill:planning` to route to the narrowest matching specialist (`plan-small` → `plan-big`, `debug-and-plan`, `plan-with-refs`) |
-| Choice prompts | `ask_choice`: recommended option first, answers auto-recorded per run; choosing Auto-complete enables recommendation-only answers for later eligible questions in the current planning run, with `/plans-autocomplete-stop` available to take back control. After execution completes, the continuation prompt enters goal-running mode by default: it asks only for the implementation-review loop's termination condition and then keeps refining until the loop ends or the cap is reached. |
+| Choice prompts | `ask_choice`: recommended option first, answers auto-recorded per run; every option you author states its advantage and its drawback as `✓ <advantage> / ✗ <drawback>` in the configured language, so the user can weigh each option before answering; choosing Auto-complete enables recommendation-only answers for later eligible questions in the current planning run, with `/plans-autocomplete-stop` available to take back control. After execution completes, the continuation prompt enters goal-running mode by default: it asks only for the implementation-review loop's termination condition and then keeps refining until the loop ends or the cap is reached. |
 | Refinement rounds | Read-only reviewer/criticizer Pi subagents consolidate findings into the next plan version; delegated runs have standalone `Reviewer`/`Criticizer` progress overlays that close before the tool result returns; `analyze_refs` shows the same kind of overlay titled `Refs` while per-reference analysis subagents run |
 | Workspace state | Config, runs, decisions, refs, and subagent ledgers in `.git/pi_plans/` (git common dir) |
 | VCC compact | Active planning/execution compaction uses deterministic, no-LLM VCC-style summaries when Pi core emits manual `/compact`, threshold, or overflow events. Summaries use five bracket sections plus a brief transcript, keep a smart recent tail, support `keep:N`, and write VCC details/stats without adding `/pi-vcc` commands. |
 | Visible Refiner overlay | Delegated reviewer/criticizer subagents surface as a named public overlay in the TUI — one `Reviewer`/`Criticizer` panel with per-lane tool progress, full streaming transcript with follow-bottom scroll, Tab-pane focus, retention until the user presses `Esc` after completion, and clean cancelled/timed-out vs completed states. `reviewers: 3` renders three equal-height panes inside the same overlay |
 | Tracked execution | Checklist injected each turn; `[DONE:VC-xxx]` markers drive completion; implementation items report progress with `[I-xxx:implemented]` / `[I-xxx:validating]` markers; the bottom status bar shows lifecycle, `x/y` progress, elapsed time, and input/output token usage in real time |
+| Multi-run workdirs (0.6.0) | Several pi sessions can plan concurrently in one workdir: the run registry derives from `runs/` (no shared pointer to race), each session binds to its run, and same-topic runs get suffixed artifact dirs. `/plans-abandon`, `/plans-execute`, and `/resume-plans` are binding-first and open a descriptive run-picker form when more than one candidate exists; `/plans` lists all runs (newest first, bound run marked) |
 | Goal-wait continuation | In TUI/RPC, only a fully settled agent with unpassed VCs and no pending input or compaction gets one hidden wake carrying the latest checklist. Tool turns never queue reminders or consume guard rounds. The status bar shows progress; 3 no-progress cycles or 6 waiting cycles pause continuation. User interruption and final model errors also pause it. Only genuine user input or `/plans-execute` resumes; extension messages cannot. Print/JSON single-shot sessions track progress without automatic wakes. `/plans-stop` terminates execution |
-| Execution handoff | The accepted plan resumes in the current session model; no separate model selection is performed. |
+| Execution handoff | The accepted plan resumes in the current session (recommended) or, after the runtime question, on a **delegated executor subagent** running a different model: ≥3 switch targets (session-visible models + registry, deduped), one child for the whole plan with native write tools, `Executor` overlay progress, parent-side `[DONE:VC-xxx]` tracking, Esc//`/plans-stop` → stopped (resumable), and a configurable timeout (`executor_timeout_minutes`, default 60). Auto-approve/no-UI skips the question (current session, `[auto-approve]` recorded) |
 | Execution-phase compaction | Pi core owns scheduling; pi-plans maps the active plan path, current `I-###`, implementation IDs, and remaining `VC-###` checklist into the VCC sections. The old current-I proactive trigger and model-generated summary path are removed. |
 | Planning-phase compaction | During `run.status=planning` with no active execution, pi-plans maps active run, artifact directory, latest plan path from session entries, and observed current-I markers into the VCC sections. Without an active planning run, compaction returns to Pi core. Additionally, creating a new run (`plans start-run`) proactively requests one pre-plan VCC compaction and resumes planning with a hidden message (default on; `prePlanCompact:false` disables). |
 | Efficient executor prompt | Each turn, the executor is steered by a fused rule set — Marcos Hernanz's AGENTS.md principles × Ponytail minimalism: layered growth, simplest implementation, long-term architecture (no stopgaps), library discipline — so plans finish in fewer tokens and fewer detours |
-| Write guard | `edit`/`write` blocked outside planning artifacts while a run is active |
+| Write guard | `edit`/`write` blocked outside planning artifacts while a run is active; delegated executor children (and `PI_PLANS_RUN_ID`-pinned children) are exempt so a foreign session's planning run can never block an executing child; graph-aware file tools fall back to native writes for executor children |
 
 ## Interface overview
 
@@ -148,11 +150,11 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | `ask_choice` | Numbered choice prompt; `autoComplete: false` for the merged accept/execute question and external-state questions |
 | `refine` | Reviewer/criticizer round via standalone read-only subagents (`--mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` for both roles when the workspace has the code graph enabled); `target: "plan"` (default) reviews the plan, `target: "implementation"` reviews the implemented worktree against the plan; delegated TUI runs show one `Reviewer`/`Criticizer` overlay (78% width × 78% height, top-center, ≥72 cols) with per-lane transcript, follow-bottom scroll, Tab focus, and retention until `Esc`; `reviewers: 3` renders three equal-height panes; enforces role/model confirmation gates |
 | `analyze_refs` | plan-with-refs reference analysis: one independent read-only subagent per downloaded reference (cwd = the ref directory), reusing the reviewer role gates and the concurrent overlay (titled `Refs`); batches of at most 3 lanes run sequentially; returns structured per-reference sections for `REF_ANALYSIS.md` |
-| `execute_plan` | Execution handoff: re-confirms with the user and enters extension-managed execution mode |
-| `/plans` | Show config, active run, and execution progress |
+| `execute_plan` | Execution handoff: re-confirms with the user, asks the runtime (current session vs switch model → delegated executor), and enters extension-managed execution mode; picks the run via a descriptive form when several planned runs coexist |
+| `/plans` | Show config, all runs (newest first, bound run marked, cap 50), and execution progress |
 | `/config-pi-plans` | Re-ask workspace defaults for language, artifact root, refs root, code graph, reviewer mode/model, and criticizer mode/model |
-| `/resume-plans` | Resume the repository's working plan in the CURRENT session across restarts: unfinished planning (pending question + answered decisions), reviewing (round/lane state, successful outputs reused), execution (approval digest + HEAD + verified VCs), and implementation review (termination condition + round count). The unfinished active run wins; otherwise a unique candidate resumes directly and multiple candidates get a chooser. Linked worktrees share candidates; a cross-worktree resume confirms, copies artifacts without overwriting, and resets approval + VC validity (the termination condition survives, rounds restart at 0). An unchanged plan digest with a changed HEAD keeps the authorization but re-verifies old VCs first. Busy sessions and runs actively owned by a live process only notify — no queueing, no takeover. Interactive (TUI/RPC) only |
-| `/plans-execute [plan.md]` | Resume a paused active execution without losing verified progress; otherwise enter the explicit execution handoff (defaults to highest `PLAN_vN.md`) |
+| `/resume-plans` | Resume a run in the CURRENT session across restarts: unfinished planning (pending question + answered decisions), reviewing (round/lane state, successful outputs reused), execution (approval digest + HEAD + verified VCs), and implementation review (termination condition + round count). Binding-first: the session-bound resumable run resumes directly; a unique candidate goes direct; multiple candidates get a descriptive chooser. Linked worktrees share candidates; a cross-worktree resume confirms, copies artifacts without overwriting, and resets approval + VC validity (the termination condition survives, rounds restart at 0). An unchanged plan digest with a changed HEAD keeps the authorization but re-verifies old VCs first. Busy sessions and runs actively owned by a live process only notify — no queueing, no takeover. Interactive (TUI/RPC) only |
+| `/plans-execute [plan.md]` | Resume a paused active execution without losing verified progress; otherwise enter the explicit execution handoff (run-picker form when several planned runs coexist; runtime question: current session or switch model) |
 | `/update-plan [plan.md] [reason…]` | Interrupt-and-refine: stops execution (if any), returns the run to planning, and directs the agent to revise the plan into `PLAN_vN+1.md` while preserving verified work |
 | `/plans-autocomplete-stop` | Stop the current run's Auto-complete mode and return later planning questions to normal interaction |
 | `/init-graph` | Build the code graph: tree-sitter function index + cross-file call/import edges (EXTRACTED vs INFERRED confidence) + label-propagation communities; writes `.git/pi_plans/graph/GRAPH_REPORT.md` (subsystems, god nodes, edge stats). Full rebuilds never touch files with staged edits (fail-closed pending guard) |
@@ -162,7 +164,7 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | `/watch-graph` `/unwatch-graph` | 300ms-debounced filesystem watcher feeding incremental reindex; single-writer per worktree (atomically claimed PID+heartbeat lock, stale takeover), skips files with staged edits, fails closed on errors, stops cleanly on fs.watch errors / repeated failures / session shutdown, auto-restarts when enabled |
 | `code_graph` actions | Read-only: `status` (files/functions/edges + confidence×resolution distribution), `screening` (per-row freshness probes), `get-function`, `query` (keyword→BFS/DFS with token budget + shown/omitted counts), `path A B` (shortest call path), `explain <fn>` (community/degrees/neighbors), `impact <fn>` (reverse call closure + affected files); write path: DB-first staged edits + `apply` (auto-reindexes the materialized set). Edge resolution covers re-export barrels (`export {x} from` / `export *` follow to the defining module), namespace/default imports, `require` destructuring, and dynamic `import()`; same-name exports classify as `ambiguous` |
 | `/plans-stop` | Stop execution mode |
-| `/plans-abandon` | Abandon the active run (lifts the write guard; artifacts stay) |
+| `/plans-abandon` | Abandon a run (pick via form when several candidates; lifts the write guard; artifacts stay) |
 | Status bar (lifecycle) | 💬 Q&A → 📝 draft written (planning sub-phases) → ⌛ executing `x/y · spent · in/out-toks` in the bottom status bar → ⛔ stopped / 🎯 done / 🚫 abandoned |
 
 ## VCC compact
@@ -218,7 +220,7 @@ Invoked via `resources_discover`, callable as `/skill:<name>`, directly as `/<na
 | [`plan-normal`](skills/plan-normal/SKILL.md) | Broad or risky change; 5–10 questions; reviewer + criticizer rounds |
 | [`plan-big`](skills/plan-big/SKILL.md) | Open-ended/high-risk effort; 10+ questions; three concurrent reviewers |
 | [`debug-and-plan`](skills/debug-and-plan/SKILL.md) | Bug, CI failure, regression, incident — diagnose before planning |
-| [`plan-with-refs`](skills/plan-with-refs/SKILL.md) | External projects/papers/docs must be analyzed before planning |
+| [`plan-with-refs`](skills/plan-with-refs/SKILL.md) | External references must be analyzed before planning — repos, papers (arXiv), engineering blogs, and docs sites all count; theoretical references are equal citizens. plan-normal/plan-big may optionally cite 1–2 search-found references without downloading |
 
 ## Installation details
 
@@ -284,6 +286,8 @@ pi-plans/
 
 Before the approved handoff the workflow writes only `.git/pi_plans/` state, the run's artifact directory, `~/.cache/pi-plans/`, and the configured refs root (set via `plans set-refs-root` or `/config-pi-plans`; the recommended `.git/pi-plans/refs/` lives inside the git dir and needs no extra guard) — the extension blocks `edit`/`write` elsewhere while a run is `planning`/`accepted` (bash stays discipline-bound: inspection, `git init`, downloads into the cache). Reviewer/criticizer/ref-analyst subagents run with read-only tools. `Auto-complete` may answer planning and refinement questions only; it is never offered for execution, installs, publishing, deployment, merge, push, or credential use, and non-interactive sessions stop instead of auto-approving those.
 
+Delegated executor children (0.6.0) write natively with the approval already recorded — the planning guard no-ops for `PI_PLANS_EXECUTOR=1` children and honors a `PI_PLANS_RUN_ID` pin, so another session's concurrent planning run can never block an executing child; graph-aware file tools bypass DB-first staging for executor children so edits always land on disk. The child inherits pi's project-trust model (built-in write tools are always available; pi has no permission popups) and never loads run bookkeeping beyond its pinned id. `ask_choice` refuses to run inside an executor child (no interactive user — decide autonomously).
+
 ## Verification
 
 ```bash
@@ -318,6 +322,10 @@ Prompts produce one-shot diffs with no recorded reasoning. pi-plans produces ver
 
 The injected rule set is four compressed lines. It buys back more than it costs: the executor stops re-deriving discipline (no speculative abstractions, no compatibility detours, no reinvented helpers), so finished items converge in fewer turns and fewer tokens overall.
 
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow (setup, checks, commit style, and PR expectations). Small fixes can go straight to a pull request; for larger changes, open an issue first. Look for issues labeled `good first issue` to get started.
+
 ## License
 
 MIT.

package/agents/executor.md

@@ -0,0 +1,26 @@
+---
+name: pi-plans-executor
+description: Delegated plan executor for pi-plans runs; autonomously implements an accepted plan end-to-end in the target workdir and reports Verifier-Checklist progress with markers.
+tools: read, write, edit, bash, grep, find, ls
+---
+
+You are a delegated plan executor in the pi-plans workflow. The parent session handed you an accepted plan; you implement it completely and autonomously.
+
+Rules:
+
+- Work autonomously. You have NO user to ask questions — the ask_choice tool is unavailable in this context. When a decision is genuinely ambiguous, choose the option most consistent with the plan's goals and constraints and record the deviation in your final summary.
+- Implement the plan file you were given, in dependency order. Read the plan first; it is the single source of truth for scope, requirements, and verification steps.
+- Write code directly. Your `write`/`edit` tools operate natively on disk (any DB-first staging in the parent workdir is bypassed for you); no `apply` step is needed.
+- Follow the plan's own execution rules: smallest end-to-end slice first, then layer; no speculative abstractions; no backward-compatibility fallbacks; prefer established libraries already in the project.
+- Emit progress markers IN YOUR REPLIES as you go: `[DONE:VC-xxx]` once a verifier item's stated evidence passes, `[I-###:implemented]` / `[I-###:validating]` for implementation items when the plan defines them. The parent session parses these markers from your streamed messages to update the tracked checklist — put them in message text, not only in the final output.
+- Run the plan's verification steps yourself (tests, validate scripts) and only mark a VC done when its stated evidence actually passes.
+- Do not modify pi-plans state (run.json, checkpoints, ledgers) — the parent owns the run bookkeeping.
+- If a verification step is impossible in this environment, leave the VC unmarked and explain in the summary.
+
+Finish with a structured summary in exactly this shape:
+
+- Completed VCs: <ids or none>
+- Remaining VCs: <ids or none, with one-line reasons>
+- Implementation items: <per-item state>
+- Deviations from the plan: <any decisions you made on ambiguous points>
+- Evidence: <commands run and their results>

package/agents/ref-analyst.md

@@ -1,6 +1,6 @@
 ---
 name: pi-plans-ref-analyst
-description: Read-only reference analyst for pi-plans plan-with-refs runs; deep-reads one downloaded reference and extracts adoptable ideas for the target repository.
+description: Read-only reference analyst for pi-plans plan-with-refs runs; deep-reads ONE downloaded reference of any medium (repo, paper, blog, docs) and extracts adoptable ideas for the target repository.
 tools: read, grep, find, ls
 ---
 
@@ -9,9 +9,12 @@ You are a read-only reference analyst in the pi-plans plan-with-refs workflow.
 Rules:
 
 - Perform read-only analysis. Never edit, write, or delete any file.
-- Your working directory is the local copy of ONE downloaded reference. Deep-read it: entry points, README/docs, core modules, tests, and configuration.
-- Judge the reference through the lens of the target repository described in your task: what is worth borrowing, what is not, and why.
-- Every claim needs evidence: a file path inside the reference (with line numbers when quoting). No evidence, no claim.
+- Your working directory is the local copy of ONE downloaded reference. Deep-read it according to its medium:
+  - code repository: entry points, README/docs, core modules, tests, and configuration;
+  - paper: claims, method, limitations, and experiments/measurements;
+  - blog post or docs site: the technique, the measurements/benchmarks, and the caveats.
+- Judge the reference through the lens of the target repository described in your task: what is worth borrowing, what is not, and why. Theoretical grounding counts — an algorithm, a formal property, or a measured tradeoff is as adoptable as an implementation pattern.
+- Every claim needs evidence. For code: a file path inside the reference (with line numbers when quoting). For papers: section/theorem/table numbers with a short quote. For blogs/docs: the heading or quoted passage. No evidence, no claim.
 - You are evidence, not authority: state what you verified, not what you assume.
 - Stay inside the reference directory; do not wander the filesystem.
 

package/index.ts

@@ -44,6 +44,7 @@ import {
 	requestPlanningCompaction,
 	restoreFromSession,
 	stopExecution,
+	abortDelegatedExecutor,
 	updateStatusWidget,
 	shouldTriggerPlanningCompaction,
 } from "./src/exec.ts";
@@ -75,8 +76,9 @@ import { restartWatcherIfEnabled, stopGraphWatcher, disableWatcher } from "./src
 import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
 import { configPiPlansCommand } from "./src/config-command.ts";
 import { resumePlansCommand } from "./src/resume-command.ts";
-import { getRun, loadConfig, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
+import { getRun, listRuns, loadConfig, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
 import { boundRunId, resolveActiveRun, restoreRunBindingFromSession } from "./src/run-context.ts";
+import { abandonCandidates, resolveCommandRun } from "./src/run-picker.ts";
 import { applyPlanWritten, mutateCheckpoint, planIdentityOf } from "./src/workflow-state.ts";
 import { registerAskChoiceTool } from "./tools/ask-choice.ts";
 import { executeCommand, registerExecutePlanTool } from "./tools/execute-plan.ts";
@@ -436,17 +438,31 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		description: "Show pi-plans state: config, active run, and execution progress",
 		handler: async (_args, ctx) => {
 			const lines: string[] = [];
+			// v0.6.0: list ALL runs (newest first, bound marked, cap 50) instead of
+			// only the shared active one — multi-run workdirs stay legible.
+			const runs = listRuns(ctx.cwd).slice(0, 50);
+			const bound = boundRunId(ctx.sessionManager, ctx.cwd);
+			if (runs.length === 0) {
+				lines.push("No planning runs recorded in this workdir.");
+			} else {
+				lines.push(`Runs (${runs.length} shown, newest first):`);
+				for (const run of runs) {
+					lines.push(`  ${run.run_id === bound ? "★" : " "} ${run.topic} · ${run.status} · ${run.skill} · ${run.updated_at}`);
+				}
+			}
 			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 			const run = active ? getRun(ctx.cwd, active.run_id) : null;
-			if (!run) {
-				lines.push("No active planning run.");
-			} else {
-				lines.push(`Active run: ${run.run_id}`);
+			if (run) {
+				lines.push(`Session run: ${run.run_id}`);
 				lines.push(`Skill: ${run.skill}  Status: ${run.status}`);
 				lines.push(`Artifacts: ${run.artifact_dir}`);
 				lines.push(`Language: ${run.language_tag ?? "(unset)"}`);
 				lines.push(`State: ${resolveStateRootOrNull(ctx.cwd) ?? "(no repo)"}`);
 			}
+			// One-time active.json deprecation note (v0.6.0 registry migration).
+			if (fs.existsSync(path.join(resolveStateRootOrNull(ctx.cwd) ?? ".git/pi_plans", "active.json"))) {
+				lines.push("Note: active.json is deprecated — the run registry now derives from runs/*/run.json; the legacy file is ignored.");
+			}
 			const execution = getExecution();
 			if (execution) {
 				const done = execution.items.filter((item) => item.done).length;
@@ -599,6 +615,9 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 			}
 			const ok = await ctx.ui.confirm("Stop execution?", "Remaining verifier items will be left unfinished.");
 			if (!ok) return;
+			// v0.6.0: a delegated executor child is killed via its AbortController
+			// before the shared stop path clears the state.
+			abortDelegatedExecutor();
 			await stopExecution(pi, ctx, "stopped by user via /plans-stop");
 			ctx.ui.notify("Execution stopped.", "info");
 		},
@@ -615,24 +634,32 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	pi.registerCommand("plans-abandon", {
 		description: "Abandon the active planning run (lifts the read-only guard; artifacts are kept)",
 		handler: async (_args, ctx) => {
-			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
-			if (!active) {
+			// v0.6.0 (R-3): pick the run to abandon when several candidates exist;
+			// binding-first, single candidate stays direct (0.5.7 parity).
+			const chosen = await resolveCommandRun(
+				{ cwd: ctx.cwd, sessionManager: ctx.sessionManager, ui: ctx.ui },
+				{ candidates: abandonCandidates(ctx.cwd), title: "Abandon which run?" },
+			);
+			if (!chosen) {
 				ctx.ui.notify("No active planning run.", "info");
 				return;
 			}
+			const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
+			const abandoningBound = active?.run_id === chosen.run_id;
 			const ok = await ctx.ui.confirm(
 				"Abandon planning run?",
-				`${active.run_id}\nThe read-only guard lifts; committed artifacts stay in place.`,
+				`${chosen.run_id} (${chosen.topic} · ${chosen.status})\nThe read-only guard lifts; committed artifacts stay in place.`,
 			);
 			if (!ok) return;
 			// Abandon must end execution first so the planning model is restored.
 			disableAutoComplete(ctx, "run abandoned");
-			if (getExecution()) {
+			if (abandoningBound && getExecution()) {
+				abortDelegatedExecutor();
 				await stopExecution(pi, ctx, "run abandoned via /plans-abandon");
 			}
 			try {
-				setRunStatus(ctx.cwd, active.run_id, "abandoned");
-				ctx.ui.notify(`Run ${active.run_id} abandoned.`, "info");
+				setRunStatus(ctx.cwd, chosen.run_id, "abandoned");
+			ctx.ui.notify(`Run ${chosen.run_id} abandoned.`, "info");
 			} catch (error) {
 				ctx.ui.notify(`Failed: ${(error as Error).message}`, "error");
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-plans",
-	"version": "0.5.7",
+	"version": "0.6.0",
 	"description": "Human-in-the-loop planning extension for the Pi coding agent: researched, refined Markdown plans before any code changes.",
 	"license": "MIT",
 	"type": "module",
@@ -40,6 +40,7 @@
 	"files": [
 		"README.md",
 		"LICENSE",
+		"CONTRIBUTING.md",
 		"index.ts",
 		"agents/",
 		"docs/assets",

package/references/pi-planning-workflow.md

@@ -19,7 +19,7 @@ This skill set is written for the Pi coding agent's documented behavior:
 - Treat the user's request as a planning target, not as write authorization.
 - Before the execution handoff, do not edit target source files, docs, configs, package metadata, generated assets, or tests outside the planning artifact directory and the pi-plans state under `.git/pi_plans/`. The extension enforces this for `edit` and `write` while a run is active: only `.git/pi_plans/`, the run's artifact directory, `~/.cache/pi-plans/`, and the configured refs root are writable. Bash is not machine-guarded — keep it read-only by discipline (inspection, `git init`, downloads into the cache).
 - The normal pre-handoff writes are `.git/pi_plans/` state plus planning artifacts under the configured artifact root (default `./docs/pi-plans/...`).
-- Downloaded references go to the workspace's configured refs root (`refs_root` in `.git/pi_plans/config.json`; unset → ask once via `ask_choice`, recommended `.git/pi-plans/refs/`, second `./refs/`, third `~/.cache/pi-plans/refs/`; persist with the `plans` tool, `set-refs-root`) and their paths and evidence are recorded in `REF_ANALYSIS.md`.
+- Downloaded references go to the workspace's configured refs root (`refs_root` in `.git/pi_plans/config.json`; unset → ask once via `ask_choice`, recommended `.git/pi-plans/refs/`, second `./refs/`, third `~/.cache/pi-plans/refs/`; persist with the `plans` tool, `set-refs-root`) and their paths and evidence are recorded in `REF_ANALYSIS.md`. References are not limited to GitHub repositories: papers (arXiv etc.), engineering blogs, and documentation sites are first-class, with per-medium qualified downloads (repo = clone; paper = full text — abstracts never qualify; blog/docs = full-article markdown) and one directory per reference; theoretical references count exactly as much as implementation references. plan-normal and plan-big may optionally cite 1–2 search-found references (URLs in the plan's Evidence section) without downloading them.
 - After the user explicitly approves the execution handoff, leave this planning workflow and execute in the extension-managed loop (see Execution Handoff).
 
 ## State And Settings
@@ -59,7 +59,7 @@ When the recommended option depends on a web-verifiable claim, search first (web
 
 Every user-facing planning or refinement question goes through the `ask_choice` tool:
 
-- `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with the tradeoff that matters in `description`;
+- `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with a `description` of the form `✓ <advantage> / ✗ <drawback>` — **every option you author states both what it gains and what it costs**, in the configured language, tersely (≈8 words per half; write `—` when a side is genuinely absent). Both halves live in the single `description` string; there are no separate `pros`/`cons` fields. This rule covers every AI-written option, including the scope confirmation, the merged accept/execute handoff, and the implementation-review setup questions; only the tool-appended `Other…` / `Auto-complete` / `Auto-refine loop` rows are exempt;
 - do not add `Other` or `Auto-complete` yourself — the tool appends `Other…` second-last and `Auto-complete` last;
 - pass `autoComplete: false` for the merged accept/execute question — it contains the execution approval, so Auto-complete never appears there — and for any install waiver, publishing, deployment, merge, push, credential, or external-state question. Auto-complete may choose the recommended planning or refinement option only.
 - When the user selects Auto-complete, it remains active for the current planning run: later eligible questions use their recommended options automatically, and the extension queues one deduplicated follow-up if the model stops after an auto-completed answer. `/plans-autocomplete-stop` disables it; session restore may reactivate it only for the same active run while its status is `planning`.
@@ -103,7 +103,7 @@ The execution loop parses `- [ ] \`VC-###\`` items and tracks `[DONE:VC-###]` ma
 
 ## Refinement
 
-After each plan version, ask one merged accept/execute question via `ask_choice` with `autoComplete: false` — it contains the execution approval, so Auto-complete never appears. Options:
+After each plan version, ask one merged accept/execute question via `ask_choice` with `autoComplete: false` — it contains the execution approval, so Auto-complete never appears. Each of the three options below carries the usual `✓ <advantage> / ✗ <drawback>` description (executing now versus deferring versus another refine round are real trade-offs — say what each wins and costs). Options:
 
 1. `✓ Accept PLAN_vN and execute it now` — mark the plan accepted (`plans set-status accepted`), then call the `execute_plan` tool.
 2. `Accept PLAN_vN, don't execute yet` — mark accepted; resume later via `/plans-execute`.
@@ -127,9 +127,10 @@ A refinement round is complete when all reviewer outputs have returned or all cr
 
 ## Execution Handoff
 
-When the user picks `✓ Accept PLAN_vN and execute it now` in the merged question, mark the plan accepted and call the `execute_plan` tool (or the user runs `/plans-execute`). It re-confirms with the user, then the extension enters execution mode:
+When the user picks `✓ Accept PLAN_vN and execute it now` in the merged question, mark the plan accepted and call the `execute_plan` tool (or the user runs `/plans-execute`). It re-confirms with the user, asks which runtime executes the plan (v0.6.0), then the extension enters execution mode:
 
 - every agent turn is injected with the remaining verifier checklist and execution rules (layered simplest implementation, waiting for subprocess-backed verification with backoff 5s -> 10s -> 20s -> 40s -> 80s, then keep polling at 80s and restart at 5s for each new subprocess, no stopgaps, dependency and library discipline, minimum tests);
+- the runtime question offers ① the current session (recommended — injected checklist loop) and ② switching to another model; switching lists at least three `provider/model` switch targets (session-visible models plus the model registry, deduped, current excluded — `Other` free input when fewer exist) and runs ONE delegated executor subagent for the whole plan: native write tools, `PI_PLANS_EXECUTOR=1` + pinned `PI_PLANS_RUN_ID`, progress streamed into an `Executor` overlay while the parent parses `[DONE:VC-xxx]` markers from the child's full-text messages; Esc or `/plans-stop` kills the child and marks the run `stopped` (resumable under either runtime); under auto-approve or no-UI the question is skipped (current session, `[auto-approve]` recorded); implementation-review rounds keep the configured reviewer model;
 - execution-phase compaction is handled only when Pi core emits manual `/compact`, threshold, or overflow events; summaries are deterministic VCC-style summaries, include session-derived plan/current-I/checklist context, use smart tail keep and `keep:N`, and never call a model or request proactive current-I compaction;
 - the read-only guard lifts: full write access returns;
 - the run status moves to `executing`, then `done` when the last `[DONE:VC-xxx]` marker lands;
@@ -167,6 +168,8 @@ The agent then asks two `ask_choice` questions (each single-question, `autoCompl
 1. **Termination condition** (questionId `termination-condition`, recommended first: goal wait) — options: 1. goal wait: continue until no unpassed VCs remain (auto-continue each round) 2. until no high-severity finding (hard cap 5 rounds) 3. 1 round 4. 2 rounds 5. 3 rounds.
 2. **Reviewer count** (questionId `impl-review-reviewer-count`, `allowOther: false`, pure digit labels `1`/`2`/`3`, recommended first): "How many concurrent reviewers should each implementation-review round use?" The recommended default follows the run's skill: `plan-big` / `plan-with-refs` → 3, others → 1.
 
+Both of these setup questions are AI-written options like any other: give each one a `description` of the form `✓ <advantage> / ✗ <drawback>` in the configured language (goal-wait buys thoroughness at the cost of a long run; more concurrent reviewers buy coverage at the cost of tokens), so the trade-off is visible before the user answers.
+
 Both answers persist TOGETHER in one `plans record-checkpoint` (`transition: "implementation-review-configured"`, `terminationCondition` + `reviewerCount`). Each refinement round calls `refine` with `role: "reviewer", target: "implementation", reviewers: <configured reviewerCount>`; an omitted `reviewers` falls back to the run's configured `reviewerCount` from the checkpoint, so restarts and worktree migrations never silently revert 2/3 to 1. Each round accepts findings on evidence, applies fixes, re-runs relevant tests, and records progress. The hard cap is 5 rounds regardless of the chosen termination condition. Multi-reviewer rounds (2 or 3) consolidate like big-plan rounds: merge and dedupe findings into one `PLAN_vN_reviewer_comments.md`, keep each finding's source reviewer, severity, evidence, and disposition, and surface at most five high-priority findings. Crash recovery: if the process dies after one or both answers were recorded in `decisions.jsonl` but before the combined write, `/resume-plans` rebuilds the answered configuration from the ledger, asks only the missing question(s), and then performs the single combined write (the re-ask guard rejects duplicate configuration writes while the fields are already set).
 - Round audit trail: `decisions.jsonl`, `subagents.jsonl`, and `pi-plans-ameliorate` entries (one at goal start, then one per round) carry `currentRound` for post-hoc verification.
 - Headless sessions skip the prompt entirely; no `pi-plans-ameliorate` entry is appended.

package/references/state-and-config.md

@@ -7,7 +7,7 @@ Do not store pi-plans preferences in Pi's own settings (`~/.pi/agent/settings.js
 ## State Root Resolution
 
 - Git runs with `GIT_DIR`, `GIT_COMMON_DIR`, and `GIT_WORK_TREE` scrubbed from the environment, so leaked env vars cannot misdirect state into an unrelated repository. Relative results (`.git`, `../.git`) resolve against the workdir.
-- Granularity is **per enclosing repository**: running from a subdirectory uses the enclosing repo's git dir (a one-line notice names that repo). Linked worktrees share one common dir; run directories are unique, but `active.json` may race across concurrent worktrees.
+- Granularity is **per enclosing repository**: running from a subdirectory uses the enclosing repo's git dir (a one-line notice names that repo). Linked worktrees share one common dir; run directories are unique, and since v0.6.0 the run registry is derived from `runs/` (no shared pointer to race). The legacy `active.json` is deprecated: reads fall back to it only when no `runs/` entries exist (pre-0.6.0 migration).
 - State does not travel with clones: a fresh clone starts with empty state while committed `./docs/pi-plans/` artifacts persist in the repository.
 
 ## Auto Git Init
@@ -26,9 +26,9 @@ Bare repositories are refused with a clear error. A missing `git` executable is
 <git-common-dir>/pi_plans/
   config.json
   pi-vcc-config.json
-  active.json
-  runs/            # note: the refs root is a sibling — .git/pi-plans/refs (hyphenated), not under pi_plans/
-    <run-id>/
+  active.json      # deprecated (v0.6.0): legacy pointer, read only when runs/ is empty
+  runs/            # the run registry derives from runs/<run-id>/run.json
+    <run-id>/      # note: the refs root is a sibling — .git/pi-plans/refs (hyphenated), not under pi_plans/
       run.json
       decisions.jsonl
       subagents.jsonl
@@ -37,7 +37,7 @@ Bare repositories are refused with a clear error. A missing `git` executable is
   cache/
 ```
 
-`config.json` is stable workspace preference state. `pi-vcc-config.json` is the repo-private compaction config used only by pi-plans' VCC-style compact hook. `active.json` and `runs/` are run state. Reference downloads go to the configured `refs_root` (asked once per workspace when unset; the recommended `.git/pi-plans/refs/` sits inside the git dir so git never tracks it), with metadata recorded in the run state and public artifacts.
+`config.json` is stable workspace preference state. `pi-vcc-config.json` is the repo-private compaction config used only by pi-plans' VCC-style compact hook. `runs/` is the run state and the source of the run registry: `listRuns` scans `runs/<run-id>/run.json` (sorted by `updated_at` desc, corrupt entries skipped) and the un-bound "active" resolution is the newest NON-TERMINAL run (null when every run is done/abandoned). Multiple concurrent planning runs in one workdir are supported: each session binds to the run it started (binding first, registry fallback after), and `/plans-abandon`, `/plans-execute`, and `/resume-plans` open a descriptive run-picker form when more than one candidate exists. Reference downloads go to the configured `refs_root` (asked once per workspace when unset; the recommended `.git/pi-plans/refs/` sits inside the git dir so git never tracks it), with metadata recorded in the run state and public artifacts.
 
 ## Config Schema
 
@@ -183,7 +183,7 @@ One run directory per planning request: `<git-common-dir>/pi_plans/runs/<YYYYMMD
 
 `run.json` includes: run ID; skill name; original request; target workspace; artifact directory; language tag; status (`planning` → `accepted` → `executing` → `done`, with `stopped`/`abandoned` as exits); timestamps.
 
-`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer/ref-analyst spawns. `refs.jsonl` records reference metadata via `plans` (`record-ref`).
+`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer/ref-analyst spawns. `refs.jsonl` records reference metadata via `plans` (`record-ref`); its `kind` field is `project` (repos), `paper` (arXiv etc.), `article` (blog posts), or `docs` (documentation sites).
 
 ## Workflow Checkpoints (`/resume-plans`)
 
@@ -200,4 +200,4 @@ Rules:
 
 ## Run Ownership
 
-A run may be held by at most one live owner (`owner.json`: host, pid, process start time via `ps -o lstart=`, session id, random process token, generation). Acquisition is an atomic exclusive create; takeovers require proof the previous owner is dead (process gone, or pid alive with a different start time — PID reuse). Foreign hosts, corrupt records, and unverifiable liveness are conservatively refused; `/resume-plans` never queues or interrupts. Sessions bind to the run they start/execute/resume (restored from `pi-plans-run-start` entries on the current branch), and attribution (tools, write guard, autocomplete, execution bookkeeping, code-graph apply gate) prefers the binding over the shared `active.json` pointer.
+A run may be held by at most one live owner (`owner.json`: host, pid, process start time via `ps -o lstart=`, session id, random process token, generation). Acquisition is an atomic exclusive create; takeovers require proof the previous owner is dead (process gone, or pid alive with a different start time — PID reuse). Foreign hosts, corrupt records, and unverifiable liveness are conservatively refused; `/resume-plans` never queues or interrupts. Sessions bind to the run they start/execute/resume (restored from `pi-plans-run-start` entries on the current branch), and attribution (tools, write guard, autocomplete, execution bookkeeping, code-graph apply gate) prefers the binding, falling back to the registry's newest non-terminal run (v0.6.0 — the shared `active.json` pointer is deprecated). Delegated executor children pin their run via `PI_PLANS_RUN_ID` and are exempt from the planning write guard (`PI_PLANS_EXECUTOR=1`).

package/scripts/validate.ts

@@ -69,7 +69,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", "criticizer", ".git/pi_plans", "drawback"];
 	for (const phrase of requiredPhrases) {
 		if (!text.includes(phrase)) fail(`${file}: missing required phrase ${phrase!}`);
 	}
@@ -131,7 +131,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 +153,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",

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

@@ -15,7 +15,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 
 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.

package/skills/plan-big/SKILL.md

@@ -14,9 +14,9 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 ## 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.
 

package/skills/plan-normal/SKILL.md

@@ -14,9 +14,9 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 ## 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.
 

package/skills/plan-small/SKILL.md

@@ -14,7 +14,7 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 ## 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.