pi-goal-x 0.8.2 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-goal-x
 
-> **Fork of [@capyup/pi-goal](https://github.com/capyup/pi-goal)** — this repository extends the upstream with quality-of-life features for the completion auditor, lifecycle reliability improvements, and drafting UX refinements. Upstream changes can be merged from the original repository.
+> **Fork of [@capyup/pi-goal](https://github.com/capyup/pi-goal)** — this repository extends the upstream with quality-of-life features for the completion auditor, lifecycle reliability improvements, mid-flight objective updates, deferred archival, and drafting UX refinements. Upstream changes can be merged from the original repository.
 
 `pi-goal-x` is a long-running goal extension for [pi](https://github.com/earendil-works/pi-coding-agent). It gives the agent a durable objective, a visible lifecycle, and schema-gated tools for drafting, executing, pausing, resuming, and completing work.
 
@@ -10,6 +10,21 @@ 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:
 
+### Mid-flight objective updates
+
+- **`update_goal({updatedObjective})`** — the agent can now sync the goal objective mid-flight when user requirements change, *without* completing the goal. This ensures the completion auditor evaluates against the latest requirements. The combined path (`updatedObjective` + `status: "complete"`) applies the update first, then runs the normal completion+audit flow.
+- **`apply_goal_tweak`** remains available for `/goal-tweak` drafting revisions; the new parameter is the lightest possible touch on the existing `update_goal` tool.
+
+### Deferred archival
+
+- **No more premature archiving**: previously, `update_goal` archived the goal file inline within the tool handler before the agent could see the audit result (or skip notification). Archival is now deferred until `turn_end` — after the agent has received the audit/skip result in the conversation. The goal remains visible in the active pool through the entire completion flow.
+- **Cleaner lifecycle**: completed goals are archived by the `turn_end` lifecycle hook, not by the tool handler. The `accountProgress` guard skips disk reconciliation for completed goals.
+
+### 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**: 131 tests total — function-level integration tests (12), mock-pi handler tests (4), file-validity checks (6), and real `pi --fork --mode json` tests (3 scenarios: quick-sync, combined sync+complete, deferred archival).
+
 ### Completion auditor
 
 - **Live progress widget** — when the auditor runs, the TUI shows a spinner, the current tool being executed, and recent output lines. No more wondering if anything is happening.

package/extensions/goal-policy.ts

@@ -43,6 +43,14 @@ export function validateGoalCompletion(args: {
 	return { ok: true };
 }
 
+export function validateGoalUpdate(args: {
+	goal: GoalPolicyRecordLike | null;
+}): PolicyValidation {
+	if (!args.goal) return { ok: false, message: "No goal is set; cannot update objective." };
+	if (args.goal.status === "complete") return { ok: false, message: "Goal is already complete; cannot update objective." };
+	return { ok: true };
+}
+
 export function validateGoalAbort(args: {
 	goal: GoalPolicyRecordLike | null;
 	runningGoalId?: string | null;

package/extensions/goal.ts

@@ -106,6 +106,7 @@ import {
 	shouldInjectPostCompactReminder,
 	validateGoalAbort,
 	validateGoalCompletion,
+	validateGoalUpdate,
 	validatePauseGoal,
 	validateResumeGoal,
 } from "./goal-policy.ts";
@@ -1704,16 +1705,70 @@ export default function goalExtension(pi: ExtensionAPI): void {
 			"Do not call update_goal merely because work is stopping, substantial progress was made, or tests passed without covering every requirement.",
 			"Do not use update_goal=complete as an escape hatch when you are blocked. If you are blocked, call pause_goal({reason, suggestedAction?}) instead so the user can intervene.",
 			"For sisyphus goals, do not mark complete until every numbered step has been executed and individually verified against its done criterion.",
+			"If the user gives requirements, feedback, or corrections that differ from the goal objective, the goal is stale. Use update_goal with updatedObjective to sync the objective before continuing work or before marking the goal complete. This ensures the auditor evaluates against the latest requirements.",
 		],
 		parameters: Type.Object({
-			status: StringEnum([COMPLETE_STATUS] as const, { description: "Set to complete only when the objective is achieved." }),
+			status: Type.Optional(StringEnum([COMPLETE_STATUS] as const, { description: "Set to complete only when the objective is achieved." })),
 			completionSummary: Type.Optional(Type.String({ description: "Concise completion claim and evidence summary passed to the independent auditor agent." })),
 			confirmBypassAuditor: Type.Optional(Type.Boolean({ description: "Set to true to confirm bypassing the independent auditor when it is disabled in settings." })),
+			updatedObjective: Type.Optional(Type.String({ description: "Revised goal objective. Use when the user's requirements have changed mid-flight. The goal remains active so the agent can continue working toward the new objective. Can be combined with status=complete to update the objective before the completion audit." })),
 		}),
 		executionMode: "sequential",
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			reconcileFocusedGoalFromDisk(ctx);
-			if (params.status !== COMPLETE_STATUS) throw new Error("update_goal only supports status=complete.");
+
+			// -- Phase 1: Objective update (quick sync) --
+			// Apply updatedObjective before any completion logic so the completion
+			// flow (if status=complete is also set) reads the latest objective.
+			if (params.updatedObjective !== undefined) {
+				const newObjective = params.updatedObjective.trim();
+				if (!newObjective) throw new Error("update_goal requires a non-empty updatedObjective.");
+				const updateGate = validateGoalUpdate({ goal: state.goal });
+				if (!updateGate.ok) {
+					return {
+						content: [{ type: "text", text: updateGate.message }],
+						details: goalDetails(state.goal),
+					};
+				}
+				if (!state.goal) throw new Error("Goal disappeared during objective update.");
+				const next: GoalRecord = {
+					...state.goal,
+					objective: newObjective,
+					updatedAt: nowIso(),
+				};
+				state.goal = writeActiveGoalFile(ctx, next);
+				pi.appendEntry(STATE_ENTRY, goalDetails(state.goal));
+				try {
+					appendGoalEvent(ctx, {
+						type: "goal_tweaked",
+						goalId: state.goal.id,
+						changeSummary: "Objective updated via update_goal",
+						at: state.goal.updatedAt,
+					});
+				} catch {
+					// Ledger append failure should not block update
+				}
+				updateUI(ctx);
+
+				// Quick sync only (no status=complete) — return without terminating
+				if (params.status !== COMPLETE_STATUS) {
+					return {
+						content: [{ type: "text", text: `Goal objective updated.` }],
+						details: goalDetails(state.goal),
+					};
+				}
+				// Fall through: status=complete also set, proceed with completion below
+			}
+
+			// -- Phase 2: Status validation --
+			if (params.status !== COMPLETE_STATUS) {
+				if (params.updatedObjective === undefined) {
+					throw new Error("update_goal requires either status=complete or updatedObjective.");
+				}
+				throw new Error("update_goal requires status=complete when marking a goal complete.");
+			}
+
+			// -- Phase 3: Completion --
 			const completionGate = validateGoalCompletion({ goal: state.goal, runningGoalId });
 			if (!completionGate.ok) {
 				return {
@@ -2009,7 +2064,8 @@ export default function goalExtension(pi: ExtensionAPI): void {
 			};
 		},
 		renderCall(args, theme) {
-			return new Text(theme.fg("toolTitle", "update_goal ") + theme.fg("success", args.status), 0, 0);
+			const label = args?.status ?? args?.updatedObjective ? "sync" : "";
+			return new Text(theme.fg("toolTitle", "update_goal ") + theme.fg("success", label), 0, 0);
 		},
 		renderResult(result, _options, theme) {
 			return renderGoalResult(result, theme);

package/extensions/prompts/goal-prompts.ts

@@ -44,7 +44,9 @@ If you hit a real blocker that you cannot resolve with one more reasonable next
 
 If the user explicitly asks to abandon/cancel this goal, or the objective is obsolete, impossible, or unsafe to continue and should not be marked complete, call abort_goal({reason}) with a non-empty reason and stop.
 
-Do NOT silently invent workarounds, fake completion, or quietly redefine the objective. Do NOT call update_goal=complete to escape a blocker.${sisyphusDisciplineBlock(goal) ? `\n${sisyphusDisciplineBlock(goal)}` : ""}`;
+Do NOT silently invent workarounds, fake completion, or quietly redefine the objective. Do NOT call update_goal=complete to escape a blocker.
+
+Goal evolution: if the user gives requirements, feedback, or corrections that differ from the goal objective, the goal is stale. Propose the updated objective concisely and wait for the user to confirm before continuing. Use update_goal with updatedObjective for narrow focus-area changes, or suggest /goal-tweak for broader revisions (boundaries, constraints, multiple sections). Do NOT mark the goal complete with a stale objective.${sisyphusDisciplineBlock(goal) ? `\n${sisyphusDisciplineBlock(goal)}` : ""}`;
 }
 
 export function continuationPrompt(goal: GoalRecord): string {
@@ -77,6 +79,8 @@ export function continuationPrompt(goal: GoalRecord): string {
 		"Do not call update_goal unless the goal is complete enough to survive independent semantic auditing. Do not mark a goal complete merely because work is stopping.",
 		"Do not ask the user for confirmation unless there is a real blocker.",
 		"",
+		"Goal evolution: if the user gives requirements, feedback, or corrections that differ from the goal objective, the goal is stale. Propose the updated objective concisely and wait for the user to confirm before continuing. Use update_goal with updatedObjective for narrow focus-area changes, or suggest /goal-tweak for broader revisions (boundaries, constraints, multiple sections). Do NOT mark the goal complete with a stale objective.",
+		"",
 		"If you hit a real blocker (missing credentials, contradictory spec, file/permission you cannot access, dangerous operation pending user approval, or an unclear Sisyphus-style ordered plan), call pause_goal({reason, suggestedAction?}) and stop. If the user explicitly asks to abandon/cancel, or the objective is obsolete, impossible, or unsafe to continue, call abort_goal({reason}) and stop. Do not silently invent workarounds. Do not fake completion. pause_goal and abort_goal are structured lifecycle exits; update_goal=complete is not an escape hatch for blockers.",
 		...(goal.sisyphus ? ["", sisyphusDisciplineBlock(goal)] : []),
 	].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Goal mode extension for pi: persistent long-running objectives, /goal-set drafting, Sisyphus prompt style, autoContinue, and an above-editor status overlay. Fork of @capyup/pi-goal.",
   "license": "MIT",
   "author": "pi-goal-x contributors",