pi-plans 0.5.7 → 0.7.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 subagent prompt (read-only; ref-analyst.md for reference analysis)
+├── 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` agent prompt declares read-only tools and states 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

@@ -22,7 +22,7 @@
 
 ---
 
-A rough change request becomes a versioned Markdown plan instead of a surprise diff. The agent inspects your repository read-only, asks scoped planning questions one at a time, and stores every answer in a per-run ledger. Reviewer and criticizer subagents refine the plan until it converges — and only after you explicitly approve the handoff does the extension enter a tracked execution loop that injects the remaining verifier checklist every turn and lifts the write guard. Nothing outside planning artifacts is writable until that approval.
+A rough change request becomes a versioned Markdown plan instead of a surprise diff. The agent inspects your repository read-only, asks scoped planning questions one at a time, and stores every answer in a per-run ledger. Reviewer subagents refine the plan (findings plus questions) until it converges — and only after you explicitly approve the handoff does the extension enter a task-tree execution loop that injects the current wave and remaining tasks every turn, tracks progress through the `plans_update_task` tool, gates completion on an independent audit, and lifts the write guard. Nothing outside planning artifacts is writable until that approval.
 
 ## Benchmarked: 6× more tasks solved
 
@@ -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
@@ -61,29 +62,31 @@ at <b>7.6× fewer tokens per solved task</b>.
    language + docs location (once per workspace)
                  |
    planning questions, one ask_choice at a time  | write guard ON
-                 |                              | only .git/pi_plans/,
+                 |                              | only .git/pi-plans/,
                  v                              | run artifacts, cache
-        PLAN_vN.md + Verifier Checklist              | are writable
+   PLAN_vN.md (## Tasks + ## Verification
+   Checks)                     | are writable
                  ^                |
                  |  refine rounds |
                  +----------------+
-         reviewer (x1..x3) -> criticizer -> revise
+       reviewer (x1..x3): findings + questions
                  |
                  v
      explicit approval (never auto-completed)
                  |
    =============================================== write guard OFF
                  |
-        tracked execution loop
+     task-tree execution loop
    fused AGENTS.md × Ponytail executor rules
-   checklist injected each turn, [DONE:VC-xxx]
-   markers tracked via bottom status bar
+   current wave + tasks injected each turn,
+   plans_update_task reports status + evidence,
+   completion auditor verifies every check
                  |
                  v
            run status: done
 ```
 
-Every plan version carries stable IDs (`I-###`, `VC-###`) that never get recycled across revisions, so acceptance criteria survive refinement rounds intact.
+Every plan version carries stable IDs (`Task-N`, `VC-###`) that never get recycled across revisions, so the task tree and verification checks survive refinement rounds intact.
 
 ## Quick start
 
@@ -101,12 +104,12 @@ Then describe a change from any repository:
 You: Create a plan to split the execution loop into smaller modules.
 
 Pi:  Which planning docs location should this workspace use?
-     1. ./docs/pi-plans (recommended)
-     2. ./.git/pi_plans/plans
+     1. ./.git/pi-plans/plans (recommended)
+     2. ./docs/pi-plans
      3. Other
      4. Auto-complete
 
-Pi:  Wrote ./docs/pi-plans/2026-08-26-split-execution-loop/PLAN_v1.md
+Pi:  Wrote ./.git/pi-plans/plans/2026-08-26-split-execution-loop/PLAN_v1.md
      Example verifier item:
      - [ ] `VC-001` covers `I-001`; pass condition: `npm test` passes;
        evidence: test output; metric: zero failing tests.
