pi-plans 0.3.0 → 0.3.2

package/README.md

@@ -114,11 +114,12 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 |---|---|
 | 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 |
+| 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 |
+| 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. |
 | 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. |
@@ -129,13 +130,14 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 
 | Tool / Command | Purpose |
 |---|---|
-| `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-root`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent` |
+| `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` |
 | `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, code graph, reviewer mode/model, and criticizer mode/model |
-| `/plans-execute [plan.md]` | Manual execution handoff (defaults to highest `PLAN_vN.md`) |
+| `/config-pi-plans` | Re-ask workspace defaults for language, artifact root, refs root, code graph, reviewer mode/model, and criticizer mode/model |
+| `/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`) |
 | `/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 |
 | `/plans-stop` | Stop execution mode |
@@ -155,7 +157,7 @@ Pi core remains the owner of compaction scheduling: manual `/compact`, threshold
 
 ## Visible Refiner overlay
 
-Delegated `refine` rounds (reviewer or criticizer) 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 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:
 
 - **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.
@@ -248,18 +250,27 @@ read, and each function retains its full UTF-8 source.
   config unreadable) are marked in the result; refiner and criticizer
   subagents get the `code_graph` tool in their allowlist (verified in headless
   no-session children); the executor loop
-  becomes DB-first: `code_graph` mutations → `/apply-graph` → `/graph-drift`
-  → `plans final-commit` → `/init-graph`.
+  becomes DB-first: `code_graph` mutations → `code_graph apply` (agent-side
+  materialization; its result carries counts and the post-apply drift
+  summary) → `plans final-commit` → `/init-graph`.
 - The `code_graph` tool provides read-only screening (`status`, `screening`,
   `get-function`, `manifest`), DB-first mutations (`update-function`,
   `update-file`, `delete-file` — all mark files `pending_materialization`
-  and append to `change_log`), and `list-pending` so agents can navigate and
+  and append to `change_log`), `list-pending`, and the agent-invokable
+  `apply` action (same planning/accepted gate as `/apply-graph`; also
+  refused for read-only refiner subagents via the `PI_PLANS_REFINER` env
+  marker; returns per-file counts plus a post-apply drift summary without
+  changing run status) so agents can navigate, stage, materialize, and
   edit the graph without pulling `full_code`.
 
 Runtime requirements: the base extension still requires Node ≥ 22.6; the
 graph feature additionally requires Node ≥ 22.13 (or `--experimental-sqlite`)
 so that `node:sqlite` is available without flag. Pi's host currently ships
-Node ≥ 22.19, so a fresh install works out of the box. On unsupported
+Node ≥ 22.19, so a fresh install works out of the box. The code graph also
+needs the optional `tree-sitter` parser packages, which are **not** installed
+automatically — add them to the workspace (or global tree) where pi runs:
+`npm i tree-sitter tree-sitter-javascript tree-sitter-typescript tree-sitter-python`. Without them, planning and execution work normally and graph
+tools report which package is missing. On unsupported
 runtimes (Bun, missing parsers) graph commands fail locally without
 affecting the planning workflow.
 
@@ -280,7 +291,7 @@ pi-plans/
 
 ## Safety model
 
-Before the approved handoff the workflow writes only `.git/pi_plans/` state, the run's artifact directory, and `~/.cache/pi-plans/` — 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 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/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.
 
 ## Verification
 
@@ -306,7 +317,7 @@ Planning and refinement choices only (the recommended option). Choosing Auto-com
 
 **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/`); large downloaded references outside the repo under `~/.cache/pi-plans/`.
