pi-soly 2.1.1 → 2.1.2

package/README.md

@@ -29,6 +29,7 @@ Restart pi (`/reload`), and you have:
 - **Project management** — plans, state, phases, decisions
 - **Workflow engine** — runs inline (no subagent plugin). The model proposes the next step and drives it via the `soly_workflow` tool on your plain-language intent; the verbs `soly discuss` · `plan` · `execute` · `verify` · `pause`/`resume` still work as text
 - **Self-review loop** — `soly verify` re-reviews the work until "No issues found."
+- **Goal-aware verification** — at the end of every `soly execute` (task / plan / phase plan-level), the worker reads PLAN.md's `## Goal` + `## Acceptance` and judges each item against `git diff`. A `## Status` section is appended to PLAN.md with a PASS / BLOCKED verdict. On `BLOCKED` the worker halts before calling `soly done` — so you can't ship a plan whose goal isn't actually met.
 - **Visual chrome** — native footer, equalizer working spinner with live telemetry, gradient welcome banner
 - **Rules & docs modal** — `/rules` and `/docs` open a fuzzy list + preview panel (no chat dumps)
 - **Mandatory rules** — strict-mode directives injected every turn

package/commands.ts

@@ -171,7 +171,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 				const rules = getRules();
 				const overridden = getOverridden();
 				if (rules.length === 0 && overridden.length === 0) {
-					ui.notify("no rules loaded from any source", "info");
+
 					return;
 				}
 				// Rich modal in the TUI; plain select elsewhere (RPC/print).
@@ -205,17 +205,11 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 					if (choice < rules.length) {
 						const rel = rules[choice];
 						if (rel) {
-							ui.notify(
-								`[${rel.sourceLabel}] ${rel.relPath}\n\n${rel.body}`,
-								"info",
-							);
+
 						}
 					} else {
 						const idx = choice - rules.length;
-						ui.notify(
-							`overridden: ${overridden[idx]} (skipped — a higher-priority source defines this rule)`,
-							"info",
-						);
+
 					}
 				}
 				return;
@@ -224,7 +218,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 			if (sub === "analytics") {
 				const rules = getRules();
 				const analytics = analyzeRules(rules, CONTEXT_WINDOW_TOKENS);
-				ui.notify(formatAnalyticsFull(analytics), "info");
+
 				return;
 			}
 
@@ -234,7 +228,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 				// Surfaces context bloat and verifies rules will actually fire.
 				const rules = getRules();
 				const stats = buildRulesContextStats(rules, CONTEXT_WINDOW_TOKENS);
-				ui.notify(formatRulesContextStats(stats), "info");
+
 				return;
 			}
 
@@ -250,13 +244,13 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 					ui.notify(`Rule not found: ${target}`, "error");
 					return;
 				}
-				ui.notify(`[${rule.sourceLabel}] ${rule.relPath}\n\n${rule.body}`, "info");
+
 				return;
 			}
 
 			if (sub === "reload") {
 				refreshRules();
-				ui.notify(`Reloaded ${getRules().length} rules`, "info");
+
 				updateStatus(ui);
 				return;
 			}
@@ -274,7 +268,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 					return;
 				}
 				rule.enabled = sub === "enable";
-				ui.notify(`${rule.relPath} ${sub}d`, "info");
+
 				updateStatus(ui);
 				return;
 			}
@@ -289,10 +283,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 						count++;
 					}
 				}
-				ui.notify(
-					`${count} rule(s) ${enable ? "enabled" : "disabled"} (${rules.length} total)`,
-					enable ? "info" : "warning",
-				);
+
 				updateStatus(ui);
 				return;
 			}
@@ -313,7 +304,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 				categories.map((c) => `${c.name} — ${c.description}`),
 			);
 			if (choice == null) {
-				ui.notify("cancelled", "info");
+
 				return;
 			}
 			const cat = categories[choice];
@@ -359,11 +350,7 @@ What must the LLM do?
 `;
 			try {
 				fs.writeFileSync(filePath, template, "utf-8");
-				ui.notify(
-					`soly: created ${path.relative(cwd, filePath)}\n\n` +
-						`Next: edit the file (description, globs, body), then \`/rules reload\` to load it.`,
-					"info",
-				);
+
 				refreshRules();
 				updateStatus(ui);
 			} catch (e) {
@@ -385,7 +372,7 @@ What must the LLM do?
 					ui.notify(`soly: only http(s) URLs are supported (got ${parsed.protocol})`, "error");
 					return;
 				}
