pi-plans 0.1.2 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@
 <h2 align="center"><b>Plan. Review. Execute.</b></h2>
 
 <p align="center">
-  <i>Versioned, reviewed Markdown plans land before any code changes.<br>Human-in-the-loop planning for the Pi coding agent.</i>
+  <i>Versioned, reviewed Markdown plans land before any code changes.<br>Human-in-the-loop planning for the <a href="https://github.com/earendil-works/pi">Pi coding agent</a>.</i>
 </p>
 
 <p align="center">
@@ -16,6 +16,7 @@
   <a href="https://www.npmjs.com/package/pi-plans"><img alt="npm downloads" src="https://img.shields.io/npm/dt/pi-plans?color=38bdf8" /></a>
   <a href="https://www.npmjs.com/package/pi-plans"><img alt="npm version" src="https://img.shields.io/npm/v/pi-plans?color=60a5fa" /></a>
   <a href="https://github.com/earendil-works/pi"><img alt="Pi package" src="https://img.shields.io/badge/Pi-package-fbbf24" /></a>
+  <a href="https://github.com/earendil-works/pi"><img alt="Pi coding agent" src="https://img.shields.io/badge/Pi%20coding%20agent-earendil--works-22d3ee" /></a>
   <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/pi-plans?color=22c55e" /></a>
   <a href="https://github.com/MaxInGaussian/pi-plans/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/MaxInGaussian/pi-plans/actions/workflows/ci.yml/badge.svg" /></a>
 </p>
@@ -62,7 +63,7 @@ A rough change request becomes a versioned Markdown plan instead of a surprise d
         tracked execution loop
    fused AGENTS.md × Ponytail executor rules
    checklist injected each turn, [DONE:VC-xxx]
-   markers tracked via bottom status bar + detail panel
+   markers tracked via bottom status bar
                  |
                  v
            run status: done
@@ -112,13 +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 |
-| Refinement rounds | Read-only reviewer/criticizer Pi subagents consolidate findings into the next plan version |
+| 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) |
-| Tracked execution | Checklist injected each turn; `[DONE:VC-xxx]` markers drive completion; implementation items report progress with `[I-xxx:implemented]` / `[I-xxx:validating]` markers; `plans-list` groups work by I-item with `[Pending/Implementing/Implemented/Validating/VC passed]` states (passed items struck through); the collapsed footer and expanded panel share the same progress projection, so `x/y` updates in real time in both views |
-| Execution model | With `plans set-execution-model <provider/model[:thinking]>`, the main session switches to it at handoff and restores the planning model + thinking level on stop/complete/abandon; when unset, the first execution handoff prompts for one and recommends inheriting the current session model |
-| Execution-phase compaction | Pi core owns threshold, overflow, and manual compaction scheduling; pi-plans only supplies a plan-aware `session_before_compact` summary and queues one hidden continuation when Pi reports `willRetry: false`, while preserving the raw execution tail and `previousSummary` chaining |
-| Planning-phase auto compaction | In active planning runs (run.status=planning, no execution), context usage >=100% triggers a plan-aware compaction too: pre-plan history compresses, Q&A during planning stays in a dedicated section, the latest `PLAN_vN.md` and later conversation stay raw; cooldown + resume guard prevent ping-pong, and manual `/compact` follows the same rules |
+| 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 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 |
 
@@ -126,17 +129,40 @@ 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-execution-model`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent` |
+| `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 read-only subagents (`--tools read,grep,find,ls`); `reviewers: 3` for big plans; enforces role/model confirmation gates |
-| `execute_plan` | Execution handoff: re-confirms with the user, prompts for an execution model if needed, and enters extension-managed execution mode |
+| `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 |
-| `/plans-list` | Toggle the execution checklist panel |
-| `/plans-execute [plan.md]` | Manual execution handoff (defaults to highest `PLAN_vN.md`; prompts for an execution model if unset) |
+| `/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 |
 | `/plans-stop` | Stop execution mode |
 | `/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 collapsed footer or expanded panel → ⛔ stopped / 🎯 done / 🚫 abandoned |
+| 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
+
+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.
+
+- **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:
+
+- **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
 
@@ -154,6 +180,9 @@ Once you approve the handoff, every turn injects a compact rule set that fuses M
 
 The rules cost four lines per turn and buy back far more: fewer wrong turns, shorter implementation paths, plans that finish in fewer tokens.
 
