@gavin-hu/my-pi-agent 0.11.3 → 0.12.0

package/extensions/file-open/open.ts

@@ -5,7 +5,7 @@
  * runs is asserted without a process. `openTarget` takes an injectable spawn so
  * a test launches nothing. Opening is best-effort: the caller decides what to do
  * with a failure, which is reported through `onError` rather than thrown, since
- * `spawn` reports a missing handler asynchronously.
+ * the launcher reports a start failure and a non-zero exit asynchronously.
  */
 
 import { spawn } from "node:child_process";
@@ -19,6 +19,11 @@ export type OpenMode = "open" | "reveal";
 export interface NativeCommand {
 	command: string;
 	args: string[];
+	/**
+	 * Whether a non-zero exit means the target was not opened. Windows
+	 * `explorer` can exit non-zero after a successful open, so it opts out.
+	 */
+	exitMeansFailure: boolean;
 }
 
 /**
@@ -51,49 +56,75 @@ export function buildCommand(
 	platform: NodeJS.Platform = process.platform,
 ): NativeCommand {
 	if (platform === "darwin") {
-		return mode === "reveal" ? { command: "open", args: ["-R", target] } : { command: "open", args: [target] };
+		return mode === "reveal"
+			? { command: "open", args: ["-R", target], exitMeansFailure: true }
+			: { command: "open", args: [target], exitMeansFailure: true };
 	}
 	if (platform === "win32") {
+		// `explorer` opens with the default handler without routing the path
+		// through cmd, which would expand `%NAME%` inside it.
 		return mode === "reveal"
-			? { command: "explorer", args: [`/select,${target}`] }
-			: { command: "cmd", args: ["/c", "start", "", target] };
+			? { command: "explorer", args: [`/select,${target}`], exitMeansFailure: false }
+			: { command: "explorer", args: [target], exitMeansFailure: false };
 	}
 	// Linux et al. xdg-open has no "select" verb, so reveal opens the parent.
-	return { command: "xdg-open", args: [mode === "reveal" ? dirname(target) : target] };
+	return {
+		command: "xdg-open",
+		args: [mode === "reveal" ? dirname(target) : target],
+		exitMeansFailure: true,
+	};
+}
+
+/** The child surface `openTarget` listens on; an injected launcher may return none. */
+export interface LauncherChild {
+	on(event: "error", listener: (error: Error) => void): unknown;
+	on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
 }
 
 /** A launcher seam; the default spawns the command detached. */
-export type SpawnFn = (command: string, args: string[]) => unknown;
+export type SpawnFn = (command: string, args: string[]) => LauncherChild | undefined;
 
 export interface OpenTargetOptions {
 	/** Platform to build the command for; defaults to the running one. */
 	platform?: NodeJS.Platform;
 	/** Override the launcher (tests). */
 	spawn?: SpawnFn;
-	/** Called when the handler cannot be started or reports an error. */
+	/** Called once when the handler cannot start, or exits non-zero where that is meaningful. */
 	onError?: (error: Error) => void;
 }
 
+/** Spawn the handler detached so the application outlives the session. */
+const spawnDetached: SpawnFn = (command, args) => {
+	const child = spawn(command, args, { detached: true, stdio: "ignore" });
+	child.unref();
+	return child;
+};
+
 /** Start the native handler for `target`, detached so it outlives the session. */
 export function openTarget(mode: OpenMode, target: string, options: OpenTargetOptions = {}): void {
-	const { command, args } = buildCommand(mode, target, options.platform);
-	const onError = options.onError;
+	const { command, args, exitMeansFailure } = buildCommand(mode, target, options.platform);
+	const launch = options.spawn ?? spawnDetached;
 
-	if (options.spawn) {
-		try {
-			options.spawn(command, args);
-		} catch (error) {
-			onError?.(toError(error));
-		}
-		return;
-	}
+	// A start failure and an exit both arrive asynchronously; report at most
+	// one, since both can fire for the same launch.
+	let reported = false;
+	const report = (error: Error): void => {
+		if (reported) return;
+		reported = true;
+		options.onError?.(error);
+	};
 
 	try {
-		const child = spawn(command, args, { detached: true, stdio: "ignore" });
-		child.on("error", (error) => onError?.(error));
-		child.unref();
+		const child = launch(command, args);
+		child?.on("error", report);
+		if (child && exitMeansFailure) {
+			child.on("exit", (code, signal) => {
+				if (signal) report(new Error(`the OS handler was stopped by ${signal}`));
+				else if (code !== 0) report(new Error(`the OS handler exited with status ${code}`));
+			});
+		}
 	} catch (error) {
-		onError?.(toError(error));
+		report(toError(error));
 	}
 }
 

