pi-goal-x 0.13.0 → 0.15.0

package/README.md

@@ -19,10 +19,19 @@ All core features of [@capyup/pi-goal](https://github.com/capyup/pi-goal) are pr
 - **Auditor integration** — the independent completion auditor receives both the `verificationContract` and `verificationSummary` and cross-checks claims against real artifacts.
 - **`complete_goal` `testResults` removed** — replaced with `verificationSummary`. The old structured test results interface is gone.
 
-### Task list system
+### Unified goal + task acceptance
 
-- **Structured task breakdown** — the agent can propose a task list via `propose_task_list`, which shows the user a Confirm / Continue Chatting dialog (mirrors the `propose_goal_draft` pattern). Once confirmed, tasks are displayed in prompts, the widget, serialized to disk, and included in auditor review.
-- **Per-task completion** — `complete_task` marks individual tasks done with optional evidence, and `skip_task` marks tasks as skipped with a required reason. Neither stops the turn, so the agent can continue uninterrupted.
+- **Single-dialog confirmation** — `propose_goal_draft` now accepts an optional `tasks` array parameter. The confirmation dialog shows the goal objective AND the proposed task list together in a single rich TUI view with box-drawing panel (`┌─ TASKS ───┐`), section headers, and hierarchical indentation for subtasks.
+- **Atomic creation** — one confirmation (single enter press) creates the goal AND its task list together. No need for separate `propose_goal_draft` + `propose_task_list` calls.
+- **Backward compatible** — existing separate `propose_task_list` flow continues to work unchanged. Goals without tasks work as before.
+
+### Task list & sub-task system
+
+- **Structured task breakdown** — the agent can propose a task list via `propose_task_list` (standalone) or `propose_goal_draft` with `tasks` (unified). Both show a Confirm / Continue Chatting dialog. Once confirmed, tasks are displayed in prompts, the widget, serialized to disk, and included in auditor review.
+- **Recursive subtasks** — tasks can have nested sub-tasks via `subtasks?: GoalTask[]` (full recursive type). Subtask depth is controlled globally by `subtaskDepth` in `.pi/goal-settings.json` (default: 1 level). Too-deep subtrees are rejected at proposal.
+- **Lightweight subtasks** — each task has an optional `lightweightSubtasks?: boolean` flag. When true, the parent can complete regardless of subtask status. When false/absent (full subtasks), all subtasks must be individually complete before the parent can close.
+- **Per-task completion** — `complete_task` marks individual tasks done with optional evidence/verificationSummary, and `skip_task` marks tasks as skipped with a required reason. Neither stops the turn, so the agent can continue uninterrupted.
+- **Hierarchical display** — task lists with subtasks render with indentation in prompts (`taskListBlock`, `goalPrompt`, `continuationPrompt`) and in the TUI widget (recursive count, BFS next-pending).
 - **Optional `taskList`** — goals without a task list work exactly as before. The feature is entirely opt-in.
 - **Soft `complete_goal` gate** — when `blockCompletion: true` is set, `complete_goal` surfaces a warning if pending tasks remain (prompt-level only; the agent can still complete).
 
@@ -39,13 +48,13 @@ All core features of [@capyup/pi-goal](https://github.com/capyup/pi-goal) are pr
 ### E2e test infrastructure
 
 - **Deterministic fork tests using `--mode json`**: the e2e suite spawns a real `pi --fork --mode json` session, parses structured `tool_execution_start`/`tool_execution_end` JSON events for field-level assertions — no free-text AI output parsing. Uses `--append-system-prompt` + `--tools` to force deterministic tool calls.
-- **Full coverage**: 205 tests total — function-level integration tests (12), mock-pi handler tests (4), file-validity checks (6), real `pi --fork --mode json` tests (3 scenarios), propose_goal_tweak unit/integration/e2e tests (15), task list policy/round-trip/render tests (50+), and verification contract tests (14).
+- **Full coverage**: 281 tests total — function-level integration tests, mock-pi handler tests, file-validity checks, real `pi --fork --mode json` E2E tests, propose_goal_tweak unit/integration/e2e tests, task list policy/round-trip/render tests (including subtasks), and verification contract tests.
 
 ### Completion auditor
 
 - **Live progress widget** — when the auditor runs, the TUI shows a spinner, a progress bar (`[████░░░░] 40%`), step labels (`Inspecting files...`, `Verifying success criteria...`), the current tool being executed, and recent output lines. No more wondering if anything is happening.
 - **Escape to skip** — press Escape during an audit to abort it and complete the goal immediately. The skip is recorded in the ledger as `audit_skipped` with reason `user_aborted` and auditor model metadata.
-- **Disable the auditor entirely** — set `disabled: true` in `.pi/goal-auditor.json` (or toggle it via `/goal-settings` → `disabled`). The agent can still bypass with user confirmation by passing `confirmBypassAuditor: true` to `update_goal`.
+- **Disable the auditor entirely** — set `disabled: true` in `.pi/pi-goal-x-settings.json` (or toggle it via `/goal-settings`). The agent can still bypass with user confirmation by passing `confirmBypassAuditor: true` to `update_goal`.
 - **Skipped audits are recorded** — every skip (whether disabled or Escape-aborted) is logged to the ledger with the reason, provider, model, and thinking level for full traceability.
 - **Robust abort detection** — the auditor detects aborts both from exceptions *and* from `session.prompt()` returning after an abort signal, preventing stuck goals or ghost states.
 - **Cleaner lifecycle** — `AbortSignal` is properly wired to `session.abort()`, animation timers are cleaned up, and the unsubscribe path is always executed. No more having to kill the session.
@@ -214,17 +223,7 @@ Before archiving the goal, `update_goal` starts a separate pi agent in an isolat
 
 The auditor is semantic, not a paperwork checklist: it should reject scaffold-only, alpha, generated-template, proxy-metric, build-only, or weakly verified completions when the real user outcome is not satisfied.
 
-By default the auditor uses the current/default pi model. Configure it interactively with `/goal-settings` -> `auditor`, then click `provider`, `model`, or `thinking_level` and type the value directly. The settings are saved to `.pi/goal-auditor.json`. You can also edit the file or override it with environment variables:
-
-```json
-{
-  "provider": "fireworks",
-  "model": "accounts/fireworks/routers/kimi-k2p6-turbo",
-  "thinking_level": "high"
-}
-```
-
-Environment variables `PI_GOAL_AUDITOR_PROVIDER`, `PI_GOAL_AUDITOR_MODEL`, and `PI_GOAL_AUDITOR_THINKING_LEVEL` take precedence over `/goal-settings`.
+By default the auditor uses the current/default pi model. Configure it via `.pi/pi-goal-x-settings.json`, or interactively with `/goal-settings` (see [Configuration](#configuration)).
 
 The completion result prints a full report into the conversation:
 
@@ -272,11 +271,47 @@ Before commands, tools, and lifecycle hooks act on a focused goal, the runtime r
 
 Goal paths are constrained to `.pi/goals/` and `.pi/goals/archived/`; absolute paths, traversal, NUL bytes, symlinks, and unsafe metadata paths are rejected.
 
+## Configuration
+
+All settings live in a single file: **`.pi/pi-goal-x-settings.json`**
+
+Configured interactively via `/goal-settings`, or edited directly:
+
+```json
+{
+  "disableTasks": false,
+  "disableContracts": false,
+  "subtaskDepth": 1,
+  "provider": "fireworks",
+  "model": "accounts/fireworks/models/deepseek-v4-flash",
+  "thinkingLevel": "high",
+  "disabled": false
+}
+```
+
+| Field | Default | Purpose |
+|---|---:|---|
+| `disableTasks` | `false` | Suppress task list features entirely when `true` |
+| `disableContracts` | `false` | Suppress verification contract enforcement when `true` |
+| `subtaskDepth` | `1` | Maximum nesting depth for subtasks |
+| `provider` | system default | Provider name for the auditor agent |
+| `model` | system default | Model name for the auditor agent |
+| `thinkingLevel` | system default | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `disabled` | `false` | When `true`, skip the completion audit entirely |
+
+**Env var overrides:**
+- `PI_GOAL_DISABLE_TASKS=1` — disable task features (takes precedence over file)
+- `PI_GOAL_DISABLE_CONTRACTS=1` — disable contract enforcement (takes precedence over file)
+- `PI_GOAL_SETTINGS_FILE=custom-path.json` — alternative settings file path (relative to cwd or absolute)
+
 ## Environment variables
 
 | Variable | Default | Purpose |
 |---|---:|---|
 | `PI_GOAL_AUTO_CONFIRM` | unset | When `1`, auto-confirms drafts in headless/test contexts |
+| `PI_GOAL_DISABLE_TASKS` | — | When `1`, disable task features (overrides settings file) |
+| `PI_GOAL_DISABLE_CONTRACTS` | — | When `1`, disable contract enforcement (overrides settings file) |
+| `PI_GOAL_SETTINGS_FILE` | `.pi/pi-goal-x-settings.json` | Alternative settings file path (relative to cwd or absolute) |
 
 ## Development
 

package/docs/architecture.md

@@ -200,7 +200,7 @@ Before archiving, the tool starts a separate in-memory pi session with a focused
 - `<approved/>` allows archiving;
 - `<disapproved/>`, no marker, an error, or abort rejects completion and leaves the goal open.
 
-The auditor uses the current/default model unless `.pi/goal-auditor.json` or `PI_GOAL_AUDITOR_PROVIDER`, `PI_GOAL_AUDITOR_MODEL`, and `PI_GOAL_AUDITOR_THINKING_LEVEL` override provider/model/thinking. `/goal-settings` opens a small UI menu with an `auditor` item; inside it, `provider`, `model`, and `thinking_level` each open a free-text input and save back to `.pi/goal-auditor.json`.
+The auditor uses the current/default model unless `.pi/pi-goal-x-settings.json` overrides `provider`, `model`, or `thinkingLevel`. `/goal-settings` opens a TUI showing all settings (disabled, provider, model, thinking_level, subtaskDepth, disableTasks, disableContracts); each editable field opens a free-text input and saves back to `.pi/pi-goal-x-settings.json`.
 
 The user sees:
 

package/extensions/goal-auditor.ts

@@ -13,14 +13,8 @@ import {
 	type ExtensionContext,
 	type ResourceLoader,
 } from "@earendil-works/pi-coding-agent";
-import type { GoalRecord, GoalTaskList } from "./goal-record.ts";
-
-export interface GoalAuditorConfig {
-	provider?: string;
-	model?: string;
-	thinkingLevel?: ThinkingLevel;
-	disabled?: boolean;
-}
+import type { GoalRecord, GoalTask, GoalTaskList } from "./goal-record.ts";
+import { loadGoalSettings, type GoalSettings } from "./goal-settings.ts";
 
 export interface AuditorProgress {
 	/** Current tool being executed by the auditor, if any */
@@ -54,10 +48,6 @@ export interface GoalAuditorResult {
 
 const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh"]);
 
-export function goalAuditorConfigPath(cwd: string): string {
-	return path.join(cwd, ".pi", "goal-auditor.json");
-}
-
 function asNonEmptyString(value: unknown): string | undefined {
 	return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
@@ -67,59 +57,7 @@ function asThinkingLevel(value: unknown): ThinkingLevel | undefined {
 	return text && THINKING_LEVELS.has(text) ? text as ThinkingLevel : undefined;
 }
 
-export function parseGoalAuditorConfig(raw: unknown): GoalAuditorConfig {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-	const record = raw as Record<string, unknown>;
-	const config: GoalAuditorConfig = {};
-	const provider = asNonEmptyString(record.provider);
-	const model = asNonEmptyString(record.model);
-	const thinkingLevel = asThinkingLevel(record.thinkingLevel ?? record.thinking_level);
-	if (provider) config.provider = provider;
-	if (model) config.model = model;
-	if (thinkingLevel) config.thinkingLevel = thinkingLevel;
-	if (record.disabled === true || record.disabled === "true") config.disabled = true;
-	return config;
-}
-
-export function loadGoalAuditorFileConfig(cwd: string): GoalAuditorConfig {
-	try {
-		const configPath = goalAuditorConfigPath(cwd);
-		if (fs.existsSync(configPath)) return parseGoalAuditorConfig(JSON.parse(fs.readFileSync(configPath, "utf8")));
-	} catch {
-		return {};
-	}
-	return {};
-}
 
-export function loadGoalAuditorConfig(cwd: string, env: NodeJS.ProcessEnv = process.env): GoalAuditorConfig {
-	const fileConfig = loadGoalAuditorFileConfig(cwd);
-	return {
-		...fileConfig,
-		provider: asNonEmptyString(env.PI_GOAL_AUDITOR_PROVIDER) ?? fileConfig.provider,
-		model: asNonEmptyString(env.PI_GOAL_AUDITOR_MODEL) ?? fileConfig.model,
-		thinkingLevel: asThinkingLevel(env.PI_GOAL_AUDITOR_THINKING_LEVEL ?? env.PI_GOAL_AUDITOR_THINKING) ?? fileConfig.thinkingLevel,
-	};
-}
-
-export function saveGoalAuditorFileConfig(cwd: string, config: GoalAuditorConfig): GoalAuditorConfig {
-	const clean: GoalAuditorConfig = {};
-	const provider = asNonEmptyString(config.provider);
-	const model = asNonEmptyString(config.model);
-	const thinkingLevel = asThinkingLevel(config.thinkingLevel);
-	if (provider) clean.provider = provider;
-	if (model) clean.model = model;
-	if (thinkingLevel) clean.thinkingLevel = thinkingLevel;
-	if (config.disabled === true) clean.disabled = true;
-	const configPath = goalAuditorConfigPath(cwd);
-	fs.mkdirSync(path.dirname(configPath), { recursive: true });
-	const persisted: Record<string, unknown> = {};
-	if (clean.provider) persisted.provider = clean.provider;
-	if (clean.model) persisted.model = clean.model;
-	if (clean.thinkingLevel) persisted.thinking_level = clean.thinkingLevel;
-	if (clean.disabled) persisted.disabled = true;
-	fs.writeFileSync(configPath, `${JSON.stringify(persisted, null, 2)}\n`, "utf8");
-	return clean;
-}
 
 export function parseAuditorDecision(output: string): { approved: boolean; disapproved: boolean } {
 	const approved = /<approved\s*\/>/.test(output);
@@ -134,18 +72,43 @@ export interface AuditorVerificationEvidence {
 	contract?: string;
 }
 
+function renderAuditorTaskTree(tasks: GoalTask[], indent: number): string[] {
+	const prefix = "  ".repeat(indent);
+	const lines: string[] = [];
+	for (const task of tasks) {
+		const marker = task.status === "complete" ? "[x]" : task.status === "skipped" ? "[~]" : "[ ]";
+		lines.push(`${prefix}${marker} ${task.id}: ${task.title}`);
+		if (task.subtasks && task.subtasks.length > 0) {
+			lines.push(...renderAuditorTaskTree(task.subtasks, indent + 1));
+		}
+	}
+	return lines;
+}
+
+function countAuditorTasks(tasks: GoalTask[]): { total: number; complete: number; skipped: number; pending: number } {
+	let total = 0;
+	let complete = 0;
+	let skipped = 0;
+	for (const t of tasks) {
+		total++;
+		if (t.status === "complete") complete++;
+		else if (t.status === "skipped") skipped++;
+		if (t.subtasks && t.subtasks.length > 0) {
+			const child = countAuditorTasks(t.subtasks);
+			total += child.total;
+			complete += child.complete;
+			skipped += child.skipped;
+		}
+	}
+	return { total, complete, skipped, pending: total - complete - skipped };
+}
+
 function taskSummaryBlock(taskList?: GoalTaskList | null): string {
 	if (!taskList || taskList.tasks.length === 0) return "";
-	const total = taskList.tasks.length;
-	const complete = taskList.tasks.filter((t) => t.status === "complete").length;
-	const skipped = taskList.tasks.filter((t) => t.status === "skipped").length;
-	const pending = taskList.tasks.filter((t) => t.status === "pending");
+	const { total, complete, skipped, pending } = countAuditorTasks(taskList.tasks);
 	const lines: string[] = [`Tasks: ${complete}/${total} complete${skipped > 0 ? `, ${skipped} skipped` : ""}`];
-	for (const task of taskList.tasks) {
-		const marker = task.status === "complete" ? "[x]" : task.status === "skipped" ? "[~]" : "[ ]";
-		lines.push(`  ${marker} ${task.id}: ${task.title}`);
-	}
-	const gate = taskList.blockCompletion && pending.length > 0 ? " | TASK GATE: pending tasks block completion" : "";
+	lines.push(...renderAuditorTaskTree(taskList.tasks, 0));
+	const gate = taskList.blockCompletion && pending > 0 ? " | TASK GATE: pending tasks block completion" : "";
 	lines[0] = lines[0]! + gate;
 	return lines.join("\n");
 }
@@ -155,6 +118,7 @@ export function buildGoalAuditorPrompt(args: {
 	completionSummary?: string | null;
 	detailedSummary: string;
 	verificationSummary?: string | null;
+	settings?: GoalSettings;
 }): string {
 	return [
 		"You are the independent completion auditor for pi-goal.",
@@ -180,7 +144,7 @@ export function buildGoalAuditorPrompt(args: {
 		"Current goal metadata:",
 		"<goal_details>",
 		args.detailedSummary,
-		...(taskSummaryBlock(args.goal.taskList) ? ["", taskSummaryBlock(args.goal.taskList)] : []),
+		...(!args.settings?.disableTasks && taskSummaryBlock(args.goal.taskList) ? ["", taskSummaryBlock(args.goal.taskList)] : []),
 		"</goal_details>",
 		...(args.verificationSummary?.trim() ? [
 			"",
@@ -189,7 +153,7 @@ export function buildGoalAuditorPrompt(args: {
 			args.verificationSummary.trim(),
 			"</verification_summary>",
 		] : []),
-		...(args.goal.verificationContract?.trim() ? [
+		...(!args.settings?.disableContracts && args.goal.verificationContract?.trim() ? [
 			"",
 			"Goal verification contract (what the executor was required to verify):",
 			"<verification_contract>",
@@ -204,7 +168,7 @@ export function buildGoalAuditorPrompt(args: {
 			...(args.verificationSummary?.trim()
 				? ["3. Check the <verification_summary> against real artifacts. If the executor claims to have run tests or searched for references, verify those claims with actual file/shell evidence. The summary is a claim, not proof — cross-check it."]
 				: []),
-			...(args.goal.verificationContract?.trim()
+			...(!args.settings?.disableContracts && args.goal.verificationContract?.trim()
 				? ["4. Verify that the executor has satisfied every item in the <verification_contract>. If any item is missing or weakly addressed, disapprove."]
 				: []),
 			"5. Explain missing or weak evidence, especially scaffold-vs-final quality gaps.",
@@ -255,7 +219,7 @@ function makeAuditorResourceLoader(): ResourceLoader {
 	};
 }
 
-function resolveAuditorModel(ctx: ExtensionContext, config: GoalAuditorConfig): { model: Model<any> | undefined; error?: string } {
+function resolveAuditorModel(ctx: ExtensionContext, config: GoalSettings): { model: Model<any> | undefined; error?: string } {
 	if (!config.model && !config.provider) return { model: ctx.model };
 	if (config.provider && config.model) {
 		const model = ctx.modelRegistry.find(config.provider, config.model);
@@ -288,6 +252,7 @@ export async function runGoalCompletionAuditor(args: {
 	completionSummary?: string | null;
 	detailedSummary: string;
 	verificationSummary?: string | null;
+	settings?: GoalSettings;
 	signal?: AbortSignal;
 	onProgress?: AuditorProgressCallback;
 	/**
@@ -297,7 +262,7 @@ export async function runGoalCompletionAuditor(args: {
 	 */
 	createSession?: typeof createAgentSession;
 }): Promise<GoalAuditorResult> {
-	const config = loadGoalAuditorConfig(args.ctx.cwd);
+	const config = loadGoalSettings(args.ctx.cwd);
 	const resolved = resolveAuditorModel(args.ctx, config);
 	const model = resolved.model;
 	const thinkingLevel = config.thinkingLevel;

package/extensions/goal-policy.ts

@@ -1,5 +1,5 @@
 import { statusLabel, type GoalDisplayRecordLike } from "./goal-core.ts";
-import type { GoalTaskList, TaskStatus } from "./goal-record.ts";
+import type { GoalTask, GoalTaskList, TaskStatus } from "./goal-record.ts";
 
 export type GoalStatusLike = "active" | "paused" | "complete";
 export type StopReasonLike = "user" | "agent";
@@ -126,10 +126,27 @@ export function abortGoalCommandMessage(args: { archived: boolean; wasDrafting:
 	return args.archived ? "Goal aborted and archived." : args.wasDrafting ? "Drafting cancelled." : "No goal is set.";
 }
 
+/** Count tasks in subtree recursively */
+function countSubtreeTasks(tasks: GoalTask[]): { total: number; complete: number; skipped: number; pending: number } {
+	let total = 0;
+	let complete = 0;
+	let skipped = 0;
+	for (const t of tasks) {
+		total++;
+		if (t.status === "complete") complete++;
+		else if (t.status === "skipped") skipped++;
+		if (t.subtasks && t.subtasks.length > 0) {
+			const child = countSubtreeTasks(t.subtasks);
+			total += child.total;
+			complete += child.complete;
+			skipped += child.skipped;
+		}
+	}
+	return { total, complete, skipped, pending: total - complete - skipped };
+}
+
 export function buildTaskSummary(taskList: GoalTaskList): string {
-	const total = taskList.tasks.length;
-	const complete = taskList.tasks.filter((t) => t.status === "complete").length;
-	const skipped = taskList.tasks.filter((t) => t.status === "skipped").length;
+	const { total, complete, skipped } = countSubtreeTasks(taskList.tasks);
 	if (total === 0) return "No tasks";
 	const parts: string[] = [`${complete}/${total} tasks complete`];
 	if (skipped > 0) parts.push(`(${skipped} skipped)`);
@@ -138,9 +155,9 @@ export function buildTaskSummary(taskList: GoalTaskList): string {
 
 export function taskCompletionBlockWarning(taskList: GoalTaskList): string | null {
 	if (!taskList.blockCompletion) return null;
-	const pending = taskList.tasks.filter((t) => t.status === "pending");
-	if (pending.length === 0) return null;
-	return `${pending.length} task${pending.length > 1 ? "s" : ""} still pending with blockCompletion enabled. Complete or skip all pending tasks before finishing the goal.`;
+	const { pending } = countSubtreeTasks(taskList.tasks);
+	if (pending === 0) return null;
+	return `${pending} task${pending > 1 ? "s" : ""} still pending with blockCompletion enabled. Complete or skip all pending tasks before finishing the goal.`;
 }
 
 /**
@@ -190,9 +207,43 @@ export function validateTaskSkip(args: {
 	return { ok: true };
 }
 
+/**
+ * Count the maximum nesting depth of a task's subtask tree.
+ * Root level = 0. Returns the deepest nesting depth found.
+ */
+export function measureSubtaskDepth(task: GoalTask): number {
+	if (!task.subtasks || task.subtasks.length === 0) return 0;
+	let maxChild = 0;
+	for (const child of task.subtasks) {
+		const childDepth = measureSubtaskDepth(child);
+		if (childDepth > maxChild) maxChild = childDepth;
+	}
+	return maxChild + 1;
+}
+
+/**
+ * Validate that a task's subtask tree does not exceed the configured max depth.
+ * maxDepth is the subtaskDepth setting (default 1) — how many levels of nesting are allowed.
+ * Returns the first violation found, or undefined if valid.
+ */
+export function findSubtaskDepthViolation(tasks: GoalTask[], maxDepth: number): string | undefined {
+	for (const task of tasks) {
+		const depth = measureSubtaskDepth(task);
+		if (depth > maxDepth) {
+			return `Task "${task.id}" has subtask nesting depth ${depth}, exceeding the configured maximum of ${maxDepth}`;
+		}
+		if (task.subtasks) {
+			const childViolation = findSubtaskDepthViolation(task.subtasks, maxDepth);
+			if (childViolation) return childViolation;
+		}
+	}
+	return undefined;
+}
+
 export function validateTaskListProposal(args: {
 	goal: GoalPolicyRecordLike | null;
-	tasks: { id: string; title: string }[];
+	tasks: GoalTask[];
+	maxSubtaskDepth?: number;
 }): PolicyValidation {
 	if (!args.goal) return { ok: false, message: "No goal is set." };
 	if (args.tasks.length > 50) return { ok: false, message: "Task list cannot exceed 50 tasks." };
@@ -203,9 +254,78 @@ export function validateTaskListProposal(args: {
 		if (ids.has(t.id)) return { ok: false, message: `Duplicate task id: "${t.id}".` };
 		ids.add(t.id);
 	}
+	// Check subtask depth limit
+	const maxDepth = args.maxSubtaskDepth ?? 1;
+	const depthViolation = findSubtaskDepthViolation(args.tasks, maxDepth);
+	if (depthViolation) return { ok: false, message: depthViolation };
 	return { ok: true };
 }
 
+/**
+ * Recursively find a task by ID in a task tree.
+ */
+export function findTaskInTree(tasks: GoalTask[], taskId: string): GoalTask | undefined {
+	for (const t of tasks) {
+		if (t.id === taskId) return t;
+		if (t.subtasks) {
+			const found = findTaskInTree(t.subtasks, taskId);
+			if (found) return found;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Recursively update a task by ID in a task tree using an updater function.
+ */
+export function updateTaskInTree(tasks: GoalTask[], taskId: string, updater: (task: GoalTask) => GoalTask): GoalTask[] {
+	return tasks.map((t) => {
+		if (t.id === taskId) return updater(t);
+		if (t.subtasks) {
+			return { ...t, subtasks: updateTaskInTree(t.subtasks, taskId, updater) };
+		}
+		return t;
+	});
+}
+
+/**
+ * Check if all subtasks of a task are complete (for full subtasks only).
+ * Returns undefined when all are complete/skipped, or an error message.
+ */
+export function checkSubtasksComplete(task: GoalTask): string | undefined {
+	if (!task.subtasks || task.subtasks.length === 0 || task.lightweightSubtasks) return undefined;
+	for (const child of task.subtasks) {
+		if (child.status === "pending") {
+			return `Task "${task.id}" has pending subtask "${child.id}". Complete or skip all subtasks first.`;
+		}
+		// Check recursively
+		const childCheck = checkSubtasksComplete(child);
+		if (childCheck) return childCheck;
+	}
+	return undefined;
+}
+
+/**
+ * Recursively skip all subtasks of a task.
+ * Returns a set of all skipped task IDs.
+ */
+export function skipAllSubtasks(task: GoalTask, now: string, reason: string): GoalTask {
+	if (!task.subtasks || task.subtasks.length === 0) return task;
+	return {
+		...task,
+		subtasks: task.subtasks.map((child) => {
+			if (child.status === "complete") return child;
+			const skipped = {
+				...child,
+				status: "skipped" as const,
+				skippedAt: now,
+				skipReason: reason,
+			};
+			return skipAllSubtasks(skipped, now, reason);
+		}),
+	};
+}
+
 export function buildCompletionReport(args: { detailedSummary: string; completionSummary?: string | null; auditorReport?: string | null; auditSkippedReason?: string | null; taskSummary?: string | null }): string {
 	const auditSkipped = args.auditSkippedReason?.trim();
 	const auditorReport = args.auditorReport?.trim();

package/extensions/goal-questionnaire.ts

@@ -92,6 +92,11 @@ export async function runGoalQuestionnaire(ctx: ExtensionContext, rawQuestions:
 	const totalTabs = questions.length + 1;
 
 	return await ctx.ui.custom<GoalQuestionnaireResult>((tui, theme, _kb, done) => {
+		// Suppress hardware cursor during dialog to reduce TUI auto-scroll
+		// (the TUI render loop runs at ~60fps and writes ANSI cursor positioning
+		// sequences every cycle, which can cause terminal viewport snapping).
+		const wasHardwareCursorShown = tui.getShowHardwareCursor();
+		tui.setShowHardwareCursor(false);
 		let currentTab = 0;
 		let optionIndex = 0;
 		let inputMode = false;
@@ -118,6 +123,8 @@ export async function runGoalQuestionnaire(ctx: ExtensionContext, rawQuestions:
 		}
 
 		function submit(cancelled: boolean) {
+			// Restore hardware cursor now that the dialog is closing
+			tui.setShowHardwareCursor(wasHardwareCursorShown);
 			const ordered = questions.map((q) => answers.get(q.id)).filter((a): a is GoalQuestionnaireAnswer => !!a);
 			done({ questions, answers: ordered, cancelled });
 		}

package/extensions/goal-record.ts

@@ -15,6 +15,8 @@ export interface GoalTask {
   evidence?: string;
   skipReason?: string;
   verificationContract?: string;
+  lightweightSubtasks?: boolean;
+  subtasks?: GoalTask[];
 }
 
 export interface GoalTaskList {
@@ -111,12 +113,19 @@ export function emptyUsage(): GoalUsage {
 	return { tokensUsed: 0, activeSeconds: 0 };
 }
 
+function cloneGoalTask(task: GoalTask): GoalTask {
+	return {
+		...task,
+		subtasks: task.subtasks ? task.subtasks.map(cloneGoalTask) : undefined,
+	};
+}
+
 export function cloneGoal(goal: GoalRecord): GoalRecord {
 	return {
 		...goal,
 		usage: { ...goal.usage },
 		taskList: goal.taskList
-			? { ...goal.taskList, tasks: goal.taskList.tasks.map(t => ({ ...t })) }
+			? { ...goal.taskList, tasks: goal.taskList.tasks.map(cloneGoalTask) }
 			: undefined,
 	};
 }
@@ -164,30 +173,41 @@ export function normalizeUsage(value: unknown): GoalUsage {
 	return { tokensUsed, activeSeconds };
 }
 
+export function normalizeTaskItem(raw: Record<string, unknown>): GoalTask | undefined {
+	const id = typeof raw.id === "string" && raw.id.trim() ? raw.id.trim() : "";
+	const title = typeof raw.title === "string" ? raw.title.trim() : "";
+	if (!id || !title) return undefined;
+	const status: TaskStatus = raw.status === "complete" ? "complete" : raw.status === "skipped" ? "skipped" : "pending";
+	const subtasksRaw = raw.subtasks;
+	let subtasks: GoalTask[] | undefined;
+	if (Array.isArray(subtasksRaw)) {
+		subtasks = subtasksRaw
+			.map((item) => (item && typeof item === "object" ? normalizeTaskItem(item as Record<string, unknown>) : undefined))
+			.filter((t): t is GoalTask => !!t);
+		if (subtasks.length === 0) subtasks = undefined;
+	}
+	return {
+		id,
+		title,
+		status,
+		completedAt: typeof raw.completedAt === "string" ? raw.completedAt : undefined,
+		skippedAt: typeof raw.skippedAt === "string" ? raw.skippedAt : undefined,
+		evidence: typeof raw.evidence === "string" ? raw.evidence : undefined,
+		skipReason: typeof raw.skipReason === "string" ? raw.skipReason : undefined,
+		verificationContract: typeof raw.verificationContract === "string" ? raw.verificationContract : undefined,
+		lightweightSubtasks: raw.lightweightSubtasks === true ? true : undefined,
+		subtasks,
+	};
+}
+
 export function normalizeTaskList(value: unknown): GoalTaskList | undefined {
 	const raw = asRecord(value);
 	if (!raw) return undefined;
 	const tasksRaw = raw.tasks;
 	if (!Array.isArray(tasksRaw)) return undefined;
-	const tasks: GoalTask[] = [];
-	for (const item of tasksRaw) {
-		if (!item || typeof item !== "object" || Array.isArray(item)) continue;
-		const t = item as Record<string, unknown>;
-		const id = typeof t.id === "string" && t.id.trim() ? t.id.trim() : "";
-		const title = typeof t.title === "string" ? t.title.trim() : "";
-		if (!id || !title) continue;
-		const status: TaskStatus = t.status === "complete" ? "complete" : t.status === "skipped" ? "skipped" : "pending";
-		tasks.push({
-			id,
-			title,
-			status,
-			completedAt: typeof t.completedAt === "string" ? t.completedAt : undefined,
-			skippedAt: typeof t.skippedAt === "string" ? t.skippedAt : undefined,
-			evidence: typeof t.evidence === "string" ? t.evidence : undefined,
-			skipReason: typeof t.skipReason === "string" ? t.skipReason : undefined,
-			verificationContract: typeof t.verificationContract === "string" ? t.verificationContract : undefined,
-		});
-	}
+	const tasks: GoalTask[] = tasksRaw
+		.map((item) => (item && typeof item !== "object" || Array.isArray(item) ? undefined : normalizeTaskItem(item as Record<string, unknown>)))
+		.filter((t): t is GoalTask => !!t);
 	if (tasks.length === 0) return undefined;
 	return {
 		tasks,