@possumtech/rummy 0.5.0 → 2.0.0

package/src/plugins/telemetry/telemetry.js

@@ -30,14 +30,15 @@ export default class Telemetry {
 
 	async #onRpcStarted({ method, id, params }) {
 		this.#starts.set(id, Date.now());
-		const summary =
-			method === "ask" || method === "act"
-				? `prompt="${(params?.prompt || "").slice(0, 60)}"`
-				: method === "run/abort"
-					? `run=${params?.run}`
-					: method === "run/resolve"
-						? `run=${params?.run} action=${params?.resolution?.action}`
-						: "";
+		let summary = "";
+		if (method === "ask" || method === "act") {
+			const prompt = params?.prompt ? params.prompt : "";
+			summary = `prompt="${prompt.slice(0, 60)}"`;
+		} else if (method === "run/abort") {
+			summary = `run=${params?.run}`;
+		} else if (method === "run/resolve") {
+			summary = `run=${params?.run} action=${params?.resolution?.action}`;
+		}
 		console.log(`[RPC] → ${method}(${id})${summary ? ` ${summary}` : ""}`);
 
 		if (method === "ask" || method === "act") {
@@ -50,11 +51,13 @@ export default class Telemetry {
 			? `${((Date.now() - this.#starts.get(id)) / 1000).toFixed(1)}s`
 			: "";
 		this.#starts.delete(id);
-		const summary = result?.run
-			? `run=${result.run} status=${result.status || "ok"}`
-			: result?.status
-				? `status=${result.status}`
-				: "";
+		let summary = "";
+		if (result?.run) {
+			const status = result.status ? result.status : "ok";
+			summary = `run=${result.run} status=${status}`;
+		} else if (result?.status) {
+			summary = `status=${result.status}`;
+		}
 		console.log(
 			`[RPC] ← ${method}(${id}) ${elapsed}${summary ? ` ${summary}` : ""}`,
 		);
@@ -65,7 +68,8 @@ export default class Telemetry {
 			? `${((Date.now() - this.#starts.get(id)) / 1000).toFixed(1)}s`
 			: "";
 		this.#starts.delete(id);
-		console.error(`[RPC] ✗ (${id}) ${elapsed} ${error?.message || error}`);
+		const detail = error?.message ? error.message : error;
+		console.error(`[RPC] ✗ (${id}) ${elapsed} ${detail}`);
 	}
 
 	async #onStepCompleted(payload) {
@@ -87,53 +91,74 @@ export default class Telemetry {
 		userMsg,
 	}) {
 		const { entries: store, runId, loopId } = rummy;
+		// Audit schemes are system-only writes (see initPlugins).
+		const systemOpts = { loopId, visibility: "archived", writer: "system" };
 
 		// assistant://N — the model's raw response
-		await store.upsert(runId, turn, `assistant://${turn}`, content, 200, {
-			loopId,
-			fidelity: "archived",
+		await store.set({
+			runId,
+			turn,
+			path: `assistant://${turn}`,
+			body: content,
+			state: "resolved",
+			...systemOpts,
 		});
 
 		// system://N, user://N — assembled messages as audit
 		if (systemMsg) {
-			await store.upsert(runId, turn, `system://${turn}`, systemMsg, 200, {
-				loopId,
-				fidelity: "archived",
+			await store.set({
+				runId,
+				turn,
+				path: `system://${turn}`,
+				body: systemMsg,
+				state: "resolved",
+				...systemOpts,
 			});
 		}
 		if (userMsg) {
-			await store.upsert(runId, turn, `user://${turn}`, userMsg, 200, {
-				loopId,
-				fidelity: "archived",
+			await store.set({
+				runId,
+				turn,
+				path: `user://${turn}`,
+				body: userMsg,
+				state: "resolved",
+				...systemOpts,
 			});
 		}
 
 		// model://N — raw API response diagnostics
-		await store.upsert(
+		await store.set({
 			runId,
 			turn,
-			`model://${turn}`,
-			JSON.stringify({
+			path: `model://${turn}`,
+			body: JSON.stringify({
 				keys: responseMessage ? Object.keys(responseMessage) : [],
-				reasoning_content: responseMessage?.reasoning_content || null,
+				reasoning_content: responseMessage?.reasoning_content
+					? responseMessage.reasoning_content
+					: null,
 				content: content.slice(0, 4096),
-				usage: result.usage || null,
-				model: result.model || null,
+				usage: result.usage ? result.usage : null,
+				model: result.model ? result.model : null,
 			}),
-			200,
-			{ loopId, fidelity: "archived" },
-		);
+			state: "resolved",
+			...systemOpts,
+		});
 
 		// reasoning://N
 		if (responseMessage?.reasoning_content) {
-			await store.upsert(
+			await store.set({
 				runId,
 				turn,
-				`reasoning://${turn}`,
-				responseMessage.reasoning_content,
-				200,
-				{ loopId, fidelity: "archived" },
-			);
+				path: `reasoning://${turn}`,
+				body: responseMessage.reasoning_content,
+				state: "resolved",
+				...systemOpts,
+			});
+			if (process.env.RUMMY_DEBUG === "true") {
+				console.log(
+					`\n--- REASONING turn ${turn} (${responseMessage.reasoning_content.length} chars) ---\n${responseMessage.reasoning_content}\n--- END REASONING turn ${turn} ---\n`,
+				);
+			}
 		}
 
 		// content://N — unparsed text. 400 Bad Request because anything in
@@ -141,46 +166,75 @@ export default class Telemetry {
 		// tool call attempts, reasoning bleed). Visible to the model so it
 		// sees the rejection on its next turn and can correct.
 		if (unparsed) {
-			await store.upsert(runId, turn, `content://${turn}`, unparsed, 400, {
+			await store.set({
+				runId,
+				turn,
+				path: `content://${turn}`,
+				body: unparsed,
+				state: "failed",
+				outcome: "unparsed",
 				loopId,
-				fidelity: "promoted",
+				visibility: "visible",
+				writer: "system",
 			});
 		}
 
-		// Commit usage stats
-		const usage = result.usage || {};
-		const cachedTokens =
-			usage.cached_tokens ||
-			usage.prompt_tokens_details?.cached_tokens ||
-			usage.input_tokens_details?.cached_tokens ||
-			usage.cache_read_input_tokens ||
-			0;
-		const reasoningTokens =
-			usage.reasoning_tokens ||
-			usage.completion_tokens_details?.reasoning_tokens ||
-			usage.output_tokens_details?.reasoning_tokens ||
-			0;
-		// Use LLM's actual prompt_tokens as the ground-truth context size when available.
-		// This back-fills context_tokens so get_last_context_tokens reflects reality for the next turn.
-		const actualContextTokens = usage.prompt_tokens || assembledTokens || 0;
-		await rummy.db.update_turn_stats.run({
+		// Commit usage stats. Providers surface token counts under
+		// incompatible keys; walk them in priority order and fall back
+		// to 0 only as the definitional "not reported" value.
+		const usage = result.usage ? result.usage : {};
+		const cachedSources = [
+			usage.cached_tokens,
+			usage.prompt_tokens_details?.cached_tokens,
+			usage.input_tokens_details?.cached_tokens,
+			usage.cache_read_input_tokens,
+		];
+		const reasoningSources = [
+			usage.reasoning_tokens,
+			usage.completion_tokens_details?.reasoning_tokens,
+			usage.output_tokens_details?.reasoning_tokens,
+		];
+		let cachedTokens = 0;
+		for (const v of cachedSources)
+			if (v) {
+				cachedTokens = v;
+				break;
+			}
+		let reasoningTokens = 0;
+		for (const v of reasoningSources)
+			if (v) {
+				reasoningTokens = v;
+				break;
+			}
+		// Use LLM's actual prompt_tokens as the ground-truth context size
+		// when available; falls back to our pre-call estimate.
+		let actualContextTokens = 0;
+		if (usage.prompt_tokens) actualContextTokens = usage.prompt_tokens;
+		else if (assembledTokens) actualContextTokens = assembledTokens;
+		const numberOrZero = (v) => (typeof v === "number" ? v : 0);
+		await rummy.entries.updateTurnStats({
 			id: rummy.turnId,
 			context_tokens: actualContextTokens,
-			reasoning_content: responseMessage?.reasoning_content || null,
-			prompt_tokens: usage.prompt_tokens ?? 0,
-			cached_tokens: cachedTokens ?? 0,
-			completion_tokens: usage.completion_tokens ?? 0,
-			reasoning_tokens: reasoningTokens ?? 0,
-			total_tokens: usage.total_tokens ?? 0,
-			cost: usage.cost ?? 0,
+			reasoning_content: responseMessage?.reasoning_content
+				? responseMessage.reasoning_content
+				: null,
+			prompt_tokens: numberOrZero(usage.prompt_tokens),
+			cached_tokens: cachedTokens,
+			completion_tokens: numberOrZero(usage.completion_tokens),
+			reasoning_tokens: reasoningTokens,
+			total_tokens: numberOrZero(usage.total_tokens),
+			cost: numberOrZero(usage.cost),
 		});
 	}
 
 	async #logMessages(messages, context) {
-		this.#currentRunAlias = context.runAlias || `run_${context.runId}`;
-		this.#currentTurn = context.turn ?? null;
+		this.#currentRunAlias = context.runAlias
+			? context.runAlias
+			: `run_${context.runId}`;
+		this.#currentTurn = context.turn === undefined ? null : context.turn;
+		const turnLabel = this.#currentTurn === null ? "?" : this.#currentTurn;
 		this.#turnLog.push(
-			`\n${"=".repeat(60)}\nTURN ${this.#currentTurn ?? "?"} — model=${context.model} run=${this.#currentRunAlias}\n${"=".repeat(60)}`,
+			`\n${"=".repeat(60)}\nTURN ${turnLabel} — model=${context.model} run=${this.#currentRunAlias}\n${"=".repeat(60)}`,
 		);
 		for (const msg of messages) {
 			const label = msg.role.toUpperCase();
@@ -195,34 +249,29 @@ export default class Telemetry {
 
 	async #logResponse(response) {
 		const msg = response.choices?.[0]?.message;
-		this.#turnLog.push(`\n--- ASSISTANT ---\n${msg?.content || "(empty)"}`);
+		const content = msg?.content ? msg.content : "(empty)";
+		this.#turnLog.push(`\n--- ASSISTANT ---\n${content}`);
 		if (msg?.reasoning_content) {
 			this.#turnLog.push(`\n--- REASONING ---\n${msg.reasoning_content}`);
 		}
-		const usage = response.usage || {};
+		const usage = response.usage ? response.usage : {};
 		this.#turnLog.push(`\n--- USAGE ---\n${JSON.stringify(usage)}`);
 		this.#flush();
 		this.#writeTurnFile();
 		return response;
 	}
 
-	#flush() {
+	async #flush() {
 		if (!this.#lastRunPath || this.#turnLog.length === 0) return;
-		writeFile(this.#lastRunPath, `${this.#turnLog.join("\n")}\n`).catch(
-			() => {},
-		);
+		await writeFile(this.#lastRunPath, `${this.#turnLog.join("\n")}\n`);
 	}
 
 	async #writeTurnFile() {
 		if (!this.#turnsDir || !this.#currentRunAlias || this.#currentTurn == null)
 			return;
 		const runDir = join(this.#turnsDir, this.#currentRunAlias);
-		try {
-			await mkdir(runDir, { recursive: true });
-			const fileName = `turn_${String(this.#currentTurn).padStart(3, "0")}.txt`;
-			await writeFile(join(runDir, fileName), `${this.#turnLog.join("\n")}\n`);
-		} catch {
-			// best effort — diagnostic feature, don't fail the turn
-		}
+		await mkdir(runDir, { recursive: true });
+		const fileName = `turn_${String(this.#currentTurn).padStart(3, "0")}.txt`;
+		await writeFile(join(runDir, fileName), `${this.#turnLog.join("\n")}\n`);
 	}
 }

package/src/plugins/think/README.md

@@ -1,4 +1,4 @@
-# think
+# think {#think_plugin}
 
 Provides a `<think>` tag for model reasoning. Not a tool — does not
 appear in the tool list.

package/src/plugins/think/think.js

@@ -14,5 +14,17 @@ export default class Think {
 				return docsMap;
 			});
 		}
+
+		// Merge <think> tag bodies into the turn's reasoning_content so
+		// models without a dedicated reasoning channel still expose their
+		// reasoning through the same field.
+		core.filter("llm.reasoning", (reasoning, { commands }) => {
+			const thinkText = commands
+				.filter((c) => c.name === "think")
+				.map((c) => c.body)
+				.filter(Boolean)
+				.join("\n");
+			return [reasoning, thinkText].filter(Boolean).join("\n");
+		});
 	}
 }

package/src/plugins/think/thinkDoc.js

@@ -1,16 +1,3 @@
-// Tool doc for <think/>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-	["## <think>[reasoning]</think> - Think before acting"],
-	[
-		"* Use <think></think> before any other tools to plan your approach",
-		"Positioning: think first, then act. Prevents degenerate tool-call storms.",
-	],
-	[
-		"* Reasoning inside <think></think> is private — it does not appear in your context",
-		"Frees the model to reason without consuming context budget.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "thinkDoc.md");

package/src/plugins/think/thinkDoc.md

@@ -0,0 +1,7 @@
+## <think>[reasoning]</think> - Think before acting
+
+* Use <think></think> before any other tools to plan your approach
+<!-- Positioning: think first, then act. Prevents degenerate tool-call storms. -->
+
+* Reasoning inside <think></think> is private — it does not appear in your context
+<!-- Frees the model to reason without consuming context budget. -->

package/src/plugins/unknown/README.md

@@ -1,4 +1,4 @@
-# unknown
+# unknown {#unknown_plugin}
 
 The Rumsfeld mechanism. The model registers what it doesn't know before acting.
 
@@ -9,7 +9,7 @@ The Rumsfeld mechanism. The model registers what it doesn't know before acting.
 - **Tool**: `unknown`
 - **Category**: `unknown`
 - **Handler**: None — recorded by TurnExecutor, deduplicated against existing unknowns.
-- **Filter**: `assembly.system` at priority 300 — renders `<unknowns>` section.
+- **Filter**: `assembly.user` at priority 200 — renders `<unknowns>` adjacent to `<prompt>` (priority 300), after `<performed>` (priority 100). Unknowns are active work, not stable environment state; they belong in the user packet.
 
 ## Projection
 
@@ -20,5 +20,5 @@ The Rumsfeld mechanism. The model registers what it doesn't know before acting.
 Unknowns are sticky — they persist across turns until the model explicitly
 removes them with `<rm>`. The model investigates unknowns using `<get>`,
 `<env>`, or `<ask_user>`, then removes resolved ones. Server deduplicates
-on insert. Each unknown renders with turn, fidelity, and tokens for
+on insert. Each unknown renders with turn, visibility, and tokens for
 temporal reasoning and context management.

package/src/plugins/unknown/unknown.js

@@ -8,12 +8,9 @@ export default class Unknown {
 			category: "unknown",
 		});
 		core.on("handler", this.handler.bind(this));
-		core.on("promoted", this.full.bind(this));
-		core.on("demoted", this.summary.bind(this));
-		core.filter("assembly.system", this.assembleUnknowns.bind(this), 300);
-		// <unknown> is internal — written via <set path="unknown://...">. Hidden
-		// from all model-facing tool lists. Handler still dispatches if the
-		// model emits <unknown> directly out of habit.
+		core.on("visible", this.full.bind(this));
+		core.on("summarized", this.summary.bind(this));
+		core.filter("assembly.user", this.assembleUnknowns.bind(this), 200);
 		core.markHidden();
 	}
 
@@ -23,7 +20,13 @@ export default class Unknown {
 		// Deduplicate — if this exact body already exists, skip
 		const existingValues = await store.getUnknownValues(runId);
 		if (existingValues.has(entry.body)) {
-			console.warn(`[RUMMY] Unknown deduped: "${entry.body.slice(0, 60)}"`);
+			await this.#core.hooks.error.log.emit({
+				store,
+				runId,
+				turn,
+				loopId,
+				message: `Unknown deduped: "${entry.body.slice(0, 60)}"`,
+			});
 			return;
 		}
 
@@ -35,29 +38,54 @@ export default class Unknown {
 			entry.body,
 			entry.attributes?.summary,
 		);
-		await store.upsert(runId, turn, unknownPath, entry.body, 200, { loopId });
+		await store.set({
+			runId,
+			turn,
+			path: unknownPath,
+			body: entry.body,
+			state: "resolved",
+			loopId,
+		});
 	}
 
 	full(entry) {
 		return entry.body;
 	}
 
-	summary() {
-		return "";
+	// Same principle as knowns: keep the first 500 characters on
+	// summarized unknowns so demotion doesn't erase the question,
+	// but cap large bodies to bound the packet cost.
+	summary(entry) {
+		if (!entry.body) return "";
+		if (entry.body.length <= 500) return entry.body;
+		return `${entry.body.slice(0, 500)}\n[truncated — promote to see the full question]`;
 	}
 
 	async assembleUnknowns(content, ctx) {
 		const entries = ctx.rows.filter((r) => r.category === "unknown");
 		if (entries.length === 0) return content;
+		const lines = entries.map((e) => renderUnknownTag(e));
+		return `${content}<unknowns>\n${lines.join("\n")}\n</unknowns>\n`;
+	}
+}
 
-		const lines = entries.map((u) => {
-			const fidelity = u.fidelity ? ` fidelity="${u.fidelity}"` : "";
-			const tokens = u.tokens ? ` tokens="${u.tokens}"` : "";
-			if (u.body) {
-				return `<unknown path="${u.path}" turn="${u.source_turn || u.turn}"${fidelity}${tokens}>${u.body}</unknown>`;
-			}
-			return `<unknown path="${u.path}" turn="${u.source_turn || u.turn}"${fidelity}${tokens}/>`;
-		});
-		return `${content}\n\n<unknowns>\n${lines.join("\n")}\n</unknowns>`;
+function renderUnknownTag(entry) {
+	const attrs =
+		typeof entry.attributes === "string"
+			? JSON.parse(entry.attributes)
+			: entry.attributes;
+	const turn = entry.source_turn ? ` turn="${entry.source_turn}"` : "";
+	const visibility = entry.visibility
+		? ` visibility="${entry.visibility}"`
+		: "";
+	const tokens = entry.aTokens != null ? ` tokens="${entry.aTokens}"` : "";
+	const summary =
+		typeof attrs?.summary === "string"
+			? ` summary="${attrs.summary.replace(/"/g, "'").slice(0, 80)}"`
+			: "";
+	const attrStr = `${turn}${summary}${visibility}${tokens}`;
+	if (entry.body) {
+		return `<unknown path="${entry.path}"${attrStr}>${entry.body}</unknown>`;
 	}
+	return `<unknown path="${entry.path}"${attrStr}/>`;
 }

package/src/plugins/unknown/unknownDoc.js

@@ -1,22 +1,3 @@
-// Tool doc for <unknown>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-	[
-		"## <unknown>[specific thing I need to learn]</unknown> - Register gaps for research",
-	],
-	[
-		'Example: <unknown path="unknown://answer">contents of answer.txt</unknown>',
-		"Path form: explicit unknown path for structured tracking.",
-	],
-	[
-		"* Investigate with Tool Commands",
-		"Unknowns drive action — get, env, search, ask_user.",
-	],
-	[
-		'* When resolved or irrelevant, remove with <set path="unknown://..." fidelity="archived"/>',
-		"Archive instead of delete — preserves the question for context history.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "unknownDoc.md");

package/src/plugins/unknown/unknownDoc.md

@@ -0,0 +1,11 @@
+## <set path="unknown://{question}">[specific thing I need to learn]</set> - Register gaps for research
+<!-- Use <set> to write unknown entries (not <unknown>). Matches instructions examples. -->
+
+Example: <set path="unknown://answer" summary="answer,contents">contents of answer.txt</set>
+<!-- Path form: explicit unknown path for structured tracking. -->
+
+* Investigate with Tool Commands
+<!-- Unknowns drive action — get, env, search, ask_user. -->
+
+* When resolved or irrelevant, remove with <set path="unknown://..." visibility="archived"/>
+<!-- Archive instead of delete — preserves the question for context history. -->

package/src/plugins/update/README.md

@@ -1,4 +1,4 @@
-# update
+# update {#update_plugin}
 
 Lifecycle signal — the model declares it has more work to do.
 

package/src/plugins/update/update.js

@@ -1,5 +1,17 @@
 import docs from "./updateDoc.js";
 
+const TERMINAL_STATUSES = new Set([200, 204, 422, 500]);
+
+const CONTRACT_REMINDER = "Missing update";
+
+const EMPTY_RESPONSE_REMINDER =
+	"Response empty - Update with status 500 if unable to fulfill request.";
+
+function isValidStatus(status) {
+	if (TERMINAL_STATUSES.has(status)) return true;
+	return Number.isInteger(status) && status >= 100 && status < 200;
+}
+
 export default class Update {
 	#core;
 
@@ -8,18 +20,68 @@ export default class Update {
 		core.ensureTool();
 		core.registerScheme({ category: "logging" });
 		core.on("handler", this.handler.bind(this));
-		core.on("promoted", this.full.bind(this));
-		core.on("demoted", this.summary.bind(this));
+		core.on("visible", this.full.bind(this));
+		core.on("summarized", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.update = docs;
 			return docsMap;
 		});
+		core.hooks.update = {
+			resolve: this.resolve.bind(this),
+		};
 	}
 
 	async handler(entry, rummy) {
-		const { entries: store, sequence: turn, runId, loopId } = rummy;
-		const statusPath = await store.slugPath(runId, "update", entry.body);
-		await store.upsert(runId, turn, statusPath, entry.body, 200, { loopId });
+		const status = entry.attributes?.status ?? 102;
+		await rummy.update(entry.body, { status });
+	}
+
+	/**
+	 * Classify this turn's update state.
+	 *
+	 * Returns { summaryText, updateText }:
+	 *   - summaryText: non-null → model claimed terminal (200/204/422)
+	 *   - updateText:  non-null → model is continuing (1xx)
+	 *
+	 * Errors (invalid status, missing update) emit via hooks.error.log.
+	 * The "terminal + turn had errors → not actually terminal" rule
+	 * lives in the error plugin's verdict, not here.
+	 */
+	async resolve({ recorded, content, runId, turn, loopId, rummy }) {
+		const entry = recorded.findLast((e) => e.scheme === "update");
+		const status = entry?.attributes?.status ?? 102;
+		const isTerminal = TERMINAL_STATUSES.has(status);
+		let summaryText = null;
+		let updateText = null;
+		if (entry?.body) {
+			if (isTerminal) summaryText = entry.body;
+			else updateText = entry.body;
+		}
+
+		if (entry && !isValidStatus(status)) {
+			await rummy.hooks.error.log.emit({
+				store: rummy.entries,
+				runId,
+				turn,
+				loopId,
+				message: `Invalid status ${entry.attributes?.status} on update — use 1xx to continue or 200 to conclude.`,
+				status: 422,
+			});
+		}
+
+		if (!summaryText && !updateText) {
+			const empty = !content || content.trim() === "";
+			await rummy.hooks.error.log.emit({
+				store: rummy.entries,
+				runId,
+				turn,
+				loopId,
+				message: empty ? EMPTY_RESPONSE_REMINDER : CONTRACT_REMINDER,
+				status: 422,
+			});
+		}
+
+		return { summaryText, updateText };
 	}
 
 	full(entry) {

package/src/plugins/update/updateDoc.js

@@ -1,31 +1,3 @@
-// Tool doc for <update>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-	[
-		"## <update>[brief status]</update> - Heartbeat for ongoing work (one per turn, at the end)",
-		"Header defines position and frequency. Without this, model uses update as inline narration between tools — multiple updates per turn.",
-	],
-	[
-		"Example: <update>Reading config files</update>",
-		"Progress checkpoint. Status signal, not a log entry.",
-	],
-	[
-		"Example: <update>Found 3 issues, fixing first</update>",
-		"Multi-step progress. Ongoing work.",
-	],
-	[
-		"* Urgent: ONE <update></update> per turn, AT THE END. Not inline narration between tools.",
-		"Single-update-per-turn is the missing rule. Model was emitting 3-6 updates per turn as progress commentary.",
-	],
-	[
-		"* If you'd repeat the same <update></update> as last turn, the work is either stuck or done. Take a different action or <summarize></summarize>.",
-		"Points at the zombie-loop failure mode directly. Gives the model a trigger (same-text-as-prior-update) and two remedies.",
-	],
-	[
-		"* YOU MUST keep <update></update> to <= 80 characters",
-		"Length cap.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "updateDoc.md");

package/src/plugins/update/updateDoc.md

@@ -0,0 +1,8 @@
+## <update status="N">{brief status}</update> - Status report (exactly one per turn, at the end)
+<!-- Header defines position, frequency, and status code requirement. -->
+
+REQUIRED: the valid values of N are defined by your current stage instructions.
+<!-- Single source of truth for codes is the current phase instructions block, not this doc. Listing codes here leaks termination knowledge (e.g. 200) that strong models use to short-circuit the protocol. -->
+
+REQUIRED: YOU MUST keep <update></update> body to <= 80 characters.
+<!-- Length cap. -->