@shanepadgett/tau-agent 0.33.1 → 0.34.0

package/extensions/patch/parser.ts

@@ -156,111 +156,144 @@ function parseChunkLine(rawLine: string): { prefix: " " | "+" | "-"; text: strin
 	return { prefix, text: rawLine.slice(1) };
 }
 
-function parseUpdateBody(
-	lines: string[],
-	startIndex: number,
-	operationPath: string,
-): { movePath?: string; chunks: UpdateFileChunk[]; linesAdded: number; linesRemoved: number; nextIndex: number } {
-	const chunks: UpdateFileChunk[] = [];
-	let index = startIndex;
-	let movePath: string | undefined;
-	let current: MutableChunk | undefined;
-	let sawAnyChunk = false;
-	let linesAdded = 0;
-	let linesRemoved = 0;
+interface UpdateBodyState {
+	chunks: UpdateFileChunk[];
+	index: number;
+	movePath?: string;
+	current?: MutableChunk;
+	sawAnyChunk: boolean;
+	linesAdded: number;
+	linesRemoved: number;
+}
 
-	while (index < lines.length) {
-		const line = lines[index];
-		if (line === undefined) break;
-		const currentDirective = updateDirective(line);
-		if (isUpdateBoundary(line)) break;
+function changeContextFromDirective(directive: string): string | undefined {
+	if (directive === CHANGE_CONTEXT_MARKER) return undefined;
+	const context = directive.slice(CHANGE_CONTEXT_MARKER.length + 1).trim();
+	return context.length > 0 ? context : undefined;
+}
 
-		if (currentDirective.startsWith(MOVE_TO_MARKER)) {
-			if (sawAnyChunk || current) throw new Error(`Move to must appear before update chunks: ${operationPath}`);
-			movePath = requireUpdatePath(line, MOVE_TO_MARKER);
-			index += 1;
-			continue;
-		}
+function openOrReuseChunk(state: UpdateBodyState, operationPath: string): MutableChunk {
+	if (state.current) return state.current;
+	if (state.sawAnyChunk || state.chunks.length > 0) {
+		throw new Error(`Only the first update chunk may omit @@: ${operationPath}`);
+	}
+	state.current = createChunk();
+	state.sawAnyChunk = true;
+	return state.current;
+}
 
-		if (currentDirective === CHANGE_CONTEXT_MARKER || currentDirective.startsWith(`${CHANGE_CONTEXT_MARKER} `)) {
-			finalizeChunk(current, chunks, operationPath);
-			const context =
-				currentDirective === CHANGE_CONTEXT_MARKER
-					? undefined
-					: currentDirective.slice(CHANGE_CONTEXT_MARKER.length + 1).trim();
-			current = createChunk(context && context.length > 0 ? context : undefined);
-			sawAnyChunk = true;
-			index += 1;
-			continue;
-		}
+function appendHunkLine(state: UpdateBodyState, current: MutableChunk, line: string): void {
+	const parsedLine = parseChunkLine(line);
+	current.hasLines = true;
+	if (parsedLine.prefix === "+") state.linesAdded += 1;
+	if (parsedLine.prefix === "-") state.linesRemoved += 1;
+	current.lines.push({ prefix: parsedLine.prefix, text: parsedLine.text });
+	state.index += 1;
+}
 
-		if (!current) {
-			if (sawAnyChunk || chunks.length > 0) {
-				throw new Error(`Only the first update chunk may omit @@: ${operationPath}`);
-			}
-			current = createChunk();
-			sawAnyChunk = true;
-		}
+function consumeUpdateLine(state: UpdateBodyState, line: string, operationPath: string): boolean {
+	const directive = updateDirective(line);
+	if (isUpdateBoundary(line)) return false;
 
-		if (currentDirective === EOF_MARKER) {
-			current.isEndOfFile = true;
-			index += 1;
-			continue;
+	if (directive.startsWith(MOVE_TO_MARKER)) {
+		if (state.sawAnyChunk || state.current) {
+			throw new Error(`Move to must appear before update chunks: ${operationPath}`);
 		}
+		state.movePath = requireUpdatePath(line, MOVE_TO_MARKER);
+		state.index += 1;
+		return true;
+	}
 
-		const parsedLine = parseChunkLine(line);
-		current.hasLines = true;
+	if (directive === CHANGE_CONTEXT_MARKER || directive.startsWith(`${CHANGE_CONTEXT_MARKER} `)) {
+		finalizeChunk(state.current, state.chunks, operationPath);
+		state.current = createChunk(changeContextFromDirective(directive));
+		state.sawAnyChunk = true;
+		state.index += 1;
+		return true;
+	}
 
-		if (parsedLine.prefix === "+") linesAdded += 1;
-		if (parsedLine.prefix === "-") linesRemoved += 1;
+	const current = openOrReuseChunk(state, operationPath);
+	if (directive === EOF_MARKER) {
+		current.isEndOfFile = true;
+		state.index += 1;
+		return true;
+	}
 
-		current.lines.push({ prefix: parsedLine.prefix, text: parsedLine.text });
-		index += 1;
+	appendHunkLine(state, current, line);
+	return true;
+}
+
+function parseUpdateBody(
+	lines: string[],
+	startIndex: number,
+	operationPath: string,
+): { movePath?: string; chunks: UpdateFileChunk[]; linesAdded: number; linesRemoved: number; nextIndex: number } {
+	const state: UpdateBodyState = {
+		chunks: [],
+		index: startIndex,
+		sawAnyChunk: false,
+		linesAdded: 0,
+		linesRemoved: 0,
+	};
+
+	while (state.index < lines.length) {
+		const line = lines[state.index];
+		if (line === undefined || !consumeUpdateLine(state, line, operationPath)) break;
 	}
 
-	finalizeChunk(current, chunks, operationPath);
-	if (chunks.length === 0 && !movePath)
+	finalizeChunk(state.current, state.chunks, operationPath);
+	if (state.chunks.length === 0 && !state.movePath) {
 		throw new Error(`Update file patch is missing chunk content: ${operationPath}`);
+	}
+
+	return {
+		movePath: state.movePath,
+		chunks: state.chunks,
+		linesAdded: state.linesAdded,
+		linesRemoved: state.linesRemoved,
+		nextIndex: state.index,
+	};
+}
+
+function parseWholeFileSection(header: string, sectionLines: string[], isReplace: boolean): ParsedSection {
+	const prefix = isReplace ? REPLACE_FILE_MARKER : ADD_FILE_MARKER;
+	const path = requireTopLevelPath(header, prefix);
+	const body = parseAddBody(sectionLines, 1);
+	if (body.nextIndex !== sectionLines.length) {
+		throw new Error(`Malformed ${isReplace ? "Replace" : "Add"} File section: ${path}`);
+	}
+	return { type: isReplace ? "replace" : "add", path, content: body.content, linesAdded: body.lineCount };
+}
+
+function parseDeleteSection(header: string, sectionLines: string[]): ParsedSection {
+	const path = requireTopLevelPath(header, DELETE_FILE_MARKER);
+	if (sectionLines.length !== 1) throw new Error(`Malformed Delete File section: ${path}`);
+	return { type: "delete", path };
+}
 
-	return { movePath, chunks, linesAdded, linesRemoved, nextIndex: index };
+function parseUpdateSection(header: string, sectionLines: string[]): ParsedSection {
+	const path = requireTopLevelPath(header, UPDATE_FILE_MARKER);
+	const updateBody = parseUpdateBody(sectionLines, 1, path);
+	if (updateBody.nextIndex !== sectionLines.length) throw new Error(`Malformed Update File section: ${path}`);
+	return {
+		type: "update",
+		path,
+		movePath: updateBody.movePath,
+		chunks: updateBody.chunks,
+		linesAdded: updateBody.linesAdded,
+		linesRemoved: updateBody.linesRemoved,
+	};
 }
 
 function parseSection(sectionLines: string[]): ParsedSection {
 	const header = sectionLines[0] ?? "";
-
 	const headerDirective = topLevelDirective(header);
 
 	if (headerDirective.startsWith(ADD_FILE_MARKER) || headerDirective.startsWith(REPLACE_FILE_MARKER)) {
-		const isReplace = headerDirective.startsWith(REPLACE_FILE_MARKER);
-		const prefix = isReplace ? REPLACE_FILE_MARKER : ADD_FILE_MARKER;
-		const path = requireTopLevelPath(header, prefix);
-		const body = parseAddBody(sectionLines, 1);
-		if (body.nextIndex !== sectionLines.length) {
-			throw new Error(`Malformed ${isReplace ? "Replace" : "Add"} File section: ${path}`);
-		}
-		return { type: isReplace ? "replace" : "add", path, content: body.content, linesAdded: body.lineCount };
-	}
-
-	if (headerDirective.startsWith(DELETE_FILE_MARKER)) {
-		const path = requireTopLevelPath(header, DELETE_FILE_MARKER);
-		if (sectionLines.length !== 1) throw new Error(`Malformed Delete File section: ${path}`);
-		return { type: "delete", path };
-	}
-
-	if (headerDirective.startsWith(UPDATE_FILE_MARKER)) {
-		const path = requireTopLevelPath(header, UPDATE_FILE_MARKER);
-		const updateBody = parseUpdateBody(sectionLines, 1, path);
-		if (updateBody.nextIndex !== sectionLines.length) throw new Error(`Malformed Update File section: ${path}`);
-		return {
-			type: "update",
-			path,
-			movePath: updateBody.movePath,
-			chunks: updateBody.chunks,
-			linesAdded: updateBody.linesAdded,
-			linesRemoved: updateBody.linesRemoved,
-		};
+		return parseWholeFileSection(header, sectionLines, headerDirective.startsWith(REPLACE_FILE_MARKER));
 	}
-
+	if (headerDirective.startsWith(DELETE_FILE_MARKER)) return parseDeleteSection(header, sectionLines);
+	if (headerDirective.startsWith(UPDATE_FILE_MARKER)) return parseUpdateSection(header, sectionLines);
 	throw new Error(`Unexpected patch line: ${header}`);
 }
 
@@ -285,15 +318,41 @@ function envelopeFailure(message: string): ParsedPatch {
 	return { operations: [], parseFailures: [{ phase: "parse", sectionIndex: 0, message }], totalSections: 1 };
 }
 
-export function parsePatch(input: string): ParsedPatch {
+function parseEnvelopeLines(input: string): string[] | ParsedPatch {
 	const normalized = input.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
 	if (!normalized) return envelopeFailure("Patch must not be empty.");
-
 	const lines = normalized.split("\n");
-	if (topLevelDirective(lines[0] ?? "") !== BEGIN_PATCH_MARKER)
+	if (topLevelDirective(lines[0] ?? "") !== BEGIN_PATCH_MARKER) {
 		return envelopeFailure("Patch must start with *** Begin Patch.");
-	if (topLevelDirective(lines[lines.length - 1] ?? "") !== END_PATCH_MARKER)
+	}
+	if (topLevelDirective(lines[lines.length - 1] ?? "") !== END_PATCH_MARKER) {
 		return envelopeFailure("Patch must end with *** End Patch.");
+	}
+	return lines;
+}
+
+function pushParsedSection(
+	operations: PatchOperation[],
+	parseFailures: PatchFailure[],
+	sectionIndex: number,
+	sectionLines: string[],
+): void {
+	try {
+		operations.push({ ...parseSection(sectionLines), sectionIndex });
+	} catch (error) {
+		parseFailures.push({
+			phase: "parse",
+			sectionIndex,
+			...parseHeaderMetadata(sectionLines[0] ?? ""),
+			message: error instanceof Error ? error.message : String(error),
+		});
+	}
+}
+
+export function parsePatch(input: string): ParsedPatch {
+	const envelope = parseEnvelopeLines(input);
+	if (!Array.isArray(envelope)) return envelope;
+	const lines = envelope;
 
 	const operations: PatchOperation[] = [];
 	const parseFailures: PatchFailure[] = [];
@@ -308,30 +367,15 @@ export function parsePatch(input: string): ParsedPatch {
 			continue;
 		}
 
-		const lineDirective = topLevelDirective(line);
-		if (!isTopLevelBoundary(line) || lineDirective === END_PATCH_MARKER) {
+		if (!isTopLevelBoundary(line) || topLevelDirective(line) === END_PATCH_MARKER) {
 			parseFailures.push({ phase: "parse", sectionIndex, message: `Unexpected patch line: ${line}` });
 			index += 1;
 			continue;
 		}
 
 		sectionIndex += 1;
-		const sectionStart = index;
 		const nextBoundary = nextSectionBoundary(lines, index + 1, isUpdateHeader(line));
-
-		const sectionLines = lines.slice(sectionStart, nextBoundary);
-		try {
-			operations.push({ ...parseSection(sectionLines), sectionIndex });
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			parseFailures.push({
-				phase: "parse",
-				sectionIndex,
-				...parseHeaderMetadata(sectionLines[0] ?? ""),
-				message,
-			});
-		}
-
+		pushParsedSection(operations, parseFailures, sectionIndex, lines.slice(index, nextBoundary));
 		index = nextBoundary;
 	}
 

package/extensions/patch/render.ts

@@ -44,6 +44,34 @@ function startPreviewOp(ops: PreviewOp[], kind: PreviewOp["kind"], path: string)
 	return op;
 }
 
+function matchPreviewSectionStart(ops: PreviewOp[], value: string): PreviewOp | undefined {
+	const addPath = pathAfter(value, ADD_FILE_MARKER);
+	if (addPath !== undefined) return startPreviewOp(ops, "add", addPath);
+	const replacePath = pathAfter(value, REPLACE_FILE_MARKER);
+	if (replacePath !== undefined) return startPreviewOp(ops, "replace", replacePath);
+	const deletePath = pathAfter(value, DELETE_FILE_MARKER);
+	if (deletePath !== undefined) return startPreviewOp(ops, "delete", deletePath);
+	const updatePath = pathAfter(value, UPDATE_FILE_MARKER);
+	if (updatePath !== undefined) return startPreviewOp(ops, "update", updatePath);
+	return undefined;
+}
+
+function accumulatePreviewBodyLine(current: PreviewOp, line: string): void {
+	if (current.kind === "update") {
+		const movePath = pathAfter(updateDirective(line), MOVE_TO_MARKER);
+		if (movePath !== undefined) {
+			current.moveTo = movePath;
+			return;
+		}
+		if (line.startsWith("+")) current.linesAdded += 1;
+		else if (line.startsWith("-")) current.linesRemoved += 1;
+		return;
+	}
+	if ((current.kind === "add" || current.kind === "replace") && line.startsWith("+")) {
+		current.linesAdded += 1;
+	}
+}
+
 // Tolerant preview scan — never throws, display-oriented (partial patches during streaming).
 function scanPreview(input: string | undefined): PreviewOp[] {
 	if (typeof input !== "string" || !input) return [];
@@ -54,47 +82,12 @@ function scanPreview(input: string | undefined): PreviewOp[] {
 	for (const line of lines) {
 		const value = current?.kind === "update" ? updateDirective(line) : topLevelDirective(line);
 		if (value === END_PATCH_MARKER) break;
-
-		const addPath = pathAfter(value, ADD_FILE_MARKER);
-		if (addPath !== undefined) {
-			current = startPreviewOp(ops, "add", addPath);
-			continue;
-		}
-
-		const replacePath = pathAfter(value, REPLACE_FILE_MARKER);
-		if (replacePath !== undefined) {
-			current = startPreviewOp(ops, "replace", replacePath);
+		const started = matchPreviewSectionStart(ops, value);
+		if (started) {
+			current = started;
 			continue;
 		}
-
-		const deletePath = pathAfter(value, DELETE_FILE_MARKER);
-		if (deletePath !== undefined) {
-			current = startPreviewOp(ops, "delete", deletePath);
-			continue;
-		}
-
-		const updatePath = pathAfter(value, UPDATE_FILE_MARKER);
-		if (updatePath !== undefined) {
-			current = startPreviewOp(ops, "update", updatePath);
-			continue;
-		}
-
-		if (!current) continue;
-
-		if (current.kind === "update") {
-			const movePath = pathAfter(updateDirective(line), MOVE_TO_MARKER);
-			if (movePath !== undefined) {
-				current.moveTo = movePath;
-				continue;
-			}
-			if (line.startsWith("+")) current.linesAdded += 1;
-			else if (line.startsWith("-")) current.linesRemoved += 1;
-			continue;
-		}
-
-		if (current.kind === "add" || current.kind === "replace") {
-			if (line.startsWith("+")) current.linesAdded += 1;
-		}
+		if (current) accumulatePreviewBodyLine(current, line);
 	}
 
 	return ops;

package/extensions/patch/summary.ts

@@ -1,35 +1,39 @@
-import { type ApplyPatchSummary, deriveStats } from "./executor.ts";
+import { type ApplyPatchStats, type ApplyPatchSummary, deriveStats } from "./executor.ts";
+import type { PatchFailure } from "./parser.ts";
 
-export function formatPatchSummary(summary: ApplyPatchSummary): string {
-	const s = deriveStats(summary);
+function formatStatusLine(summary: ApplyPatchSummary, stats: ApplyPatchStats): string {
+	if (summary.status === "failed") return "No changes applied.";
+	const parts: string[] = [];
+	if (stats.linesAdded > 0) parts.push(`+${stats.linesAdded}`);
+	if (stats.linesRemoved > 0) parts.push(`-${stats.linesRemoved}`);
+	const badge = parts.length > 0 ? ` [${parts.join(" ")}]` : "";
+	return `Applied ${stats.completedOperations}/${summary.totalSections} sections.${badge}`;
+}
+
+function formatChangeLines(stats: ApplyPatchStats): string[] {
 	const lines: string[] = [];
-	if (summary.status === "failed") {
-		lines.push("No changes applied.");
-	} else {
-		const parts: string[] = [];
-		if (s.linesAdded > 0) parts.push(`+${s.linesAdded}`);
-		if (s.linesRemoved > 0) parts.push(`-${s.linesRemoved}`);
-		const badge = parts.length > 0 ? ` [${parts.join(" ")}]` : "";
-		lines.push(`Applied ${s.completedOperations}/${summary.totalSections} sections.${badge}`);
-	}
+	for (const path of stats.added) lines.push(`A ${path}`);
+	for (const path of stats.replaced) lines.push(`M ${path}`);
+	for (const path of stats.updated) lines.push(`M ${path}`);
+	for (const path of stats.deleted) lines.push(`D ${path}`);
+	for (const move of stats.moved) lines.push(`R ${move.from} -> ${move.to}`);
+	return lines;
+}
 
-	for (const path of s.added) lines.push(`A ${path}`);
-	for (const path of s.replaced) lines.push(`M ${path}`);
-	for (const path of s.updated) lines.push(`M ${path}`);
-	for (const path of s.deleted) lines.push(`D ${path}`);
-	for (const move of s.moved) lines.push(`R ${move.from} -> ${move.to}`);
+function formatFailureLine(failure: PatchFailure): string {
+	const kind = failure.kind ? `${failure.kind} ` : "";
+	const path = failure.path ?? "";
+	const chunk = failure.chunkIndex && failure.totalChunks ? ` chunk ${failure.chunkIndex}/${failure.totalChunks}` : "";
+	const ctx = failure.contextHint ? ` (context: "${failure.contextHint}")` : "";
+	return `- ${kind}${path}${chunk}: ${failure.message}${ctx}`.trim();
+}
 
+export function formatPatchSummary(summary: ApplyPatchSummary): string {
+	const stats = deriveStats(summary);
+	const lines = [formatStatusLine(summary, stats), ...formatChangeLines(stats)];
 	if (summary.failures.length > 0) {
 		lines.push("Failures:");
-		for (const failure of summary.failures) {
-			const kind = failure.kind ? `${failure.kind} ` : "";
-			const path = failure.path ?? "";
-			const chunk =
-				failure.chunkIndex && failure.totalChunks ? ` chunk ${failure.chunkIndex}/${failure.totalChunks}` : "";
-			const ctx = failure.contextHint ? ` (context: "${failure.contextHint}")` : "";
-			lines.push(`- ${kind}${path}${chunk}: ${failure.message}${ctx}`.trim());
-		}
+		for (const failure of summary.failures) lines.push(formatFailureLine(failure));
 	}
-
 	return lines.join("\n");
 }

package/extensions/ready/README.md

@@ -0,0 +1,7 @@
+# Ready
+
+Adds `/ready` to scan the repository for agent-readiness rails and write one report file.
+
+You pick Markdown or HTML. Tau runs a deterministic scan (no model), builds the report in memory, and writes a timestamped file under `.pi/tau/ready/` using your local timezone in the filename. A notification shows the path and status counts.
+
+The scan looks for cold-start docs, toolchain pins, task/verify entrypoints, silent command runner config, policy and vocabulary files, standards and context catalogs, and language-specific format/lint/types/entropy tools (TypeScript, Deno, Go, Rust packs in v1). Statuses are pass, weak, missing, n/a, or unknown — no scores.

package/extensions/ready/index.ts

@@ -0,0 +1,58 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { resolveProjectRoot } from "../../shared/settings/paths.ts";
+import { errorText } from "../../shared/text.ts";
+import { type ReadyFormat, localTimestampSlug, summarizeCounts } from "./model.ts";
+import { readyFileExtension, renderReadyReport } from "./render.ts";
+import { scanReadyReport } from "./scan.ts";
+
+const OUTPUT_DIR = join(".pi", "tau", "ready");
+
+export default function readyExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("ready", {
+		description: "Scan agent readiness and write a markdown or HTML report",
+		handler: async (_args, ctx) => {
+			try {
+				await runReady(ctx);
+			} catch (error) {
+				ctx.ui.notify(`/ready failed: ${errorText(error)}`, "error");
+			}
+		},
+	});
+}
+
+async function runReady(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.isProjectTrusted()) {
+		ctx.ui.notify("/ready requires a trusted project", "warning");
+		return;
+	}
+
+	const format = await pickFormat(ctx);
+	if (!format) return;
+
+	const root = await resolveProjectRoot(ctx.cwd);
+	const report = await scanReadyReport(ctx.cwd);
+	const body = renderReadyReport(report, format);
+	const stamp = localTimestampSlug(new Date(report.generatedAt));
+	const fileName = `ready-${stamp}.${readyFileExtension(format)}`;
+	const outDir = join(root, OUTPUT_DIR);
+	const outPath = join(outDir, fileName);
+
+	await mkdir(outDir, { recursive: true });
+	await writeFile(outPath, body, "utf8");
+
+	const displayPath = relative(ctx.cwd, outPath) || outPath;
+	ctx.ui.notify(`/ready ${summarizeCounts(report.counts)}\n${displayPath}`, "info");
+}
+
+async function pickFormat(ctx: ExtensionCommandContext): Promise<ReadyFormat | undefined> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("/ready needs the TUI to choose Markdown or HTML", "warning");
+		return undefined;
+	}
+	const selected = await ctx.ui.select("Ready report format", ["Markdown", "HTML"]);
+	if (selected === "Markdown") return "markdown";
+	if (selected === "HTML") return "html";
+	return undefined;
+}

package/extensions/ready/model.ts

@@ -0,0 +1,128 @@
+export type ReadyStatus = "pass" | "weak" | "missing" | "na" | "unknown";
+export type ReadyHow = "scan" | "judgment" | "mixed";
+export type ReadyFormat = "markdown" | "html";
+
+export type ReadyAreaId =
+	| "cold-start"
+	| "toolchain"
+	| "verify"
+	| "lint-entropy"
+	| "policy"
+	| "standards"
+	| "context"
+	| "reuse"
+	| "markers"
+	| "harness"
+	| "side-effect-verbs";
+
+export interface ReadyRow {
+	id: string;
+	area: ReadyAreaId;
+	title: string;
+	status: ReadyStatus;
+	how: ReadyHow;
+	evidence: string[];
+	note: string;
+	next?: string;
+}
+
+export interface ReadyReport {
+	generatedAt: string;
+	generatedAtLabel: string;
+	root: string;
+	languages: string[];
+	rows: ReadyRow[];
+	counts: Record<ReadyStatus, number>;
+}
+
+export const AREA_LABELS: Record<ReadyAreaId, string> = {
+	"cold-start": "Cold start",
+	toolchain: "Toolchain",
+	verify: "Verify",
+	"lint-entropy": "Lint and entropy",
+	policy: "Policy",
+	standards: "Standards",
+	context: "Context",
+	reuse: "Reuse",
+	markers: "Markers",
+	harness: "Harness gates",
+	"side-effect-verbs": "Side-effect verbs",
+};
+
+export const AREA_ORDER: ReadyAreaId[] = [
+	"cold-start",
+	"toolchain",
+	"verify",
+	"lint-entropy",
+	"policy",
+	"standards",
+	"context",
+	"reuse",
+	"markers",
+	"harness",
+	"side-effect-verbs",
+];
+
+export function countStatuses(rows: readonly ReadyRow[]): Record<ReadyStatus, number> {
+	const counts: Record<ReadyStatus, number> = {
+		pass: 0,
+		weak: 0,
+		missing: 0,
+		na: 0,
+		unknown: 0,
+	};
+	for (const row of rows) counts[row.status] += 1;
+	return counts;
+}
+
+export function summarizeCounts(counts: Record<ReadyStatus, number>): string {
+	const parts: string[] = [];
+	for (const status of ["pass", "weak", "missing", "na", "unknown"] as const) {
+		if (counts[status] > 0) parts.push(`${counts[status]} ${status}`);
+	}
+	return parts.join(" · ") || "no rows";
+}
+
+/** Local-timezone stamp for filenames: 2026-04-08-143052 */
+export function localTimestampSlug(date = new Date()): string {
+	const pad = (value: number) => String(value).padStart(2, "0");
+	return [
+		date.getFullYear(),
+		pad(date.getMonth() + 1),
+		pad(date.getDate()),
+		"-",
+		pad(date.getHours()),
+		pad(date.getMinutes()),
+		pad(date.getSeconds()),
+	].join("");
+}
+
+export function localTimestampLabel(date = new Date()): string {
+	return date.toLocaleString(undefined, {
+		year: "numeric",
+		month: "short",
+		day: "numeric",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		timeZoneName: "short",
+	});
+}
+
+export function row(
+	partial: Omit<ReadyRow, "how" | "evidence"> & {
+		how?: ReadyHow;
+		evidence?: string[];
+	},
+): ReadyRow {
+	return {
+		how: partial.how ?? "scan",
+		evidence: partial.evidence ?? [],
+		id: partial.id,
+		area: partial.area,
+		title: partial.title,
+		status: partial.status,
+		note: partial.note,
+		next: partial.next,
+	};
+}