Resolve planning uncertainty before approval

docs/slop/audit/20260826_pi-plan-aligned-planning.md

@@ -20,6 +20,6 @@ $ git diff --check
 
 [test/goals-flow.test.ts](../../../test/goals-flow.test.ts) covers the visible plan before Refine, an editor prompt before a Refine revision turn, exact multiline Refine notes in `## Interview`, Ready as the only work handoff, Pi editor then Cancel, phase restoration, planning snapshot, writable plan path, allowed `pwd && ls && git log` and `cd . && ls -la`, blocked pipe, and blocked `CompleteGoal`.
 
-[test/prompts.test.ts](../../../test/prompts.test.ts) locks the prompt instruction to inspect discoverable facts or ask one focused question, and forbids placeholder goals.
+[test/prompts.test.ts](../../../test/prompts.test.ts) locks the prompt instruction to inspect repository facts and use web search, ask the human to confirm interpretation and approve preference choices, and forbid placeholder goals.
 
 [test/rpc-review.test.ts](../../../test/rpc-review.test.ts) starts the installed Pi RPC executable with [offline-model.ts](../../../test/fixtures/offline-model.ts), selects Refine through Pi's real dialog protocol, receives the editor request before the revision call, then submits notes and observes the revision call. The test uses a local HTTP model, so it spends no API credits.

docs/slop/plans/20260826_pi-plan-aligned-planning.md

@@ -29,12 +29,13 @@ Pi-goals will use pi-plan's small phase model. The UI, tool gate, and agent cont
   - subtle failure mode: a review choice queues an unrequested agent turn or hides the plan below the dialog.
   - discriminator: flow tests show plan before the menu and distinguish all four actions.
   - evidence: [goals-flow.test.ts](../../../test/goals-flow.test.ts) shows plan before the menu and isolates Ready as the work handoff; [verification](../audit/20260826_pi-plan-aligned-planning.md) records `25 passed`. Pending human Pi TUI check.
-- [x] goal: Planning turns an unclear objective into a judgeable outcome
-  - [x] Require repository inspection for discoverable facts, then one focused human question for an unresolved outcome or acceptance condition.
+- [x] goal: Planning resolves facts, interpretation, and approval before overnight work
+  - [x] Require repository inspection and web search for discoverable facts.
+  - [x] Require human confirmation for the agent's interpretation, unresolved task or outcome, scope, and decisions needing later approval.
   - [x] Ban placeholder goals such as "work out the thing" before the plan review menu.
-  - subtle failure mode: the plan has a formal discriminator but its goal still has no object or observable result.
-  - discriminator: [prompts.test.ts](../../../test/prompts.test.ts) locks the inspect-or-ask rule and the concrete-goal rule in the model prompt.
-  - evidence: [prompts.ts](../../../src/prompts.ts) requires a goal object plus observable result, and [prompts.test.ts](../../../test/prompts.test.ts) asserts that wording. [verification](../audit/20260826_pi-plan-aligned-planning.md) records `29 passed`.
+  - subtle failure mode: the plan has a formal discriminator but silently chooses an editorial direction or other human decision.
+  - discriminator: [prompts.test.ts](../../../test/prompts.test.ts) locks the research, clarification, approval, and concrete-goal rules in the model prompt.
+  - evidence: [prompts.ts](../../../src/prompts.ts) requires research, human confirmation, and approval before Ready. [prompts.test.ts](../../../test/prompts.test.ts) checks those requirements. [verification](../audit/20260826_pi-plan-aligned-planning.md) records `29 passed`.
 - [x] goal: Refine waits for text in Pi's real dialog protocol
   - [x] Run Pi in RPC mode against a local no-cost model.
   - [x] Select Refine, observe the editor request, then submit text and observe the revision turn.

src/prompts.ts