@@ -120,25 +123,26 @@ Pi:  Accept the plan and execute it now?
 You: 1 — accept and execute.
 ```
 
-Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (public, committed). Prefer `.git/pi_plans/plans` if you want them private to the repository.
+Planning artifacts live under `./.git/pi-plans/plans/YYYY-MM-DD-<topic>/` by default — private to the repository, never tracked, never published. Choose `./docs/pi-plans` instead if you want the plans public and committed alongside the code.
 
 ## What it does
 
 | 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. |
-| 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) |
+| 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. |
+| Refinement rounds | Read-only reviewer Pi subagents return findings (`F-###`) and up to five questions (`Q-1..Q-5`) in one round; the main agent asks every question with `ask_choice` and records the answers before revising. Delegated runs have a standalone `Reviewer` progress overlay; `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 |
-| 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-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. |
+| Visible Refiner overlay | Delegated reviewer subagents surface as a named public overlay in the TUI — one `Reviewer` 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 | The current wave and remaining tasks are injected each turn; task progress is reported exclusively through the `plans_update_task` tool (status + evidence / skipReason, audit-only rollback); the task dashboard shows the tree live (compact aboveEditor widget, Ctrl+Shift+T expanded view with ✓/▸/~/· markers, width-adaptive); a stall watchdog pauses after three settled rounds without task-state change; the status bar shows lifecycle, `x/y` task progress, elapsed time, and 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) |
+| Completion auditor | When every task reaches a terminal state, an independent read-only auditor verifies each `VC-###` check against the worktree; failed checks roll their covered tasks (children cascade, skipped reopen) back to pending and inject the audit report; three failed rounds pause for the user — auto-approve/headless terminates as `stopped` instead of hanging. Checks with all-skipped coverage pass; checks covering no task never audit |
+| Execution handoff | The accepted plan executes in the current session after explicit approval (never auto-completed); legacy `I-###` plans parse through the compatibility mapping with an upgrade notice; 0.6.0 in-flight runs resume compatibly (delegated-executor orphans re-approve, paused executions rebuild from the task tree) |
+| Execution-phase compaction | Pi core owns scheduling; pi-plans maps the active plan path, current task, task ids, and remaining `VC-###` checks into the VCC sections. Proactive triggers and model-generated summary paths 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 planning run is active in the workdir; the guard prefers the session-bound run and lists the allowed roots on refusal |
 
 ## Interface overview
 
@@ -146,23 +150,23 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 |---|---|
 | `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-root`, `set-refs-root`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent`, `record-checkpoint` (state-machine-validated workflow transitions) |
 | `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 |
