pi-soly 0.2.1

package/iteration.ts

@@ -0,0 +1,712 @@
+// =============================================================================
+// iteration.ts — Per-iteration context bundle (B2 of the soly design)
+// =============================================================================
+//
+// Writes a self-contained .md file under `.soly/iterations/` that bundles
+// everything a worker needs for ONE iteration of a plan / task / phase:
+// intent docs, STATE.md, ROADMAP row, phase CONTEXT, phase RESEARCH, up
+// to 3 prior SUMMARYs, and the current PLAN.md (for exec).
+//
+// Why a file (and not just system-prompt injection):
+//   - The bundle is too large for system prompt (intent + CONTEXT +
+//     RESEARCH + prior SUMMARYs + current PLAN ≈ 6–8k tokens)
+//   - File is auditable — humans can inspect what context a worker had
+//   - Resume after `soly pause` is reliable: file persists across sessions
+//   - Worker can re-read sections it forgot without bothering the user
+//
+// Plus a small inline summary (must_haves + anti-patterns) is included in
+// the worker's task string itself, so the worker has the most critical
+// bits available even before opening the file.
+//
+// All worktree writes go to `.soly/iterations/` (under the project's
+// `.soly/`), never to the project root. See workflow markdown templates
+// for the hard rule.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFileSync, readIfExists } from "./core.js";
+
+export type IterationKind = "exec" | "plan" | "discuss" | "pause";
+
+export interface IterationInput {
+	solyDir: string;
+	projectRoot: string;
+	kind: IterationKind;
+	/** Phase number (for plan / discuss / exec-phase). */
+	phaseNumber?: number;
+	/** Plan number within phase (only for kind=exec of a phase plan). */
+	planNumber?: number;
+	/** Task id (only for task-mode execution / planning). */
+	taskId?: string;
+	/** Feature name (only for task-mode). Backfilled from disk if omitted. */
+	feature?: string;
+}
+
+export interface IterationOutput {
+	/** Absolute path to the written file. */
+	filePath: string;
+	/** Path relative to projectRoot (for display in prompts). */
+	relPath: string;
+	/** Filename only. */
+	fileName: string;
+	/** File size in bytes. */
+	bytes: number;
+	/** Estimated tokens. */
+	tokens: number;
+	/** Generation timestamp (ISO 8601). */
+	generatedAt: string;
+}
+
+// ----------------------------------------------------------------------------
+// Section token budgets. Total target: ~6500 tokens (fits comfortably in
+// worker's context window; worker can re-read source files for full content).
+// ----------------------------------------------------------------------------
+
+const SECTION_BUDGETS = {
+	intent: 500,
+	state: 400,
+	roadmap: 400,
+	context: 1500,
+	research: 1500,
+	summaries: 1800, // up to 3 × 600
+	plan: 2500,
+	antipatterns: 500,
+	featureReadme: 800,
+} as const;
+
+/** Slug-shaped ISO timestamp suitable for filenames (e.g. 20260614T201530Z). */
+export function timestampSlug(): string {
+	return new Date()
+		.toISOString()
+		.replace(/[-:]/g, "")
+		.replace(/\.\d+Z$/, "Z");
+}
+
+/** Truncate text to roughly N tokens (1 token ≈ 4 chars). */
+function truncate(text: string, maxTokens: number, note?: string): string {
+	const maxChars = maxTokens * 4;
+	if (text.length <= maxChars) return text;
+	const footer = note
+		? `\n\n<!-- ${note}; truncated at ${maxTokens} tokens (${text.length} chars) -->`
+		: `\n\n<!-- truncated at ${maxTokens} tokens (${text.length} chars) -->`;
+	return text.slice(0, maxChars) + footer;
+}
+
+/** Make an absolute path relative to projectRoot for display. */
+function rel(projectRoot: string, abs: string): string {
+	const r = path.relative(projectRoot, abs);
+	return r.startsWith("..") ? abs : r;
+}
+
+// ----------------------------------------------------------------------------
+// Disk lookups
+// ----------------------------------------------------------------------------
+
+/** Find the phase directory `<solyDir>/phases/<NN>-<slug>/` matching phaseNumber. */
+export function findPhaseDir(solyDir: string, phaseNumber: number): string | null {
+	const phasesRoot = path.join(solyDir, "phases");
+	if (!fs.existsSync(phasesRoot)) return null;
+	for (const entry of fs.readdirSync(phasesRoot, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const m = entry.name.match(/^(\d+)/);
+		if (m && parseInt(m[1], 10) === phaseNumber) {
+			return path.join(phasesRoot, entry.name);
+		}
+	}
+	return null;
+}
+
+/** Find the task directory for a given task id. */
+export function findTaskDir(
+	solyDir: string,
+	taskId: string,
+): { dir: string; feature: string } | null {
+	const featuresRoot = path.join(solyDir, "features");
+	if (!fs.existsSync(featuresRoot)) return null;
+	for (const f of fs.readdirSync(featuresRoot, { withFileTypes: true })) {
+		if (!f.isDirectory()) continue;
+		const taskDir = path.join(featuresRoot, f.name, "tasks", taskId);
+		if (fs.existsSync(taskDir)) return { dir: taskDir, feature: f.name };
+	}
+	return null;
+}
+
+/** Find the PLAN.md file for a given plan number within a phase dir. */
+export function findPlanFile(phaseDir: string, planNumber: number): string | null {
+	const padded = String(planNumber).padStart(2, "0");
+	let files: string[];
+	try {
+		files = fs.readdirSync(phaseDir);
+	} catch {
+		return null;
+	}
+	const re = new RegExp(`^\\d+-${padded}-.+-PLAN\\.md$`);
+	const match = files.find((f) => re.test(f));
+	return match ? path.join(phaseDir, match) : null;
+}
+
+/** Find the most recent N SUMMARY.md files in a phase dir, oldest-first. */
+export function findRecentSummaries(dir: string, n: number): string[] {
+	let files: string[];
+	try {
+		files = fs.readdirSync(dir).filter((f) => f.endsWith("-SUMMARY.md"));
+	} catch {
+		return [];
+	}
+	files.sort();
+	return files.slice(-n).map((f) => path.join(dir, f));
+}
+
+/** Find a phase's `<NN>-CONTEXT.md` path (or null).
+ *  Convention: filename starts with the padded phase number, not the full
+ *  slug. e.g. `.soly/phases/05-auth/05-CONTEXT.md`, not `05-auth-CONTEXT.md`. */
+export function findPhaseContextPath(phaseDir: string): string | null {
+	const slug = path.basename(phaseDir);
+	const numMatch = slug.match(/^(\d+)/);
+	if (!numMatch) return null;
+	const padded = numMatch[1]!.padStart(2, "0");
+	const p = path.join(phaseDir, `${padded}-CONTEXT.md`);
+	return fs.existsSync(p) ? p : null;
+}
+
+/** Find a phase's `<NN>-RESEARCH.md` path (or null). */
+export function findPhaseResearchPath(phaseDir: string): string | null {
+	const slug = path.basename(phaseDir);
+	const numMatch = slug.match(/^(\d+)/);
+	if (!numMatch) return null;
+	const padded = numMatch[1]!.padStart(2, "0");
+	const p = path.join(phaseDir, `${padded}-RESEARCH.md`);
+	return fs.existsSync(p) ? p : null;
+}
+
+/** Find a phase's `.continue-here.md` path (or null). */
+export function findContinueHerePath(phaseDir: string): string | null {
+	const p = path.join(phaseDir, ".continue-here.md");
+	return fs.existsSync(p) ? p : null;
+}
+
+// ----------------------------------------------------------------------------
+// Section loaders (each returns the section body, already truncated)
+// ----------------------------------------------------------------------------
+
+function loadIntentSummary(solyDir: string, maxTokens: number): string {
+	const docsRoot = path.join(solyDir, "docs");
+	if (!fs.existsSync(docsRoot)) return "_(no \`.soly/docs/\` directory — drop your 0-point docs there)_";
+
+	const files: string[] = [];
+	for (const e of fs.readdirSync(docsRoot, { withFileTypes: true })) {
+		if (e.name.startsWith(".")) continue;
+		const full = path.join(docsRoot, e.name);
+		if (e.isDirectory()) {
+			for (const sub of fs.readdirSync(full, { withFileTypes: true })) {
+				if (sub.isFile() && sub.name.endsWith(".md")) files.push(path.join(full, sub.name));
+			}
+		} else if (e.isFile() && e.name.endsWith(".md")) {
+			files.push(full);
+		}
+	}
+	if (files.length === 0) return "_(no \`.md\` files in \`.soly/docs/\`)_";
+
+	files.sort();
+	const out: string[] = [];
+	let usedChars = 0;
+	const maxChars = maxTokens * 4;
+	for (const f of files) {
+		const relPath = path.relative(solyDir, f);
+		const body = readIfExists(f) ?? "";
+		const preview = body
+			.replace(/^---[\s\S]*?---\r?\n/, "")
+			.split(/\r?\n/)
+			.filter((l) => l.trim() && !l.startsWith("#") && !l.startsWith("```"))
+			.slice(0, 6)
+			.join(" ");
+		const chunk = `- \`${relPath}\`: ${preview.slice(0, 240)}\n`;
+		if (usedChars + chunk.length > maxChars) {
+			out.push(`\n_(truncated at ${maxTokens} tokens; full files in \`.soly/docs/\`)_\n`);
+			break;
+		}
+		out.push(chunk);
+		usedChars += chunk.length;
+	}
+	return out.join("");
+}
+
+function loadStateSection(solyDir: string, maxTokens: number): string {
+	const statePath = path.join(solyDir, "STATE.md");
+	const raw = readIfExists(statePath);
+	if (!raw) return "_(no \`STATE.md\`) — initialize with \`soly init\` or create manually_";
+
+	// Prefer "Current Position" + "## Decisions" + top 20 lines of frontmatter
+	const lines = raw.split(/\r?\n/);
+	const out: string[] = [];
+	let inSection = "";
+	let buf: string[] = [];
+
+	const flush = () => {
+		if (buf.length > 0) {
+			out.push(buf.join("\n"));
+			buf = [];
+		}
+	};
+
+	for (const l of lines) {
+		if (l.match(/^##\s*Current Position/i)) {
+			flush();
+			inSection = "current";
+			buf.push(l);
+			continue;
+		}
+		if (l.match(/^##\s*Decisions/i)) {
+			flush();
+			inSection = "decisions";
+			buf.push(l);
+			continue;
+		}
+		if (l.match(/^##\s/) && (inSection === "current" || inSection === "decisions")) {
+			flush();
+			inSection = "";
+		}
+		if (inSection) buf.push(l);
+	}
+	flush();
+
+	const combined = out.length > 0 ? out.join("\n\n") : truncate(raw, maxTokens);
+	return truncate(combined.trim(), maxTokens);
+}
+
+function loadRoadmapRow(solyDir: string, phaseNumber: number, maxTokens: number): string {
+	const roadmapPath = path.join(solyDir, "ROADMAP.md");
+	const raw = readIfExists(roadmapPath);
+	if (!raw) return "_(no \`ROADMAP.md\`)_";
+
+	const lines = raw.split(/\r?\n/);
+	// Match `## Phase <N>`, `## Phase <NN>`, `## <N>`, `## <NN>`, `## <N>-...`
+	// The phase number is matched with optional zero-padding, the "Phase"
+	// prefix is optional, the separator is `:` / `-` / space.
+	const re = new RegExp(
+		`^#{2,4}\\s+(?:Phase\\s+)?0*${phaseNumber}(?:[\\s:\\-.]|$)`,
+		"i",
+	);
+	const startIdx = lines.findIndex((l) => re.test(l));
+	if (startIdx === -1) return truncate(raw, maxTokens);
+
+	const out: string[] = [];
+	for (let i = startIdx; i < lines.length; i++) {
+		const l = lines[i]!;
+		if (i > startIdx && /^##\s/.test(l)) break;
+		out.push(l);
+	}
+	return truncate(out.join("\n"), maxTokens);
+}
+
+function loadPhaseContext(phaseDir: string, maxTokens: number): string {
+	const p = findPhaseContextPath(phaseDir);
+	if (!p) return "_(no \`CONTEXT.md\` for this phase — run \`soly discuss <N>\` first if decisions are missing)_";
+	return truncate(readIfExists(p) ?? "", maxTokens);
+}
+
+function loadPhaseResearch(phaseDir: string, maxTokens: number): string {
+	const p = findPhaseResearchPath(phaseDir);
+	if (!p) return "_(no \`RESEARCH.md\` for this phase yet)_";
+	return truncate(readIfExists(p) ?? "", maxTokens);
+}
+
+function loadPlanFile(planFile: string, maxTokens: number): string {
+	return truncate(readIfExists(planFile) ?? "", maxTokens);
+}
+
+function loadPhaseSummaries(phaseDir: string, n: number, perSummaryTokens: number): string {
+	const files = findRecentSummaries(phaseDir, n);
+	if (files.length === 0) return "_(no prior \`SUMMARY.md\` files in this phase)_";
+	return files
+		.map((f) => `### ${path.basename(f)}\n\n${truncate(readIfExists(f) ?? "", perSummaryTokens)}`)
+		.join("\n\n---\n\n");
+}
+
+function loadFeatureTaskSummaries(
+	taskDir: string,
+	n: number,
+	perSummaryTokens: number,
+): string {
+	const featureDir = path.dirname(path.dirname(taskDir));
+	const tasksDir = path.join(featureDir, "tasks");
+	if (!fs.existsSync(tasksDir)) return "_(no prior task \`SUMMARY.md\` files in this feature)_";
+	const all: string[] = [];
+	for (const t of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+		if (!t.isDirectory()) continue;
+		const s = path.join(tasksDir, t.name, "SUMMARY.md");
+		if (fs.existsSync(s) && s !== path.join(taskDir, "SUMMARY.md")) all.push(s);
+	}
+	all.sort();
+	const recent = all.slice(-n);
+	if (recent.length === 0) return "_(no prior task \`SUMMARY.md\` files in this feature)_";
+	return recent
+		.map((f) => `### ${path.basename(path.dirname(f))}\n\n${truncate(readIfExists(f) ?? "", perSummaryTokens)}`)
+		.join("\n\n---\n\n");
+}
+
+function loadAntiPatterns(phaseDir: string, maxTokens: number): string {
+	const cont = findContinueHerePath(phaseDir);
+	if (!cont) return "_(no \`.continue-here.md\` for this phase)_";
+	const body = readIfExists(cont) ?? "";
+	const lines = body.split(/\r?\n/);
+	const out: string[] = [];
+	let inSection = false;
+	for (const l of lines) {
+		if (l.match(/^##\s*Critical Anti-Patterns/i)) {
+			inSection = true;
+			out.push(l);
+			continue;
+		}
+		if (inSection) {
+			if (l.match(/^##\s/) && !l.match(/Critical Anti-Patterns/i)) break;
+			out.push(l);
+		}
+	}
+	if (out.length === 0) return "_(no \`## Critical Anti-Patterns\` section in \`.continue-here.md\`) — safe to proceed_";
+	return truncate(out.join("\n"), maxTokens, "blocking rows only");
+}
+
+function loadFeatureReadme(feature: string, solyDir: string, maxTokens: number): string {
+	const readme = path.join(solyDir, "features", feature, "README.md");
+	if (!fs.existsSync(readme)) return `_(no \`.soly/features/${feature}/README.md\`)_`;
+	return truncate(readIfExists(readme) ?? "", maxTokens);
+}
+
+// ----------------------------------------------------------------------------
+// Plan summary extraction (for inline task-string cache)
+// ----------------------------------------------------------------------------
+
+export interface PlanSummary {
+	id: string;
+	title: string;
+	wave: number;
+	requirements: string[];
+	dependsOn: string[];
+	mustHaves: {
+		truths: string[];
+		artifacts: string[];
+		keyLinks: string[];
+	};
+}
+
+/** Extract key fields from a PLAN.md for inline use in the worker task. */
+export function extractPlanSummary(planContent: string): PlanSummary | null {
+	const m = planContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+	if (!m) return null;
+	const yaml = m[1]!;
+	const body = m[2]!;
+
+	const get = (key: string): string => {
+		const line = yaml.split(/\r?\n/).find((l) => l.startsWith(`${key}:`));
+		return (line?.split(":").slice(1).join(":") ?? "").trim().replace(/^["']|["']$/g, "");
+	};
+
+	const id = get("id") || "";
+	const title = get("title") || "";
+	const wave = parseInt(get("wave") || "1", 10) || 1;
+	// Split helper: strip outer [ ], split on comma, trim, strip inner quotes.
+	const splitList = (raw: string): string[] =>
+		raw
+			.replace(/^\[|\]$/g, "")
+			.split(",")
+			.map((s) => s.trim().replace(/^["']|["']$/g, ""))
+			.filter(Boolean);
+	const requirements = splitList(get("requirements"));
+	const dependsOn = splitList(get("depends-on"));
+
+	// Must Haves
+	const truths: string[] = [];
+	const artifacts: string[] = [];
+	const keyLinks: string[] = [];
+	const mhMatch = body.match(/##\s*Must Haves\s*\n([\s\S]*?)(?=\n##\s|\s*$)/);
+	if (mhMatch) {
+		const mhBody = mhMatch[1]!;
+		const truthSec = mhBody.match(/###\s*truths\b[\s\S]*?(?=###\s|$)/i)?.[0];
+		if (truthSec) {
+			for (const m of truthSec.matchAll(/^- \[[ x]\]\s*(.+)$/gm)) truths.push(m[1]!.trim());
+		}
+		const artSec = mhBody.match(/###\s*artifacts\b[\s\S]*?(?=###\s|$)/i)?.[0];
+		if (artSec) {
+			for (const m of artSec.matchAll(/^-\s*(.+)$/gm)) {
+				const t = m[1]!.trim();
+				if (t && !t.startsWith("###")) artifacts.push(t);
+			}
+		}
+		const linkSec = mhBody.match(/###\s*key_links\b[\s\S]*?(?=###\s|$)/i)?.[0];
+		if (linkSec) {
+			for (const m of linkSec.matchAll(/^-\s*(.+)$/gm)) {
+				const t = m[1]!.trim();
+				if (t && !t.startsWith("###")) keyLinks.push(t);
+			}
+		}
+	}
+
+	return { id, title, wave, requirements, dependsOn, mustHaves: { truths, artifacts, keyLinks } };
+}
+
+/** Render a PlanSummary as a compact bullet block for inline use. */
+export function renderPlanSummaryInline(s: PlanSummary): string {
+	const out: string[] = [];
+	if (s.title) out.push(`- **Plan title**: ${s.title}`);
+	out.push(`- **Wave**: ${s.wave}`);
+	if (s.requirements.length > 0) out.push(`- **Requirements**: [${s.requirements.join(", ")}]`);
+	if (s.dependsOn.length > 0) out.push(`- **Depends-on**: [${s.dependsOn.join(", ")}]`);
+	if (s.mustHaves.truths.length > 0) {
+		out.push(`- **Must-haves — truths**:`);
+		for (const t of s.mustHaves.truths) out.push(`  - ${t}`);
+	}
+	if (s.mustHaves.artifacts.length > 0) {
+		out.push(`- **Must-haves — artifacts**:`);
+		for (const a of s.mustHaves.artifacts) out.push(`  - ${a}`);
+	}
+	if (s.mustHaves.keyLinks.length > 0) {
+		out.push(`- **Must-haves — key_links**:`);
+		for (const k of s.mustHaves.keyLinks) out.push(`  - ${k}`);
+	}
+	return out.join("\n");
+}
+
+// ----------------------------------------------------------------------------
+// Bundle assembly
+// ----------------------------------------------------------------------------
+
+/** Build the full bundle content (no I/O — pure-ish, only reads from disk). */
+export function buildIterationContent(input: IterationInput): string {
+	const sections: string[] = [];
+	const generatedAt = new Date().toISOString();
+	const projectRoot = input.projectRoot;
+
+	// ---- Frontmatter ----
+	sections.push("---");
+	sections.push(`generated: ${generatedAt}`);
+	sections.push(`kind: ${input.kind}`);
+	if (input.phaseNumber != null) sections.push(`phase: ${input.phaseNumber}`);
+	if (input.planNumber != null) sections.push(`plan: ${input.planNumber}`);
+	if (input.taskId) sections.push(`task: ${input.taskId}`);
+	if (input.feature) sections.push(`feature: ${input.feature}`);
+	sections.push(`soly_dir: ${input.solyDir}`);
+	sections.push("---");
+	sections.push("");
+
+	// ---- Title ----
+	let title: string;
+	if (input.kind === "exec") {
+		title = input.taskId
+			? `# Iteration Context — Execute Task \`${input.taskId}\``
+			: `# Iteration Context — Execute Phase ${input.phaseNumber} / Plan ${input.planNumber}`;
+	} else if (input.kind === "plan") {
+		title = input.taskId
+			? `# Iteration Context — Plan Task \`${input.taskId}\``
+			: `# Iteration Context — Plan Phase ${input.phaseNumber}`;
+	} else if (input.kind === "discuss") {
+		title = `# Iteration Context — Discuss Phase ${input.phaseNumber}`;
+	} else {
+		title = `# Iteration Context — ${input.kind}`;
+	}
+	sections.push(title);
+	sections.push("");
+	sections.push(`**Generated**: ${generatedAt}`);
+	sections.push(`**Soly dir**: \`${rel(projectRoot, input.solyDir) || ".soly"}\``);
+	if (input.taskId) {
+		sections.push(`**Task**: \`${input.taskId}\` in feature \`${input.feature ?? "?"}\``);
+	} else if (input.phaseNumber != null) {
+		sections.push(
+			`**Phase**: ${input.phaseNumber}${input.planNumber != null ? ` / Plan ${input.planNumber}` : ""}`,
+		);
+	}
+	sections.push("");
+	sections.push("> **Read this file first.** It contains all the context you need for this iteration.");
+	sections.push(
+		"> If you need the full unabridged version of any section, the source path is given in the section header.",
+	);
+	sections.push("");
+
+	// ---- Section 0: Intent ----
+	sections.push("## 0. Project Intent (from `.soly/docs/`)");
+	sections.push("");
+	sections.push(
+		`_Source: \`.soly/docs/\` (full files in \`.soly/docs/\`, see also \`soly_intent\` tool)_`,
+	);
+	sections.push("");
+	sections.push(loadIntentSummary(input.solyDir, SECTION_BUDGETS.intent));
+	sections.push("");
+
+	// ---- Look up phase / task dirs (backfill feature from disk if needed) ----
+	let phaseDir: string | null = null;
+	if (input.phaseNumber != null) phaseDir = findPhaseDir(input.solyDir, input.phaseNumber);
+
+	let taskDir: string | null = null;
+	if (input.taskId) {
+		const found = findTaskDir(input.solyDir, input.taskId);
+		if (found) {
+			taskDir = found.dir;
+			if (!input.feature) input.feature = found.feature;
+		}
+	}
+
+	// ---- Section 1: State (only if there's a project state) ----
+	if (input.kind !== "pause") {
+		sections.push("## 1. Project State (`.soly/STATE.md` — Current Position + Decisions)");
+		sections.push("");
+		sections.push(`_Source: \`${rel(projectRoot, path.join(input.solyDir, "STATE.md"))}\`_`);
+		sections.push("");
+		sections.push(loadStateSection(input.solyDir, SECTION_BUDGETS.state));
+		sections.push("");
+	}
+
+	// ---- Phase-based sections (intent/plan/exec with a phase number) ----
+	if ((input.kind === "plan" || input.kind === "exec" || input.kind === "discuss") && input.phaseNumber != null) {
+		// Section 2: ROADMAP row
+		sections.push(`## 2. ROADMAP.md — Phase ${input.phaseNumber} row`);
+		sections.push("");
+		sections.push(`_Source: \`${rel(projectRoot, path.join(input.solyDir, "ROADMAP.md"))}\`_`);
+		sections.push("");
+		sections.push(loadRoadmapRow(input.solyDir, input.phaseNumber, SECTION_BUDGETS.roadmap));
+		sections.push("");
+	}
+
+	if ((input.kind === "plan" || input.kind === "exec" || input.kind === "discuss") && phaseDir) {
+		// Section 3: Phase CONTEXT (also for discuss — facilitator refines, doesn't re-derive)
+		const ctxPath = findPhaseContextPath(phaseDir);
+		sections.push("## 3. Phase CONTEXT");
+		sections.push("");
+		sections.push(`_Source: \`${ctxPath ? rel(projectRoot, ctxPath) : "(missing)"}\`_`);
+		sections.push("");
+		sections.push(loadPhaseContext(phaseDir, SECTION_BUDGETS.context));
+		sections.push("");
+	}
+
+	if ((input.kind === "plan" || input.kind === "exec") && phaseDir) {
+		// Section 3: Phase CONTEXT
+		const ctxPath = findPhaseContextPath(phaseDir);
+		sections.push("## 3. Phase CONTEXT");
+		sections.push("");
+		sections.push(`_Source: \`${ctxPath ? rel(projectRoot, ctxPath) : "(missing)"}\`_`);
+		sections.push("");
+		sections.push(loadPhaseContext(phaseDir, SECTION_BUDGETS.context));
+		sections.push("");
+
+		// Section 4: Phase RESEARCH
+		const resPath = findPhaseResearchPath(phaseDir);
+		sections.push("## 4. Phase RESEARCH");
+		sections.push("");
+		sections.push(`_Source: \`${resPath ? rel(projectRoot, resPath) : "(missing)"}\`_`);
+		sections.push("");
+		sections.push(loadPhaseResearch(phaseDir, SECTION_BUDGETS.research));
+		sections.push("");
+
+		// Section 5: Prior SUMMARYs
+		sections.push("## 5. Prior SUMMARYs (last 3 in this phase)");
+		sections.push("");
+		sections.push(loadPhaseSummaries(phaseDir, 3, 600));
+		sections.push("");
+
+		// For exec, also include the current PLAN
+		if (input.kind === "exec" && input.planNumber != null) {
+			const planFile = findPlanFile(phaseDir, input.planNumber);
+			if (planFile) {
+				sections.push(`## 6. Current PLAN (\`${path.basename(planFile)}\`)`);
+				sections.push("");
+				sections.push(`_Source: \`${rel(projectRoot, planFile)}\`_`);
+				sections.push("");
+				sections.push(loadPlanFile(planFile, SECTION_BUDGETS.plan));
+				sections.push("");
+			}
+		}
+
+		// Section 7: Anti-patterns (from .continue-here.md)
+		if (input.kind === "exec") {
+			sections.push("## 7. Critical Anti-Patterns (from `.continue-here.md`, if present)");
+			sections.push("");
+			sections.push(
+				"_Treat any `severity = blocking` row as a hard rule. Acknowledge before proceeding._",
+			);
+			sections.push("");
+			sections.push(loadAntiPatterns(phaseDir, SECTION_BUDGETS.antipatterns));
+			sections.push("");
+		}
+	}
+
+	// ---- Task-mode sections ----
+	if (input.taskId && taskDir) {
+		const featureName = input.feature ?? "unknown";
+		const readmeRel = path.join(input.solyDir, "features", featureName, "README.md");
+
+		// Section 2 (replaces phase sections): Feature README
+		sections.push("## 2. Feature README");
+		sections.push("");
+		sections.push(`_Source: \`${rel(projectRoot, readmeRel)}\`_`);
+		sections.push("");
+		sections.push(loadFeatureReadme(featureName, input.solyDir, SECTION_BUDGETS.featureReadme));
+		sections.push("");
+
+		// Section 3: Prior task SUMMARYs
+		sections.push("## 3. Prior task SUMMARYs (last 3 in this feature)");
+		sections.push("");
+		sections.push(loadFeatureTaskSummaries(taskDir, 3, 600));
+		sections.push("");
+
+		// Section 4: Current task PLAN
+		if (input.kind === "exec" || input.kind === "plan") {
+			const planFile = path.join(taskDir, "PLAN.md");
+			if (fs.existsSync(planFile)) {
+				sections.push("## 4. Current task PLAN");
+				sections.push("");
+				sections.push(`_Source: \`${rel(projectRoot, planFile)}\`_`);
+				sections.push("");
+				sections.push(loadPlanFile(planFile, SECTION_BUDGETS.plan));
+				sections.push("");
+			}
+		}
+	}
+
+	sections.push("---");
+	sections.push("");
+	sections.push(
+		"**End of iteration context.** Continue with the workflow instructions in the task prompt.",
+	);
+
+	return sections.join("\n");
+}
+
+// ----------------------------------------------------------------------------
+// File writer
+// ----------------------------------------------------------------------------
+
+/** Compute the bundle file path (does not write). */
+export function iterationFilePath(input: IterationInput): string {
+	const iterationsDir = path.join(input.solyDir, "iterations");
+	const ts = timestampSlug();
+	let fileName: string;
+	if (input.taskId) {
+		const feat = input.feature ?? "task";
+		fileName = `${feat}__${input.taskId}-${input.kind}-${ts}.md`;
+	} else if (input.phaseNumber == null) {
+		fileName = `${input.kind}-${ts}.md`;
+	} else {
+		const padded = String(input.phaseNumber).padStart(2, "0");
+		const planPart =
+			input.planNumber != null ? `-${String(input.planNumber).padStart(2, "0")}` : "";
+		fileName = `${padded}${planPart}-${input.kind}-${ts}.md`;
+	}
+	return path.join(iterationsDir, fileName);
+}
+
+/** Build the bundle + write it to disk. Returns metadata. */
+export function writeIterationContext(input: IterationInput): IterationOutput {
+	const iterationsDir = path.join(input.solyDir, "iterations");
+	fs.mkdirSync(iterationsDir, { recursive: true });
+	const filePath = iterationFilePath(input);
+	const content = buildIterationContent(input);
+	atomicWriteFileSync(filePath, content, "utf-8");
+	return {
+		filePath,
+		relPath: rel(input.projectRoot, filePath),
+		fileName: path.basename(filePath),
+		bytes: content.length,
+		tokens: Math.ceil(content.length / 4),
+		generatedAt: new Date().toISOString(),
+	};
+}