-				ui.notify(`soly: downloading ${url}…`, "info");
+
 				const res = await fetch(url, {
 					signal: AbortSignal.timeout(10_000),
 					headers: { "user-agent": "soly-extension/1.0" },
@@ -420,16 +407,13 @@ What must the LLM do?
 						`${fileName} already exists. Overwrite?`,
 					);
 					if (!overwrite) {
-						ui.notify("soly: add cancelled", "info");
+
 						return;
 					}
 				}
 				fs.writeFileSync(targetFile, text, "utf-8");
 				refreshRules();
-				ui.notify(
-					`soly: installed ${path.relative(process.cwd(), targetFile)} (${(text.length / 1024).toFixed(1)}KB)`,
-					"info",
-				);
+
 				updateStatus(ui);
 			} catch (e) {
 				ui.notify(`soly: download failed: ${(e as Error).message}`, "error");
@@ -466,7 +450,7 @@ What must the LLM do?
 			if (sub === "list") {
 				const docs = getIntentDocs();
 				if (docs.length === 0) {
-					ui.notify("no intent docs found in .agents/docs/ — drop your vision/domain docs there", "info");
+
 					return;
 				}
 				if (ctx.mode === "tui") {
@@ -493,15 +477,11 @@ What must the LLM do?
 				const docs = getIntentDocs();
 				const inlineBodies: IntentInlineDoc[] = loadInlineIntentBodies(docs);
 				const stats = buildIntentStats(docs, inlineBodies);
-				ui.notify(formatIntentStats(stats), "info");
+
 				return;
 			}
 
-			ui.notify(
-				`Usage: /docs [list|stats] — open the docs panel, or show the context breakdown\n` +
-				`Found ${getIntentDocs().length} doc(s) loaded.`,
-				"info",
-			);
+
 		},
 	});
 
@@ -543,7 +523,7 @@ What must the LLM do?
 
 			const state = getState();
 			if (!state.exists) {
-				ui.notify("soly: no .agents/ project here — run `/soly init` to scaffold one", "info");
+
 				return;
 			}
 
@@ -557,7 +537,7 @@ What must the LLM do?
 					content.length > MAX
 						? `${content.slice(0, MAX)}\n\n[...truncated, file is ${content.length} chars]`
 						: content;
-				ui.notify(`${label}\n\n${truncated}`, "info");
+
 			};
 
 			type SolySub = {
@@ -584,7 +564,7 @@ What must the LLM do?
 				};
 				const state = getState();
 				if (!state.exists) {
-					ui.notify("soly: no .agents/ project here — run `/soly init` to scaffold one", "info");
+
 					return;
 				}
 				switch (verb) {
@@ -624,7 +604,7 @@ What must the LLM do?
 						return;
 					}
 					default:
-						ui.notify(`soly: workflow '${verb}' not yet wired into slash command`, "info");
+
 						return;
 				}
 			};
@@ -651,7 +631,7 @@ What must the LLM do?
 						out.push(`  - project: edit \`${state.solyDir}/soly.json\` directly`);
 						out.push(`  - global:  edit \`~/.agents/soly.json\``);
 						out.push("After editing, run /soly reload to re-pick up changes.");
-						ui.notify(out.join("\n"), "info");
+
 					},
 				},
 				position: {
@@ -659,21 +639,9 @@ What must the LLM do?
 					run: () => {
 						const s = getState();
 						if (s.position) {
-							ui.notify(
-								[
-									`milestone: ${s.milestone}${s.milestoneName ? ` — ${s.milestoneName}` : ""}`,
-									`phase:     ${s.position.phase}`,
-									`plan:      ${s.position.plan}`,
-									`status:    ${s.position.status}`,
-									`progress:  ${buildProgressBar(s.progress.percent, 20)} ${s.progress.percent}% (${s.progress.completedPhases}/${s.progress.totalPhases} phases, ${s.progress.completedPlans}/${s.progress.totalPlans} plans)`,
-								].join("\n"),
-								"info",
-							);
+
 						} else {
-							ui.notify(
-								`milestone: ${s.milestone} — no position set in STATE.md`,
-								"info",
-							);
+
 						}
 					},
 				},