+Waiting for subprocess-backed verification:
+For subprocess-backed verification, when a step starts a subprocess and needs its result before verifying, use literal `waiting for` with backoff `5s -> 10s -> 20s -> 40s -> 80s`, then keep polling at 80s; restart at 5s for each new subprocess.
+
 ## Skills
 
 Invoked via `resources_discover`, callable as `/skill:<name>`, directly as `/<name>` (e.g. `/planning`, `/plan-small` — extension aliases that forward to the skill), or picked automatically from the task description.
@@ -188,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
-├── src/                   # state, guard, plan parsing, subagent runner, exec loop
+├── 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)
+└── tests/                 # node:test suite (state, guard, plan parsing, execution, refine progress, code-graph)
 ```
 
 ## Safety model
@@ -213,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
 
@@ -223,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). 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

@@ -10,7 +10,7 @@
  *   - `refine` tool     — reviewer/criticizer rounds via read-only pi subagents
  *   - `execute_plan`    — execution handoff into the tracked execution loop
  *   - write guard       — planning runs may only write planning artifacts
- *   - execution loop    — checklist injection, [DONE:VC-xxx] tracking, progress widget
+ *   - execution loop    — checklist injection, [DONE:VC-xxx] tracking, progress status
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -19,7 +19,6 @@ import * as path from "node:path";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-	consumePendingPanelSync,
 	consumePlanningCompactionResumeGuard,
 	drainExecutionFlush,
 	executionContextMessage,
@@ -29,25 +28,44 @@ import {
 	handleExecutionBeforeCompact,
 	handleExecutionCompact,
 	handleExecutionCompactFailed,
+	handleExecutionTurnCompaction,
 	handlePlanningBeforeCompact,
 	handlePlanningCompact,
 	handlePlanningCompactFailed,
+	noteCompactionEnded,
+	noteCompactionStarted,
 	PLANNING_PLAN_WRITTEN_CUSTOM_TYPE,
 	registerExecutionTurnHandlers,
-	recordTouchedPaths,
 	refreshPlanningCompactionCooldown,
 	requestPlanningCompaction,
 	restoreFromSession,
-	ensureExecutionModelActive,
 	stopExecution,
-	syncExecutionPanel,
-	toggleExecutionPanelView,
 	updateStatusWidget,
 	shouldTriggerPlanningCompaction,
 } from "./src/exec.ts";
+import {
+	autoCompleteStatus,
+	disableAutoComplete,
+	markPlanWritten,
+	registerAutoCompleteTurnHandlers,
+	restoreAutoCompleteFromSession,
+} 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";
@@ -63,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) {
@@ -80,20 +103,12 @@ function extensionStalenessLine(): string {
 	}
 }
 
-function extractPathsFromBash(command: string): string[] {
-	const values = new Set<string>();
-	for (const token of command.split(/\s+/)) {
-		const cleaned = token.replace(/^["'`(<[{]+|["'`)>}\],;]+$/g, "");
-		if (!cleaned || cleaned === "." || cleaned === ".." || cleaned.startsWith("-") || cleaned.includes("=") ) continue;
-		const looksLikePath =
-			cleaned.includes("/") ||
-			cleaned.startsWith(".") ||
-			cleaned.startsWith("~") ||
-			/^[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+$/.test(cleaned);
-		if (!looksLikePath) continue;
-		values.add(cleaned);
-	}
-	return [...values];
+function hasActivePlanningWorkflow(ctx: Parameters<typeof updateStatusWidget>[0]): boolean {
+	if (getExecution()) return true;
+	const active = readActive(ctx.cwd);
+	if (!active) return false;
+	const status = getRun(ctx.cwd, active.run_id)?.status;
+	return status === "planning" || status === "accepted" || status === "executing";
 }
 
 export default function piPlansExtension(pi: ExtensionAPI): void {
@@ -101,6 +116,9 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	registerAskChoiceTool(pi);
 	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", () => ({
@@ -142,25 +160,14 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// not been approved), edit/write may only target planning artifacts.
 	// -----------------------------------------------------------------------
 	pi.on("tool_call", async (event, ctx) => {
-		const execution = getExecution();
-		if (execution) {
-			if (event.toolName === "edit" || event.toolName === "write") {
-				const rawPath = String((event.input as { path?: string }).path ?? "");
-				if (rawPath) recordTouchedPaths(ctx.cwd, [rawPath]);
-			}
-			if (event.toolName === "bash") {
-				const command = String((event.input as { command?: string }).command ?? "");
-				if (command) recordTouchedPaths(ctx.cwd, extractPathsFromBash(command));
-			}
-			return;
-		}
+		if (getExecution()) return;
 		const rawPath = String((event.input as { path?: string }).path ?? "");
 		if (!rawPath) return;
 		const reason = planningWriteBlockReason({ workdir: ctx.cwd, toolName: event.toolName, rawPath });
 		if (reason) return { block: true, reason };
 		// Allowed write: if it lands exactly on the run's latest plan file, drop a
 		// marker entry so planning-phase compaction can anchor its cut point there.
-		if (event.toolName === "write") {
+		if (event.toolName === "write" || event.toolName === "edit") {
 			const active = readActive(ctx.cwd);
 			if (active) {
 				const latest = latestPlanVersion(active.artifact_dir);
@@ -169,12 +176,39 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 						runId: active.run_id,
 						planPath: latest.path,
 					});
+					markPlanWritten(ctx);
 				}
 			}
 		}
 		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);
@@ -184,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
@@ -210,8 +247,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// -----------------------------------------------------------------------
 	pi.on("before_agent_start", async (_event, ctx) => {
 		drainExecutionFlush(pi, ctx);
-		await ensureExecutionModelActive(pi, ctx);
-		const content = executionContextMessage();
+		const content = executionContextMessage(ctx);
 		if (!content) {
 			if (!getExecution() && shouldTriggerPlanningCompaction(ctx)) {
 				requestPlanningCompaction(ctx);
@@ -228,10 +264,11 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	});
 
 	registerExecutionTurnHandlers(pi, async (ctx) => {
-		if (!getExecution()) {
+		if (getExecution()) {
+			handleExecutionTurnCompaction(ctx);
+		} else {
 			refreshPlanningCompactionCooldown(ctx);
 			if (consumePlanningCompactionResumeGuard(ctx)) {
-				if (consumePendingPanelSync()) syncExecutionPanel(ctx);
 				updateStatusWidget(ctx);
 				return;
 			}
@@ -239,24 +276,61 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 				requestPlanningCompaction(ctx);
 			}
 		}
-		// A busy-toggle during the previous turn deferred its re-render; the
-		// turn just ended, so this is the safe point to apply it.
-		if (consumePendingPanelSync()) syncExecutionPanel(ctx);
+		// A completed turn is the safe point for status updates.
 		updateStatusWidget(ctx);
 	});
+	registerAutoCompleteTurnHandlers(pi);
 
 	// -----------------------------------------------------------------------
-	// Commands and shortcuts
+	// Commands
 	// -----------------------------------------------------------------------
-	pi.registerShortcut("alt+o", {
-		description: "Toggle pi-plans execution checklist widget",
-		handler: async (ctx) => {
-			const expanded = toggleExecutionPanelView(pi, ctx);
-			if (expanded === null) {
-				ctx.ui.notify("No execution in progress.", "info");
-				return;
-			}
-			ctx.ui.notify(expanded ? "Execution checklist expanded." : "Execution checklist collapsed.", "info");
+
+	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);
 		},
 	});
 
@@ -283,20 +357,24 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 					lines.push(`  ${item.done ? "☑" : "☐"} ${item.id}`);
 				}
 			}
+			lines.push(`Auto-complete: ${autoCompleteStatus(ctx)}`);
 			lines.push(extensionStalenessLine());
 			ctx.ui.notify(lines.join("\n"), "info");
 		},
 	});
 
