pi-goal-x 0.12.0 → 0.14.0

package/README.md

@@ -10,10 +10,28 @@ The extension is designed around one rule: **the user owns intent; the agent exe
 
 All core features of [@capyup/pi-goal](https://github.com/capyup/pi-goal) are preserved. The following changes are specific to pi-goal-x:
 
-### Task list system
+### Verification contract system
 
-- **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.
+- **Per-goal verification contracts** — when drafting a goal, include a `Verification contract:` section with plain-text requirements (e.g. "Run npm test (0 failures), grep for remaining STP references"). The contract is extracted, stored on the goal record, and enforced by the `complete_goal` tool — the call is rejected unless the agent provides a non-empty `verificationSummary` matching the contract.
+- **Per-task verification contracts** — `propose_task_list` supports an optional `verificationContract` per task. If set, `complete_task` requires a non-empty `verificationSummary`.
+- **Both prompt and tool enforcement** — prompts include a VERIFICATION CONTRACT section instructing the agent; tool validators reject calls that violate the contract.
+- **Backward compatible** — goals/tasks without a `Verification contract:` section work exactly as before. No contract = no enforcement.
+- **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.
+
+### Unified goal + task acceptance
+
+- **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).
 
@@ -30,7 +48,7 @@ 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**: 193 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), and task list policy/round-trip/render tests (50+).
+- **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
 
@@ -165,11 +183,11 @@ The extension exposes tools only when they make sense for the current lifecycle
 | `get_goal` | always | Read the focused goal state; mentions other open goals when present |
 | `propose_goal_draft` | drafting only (goal creation) | Submit a concrete draft for user confirmation |
 | `propose_goal_tweak` | tweak drafting only | Submit a revision to an existing goal (shows Confirm / Continue Chatting dialog) |
-| `complete_goal` | focused active or paused goal | Mark the focused goal complete — only when every requirement is satisfied. When the auditor is disabled, supply `confirmBypassAuditor: true` after user confirmation to bypass the audit |
+| `complete_goal` | focused active or paused goal | Mark the focused goal complete — supply a `verificationSummary` covering all contract items. When the auditor is disabled, supply `confirmBypassAuditor: true` after user confirmation to bypass the audit |
 | `pause_goal` | focused active goal | Pause the focused goal because of a real blocker |
 | `abort_goal` | focused active or paused goal | Abort/archive an obsolete, impossible, unsafe, or user-cancelled focused goal |
 | `propose_task_list` | active or paused goal | Propose a structured task list for user confirmation (stops the turn) |
-| `complete_task` | active or paused goal | Mark a task complete with optional evidence (does not stop turn) |
+| `complete_task` | active or paused goal | Mark a task complete with optional `verificationSummary`. If the task has a `verificationContract`, the summary is required (does not stop turn) |
 | `skip_task` | active or paused goal | Mark a task skipped with a required reason (does not stop turn) |
 | `propose_goal_tweak` | tweak drafting only | Submit a revision to the focused goal (shows Confirm / Continue Chatting dialog) |
 | `step_complete` | hidden / legacy | Compatibility no-op; Sisyphus no longer requires a step counter |