@@ -735,16 +703,7 @@ What must the LLM do?
 					description: "progress bar + counts",
 					run: () => {
 						const s = getState();
-						ui.notify(
-							[
-								`milestone: ${s.milestone}${s.milestoneName ? ` — ${s.milestoneName}` : ""}`,
-								`status:    ${s.status}`,
-								`progress:  ${buildProgressBar(s.progress.percent, 30)} ${s.progress.percent}%`,
-								`phases:    ${s.progress.completedPhases}/${s.progress.totalPhases}`,
-								`plans:     ${s.progress.completedPlans}/${s.progress.totalPlans}`,
-							].join("\n"),
-							"info",
-						);
+
 					},
 				},
 				phases: {
@@ -752,7 +711,7 @@ What must the LLM do?
 					run: () => {
 						const phases = getState().phases;
 						if (phases.length === 0) {
-							ui.notify("soly: no phases found", "info");
+
 							return;
 						}
 						const current = getState().currentPhase?.number;
@@ -761,7 +720,7 @@ What must the LLM do?
 							const cr = (p.contextExists ? "C" : "·") + (p.researchExists ? "R" : "·");
 							return `${marker} ${String(p.number).padStart(2, "0")}. ${p.name}  [${cr}]  plans=${p.planCount}`;
 						});
-						ui.notify(`phases:\n\n${lines.join("\n")}`, "info");
+
 					},
 				},
 				tasks: {
@@ -769,7 +728,7 @@ What must the LLM do?
 					run: () => {
 						const s = getState();
 						if (s.tasks.length === 0) {
-							ui.notify("soly: no tasks found in .agents/features/*/tasks/", "info");
+
 							return;
 						}
 						const byFeature = new Map<string, typeof s.tasks>();
@@ -788,7 +747,7 @@ What must the LLM do?
 							}
 							out.push("");
 						}
-						ui.notify(out.join("\n"), "info");
+
 					},
 				},
 				task: {
@@ -819,7 +778,7 @@ What must the LLM do?
 						if (summaryBody) {
 							showFile("SUMMARY.md", summaryBody);
 						} else {
-							ui.notify("SUMMARY.md: not found (task not yet executed)", "info");
+
 						}
 					},
 				},
@@ -828,14 +787,14 @@ What must the LLM do?
 					run: () => {
 						const features = getState().features;
 						if (features.length === 0) {
-							ui.notify("soly: no features found in .agents/features/", "info");
+
 							return;
 						}
 						const lines = features.map((f) => {
 							const rm = f.readmeExists ? "R" : "·";
 							return `  ${f.name.padEnd(28)} tasks=${f.taskCount}  [${rm}]`;
 						});
-						ui.notify(`features (${features.length}):\n\n${lines.join("\n")}`, "info");
+
 					},
 				},
 				milestone: {
@@ -843,7 +802,7 @@ What must the LLM do?
 					run: () => {
 						const s = getState();
 						if (!s.milestone || s.milestone === "—") {
-							ui.notify("soly: no milestone set in STATE.md frontmatter", "info");
+
 							return;
 						}
 						const candidates = [
@@ -869,10 +828,7 @@ What must the LLM do?
 						refreshState();
 						updateStatus(ui);
 						const s = getState();
-						ui.notify(
-							`soly: reloaded — ${s.milestone} · ${s.phases.length} phases`,
-							"info",
-						);
+
 					},
 				},
 				// ------------------------------------------------------------------

package/init.ts

@@ -223,7 +223,7 @@ export async function initSolyProject(
 			["minimal", "web-app", "library", "cli"],
 		);
 		if (!pick) {
-			ui.notify("soly init: cancelled", "info");
+
 			return { created: false, template: null, projectName };
 		}
 		template = pick as InitTemplate;
@@ -237,7 +237,7 @@ export async function initSolyProject(
 			`Create .agents/ structure in:\n  ${cwd}\n\nProject name: ${projectName}`,
 		);
 		if (!ok) {
-			ui.notify("soly init: cancelled", "info");
+
 			return { created: false, template: null, projectName };
 		}
 	}
