pi-plans 0.1.2 → 0.3.0

package/references/pi-planning-workflow.md

@@ -9,8 +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; their results return to the main session as tool output;
-- the execution loop is extension-managed: remaining verifier items are injected each turn and `[DONE:VC-xxx]` markers are tracked with a footer progress widget.
+- `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; 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
 
@@ -60,6 +62,7 @@ Every user-facing planning or refinement question goes through the `ask_choice`
 - `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with the tradeoff that matters in `description`;
 - do not add `Other` or `Auto-complete` yourself — the tool appends `Other…` second-last and `Auto-complete` last;
 - pass `autoComplete: false` for the merged accept/execute question — it contains the execution approval, so Auto-complete never appears there — and for any install waiver, publishing, deployment, merge, push, credential, or external-state question. Auto-complete may choose the recommended planning or refinement option only.
+- When the user selects Auto-complete, it remains active for the current planning run: later eligible questions use their recommended options automatically, and the extension queues one deduplicated follow-up if the model stops after an auto-completed answer. `/plans-autocomplete-stop` disables it; session restore may reactivate it only for the same active run while its status is `planning`.
 
 Answers are recorded automatically in the active run's `decisions.jsonl`. You must still maintain `DECISIONS.md` in the artifact directory (summary table of questions, options, answers, answer sources, open assumptions).
 
@@ -126,13 +129,28 @@ 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, no stopgaps, dependency and library discipline, minimum tests);
+- 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 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:
 
@@ -120,7 +152,7 @@ If a spawn later fails because the stored selector is unavailable, reset the mar
 
 ## Subagent Spawning
 
-When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` subprocess (`--mode json -p --no-session --tools read,grep,find,ls`) whose system prompt comes from `agents/reviewer.md` or `agents/criticizer.md`. The subagent:
+When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` subprocess (`--mode json -p --no-session --tools read,grep,find,ls`) whose system prompt comes from `agents/reviewer.md` or `agents/criticizer.md`. In TUI mode, delegated runs also show a standalone `Reviewer` or `Criticizer` overlay with live lane/tool status; the child is awaited and the overlay is closed before the tool result returns. The subagent:
 
 - performs read-only analysis and never edits files;
 - receives the full plan text and a review/criticism brief;

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]+)*$/;

package/src/autocomplete.ts