-	pi.registerCommand("plans-list", {
-		description: "Toggle the pi-plans execution checklist widget",
+	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) => {
-			const expanded = toggleExecutionPanelView(pi, ctx);
-			if (expanded === null) {
-				ctx.ui.notify("No execution in progress.", "info");
-				return;
-			}
-			ctx.ui.notify(expanded ? "Execution checklist expanded." : "Execution checklist collapsed.", "info");
+			const stopped = disableAutoComplete(ctx, "stopped by user");
+			ctx.ui.notify(stopped ? "Auto-complete stopped." : "Auto-complete is not active.", stopped ? "info" : "warning");
 		},
 	});
 
@@ -333,6 +411,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 
 			const active = readActive(ctx.cwd);
 			const execution = getExecution();
+			disableAutoComplete(ctx, "plan update");
 
 			// Resolve the plan to revise: explicit arg > running execution > latest in artifact dir.
 			let sourcePlanPath: string | null = planArg
@@ -441,6 +520,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 			);
 			if (!ok) return;
 			// Abandon must end execution first so the planning model is restored.
+			disableAutoComplete(ctx, "run abandoned");
 			if (getExecution()) {
 				await stopExecution(pi, ctx, "run abandoned via /plans-abandon");
 			}
@@ -459,5 +539,6 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// -----------------------------------------------------------------------
 	pi.on("session_start", async (_event, ctx) => {
 		await restoreFromSession(pi, ctx, ctx.sessionManager.getEntries() 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.1.2",
+  "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"
   }
 }