@@ -288,11 +288,7 @@ export async function initSolyProject(
 	for (const extra of TEMPLATE_EXTRAS[template]) {
 		created.push(`.agents/${extra.file}`);
 	}
-	ui.notify(
-		`soly init: done (${template}). Created:\n  - ${created.join("\n  - ")}\n\n` +
-			`Next:\n  1. Edit \`.agents/docs/vision.md\`\n  2. \`/plan 1\` to start the first phase`,
-		"info",
-	);
+
 	return { created: true, template, projectName: safeProjectName };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Project management + workflow framework for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker, native footer + welcome chrome — one npm install, zero config. The LLM drives the workflow inline via the soly_workflow tool — no external subagent plugin.",
   "type": "module",
   "main": "index.ts",

package/workflows/done.ts

@@ -144,7 +144,7 @@ export function buildDoneTransform(
 			pushed = true;
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
-			ui.notify(`soly done: push failed — ${msg}\nPlan was committed but not pushed. Push manually with \`git push -u origin ${branchName}\`.`, "warning");
+
 			return {
 				handled: true,
 				transformedText: `Plan ${branchName} committed locally (${commitHash.slice(0, 7)}), but push failed.\n${msg}`,
@@ -152,7 +152,7 @@ export function buildDoneTransform(
 			};
 		}
 	} else {
-		ui.notify(`soly done: no 'origin' remote — committed locally only. Add a remote and \`git push\` when ready.`, "warning");
+
 	}
 
 	// 4. Draft PR via gh
@@ -174,18 +174,10 @@ export function buildDoneTransform(
 			// gh failed (maybe not authenticated, or PR already exists, etc.)
 			// Don't fail the whole workflow — just report.
 			const msg = err instanceof Error ? err.message : String(err);
-			ui.notify(
-				`soly done: pushed OK, but draft PR creation failed — ${msg}\n` +
-					`Run \`gh pr create --draft --fill\` manually.`,
-				"warning",
-			);
+
 		}
 	} else if (pushed) {
-		ui.notify(
-			`soly done: pushed OK, but \`gh\` CLI not found — draft PR not created.\n` +
-				`Install \`gh\` (https://cli.github.com) and run \`gh pr create --draft --fill\` manually.`,
-			"info",
-		);
+
 	}
 
 	// 5. Done — summarize
@@ -198,7 +190,7 @@ export function buildDoneTransform(
 
 	// (No registry file to update — the plan's git branch IS the source of
 	// truth for "active plans". See PLAN.md / "Out of scope" for the trade-off.)
-	ui.notify(notice, "info");
+
 	return {
 		handled: true,
 		transformedText: notice,

package/workflows/execute.ts

@@ -26,6 +26,23 @@ import {
 	renderPlanSummaryInline,
 	writeIterationContext,
 } from "../iteration.js";
+import { buildVerificationPrompt, parseGoalAndAcceptance } from "./goal-verify.ts";
+
+/**
+ * Append the goal-verification step to a worker close-out block, gated on
+ * whether PLAN.md at `planPath` actually has Goal + Acceptance sections.
+ * If parsing fails (empty/missing sections), we skip the block rather than
+ * inject a malformed prompt — the worker has nothing meaningful to verify.
+ */
+function withGoalCheck(planPath: string, suffix: string): string {
+	try {
+		const r = parseGoalAndAcceptance(planPath);
+		if (!r.ok) return suffix;
+		return buildVerificationPrompt(r, planPath) + suffix;
+	} catch {
+		return suffix;
+	}
+}
 
 /** Resolve <extension>/workflows-data/<name>.md regardless of cwd. */
 function loadWorkflowMarkdown(name: string): string | null {
@@ -225,7 +242,10 @@ Hard rules:
   - Interactive-only rules are NOT in scope here: ${interactiveRules.length > 0 ? interactiveRules.join(", ") : "(none)"}.
 
 When done, confirm the SUMMARY.md was written and the task flipped to \`status: done\`. Then suggest \`soly verify\` to self-review the change with fresh eyes before calling it done.`;
-		return { handled: true, transformedText: instruction };
+		return {
+			handled: true,
+			transformedText: withGoalCheck(path.join(task.dir, "PLAN.md"), instruction),
+		};
 	}
 
 	// === ALL / FEATURE (new dual-mode, sequential in v0.1) ===
@@ -348,7 +368,10 @@ Hard rules:
   - Do not commit unless the workflow tells you to; the user reviews and merges.
 
 When done, suggest \`soly verify\` to self-review with fresh eyes, then \`soly done ${target.raw}\` to open the PR.`;
-		return { handled: true, transformedText: instruction };
+		return {
+			handled: true,
+			transformedText: withGoalCheck(planFile, instruction),
+		};
 	}
 
 	// === PHASE MODE ===
@@ -480,5 +503,12 @@ Hard rules:
 
 When done, confirm STATE.md was updated. Then suggest \`soly verify\` to self-review the work with fresh eyes before calling the phase done.`;
 
-	return { handled: true, transformedText: instruction };
+	// Goal verification only makes sense for plan-level phase execution —
+	// wave-based / task-based execution iterates many plans and has no
+	// single PLAN.md to verify against.
+	const phasePlanPath = isPlanLevel && planFileResolved ? planFileResolved : null;
+	return {
+		handled: true,
+		transformedText: phasePlanPath ? withGoalCheck(phasePlanPath, instruction) : instruction,
+	};
 }

