pi-plans 0.2.0 → 0.3.0

package/README.md

@@ -113,15 +113,15 @@ 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 |
+| 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 |
 | Workspace state | Config, runs, decisions, refs, and subagent ledgers in `.git/pi_plans/` (git common dir) |
-| Smart compact (I-aware) | History is sliced by `I-###` instead of VC. The current-I slice above 20% of the model window triggers a bounded summary with paired `Read:` records, retains a legal recent suffix, targets <10% post-context, and records a hard-floor reason when unreachable. Planning phase falls back to the latest plan/Q&A focus when no current marker exists; cooldown + resume guard prevent ping-pong; one hidden continuation is queued when Pi reports `willRetry: false` |
-| 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, bounded output preview, and clean cancelled/timed-out vs completed states. The overlay opens when the round starts and closes before the tool result returns to the main session |
+| 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 |
 | Execution handoff | The accepted plan resumes in the current session model; no separate model selection is performed. |
-| Execution-phase compaction | Pi core owns threshold, overflow, and manual scheduling; pi-plans adds a current-I proactive check once the current-I slice exceeds 20% of the model window, summarizes I-level history and bounded `Read:` records, retains a legal recent suffix, targets under 10% when possible, and records hard-floor reasons when not; one hidden continuation is queued when Pi reports `willRetry: false` |
-| Planning-phase auto compaction | In active planning runs (run.status=planning, no execution), the current-I check uses the same 20%/10% best-effort policy when a marker exists; without a marker it protects the latest plan/Q&A focus, while Pi threshold, overflow, and manual compaction remain supported; cooldown + resume guard prevent ping-pong and hidden resume messages stay out of model context |
+| 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. |
 | 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 |
 
@@ -131,9 +131,10 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 |---|---|
 | `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-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`); delegated TUI runs show one `Reviewer`/`Criticizer` overlay and close it before returning; `reviewers: 3` for big plans; enforces role/model confirmation gates |
+| `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 |
 | `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`) |
 | `/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 |
