pi-soly 0.2.1

package/workflows/execute.ts

@@ -0,0 +1,401 @@
+// =============================================================================
+// workflows/execute.ts — `soly execute <N>` / `soly execute <N.MM>` handler
+// =============================================================================
+//
+// Intercepts "soly execute 11" (phase) or "soly execute 11.02" (specific plan)
+// and transforms it into a detailed LLM instruction that launches a worker
+// subagent with the soly execute workflow loaded into its system prompt.
+//
+// We use `action: "transform"` (not `action: "handled"`) — the LLM still
+// receives the request, but with the full workflow context, so it can call
+// the `subagent(...)` tool itself and apply the SOLY-specific close-out
+// discipline (commits, SUMMARY.md, STATE.md update).
+//
+// We do NOT spawn the subagent directly from the extension — `subagent(...)`
+// is a tool only available to the LLM (via pi-subagents), and the parent
+// session needs to keep ownership of the close-out loop.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describeExecuteTarget, type SolyCommand } from "./parser.js";
+import type { SolyState } from "../core.js";
+import {
+	extractPlanSummary,
+	renderPlanSummaryInline,
+	writeIterationContext,
+} from "../iteration.js";
+
+/** Resolve <extension>/workflows-data/<name>.md regardless of cwd. */
+function loadWorkflowMarkdown(name: string): string | null {
+	try {
+		const here = path.dirname(fileURLToPath(import.meta.url));
+		// workflows-data is sibling of workflows/
+		const candidate = path.resolve(here, "..", "workflows-data", name);
+		if (fs.existsSync(candidate)) return fs.readFileSync(candidate, "utf-8");
+	} catch {
+		// fileURLToPath may fail in some runtimes; fall through.
+	}
+	return null;
+}
+
+/** Build the inline plan summary block for the worker task (so it has the
+ *  must_haves / wave / requirements even before reading the iteration file). */
+function inlinePlanSummary(planFilePath: string | null): string {
+	if (!planFilePath) return "_(no PLAN.md located)_";
+	const raw = fs.readFileSync(planFilePath, "utf-8");
+	const summary = extractPlanSummary(raw);
+	if (!summary) return "_(PLAN.md missing frontmatter or unparseable)_";
+	return renderPlanSummaryInline(summary);
+}
+
+export interface ExecuteHandlerResult {
+	handled: boolean;
+	transformedText?: string;
+}
+
+/**
+ * Build the transformed LLM instruction for a `soly execute ...` command.
+ * Returns { handled: false } if the args are malformed.
+ *
+ * `interactiveRules` is the list of relPaths marked `interactive: true`
+ * — passed to the worker so it knows which rules are explicitly OUT of
+ * scope (they describe the user-facing conversation, not the work).
+ */
+export function buildExecuteTransform(
+	cmd: SolyCommand,
+	state: SolyState,
+	interactiveRules: string[] = [],
+	opts: { agent?: string; useSolyWorker?: boolean } = {},
+): ExecuteHandlerResult {
+	if (!state.exists) {
+		return {
+			handled: true,
+			transformedText:
+				`soly: no .soly/ directory found in cwd (${state.solyDir || "<cwd>"}) — cannot execute phase.\n` +
+				`Initialize a soly project first (see soly quickstart) before running "soly execute".`,
+		};
+	}
+
+	const projectRoot = path.dirname(state.solyDir);
+	const target = describeExecuteTarget(cmd.args);
+	if (!target) {
+		return {
+			handled: true,
+			transformedText:
+				`soly execute: missing or malformed target.\n` +
+				`Usage:\n` +
+				`  soly execute <N>            — execute all plans in phase N\n` +
+				`  soly execute <N.MM>         — execute a specific plan\n` +
+				`  soly execute <task-id>      — execute a specific task (new dual-mode)\n` +
+				`  soly execute --all          — execute all ready tasks (sequential in v0.1)\n` +
+				`  soly execute --feature <n>  — execute all tasks in a feature (sequential in v0.1)`,
+		};
+	}
+
+	// === TASK MODE (new dual-mode) ===
+	if (target.kind === "task") {
+		const task = state.tasks.find((t) => t.id === target.taskId);
+		if (!task) {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: task ${target.taskId} not found in .soly/features/*/tasks/.\n` +
+					`Known tasks: ${state.tasks.map((t) => t.id).join(", ") || "(none)"}\n` +
+					`Tip: use the \`soly_list_tasks\` tool to see all available tasks.`,
+			};
+		}
+		if (!task.planExists) {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: task ${target.taskId} has no PLAN.md at ${task.dir}/PLAN.md.\n` +
+					`Create a PLAN.md with frontmatter (id, kind, feature, status, depends-on) before executing.`,
+			};
+		}
+		if (task.status === "blocked") {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: task ${target.taskId} is \`status: blocked\`.\n` +
+					`Resolve blockers in PLAN.md before executing.`,
+			};
+		}
+		if (task.status === "done") {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: task ${target.taskId} is already \`status: done\`.\n` +
+					`SUMMARY.md exists at ${task.dir}/SUMMARY.md. To re-run, change status to \`ready\` in PLAN.md frontmatter.`,
+			};
+		}
+		// Check deps
+		const unmetDeps = task.dependsOn.filter((depId) => {
+			const dep = state.tasks.find((t) => t.id === depId);
+			return !dep || dep.status !== "done";
+		});
+		if (unmetDeps.length > 0) {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: task ${target.taskId} has unmet dependencies: [${unmetDeps.join(", ")}].\n` +
+					`Tasks must be \`status: done\` (have a SUMMARY.md) before their dependents can run.`,
+			};
+		}
+		const workflow = loadWorkflowMarkdown("execute-task.md");
+		if (!workflow) {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: workflow markdown not found: workflows-data/execute-task.md\n` +
+					`This is an extension installation issue — reinstall soly.`,
+			};
+		}
+		const featureDir = path.dirname(path.dirname(task.dir));
+
+		// Write per-iteration context bundle (B2 of the soly design).
+		// Worker reads this file first; no need to chase 6+ .soly/ files.
+		const iter = writeIterationContext({
+			solyDir: state.solyDir,
+			projectRoot,
+			kind: "exec",
+			taskId: task.id,
+			feature: task.feature,
+		});
+		const inlineSummary = inlinePlanSummary(path.join(task.dir, "PLAN.md"));
+
+		const instruction = `soly execute ${target.taskId} — launching worker for task.
+
+**Task:** ${task.id}
+**Feature:** ${task.feature}
+**Kind:** ${task.kind}
+**Status:** ${task.status}
+**Priority:** ${task.priority}
+**Depends-on:** [${task.dependsOn.join(", ") || "none"}]
+**Parallelizable:** ${task.parallelizable}
+**Dir:** ${task.dir}
+
+**Iteration context file written:** \`${iter.relPath}\` (${iter.tokens} tokens, ${iter.bytes} bytes)
+The worker reads this file first — it contains intent, STATE, ROADMAP (n/a for tasks), the feature README, prior task SUMMARYs, and the current task PLAN.
+
+**0-POINT CHECK.** Worker must re-read .soly/docs/ (intent) and .soly/features/${task.feature}/README.md before implementing.
+
+Launch a single subagent for this work. Do NOT do the work inline.
+
+subagent({
+  agent: ${JSON.stringify(opts.agent ?? "worker")},
+  context: "fresh",
+  async: true,
+  maxSubagentDepth: 1,
+  task: \`You are soly-executor (single-task writer).
+
+Your job: execute ONE task (atomic unit) and produce its SUMMARY.md.
+
+**FIRST ACTION — read the iteration context file:**
+\`\`\`
+${iter.relPath}
+\`\`\`
+It contains intent, STATE, feature README, prior task SUMMARYs, and the current PLAN. Do NOT skip it. The must-haves below are also inlined so you have them even before reading the file.
+
+**Inline plan summary (from PLAN.md frontmatter + Must Haves):**
+${inlineSummary}
+
+Project root: ${projectRoot}
+Soly dir:    ${state.solyDir}
+Feature dir: ${featureDir}
+Task dir:    ${task.dir}
+
+**0-POINT CHECK — read .soly/docs/ first.**
+These are the project's INTENT (business context, design vision). Re-read them before implementing. If you find a conflict between intent and PLAN.md, flag it instead of silently choosing one.
+
+**Follow the worker self-audit gate (see .soly/rules/process/worker-audit.md):**
+1. Run \`dotnet build\` (or relevant build) — 0 warnings
+2. Cross-check diff against .soly/rules/coding/*
+3. Invoke \`analyzer-coach\` skill for any rule gaps
+4. Loop until clean (max 3 iterations)
+5. Commit (production-code commit(s))
+6. Write SUMMARY.md, commit it
+7. Update PLAN.md frontmatter: \`status: done\`
+
+=== WORKFLOW: execute-task.md ===
+${workflow}
+=== END WORKFLOW ===
+
+Hard rules:
+  - Do not skip the close-out order: production commits -> SUMMARY commit -> status: done.
+  - Do not modify any .soly/rules/ files.
+  - Do not run subagents yourself.
+  - Do not start a task whose \`depends-on:\` lists tasks that are not \`done\`.
+  - PATH DISCIPLINE: all files YOU create must live under \`.soly/\` (iteration, handoff, etc.) or under the project's source dirs. Never write to the project root.
+  - Return: changed files, commands run with exit codes, validation evidence, surprises, decisions needing parent approval.
+  - Interactive-only rules are NOT in scope for you: ${interactiveRules.length > 0 ? interactiveRules.join(", ") : "(none)"}.
+\`
+})
+
+When the subagent completes, synthesize the result. Do not re-execute its work.`;
+		return { handled: true, transformedText: instruction };
+	}
+
+	// === ALL / FEATURE (new dual-mode, sequential in v0.1) ===
+	if (target.kind === "all" || target.kind === "feature") {
+		const allTasks =
+			target.kind === "all"
+				? state.tasks
+				: state.tasks.filter((t) => t.feature === target.feature);
+		if (allTasks.length === 0) {
+			return {
+				handled: true,
+				transformedText:
+					target.kind === "all"
+						? `soly execute --all: no tasks found in .soly/features/*/tasks/.`
+						: `soly execute --feature ${target.feature}: no tasks found for that feature.`,
+			};
+		}
+		const ready = allTasks.filter((t) => t.status === "ready");
+		const blocked = allTasks.filter((t) => t.status === "blocked");
+		const done = allTasks.filter((t) => t.status === "done");
+		if (ready.length === 0) {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: no ready tasks in scope.\n` +
+					`Tasks: ${allTasks.length} total, ${done.length} done, ${blocked.length} blocked.`,
+			};
+		}
+		return {
+			handled: true,
+			transformedText:
+				`soly execute ${target.kind === "all" ? "--all" : `--feature ${target.feature}`}: ${ready.length} task(s) ready.\n\n` +
+				`**v0.1 limitation:** tasks run sequentially, not in parallel. Parallel mode is v0.2.\n\n` +
+				`Ready tasks (in suggested order):\n` +
+				ready.map((t, i) => `  ${i + 1}. ${t.id}  [${t.kind}]  prio=${t.priority}`).join("\n") +
+				`\n\nLaunch a single subagent to execute them one at a time in this order. The subagent uses the task execution workflow (execute-task.md) per task.`,
+		};
+	}
+
+	// === PHASE MODE ===
+	const phase = state.phases.find((p) => p.number === target.phase);
+	if (!phase) {
+		return {
+			handled: true,
+			transformedText:
+				`soly execute: phase ${target.phase} not found in .soly/phases/.\n` +
+				`Known phases: ${state.phases.map((p) => p.number).join(", ") || "(none)"}`,
+		};
+	}
+
+	const isPlanLevel = target.plan != null;
+	const workflowName = isPlanLevel ? "execute-plan.md" : "execute-phase.md";
+	const workflow = loadWorkflowMarkdown(workflowName);
+	if (!workflow) {
+		return {
+			handled: true,
+			transformedText:
+				`soly execute: workflow markdown not found: workflows-data/${workflowName}\n` +
+				`This is an extension installation issue — reinstall soly.`,
+		};
+	}
+
+	// Write per-iteration context bundle (B2 of the soly design).
+	// For plan-level execution: bundle includes the specific PLAN.md.
+	// For phase-level execution: bundle includes all plan frontmatter summaries
+	// (the phase workflow iterates waves on its own).
+	const iter = writeIterationContext({
+		solyDir: state.solyDir,
+		projectRoot,
+		kind: "exec",
+		phaseNumber: target.phase,
+		planNumber: isPlanLevel ? (target.plan ?? undefined) : undefined,
+	});
+
+	// For plan-level: also pull out the must_haves summary for inline cache.
+	const planFile = isPlanLevel
+		? path.join(phase.dir, `${phase.slug}-${String(target.plan).padStart(2, "0")}-${phase.slug.split("-").slice(1).join("-") || "plan"}-PLAN.md`)
+		: null;
+	// Fall back to findPlanFile if the conventional name didn't match.
+	let planFileResolved = planFile;
+	if (isPlanLevel && planFile && !fs.existsSync(planFile)) {
+		const padded = String(target.plan).padStart(2, "0");
+		const candidates = fs.readdirSync(phase.dir).filter((f) =>
+			new RegExp(`^\\d+-${padded}-.+-PLAN\\.md$`).test(f),
+		);
+		if (candidates.length > 0) planFileResolved = path.join(phase.dir, candidates[0]!);
+	}
+	const inlineSummary = isPlanLevel ? inlinePlanSummary(planFileResolved) : "_(phase-level exec — iterate all PLAN.md files; each iteration has its own bundle)_";
+
+	// Build the LLM instruction. Keep it terse at the top, then dump the
+	// workflow markdown verbatim so the LLM has full context.
+	const targetDesc = isPlanLevel
+		? `phase ${target.phase} plan ${String(target.plan).padStart(2, "0")}`
+		: `phase ${target.phase} (${phase.name}) — all ${phase.planCount} plan(s)`;
+
+	const scopeBlock = isPlanLevel
+		? `Target: ONE plan = ${targetDesc}.
+The iteration context file lists the specific plan at section 6.`
+		: `Target: ${targetDesc}.
+The iteration context file lists all plans (their frontmatter) in section 6, grouped by wave.`;
+
+	const childRole = isPlanLevel
+		? `soly-executor (single-plan writer)`
+		: `soly-executor (wave-based parallel phase executor)`;
+
+	const instruction = `soly execute ${target.raw} — launching worker for ${targetDesc}.
+
+**Iteration context file written:** \`${iter.relPath}\` (${iter.tokens} tokens, ${iter.bytes} bytes)
+The worker reads this file first — it contains intent, STATE, ROADMAP row for this phase, phase CONTEXT, phase RESEARCH, prior SUMMARYs, ${isPlanLevel ? "and the current PLAN" : "and all PLAN frontmatter summaries"}, and (for exec) the Critical Anti-Patterns from .continue-here.md.
+
+**0-POINT CHECK — worker must read .soly/docs/ first.**
+These are the project's INTENT docs. The worker is about to implement tasks; if the implementation diverges from intent, it will be wrong even if the tests pass. Have the worker re-read .soly/docs/ (and any intent docs linked from PLAN.md) before each plan.
+
+${scopeBlock}
+
+Launch a single subagent for this work. Do NOT do the work inline.
+
+subagent({
+  agent: ${JSON.stringify(opts.agent ?? "worker")},
+  context: "fresh",
+  async: true,
+  maxSubagentDepth: 1,  // worker must not spawn sub-sub-agents
+  task: \`You are ${childRole}.
+
+Your job: ${isPlanLevel ? "execute ONE plan and produce its SUMMARY.md" : "execute ALL plans in this phase using wave-based parallel execution"}.
+
+**FIRST ACTION — read the iteration context file:**
+\`\`\`
+${iter.relPath}
+\`\`\`
+It contains intent, STATE, ROADMAP, phase CONTEXT, phase RESEARCH, prior SUMMARYs, ${isPlanLevel ? "and the current PLAN" : "and the wave-grouped plan index"}, and (for exec) the Critical Anti-Patterns.
+
+${isPlanLevel
+	? `**Inline plan summary (so you have must-haves even before reading the file):**
+${inlineSummary}`
+	: `**Note for phase-level exec:** for each plan you execute, you may write a new bundle via the extension (the parent will regenerate; you do not need to). Or, simpler: read the plan file directly from the source path listed in section 6. The must-haves of the current plan are in section 6 too.`}
+
+Project root: ${projectRoot}
+Soly dir:    ${state.solyDir}
+Phase dir:   ${phase.dir}
+
+**0-POINT CHECK — read .soly/docs/ first.**
+These are the project's INTENT (business context, design vision). Re-read them before implementing each plan. If you find a conflict between intent and PLAN.md, flag it instead of silently choosing one.
+
+Follow the workflow below VERBATIM — these are the user-approved soly instructions, not suggestions.
+
+=== WORKFLOW: ${workflowName} ===
+${workflow}
+=== END WORKFLOW ===
+
+Hard rules:
+  - Do not skip the close-out order: production commits -> SUMMARY commit -> STATE/ROADMAP update.
+  - Do not modify any .soly/rules/ files.
+  - Do not run subagents yourself.
+  - PATH DISCIPLINE: all files YOU create must live under \`.soly/\` (e.g. .soly/iterations/, .soly/phases/<slug>/, .soly/HANDOFF.json) or under the project's source dirs. Never write PLAN/SUMMARY/CONTEXT/RESEARCH/iteration files to the project root.
+  - Return: changed files, commands run with exit codes, validation evidence, surprises, and any decisions needing parent approval.
+  - Interactive-only rules are NOT in scope for you: ${interactiveRules.length > 0 ? interactiveRules.join(", ") : "(none)"}. They describe how the user-facing conversation should go, not how to execute work.
+\`
+})
+
+When the subagent completes, synthesize the result and confirm STATE.md was updated. Do not re-execute its work.`;
+
+	return { handled: true, transformedText: instruction };
+}