package/workflows/goal-verify.ts

@@ -0,0 +1,297 @@
+// =============================================================================
+// workflows/goal-verify.ts — Goal & Acceptance verification for `soly execute`
+// =============================================================================
+//
+// Reads PLAN.md `## Goal` + `## Acceptance`, hands the LLM a structured
+// "verify against the diff" prompt at end of execute, and lets the worker
+// append a `## Status` section (idempotent, fenced by marker comments).
+//
+// Pure LLM review — no `bun/dotnet/pytest`-style mechanical checks. This
+// plugin is multi-language; mechanical checks would be unreliable. The LLM
+// walks `git diff master..HEAD` itself and judges.
+//
+// Headless-safe by construction: this module MUST NOT import `ask_pro`,
+// `decision_deck`, `@earendil-works/pi-tui`, or call `ctx.ui.custom(...)`.
+// A regression test greps the source for those tokens.
+//
+// Three public surfaces:
+//   1. `parseGoalAndAcceptance(planPath)`   — read PLAN.md, return parsed
+//                                            sections or `{ ok:false, error }`.
+//   2. `buildVerificationPrompt(parsed, planPath)` — instruction string for
+//                                            the execute worker.
+//   3. `appendStatus(planPath, report)`     — idempotent append/replace of
+//                                            the `## Status` section.
+//
+// Pure helpers (`buildStatusSection`, `findMarkerBlock`) are exported for tests.
+// =============================================================================
+
+import * as fs from "node:fs";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type GoalAcceptanceParsed = {
+	ok: true;
+	goal: string;
+	acceptance: string[];
+};
+
+export type GoalAcceptanceError = {
+	ok: false;
+	error: string;
+};
+
+export type GoalAcceptanceResult = GoalAcceptanceParsed | GoalAcceptanceError;
+
+export type StatusAcceptanceItem = {
+	item: string;
+	met: boolean;
+	evidence: string;
+};
+
+export type StatusReport = {
+	goalMet: boolean;
+	acceptance: StatusAcceptanceItem[];
+};
+
+export const STATUS_BEGIN = "<!-- soly:status:begin -->";
+export const STATUS_END = "<!-- soly:status:end -->";
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a PLAN.md and extract the `## Goal` text + each `- [ ]` bullet from
+ * `## Acceptance`. Never throws — returns `{ ok:false, error }` so callers
+ * (the verifier prompt) can surface a clean gap report instead of crashing
+ * the execute worker.
+ *
+ * Tolerates frontmatter at the top of the file. Stops each section at the
+ * next `## ` heading (case-insensitive on the marker). Multiple
+ * `## Acceptance` sections: only the first is used.
+ */
+export function parseGoalAndAcceptance(planPath: string): GoalAcceptanceResult {
+	let raw: string;
+	try {
+		raw = fs.readFileSync(planPath, "utf-8");
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { ok: false, error: `Cannot read PLAN.md at ${planPath}: ${msg}` };
+	}
+
+	// Strip optional frontmatter (--- ... --- at top of file).
+	const body = stripFrontmatter(raw);
+
+	const goalText = extractSectionBody(body, "Goal");
+	if (goalText === null) {
+		return { ok: false, error: "PLAN.md is missing required `## Goal` section." };
+	}
+	if (goalText.trim().length === 0) {
+		return { ok: false, error: "`## Goal` section is empty." };
+	}
+
+	const acceptanceText = extractSectionBody(body, "Acceptance");
+	if (acceptanceText === null) {
+		return { ok: false, error: "PLAN.md is missing required `## Acceptance` section." };
+	}
+
+	const items = extractAcceptanceItems(acceptanceText);
+	if (items.length === 0) {
+		return { ok: false, error: "`## Acceptance` section has no `- [ ]` items." };
+	}
+
+	return { ok: true, goal: goalText.trim(), acceptance: items };
+}
+
+/** Strip YAML frontmatter (`---\n...\n---\n`) at the top of the file. */
+function stripFrontmatter(raw: string): string {
+	const m = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+	return m ? raw.slice(m[0].length) : raw;
+}
+
+/**
+ * Extract the body of the FIRST `## <name>` section: everything from the
+ * heading line (exclusive) up to the next `## ` heading or end of file.
+ * Returns null if the section does not exist. Returns "" if the section
+ * exists but is empty.
+ */
+function extractSectionBody(body: string, name: string): string | null {
+	const lines = body.split(/\r?\n/);
+	const headingRe = new RegExp(`^##\\s+${escapeRegex(name)}\\s*$`);
+	const nextHeadingRe = /^##\s+\S+/;
+	let startIdx = -1;
+	for (let i = 0; i < lines.length; i++) {
+		if (headingRe.test(lines[i] ?? "")) {
+			startIdx = i;
+			break;
+		}
+	}
+	if (startIdx === -1) return null;
+	let endIdx = lines.length;
+	for (let i = startIdx + 1; i < lines.length; i++) {
+		if (nextHeadingRe.test(lines[i] ?? "")) {
+			endIdx = i;
+			break;
+		}
+	}
+	return lines.slice(startIdx + 1, endIdx).join("\n");
+}
+
+/** Pull each `- [ ] <text>` bullet (allowing leading whitespace) from a section body. */
+function extractAcceptanceItems(section: string): string[] {
+	const items: string[] = [];
+	for (const line of section.split(/\r?\n/)) {
+		// Require exactly `[ ]` (one space inside the brackets) — matches the
+		// standard markdown task-list convention. Lines like `- [x] foo` or
+		// `- [] foo` are intentionally NOT accepted: `x` is checked, and `[]`
+		// (no inner space) is a typo we'd rather surface than silently keep.
+		const m = line.match(/^\s*-\s+\[\s\]\s+(.+?)\s*$/);
+		if (m) items.push(m[1]);
+	}
+	return items;
+}
+
+/** Escape a literal string for safe inclusion in a RegExp constructor. */
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the LLM instruction injected at the end of an execute worker block
+ * (task / plan / phase plan-level). The worker is told to read PLAN.md,
+ * walk `git diff master..HEAD`, judge each acceptance item, judge the
+ * Goal as a whole, and append/replace a `## Status` section between the
+ * marker comments.
+ *
+ * `planPathHint` is a textual hint about where PLAN.md lives — typically the
+ * absolute path. The worker resolves it via `read`.
+ */
+export function buildVerificationPrompt(parsed: GoalAcceptanceParsed, planPathHint: string): string {
+	const itemsList = parsed.acceptance.map((a) => `- ${a}`).join("\n");
+	return `
+
+GOAL VERIFICATION (mandatory before close-out):
+
+Before reporting this work as done, verify that the diff actually
+delivers the plan's Goal and meets every Acceptance item. This is a
+hard gate — if it fails, you must NOT call \`soly done\`; you must
+report the gap and stop.
+
+PLAN.md: ${planPathHint}
+
+Goal (verbatim from PLAN.md):
+
+"""
+${parsed.goal}
+"""
+
+Acceptance items (verbatim, ${parsed.acceptance.length} total):
+
+${itemsList}
+
+Steps:
+1. Read ${planPathHint} (use the read tool) to confirm the Goal and
+   Acceptance text.
+2. Run \`git diff master..HEAD\` (or \`git diff origin/master..HEAD\`
+   if no local master) to see what actually changed.
+3. For each Acceptance item above, judge met / not-met. Cite evidence
+   — file:line from the diff, or a short reasoning string.
+4. Judge the Goal as a whole against the actual outcome.
+5. Use the edit tool to append or replace a \`## Status\` section in
+   ${planPathHint}, between the marker comments:
+
+${STATUS_BEGIN}
+## Status
+
+**Goal met:** YES | NO
+
+### Acceptance
+- [x] <item text> — <evidence>
+- [ ] <item text> — GAP: <what is missing>
+
+**Verdict:** PASS | BLOCKED — gaps remain
+${STATUS_END}
+
+   If the markers already exist in the file, replace the content
+   between them. If they don't, append the block at end of file. Do
+   NOT touch any text outside the markers.
+6. If Verdict is BLOCKED: STOP. Do NOT call \`soly done\`. Report the
+   gap inline and list which Acceptance items remain unmet.
+7. If Verdict is PASS: proceed to the close-out steps below.
+
+---
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Status section appender
+// ---------------------------------------------------------------------------
+
+/** Pure: build the Status markdown block between the marker comments. */
+export function buildStatusSection(report: StatusReport): string {
+	const allMet = report.goalMet && report.acceptance.every((a) => a.met);
+	const verdict = allMet ? "PASS" : "BLOCKED — gaps remain";
+	const lines: string[] = [];
+	lines.push(STATUS_BEGIN);
+	lines.push("## Status");
+	lines.push("");
+	lines.push(`**Goal met:** ${report.goalMet ? "YES" : "NO"}`);
+	lines.push("");
+	lines.push("### Acceptance");
+	for (const a of report.acceptance) {
+		const box = a.met ? "[x]" : "[ ]";
+		const tag = a.met ? "— " : "— GAP: ";
+		lines.push(`- ${box} ${a.item} ${tag}${a.evidence}`);
+	}
+	lines.push("");
+	lines.push(`**Verdict:** ${verdict}`);
+	lines.push(STATUS_END);
+	return lines.join("\n");
+}
+
+/**
+ * Find the marker block in `raw`. Returns:
+ *   { begin, end } — slice indices (begin = index of STATUS_BEGIN,
+ *                     end = index AFTER STATUS_END), or null if either
+ *                     marker is missing or the order is wrong.
+ */
+export function findMarkerBlock(raw: string): { begin: number; end: number } | null {
+	const begin = raw.indexOf(STATUS_BEGIN);
+	const endIdx = raw.indexOf(STATUS_END);
+	if (begin === -1 || endIdx === -1 || endIdx < begin) return null;
+	return { begin, end: endIdx + STATUS_END.length };
+}
+
+/**
+ * Append or replace the `## Status` section in PLAN.md. Idempotent: a
+ * second run replaces the previous block (between marker comments)
+ * instead of duplicating content. Never touches text outside the
+ * marker block.
+ */
+export function appendStatus(planPath: string, report: StatusReport): void {
+	const raw = fs.readFileSync(planPath, "utf-8");
+	const section = buildStatusSection(report);
+	const block = findMarkerBlock(raw);
+
+	let next: string;
+	if (block) {
+		// Replace between markers, preserve prefix and suffix content.
+		const before = raw.slice(0, block.begin).replace(/\s+$/, "");
+		const after = raw.slice(block.end).replace(/^\s+/, "");
+		const parts = [before, section];
+		if (after.length > 0) parts.push(after);
+		next = parts.join("\n\n") + "\n";
+	} else {
+		// Append at end of file.
+		const trimmed = raw.replace(/\s+$/, "");
+		next = `${trimmed}\n\n${section}\n`;
+	}
+
+	fs.writeFileSync(planPath, next, "utf-8");
+}

package/workflows/inspect.ts

@@ -248,7 +248,7 @@ export function showDoctor(_cmd: unknown, state: SolyState, ui: InspectUI, confi
 		out.push("");
 		out.push("Warnings present — run `/soly iterations` and `/soly config` to review.");
 	}
-	ui.notify(out.join("\n"), counts.fail > 0 ? "error" : counts.warn > 0 ? "warning" : "info");
+
 }
 
 // ---------------------------------------------------------------------------