-| `/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`) |
+| `refine` | Reviewer round via standalone read-only subagents (`--mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` when the workspace has the code graph enabled): findings (`F-###`) and up to five questions (`Q-1..Q-5`) per lane; the caller must ask every question with `ask_choice` and record answers before revising; delegated TUI runs show one `Reviewer` 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 the reviewer gates — first use pops native model + effort panels in TUI (menus on RPC, text guidance headless), persisted to the global reviewer config |
+| `analyze_refs` | plan-with-refs reference analysis: one independent read-only subagent per downloaded reference (cwd = the ref directory), reusing the reviewer model confirmation from the global config (the mode is not consulted — analysis always spawns) 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 (never auto-completed) and enters task-tree execution mode (`plans_update_task` progress, dashboard, completion auditor); legacy `I-###` plans parse through the compatibility mapping with an upgrade notice; 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, and code graph, plus the reviewer mode/model (keep/change menu; native model + effort panels on change in TUI; current-session skips the model step) |
+| `/resume-plans` | Resume a run in the CURRENT session across restarts: unfinished planning (pending question + answered decisions), reviewing (round/lane state, successful outputs reused), and execution (approval digest + HEAD + recorded task progress; 0.6.0 delegated-executor orphans re-approve, legacy implementation-review phases map to done). 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 + task progress. An unchanged plan digest with a changed HEAD keeps the authorization but re-opens closed tasks. Busy sessions and actively owned runs only notify — no queueing, no takeover. Interactive (TUI/RPC) only |
+| `/plans-execute [plan.md]` | Resume a paused active execution without losing task progress; otherwise enter the explicit execution handoff (run-picker form when several planned runs coexist; legacy plans get an upgrade notice) |
 | `/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) |
+| `/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) |
 | `/update-graph` | Incrementally reindex changed files (shared path used by apply/final-commit triggers and the watcher) |
 | `/apply-graph` | Materialize DB-first staged edits to the worktree; auto-reindexes the materialized set afterward |
 | `/graph-status` `/graph-drift` | Graph inventory and DB↔source convergence |
 | `/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
@@ -175,11 +179,11 @@ Pi core remains the owner of compaction scheduling: manual `/compact`, threshold
 - **Manual matrix.** Plain `/compact` and `/compact keep:N` compact and show stats without continuing. `/compact <text>` and `/compact keep:N <text>` compact, then send the text once as the follow-up prompt. Internal pi-plans compaction markers are never reused as user follow-up prompts.
 - **Fallbacks and stats.** Unsafe manual/threshold cuts cancel with a warning; overflow or retrying unsafe cuts return control to Pi core. Successful VCC compactions notify with kept-tail and summarized-message stats. Threshold/overflow compactions may queue one hidden continuation only when the running Pi version still needs it and `continueAfterThresholdCompact` is enabled.
 - **Pre-plan compaction.** When `plans start-run` creates a new planning run, pi-plans proactively requests one VCC compaction (internal hint `pi-plans planning pre-plan compact`) right after the run is created and before the first planning question, then resumes the planning turn with a hidden message — so each new plan starts on a lean context (LLM reasoning degrades with longer input). Small sessions, already-compacted sessions, and failures skip silently and still resume. `prePlanCompact:false` in the repo-private config restores the old behavior.
-- **Repo-private config.** Defaults are scaffolded in `.git/pi_plans/pi-vcc-config.json` under the resolved git common dir: `overrideDefaultCompaction:true`, `smartKeepTail:true`, `continueAfterThresholdCompact:true`, `prePlanCompact:true`, `debug:false`. Global pi-vcc config and `PI_VCC_CONFIG_PATH` are intentionally ignored.
+- **Repo-private config.** Defaults are scaffolded in `.git/pi-plans/pi-vcc-config.json` under the resolved git common dir: `overrideDefaultCompaction:true`, `smartKeepTail:true`, `continueAfterThresholdCompact:true`, `prePlanCompact:true`, `debug:false`. Global pi-vcc config and `PI_VCC_CONFIG_PATH` are intentionally ignored.
 
 ## Visible Refiner overlay
 
-Delegated `refine` rounds (reviewer or criticizer) and `analyze_refs` rounds (titled `Refs`) show their progress directly inside the Pi TUI instead of disappearing into the child process's terminal. The overlay is a public, named panel so users always know who is doing what:
+Delegated `refine` rounds (reviewer) and `analyze_refs` rounds (titled `Refs`) show their progress directly inside the Pi TUI instead of disappearing into the child process's terminal. The overlay is a public, named panel so users always know who is doing what:
 
 - **Pi-btw-aligned geometry.** Each round uses `width: "78%"`, `minWidth: 72`, `maxHeight: "78%"`, `anchor: "top-center"`, and `{ top: 1, left: 2, right: 2 }` margins (no dependency on `pi-btw`; the renderer is built on Pi's public `pi-tui` primitives).
 - **Complete streaming transcript.** Assistant text, thinking blocks, tool calls, tool results, and stderr are merged per turn/content block into lane entries without overlay-facing truncation; only the viewport slices them. Final `message_end` / `tool_execution_end` overwrite the live snapshot with the authoritative content.
@@ -214,11 +218,11 @@ Invoked via `resources_discover`, callable as `/skill:<name>`, directly as `/<na
 | Skill | Use it when |
 |---|---|
 | [`planning`](skills/planning/SKILL.md) | General router; selects the narrowest specialist skill before planning starts |
-| [`plan-small`](skills/plan-small/SKILL.md) | Small scoped change; 1–3 questions; one criticizer round |
-| [`plan-normal`](skills/plan-normal/SKILL.md) | Broad or risky change; 5–10 questions; reviewer + criticizer rounds |
+| [`plan-small`](skills/plan-small/SKILL.md) | Small scoped change; 1–3 questions; one reviewer round |
+| [`plan-normal`](skills/plan-normal/SKILL.md) | Broad or risky change; 5–10 questions; reviewer 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
 
@@ -275,14 +279,16 @@ pi-plans/
 │   └── code-graph/        # SQLite schema/store, parsers, indexer, summary, materialize
 ├── skills/                # The planning router plus five specialist planning skills
 ├── references/            # Shared workflow, state/config, plan template (normative)