package/workflows/index.ts

@@ -0,0 +1,235 @@
+// =============================================================================
+// workflows/index.ts — Single `input` event hook for all soly workflow verbs
+// =============================================================================
+//
+// Intercepts plain-text "soly <verb> ..." user input (NOT /soly slash commands
+// — those still go through pi.registerCommand in commands.ts).
+//
+// For each verb, the handler either:
+//   - transforms the input into a detailed LLM instruction (execute / pause /
+//     compact / resume / plan / discuss) — LLM drives the heavy lifting
+//   - shows a direct response (status / log / diff) — extension computes
+//     immediately, no LLM round-trip needed
+//
+// "Direct response" verbs (status/log/diff) return action: "handled" — the
+// LLM never sees them, and the user gets an immediate UI notification.
+// =============================================================================
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { parseSolyCommand, type SolyCommand } from "./parser.js";
+import { buildExecuteTransform } from "./execute.js";
+import { buildPauseTransform } from "./pause.js";
+import { buildResumeTransform } from "./resume.js";
+import { showStatus, showLog, showDiff } from "./quick.js";
+import { showDoctor, showIterations, showDiffIterations, showPhaseDelete, showTodos } from "./inspect.js";
+import { buildPlanTransform, buildDiscussTransform } from "./planning.js";
+import type { SolyState } from "../core.js";
+import type { SolyConfig } from "../config.js";
+
+export interface WorkflowsDeps {
+	getState: () => SolyState;
+	/** List of rule relPaths marked `interactive: true` — passed to subagent
+	 *  workers so they know which rules are explicitly out of scope. */
+	getInteractiveRules: () => string[];
+	/** List of active tool names. Used to detect optional cross-extension
+	 *  dependencies (e.g. `ask_pro` from the separate `pi-ask` extension). */
+	getActiveTools: () => string[];
+	/** Current merged config (per-project + global + defaults). */
+	getConfig: () => SolyConfig;
+	/** Fired when a recognized soly verb is parsed (handled OR transformed).
+	 *  Used by the parent extension to reset drift counters etc. */
+	onWorkflowUsed?: () => void;
+}
+
+export function registerWorkflows(pi: ExtensionAPI, deps: WorkflowsDeps): void {
+	const { getState, getInteractiveRules, getActiveTools, getConfig, onWorkflowUsed } = deps;
+	// The current agent is owned by the separate `pi-switch` extension.
+	// It writes `globalThis.__PI_SWITCH_AGENT__` (in-process) and
+	// `.soly/agent` (persisted). We read the in-process value first (fresh);
+	// fall back to "worker" if pi-switch isn't installed.
+	const getCurrentAgent = (): string => {
+		return (globalThis as { __PI_SWITCH_AGENT__?: string }).__PI_SWITCH_AGENT__ ?? "worker";
+	};
+
+	// Track whether we need to fire ctx.compact() at the end of the upcoming
+	// turn. Reset on every user input — only set if the user types
+	// "soly compact" (which expands to a handoff + compact request).
+	let pendingCompact = false;
+
+	pi.on("input", async (event, ctx) => {
+		// Only handle plain interactive text. Skip:
+		//   - extension-injected messages (recursion guard)
+		//   - RPC / programmatic sources (we want explicit user intent)
+		//   - slash commands ("/soly ...") — those go through pi's command
+		//     handler in commands.ts, not here
+		if (event.source !== "interactive") return;
+		if (event.text.trim().startsWith("/")) return;
+
+		const cmd = parseSolyCommand(event.text);
+		if (!cmd) return;
+
+		// Notify the parent extension that a soly verb was used
+		// (resets the drift counter, etc.). Fires for BOTH "handled"
+		// and "transform" actions — both are real workflow usage.
+		onWorkflowUsed?.();
+
+		const state = getState();
+
+		// ----- LLM-driven transforms -----
+
+		if (cmd.verb === "execute") {
+			const result = buildExecuteTransform(cmd, state, getInteractiveRules(), {
+				useSolyWorker: getConfig().agent.useSolyWorkerSubagents,
+			});
+			if (!result.handled || !result.transformedText) return;
+			return { action: "transform", text: result.transformedText };
+		}
+
+		if (cmd.verb === "pause" || cmd.verb === "compact") {
+			const result = buildPauseTransform(cmd, state);
+			if (!result.handled || !result.transformedText) return;
+			if (result.triggerCompact) pendingCompact = true;
+			return { action: "transform", text: result.transformedText };
+		}
+
+		if (cmd.verb === "resume") {
+			const result = buildResumeTransform(cmd, state);
+			if (!result.handled || !result.transformedText) return;
+			return { action: "transform", text: result.transformedText };
+		}
+
+		if (cmd.verb === "plan") {
+			const result = buildPlanTransform(cmd, state);
+			if (!result.handled || !result.transformedText) return;
+			return { action: "transform", text: result.transformedText };
+		}
+
+		if (cmd.verb === "discuss") {
+			const hasAskPro = getActiveTools().includes("ask_pro");
+			const result = buildDiscussTransform(cmd, state, { hasAskPro });
+			if (!result.handled || !result.transformedText) return;
+			return { action: "transform", text: result.transformedText };
+		}
+
+		if (cmd.verb === "help") {
+			return {
+				action: "transform",
+				text: `soly subcommand picker (esc to cancel).
+
+Available verbs (all start with \`soly <verb>\` or use \`/soly <verb>\` in slash form):
+
+  position       — one-screen current position summary
+  state          — full STATE.md body
+  plan           — current PLAN.md body
+  context        — current phase CONTEXT.md
+  research       — current phase RESEARCH.md
+  roadmap        — ROADMAP.md body
+  progress       — progress bar + counts
+  phases         — list all phases with C/R markers
+  tasks          — list all tasks grouped by feature (new in v2)
+  task <id>      — show one task's PLAN + SUMMARY
+  features       — list all features (new in v2)
+  milestone      — show the active milestone document
+  log [N]        — last N (default 20) decisions from STATE.md
+  diff           — git status + uncommitted .soly/ changes
+  doctor         — health check: missing files, broken refs, stale iterations
+  iterations [N] — list recent iteration files
+  todos          — show pi-todo live list (.soly/todos.json or .pi-todos.json)
+  phase delete <N> — soft-delete a phase
+  reload         — re-read project state from disk
+  plan <N>       — produce PLAN.md for phase N
+  discuss <N>    — interactive discussion of phase N
+  execute <N>    — execute all plans in phase N (or \`execute N.MM\` for one plan)
+  pause          — write HANDOFF.json + .continue-here.md
+  compact        — pause + auto-compact session
+  resume [N]     — restore from handoff (scoped to phase N if given)
+  help           — this picker
+
+Unknown / missing verb? Use \`/soly\` (slash) for the picker.`,
+			};
+		}
+
+		// ----- Direct responses (no LLM round-trip) -----
+
+		if (cmd.verb === "status") {
+			showStatus(cmd, state, ctx.ui, getConfig());
+			return { action: "handled" };
+		}
+
+		if (cmd.verb === "log") {
+			showLog(cmd, state, ctx.ui);
+			return { action: "handled" };
+		}
+
+		if (cmd.verb === "diff") {
+			// Subverb: "soly diff iterations <a> <b>" — compare two iteration files
+			if (cmd.args[0] === "iterations" || cmd.args[0] === "iter") {
+				showDiffIterations(
+					{ verb: "diff", args: cmd.args.slice(1), raw: cmd.raw },
+					state,
+					ctx.ui,
+				);
+			} else {
+				await showDiff(cmd, state, ctx.ui);
+			}
+			return { action: "handled" };
+		}
+
+		if (cmd.verb === "doctor") {
+			showDoctor(cmd, state, ctx.ui, getConfig(), getActiveTools());
+			return { action: "handled" };
+		}
+
+		if (cmd.verb === "iterations") {
+			showIterations(cmd, state, ctx.ui);
+			return { action: "handled" };
+		}
+
+		if (cmd.verb === "todos") {
+			showTodos(cmd, state, ctx.ui);
+			return { action: "handled" };
+		}
+
+		if (cmd.verb === "phase") {
+			// "soly phase delete <N>" — soft delete
+			if (cmd.args[0] === "delete" || cmd.args[0] === "rm") {
+				showPhaseDelete(
+					{ verb: "phase", args: cmd.args.slice(1), raw: cmd.raw },
+					state,
+					ctx.ui,
+				);
+			} else {
+				return {
+					action: "transform",
+					text: `soly phase — usage:
+  soly phase delete <N>   — soft-delete phase N (move to .soly/phases/.trash/)
+  soly phase list        — list all phases (same as /soly phases)
+  soly phase <N>         — alias for "soly plan <N>" (route through planner)`,
+				};
+			}
+			return { action: "handled" };
+		}
+	});
+
+	// After the LLM finishes a turn that was triggered by "soly compact",
+	// fire ctx.compact() to actually compress the session.
+	pi.on("agent_end", async (_event, ctx) => {
+		if (!pendingCompact) return;
+		pendingCompact = false;
+		ctx.compact({
+			customInstructions:
+				"Session was paused via `soly compact`. Handoff files are in .soly/HANDOFF.json " +
+				"and .soly/.continue-here.md. Preserve milestone/phase/plan position and key " +
+				"decisions in the summary. Drop implementation-detail noise.",
+			onComplete: () => {
+				ctx.ui.notify("soly: session compacted. Use `soly resume` to pick up.", "info");
+			},
+			onError: (err) => {
+				ctx.ui.notify(`soly: compact failed — ${err.message}`, "error");
+			},
+		});
+	});
+}
+
+/** Re-export for callers that want to inspect the parsed command. */
+export type { SolyCommand };