@@ -287,10 +287,7 @@ export function showTodos(
 	}
 	const file = findTodosFile(state.solyDir);
 	if (!file) {
-		ui.notify(
-			"soly todos: no todo file found. Install the `pi-todo` extension or write `.agents/todos.json` manually.",
-			"info",
-		);
+
 		return;
 	}
 	let parsed: { todos?: Array<{ content?: string; status?: string; activeForm?: string }> } | null = null;
@@ -301,7 +298,7 @@ export function showTodos(
 		return;
 	}
 	if (!parsed || !Array.isArray(parsed.todos) || parsed.todos.length === 0) {
-		ui.notify("soly todos: list is empty. Use the LLM's `todo_update` tool to add items.", "info");
+
 		return;
 	}
 	const todos = parsed.todos;
@@ -316,7 +313,7 @@ export function showTodos(
 		const suffix = t.status === "in_progress" && typeof t.activeForm === "string" ? ` (${t.activeForm})` : "";
 		lines.push(`  ${mark} ${t.content}${suffix}`);
 	}
-	ui.notify(lines.join("\n"), "info");
+
 }
 
 // ---------------------------------------------------------------------------
@@ -335,7 +332,7 @@ export function showIterations(
 	}
 	const iterDir = path.join(state.solyDir, "iterations");
 	if (!fs.existsSync(iterDir)) {
-		ui.notify("soly iterations: no iterations yet (run soly plan or soly execute first)", "info");
+
 		return;
 	}
 