package/extensions/goal/README.md

@@ -21,7 +21,11 @@ How the `goal` call and its result look in the transcript — the call line as a
   objective. Send the complete objective every call; an empty objective clears
   it.
 - Tracks `status`: `active` while the goal is being pursued, `achieved` when it
-  is done.
+  is done. Achieving it while the branch's todo list still has open items names
+  the count in the result (`1 todo item is still open…`), so the model closes the
+  *how* instead of declaring the *what* done over an unfinished list. The count
+  is read from the branch through `lib/todo-state.ts`; the structured result is
+  unchanged.
 - Shows a persistent one-line rail above the editor whenever a goal exists,
   label-first to match the [`todo`](../todo/) widget, pinned at the top of the
   `Goal / Todos` stack when both are loaded:
@@ -44,8 +48,9 @@ How the `goal` call and its result look in the transcript — the call line as a
 - Understands the goal before recording it: `/goal <prompt>` asks the session
   model to restate the goal as it understands it and, when it cannot yet, to ask
   up to three questions — which the command asks directly through host dialogs
-  (`select` / `input`). The model then folds the answers into the final
-  restatement, and the user confirms or corrects it in the editor. `/goal set
+  (`select` / `input`). The answers are carried into the editor under the
+  restatement as `Also: <question> → <answer>` notes, and the user confirms,
+  folds them in, or corrects the goal there. `/goal set
   <prompt>` reuses the loop but records without starting a turn, `/goal edit`
   changes the current goal in place, and `/goal raw <prompt>` records the typed
   words verbatim. The loop is best-effort and needs a dialog UI plus a model; the
@@ -79,6 +84,13 @@ line: control characters (including `ESC`) become spaces and any whitespace run
 (newlines, tabs, repeated spaces) collapses to one space. This keeps the widget
 to one logical line and stops model text from injecting terminal sequences.
 
+A successful `status: "achieved"` call also appends one line to the model-facing
+text when the branch's todo list still has open items — `3 todo items are still
+open; close or clear the list if that work is done.` The list is replayed from
+the branch, so the note appears whether the todos were written by the model, by
+`/todos`, or by an approved plan. It is text only: `details`,
+`structuredContent`, and the transcript header are unaffected.
+
 `goal` is allowlisted in `plan-mode` (alongside `todo`), so the model can record
 or update the objective during read-only exploration without leaving plan mode.
 
@@ -90,9 +102,9 @@ entry; `reconstructGoal` replays both entry kinds in branch order.
 | Command | What it does |
 |---|---|
 | `/goal` | Show the current goal, or the command usage when none is set. |
-| `/goal <prompt>` | Run the understanding loop — restate, ask any questions the model needs, re-comprehend, then confirm/edit — and start the run. Replacing a live goal is confirmed first. |
+| `/goal <prompt>` | Run the understanding loop — restate, ask any questions the model needs, then confirm/edit in the editor, which carries the answers as notes — and start the run. Replacing a live goal is confirmed first. |
 | `/goal raw <prompt>` | Skip the loop: record the typed words verbatim and start the run. |
-| `/goal set <prompt>` (or `/goal edit <prompt>`) | The same loop, but record the goal without starting a run. |
+| `/goal set <prompt>` (or `/goal edit <prompt>`) | The same loop, but record the goal without starting a run. An explicit `set`/`edit <text>` replaces an active goal without asking, since the command already says so. |
 | `/goal set` (or `/goal edit`) | Open the editor prefilled with the current goal and save it as the active goal, without starting a run. |
 | `/goal done` (or `/goal achieved`) | Mark the current goal achieved (idempotent). |
 | `/goal clear` | Clear the goal. |
@@ -113,7 +125,7 @@ without one they show the usage instead. `/goal raw` never needs one.
 
 The tool works in every mode. The persistent widget requires interactive
 (`tui`) mode; the reminder and the `/goal` command work everywhere. The
-`/goal <prompt>` runs the loop: each model call uses a cancellable `tui` spinner
+`/goal <prompt>` runs the loop: its model call uses a cancellable `tui` spinner
 in interactive mode and runs directly in RPC; the questions and the confirm step
 are host dialogs, forwarded by RPC. In print and JSON mode the loop is skipped
 and the typed text is sent. The widget is always a single line; the transcript
@@ -166,8 +178,8 @@ depends on config.
 | State storage | tool-result `details` plus a `pi.appendEntry("goal", { goal })` custom entry for command-set goals |
 | Lifecycle hooks | `session_start` (load config, reconstruct), `session_tree` (reconstruct), `session_shutdown` (clear widget); `before_agent_start` (inject `goal-context`), `context` (filter stale/duplicate reminders) |
 | UI | `ctx.ui.setWidget` one-line rail in `tui` mode; coordinated through `pi.events` so it stays the top rail |
-| Model calls | Up to two `ctx.modelRegistry.complete` calls on the session model (comprehend, then re-comprehend), each with a 30 s timeout and `cacheRetention: "none"`; skipped without a dialog UI or a model; their usage is not counted in session totals |
-| Questions | When the goal is not yet understood, the command asks the model's questions through `ctx.ui.select` / `ctx.ui.input` and passes the answers to the re-comprehension call. No cross-extension tool is used. |
+| Model calls | One `ctx.modelRegistry.complete` call on the session model with a 30 s timeout and `cacheRetention: "none"`; skipped without a dialog UI or a model; its usage is not counted in session totals |
+| Questions | When the goal is not yet understood, the command asks the model's questions through `ctx.ui.select` / `ctx.ui.input` and carries the answers into the editor prefill. No cross-extension tool is used. |
 
 ## Design notes
 
@@ -181,8 +193,10 @@ depends on config.
   user-driven path: one comprehension call (`clarify-prompt.ts` + `clarify.ts`)
   returns `{ understood, goal, questions }`. An understood goal opens a prefilled
   `ctx.ui.editor`, then `pi.sendUserMessage` sets and runs it. A not-understood
-  goal has its questions asked through host dialogs and its answers folded into
-  the goal by a second model call, then confirmed in the editor. `/goal set`
+  goal has its questions asked through host dialogs, and its answers ride into
+  the editor as `Also:` notes under the restatement: no second model call
+  rewrites the goal, so the user is the one who folds them into the sentence.
+  `/goal set`
   reuses the loop but skips the send; a bare `/goal set` or `/goal edit` opens
   the editor prefilled with the current goal; and `/goal raw` skips the loop
   entirely. The loop is best-effort (a failure keeps the typed text) and a
@@ -214,6 +228,18 @@ depends on config.
   the status header alone (`Goal · active`), because the call line above it
   already carries the objective; it does not restate it. `achieved: "show"`
   restores the dimmed widget line; config only affects presentation.
+- **Completing the *what* checks the *how*.** Marking a goal achieved while the
+  todo list still holds open items appends one line to the model-facing result
+  naming the count. The list is replayed from the branch by
+  `lib/todo-state.ts` (shared with plan's approval-time merge, which reads the
+  same channel), never by importing the `todo` extension. Only the text is
+  affected: `details` and `structuredContent` stay the goal alone, and the
+  transcript result is still the status header.
+- **One verb table.** `GOAL_VERBS` is the only list of reserved words: the
+  parser looks a first word up in it, the completions are generated from it, and
+  a test asserts every word is offered as a completion and named in `GOAL_HELP`.
+  Adding a verb without documenting or completing it fails that test instead of
+  drifting silently.
 - **Sanitize at the boundary.** `normalizeGoal` and `parseClarification` both route
   model text through `lib/format.ts`'s `sanitizeLine`, so an embedded newline
   cannot corrupt the widget and raw escapes cannot restyle the terminal.
@@ -225,16 +251,16 @@ depends on config.
 | `index.ts` | Factory: wire the runtime, tool, command, reminder, and session events. |
 | `types.ts` | `Goal`, `GoalStatus`, `GoalDetails`. |
 | `schema.ts` | TypeBox parameters and pure validation/normalization. |
-| `clarify-prompt.ts` | Comprehension and re-comprehension prompts plus their message builders (pure). |
+| `clarify-prompt.ts` | The comprehension prompt and its message builder (pure). |
 | `clarify-parse.ts` | Parse the `{ understood, goal, questions }` reply (and the plain-text fallback), normalize questions, and expose the limits (pure). |
-| `clarify.ts` | The two model calls, their cancellable loaders, the in-command questionnaire, and the confirm/edit dialog (host). |
+| `clarify.ts` | The model call, its cancellable loader, the in-command questionnaire, and the confirm/edit dialog (host). |
 | `state.ts` | Branch reconstruction (pure). |
 | `format.ts` | Model-facing and terminal text plus the header and rail vocabulary (pure). |
 | `config.ts` | Widget config load/validation (the `goal` section of `bytefly.json`). |
 | `tui.ts` | The persistent goal widget and the transcript status header. |
 | `runtime.ts` | Session-scoped state and widget synchronization. |
 | `tools.ts` | `goal` tool registration and rendering. |
-| `commands.ts` | `/goal`. |
+| `commands.ts` | `/goal`: the `GOAL_VERBS` table, the argument parser, the completions, and the command handler. |
 
 ## Testing
 

package/extensions/goal/clarify-prompt.ts

@@ -1,15 +1,14 @@
 /**
  * Prompt text for the goal comprehension step (pure).
  *
- * Both system prompts are sent only on the nested clarifier calls, so they are
- * not part of Pi's always-on prompt budget. The model's job is to understand and
- * restate the user's goal — not to improve it — and, when it cannot yet, to ask
- * only what it needs from the user. The second call folds the answers into the
- * final restatement.
+ * Sent only on the nested clarifier call, so it is not part of Pi's always-on
+ * prompt budget. The model's job is to understand and restate the user's goal —
+ * not to improve it — and, when it cannot yet, to ask only what it needs from
+ * the user.
  */
 
 import type { UserMessage } from "@earendil-works/pi-ai";
-import { MAX_QUESTIONS, type ClarifyAnswer } from "./clarify-parse.ts";
+import { MAX_QUESTIONS } from "./clarify-parse.ts";
 
 /** The comprehension system prompt: understand the goal, ask only what is missing. */
 export const CLARIFY_SYSTEM_PROMPT = `You are establishing a shared understanding of the user's goal for this session.