@@ -29,17 +29,19 @@
 export const planDrafting = `\
 You are in plan mode. You are making a short judgeable plan that captures the user's real goals, then tests it in conversation.
 
-1. Explore the repository read-only first. Use read-only tools to resolve discoverable facts. Do not
-write or run code in this phase (edit/write are blocked except for the plan file; don't mutate state
-via bash either).
-2. Before you draft a goal, identify its object and the observable result that will show it is done.
-If either is uncertain, reduce uncertainty now: inspect the repository when it can answer, or ask the
-human one focused question when only their intent or acceptance condition can answer. Do not present
-the review menu with a placeholder goal such as "work out the thing", "improve it", or "investigate".
-3. For high-impact human preferences, build a decision tree and ask the whole independent frontier
-in one round. Give a recommended answer for each question. Record each answer in ## Interview. Do
-not make the plan final while material user decisions remain open.
-4. When every goal has an object and an observable result, draft the plan file and present it.
+1. Reduce technical uncertainty first. Use read-only repository tools and web search to resolve
+facts. Do not write or run code in this phase (edit/write are blocked except for the plan file; don't
+mutate state via bash either).
+2. Before you draft a goal, identify its object, observable result, scope, and any decision that the
+human would need to approve later. If any is uncertain, reduce uncertainty now: inspect files or the
+web for facts, then ask the human to confirm your interpretation, pin down the outcome or task, or
+approve an editorial or other preference choice. Do not present the review menu with a placeholder
+goal such as "work out the thing", "improve it", or "investigate".
+3. For independent high-impact questions, build a decision tree and ask the whole frontier in one
+round. Give a recommended answer for each question. Record each answer in ## Interview. Do not make
+the plan final while material user decisions remain open.
+4. When every goal has an object, observable result, settled scope, and required approval, draft the
+plan file and present it. It should be safe to work overnight and present the requested outcome.
 
 How this mode ends: after each settled draft the human gets a menu (Ready / Refine / Edit / Cancel).
 Plan mode ends only when they pick Ready. Refine collects short revision notes. Edit opens the full
@@ -136,10 +138,11 @@ When the goals are drafted, present them and say the plan is final. Do not begin
 export function planningState(planPath: string): string {
 	return `\
 [PLANNING MODE]
-The plan at ${planPath} is the only file you may change. Use read-only tools to find facts yourself,
-then ask the human one focused question for an unresolved intent or acceptance condition. Do not draft
-a placeholder goal without a concrete object and observable result. Do not execute work, mark a goal
-[/] or [x], or sign off a goal. The plan is not approved until the human selects Ready.`;
+The plan at ${planPath} is the only file you may change. Use read-only repository tools and web search
+to find facts. Ask the human to confirm unresolved interpretation, outcome, task, scope, or a choice
+that needs their approval. Do not draft a placeholder goal without a concrete object, observable
+result, settled scope, and required approval. Do not execute work, mark a goal [/] or [x], or sign off
+a goal. The plan is not approved until the human selects Ready.`;
 }
 
 export function reminder(foldedPlan: string, planRel: string): string {

test/prompts.test.ts

@@ -3,14 +3,15 @@ import { planDrafting, planningState } from "../src/prompts.js";
 
 describe("planning prompt", () => {
 	it("requires fact finding or a focused question before a goal", () => {
-		expect(planDrafting).toContain("Use read-only tools to resolve discoverable facts.");
-		expect(planDrafting).toContain("ask the\nhuman one focused question");
-		expect(planDrafting).toContain("placeholder goal such as \"work out the thing\"");
-		expect(planDrafting).toContain("object and an observable result");
+		expect(planDrafting).toContain("Use read-only repository tools and web search");
+		expect(planDrafting).toContain("ask the human to confirm your interpretation");
+		expect(planDrafting).toContain("approve an editorial or other preference choice");
+		expect(planDrafting).toContain("placeholder\ngoal such as \"work out the thing\"");
+		expect(planDrafting).toContain("object, observable result, settled scope, and required approval");
 	});
 
 	it("restores the same rule after compaction", () => {
-		expect(planningState(".pi/plan/test.md")).toContain("Use read-only tools to find facts yourself");
-		expect(planningState(".pi/plan/test.md")).toContain("one focused question");
+		expect(planningState(".pi/plan/test.md")).toContain("web search");
+		expect(planningState(".pi/plan/test.md")).toContain("choice\nthat needs their approval");
 	});
 });