@@ -362,7 +359,7 @@ export function showIterations(
 		.slice(0, limit);
 
 	if (files.length === 0) {
-		ui.notify("soly iterations: no iteration files found", "info");
+
 		return;
 	}
 
@@ -378,7 +375,7 @@ export function showIterations(
 		out.push("");
 		out.push("Tip: `soly iterations 20` for more, `soly diff iterations <a> <b>` to compare two.");
 	}
-	ui.notify(out.join("\n"), "info");
+
 }
 
 function humanizeAge(ms: number): string {
@@ -444,7 +441,7 @@ export function showDiffIterations(
 		out.push(bodyB);
 		out.push("--- END B ---");
 	}
-	ui.notify(out.join("\n"), "info");
+
 }
 
 // ---------------------------------------------------------------------------
@@ -495,5 +492,5 @@ export function showPhaseDelete(
 	out.push("");
 	out.push("To restore: `mv` it back to .agents/phases/");
 	out.push("To permanently delete: `rm -rf " + dest + "`");
-	ui.notify(out.join("\n"), "info");
+
 }

package/workflows/migrate.ts

@@ -167,6 +167,6 @@ export function buildMigrateTransform(
 			? skipped.map((s) => `  ! ${s.phase}: ${s.reason}`).join("\n") + "\n"
 			: "") +
 		`\nPush and PR the migration branches manually: \`git push origin <branch>\`.`;