+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`.
 
 **How is this different from just prompting an AI to make changes?**
 

package/agents/ref-analyst.md

@@ -0,0 +1,18 @@
+---
+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.
+tools: read, grep, find, ls
+---
+
+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.
+- You are evidence, not authority: state what you verified, not what you assume.
+- Stay inside the reference directory; do not wander the filesystem.
+
+Output structured Markdown in exactly the seven sections your task specifies, in that order, with no extra top-level sections.

package/index.ts

@@ -23,6 +23,7 @@ import {
 	drainExecutionFlush,
 	executionContextMessage,
 	filterExecutionResumeMessages,
+	filterGoalWaitMessages,
 	filterPlanningResumeMessages,
 	getExecution,
 	handleExecutionBeforeCompact,
@@ -67,9 +68,10 @@ import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
 import { configPiPlansCommand } from "./src/config-command.ts";
 import { getRun, loadConfig, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
 import { registerAskChoiceTool } from "./tools/ask-choice.ts";
-import { executeHandoff, registerExecutePlanTool } from "./tools/execute-plan.ts";
+import { executeCommand, registerExecutePlanTool } from "./tools/execute-plan.ts";
 import { registerPlansTool } from "./tools/plans.ts";
 import { registerRefineTool } from "./tools/refine.ts";
+import { registerAnalyzeRefsTool } from "./tools/analyze-refs.ts";
 
 const baseDir = dirname(fileURLToPath(import.meta.url));
 
@@ -115,6 +117,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	registerPlansTool(pi);
 	registerAskChoiceTool(pi);
 	registerRefineTool(pi, baseDir);
+	registerAnalyzeRefsTool(pi, baseDir);
 	registerExecutePlanTool(pi);
 	registerQueryInterviewHooks(pi, hasActivePlanningWorkflow);
 	registerCodeGraphTool(pi);
@@ -198,20 +201,20 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		}
 		if (!graphEnabled) return;
 		if (event.toolName === "edit" || event.toolName === "write") {
-			ctx.ui?.notify?.("code-graph: source edited directly — run /update-graph to sync the graph, or use code_graph mutations + /apply-graph for DB-first edits", "info");
+			ctx.ui?.notify?.("code-graph: source edited directly — run /update-graph to sync the graph, or use code_graph mutations + code_graph apply for DB-first edits", "info");
 			return;
 		}
 		if (event.toolName === "code_graph") {
 			const action = String((event.input as { action?: string }).action ?? "");
 			if (action === "update-function" || action === "update-file" || action === "delete-file") {
-				ctx.ui?.notify?.("code-graph: mutation staged — run /apply-graph to materialize, then /graph-drift to verify", "info");
+				ctx.ui?.notify?.("code-graph: mutation staged — run code_graph apply to materialize (its result includes the post-apply drift summary)", "info");
 			}
 		}
 	});
 
 	pi.on("context", (event) => {
 		const filteredExecution = filterExecutionResumeMessages(event.messages as Array<{ customType?: string }>);
-		const messages = filterPlanningResumeMessages(filteredExecution);
+		const messages = filterGoalWaitMessages(filterPlanningResumeMessages(filteredExecution));
 		if (messages.length !== event.messages.length) {
 			return { messages };
 		}
@@ -234,14 +237,6 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		noteCompactionEnded(ctx, event.customInstructions);
 	});
 
-	// Flush points for deferred execution-loop writes: primary drain when the
-	// agent run fully settles, backstop drain at the next run's start (covers
-	// continuation paths that might not emit agent_settled), plus the forced
-	// synchronous flush inside stop/complete.
-	pi.on("agent_settled", async (_event, ctx) => {
-		drainExecutionFlush(pi, ctx);
-	});
-
 	// -----------------------------------------------------------------------
 	// Execution loop: inject remaining checklist each turn, track markers.
 	// -----------------------------------------------------------------------
@@ -382,7 +377,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		description: "Execute handoff: enter tracked execution mode for an accepted plan",
 		handler: async (args, ctx) => {
 			const planPath = args.trim() || undefined;
-			const outcome = await executeHandoff(ctx, planPath);
+			const outcome = await executeCommand(ctx, planPath);
 			ctx.ui.notify(outcome.message, outcome.status === "error" ? "error" : "info");
 		},
 	});
@@ -537,8 +532,11 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// -----------------------------------------------------------------------
 	// Session lifecycle
 	// -----------------------------------------------------------------------
+	pi.on("session_tree", async (_event, ctx) => {
+		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
+	});
 	pi.on("session_start", async (_event, ctx) => {
-		await restoreFromSession(pi, ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreFromSession>[2]);
+		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
 		restoreAutoCompleteFromSession(ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreAutoCompleteFromSession>[1]);
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-plans",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Human-in-the-loop planning extension for the Pi coding agent: researched, refined Markdown plans before any code changes.",
   "license": "MIT",
   "type": "module",
@@ -55,10 +55,19 @@
     "test": "node --experimental-strip-types scripts/run-tests.ts",
     "prepack": "npm run validate && npm test"
   },
-  "dependencies": {
+  "dependencies": {},
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-server": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "typebox": "1.3.7",
     "tree-sitter": "^0.25.1",
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-python": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2"
+  },
+  "overrides": {
+    "tree-sitter": "^0.25.1"
   }
 }

package/references/pi-planning-workflow.md

@@ -8,18 +8,18 @@ This skill set is written for the Pi coding agent's documented behavior:
 
 - the five skills are contributed by the pi-plans extension and loaded as Pi skills (also invokable as `/skill:<name>`);
 - skill references and helper sources are resolved relative to the directory containing `SKILL.md`;
-- the extension provides these tools: `plans` (workspace state), `ask_choice` (choice prompts), `refine` (reviewer/criticizer subagents), and `execute_plan` (execution handoff);
-- `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` for both roles when workspace `graph_enabled` is true) with isolated context; delegated Reviewer/Criticizer runs show a standalone aggregate overlay titled `Reviewer` or `Criticizer` (78% × 78% top-center, ≥72 cols, no input row), stream assistant/thinking/tool events into per-lane transcripts with follow-bottom scroll, dismiss on `Esc` (close-only — the refiner child keeps running and its result still flows back as tool output), replace any retained finished overlay when a new round begins, and return conclusions to the main session as tool output;
-- when graph mode is enabled, graph-aware `read`/`edit` overrides are active for indexed source files: `read` returns a capped function digest (≤50 lines, synthetic anonymous entries folded) by default — drill in via `offset/limit` or `code_graph get-function`, and `full: true` is the only whole-file exit (small/zero-function files return full text; safety truncation matches native read); `write`/`edit` stage DB-first mutations until `/apply-graph`; unexpected fallbacks (`not indexed` / `runtime unavailable` / `config read failed`) are marked at the top of the result while flag-off fallbacks stay unmarked;
+- Planning and reference analysis run with the extension tools `plans`, `ask_choice`, `refine`, `analyze_refs`, and `execute_plan`;
+- `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`, plus `code_graph` for both roles when workspace `graph_enabled` is true) with isolated context; delegated Reviewer/Criticizer runs show a standalone aggregate overlay titled `Reviewer` or `Criticizer` (78% × 78% top-center, ≥72 cols, no input row), stream assistant/thinking/tool events into per-lane transcripts with follow-bottom scroll, dismiss on `Esc` (close-only — the refiner child keeps running and its result still flows back as tool output), replace any retained finished overlay when a new round begins, and return conclusions to the main session as tool output; `analyze_refs` spawns one read-only subagent per downloaded reference (cwd = that ref's directory) reusing the reviewer role gates, shows the same overlay titled `Refs` in batches of at most 3 lanes, and returns structured per-reference sections for `REF_ANALYSIS.md`;
+- when graph mode is enabled, graph-aware `read`/`edit` overrides are active for indexed source files: `read` returns a capped function digest (≤50 lines, synthetic anonymous entries folded) by default — drill in via `offset/limit` or `code_graph get-function`, and `full: true` is the only whole-file exit (small/zero-function files return full text; safety truncation matches native read); `write`/`edit` stage DB-first mutations until materialized via the `code_graph` tool's `apply` action (same planning/accepted gate as /apply-graph; refused for read-only refiner subagents via the PI_PLANS_REFINER marker; returns a per-file report with counts and a post-apply drift summary, and never changes run status); unexpected fallbacks (`not indexed` / `runtime unavailable` / `config read failed`) are marked at the top of the result while flag-off fallbacks stay unmarked;
 - the execution loop is extension-managed: remaining verifier items are injected each turn, implementation items emit `[I-###:current]`/`[I-###:implemented|validating]`, and `[DONE:VC-xxx]` markers are tracked with a bottom status bar;
 - execution and planning compaction keep Pi's SessionManager as the history owner; during active pi-plans runs, `session_before_compact` uses a deterministic no-LLM VCC-style summary with `[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, `[User Preferences]`, and a ranked brief transcript; Pi core owns manual `/compact`, threshold, and overflow scheduling, while pi-plans handles smart tail keep, `keep:N`, stats, and phase-specific run/plan/current-I/checklist context;
 
 ## Planning Boundary
 
 - 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, and `~/.cache/pi-plans/` are writable. Bash is not machine-guarded — keep it read-only by discipline (inspection, `git init`, downloads into the cache).
+- 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/...`).
-- Large downloaded references belong outside the target repo by default, under `~/.cache/pi-plans/refs/<repo-slug>/<topic>/`; record their paths and evidence 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`.
 - 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
@@ -137,6 +137,27 @@ When the user picks `✓ Accept PLAN_vN and execute it now` in the merged questi
 
 If the user declines, stay in planning (or stop, per their choice). Never start implementation without the approved handoff.
 
+### Execution Goal-Wait
+
+In TUI/RPC, automatic goal-wait is evaluated only at `agent_settled`, after
+Pi has finished natural tool continuation, retries, and compaction. The
+extension rechecks that the same execution is active and incomplete, the
+session is idle, and neither pending input nor compaction owns continuation.
+Each eligible settled cycle can send at most one hidden custom message with
+the current execution rules and remaining VC checklist. Tool `turn_end`
+events only update progress; they never prequeue goal-wait reminders.
+
+No-progress and literal `waiting for` counters advance only on eligible
+settled cycles. Real marker progress resets both; thresholds remain 3 and 6.
+User interruption and final model errors also pause continuation. Genuine
+interactive/RPC user input or `/plans-execute` can resume a paused active
+execution without losing verified VCs; extension input cannot unpause it.
+New-plan handoffs and the `execute_plan` tool still require explicit approval.
+Completion, stop, and session replacement invalidate the extension's wake
+identity without clearing user or other-extension queues. Print/JSON
+single-shot sessions keep VC tracking and completion but never auto-wake;
+use RPC for persistent headless execution.
+
 ### Post-Execution Continuation
 
 When execution completes in an interactive session, the completion message attaches a goal-running continuation block and triggers a new agent turn so the model can enter the implementation-review loop immediately. The interactive-only trigger keeps headless sessions silent (no unconsented subagent cost). The same behavior applies on both completion call sites (the normal `turn_end` completion and the `restoreFromSession` recovery path).

package/references/state-and-config.md

@@ -27,7 +27,7 @@ Bare repositories are refused with a clear error. A missing `git` executable is
   config.json
   pi-vcc-config.json
   active.json
-  runs/
+  runs/            # note: the refs root is a sibling — .git/pi-plans/refs (hyphenated), not under pi_plans/
     <run-id>/
       run.json
       decisions.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. Large external references stay outside the repository by default under `~/.cache/pi-plans/refs/`, 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. `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 Schema
 
@@ -61,7 +61,10 @@ The default config is:
   },
   "artifact_root": "./docs/pi-plans",
   "artifact_root_source": "unset",
-  "artifact_root_updated_at": null
+  "artifact_root_updated_at": null,
+  "refs_root": null,
+  "refs_root_source": "unset",
+  "refs_root_updated_at": null
 }
 ```
 
@@ -75,6 +78,7 @@ Rules:
 - `artifact_root` is relative to the target workspace unless absolute.
 - `artifact_root_source` is `user`, `auto`, or `unset`.
 - `artifact_root_updated_at` is the selection timestamp or `null` before confirmation.
+- `refs_root` is where plan-with-refs downloads references, relative to the target workspace unless absolute, or `null` before selection; `refs_root_source` is `user`, `auto`, or `unset`; `refs_root_updated_at` is the selection timestamp or `null`.
 - There is intentionally no `effort` field: subagents inherit the dispatching session's model and thinking level unless an exact selector is stored. The real lever is the main session's thinking level at refine time.
 
 ## VCC Compact Config
@@ -115,11 +119,11 @@ Persist with `plans` (`set-language`, `languageSource: "user"`). Use the selecte
 
 ## Code Graph Enabled
 
-`graph_enabled` (`boolean | null`) records whether the workspace wants graph-aware read/write/edit wrappers and `code_graph` mutations for indexed source files. `null` means the question was never asked: the first `plans` `init`/`show` in a workspace returns a `hint` instructing the agent to ask the user once via `ask_choice` (recommended: yes) and persist with the `plans` tool (`set-graph-enabled`, `enabled: true|false`). This question does not count against the planning-question limit. `/enable-graph` and `/disable-graph` toggle it later; disable refuses while graph drift is dirty.
+`graph_enabled` (`boolean | null`) records whether the workspace wants graph-aware read/write/edit wrappers and `code_graph` mutations for indexed source files. `null` means the question was never asked: the first `plans` `init`/`show` in a workspace returns a `hint` instructing the agent to ask the user once via `ask_choice` (recommended: yes) and persist with the `plans` tool (`set-graph-enabled`, `enabled: true|false`). This question does not count against the planning-question limit. `/enable-graph` and `/disable-graph` toggle it later; disable refuses while graph drift is dirty. When enabled, DB-first staged edits are materialized agent-side via the `code_graph` tool's `apply` action (same planning/accepted gate as `/apply-graph`; refused for read-only refiner subagents via the `PI_PLANS_REFINER` env marker; the result carries per-file counts and a post-apply drift summary and never changes run status).
 
 ## `/config-pi-plans`
 
-`/config-pi-plans` is an interactive workspace configuration wizard. It re-asks the workspace language, planning docs root, code graph toggle, reviewer mode/model, and criticizer mode/model, then writes the chosen defaults back to `.git/pi_plans/config.json`. When code graph is enabled, the extension also overrides built-in `read`/`write`/`edit` for indexed source files so graph-backed source reads and DB-first edits happen automatically. Model pickers can reuse the current session model, any available selector surfaced by `ctx.scopedModels` or the model registry, or a manually entered exact `provider/model` string. If a run is already active, only the workspace defaults change; the active run's `artifact_dir` and `language_tag` stay unchanged.
+`/config-pi-plans` is an interactive workspace configuration wizard. It re-asks the workspace language, planning docs root, refs root, code graph toggle, reviewer mode/model, and criticizer mode/model, then writes the chosen defaults back to `.git/pi_plans/config.json`. When code graph is enabled, the extension also overrides built-in `read`/`write`/`edit` for indexed source files so graph-backed source reads and DB-first edits happen automatically. Model pickers can reuse the current session model, any available selector surfaced by `ctx.scopedModels` or the model registry, or a manually entered exact `provider/model` string. If a run is already active, only the workspace defaults change; the active run's `artifact_dir` and `language_tag` stay unchanged.
 
 
 Before the first product planning question, check the persisted config again. If `artifact_root_source` is missing or `unset`, ask exactly one `ask_choice` question:
@@ -131,6 +135,15 @@ Before the first product planning question, check the persisted config again. If
 
 Persist with `plans` (`set-artifact-root`, `artifactRoot: <selected path>`, `artifactRootSource: "user"` or `"auto"`). Use the selected path for the run's artifact directory root. This question does not count against the planning-question limit.
 
+Before downloading any reference in a plan-with-refs flow, check the persisted config. If `refs_root_source` is missing or `unset`, ask exactly one `ask_choice` question:
+
+1. `.git/pi-plans/refs` — recommended; inside the git dir so git never tracks the downloads.
+2. `./refs/` — inside the worktree; the planning write guard allows writes under the configured refs root.
+3. `~/.cache/pi-plans/refs/` — outside the repository; matches the historical default.
+4. `Other` / `Auto-complete` — select the recommended path.
+
+Persist with `plans` (`set-refs-root`, `refsRoot: <selected path>`, `refsRootSource: "user"` or `"auto"`). Download references under this root. This question does not count against the planning-question limit.
+
 
 Before running a `refine` round, read the role setting from the persisted config.
 
@@ -160,10 +173,12 @@ When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` s
 
 The main agent consolidates the results, records dispositions, revises the plan, and asks the next merged accept/execute question — all in the same turn.
 
+The `analyze_refs` tool (plan-with-refs) uses the same spawning machinery with the **reviewer** role's gates (`mode` must be `delegated-subagent`; a confirmed `current-session` reviewer is refused with guidance to switch, since analysis is spawn-only) and the reviewer's model selector. Each downloaded reference gets one independent read-only subagent whose system prompt comes from `agents/ref-analyst.md` and whose working directory is that reference's own directory; lanes never get `code_graph`. Lanes run in sequential batches of at most 3 under a standalone overlay titled `Refs`; each batch's controller opens and closes exactly like a single refine round. Successful spawns are recorded best-effort in `subagents.jsonl` with role `ref-analyst` (skipped when no active run exists, e.g. adhoc calls). The structured per-reference sections come back as the tool result; the main agent owns `REF_ANALYSIS.md` and fills `coverage`/`gaps` in `refs.jsonl` via `plans` (`record-ref`).
+
 ## Run State
 
 One run directory per planning request: `<git-common-dir>/pi_plans/runs/<YYYYMMDDTHHMMSSZ-topic>/` (second-precision; `-2`, `-3` suffixes on collision).
 
 `run.json` includes: run ID; skill name; original request; target workspace; artifact directory; language tag; status (`planning` → `accepted` → `executing` → `done`, with `stopped`/`abandoned` as exits); timestamps.
 
-`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer 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`).

package/scripts/validate.ts

@@ -21,6 +21,7 @@ const REQUIRED_TOOL_FILES = [
 	"tools/plans.ts",
 	"tools/ask-choice.ts",
 	"tools/refine.ts",
+	"tools/analyze-refs.ts",
 	"tools/execute-plan.ts",
 	"tools/code-graph.ts",
 	"src/state.ts",

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

@@ -16,15 +16,15 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 1. Inspect the target Git repo read-only before external research so search terms match the actual codebase and constraints.
 2. Create the `.git/pi_plans` run state and planning artifact directory once the topic is clear (`plans` action `start-run`).
 3. Search proactively for related projects, articles, papers, docs, and prior art. Prefer a websearch skill when installed; otherwise use bash tools such as `curl` or `gh` when already available.
-4. Download or clone at least 3 credible references before writing `PLAN_v1.md`; store large downloads outside the target repo under `~/.cache/pi-plans/refs/<repo-slug>/<topic>/`. Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
+4. Before the first download, check `refs_root` in `.git/pi_plans/config.json` (`plans` action `show`). If it is unset, ask exactly one `ask_choice` question — recommended `.git/pi-plans/refs/` (inside the git dir, never tracked), second `./refs/`, third `~/.cache/pi-plans/refs/` — and persist with `plans` (`set-refs-root`); this question does not count against the planning-question limit. Then download or clone at least 3 credible references before writing `PLAN_v1.md`, under the configured refs root (create per-ref subdirectories). Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
 5. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and in the run's `refs.jsonl` (via `plans` action `record-ref`): title, URL, kind, retrieval method, date accessed, local path, coverage, and evidence gaps.
-6. For every reference, produce a structured analysis artifact (manual structured read recorded in `REF_ANALYSIS.md`) before asking adoption questions.
+6. For every reference, run the `analyze_refs` tool (required path — it replaces manual structured reads): one independent read-only subagent per reference deep-reads it and returns structured sections (Overview / Key Mechanisms And Design Tradeoffs / Adoptable Ideas For The Target Repo / Pitfalls And Anti-Patterns / Evidence Citations / Coverage / Evidence Gaps). Paste each analysis into `REF_ANALYSIS.md` and fill `coverage` and `gaps` in `refs.jsonl` via `plans` (`record-ref`) before asking adoption questions.
 7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both).
 8. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum. `Auto-complete` cannot grant this waiver.
 9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round, then a criticizer round), no refinement limit, at most five high-priority comments or questions per refinement round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 
 ## REF_ANALYSIS.md
 
-Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; local download paths; structured analysis summaries; adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.
+Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; configured refs root and local download paths; the per-reference `analyze_refs` structured analyses (pasted verbatim, one section per reference); adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.
 
 Reference ideas are not eligible for `PLAN_v1.md` until their adoption question answers are recorded.

package/src/code-graph/commands.ts

@@ -17,7 +17,7 @@ import { makeBackend } from "./parsers/javascript.ts";
 import { PythonBackend } from "./parsers/python.ts";
 import type { ParserBackend } from "./parser.ts";
 import type { Language } from "./types.ts";
-import { materialize } from "./materialize.ts";
+import { materialize, type MaterializeReport } from "./materialize.ts";
 import { generateSummaries, type CompletionHandle, type SummaryReport } from "./summary.ts";
 import { readActive, getRun, setRunStatus } from "../state.ts";
 
@@ -84,12 +84,16 @@ async function bootstrap(ctx: CommandContext, opts: { reindex?: boolean }): Prom
 	return { store, paths, parsers, runtimeStatus: status };
 }
 
+function activePlanningRun(workdir: string): ActiveInfo | null {
+	const active = readActive(workdir);
+	if (!active) return null;
+	const run = getRun(workdir, active.run_id);
+	if (!run) return null;
+	return run.status === "planning" || run.status === "accepted" ? active : null;
+}
+
 function denyActivePlanning(ctx: CommandContext): boolean {
-	const active = readActive(ctx.cwd);
-	if (!active) return false;
-	const run = getRun(ctx.cwd, active.run_id);
-	if (!run) return false;
-	return run.status === "planning" || run.status === "accepted";
+	return activePlanningRun(ctx.cwd) !== null;
 }
 
 export async function initGraphCommand(args: string, ctx: CommandContext): Promise<void> {
@@ -172,35 +176,77 @@ export async function initGraphCommand(args: string, ctx: CommandContext): Promi
 	}
 }
 
-export async function applyGraphCommand(args: string, ctx: CommandContext): Promise<void> {
-	if (denyActivePlanning(ctx)) {
-		ctx.ui.notify("code-graph apply refused: a planning run is currently planning or accepted.", "error");
-		return;
+export interface ApplyGraphCoreResult {
+	refused?: string;
+	failed?: string;
+	report?: MaterializeReport;
+	drift?: { pending: number; ok: boolean } | null;
+}
+
+/**
+ * Shared core for /apply-graph and the code_graph "apply" tool action:
+ * gate (planning/accepted refusal) → bootstrap → materialize → drift summary.
+ * No notifications and no run-status side effects; callers own presentation
+ * and lifecycle transitions.
+ */
+export async function applyGraphCore(workdir: string, opts: { force?: boolean } = {}): Promise<ApplyGraphCoreResult> {
+	const planned = activePlanningRun(workdir);
+	if (planned) {
+		return { refused: `code-graph apply refused: a planning run is currently planning or accepted (run ${planned.run_id}).` };
 	}
-	const flags = parseCommandArgs(args).flags;
-	const bootstrapResult = await bootstrap(ctx, {});
-	if (!bootstrapResult) return;
+	let bootstrapFailure = "";
+	const bootstrapResult = await bootstrap(
+		{ cwd: workdir, hasUI: false, ui: { notify: (message: string) => { bootstrapFailure ||= message; }, confirm: async () => false } } as never,
+		{},
+	);
+	if (!bootstrapResult) return { failed: bootstrapFailure || "code-graph runtime unavailable" };
 	const { store, paths } = bootstrapResult;
 	try {
-		const report = materialize({ store, worktreeRoot: paths.worktreeRoot, force: flags.has("force") });
-		const stale = report.files.filter((file) => file.status === "stale").length;
-		const errors = report.files.filter((file) => file.status === "error").length;
-		const ok = report.files.filter((file) => file.status === "ok").length;
-		const deleted = report.files.filter((file) => file.status === "deleted").length;
-		const skipped = report.files.filter((file) => file.status === "skipped-missing").length;
-		ctx.ui.notify(
-			`code-graph apply: ${ok} ok, ${deleted} deleted, ${stale} stale, ${skipped} skipped-missing, ${errors} error`,
-			errors > 0 ? "error" : "info",
-		);
-		const active = readActive(ctx.cwd);
-		if (active) setRunStatus(ctx.cwd, active.run_id, "executing");
+		const report = materialize({ store, worktreeRoot: paths.worktreeRoot, force: opts.force ?? false });
+		let drift: ApplyGraphCoreResult["drift"] = null;
+		try {
+			const d = computeDrift(store, paths.worktreeRoot);
+			drift = { pending: d.pending.length, ok: d.ok };
+		} catch {
+			drift = null; // drift summary is best-effort; materialization already succeeded
+		}
+		return { report, drift };
 	} catch (error) {
-		ctx.ui.notify(`code-graph apply failed: ${(error as Error).message}`, "error");
+		return { failed: (error as Error).message };
 	} finally {
 		store.close();
 	}
 }
 
+export async function applyGraphCommand(args: string, ctx: CommandContext): Promise<void> {
+	if (denyActivePlanning(ctx)) {
+		ctx.ui.notify("code-graph apply refused: a planning run is currently planning or accepted.", "error");
+		return;
+	}
+	const flags = parseCommandArgs(args).flags;
+	const core = await applyGraphCore(ctx.cwd, { force: flags.has("force") });
+	if (core.refused) {
+		ctx.ui.notify(core.refused, "error");
+		return;
+	}
+	if (core.failed || !core.report) {
+		ctx.ui.notify(`code-graph apply failed: ${core.failed ?? "unknown error"}`, "error");
+		return;
+	}
+	const report = core.report;
+	const stale = report.files.filter((file) => file.status === "stale").length;
+	const errors = report.files.filter((file) => file.status === "error").length;
+	const ok = report.files.filter((file) => file.status === "ok").length;
+	const deleted = report.files.filter((file) => file.status === "deleted").length;
+	const skipped = report.files.filter((file) => file.status === "skipped-missing").length;
+	ctx.ui.notify(
+		`code-graph apply: ${ok} ok, ${deleted} deleted, ${stale} stale, ${skipped} skipped-missing, ${errors} error`,
+		errors > 0 ? "error" : "info",
+	);
+	const active = readActive(ctx.cwd);
+	if (active) setRunStatus(ctx.cwd, active.run_id, "executing");
+}
+
 export async function graphStatusCommand(_args: string, ctx: CommandContext): Promise<void> {
 	const bootstrapResult = await bootstrap(ctx, {});
 	if (!bootstrapResult) return;
@@ -309,7 +355,7 @@ export function computeDrift(store: Store, worktreeRoot: string): DriftResult {
 	const recommendation = needsUpdate
 		? "run /update-graph to reindex changed paths"
 		: needsApply
-			? "run /apply-graph to materialize pending DB edits"
+			? "run code_graph apply (or /apply-graph) to materialize pending DB edits"
 			: "in sync";
 	return {
 		ok: hashDrift.every((item) => item.kind !== "hash-mismatch") && unindexed.length === 0,

package/src/code-graph/prompts.ts

@@ -13,6 +13,6 @@ export function graphBlockForRefiner(enabled: boolean): string {
 
 export function graphBlockForExecutor(enabled: boolean): string {
 	return enabled
-		? "Code graph loop: indexed code files read as a function digest by default — never whole-file; drill in via offset/limit or code_graph get-function, full:true is the only whole-file exit. Edit via graph-aware edit (DB-first), then /apply-graph → /graph-drift → plans final-commit."
+		? "Code graph loop: indexed code files read as a function digest by default — never whole-file; drill in via offset/limit or code_graph get-function, full:true is the only whole-file exit. Edit via graph-aware edit (DB-first), then code_graph apply (its result includes the post-apply drift summary) → plans final-commit."
 		: "Code graph disabled: edit source files directly with edit/write.";
 }