@@ -33,12 +32,6 @@ Rules:
 - Ask only what only the user can answer: purpose, scope, preference, or priority. Never ask for a fact the work itself would reveal, and never ask the user to restate the goal.
 - Give a question 2-4 concrete options when the answers are a small known set, or no options at all when free-form.`;
 
-/** The re-comprehension system prompt: fold the answers into one goal statement. */
-export const REFINE_SYSTEM_PROMPT = `The user has answered questions about their goal. Restate the goal as you now understand it.
-
-Reply with ONLY the goal as one sentence, no prose and no code fence.
-Use their answers and the original request; add nothing they did not state.`;
-
 /** The user message sent to the clarifier alongside {@link CLARIFY_SYSTEM_PROMPT}. */
 export function buildClarifyUserText(text: string): string {
 	return `Understand this session goal:\n\n${text}`;
@@ -54,27 +47,3 @@ export function buildClarifyMessages(
 		messages: [{ role: "user", content: [{ type: "text", text: buildClarifyUserText(text) }], timestamp: now }],
 	};
 }
-
-/** The user message that carries the original request, the first restatement, and the answers. */
-export function buildRefineUserText(original: string, goal: string, answers: readonly ClarifyAnswer[]): string {
-	const lines = [`Original request:\n${original}`];
-	if (goal) lines.push(`First restatement: ${goal}`);
-	lines.push("The user was asked, and answered:");
-	for (const item of answers) lines.push(`- ${item.question}\n  ${item.answer}`);
-	return lines.join("\n");
-}
-
-/** The request sent to the clarifier after the user answers. */
-export function buildRefineMessages(
-	original: string,
-	goal: string,
-	answers: readonly ClarifyAnswer[],
-	now = Date.now(),
-): { systemPrompt: string; messages: UserMessage[] } {
-	return {
-		systemPrompt: REFINE_SYSTEM_PROMPT,
-		messages: [
-			{ role: "user", content: [{ type: "text", text: buildRefineUserText(original, goal, answers) }], timestamp: now },
-		],
-	};
-}

package/extensions/goal/clarify.ts

@@ -1,24 +1,24 @@
 /**
- * Host orchestration for the goal comprehension step: the nested clarifier
- * calls, their cancellable TUI loaders, the in-command questionnaire, and the
- * confirm/edit dialog.
+ * Host orchestration for the goal comprehension step: the clarifier call, its
+ * cancellable TUI loader, the in-command questionnaire, and the confirm/edit
+ * dialog.
  *
- * The loop's target is understanding what the user wants. The first call asks
- * the model whether it understands the goal and, if not, what it needs to know;
- * the command asks those questions through host dialogs; a second call folds the
- * answers into the final restatement; the editor lets the user confirm or
- * correct it. The flow never throws and never half-applies: a failed,
- * timed-out, cancelled, or unusable comprehension falls back to the text the
- * user typed, and a dismissed dialog cancels the whole command.
+ * The loop's target is understanding what the user wants. One call asks the
+ * model whether it understands the goal and, when it cannot yet, what it needs
+ * to know; the command asks those questions through host dialogs and carries
+ * the answers into the editor, where the user confirms or corrects the goal.
+ * The flow never throws and never half-applies: a failed, timed-out, cancelled,
+ * or unusable comprehension falls back to the text the user typed, and a
+ * dismissed dialog cancels the whole command.
  */
 
 import { BorderedLoader, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { UserMessage } from "@earendil-works/pi-ai";
 import { sanitizeLine } from "../../lib/format.ts";
 import { type Clarification, type ClarifyAnswer, type ClarifyQuestion, parseClarification } from "./clarify-parse.ts";
-import { buildClarifyMessages, buildRefineMessages } from "./clarify-prompt.ts";
+import { buildClarifyMessages } from "./clarify-prompt.ts";
 
-/** Bound on each clarifier model call, in milliseconds. */
+/** Bound on the clarifier model call, in milliseconds. */
 const CLARIFY_TIMEOUT_MS = 30_000;
 
 /** The slice of the context the clarify step reads. */
@@ -27,9 +27,6 @@ export type ClarifyContext = Pick<ExtensionContext, "mode" | "ui" | "signal" | "
 /** Loader text shown while the comprehension call runs. */
 const LOADER_MESSAGE = "Understanding goal…";
 
-/** Loader text shown while the goal is restated from the answers. */
-const REFINE_LOADER_MESSAGE = "Updating the goal…";
-
 /** The confirm/edit dialog title, reading as a confirmation of understanding. */
 const EDITOR_TITLE = "Confirm the goal — Enter to save, Esc to cancel";
 
@@ -79,74 +76,54 @@ function assistantText(response: { content?: unknown }): string {
 	return parts.join("\n");
 }
 
-/** Runs a nested operation, optionally behind the TUI loader. */
-type CompleterRun = <T>(fn: (signal: AbortSignal | undefined) => Promise<T>) => Promise<T | undefined>;
-
-/** The context slice the completer needs. */
-type CompleterContext = Pick<ExtensionContext, "model" | "modelRegistry" | "signal">;
-
 /**
- * Build one clarifier caller.
+ * One clarifier model call, behind the TUI loader.
  *
- * `buildMessages` produces the request; the call runs through `run` (the loader
- * wrapper) with an `AbortController` aborted on timeout, on the session signal,
- * or when the loader is cancelled. Any throw becomes `undefined`, so a provider
- * failure never blocks the command.
+ * The call is aborted on timeout, on the session signal, or when the loader is
+ * cancelled, and any failure becomes `undefined` so a provider error never
+ * blocks the command. Nothing from the conversation is sent: the model must not
+ * invent scope the user did not state.
  */
-function createCompleter(
-	ctx: CompleterContext,
-	timeoutMs: number,
-	run: CompleterRun,
-	buildMessages: () => { systemPrompt: string; messages: UserMessage[] },
-): () => Promise<string | undefined> {
-	return async () => {
-		const model = ctx.model;
-		if (!model) return undefined;
-
-		const { systemPrompt, messages } = buildMessages();
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), timeoutMs);
-		const onAbort = () => controller.abort();
-		ctx.signal?.addEventListener("abort", onAbort, { once: true });
-		try {
-			return await run(async (signal) => {
-				if (signal) signal.addEventListener("abort", () => controller.abort(), { once: true });
-				const response = await ctx.modelRegistry.complete(
-					model,
-					{ systemPrompt, messages },
-					{ signal: controller.signal, cacheRetention: "none" },
-				);
-				if (response.stopReason === "aborted") return undefined;
-				return assistantText(response);
-			});
-		} catch {
-			return undefined;
-		} finally {
-			clearTimeout(timer);
-			ctx.signal?.removeEventListener("abort", onAbort);
-		}
-	};
-}
-
-/** Run one clarifier call behind its loader and return the raw reply. */
-async function completeOnce(
+async function askClarifier(
 	ctx: ClarifyContext,
-	loaderMessage: string,
 	buildMessages: () => { systemPrompt: string; messages: UserMessage[] },
 ): Promise<string | undefined> {
-	return createCompleter(ctx, CLARIFY_TIMEOUT_MS, (run) => withLoader(ctx, loaderMessage, run), buildMessages)();
+	const model = ctx.model;
+	if (!model) return undefined;
+
+	const { systemPrompt, messages } = buildMessages();
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), CLARIFY_TIMEOUT_MS);
+	const onAbort = () => controller.abort();
+	ctx.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		return await withLoader(ctx, LOADER_MESSAGE, async (signal) => {
+			if (signal) signal.addEventListener("abort", () => controller.abort(), { once: true });
+			const response = await ctx.modelRegistry.complete(
+				model,
+				{ systemPrompt, messages },
+				{ signal: controller.signal, cacheRetention: "none" },
+			);
+			if (response.stopReason === "aborted") return undefined;
+			return assistantText(response);
+		});
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+		ctx.signal?.removeEventListener("abort", onAbort);
+	}
 }
 
 /**
- * One comprehension call on the session model, parsed into a
- * {@link Clarification}.
+ * The comprehension call, parsed into a {@link Clarification}.
  *
  * Returns `undefined` when there is no dialog UI or no model, or when the call
  * fails, times out, is cancelled, or returns nothing usable.
  */
 export async function clarifyGoalPrompt(ctx: ClarifyContext, text: string): Promise<Clarification | undefined> {
 	if (!ctx.hasUI || !ctx.model) return undefined;
-	return parseClarification(await completeOnce(ctx, LOADER_MESSAGE, () => buildClarifyMessages(text)));
+	return parseClarification(await askClarifier(ctx, () => buildClarifyMessages(text)));
 }
 
 /**
@@ -155,7 +132,7 @@ export async function clarifyGoalPrompt(ctx: ClarifyContext, text: string): Prom
  * A question with options uses a selector; a free-form question uses a text
  * input. Resolves `undefined` when any dialog is dismissed, so the caller cancels
  * the whole command; an empty answer is skipped. The answer is sanitized to one
- * line, since it is folded into a model message and later the goal.
+ * line, since it is folded into the goal the editor holds.
  */
 async function askQuestions(
 	ctx: Pick<ClarifyContext, "ui">,
@@ -178,19 +155,15 @@ async function askQuestions(
 }
 
 /**
- * Fold the user's answers into the final restatement of the goal.
+ * Carry the answers into the editor as notes under the restatement.
  *
- * Returns `undefined` on any failure, so the caller falls back to the first
- * restatement.
+ * No model call rewrites the goal from the answers, so they are shown verbatim
+ * with the question that asked for them: the user folds them into the sentence
+ * or deletes them, and whatever the editor holds is what gets recorded.
  */
-async function refineWithAnswers(
-	ctx: ClarifyContext,
-	original: string,
-	goal: string,
-	answers: readonly ClarifyAnswer[],
-): Promise<string | undefined> {
-	const reply = await completeOnce(ctx, REFINE_LOADER_MESSAGE, () => buildRefineMessages(original, goal, answers));
-	return parseClarification(reply)?.goal || undefined;
+function withAnswers(goal: string, answers: readonly ClarifyAnswer[]): string {
+	if (answers.length === 0) return goal;
+	return [goal, "", ...answers.map((answer) => `Also: ${answer.question} → ${answer.answer}`)].join("\n");
 }
 
 /** Open the confirm/edit dialog, or cancel when it is dismissed. */
@@ -201,7 +174,7 @@ async function editOrCancel(ctx: ClarifyContext, prefill: string): Promise<GoalP
 
 /**
  * Run the understanding loop for `/goal <prompt>`: comprehend, ask what is
- * missing, re-comprehend, then let the user confirm or correct the goal.
+ * missing, then let the user confirm or correct the goal.
  *
  * Without a dialog UI or a model the typed text is used unchanged, so the
  * command never blocks on the loop in print or JSON mode. A failed comprehension
@@ -224,11 +197,7 @@ export async function prepareGoalPrompt(ctx: ClarifyContext, typed: string): Pro
 			ctx.ui.notify("Goal not set.", "info");
 			return { action: "cancel" };
 		}
-		if (answers.length > 0) {
-			const refined = await refineWithAnswers(ctx, typed, proposed, answers);
-			if (refined) proposed = refined;
-			else ctx.ui.notify("Could not update the goal from your answers; edit it below.", "info");
-		}
+		proposed = withAnswers(proposed, answers);
 	}
 	return editOrCancel(ctx, proposed);
 }

package/extensions/goal/commands.ts

@@ -23,23 +23,37 @@ import { GOAL_ENTRY_TYPE, type Goal } from "./types.ts";
 /** Title of the record-only edit dialog, spelling out both exits. */
 const EDIT_TITLE = "Goal — Enter to save, Esc to cancel";
 
-/** Completion values for the goal keywords: `set`/`edit`/`raw` take an argument. */
-const GOAL_COMPLETIONS = [
-	{ value: "set ", label: "set" },
-	{ value: "edit ", label: "edit" },
-	{ value: "raw ", label: "raw" },
-	{ value: "clear", label: "clear" },
-	{ value: "done", label: "done" },
-	{ value: "achieved", label: "achieved" },
-	{ value: "help", label: "help" },
-	{ value: "-h", label: "-h" },
-	{ value: "--help", label: "--help" },
+/**
+ * One reserved `/goal` verb: the word, what a bare occurrence means, and whether
+ * it takes the rest of the line as its argument.
+ */
+type GoalVerb =
+	| { word: string; kind: "usage" | "clear" | "done"; argument: "none" }
+	| { word: string; kind: "raw"; argument: "required" }
+	| { word: string; kind: "record"; argument: "required" | "optional" };
+
+/**
+ * The single list behind the parser, the completions, and the help text, so a
+ * new verb cannot land in one of them and be missing from another.
+ * `set`/`edit` share the `record` kind; the two words are interchangeable.
+ */
+export const GOAL_VERBS: readonly GoalVerb[] = [
+	{ word: "set", kind: "record", argument: "optional" },
+	{ word: "edit", kind: "record", argument: "optional" },
+	{ word: "raw", kind: "raw", argument: "required" },
+	{ word: "clear", kind: "clear", argument: "none" },
+	{ word: "done", kind: "done", argument: "none" },
+	{ word: "achieved", kind: "done", argument: "none" },
+	{ word: "help", kind: "usage", argument: "none" },
+	{ word: "-h", kind: "usage", argument: "none" },
+	{ word: "--help", kind: "usage", argument: "none" },
 ];
 
-/** `/goal set <text>` and `/goal edit <text>`: `text` is optional. */
-const RECORD_PATTERN = /^(set|edit)(?:\s+([\s\S]*))?$/i;
-/** `/goal raw <text>`: `text` is required. */
-const RAW_PATTERN = /^raw(?:\s+([\s\S]*))?$/i;
+/** Completion values: a verb that takes an argument completes with a space. */
+const GOAL_COMPLETIONS = GOAL_VERBS.map((verb) => ({
+	value: verb.argument === "none" ? verb.word : `${verb.word} `,
+	label: verb.word,
+}));
 
 /** One parsed `/goal` invocation. */
 export type GoalCommand =
@@ -55,30 +69,22 @@ export type GoalCommand =
 /**
  * Parse `/goal`'s argument into one command.
  *
- * Keywords match whole words, so `setfoo` and `edit-foo` are free-form prompts,
- * not malformed keywords. Only `help`/`clear`/`done`/`achieved` are reserved
- * without an argument; anything else is a prompt.
+ * Only the first word is looked up, so a keyword matches a whole word: `setfoo`
+ * and `edit-foo` are free-form prompts, not malformed keywords, and a verb that
+ * takes no argument leaves the whole line a prompt (`clear the cache`). Anything
+ * unlisted is a prompt.
  */
 export function parseGoalCommand(input: string): GoalCommand {
 	const text = input.trim();
 	if (!text) return { kind: "show" };
 
-	const keyword = text.toLowerCase();
-	if (keyword === "help" || keyword === "-h" || keyword === "--help") return { kind: "usage" };
-	if (keyword === "clear") return { kind: "clear" };
-	if (keyword === "done" || keyword === "achieved") return { kind: "done" };
-
-	const record = RECORD_PATTERN.exec(text);
-	if (record) {
-		const objective = (record[2] ?? "").trim();
-		return objective ? { kind: "record", text: objective } : { kind: "editor" };
-	}
-	const raw = RAW_PATTERN.exec(text);
-	if (raw) {
-		const objective = (raw[1] ?? "").trim();
-		return objective ? { kind: "raw", text: objective } : { kind: "usage" };
-	}
-	return { kind: "prompt", text };
+	const head = text.split(/\s+/, 1)[0] ?? "";
+	const rest = text.slice(head.length).trim();
+	const verb = GOAL_VERBS.find((candidate) => candidate.word === head.toLowerCase());
+	if (!verb) return { kind: "prompt", text };
+	if (verb.argument === "none") return rest ? { kind: "prompt", text } : { kind: verb.kind };
+	if (verb.kind === "raw") return rest ? { kind: "raw", text: rest } : { kind: "usage" };
+	return rest ? { kind: "record", text: rest } : { kind: "editor" };
 }
 
 /**
@@ -87,7 +93,7 @@ export function parseGoalCommand(input: string): GoalCommand {
  * once the prefix contains a space (or the start of the prompt does not look
  * like a keyword) the argument is left to the user.
  */
-function completeGoalArg(prefix: string): Array<{ value: string; label: string }> | null {
+export function completeGoalArg(prefix: string): Array<{ value: string; label: string }> | null {
 	const text = prefix.trimStart();
 	if (text.includes(" ")) return null;
 	const items = GOAL_COMPLETIONS.filter((item) => item.label.startsWith(text));