@@ -205,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/goal-auditor.json`, interactively with `/goal-settings` → `auditor`, or environment variables (see [Settings files](#settings-files)).
 
 The completion result prints a full report into the conversation:
 
@@ -263,6 +271,52 @@ 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.
 
+## Settings files
+
+Configuration is split across two files under `.pi/`.
+
+### `.pi/goal-settings.json`
+
+Configured interactively via `/goal-settings`, or edited directly:
+
+```json
+{
+  "disableTasks": false,
+  "disableContracts": false,
+  "subtaskDepth": 1
+}
+```
+
+| 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 (`1` = tasks → subtasks, `2` = tasks → subtasks → sub-subtasks) |
+
+**Env var overrides:** `PI_GOAL_DISABLE_TASKS=1` and `PI_GOAL_DISABLE_CONTRACTS=1` take precedence over the file. Set to any truthy string to disable.
+
+### `.pi/goal-auditor.json`
+
+Configured interactively via `/goal-settings` → `auditor`, or edited directly:
+
+```json
+{
+  "provider": "fireworks",
+  "model": "accounts/fireworks/models/deepseek-v4-flash",
+  "thinkingLevel": "high",
+  "disabled": false
+}
+```
+
+| Field | Default | Purpose |
+|---|---:|---|
+| `provider` | system default | Provider name for the auditor agent (`anthropic`, `fireworks`, `google`, `groq`, etc.) |
+| `model` | system default | Model name for the auditor agent |
+| `thinkingLevel` | system default | Thinking level: `none`, `low`, `medium`, `high` |
+| `disabled` | `false` | When `true`, skip the completion audit entirely |
+
+**Env var overrides:** `PI_GOAL_AUDITOR_PROVIDER`, `PI_GOAL_AUDITOR_MODEL`, and `PI_GOAL_AUDITOR_THINKING_LEVEL` take precedence over file config. `PI_GOAL_AUDITOR_THINKING` is also accepted as an alias for the thinking level.
+
 ## Environment variables
 
 | Variable | Default | Purpose |

package/extensions/goal-auditor.ts

@@ -13,7 +13,8 @@ import {
 	type ExtensionContext,
 	type ResourceLoader,
 } from "@earendil-works/pi-coding-agent";
-import type { GoalRecord, GoalTaskList } from "./goal-record.ts";
+import type { GoalRecord, GoalTask, GoalTaskList } from "./goal-record.ts";
+import type { GoalSettings } from "./goal-settings.ts";
 
 export interface GoalAuditorConfig {
 	provider?: string;
@@ -127,29 +128,50 @@ export function parseAuditorDecision(output: string): { approved: boolean; disap
 	return { approved: approved && !disapproved, disapproved };
 }
 
-export interface AuditorTestResults {
-	/** Exit code of the test run (0 = success) */
-	exitCode: number;
-	/** Test suite name, e.g. 'npm test' */
-	suiteName?: string;
-	/** Last lines of test output showing results */
-	output?: string;
-	/** ISO timestamp of when tests were run */
-	timestamp?: string;
+export interface AuditorVerificationEvidence {
+	/** The agent's verification summary describing what was checked. */
+	summary: string;
+	/** The goal's verification contract (what the agent was required to verify), if any. */
+	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");
 }
@@ -158,7 +180,8 @@ export function buildGoalAuditorPrompt(args: {
 	goal: GoalRecord;
 	completionSummary?: string | null;
 	detailedSummary: string;
-	testResults?: AuditorTestResults | null;
+	verificationSummary?: string | null;
+	settings?: GoalSettings;
 }): string {
 	return [
 		"You are the independent completion auditor for pi-goal.",
@@ -184,33 +207,36 @@ 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.testResults ? [
+		...(args.verificationSummary?.trim() ? [
 			"",
-			"Executor test evidence:",
-			"<test_evidence>",
-			`  Suite: ${args.testResults.suiteName ?? "(not specified)"}`,
-			`  Exit code: ${args.testResults.exitCode}`,
-			`  Timestamp: ${args.testResults.timestamp ?? "(not specified)"}`,
-			`  Output:`,
-			...(args.testResults.output ? args.testResults.output.split("\n").map((l) => `    ${l}`) : ["    (none provided)"]),
-			"</test_evidence>",
+			"Executor verification summary:",
+			"<verification_summary>",
+			args.verificationSummary.trim(),
+			"</verification_summary>",
+		] : []),
+		...(!args.settings?.disableContracts && args.goal.verificationContract?.trim() ? [
+			"",
+			"Goal verification contract (what the executor was required to verify):",
+			"<verification_contract>",
+			args.goal.verificationContract.trim(),
+			"</verification_contract>",
 		] : []),
 		"",
 		"Audit checklist:",
-		...(args.testResults ? [
-			"1. Extract the real success criteria from the objective, including quality/reader outcomes.",
-			"2. Inspect artifacts or command output that can prove or disprove those criteria.",
-			"3. Before running a test suite with bash, check the <test_evidence> block. If the executor has provided recent passing test results for that suite, accept them as evidence rather than re-running the tests.",
-			"4. Explain missing or weak evidence, especially scaffold-vs-final quality gaps.",
-			"5. End with exactly <approved/> only if the objective is truly complete; otherwise end with exactly <disapproved/>.",
-		] : [
+		...[
 			"1. Extract the real success criteria from the objective, including quality/reader outcomes.",
 			"2. Inspect artifacts or command output that can prove or disprove those criteria.",
-			"3. Explain missing or weak evidence, especially scaffold-vs-final quality gaps.",
-			"4. End with exactly <approved/> only if the objective is truly complete; otherwise end with exactly <disapproved/>.",
-		]),
+			...(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.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.",
+			"6. End with exactly <approved/> only if the objective is truly complete; otherwise end with exactly <disapproved/>.",
+		],
 		"",
 		"Progress reporting:",
 		"You have the report_auditor_progress tool available to report your progress to the user.",
@@ -288,7 +314,8 @@ export async function runGoalCompletionAuditor(args: {
 	goal: GoalRecord;
 	completionSummary?: string | null;
 	detailedSummary: string;
-	testResults?: AuditorTestResults | null;
+	verificationSummary?: string | null;
+	settings?: GoalSettings;
 	signal?: AbortSignal;
 	onProgress?: AuditorProgressCallback;
 	/**

package/extensions/goal-draft.ts

@@ -26,6 +26,57 @@ export function promptSafeObjective(objective: string): string {
 	return objective.replace(/<\/?untrusted_objective>/gi, (tag) => tag.replace(/</g, "&lt;").replace(/>/g, "&gt;"));
 }
 
+const VERIFICATION_CONTRACT_RE = /^Verification contract:\s*(.+)$/im;
+
+const CONVENTIONAL_SECTION_NAMES = [
+	"success criteria",
+	"boundaries",
+	"constraints",
+	"if blocked",
+	"if blocked / unclear / failing",
+	"don'ts",
+	"sisyphus reminder",
+	"objective",
+	"目标",
+	"ordered steps",
+	"order rules",
+	"steps",
+];
+
+/**
+ * Extract a `Verification contract:` section from a goal objective and return
+ * the cleaned objective (without the contract section) and the contract text.
+ *
+ * The contract section is a single line matching:
+ *   Verification contract: <text>
+ *
+ * It can appear anywhere in the objective, but by convention it goes after
+ * the other sections (like Success criteria, Boundaries, Constraints).
+ *
+ * If no contract section is found, `verificationContract` is undefined.
+ */
+export function extractVerificationContract(objective: string): { objective: string; verificationContract?: string } {
+	const lines = objective.replace(/\r/g, "").split("\n");
+	let contract: string | undefined;
+	const filtered: string[] = [];
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		const m = VERIFICATION_CONTRACT_RE.exec(trimmed);
+		if (m) {
+			contract = m[1].trim();
+			// Skip this line — don't add it to the cleaned objective
+		} else {
+			filtered.push(line);
+		}
+	}
+
+	return {
+		objective: filtered.join("\n"),
+		verificationContract: contract || undefined,
+	};
+}
+
 export function buildDraftConfirmationText(args: {
 	focus: GoalDraftingFocus;
 	originalTopic: string;
@@ -143,6 +194,7 @@ export function goalDraftingPrompt(topic: string, focus: GoalDraftingFocus): str
 		"Success criteria: <observable evidence the goal is done>",
 		"Boundaries: <in scope / out of scope>",
 		"Constraints: <hard rules>",
+		"Verification contract: <optional — what verification evidence is required before marking complete, e.g. 'Run npm test (0 failures), grep for remaining references, re-read requirements and confirm every item is addressed'>",
 		"If blocked: <default = stop and ask the user>",
 		"Call propose_goal_draft with sisyphus=false and autoContinue=true unless the user asked otherwise.",
 	];
@@ -155,6 +207,7 @@ export function goalDraftingPrompt(topic: string, focus: GoalDraftingFocus): str
 		"Success criteria: <observable evidence the whole ordered goal is done>",
 		"Boundaries: <in scope / out of scope>",
 		"Constraints: <hard rules, files not to touch, etc.>",
+		"Verification contract: <optional — what verification evidence is required before marking complete>",
 		"Ordered steps: <preserve the user's requested steps and ordering; do not add preflight or reconnaissance steps they did not ask for>",
 		"If blocked / unclear / failing: <default = stop and ask the user>",
 		"Sisyphus reminder: Work patiently and sequentially. No rushing, no unrequested preflight steps, no improvising around blockers.",

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,28 @@ 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.`;
+}
+
+/**
+ * Validate that a verificationSummary satisfies a verificationContract.
+ * If a contract exists, the summary must be non-empty.
+ */
+export function validateVerificationSummary(args: {
+	verificationContract?: string | null;
+	verificationSummary?: string | null;
+}): PolicyValidation {
+	const contract = args.verificationContract?.trim();
+	const summary = args.verificationSummary?.trim();
+	if (contract && !summary) {
+		return {
+			ok: false,
+			message: `This goal has a verification contract but no verificationSummary was provided. Provide a verificationSummary that addresses the contract requirements.`,
+		};
+	}
+	return { ok: true };
 }
 
 export function validateTaskCompletion(args: {
@@ -171,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." };
@@ -184,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 });
 		}