-	ui.notify(`soly migrate: ${migrated.length} migrated, ${skipped.length} skipped`, "info");
+
 	return { handled: true, transformedText: notice, migrated, skipped };
 }

package/workflows/new.ts

@@ -164,7 +164,7 @@ export function buildNewTransform(
 	const notice = branchExisted
 		? `Plan '${name}' reused on existing branch ${branchName}.\nPLAN.md was ${planFile}.\nNext: \`soly plan ${branchName}\``
 		: `Plan '${name}' scaffolded on new branch ${branchName}.\nPLAN.md: ${planFile}\nNext: \`soly plan ${branchName}\``;
-	ui.notify(notice, "info");
+
 	return {
 		handled: true,
 		transformedText: notice,

package/workflows/quick.ts

@@ -100,7 +100,7 @@ export function showStatus(
 		}
 	}
 
-	ui.notify(lines.join("\n"), "info");
+
 }
 
 // =============================================================================
@@ -136,7 +136,7 @@ export function showLog(cmd: SolyCommand, state: SolyState, ui: QuickUI): void {
 	const lines = raw.split(/\r?\n/);
 	const decisionsIdx = lines.findIndex((l) => DECISIONS_HEADER.test(l));
 	if (decisionsIdx === -1) {
-		ui.notify("soly log: no Decisions table in STATE.md", "info");
+
 		return;
 	}
 
@@ -151,7 +151,7 @@ export function showLog(cmd: SolyCommand, state: SolyState, ui: QuickUI): void {
 	}
 
 	if (rows.length === 0) {
-		ui.notify("soly log: Decisions table is empty", "info");
+
 		return;
 	}
 
@@ -178,7 +178,7 @@ export function showLog(cmd: SolyCommand, state: SolyState, ui: QuickUI): void {
 		out.push(`           ${r.rationale}`);
 		out.push("");
 	}
-	ui.notify(out.join("\n"), "info");
+
 }
 
 // =============================================================================
@@ -254,5 +254,5 @@ export async function showDiff(
 		}
 	}
 
-	ui.notify(out.join("\n"), "info");
+
 }