pi-goal-list-loop-audit 0.33.1 → 0.33.3

package/extensions/goal-loop-display.ts

@@ -449,7 +449,7 @@ function loopLines(l: LoopState, now: number, theme?: DisplayTheme, width?: numb
     lines.push(`├─ ${paint(theme, act.ok ? "success" : "error", act.ok ? "✓" : "✗")} ${act.name}${act.arg ? ` ${paint(theme, "dim", truncate(act.arg, 24))}` : ""}${act.ms > 0 ? ` ${paint(theme, "dim", `(${fmtElapsed(act.ms)})`)}` : ""}`);
   }
   const footer = !l.measureCmd
-    ? "metricless (no plateau) · /loop stop · /loop polish"
+    ? "metricless (no plateau) · /loop stop · /loop refine" // v0.33.2: the verb exists now
     : `${l.kind === "audit" ? "metric: closed findings" : truncate(l.measureCmd, budgetFor(width, 3, 30))} · /loop stop`;
   lines.push(`└─ ${paint(theme, "dim", footer)}`);
   if (l.branchName) lines.push(`⎇ ${paint(theme, "muted", truncate(l.branchName, budgetFor(width, 3, 50)))}`);

package/extensions/goal-loop-forever.ts

@@ -10,6 +10,7 @@
  * self-reports progress.
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
@@ -110,6 +111,20 @@ export interface LoopState {
   /** v0.25.1: /loop start toolsamerepeat=N — legacy same-tool-same-result
    * check window. 0 disables it (multi-signal detector only). */
   toolSameRepeat?: number;
+  /** v0.33.2: respec loops carry their spec file — drift detection
+   * (specHash compared per tick), checkbox progress (specChecked →
+   * spec_item_progress events), and the refine tool's specText write path. */
+  specFile?: string;
+  specHash?: string;
+  specChecked?: number;
+  /** v0.33.2: hypothesis feedback loop — the last turn's HYPOTHESIS line
+   * plus the verdict computed against the metric movement, injected into
+   * the next iteration's prompt. */
+  lastHypothesis?: string;
+  hypothesisFeedback?: string;
+  /** v0.33.2: /loop refine <text> — the operator's respec suggestion rides
+   * the next iteration's prompt; the agent proposes via propose_loop_refine. */
+  refineHint?: string;
   /** v0.25.1: per-iteration progress-signal accumulators for the
    * multi-signal stuck gate. fileWrites bumps on write/edit tool results;
    * iterationStartHead/At snapshot when the iteration BEGAN so the tick can
@@ -464,6 +479,37 @@ export function countOpenAuditFindings(cwd: string): number {
   }
 }
 
+/** v0.33.2: the first OPEN finding's text — the reprieve note names what
+ * to close, not just how many remain. */
+export function topOpenAuditFinding(cwd: string): string | null {
+  try {
+    const p = join(cwd, AUDIT_FINDINGS_REL);
+    if (!existsSync(p)) return null;
+    const line = readFileSync(p, "utf-8").split("\n").find((l) => /^- \[ \]/.test(l));
+    return line ? line.replace(/^- \[ \]\s*/, "").trim().slice(0, 120) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** v0.33.2: spec drift detection — short sha256 of the spec file. */
+export function specFileHash(p: string): string | null {
+  try {
+    return createHash("sha256").update(readFileSync(p, "utf-8")).digest("hex").slice(0, 16);
+  } catch {
+    return null;
+  }
+}
+
+/** v0.33.2: checked checkbox count in a spec file (spec_item_progress). */
+export function countCheckedSpecItems(p: string): number | null {
+  try {
+    return readFileSync(p, "utf-8").split("\n").filter((l) => /^- \[x\]/i.test(l)).length;
+  } catch {
+    return null;
+  }
+}
+
 // ---- /goal audit-project (v0.29.8) ----
 
 /**
@@ -497,7 +543,7 @@ export const LIST_AUDIT_COLLECT_MARKER = "[LIST-AUDIT-COLLECT]";
 
 export function listAuditCollectTarget(focus?: string): string {
   const scope = focus && focus.trim() ? focus.trim() : "the whole project";
-  return `${LIST_AUDIT_COLLECT_MARKER} Run ONE project audit pass that COLLECTS work — the follow-up fixes are queued as separate list items, so this pass changes no code. Scope: ${scope}. (1) Run a FRESH audit pass over the codebase — spawn Explore subagents for breadth — hunting real problems: bugs, broken flows, regressions, drift between docs and code, dead code, security holes. Not style nits, not speculative refactors. (2) Append every NEW finding to ${AUDIT_FINDINGS_REL} (create the file on the first finding; append-only — never delete, rewrite, or reorder existing lines; never re-report a finding already listed), classified: "- [ ] FIX: SEVERITY: short description (file:line)" for bugs and polish — and "- [?] DECIDE: short description (what the choice is, what each side costs)" for direction, trade-offs, and scope questions where two reasonable answers exist. (3) Change NOTHING — no fixes, no refactors, no drive-by edits: the orchestrator queues each open FIX finding as its own list item after this pass completes, and each fix lands with its own commit and its own audit. (4) DECIDE findings are listed in the completion report — they are presented to the user, never queued and never silently fixed. (5) Honesty law: never fabricate findings to look busy; if the pass is genuinely clean, say so plainly — an empty findings set is a success, not a failure. Done when: the audit pass is complete and every finding it surfaced is appended to ${AUDIT_FINDINGS_REL} with the right classification (or the report states plainly that nothing was found).`;
+  return `${LIST_AUDIT_COLLECT_MARKER} Run ONE project audit pass that COLLECTS work — the follow-up fixes are queued as separate list items, so this pass changes no code. Scope: ${scope}. (1) Run a FRESH audit pass over the codebase — spawn Explore subagents for breadth — hunting real problems: bugs, broken flows, regressions, drift between docs and code, dead code, security holes. Not style nits, not speculative refactors. (2) Append every NEW finding to ${AUDIT_FINDINGS_REL} (create the file on the first finding; append-only — never delete, rewrite, or reorder existing lines; never re-report a finding already listed), classified: "- [ ] FIX: SEVERITY: short description (file:line)" for bugs and polish — and "- [?] DECIDE: short description (what the choice is, what each side costs)" for direction, trade-offs, and scope questions where two reasonable answers exist. (3) Change NOTHING — no fixes, no refactors, no drive-by edits: the orchestrator queues each open FIX finding as its own list item after this pass completes, and each fix lands with its own commit and its own audit. (4) DECIDE findings are appended as "- [?]" lines and NOTHING more — the orchestrator raises them to the user as questions after the pass completes; they are never queued and never silently fixed. (5) Honesty law: never fabricate findings to look busy; if the pass is genuinely clean, say so plainly — an empty findings set is a success, not a failure. Done when: the audit pass is complete and every finding it surfaced is appended to ${AUDIT_FINDINGS_REL} with the right classification (or the report states plainly that nothing was found).`;
 }
 
 /** One parsed open finding from the audit findings file. */
@@ -558,5 +604,5 @@ export const LOOP_AUDIT_MARKER = "iteration by iteration — FIX-FIRST";
 
 export function projectAuditTarget(focus?: string): string {
   const scope = focus && focus.trim() ? focus.trim() : "the whole project";
-  return `${GOAL_AUDIT_ONESHOT_MARKER}. Scope: ${scope}. (1) Run a FRESH audit pass over the codebase — spawn Explore subagents for breadth — hunting real problems: bugs, broken flows, regressions, drift between docs and code, dead code, security holes. Not style nits, not speculative refactors. (2) Append every NEW finding to ${AUDIT_FINDINGS_REL} (create the file on the first finding; append-only — never delete, rewrite, or reorder existing lines; never re-report a finding already listed), classified: "- [ ] FIX: SEVERITY: short description (file:line)" for bugs and polish — whether to fix these is NOT a decision — and "- [?] DECIDE: short description (what the choice is, what each side costs)" for direction, trade-offs, and scope questions where two reasonable answers exist. (3) Fix every NEW FIX finding from this pass — real fixes, committed with the repo's configured identity on the current branch (no invented identities or branches) — then check the box: "- [x] … — fixed in <commit>". (4) Change NOTHING for DECIDE findings — present them in the completion report instead. (5) Honesty law: never fabricate findings to look busy; never check a box without the fix commit existing; never silently turn a DECIDE into a fix. Done when: the audit pass is complete, every new FIX finding has a fix commit and a checked box in ${AUDIT_FINDINGS_REL}, and every DECIDE finding is listed in the file and presented in the completion report.`;
+  return `${GOAL_AUDIT_ONESHOT_MARKER}. Scope: ${scope}. (1) Run a FRESH audit pass over the codebase — spawn Explore subagents for breadth — hunting real problems: bugs, broken flows, regressions, drift between docs and code, dead code, security holes. Not style nits, not speculative refactors. (2) Append every NEW finding to ${AUDIT_FINDINGS_REL} (create the file on the first finding; append-only — never delete, rewrite, or reorder existing lines; never re-report a finding already listed), classified: "- [ ] FIX: SEVERITY: short description (file:line)" for bugs and polish — whether to fix these is NOT a decision — and "- [?] DECIDE: short description (what the choice is, what each side costs)" for direction, trade-offs, and scope questions where two reasonable answers exist. (3) Fix every NEW FIX finding from this pass — real fixes, committed with the repo's configured identity on the current branch (no invented identities or branches) — then check the box: "- [x] … — fixed in <commit>". (4) Change NOTHING for DECIDE findings — RAISE them instead: if any "- [?]" findings exist, present each one to the user with ask_user_question BEFORE calling complete_goal (one question per finding, options from the finding's own two sides plus "Defer"; prose numbered list if ask_user_question is unavailable; Esc = Defer), then record every answer in ${AUDIT_FINDINGS_REL} — replace the "- [?]" line with "- [x] DECIDED: <what was chosen> (<date>)" (or "- [x] DEFERRED") so it stops re-surfacing — and queue any chosen work with list_add. (5) Honesty law: never fabricate findings to look busy; never check a box without the fix commit existing; never silently turn a DECIDE into a fix. Done when: the audit pass is complete, every new FIX finding has a fix commit and a checked box in ${AUDIT_FINDINGS_REL}, and every DECIDE finding has been raised to the user and recorded as DECIDED/DEFERRED (or the report states plainly that none were found).`;
 }

package/extensions/goal-loop-repetition.ts

@@ -190,7 +190,19 @@ export function forwardTransitionPaired(input: LoopStuckInput): boolean {
  * (new detector only), undefined = REPETITION.toolResultRepeat.
  */
 export function isActuallyStuck(input: LoopStuckInput, toolSameRepeat?: number): string | undefined {
-  if ((input.fileWriteCount ?? 0) > 0) return undefined;
+  if ((input.fileWriteCount ?? 0) > 0) {
+    // v0.33.2: write-exemption abuse — endless cosmetic edits with a
+    // near-identical reply are churn, not progress (the metricless
+    // doorknob leak). The stuck ladder's first rung is a prompt note;
+    // any genuinely different iteration resets it.
+    if (input.previousText && input.assistantText && normalizeForPrint(input.assistantText).length > REPETITION.minSimilarLength) {
+      const sim = trigramSimilarity(input.assistantText, input.previousText);
+      if (sim >= REPETITION.similarityThreshold) {
+        return `cosmetic churn: wrote files but the reply is ~${Math.round(sim * 100)}% identical to the previous iteration`;
+      }
+    }
+    return undefined;
+  }
   if ((input.gitCommitCount ?? 0) > 0) return undefined;
   if ((input.specItemProgressCount ?? 0) > 0) return undefined;
   if (forwardTransitionPaired(input)) return undefined;

package/extensions/loops/goal.ts

@@ -169,6 +169,9 @@ import {
   LOOP_DEFAULTS,
   resolveSpecFiles,
   respecTarget,
+  topOpenAuditFinding,
+  specFileHash,
+  countCheckedSpecItems,
   auditMeasureCmd,
   auditTarget,
   AUDIT_PLATEAU_MAX_REPRIEVES,
@@ -1382,10 +1385,24 @@ async function fanOutListAuditFindings(ctx: ExtensionContext): Promise<void> {
   // hundreds of items on a single Confirm.
   const fresh = open.filter((f) => !queuedText.includes(f.text.slice(0, 60))).slice(0, 50);
   const alreadyQueued = open.length - fresh.length;
+  // v0.33.3: DECIDE findings are RAISED TO THE USER as real questions
+  // (hegemon 2026-07-31: a truncated notify left the user typing "decide
+  // what" into the void). The orchestrator can't call ask_user_question —
+  // the agent can — so the full untruncated findings go to the agent as a
+  // steer with the raise + record protocol. Fires BEFORE the queueing
+  // early-returns below: decisions need answers even when nothing new
+  // queued or the fan-out was declined.
+  if (decisions.length > 0) {
+    const decList = decisions.slice(0, 8).map((d, i) => `${i + 1}. ${d.slice(0, 500)}`).join("\n");
+    extensionApi?.sendUserMessage(
+      `[DECIDE FINDINGS — user decisions needed] The audit surfaced ${decisions.length} DECIDE finding(s) — direction calls only the user can make (a decision is not a task, so they were NOT queued):\n${decList}\nRaise them to the user NOW with ask_user_question — one question per finding, options from the finding's own two sides plus "Defer" (prose numbered list if ask_user_question is unavailable; Esc = Defer). Then record every answer in ${AUDIT_FINDINGS_REL}: replace the "- [?]" line with "- [x] DECIDED: <what was chosen> (<date>)" (or "- [x] DEFERRED") so it stops re-surfacing, and queue any chosen work with list_add — do NOT start the work inline.`,
+      { deliverAs: ctx.isIdle() ? "followUp" : "steer" },
+    );
+    appendLedger(ctx.cwd, "list_audit_decisions_raised", { decisions: decisions.length });
+  }
   const decideNote =
     decisions.length > 0
-      ? `\n${decisions.length} DECIDE finding(s) need YOU (not queued — a decision is not a task):\n` +
-        decisions.slice(0, 10).map((d) => `  ? ${d.slice(0, 110)}`).join("\n")
+      ? ` ${decisions.length} DECIDE finding(s) need YOU — raising them as questions now (not queued — a decision is not a task).`
       : "";
   if (fresh.length === 0) {
     ctx.ui.notify(
@@ -2614,7 +2631,7 @@ async function runGit(ctx: ExtensionContext, args: string[]): Promise<{ ok: bool
   }
 }
 
-function loopPrompt(loop: LoopState, regressionNote: string, strategyNote: string, boundsNote: string, interventionNote = "", variantNote = ""): string {
+function loopPrompt(loop: LoopState, regressionNote: string, strategyNote: string, boundsNote: string, interventionNote = "", variantNote = "", hypothesisNote = "", refineHintNote = ""): string {
   // v0.23.0: metricless loops get their own prompt — no metric section,
   // anti-doorknob rules instead of anti-gaming rules.
   const metricless = !loop.measureCmd;
@@ -2641,7 +2658,9 @@ function loopPrompt(loop: LoopState, regressionNote: string, strategyNote: strin
     .replace(/\$\{STRATEGY_NOTE\}/g, strategyNote)
     .replace(/\$\{BOUNDS_NOTE\}/g, boundsNote)
     .replace(/\$\{INTERVENTION_NOTE\}/g, interventionNote)
-    .replace(/\$\{VARIANT_NOTE\}/g, variantNote);
+    .replace(/\$\{VARIANT_NOTE\}/g, variantNote)
+    .replace(/\$\{HYPOTHESIS_NOTE\}/g, hypothesisNote)
+    .replace(/\$\{REFINE_HINT\}/g, refineHintNote);
 }
 
 function scheduleLoopTick(ctx: ExtensionContext): void {
@@ -2693,7 +2712,13 @@ function sendLoopTurn(): void {
   // Strategy rotation (from pi-loop-mode's one good idea): one stall before
   // the plateau window closes, stop polishing and change approach entirely.
   const strategyNote = loop.stallCount >= loop.plateauWindow - 1 && loop.stallCount > 0
-    ? "**You are one stall from a plateau stop. Small tweaks are not working — try a FUNDAMENTALLY different approach: different file, different technique, or revert and rethink the angle of attack.**"
+    ? "**You are one stall from a plateau stop. Small tweaks are not working — try a FUNDAMENTALLY different approach: different file, different technique, or revert and rethink the angle of attack.**" +
+      // v0.33.2: a metric flat AT BEST may mean the spec stopped capturing
+      // "better" — the loop holds the evidence, so it says so (was: the
+      // prompt said "call propose_loop_refine" but the loop never suggested it).
+      (loop.lastValue !== null && loop.lastValue === loop.bestValue
+        ? " **The metric has been flat at best — if the spec no longer captures 'better' (saturated metric, drifted target), call propose_loop_refine.**"
+        : "")
     : "";
   // v0.15.0: arbitrary bounds (never "completion") — surface what's armed.
   // v0.23.0: for metricless loops the bounds are the ONLY stop (no
@@ -2724,12 +2749,19 @@ function sendLoopTurn(): void {
   // v0.24.0: identical prompts invite identical answers — rotate the base
   // instruction (metricless loops; metric loops already vary via values).
   const variantNote = metricless ? continueVariant(loop.iteration) : "";
+  // v0.33.2: one-shot prompt payloads, consumed on use.
+  const hypothesisNote = loop.hypothesisFeedback ?? "";
+  if (hypothesisNote) loop.hypothesisFeedback = undefined;
+  const refineHintNote = loop.refineHint
+    ? `**The operator suggests refining the spec:** ${loop.refineHint} — if the current spec no longer captures "better", call propose_loop_refine (target and/or measureCmd${loop.specFile ? " and/or specText/specAppend" : ""}); if it still stands, say why in one line and keep working.`
+    : "";
+  if (refineHintNote) loop.refineHint = undefined;
   try {
     let loopResync = "";
     if (postCompactResyncPending) { try { loopResync = buildPostCompactResync(); } catch { loopResync = ""; } } // v0.33.1
     extensionApi.sendMessage({
       customType: GOAL_EVENT_ENTRY,
-      content: loopResync + loopPrompt(loop, regressionNote, strategyNote, boundsNote, interventionNote, variantNote),
+      content: loopResync + loopPrompt(loop, regressionNote, strategyNote, boundsNote, interventionNote, variantNote, hypothesisNote, refineHintNote),
       display: false,
     }, { triggerTurn: true, deliverAs: "followUp" });
     if (loopResync) postCompactResyncPending = false; // consumed only by a landed send
@@ -2800,6 +2832,23 @@ async function runLoopTick(ctx: ExtensionContext, event?: any): Promise<void> {
       }
     } catch { /* no ledger yet */ }
   }
+  // v0.33.2: respec spec drift + checkbox progress — hash compared per
+  // tick (external edits ledger spec_updated); newly checked boxes emit
+  // the spec_item_progress signal the stuck gate already consumes (it was
+  // consumed-but-never-emitted until now).
+  if (loop.specFile) {
+    const hash = specFileHash(loop.specFile);
+    if (hash && loop.specHash && loop.specHash !== hash) {
+      appendLedger(ctx.cwd, "spec_updated", { via: "external", iteration: loop.iteration });
+      ctx.ui.notify("Spec file changed mid-loop — drift ledgered (spec_updated).", "info");
+    }
+    if (hash) loop.specHash = hash;
+    const checked = countCheckedSpecItems(loop.specFile);
+    if (checked !== null && loop.specChecked !== undefined && checked > loop.specChecked) {
+      appendLedger(ctx.cwd, "spec_item_progress", { iteration: loop.iteration, newlyChecked: checked - loop.specChecked, totalChecked: checked });
+    }
+    if (checked !== null) loop.specChecked = checked;
+  }
   const iterSignals = {
     fileWrites: loop.iterMetrics?.fileWrites ?? 0,
     gitCommits,
@@ -2839,6 +2888,26 @@ async function runLoopTick(ctx: ExtensionContext, event?: any): Promise<void> {
     loop.lastStuckReason = undefined;
   }
   let outcome: LoopTickOutcome = metricless ? applyMetriclessTick(loop, nowIso()) : applyMeasurement(loop, value, nowIso());
+  // v0.33.2: close the hypothesis feedback loop — the prediction went into
+  // the ledger; now the VERDICT rides the next iteration's prompt.
+  if (loop.lastHypothesis) {
+    const h = loop.history;
+    const cur = h.length >= 1 ? h[h.length - 1]!.value : null;
+    const prev = h.length >= 2 ? h[h.length - 2]!.value : null;
+    if (metricless || cur === null) {
+      loop.hypothesisFeedback = `Last iteration you predicted: "${loop.lastHypothesis}". ${metricless ? "Metricless loop — no number to verify it against; say honestly whether the prediction landed." : "The measure printed no number — the prediction is unverifiable."}`;
+    } else {
+      const moved = prev === null
+        ? `first measurement ${cur}`
+        : cur === prev
+          ? `flat at ${cur}`
+          : loop.direction === "min"
+            ? (cur < prev ? `improved ${prev} → ${cur}` : `regressed ${prev} → ${cur}`)
+            : (cur > prev ? `improved ${prev} → ${cur}` : `regressed ${prev} → ${cur}`);
+      loop.hypothesisFeedback = `Last iteration you predicted: "${loop.lastHypothesis}". Result: metric ${moved} (best ${loop.bestValue}).`;
+    }
+  }
+  loop.lastHypothesis = hypothesis;
   persistState(ctx);
   appendLedger(ctx.cwd, "loop_measured", {
     iteration: loop.iteration,
@@ -2892,7 +2961,8 @@ async function runLoopTick(ctx: ExtensionContext, event?: any): Promise<void> {
           loop.stopReason = undefined;
           loop.stallCount = 0;
           loop.auditPlateauReprieves = reprieves;
-          loop.auditReprieveNote = `PLATEAU REPRIEVE (${reprieves}/${AUDIT_PLATEAU_MAX_REPRIEVES}): ${open} finding(s) still OPEN in ${AUDIT_FINDINGS_REL} — the plateau stop does not fire while the well isn't dry. Stop hunting and stop narrating: pick the smallest OPEN finding and CLOSE it this iteration (fix commit + checked box). ${AUDIT_PLATEAU_MAX_REPRIEVES - reprieves} reprieve(s) remain.`;
+          const topFinding = topOpenAuditFinding(ctx.cwd); // v0.33.2: name what to close, not just the count
+          loop.auditReprieveNote = `PLATEAU REPRIEVE (${reprieves}/${AUDIT_PLATEAU_MAX_REPRIEVES}): ${open} finding(s) still OPEN in ${AUDIT_FINDINGS_REL} — the plateau stop does not fire while the well isn't dry. Stop hunting and stop narrating: pick the smallest OPEN finding and CLOSE it this iteration (fix commit + checked box).${topFinding ? ` Top open: ${topFinding}` : ""} ${AUDIT_PLATEAU_MAX_REPRIEVES - reprieves} reprieve(s) remain.`;
           persistState(ctx);
           appendLedger(ctx.cwd, "audit_plateau_reprieve", { open, reprieves, best: loop.bestValue });
           ctx.ui.notify(`Audit loop plateau reprieve (${reprieves}/${AUDIT_PLATEAU_MAX_REPRIEVES}): ${open} open findings — the well isn't dry, continuing.`, "info");
@@ -2951,6 +3021,9 @@ interface LoopConfig {
   deferBaseline?: boolean;
   /** v0.29.10: audit loops get audit-flavoured regression wording. */
   kind?: "audit";
+  /** v0.33.2: respec loops carry their spec file (drift detection,
+   * checkbox progress, refine specText writes). */
+  specFile?: string;
 }
 
 /** Shared loop-start path: /loop start AND propose_loop_draft (after Confirm). */
@@ -3017,6 +3090,9 @@ async function startLoopFromConfig(ctx: ExtensionContext, cfg: LoopConfig): Prom
       branchName,
       originalBranch,
       toolSameRepeat: cfg.toolSameRepeat,
+      specFile: cfg.specFile,
+      specHash: cfg.specFile ? specFileHash(cfg.specFile) ?? undefined : undefined,
+      specChecked: cfg.specFile ? countCheckedSpecItems(cfg.specFile) ?? undefined : undefined,
       iterMetrics: { fileWrites: 0, iterationStartAt: nowIso() },
     },
   };
@@ -3135,6 +3211,28 @@ async function cmdLoop(args: string, ctx: ExtensionContext): Promise<void> {
 
   // v0.28.14: /loop cancel is a first-class alias — users reached for
   // /goal cancel to kill loops because "cancel" is the verb they know.
+  if (sub === "refine" || sub === "polish") {
+    // v0.33.2: the operator's respec verb. The refine flow stays
+    // agent-proposed + user-confirmed (propose_loop_refine) — this command
+    // queues the operator's suggestion into the next iteration's prompt.
+    // ("polish" accepted as an alias: the widget footer advertised it
+    // before the command existed — now it does.)
+    if (!isLoopActive()) {
+      ctx.ui.notify("No active loop to refine — /loop start first.", "warning");
+      return;
+    }
+    const hint = rest.trim();
+    if (!hint) {
+      ctx.ui.notify("Usage: /loop refine <what the spec should capture better> — the suggestion rides the next iteration's prompt; the agent proposes via propose_loop_refine and you confirm.", "info");
+      return;
+    }
+    state.loop!.refineHint = hint.slice(0, 300);
+    persistState(ctx);
+    appendLedger(ctx.cwd, "loop_refine_hint", { iteration: state.loop!.iteration, hint: state.loop!.refineHint });
+    ctx.ui.notify("Refine hint queued — it rides the next iteration's prompt.", "info");
+    return;
+  }
+
   if (sub === "stop" || sub === "cancel") {
     if (!state.loop) {
       ctx.ui.notify("No loop to stop.", "info");
@@ -3273,6 +3371,7 @@ async function cmdLoop(args: string, ctx: ExtensionContext): Promise<void> {
       maxIterations: 0,
       branch: false,
       force: false,
+      specFile: specPath, // v0.33.2
     });
     return;
   }
@@ -4124,12 +4223,14 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
     parameters: Type.Object({
       target: Type.Optional(Type.String({ description: "The sharpened target text (omit to keep the current target)" })),
       measureCmd: Type.Optional(Type.String({ description: "The new measure command printing ONE number (omit to keep the current metric)" })),
+      specText: Type.Optional(Type.String({ description: "v0.33.2: full replacement text for the loop's spec file (respec loops only) — the orchestrator owns the write on user confirm" })),
+      specAppend: Type.Optional(Type.String({ description: "v0.33.2: lines to append to the loop's spec file (respec loops only)" })),
       rationale: Type.String({ description: "Why the current spec no longer captures 'better' — shown to the user in the Confirm dialog" }),
     }),
     async execute(_id, params, _signal, _onUpdate, execCtx) {
       const foreign4 = foreignToolGuard(execCtx);
       if (foreign4) return { content: [{ type: "text", text: foreign4 }], details: {} };
-      const p = params as { target?: string; measureCmd?: string; rationale: string };
+      const p = params as { target?: string; measureCmd?: string; specText?: string; specAppend?: string; rationale: string };
       const liveCtx = (execCtx as ExtensionContext | undefined) ?? ctx;
       const loop = state.loop;
       if (!loop?.active) {
@@ -4142,8 +4243,12 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
       if (!loop.measureCmd && p.measureCmd?.trim()) {
         return { content: [{ type: "text", text: "This loop is metricless — refining it into a measured loop isn't supported. /loop stop, then /loop start with a metric." }], details: {} };
       }
-      if (newTarget === loop.target && newMeasure === loop.measureCmd) {
-        return { content: [{ type: "text", text: "Refinement proposed no changes — provide a new target, a new measureCmd, or both." }], details: {} };
+      const specChange = (p.specText?.trim() || p.specAppend?.trim()) ? true : false;
+      if (specChange && !loop.specFile) {
+        return { content: [{ type: "text", text: "This loop has no spec file (specText/specAppend apply to /loop respec loops). Refine the target instead." }], details: {} };
+      }
+      if (newTarget === loop.target && newMeasure === loop.measureCmd && !specChange) {
+        return { content: [{ type: "text", text: "Refinement proposed no changes — provide a new target, a new measureCmd, a spec change, or any combination." }], details: {} };
       }
       // Measure change → orchestrator test-runs the new command first.
       let newBaseline: number | null = null;
@@ -4174,7 +4279,7 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
           confirmed = (await confirmDraft(
             liveCtx,
             "Confirm loop spec refinement",
-          `Rationale: ${p.rationale}\n\nTarget:\n  old: ${loop.target.slice(0, 120)}\n  new: ${newTarget.slice(0, 120)}\n\nMeasure:\n  old: ${loop.measureCmd}\n  new: ${newMeasure}${newMeasure !== loop.measureCmd ? `\n  test-run: ${testOutput.slice(0, 120)} → ${newBaseline}` : ""}\n\nThe loop keeps running against the refined spec (iteration ${loop.iteration} so far). Apply?`,
+          `Rationale: ${p.rationale}\n\nTarget:\n  old: ${loop.target.slice(0, 120)}\n  new: ${newTarget.slice(0, 120)}\n\nMeasure:\n  old: ${loop.measureCmd}\n  new: ${newMeasure}${newMeasure !== loop.measureCmd ? `\n  test-run: ${testOutput.slice(0, 120)} → ${newBaseline}` : ""}${specChange ? `\n\nSpec file (${loop.specFile}):\n  ${p.specText?.trim() ? `REPLACE with ${p.specText!.trim().length} chars` : ""}${p.specText?.trim() && p.specAppend?.trim() ? " + " : ""}${p.specAppend?.trim() ? `APPEND: ${p.specAppend!.trim().slice(0, 120)}` : ""}` : ""}\n\nThe loop keeps running against the refined spec (iteration ${loop.iteration} so far). Apply?`,
           )) === "yes";
         } catch {
           confirmed = false;
@@ -4191,9 +4296,22 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
         oldMeasureCmd: loop.measureCmd ?? "",
         newMeasureCmd: newMeasure,
       }, newBaseline);
+      // v0.33.2: the orchestrator owns the spec write (honesty stays
+      // inspectable — the agent never edits the spec it's judged against
+      // outside a confirmed refine).
+      if (specChange && loop.specFile) {
+        try {
+          if (p.specText?.trim()) fs.writeFileSync(loop.specFile, p.specText.trim() + "\n");
+          if (p.specAppend?.trim()) fs.appendFileSync(loop.specFile, (p.specText?.trim() ? "" : "\n") + p.specAppend.trim() + "\n");
+          loop.specHash = specFileHash(loop.specFile) ?? undefined;
+          appendLedger(liveCtx.cwd, "spec_updated", { via: "refine", iteration: loop.iteration, replaced: Boolean(p.specText?.trim()), appended: Boolean(p.specAppend?.trim()) });
+        } catch (e) {
+          return { content: [{ type: "text", text: `Spec file write failed: ${String(e).slice(0, 200)}. The target/measure refinement was applied; re-propose the spec change.` }], details: {} };
+        }
+      }
       persistState(liveCtx);
-      appendLedger(liveCtx.cwd, "loop_refined", { iteration: loop.iteration, newTarget, newMeasureCmd: newMeasure, newBaseline });
-      liveCtx.ui.notify(`Loop spec refined at iteration ${loop.iteration}.${newBaseline !== null ? ` New baseline: ${newBaseline}.` : ""}`, "info");
+      appendLedger(liveCtx.cwd, "loop_refined", { iteration: loop.iteration, newTarget, newMeasureCmd: newMeasure, newBaseline, specChanged: specChange || undefined });
+      liveCtx.ui.notify(`Loop spec refined at iteration ${loop.iteration}.${newBaseline !== null ? ` New baseline: ${newBaseline}.` : ""}${specChange ? " Spec file updated." : ""}`, "info");
       return { content: [{ type: "text", text: "Refinement confirmed and applied. Continue improving against the NEW spec — one small change per turn." }], details: {} };
     },
   }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-list-loop-audit",
-  "version": "0.33.1",
+  "version": "0.33.3",
   "description": "Goal. Loop. Audit. Done. \u2014 a pi-coding-agent extension that supervises long-running work, with isolated auditor on each completion. Beat bamboozling by design: the auditor runs in a fresh session with no extensions, no skills, no editor \u2014 only the read tools needed to verify your goal.",
   "license": "MIT",
   "author": "dracon",

package/prompts/goal-loop-forever-metricless.md

@@ -31,6 +31,8 @@ fails, retry with a different approach — just continue, don't stall the loop
 asking permission. You remain the single writer: apply the edit yourself.
 
 ${INTERVENTION_NOTE}
+${HYPOTHESIS_NOTE}
+${REFINE_HINT}
 ${REGRESSION_NOTE}
 ${STRATEGY_NOTE}
 

package/prompts/goal-loop-forever.md

@@ -35,6 +35,8 @@ fails, retry with a different approach — just continue, don't stall the loop
 asking permission. You remain the single writer: apply the edit yourself.
 
 ${INTERVENTION_NOTE}
+${HYPOTHESIS_NOTE}
+${REFINE_HINT}
 ${REGRESSION_NOTE}
 ${STRATEGY_NOTE}