@possumtech/rummy 0.5.0 → 2.0.1

package/src/plugins/instructions/instructions.js

@@ -1,28 +1,250 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import Protocol from "./protocol.js";
 
-const preamble = readFileSync(
-	new URL("./preamble.md", import.meta.url),
+const baseInstructions = readFileSync(
+	new URL("./instructions.md", import.meta.url),
 	"utf8",
 );
 
+// 1XY status encoding: X=current phase, Y=next phase. Y routes through
+// phaseForStatus to select next turn's <instructions>. Phases 4–9 are
+// reserved (status codes 1X4..1X9); add new phases by dropping in
+// `instructions_10N.md`. Absent files render no <instructions> block —
+// the model runs on base instructions only. This lets you route ahead
+// of writing the prose (e.g. an upcoming "ask lite" phase 9).
+const PHASES = [4, 5, 6, 7, 8, 9];
+const phaseInstructions = Object.fromEntries(
+	PHASES.flatMap((p) => {
+		const url = new URL(`./instructions_10${p}.md`, import.meta.url);
+		return existsSync(url) ? [[p, readFileSync(url, "utf8").trim()]] : [];
+	}),
+);
+const TURN_FROM_PATH = /^log:\/\/turn_(\d+)\/update\//;
+
+function phaseForStatus(status) {
+	if (status == null) return 4;
+	if (status === 200) return 7;
+	const last = status % 10;
+	return PHASES.includes(last) ? last : 4;
+}
+
+// Scan an already-materialized row set for the most recent update
+// emission's status. Used by the assembly.user filter so the phase
+// instructions ride with the user message (dynamic, expected to
+// change every turn) instead of the system prompt (stable, cached).
+// Validation is upstream (update.js isValidStatus + 422 error log) so
+// we trust the status and route on it directly — a whitelist here
+// silently drops advertised completion codes whose contracts drift,
+// which is worse than a noisy fallback.
+function latestUpdateStatusFromRows(rows) {
+	let bestTurn = -1;
+	let bestStatus = null;
+	for (const r of rows) {
+		const m = TURN_FROM_PATH.exec(r.path);
+		if (!m) continue;
+		const turn = Number(m[1]);
+		const attrs =
+			typeof r.attributes === "string"
+				? JSON.parse(r.attributes)
+				: r.attributes;
+		const status = attrs?.status;
+		if (status == null) continue;
+		// Rejected updates are written for the model's audit trail but are
+		// not navigation events — phase router skips them so the model
+		// stays in the stage it was already in.
+		if (attrs?.rejected) continue;
+		if (turn > bestTurn || (turn === bestTurn && status > bestStatus)) {
+			bestTurn = turn;
+			bestStatus = status;
+		}
+	}
+	return bestStatus;
+}
+
 export default class Instructions {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.on("promoted", this.full.bind(this));
+		core.on("visible", this.full.bind(this));
 		core.on("turn.started", this.onTurnStarted.bind(this));
+		core.hooks.instructions.resolveSystemPrompt =
+			this.resolveSystemPrompt.bind(this);
+		core.hooks.instructions.validateNavigation =
+			this.validateNavigation.bind(this);
+		core.hooks.instructions.findLatestSummary =
+			this.findLatestSummary.bind(this);
+		// Dynamic phase instructions live in the user message (above
+		// <prompt>) so the system message stays cache-stable across turns.
+		// Priority 250 puts us between <log> (100), <unknowns> (200),
+		// and <prompt> (300).
+		core.filter("assembly.user", this.assembleInstructions.bind(this), 250);
+		new Protocol(core);
+	}
+
+	/**
+	 * Materialize the system prompt for a run: look up the
+	 * instructions://system entry, project it through the promoted view.
+	 * TurnExecutor calls this once per turn before context assembly.
+	 */
+	async resolveSystemPrompt(rummy) {
+		const { entries: store, runId, hooks } = rummy;
+		const entries = await store.getEntriesByPattern(
+			runId,
+			"instructions://system",
+			null,
+			{ includeAuditSchemes: true },
+		);
+		// The entry is always written by onTurnStarted before this runs.
+		const entry = entries[0];
+		const attributes = await store.getAttributes(
+			runId,
+			"instructions://system",
+		);
+		return hooks.tools.view("instructions", {
+			path: "instructions://system",
+			scheme: "instructions",
+			body: entry.body,
+			attributes,
+			visibility: "visible",
+			category: "system",
+		});
+	}
+
+	/**
+	 * Reject illegal stage navigation. Two checks:
+	 *
+	 *   1. Forward skip — `nextPhase > currentPhase + 1`. Models advancing
+	 *      more than one stage at a time are jumping past required work.
+	 *      Returns and continuations (nextPhase ≤ currentPhase) always pass.
+	 *
+	 *   2. Deployment with prior prompts — any status landing the model in
+	 *      Deployment (phase 7) requires zero visible PRIOR prompts. State-
+	 *      property rule covering both entry (167) and continuation (177,
+	 *      200) — once in Deployment, the model still can't claim it with
+	 *      undemoted prior prompts. The current (latest) prompt always
+	 *      stays visible since Deployment must act on it.
+	 *
+	 * On rejection the caller marks the update entry rejected (so the
+	 * phase router skips it) and emits an error log; navigation rejections
+	 * count as normal strikes.
+	 */
+	async validateNavigation(status, rummy) {
+		const currentPhase = await this.#getCurrentPhase(rummy);
+		const nextPhase = phaseForStatus(status);
+		if (nextPhase > currentPhase + 1) {
+			return { ok: false, reason: "Illegal navigation attempt" };
+		}
+		if (nextPhase === 7) {
+			const visible = await this.#countVisiblePriorPrompts(rummy);
+			if (visible > 0) {
+				return {
+					ok: false,
+					reason: `Illegal navigation attempt: ${visible} visible prior prompts`,
+				};
+			}
+		}
+		return { ok: true };
+	}
+
+	async #getCurrentPhase(rummy) {
+		// `**` (not `*`) for the slug position — update slugs are derived
+		// from the model's update body and can contain URL-encoded `/`
+		// characters (e.g. `known%3A//foo/bar` in a "ready for deployment"
+		// summary). Single `*` doesn't cross those embedded slashes and
+		// silently misses the prior turn's update.
+		const updates = await rummy.entries.getEntriesByPattern(
+			rummy.runId,
+			"log://*/update/**",
+			null,
+		);
+		let bestTurn = -1;
+		let bestStatus = null;
+		for (const e of updates) {
+			const m = TURN_FROM_PATH.exec(e.path);
+			if (!m) continue;
+			const turn = Number(m[1]);
+			if (turn >= rummy.sequence) continue;
+			const attrs =
+				typeof e.attributes === "string"
+					? JSON.parse(e.attributes)
+					: e.attributes;
+			if (attrs?.rejected) continue;
+			if (attrs?.status == null) continue;
+			if (turn > bestTurn) {
+				bestTurn = turn;
+				bestStatus = attrs.status;
+			}
+		}
+		return phaseForStatus(bestStatus);
+	}
+
+	/**
+	 * Find the latest successful Deployment summary from a log-entry list.
+	 * Matches `log://turn_N/update/...` entries with status=200 (successful
+	 * Deployment completion) and returns the most recent. Used by
+	 * AgentLoop telemetry to surface the model's latest delivery.
+	 *
+	 * Lives here, not in AgentLoop, because "what counts as a summary" is
+	 * state-machine knowledge — phase 7's success status (200) is the
+	 * definition. AgentLoop just consumes the result.
+	 */
+	findLatestSummary(logEntries) {
+		return logEntries
+			.filter((e) => {
+				if (!TURN_FROM_PATH.test(e.path)) return false;
+				const attrs =
+					typeof e.attributes === "string"
+						? JSON.parse(e.attributes)
+						: e.attributes;
+				return attrs?.status === 200;
+			})
+			.at(-1);
+	}
+
+	async #countVisiblePriorPrompts(rummy) {
+		const prompts = await rummy.entries.getEntriesByPattern(
+			rummy.runId,
+			"prompt://*",
+			null,
+		);
+		const visible = prompts.filter((p) => p.visibility === "visible");
+		if (visible.length === 0) return 0;
+		// Exclude the current (latest) prompt — that's what Deployment acts on.
+		// Demoting it would force the model to deliver on content it hid from
+		// itself. Only PRIOR prompts are subject to demote-before-Deployment.
+		let maxNum = -1;
+		for (const p of visible) {
+			const m = /^prompt:\/\/(\d+)$/.exec(p.path);
+			if (m && Number(m[1]) > maxNum) maxNum = Number(m[1]);
+		}
+		return visible.filter((p) => {
+			const m = /^prompt:\/\/(\d+)$/.exec(p.path);
+			return !m || Number(m[1]) !== maxNum;
+		}).length;
 	}
 
 	async onTurnStarted({ rummy }) {
 		const { entries: store, sequence: turn, runId } = rummy;
-		const runRow = await rummy.db.get_run_by_id.get({ id: runId });
+		const runRow = await store.getRun(runId);
 		const toolSet = rummy.toolSet
 			? [...rummy.toolSet]
 			: this.#core.hooks.tools.names;
-		await store.upsert(runId, turn, "instructions://system", "", 200, {
+		// instructions:// is an audit scheme (writable_by: ["system"]).
+		// No per-turn phase state on this entry — keeps the system
+		// prompt cache-stable across turns. Phase selection happens at
+		// assembly.user time from the current row set.
+		await store.set({
+			runId,
+			turn,
+			path: "instructions://system",
+			body: "",
+			state: "resolved",
+			writer: "system",
 			attributes: {
-				persona: runRow?.persona || null,
+				// runRow.persona is a nullable TEXT column; absent row is
+				// a system bug — let the null propagate if runRow exists.
+				persona: runRow.persona,
 				toolSet,
 			},
 		});
@@ -41,15 +263,28 @@ export default class Instructions {
 		const sorted = this.#core.hooks.tools.advertisedNames.filter((n) =>
 			activeTools.has(n),
 		);
-		const tools = sorted.join(", ");
+		const tools = sorted.map((n) => `<${n}/>`).join(", ");
 		const docsText = sorted
 			.filter((key) => toolDocs[key])
 			.map((key) => toolDocs[key])
 			.join("\n\n");
-		let prompt = preamble
+		let prompt = baseInstructions
 			.replace("[%TOOLS%]", tools)
 			.replace("[%TOOLDOCS%]", docsText);
 		if (attrs.persona) prompt += `\n\n## Persona\n\n${attrs.persona}`;
 		return prompt;
 	}
+
+	// Renders the current phase's instructions as an <instructions>
+	// block in the user message. Runs at priority 250 — after <log>
+	// and <unknowns>, immediately before <prompt>. System prompt stays
+	// static so prompt caching keeps its prefix intact across turns.
+	// A routed phase without an instructions_10N.md file emits nothing —
+	// the model proceeds on base instructions alone.
+	assembleInstructions(content, ctx) {
+		const status = latestUpdateStatusFromRows(ctx.rows);
+		const step = phaseInstructions[phaseForStatus(status)];
+		if (!step) return content;
+		return `${content}<instructions>\n${step}\n</instructions>\n`;
+	}
 }

package/src/plugins/instructions/instructions.md

@@ -0,0 +1,33 @@
+XML Commands Available: [%TOOLS%]
+
+# FCRM State Machine
+
+You are a Folksonomic Context Relevance Maximization (FCRM) State Machine
+
+YOU MUST perform the actions corresponding with your current stage:
+* Definition Stage: Defining what's unknown into unknown:// entries
+* Discovery Stage: Selecting an unknown, discovering relevant source entries and prompts, then distilling them into known:// entries
+* Demotion Stage: Demoting the unknown entries, source entries, prompts, and log events after distillation is completed
+* Deployment Stage: Acting on the current prompt
+* Resolution Stage: Multi-prompt benchmark final `fcrmScore`
+
+## Visibility States: Promote and Demote Visibility State to Control Context Relevance
+* visible: Fully visible, but uses `tokens="N"` context budget
+* summarized: Approximate, summary information, very small context budget penalty
+* archived: Hidden from Context, but can be retrieved later with <get path="..."/>
+
+Tip: You can leverage the FCRM's Visibility States with folksonomic taxonomies and tags to store and recall unlimited information.
+Tip: The `tokens="N"` shows how much context memory is consumed if "visible". Entries only consume tokens when at "visible" visibility.
+
+Warning: YOU MUST NOT allow the `tokens="N"` sum of irrelevant source entries, prompts, or log events to exceed `tokensFree` budget.
+Warning: YOU MUST NOT skip or avoid state machine steps or the Resolution Stage will fail.
+
+# Commands
+
+Warning: YOU MUST NOT use shell commands for project file operations. Project files are entries that require XML Commands.
+Example: <set path="src/file.txt">new file content</set>
+Example: <get path="src/*.txt" preview/>
+
+Tip: Project files, entries, prompts, and log events are all accessible with the XML Commands.
+
+[%TOOLDOCS%]

package/src/plugins/instructions/instructions_104.md

@@ -0,0 +1,7 @@
+# Definition Stage: YOU MUST ONLY create topical, taxonomized, and tagged unknown:// entries for missing information
+
+Example: <set path="unknown://countries/france/capital" summary="countries,france,capital,geography,trivia">What is the capital of France?</set>
+
+
+## Turn Termination:
+* Definition Stage Completion: <update status="145">unknowns identified</update>

package/src/plugins/instructions/instructions_105.md

@@ -0,0 +1,38 @@
+# Discovery Stage: YOU MUST select an unknown:// entry, then discover its source entries and distill them into known:// entries
+
+YOU MUST create topical, taxonomized, and tagged known:// entries to resolve the selected unknown:// entry.
+YOU MUST reference all related source entries and prompts.
+YOU MUST ONLY populate known entries with promoted information, NOT from your own training data or opinion.
+YOU MUST immediately demote unknowns, source entries, prompts, and log events after they are distilled, irrelevant, or resolved.
+
+Tip: Check the `tokens="N"` of the source entries against the `tokensFree="N"` constraint before promoting entries.
+Tip: You can use <get path="..." preview/> to preview the potential `tokens="N"` budget impact of bulk operations.
+Tip: You can use <get path="..." line="X" limit="Y"/> to read subsets of entries that would exceed your `tokensFree` budget.
+
+## Example:
+	<get path="**" preview>capital</get>
+	<get path="prompt://3" line="1" limit="100"/>
+
+	<set path="trivia/capitals.csv" visibility="visible"/>
+
+	<set path="known://countries/france/capital" summary="countries,france,capital,geography,trivia">
+		# Capital of France
+		The capital of France is Paris.
+
+		{...}
+
+		## Related
+		[trivia question](prompt://3)
+		[unknown resolving](unknown://countries/france/capital)
+		[source entry](trivia/capitals.csv)
+	</set>
+
+	<set path="prompt://3" visibility="summarized"/>
+	<set path="unknown://countries/france/capital" visibility="summarized"/>
+	<set path="unknown://countries/france/seat_of_government" summary="RESOLVED: Not necessary" visibility="summarized"/>
+	<set path="trivia/capitals.csv" visibility="summarized"/>
+
+## Turn Termination (CHOOSE ONLY ONE):
+* Definition Stage Return: <update status="154">returning to Definition Stage</update>
+* Discovery Stage Continuation: <update status="155">discovering and distilling more for the selected unknown</update>
+* Discovery Stage Completion: <update status="156">this unknown's known entries written</update>

package/src/plugins/instructions/instructions_106.md

@@ -0,0 +1,21 @@
+# Demotion Stage: YOU MUST demote all source entries, prompts, and log events that are now distilled or no longer relevant
+
+Examples:
+<set path="prompt://2" summary="All information distilled into knowns" visibility="summarized"/>
+<set path="trivia/capitals.csv" visibility="summarized"/>
+<set path="unknown://countries/france/capital" visibility="summarized"/>
+<set path="unknown://countries/poland/capital" summary="REJECTED: Irrelevant" visibility="summarized"/>
+<set path="https://en.wikipedia.org/wiki/Paris,_Texas" summary="REJECTED: Wrong Paris" visibility="summarized"/>
+<set path="log://turn_1/**" visibility="archived"/>
+<set path="log://turn_2/**" visibility="archived"/>
+<set path="log://turn_3/set/**" visibility="archived"/>
+<set path="log://turn_3/get/**" visibility="archived"/>
+<set path="log://turn_3/search/**" visibility="archived"/>
+
+Tip: You need room to think. Demote large prompts and source entries, then iterate them with <get path="..." line="N" limit="N"/> as necessary.
+
+## Turn Termination (CHOOSE ONLY ONE):
+* Definition Stage Return: <update status="164">returning to Definition Stage</update>
+* Discovery Stage Return: <update status="165">more unknowns remain; returning to Discovery Stage</update>
+* Demotion Stage Continuation: <update status="166">demoting more distilled or irrelevant entries, prompts, and log events</update>
+* Demotion Stage Completion: <update status="167">all unknowns resolved and demoted; ready for Deployment Stage</update>

package/src/plugins/instructions/instructions_107.md

@@ -0,0 +1,10 @@
+# Deployment Stage
+
+YOU MUST act on the prompt.
+
+## Turn Termination (CHOOSE ONLY ONE):
+* Definition Stage Return: <update status="174">returning to Definition Stage</update>
+* Discovery Stage Return: <update status="175">returning to Discovery Stage</update>
+* Demotion Stage Return: <update status="176">returning to Demotion Stage</update>
+* Deployment Stage Continuation: <update status="177">performing more actions</update>
+* Deployment Stage Completion: <update status="200">{direct answer if prompt asked a question, summary of actions if not}</update>

package/src/plugins/instructions/protocol.js

@@ -0,0 +1,12 @@
+export default class Protocol {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.filter("entry.recording", this.#onRecording.bind(this), 1);
+	}
+
+	async #onRecording(entry, _ctx) {
+		return entry;
+	}
+}

package/src/plugins/known/README.md

@@ -1,6 +1,6 @@
-# known
+# known {#known_plugin}
 
-Writes knowledge entries into the store at full fidelity.
+Writes knowledge entries into the store at full visibility.
 
 ## Registration
 

package/src/plugins/known/known.js

@@ -1,6 +1,7 @@
+import { stateToStatus } from "../../agent/httpStatus.js";
 import { countTokens } from "../../agent/tokens.js";
 
-const MAX_ENTRY_TOKENS = Number(process.env.RUMMY_MAX_ENTRY_TOKENS) || 512;
+const MAX_ENTRY_TOKENS = Number(process.env.RUMMY_MAX_ENTRY_TOKENS);
 
 export default class Known {
 	#core;
@@ -9,9 +10,9 @@ export default class Known {
 		this.#core = core;
 		core.registerScheme({ category: "data" });
 		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.assembleKnown.bind(this), 100);
+		core.on("visible", this.full.bind(this));
+		core.on("summarized", this.summary.bind(this));
+		core.filter("assembly.system", this.assembleContext.bind(this), 100);
 		// <known> is internal — written via <set path="known://...">. Hidden
 		// from all model-facing tool lists. Handler still dispatches if the
 		// model emits <known> directly out of habit.
@@ -26,19 +27,20 @@ export default class Known {
 		const entryTokens = countTokens(entry.body);
 		if (entryTokens > MAX_ENTRY_TOKENS) {
 			const rejectPath = await store.slugPath(runId, "known", entry.body);
-			await store.upsert(
+			await store.set({
 				runId,
 				turn,
-				rejectPath,
-				`Entry too large (${entryTokens} tokens, max ${MAX_ENTRY_TOKENS}). Sort the information, ideas, or plans carefully into multiple entries.`,
-				413,
-				{ loopId },
-			);
+				path: rejectPath,
+				body: `Entry too large (${entryTokens} tokens, max ${MAX_ENTRY_TOKENS}). Sort the information, ideas, or plans carefully into multiple entries.`,
+				state: "failed",
+				outcome: `overflow:${entryTokens}`,
+				loopId,
+			});
 			return;
 		}
 
 		// Resolve path: explicit or auto-generated slug
-		let knownPath = entry.attributes?.path || null;
+		let knownPath = entry.attributes?.path;
 		if (knownPath && !knownPath.includes("://")) {
 			knownPath = `known://${knownPath}`;
 		}
@@ -51,21 +53,30 @@ export default class Known {
 			);
 		}
 
-		// Dedup: if path exists, update rather than duplicate
+		// Dedup: if path exists, update rather than duplicate. An empty
+		// new body means "preserve the existing entry's body" (e.g. the
+		// model is updating attributes only).
 		const existing = await store.getEntriesByPattern(runId, knownPath, null);
 		if (existing.length > 0) {
-			await store.upsert(
+			const nextBody = entry.body === "" ? existing[0].body : entry.body;
+			await store.set({
 				runId,
 				turn,
-				existing[0].path,
-				entry.body || existing[0].body,
-				200,
-				{ attributes: entry.attributes, loopId },
-			);
+				path: existing[0].path,
+				body: nextBody,
+				state: "resolved",
+				attributes: entry.attributes,
+				loopId,
+			});
 			return;
 		}
 
-		await store.upsert(runId, turn, knownPath, entry.body, 200, {
+		await store.set({
+			runId,
+			turn,
+			path: knownPath,
+			body: entry.body,
+			state: "resolved",
 			attributes: entry.attributes,
 			loopId,
 		});
@@ -75,33 +86,53 @@ export default class Known {
 		return entry.body;
 	}
 
-	summary() {
-		return "";
+	// Summarized knowns keep the first 500 characters so the model
+	// doesn't lose the plot when budget auto-demotion kicks in on its
+	// own work. Anything larger gets capped so a pathologically big
+	// known doesn't saturate the packet at summarized visibility
+	// either. Matches the pattern on `<prompt>` summarized view.
+	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 body]`;
 	}
 
-	async assembleKnown(content, ctx) {
+	async assembleContext(content, ctx) {
 		const entries = ctx.rows.filter((r) => r.category === "data");
 		if (entries.length === 0) return content;
-
-		// Rows arrive pre-sorted by SQL: summary → full, then by recency
-		const demotedSet = new Set(ctx.demoted || []);
-		const lines = entries.map((e) => renderKnownTag(e, demotedSet));
-		return `${content}\n\n<knowns>\n${lines.join("\n")}\n</knowns>`;
+		const demotedSet = new Set(ctx.demoted);
+		const lines = entries.map((e) => renderContextTag(e, demotedSet));
+		return `${content}\n\n<context>\n${lines.join("\n")}\n</context>`;
 	}
 }
 
-function renderKnownTag(entry, demotedSet) {
-	const tag = entry.scheme || "file";
+function renderContextTag(entry, demotedSet) {
+	// schemeOf() returns NULL / "" for bare file paths; translate for the tag.
+	const tag = entry.scheme ? entry.scheme : "file";
 	const turn = entry.source_turn ? ` turn="${entry.source_turn}"` : "";
-	const tokens = entry.tokens ? ` tokens="${entry.tokens}"` : "";
-	const status = entry.status ? ` status="${entry.status}"` : "";
-	const fidelity = entry.fidelity ? ` fidelity="${entry.fidelity}"` : "";
-	const flag = demotedSet?.has(entry.path) ? " demoted" : "";
-
+	const tokens = entry.aTokens != null ? ` tokens="${entry.aTokens}"` : "";
+	const lines = entry.vLines != null ? ` lines="${entry.vLines}"` : "";
 	const attrs =
 		typeof entry.attributes === "string"
 			? JSON.parse(entry.attributes)
 			: entry.attributes;
+	const statusValue =
+		attrs?.status != null
+			? attrs.status
+			: entry.state
+				? stateToStatus(entry.state, entry.outcome)
+				: null;
+	const status =
+		statusValue != null && statusValue !== 200
+			? ` status="${statusValue}"`
+			: "";
+	const stateAttr =
+		entry.state && entry.state !== "resolved" ? ` state="${entry.state}"` : "";
+	const outcomeAttr = entry.outcome ? ` outcome="${entry.outcome}"` : "";
+	const visibility = entry.visibility
+		? ` visibility="${entry.visibility}"`
+		: "";
+	const flag = demotedSet?.has(entry.path) ? " demoted" : "";
 	// Always render summary attribute on knowns — empty value hints the model
 	// it forgot to add searchable keywords.
 	const summaryText =
@@ -110,8 +141,9 @@ function renderKnownTag(entry, demotedSet) {
 			: "";
 	const summary = ` summary="${summaryText}"`;
 
+	const attrStr = `${turn}${status}${stateAttr}${outcomeAttr}${summary}${visibility}${tokens}${lines}${flag}`;
 	if (entry.body) {
-		return `<${tag} path="${entry.path}"${turn}${status}${summary}${fidelity}${tokens}${flag}>${entry.body}</${tag}>`;
+		return `<${tag} path="${entry.path}"${attrStr}>${entry.body}</${tag}>`;
 	}
-	return `<${tag} path="${entry.path}"${turn}${status}${summary}${fidelity}${tokens}${flag}/>`;
+	return `<${tag} path="${entry.path}"${attrStr}/>`;
 }

package/src/plugins/known/knownDoc.js

@@ -1,18 +1,3 @@
-// Tool doc for <known/>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-	[
-		'## <known path="known://topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</known> - Sort and save what you learn for later recall',
-	],
-	[
-		'Example: <known path="known://people/rumsfeld" summary="defense,secretary,born,1932">Donald Rumsfeld was born in 1932 and served as Secretary of Defense</known>',
-		"Explicit path form: slashed path=category/key, summary=keywords.",
-	],
-	[
-		'* Recall with <get path="known://people/*">keyword</get>',
-		"Cross-tool lifecycle: pattern by category, filter by keyword.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "knownDoc.md");

package/src/plugins/known/knownDoc.md

@@ -0,0 +1,8 @@
+## <set path="known://topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</set> - Sort and save what you learn for later recall
+<!-- Use <set> to write known entries (not <known>). Matches instructions examples. -->
+
+Example: <set path="known://people/rumsfeld" summary="defense,secretary,born,1932">Donald Rumsfeld was born in 1932 and served as Secretary of Defense</set>
+<!-- Explicit path form: slashed path=category/key, summary=keywords. -->
+
+* Recall with <get path="known://people/*">keyword</get>
+<!-- Cross-tool lifecycle: pattern by category, filter by keyword. -->