@@ -141,24 +142,26 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | `/plans-abandon` | Abandon the active run (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 |
 
-## Smart compact (I-aware)
+## VCC compact
 
-Default `compaction` is Pi-core-owned: threshold, overflow, and manual `/compact` always run as designed. On top of that, pi-plans layers an **I-aware policy** so long, tool-heavy sessions survive the same run instead of running out of context:
+Pi core remains the owner of compaction scheduling: manual `/compact`, threshold, and overflow events are emitted by Pi as usual. During an active pi-plans planning or execution run, pi-plans handles `session_before_compact` with a deterministic VCC-style compiler instead of calling a model for a summary.
 
-- **Slice by implementation item.** History is grouped by `[I-###:current]` markers instead of `[DONE:VC-xxx]`. The current I's prefix can be summarized, the current I's recent suffix stays raw, and finished `I-###` items become independent sections.
-- **Bounded read history.** Every paired `read` call/result is reduced to `Read: <path> line <X-Y> Extracted information summary: ...` (line range is `unknown` when no offset/limit is given). Records deduplicate by path/range across compactions and never embed full raw tool output.
-- **20%/10% best-effort budget.** When the current-I slice exceeds 20% of `ctx.getContextUsage().contextWindow`, a compact is requested on the next settled turn. The summary's `details` record `contextWindow`, `tokensBefore`, `currentITokens`, `summaryTokens`, `keptSuffixTokens`, `estimatedAfterTokens`, `targetRatio`, `currentI`, `firstKeptEntryId`, `targetMet`, and a `hardFloorReason` when the 10% target cannot be reached (system prompt, tool definitions, single oversized tool result). Hard floors stop the loop; they do not silently fall through.
-- **Pi-owned scheduling preserved.** Threshold, overflow, and manual triggers still come from Pi core. pi-plans only customizes the summary and re-arms once usage falls below the low watermark. The hidden `Continue execution.` resume message is queued on non-retry compactions and never enters model context.
-- **Bounded model call.** Custom summaries reuse the current Pi model via `ctx.modelRegistry.complete(model, context, options)` with `event.signal`, `cacheRetention: "none"`, a fresh `sessionId`, and bounded `maxTokens`. Empty, length-stopped, error, or tool-call responses fall back to Pi's default compaction — no half-checkpoint is ever written.
-- **Phase isolation.** Planning and execution keep independent compaction state (`pi-plans-plan-resume` vs `pi-plans-exec-resume`); planning without a current marker protects the latest plan/Q&A focus rather than leaking execution state.
+- **Summary shape.** The summary contains exactly five bracket sections: `[Session Goal]`, `[Files And Changes]`, `[Commits]`, `[Outstanding Context]`, and `[User Preferences]`, followed by `---` and a ranked brief transcript. Execution contributes plan path, current `I-###`, implementation IDs, and remaining verifier IDs; planning contributes run ID, artifact directory, latest plan path from session entries, and any observed current-I marker.
+- **Session-only input.** Compact summaries are built from the event's branch entries, previous summary, file ops, pi-plans custom session entries, and live phase state. The compiler does not read plan files, git history, or the worktree to invent context.
+- **Tail policy.** The default keep is one recent user turn; smart keep may retain more turns when the tail is still small. Explicit `keep:N` is honored, while no-anchor and oversized-tail cases use a deterministic token-budget cut that avoids starting retained context with an orphan tool result.
+- **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.
+- **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`, `debug:false`. Global pi-vcc config and `PI_VCC_CONFIG_PATH` are intentionally ignored.
 
 ## 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:
 
-- **Named public overlays.** Each round uses the literal overlay name `Reviewer` or `Criticizer` (no dependency on `pi-btw`; the renderer is built on Pi's public `pi-tui` primitives). The big-plan concurrent reviewer round renders one reviewer lane per subagent under the same `Reviewer` overlay.
-- **Bounded live detail.** The overlay tracks lane state (`pending → running → completed | cancelled | timed-out`) and the most recent tool call plus a clipped argument preview. Raw tool output is never surfaced, so progress stays legible even when subagents read large files.
-- **Clean lifecycle edges.** The overlay opens at round start, advances via the JSONL progress feed emitted by `pi --mode json`, and is `close()`d before the round's conclusion returns as a tool result to the main session. Cancelled and timed-out children render as terminal states with the original error message — never as silent drops.
+- **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.
+- **No input row.** The overlay has no composer, no submit path, and no printable input forwarding. Only `Esc`, `Tab`/`Shift+Tab`, `↑/↓`, `PgUp/PgDn`, and SGR mouse wheel are consumed; everything else is ignored by design.
+- **Equal-height panes for `reviewers: 3`.** Concurrent reviewer rounds render one reviewer lane per subagent as three independent equal-height panes inside the same top-center overlay; each pane keeps its own scroll offset and `follow-bottom` state. `Tab`/`Shift+Tab` switches the focused pane and scroll keys only affect it.
+- **Lifecycle.** The overlay opens at round start, advances via the JSONL progress feed emitted by `pi --mode json`, and is dismissed by `Esc`. `Esc` is close-only — it never aborts the refiner child; the child keeps running to natural completion and its result still flows back through the tool result path. A new refinement round replaces any retained finished overlay to avoid overlay stacking. Cancelled and timed-out children render as terminal states with the original error message — never as silent drops.
 - **Tool-only progress.** The overlay only consumes tool and message lifecycle events from the child; unrelated `pi` events are ignored, so a noisy upstream release does not desync the panel.
 
 ## The execution rules
@@ -214,18 +217,65 @@ or register the absolute path in `~/.pi/agent/settings.json`:
 { "extensions": ["/absolute/path/to/pi-plans"] }
 ```
 
+## Code graph (v0.3+)
+
+`/init-graph` walks the worktree, parses JavaScript/TypeScript and Python
+files with Tree-sitter, and stores a normalized function graph in
+`.git/pi_plans/code_graph.db`. The DB is the canonical source for downstream
+agents: function rows expose a low-token `description`/`inputs`/`outputs`
+JSON view, call edges are normalized with `in_links`/`out_links` derived on
+read, and each function retains its full UTF-8 source.
+
+- `/init-graph [--reindex] [--no-summary] [--no-commit]` — scan the worktree and write the graph; if `code_graph.db` already exists, it first asks whether to rebuild or sync changed paths via `/update-graph` (non-interactive runs and `--reindex` stay on the rebuild path). With `--reindex` it keeps the existing full-worktree reindex semantics on the rebuild path. Dirty trees get a `chore(code-graph): pre-init snapshot` commit first (`--no-commit` skips). After indexing it records a `code_graph_snapshot` (HEAD + uncommitted paths) that `/graph-drift` compares against. The parser dependencies are installed via npm (`tree-sitter`, grammars).
+- `/graph-status` — print function/file/edge counts.
+- `/update-graph [--dry-run] [--base <commit>]` — incrementally reindex only the paths `git status --porcelain` reports (including untracked and rename targets); deleted files' DB rows are purged, never resurrected. `/init-graph` uses this path when you choose the sync-changes branch.
+- `/graph-drift [--json] [--commit-aware]` — direction-aware convergence check:
+  (a) per-file hash match or a pending apply marker, (b) every uncommitted
+  indexable path is indexed, (c) snapshot vs current HEAD (informational).
+- `/apply-graph [--force]` — materialize DB edits back to source. Files with
+  `pending_kind='update'` are written (created when missing on disk);
+  `pending_kind='delete'` files are removed from disk and the DB; pending-null
+  missing files are skipped, never resurrected. Refuses when the active
+  planning run is `planning`/`accepted`.
+- `/enable-graph` / `/disable-graph` — toggle the `graph_enabled` config
+  flag (disable refuses while drift is dirty). When enabled, planner/refiner/
+  executor prompts hard-require function-level reads for indexed code, and the
+  built-in `read`/`write`/`edit` tools become graph-aware overrides for
+  indexed source files: `read` returns a capped function digest (≤50 lines,
+  synthetic anonymous entries folded) with `full: true` as the only whole-file
+  exit (small/zero-function files return full text); `write`/`edit` stage
+  DB-first mutations; unexpected fallbacks (not indexed / runtime unavailable /
+  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`.
+- 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
+  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
+runtimes (Bun, missing parsers) graph commands fail locally without
+affecting the planning workflow.
+
 ## Layout
 
 ```
 pi-plans/
 ├── index.ts               # Extension entry: tools, commands, guard, execution loop
-├── tools/                 # plans, ask-choice, refine, execute-plan
+├── tools/                 # plans, ask-choice, refine, execute-plan, code-graph
 ├── src/                   # state, guard, plan parsing, subagent runner, refine overlay, exec loop
+│   └── 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
 ├── scripts/validate.ts    # Structure validator
-└── tests/                 # node:test suite (state, guard, plan parsing, execution, refine progress)
+└── tests/                 # node:test suite (state, guard, plan parsing, execution, refine progress, code-graph)
 ```
 
 ## Safety model
@@ -239,7 +289,10 @@ npm run validate   # structure validator
 npm test           # node:test suite (stdlib only, no deps)
 ```
 
-Both run on Node ≥ 22.6 via `--experimental-strip-types`; no npm dependencies.
+Both run on Node ≥ 22.6 via `--experimental-strip-types`. The graph
+extension additionally requires `node:sqlite` (Node ≥ 22.13 unflagged, or
+any Node ≥ 22.6 with `--experimental-sqlite`) and the four parser
+dependencies listed in `dependencies`.
 
 ## FAQ
 
@@ -249,7 +302,7 @@ 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.
+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.
 
 **Where does all the state live?**
 

package/index.ts

@@ -32,6 +32,8 @@ import {
 	handlePlanningBeforeCompact,
 	handlePlanningCompact,
 	handlePlanningCompactFailed,
+	noteCompactionEnded,
+	noteCompactionStarted,
 	PLANNING_PLAN_WRITTEN_CUSTOM_TYPE,
 	registerExecutionTurnHandlers,
 	refreshPlanningCompactionCooldown,
@@ -50,8 +52,20 @@ import {
 } from "./src/autocomplete.ts";
 import { planningWriteBlockReason } from "./src/guard.ts";
 import { registerQueryInterviewHooks } from "./src/query-hook.ts";
+import { registerCodeGraphTool } from "./tools/code-graph.ts";
+import { registerGraphAwareFileTools } from "./tools/graph-aware-file-tools.ts";
+import {
+	initGraphCommand,
+	applyGraphCommand,
+	graphStatusCommand,
+	updateGraphCommand,
+	graphDriftCommand,
+	enableGraphCommand,
+	disableGraphCommand,
+} from "./src/code-graph/commands.ts";
 import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
-import { getRun, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.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 { registerPlansTool } from "./tools/plans.ts";
@@ -67,12 +81,17 @@ const extensionLoadedAt = new Date();
 function extensionStalenessLine(): string {
 	try {
 		const dirs = [baseDir, path.join(baseDir, "src"), path.join(baseDir, "tools")];
+		const stack: string[] = [...dirs];
 		let newest = 0;
-		for (const dir of dirs) {
-			for (const name of fs.readdirSync(dir)) {
-				if (!name.endsWith(".ts")) continue;
-				const mtime = fs.statSync(path.join(dir, name)).mtimeMs;
-				if (mtime > newest) newest = mtime;
+		while (stack.length) {
+			const dir = stack.pop()!;
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				const full = path.join(dir, entry.name);
+				if (entry.isDirectory()) stack.push(full);
+				else if (entry.isFile() && entry.name.endsWith(".ts")) {
+					const mtime = fs.statSync(full).mtimeMs;
+					if (mtime > newest) newest = mtime;
+				}
 			}
 		}
 		if (newest > extensionLoadedAt.getTime() + 2000) {
@@ -98,6 +117,8 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	registerRefineTool(pi, baseDir);
 	registerExecutePlanTool(pi);
 	registerQueryInterviewHooks(pi, hasActivePlanningWorkflow);
+	registerCodeGraphTool(pi);
+	registerGraphAwareFileTools(pi);
 
 	// Contribute the router skill plus the five specialist planning skills.
 	pi.on("resources_discover", () => ({
@@ -162,6 +183,32 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		return;
 	});
 
+	// Bidirectional code-graph reminder hook: separate from the planning guard
+	// above (which early-returns during execution). Fires only when the graph
+	// is enabled and an execution is active. Reminders are best-effort notifies.
+	pi.on("tool_call", async (event, ctx) => {
+		if (!getExecution()) return;
+		const stateRoot = resolveStateRootOrNull(ctx.cwd);
+		if (!stateRoot) return;
+		let graphEnabled = false;
+		try {
+			graphEnabled = loadConfig(stateRoot).graph_enabled === true;
+		} catch {
+			return;
+		}
+		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");
+			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");
+			}
+		}
+	});
+
 	pi.on("context", (event) => {
 		const filteredExecution = filterExecutionResumeMessages(event.messages as Array<{ customType?: string }>);
 		const messages = filterPlanningResumeMessages(filteredExecution);
@@ -171,17 +218,20 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_before_compact", async (event, ctx) => {
+		noteCompactionStarted(ctx, event.customInstructions);
 		const executionResult = await handleExecutionBeforeCompact(pi, ctx, event);
 		if (executionResult) return executionResult;
 		return handlePlanningBeforeCompact(pi, ctx, event);
 	});
 	pi.on("session_compact", async (event, ctx) => {
-		handleExecutionCompact(pi, ctx, event);
-		handlePlanningCompact(pi, ctx, event);
+		await handleExecutionCompact(pi, ctx, event);
+		await handlePlanningCompact(pi, ctx, event);
+		noteCompactionEnded(ctx, event.customInstructions);
 	});
 	pi.on("session_compact_failed", async (event, ctx) => {
 		handleExecutionCompactFailed(pi, ctx, event);
 		handlePlanningCompactFailed(pi, ctx, event);
+		noteCompactionEnded(ctx, event.customInstructions);
 	});
 
 	// Flush points for deferred execution-loop writes: primary drain when the
@@ -197,7 +247,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// -----------------------------------------------------------------------
 	pi.on("before_agent_start", async (_event, ctx) => {
 		drainExecutionFlush(pi, ctx);
-		const content = executionContextMessage();
+		const content = executionContextMessage(ctx);
 		if (!content) {
 			if (!getExecution() && shouldTriggerPlanningCompaction(ctx)) {
 				requestPlanningCompaction(ctx);
@@ -235,6 +285,55 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// Commands
 	// -----------------------------------------------------------------------
 
+	pi.registerCommand("init-graph", {
+		description: "Index the worktree into .git/pi_plans/code_graph.db. If a graph DB already exists, prompt to rebuild or sync changed paths via /update-graph; `--reindex` and non-interactive runs stay on the rebuild path.",
+		handler: async (args, ctx) => {
+			await initGraphCommand(args, ctx);
+		},
+	});
+
+	pi.registerCommand("apply-graph", {
+		description: "Apply code_graph.db changes back to source. Refuses during active planning/accepted run.",
+		handler: async (args, ctx) => {
+			await applyGraphCommand(args, ctx);
+		},
+	});
+
+	pi.registerCommand("graph-status", {
+		description: "Show code graph counts (functions, files, edges).",
+		handler: async (args, ctx) => {
+			await graphStatusCommand(args, ctx);
+		},
+	});
+
+	pi.registerCommand("update-graph", {
+		description: "Incrementally reindex working-tree changes (git status porcelain, incl. untracked/renames) into code_graph.db. Also used by /init-graph when you choose the sync-changes branch. Flags: --dry-run, --base <commit>.",
+		handler: async (args, ctx) => {
+			await updateGraphCommand(args, ctx);
+		},
+	});
+
+	pi.registerCommand("graph-drift", {
+		description: "Check DB↔source convergence (hash/pending, uncommitted coverage, snapshot). Flags: --json, --commit-aware.",
+		handler: async (args, ctx) => {
+			await graphDriftCommand(args, ctx);
+		},
+	});
+
+	pi.registerCommand("enable-graph", {
+		description: "Enable the code graph: agents prefer graph reads and DB-first edits.",
+		handler: async (_args, ctx) => {
+			await enableGraphCommand(_args, ctx);
+		},
+	});
+
+	pi.registerCommand("disable-graph", {
+		description: "Disable the code graph (refuses while DB/source drift is dirty).",
+		handler: async (_args, ctx) => {
+			await disableGraphCommand(_args, ctx);
+		},
+	});
+
 	pi.registerCommand("plans", {
 		description: "Show pi-plans state: config, active run, and execution progress",
 		handler: async (_args, ctx) => {
@@ -264,6 +363,13 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("config-pi-plans", {
+		description: "Re-ask and update pi-plans workspace config: language, artifact root, graph, reviewer, and criticizer defaults",
+		handler: async (args, ctx) => {
+			await configPiPlansCommand(args, ctx);
+		},
+	});
+
 	pi.registerCommand("plans-autocomplete-stop", {
 		description: "Stop Auto-complete for the active planning run",
 		handler: async (_args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-plans",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -54,5 +54,11 @@
     "validate": "node --experimental-strip-types scripts/validate.ts",
     "test": "node --experimental-strip-types scripts/run-tests.ts",
     "prepack": "npm run validate && npm test"
+  },
+  "dependencies": {
+    "tree-sitter": "^0.25.1",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-typescript": "^0.23.2"
   }
 }

package/references/pi-planning-workflow.md

@@ -9,9 +9,10 @@ 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`) with isolated context; delegated Reviewer/Criticizer runs show a standalone aggregate overlay titled `Reviewer` or `Criticizer`, close the overlay before returning, and return conclusions to the main session as tool output;
+- `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;
 - 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, group compacted history by implementation item, retain a legal current-I suffix, summarize paired reads as bounded `Read: <path> line <X-Y> Extracted information summary: ...` records, and target `<10%` of the model window after a current-I slice exceeds `20%`; hard-floor cases are recorded instead of looping;
+- 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
 
@@ -129,13 +130,27 @@ A refinement round is complete when all reviewer outputs have returned or all cr
 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:
 
 - 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);
-- execution-phase compaction may proactively compact the current-I slice above 20% of the model window, summarizes the oldest eligible prefix and bounded Read records, preserves a legal recent suffix, and records whether the <10% target was met; Pi still owns threshold, overflow, and manual scheduling;
+- 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;
 - `/plans-stop` stops execution; `/plans` shows progress.
 
 If the user declines, stay in planning (or stop, per their choice). Never start implementation without the approved handoff.
 
+### 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).
+
+The agent then asks one `ask_choice` question for the termination condition of the implementation-review loop:
+
+- `autoComplete: false` — suppresses the run-scoped Auto-complete mode for this question.
+- Options (recommended first): 1. until no high-severity finding (hard cap 5 rounds) 2. 1 round 3. 2 rounds 4. 3 rounds.
+- Each refinement round calls `refine` with `role: "reviewer", target: "implementation"`, 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.
+- 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.
+
+`refine` accepts a `target` parameter (`"plan"` default, `"implementation"` for the post-execution loop). The implementation brief anchors findings to the plan's goals and acceptance criteria, explicitly assesses delivery maturity (MVP-only vs. long-term refinement: stopgaps, missing tests, technical debt, production readiness), and tags out-of-scope improvements as low severity.
+
 ## Red Flags
 
 Stop and return to the workflow if any of these happen:

package/references/state-and-config.md

@@ -25,6 +25,7 @@ Bare repositories are refused with a clear error. A missing `git` executable is
 ```text
 <git-common-dir>/pi_plans/
   config.json
+  pi-vcc-config.json
   active.json
   runs/
     <run-id>/
@@ -36,7 +37,7 @@ Bare repositories are refused with a clear error. A missing `git` executable is
   cache/
 ```
 
-`config.json` is stable workspace preference state. `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. 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 Schema
 
@@ -76,6 +77,30 @@ Rules:
 - `artifact_root_updated_at` is the selection timestamp or `null` before confirmation.
 - 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
+
+`pi-vcc-config.json` is scaffolded under the resolved `<git-common-dir>/pi_plans/` state root when an active planning or execution compaction hook first needs it. It is independent from `config.json` so planning preferences, run state, and compact policy can evolve separately.
+
+Default values:
+
+```json
+{
+  "overrideDefaultCompaction": true,
+  "smartKeepTail": true,
+  "continueAfterThresholdCompact": true,
+  "debug": false
+}
+```
+
+Rules:
+
+- Only the repo-private file is read. Upstream global pi-vcc config such as `~/.pi/agent/pi-vcc-config.json` and `PI_VCC_CONFIG_PATH` are ignored.
+- Missing files are created with defaults; valid files keep user values and receive missing default keys; invalid JSON is never clobbered and the runtime falls back to defaults for that read.
+- `overrideDefaultCompaction:false` returns ordinary Pi manual/threshold/overflow compactions to Pi core. Explicit pi-plans internal compact hints can still use the VCC path.
+- `smartKeepTail:true` starts from the requested/default keep count and may retain more recent user turns when the retained tail remains within the safe token budget. Explicit `keep:N` is honored.
+- `continueAfterThresholdCompact:true` permits one hidden continuation after successful threshold/overflow compaction only on Pi versions that still need extension-driven resume behavior. Plain manual `/compact` never auto-continues, and `/compact <text>` sends the text once as the follow-up prompt.
+- `debug:false` writes no diagnostics; `debug:true` writes a best-effort `/tmp/pi-vcc-debug.json` snapshot for local troubleshooting.
+
 ## Language Setting
 
 Before the first product planning question, check the persisted config (`plans` action `show`). If `language.tag` is missing or invalid, ask exactly one `ask_choice` question:
@@ -88,7 +113,14 @@ Before the first product planning question, check the persisted config (`plans`
 
 Persist with `plans` (`set-language`, `languageSource: "user"`). Use the selected language for visible questions, choices, review summaries, criticizer questions, and Markdown artifacts. Keep IDs, file paths, command names, JSON keys, and protocol labels stable in English.
 
-## Planning Docs Location
+## 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.
+
+## `/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.
+
 
 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:
 

package/scripts/validate.ts

@@ -22,11 +22,15 @@ const REQUIRED_TOOL_FILES = [
 	"tools/ask-choice.ts",
 	"tools/refine.ts",
 	"tools/execute-plan.ts",
+	"tools/code-graph.ts",
 	"src/state.ts",
 	"src/guard.ts",
 	"src/plan.ts",
 	"src/subagent.ts",
 	"src/exec.ts",
+	"src/code-graph/runtime.ts",
+	"src/code-graph/schema.ts",
+	"src/code-graph/store.ts",
 ];
 
 const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;