@@ -0,0 +1,163 @@
+/** Run-scoped Auto-complete state and planning-turn continuation. */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getRun, readActive } from "./state.ts";
+
+export const AUTOCOMPLETE_ENTRY = "pi-plans-autocomplete";
+const AUTOCOMPLETE_CONTINUE = "Continue the current planning workflow. Raise the next relevant question with ask_choice; do not stop after an auto-completed answer.";
+
+type SessionEntry = { type: string; customType?: string; data?: unknown };
+
+type AutoCompleteState = {
+	runId: string;
+	enabled: boolean;
+	pendingFollowUp: boolean;
+	askChoiceCount: number;
+	autoChoiceCount: number;
+	planWritten: boolean;
+};
+
+type SessionWithAutoComplete = ExtensionContext["sessionManager"] & {
+	__piPlansAutoComplete?: AutoCompleteState;
+};
+
+let api: ExtensionAPI | null = null;
+
+export function setAutoCompleteApi(next: ExtensionAPI | null): void {
+	api = next;
+}
+
+function sessionState(ctx: ExtensionContext): AutoCompleteState | undefined {
+	return (ctx.sessionManager as SessionWithAutoComplete).__piPlansAutoComplete;
+}
+
+function activePlanningRun(ctx: ExtensionContext): { runId: string } | null {
+	const active = readActive(ctx.cwd);
+	if (!active) return null;
+	const run = getRun(ctx.cwd, active.run_id);
+	return run?.status === "planning" ? { runId: run.run_id } : null;
+}
+
+function appendState(runId: string, enabled: boolean, reason?: string): void {
+	if (!api) return;
+	api.appendEntry(AUTOCOMPLETE_ENTRY, { runId, enabled, ...(reason ? { reason } : {}) });
+}
+
+export function enableAutoComplete(ctx: ExtensionContext): boolean {
+	const run = activePlanningRun(ctx);
+	if (!run) return false;
+	const current = sessionState(ctx);
+	if (current?.enabled && current.runId === run.runId) return true;
+	(ctx.sessionManager as SessionWithAutoComplete).__piPlansAutoComplete = {
+		runId: run.runId,
+		enabled: true,
+		pendingFollowUp: false,
+		askChoiceCount: 0,
+		autoChoiceCount: 0,
+		planWritten: false,
+	};
+	appendState(run.runId, true);
+	return true;
+}
+
+export function disableAutoComplete(ctx: ExtensionContext, reason = "disabled"): boolean {
+	const state = sessionState(ctx);
+	const run = activePlanningRun(ctx);
+	const runId = state?.runId ?? run?.runId;
+	if (!runId && !state?.enabled) return false;
+	if (state) state.enabled = false;
+	if (runId) appendState(runId, false, reason);
+	return true;
+}
+
+export function isAutoCompleteEnabled(ctx: ExtensionContext): boolean {
+	const state = sessionState(ctx);
+	const run = activePlanningRun(ctx);
+	return !!state?.enabled && !!run && state.runId === run.runId;
+}
+
+/** Record every ask_choice call for this turn; autoChoice marks a recommendation selected by the mode. */
+export function recordAskChoice(ctx: ExtensionContext, autoChoice: boolean): void {
+	const state = sessionState(ctx);
+	if (!state) return;
+	state.askChoiceCount += 1;
+	if (autoChoice) state.autoChoiceCount += 1;
+}
+
+export function markPlanWritten(ctx: ExtensionContext): void {
+	const state = sessionState(ctx);
+	if (state) state.planWritten = true;
+}
+
+export function resetAutoCompleteTurn(ctx: ExtensionContext): void {
+	const state = sessionState(ctx);
+	if (!state) return;
+	state.pendingFollowUp = false;
+	state.askChoiceCount = 0;
+	state.autoChoiceCount = 0;
+	state.planWritten = false;
+}
+
+export function shouldContinueAutoComplete(ctx: ExtensionContext): boolean {
+	const state = sessionState(ctx);
+	return isAutoCompleteEnabled(ctx)
+		&& !!state
+		&& state.autoChoiceCount > 0
+		&& state.askChoiceCount === state.autoChoiceCount
+		&& !state.planWritten
+		&& !state.pendingFollowUp;
+}
+
+export async function continueAutoComplete(ctx: ExtensionContext): Promise<boolean> {
+	if (!api || !shouldContinueAutoComplete(ctx)) return false;
+	const state = sessionState(ctx);
+	if (!state) return false;
+	state.pendingFollowUp = true;
+	try {
+		await api.sendUserMessage(AUTOCOMPLETE_CONTINUE, { deliverAs: "followUp" });
+		return true;
+	} catch {
+		state.pendingFollowUp = false;
+		return false;
+	}
+}
+
+export function registerAutoCompleteTurnHandlers(pi: ExtensionAPI): void {
+	setAutoCompleteApi(pi);
+	pi.on("turn_start", async (_event, ctx) => {
+		resetAutoCompleteTurn(ctx);
+	});
+	pi.on("turn_end", async (event, ctx) => {
+		const message = event.message as { role?: string } | undefined;
+		if (message?.role === "assistant") await continueAutoComplete(ctx);
+	});
+}
+
+export function restoreAutoCompleteFromSession(ctx: ExtensionContext, entries: SessionEntry[]): void {
+	const session = ctx.sessionManager as SessionWithAutoComplete;
+	delete session.__piPlansAutoComplete;
+	let restored: { runId: string; enabled: boolean } | null = null;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type !== "custom" || entry.customType !== AUTOCOMPLETE_ENTRY || !entry.data) continue;
+		const data = entry.data as { runId?: unknown; enabled?: unknown };
+		if (typeof data.runId === "string" && typeof data.enabled === "boolean") {
+			restored = { runId: data.runId, enabled: data.enabled };
+			break;
+		}
+	}
+	const active = activePlanningRun(ctx);
+	if (!restored || !restored.enabled || !active || restored.runId !== active.runId) return;
+	session.__piPlansAutoComplete = {
+		runId: active.runId,
+		enabled: true,
+		pendingFollowUp: false,
+		askChoiceCount: 0,
+		autoChoiceCount: 0,
+		planWritten: false,
+	};
+}
+
+export function autoCompleteStatus(ctx: ExtensionContext): "enabled" | "disabled" {
+	return isAutoCompleteEnabled(ctx) ? "enabled" : "disabled";
+}