-├── agents/                # reviewer.md / criticizer.md subagent prompts
+├── agents/                # reviewer.md subagent prompt (ref-analyst.md for reference analysis)
 ├── scripts/validate.ts    # Structure + package artifact guard
 └── tests/                 # node:test suite (state, guard, plan parsing, execution, refine progress, code-graph)
 ```
 
 ## Safety model
 
-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.
+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/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.
+
+Read-only reviewer and ref-analyst subagents run with pinned tool lists (`read, grep, find, ls` plus `code_graph` when enabled) and inherit pi's project-trust model without any write capability; the completion auditor runs the same read-only profile. Execution itself happens in the approved session, never in an unsupervised child.
 
 ## Verification
 
@@ -304,11 +310,11 @@ The plan is the contract. Refinement converges on scope while nothing is writabl
 
 **What can Auto-complete decide on my behalf?**
 
-Planning and refinement choices only (the recommended option). Choosing Auto-complete enables the recommended answer for later eligible planning questions in the current run and the extension continues the planning turn when the model stops early. Use `/plans-autocomplete-stop` to take back control. It is never offered for execution approval, installs, publishing, deployment, merge, push, or credentials — those questions stop and wait for you. After execution completes, interactive sessions enter goal-running review mode automatically and ask only for the implementation-review loop's termination condition; the loop then continues until that condition or the 5-round cap. Headless sessions stay silent.
+Planning and refinement choices only (the recommended option). Choosing Auto-complete enables the recommended answer for later eligible planning questions in the current run and the extension continues the planning turn when the model stops early. Use `/plans-autocomplete-stop` to take back control. It is never offered for execution approval, installs, publishing, deployment, merge, push, or credentials — those questions stop and wait for you. After execution completes, the independent completion auditor verifies every check; interactive sessions pause for review if the audit exhausts its three rounds, while headless runs terminate bounded instead of hanging.
 
 **Where does all the state live?**
 
-Preferences and run ledgers in `.git/pi_plans/` inside your workspace's git directory (never tracked, never published); plan artifacts under the configured artifact root (default `./docs/pi-plans/`); reference downloads under the configured refs root — asked once per workspace (recommended `.git/pi-plans/refs/`), changeable via `plans set-refs-root` or `/config-pi-plans`.
+Workspace preferences and run ledgers in `.git/pi-plans/` inside your workspace's git directory (never tracked, never published); the reviewer role in the global config `~/.pi/pi-plans/config.json` (override with `PI_PLANS_GLOBAL_DIR`) — confirmed once, shared across every workspace; plan artifacts under the configured artifact root (default `./.git/pi-plans/plans/`, also private — pick `./docs/pi-plans` for public committed plans); reference downloads under the configured refs root — asked once per workspace (recommended `.git/pi-plans/refs/`), changeable via `plans set-refs-root` or `/config-pi-plans`.
 
 **How is this different from just prompting an AI to make changes?**
 
@@ -318,6 +324,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/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/agents/reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: pi-plans-reviewer
-description: Read-only plan reviewer for pi-plans refinement rounds; verifies plan claims against the repository.
+description: Read-only plan reviewer for pi-plans refinement rounds; verifies plan claims against the repository and surfaces the questions only the user can settle.
 tools: read, grep, find, ls
 ---
 
@@ -12,9 +12,18 @@ Rules:
 - Verify the plan's claims against the actual repository using your read tools before judging them.
 - Every finding needs evidence: a repo path, a command, or an external citation. No evidence, no finding.
 - You are evidence, not authority: state what you verified, not what you assume.
+- Criticize like a criticizer: when a trade-off, an undetermined semantic, or an accept/reject call genuinely needs the user's decision, raise it as a question instead of burying it in a finding.
 
-Output findings as Markdown, highest severity first, in this shape per finding:
+Output Markdown with exactly two top-level parts, in this order:
+
+## Findings
+
+Highest severity first, in this shape per finding:
 
 - `F-###` — severity: high | medium | low; affected plan IDs; evidence: <repo path/command or source>; impact: <what breaks>; recommended fix: <concrete change>; suggested disposition: accept | reject | needs-discussion.
 
-Surface at most five high-priority findings first; list lower-severity findings after them. If the plan holds up, say so explicitly and list what you checked.
+Surface at most five high-priority findings first; list lower-severity findings after them. Write "None." when there are none. If the plan holds up, say so explicitly and list what you checked.
+
+## Questions
+
+At most five numbered questions (`Q-1`, `Q-2`, …) that must be answered by the user before the plan can be safely revised. Each question: one line of why it matters, phrased so a user with repo access can answer concretely. Never rhetorical; never questions the repository already answers. Stop earlier if nothing genuinely needs the user.