@possumtech/rummy 0.4.0 → 2.0.0

package/src/plugins/hedberg/README.md

@@ -1,4 +1,4 @@
-# hedberg
+# hedberg {#hedberg_plugin}
 
 The interpretation boundary between stochastic model output and
 deterministic system operations.
@@ -26,7 +26,6 @@ constructor(core) {
 | `replace(body, search, replacement, opts?)` | Apply replacement (sed regex → literal → heuristic) |
 | `parseSed(input)` | Parse sed syntax into `[{ search, replace, flags, sed }]` |
 | `parseEdits(content)` | Detect edit format (merge conflict, udiff, Claude XML) |
-| `normalizeAttrs(attrs)` | Heal model attribute names (value→body, unknown→path) |
 | `generatePatch(path, old, new)` | Generate unified diff |
 
 ### Hedberg.replace(body, search, replacement, options?)

package/src/plugins/hedberg/hedberg.js

@@ -1,6 +1,6 @@
 import { parseEditContent } from "./edits.js";
 import HeuristicMatcher, { generatePatch } from "./matcher.js";
-import { normalizeAttrs, parseJsonEdit } from "./normalize.js";
+import { parseJsonEdit } from "./normalize.js";
 import { hedmatch, hedsearch } from "./patterns.js";
 import { parseSed } from "./sed.js";
 
@@ -14,7 +14,6 @@ import { parseSed } from "./sed.js";
  *   core.hedberg.replace(body, search, replacement, options?)
  *   core.hedberg.parseSed(input)
  *   core.hedberg.parseEdits(content)
- *   core.hedberg.normalizeAttrs(attrs)
  *   core.hedberg.generatePatch(path, old, new)
  */
 export default class Hedberg {
@@ -30,7 +29,6 @@ export default class Hedberg {
 			parseSed,
 			parseEdits: parseEditContent,
 			parseJsonEdit,
-			normalizeAttrs,
 			generatePatch,
 		};
 
@@ -57,7 +55,13 @@ export default class Hedberg {
 					searchText,
 					flags.includes("g") ? flags : `${flags}g`,
 				);
-				patch = body.replace(re, replaceText);
+				// Unescape regex metacharacter escapes in the replacement string.
+				// The model writes `\[x\]` meaning literal `[x]` in both search
+				// and replace. RegExp handles this in search; in the replacement
+				// string we must strip the backslashes ourselves since
+				// String.replace only interprets `$` sequences, not `\`.
+				const unescaped = replaceText.replace(/\\([[\](){}.*+?^$|\\])/g, "$1");
+				patch = body.replace(re, unescaped);
 				if (patch === body) patch = null;
 			} catch {
 				// Invalid regex — fall through to literal/heuristic interpretation

package/src/plugins/hedberg/matcher.js

@@ -1,9 +1,9 @@
 import { createTwoFilesPatch } from "diff";
 
-export function generatePatch(filePath, oldContent, newContent) {
+export function generatePatch(entryPath, oldContent, newContent) {
 	return createTwoFilesPatch(
-		`${filePath}\told`,
-		`${filePath}\tnew`,
+		`${entryPath}\told`,
+		`${entryPath}\tnew`,
 		oldContent,
 		newContent,
 		"",
@@ -13,37 +13,36 @@ export function generatePatch(filePath, oldContent, newContent) {
 }
 
 export default class HeuristicMatcher {
-	static matchAndPatch(filePath, fileContent, searchBlock, replaceBlock) {
+	static matchAndPatch(entryPath, entryBody, searchBlock, replaceBlock) {
 		// Unescape common regex escapes (models often escape brackets, parens, etc.)
 		const unescaped = searchBlock.replace(/\\([[\](){}.*+?^$|\\])/g, "$1");
-		if (unescaped !== searchBlock && fileContent.includes(unescaped)) {
+		if (unescaped !== searchBlock && entryBody.includes(unescaped)) {
 			searchBlock = unescaped;
 		}
 
 		const searchLines = searchBlock.split(/\r?\n/);
-		const fileLines = fileContent.split(/\r?\n/);
+		const fileLines = entryBody.split(/\r?\n/);
 
 		// 1. Exact Match Attempt (line-boundary substring search)
-		let exactIdx = fileContent.indexOf(searchBlock);
+		let exactIdx = entryBody.indexOf(searchBlock);
 		let lastExactIdx = -1;
 		let exactCount = 0;
 		while (exactIdx !== -1) {
-			const atLineBoundary =
-				exactIdx === 0 || fileContent[exactIdx - 1] === "\n";
+			const atLineBoundary = exactIdx === 0 || entryBody[exactIdx - 1] === "\n";
 			if (atLineBoundary) {
 				exactCount++;
 				lastExactIdx = exactIdx;
 			}
-			exactIdx = fileContent.indexOf(searchBlock, exactIdx + 1);
+			exactIdx = entryBody.indexOf(searchBlock, exactIdx + 1);
 		}
 
 		if (exactCount > 0) {
 			const useIdx = lastExactIdx;
 			const newContent =
-				fileContent.slice(0, useIdx) +
+				entryBody.slice(0, useIdx) +
 				replaceBlock +
-				fileContent.slice(useIdx + searchBlock.length);
-			const patch = generatePatch(filePath, fileContent, newContent);
+				entryBody.slice(useIdx + searchBlock.length);
+			const patch = generatePatch(entryPath, entryBody, newContent);
 			const warning =
 				exactCount > 1
 					? `SEARCH block matched ${exactCount} locations. Edit was applied to the last occurrence. Use more surrounding context in future edits to avoid ambiguity.`
@@ -59,9 +58,9 @@ export default class HeuristicMatcher {
 
 		if (searchTokens.length === 0) {
 			// Empty SEARCH = append REPLACE to end of file
-			const trailing = fileContent.endsWith("\n") ? "" : "\n";
-			const newContent = `${fileContent + trailing + replaceBlock}\n`;
-			const patch = generatePatch(filePath, fileContent, newContent);
+			const trailing = entryBody.endsWith("\n") ? "" : "\n";
+			const newContent = `${entryBody + trailing + replaceBlock}\n`;
+			const patch = generatePatch(entryPath, entryBody, newContent);
 			return { patch, newContent, warning: null, error: null };
 		}
 
@@ -149,7 +148,7 @@ export default class HeuristicMatcher {
 		];
 		const newContent = newFileLines.join("\n");
 
-		const patch = generatePatch(filePath, fileContent, newContent);
+		const patch = generatePatch(entryPath, entryBody, newContent);
 
 		if (fuzzyAmbiguous) {
 			warning =

package/src/plugins/hedberg/normalize.js

@@ -1,51 +1,3 @@
-/**
- * Attribute normalization. Heals legacy and alternative attribute names
- * from model output into canonical form.
- *
- * - value="" → body=""
- * - file="" or key="" → path="" (first unrecognized attr becomes path)
- * - preview="" → preview=true
- */
-
-const KNOWN_ATTRS = new Set([
-	"path",
-	"body",
-	"preview",
-	"question",
-	"options",
-	"search",
-	"replace",
-	"to",
-	"results",
-	"command",
-	"warn",
-	"summary",
-	"fidelity",
-]);
-
-export function normalizeAttrs(attrs) {
-	const out = { ...attrs };
-	if ("value" in out && !("body" in out)) {
-		out.body = out.value;
-		delete out.value;
-	}
-	if (!out.path) {
-		for (const [k, v] of Object.entries(out)) {
-			if (!KNOWN_ATTRS.has(k) && v) {
-				out.path = v;
-				delete out[k];
-				break;
-			}
-		}
-	}
-	if ("preview" in out) out.preview = true;
-	// summary="..." is the description text, not a fidelity flag
-	if ("summary" in out && !out.summary) out.summary = true;
-	// file:// prefix — strip silently, bare paths are the convention
-	if (out.path?.startsWith("file://")) out.path = out.path.slice(7);
-	return out;
-}
-
 /**
  * Parse JSON-style edit from body content.
  * Accepts: {"search":"old","replace":"new"} and {search="old",replace="new"}

package/src/plugins/helpers.js

@@ -1,3 +1,35 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Read a sibling tooldoc markdown file and return its model-facing text.
+ * Strips HTML comments (rationale stays in source, never reaches the model)
+ * and collapses any blank-line runs left behind. Each plugin's Doc.js is a
+ * one-liner that defers to this so authors edit normal markdown instead of
+ * a JS array of [text, rationale] pairs.
+ */
+export function loadDoc(metaUrl, name) {
+	const dir = dirname(fileURLToPath(metaUrl));
+	return readFileSync(join(dir, name), "utf8")
+		.replace(/<!--[\s\S]*?-->/g, "")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+/**
+ * Translate a log entry path into its companion data-scheme base path.
+ * `log://turn_N/{action}/{rest}` → `{action}://turn_N/{rest}`.
+ * Streaming producers (sh, env) create data channel entries under the
+ * producer scheme while the audit record lives in the log scheme; this
+ * helper bridges the two namespaces. Returns null for non-log paths.
+ */
+export function logPathToDataBase(logPath) {
+	const m = logPath?.match(/^log:\/\/turn_(\d+)\/([^/]+)\/(.+)$/);
+	if (!m) return null;
+	return `${m[2]}://turn_${m[1]}/${m[3]}`;
+}
+
 /**
  * Shared helper for pattern-based tool results.
  * Used by get, set, store, and rm tools.
@@ -10,13 +42,21 @@ export async function storePatternResult(
 	path,
 	bodyFilter,
 	matches,
-	{ preview = false, loopId = null } = {},
+	{ preview = false, loopId = null, attributes = null } = {},
 ) {
-	const slug = await store.slugPath(runId, scheme, path);
+	const logSlug = await store.logPath(runId, turn, scheme, path);
 	const filter = bodyFilter ? ` body="${bodyFilter}"` : "";
 	const total = matches.reduce((s, m) => s + m.tokens, 0);
 	const listing = matches.map((m) => `${m.path} (${m.tokens})`).join("\n");
 	const prefix = preview ? "PREVIEW " : "";
 	const body = `${prefix}${scheme} path="${path}"${filter}: ${matches.length} matched (${total} tokens)\n${listing}`;
-	await store.upsert(runId, turn, slug, body, 200, { loopId });
+	await store.set({
+		runId,
+		turn,
+		path: logSlug,
+		body,
+		state: "resolved",
+		loopId,
+		attributes,
+	});
 }

package/src/plugins/index.js

@@ -11,20 +11,70 @@ function getGlobalPrefix() {
 	return globalPrefix;
 }
 
-const instances = new Map();
-
 /**
- * Dynamically loads and registers plugins from provided directories
- * and RUMMY_PLUGIN_* env vars.
+ * Plugin loader:
+ *   1. Walk filesystem + env vars to collect plugin descriptors.
+ *   2. Import each and instantiate with a fresh PluginContext.
+ *
+ * Returns a Map of name → PluginContext for the caller to pass to
+ * initPlugins. No module-global state — each caller owns its set.
+ *
+ * Plugin constructors must be declarative (SPEC surfaces): they
+ * register schemes, hooks, filters, RPC methods — but don't dereference
+ * infrastructure that might not be ready yet. Because the plugin
+ * contract makes constructors side-effect-free on each other, load
+ * order doesn't matter and there is no dependency system.
  */
 export async function registerPlugins(dirs = [], hooks) {
 	const uniqueDirs = [...new Set(dirs.map((d) => join(d)))];
 
+	const descriptors = [];
 	for (const dir of uniqueDirs) {
-		await scanDir(dir, hooks, true);
+		await collectFromDir(dir, true, descriptors);
+	}
+	await collectFromEnv(descriptors);
+
+	const resolved = [];
+	for (const d of descriptors) {
+		try {
+			const module = await withTimeout(
+				import(d.url),
+				PLUGIN_LOAD_TIMEOUT,
+				`Plugin import timed out: ${d.source}`,
+			);
+			resolved.push({ ...d, Plugin: module.default });
+		} catch (err) {
+			console.warn(`[RUMMY] Plugin import failed: ${d.name} — ${err.message}`);
+		}
 	}
 
-	await loadEnvPlugins(hooks);
+	const instances = new Map();
+	for (const r of resolved) {
+		try {
+			await instantiatePlugin(r, hooks, instances);
+		} catch (err) {
+			console.warn(`[RUMMY] Plugin load failed: ${r.name} — ${err.message}`);
+		}
+	}
+	return instances;
+}
+
+async function instantiatePlugin({ name, Plugin, source }, hooks, instances) {
+	if (typeof Plugin?.register === "function") {
+		await withTimeout(
+			Plugin.register(hooks),
+			PLUGIN_LOAD_TIMEOUT,
+			`Plugin register timed out: ${source}`,
+		);
+		return;
+	}
+	if (typeof Plugin !== "function") return;
+	const ctx = new PluginContext(name, hooks);
+	new Plugin(ctx);
+	instances.set(name, ctx);
+	if (source.startsWith("env:")) {
+		console.log(`[RUMMY] Plugin ${name}: ${source.slice(4)}`);
+	}
 }
 
 const AUDIT_SCHEMES = [
@@ -32,62 +82,98 @@ const AUDIT_SCHEMES = [
 	"system",
 	"reasoning",
 	"model",
-	"error",
 	"user",
 	"assistant",
 	"content",
 ];
 
-const PROMPT_SCHEMES = ["prompt", "progress"];
+const PROMPT_SCHEMES = ["prompt"];
+
+// Lifecycle schemes: client-addressable entries that reflect server
+// state. Writable by system (internal bookkeeping), plugin (extensions),
+// and client (RPC in Phase 4).
+const LIFECYCLE_SCHEMES = ["run"];
+
+// Unified log namespace for action history entries under
+// log://turn_N/scheme/slug.
+const LOG_SCHEMES = ["log"];
 
 /**
- * After DB is ready, inject db and store into all PluginContext instances,
- * upsert declared schemes, and bootstrap audit schemes.
+ * After DB is ready, upsert declared schemes and bootstrap audit/prompt
+ * schemes. Takes the plugin collection returned by registerPlugins.
+ * Per-plugin store/db access is provided per-turn via RummyContext;
+ * PluginContext itself holds only name + hooks.
  */
-export async function initPlugins(db, store, hooks) {
+export async function initPlugins(db, hooks, instances) {
 	for (const name of AUDIT_SCHEMES) {
+		// Audit schemes are written only by system-level code (reasoning,
+		// user/assistant/model messages, etc.). Closing the door on model
+		// writes and plugin writes here.
 		await db.upsert_scheme.run({
 			name,
 			model_visible: 0,
 			category: "audit",
+			default_scope: "run",
+			writable_by: JSON.stringify(["system"]),
 		});
 	}
 	for (const name of PROMPT_SCHEMES) {
+		// Prompt entries are created by the prompt plugin on user input;
+		// model doesn't emit <set path="prompt://...">.
 		await db.upsert_scheme.run({
 			name,
 			model_visible: 1,
 			category: "prompt",
+			default_scope: "run",
+			writable_by: JSON.stringify(["plugin"]),
+		});
+	}
+	for (const name of LOG_SCHEMES) {
+		await db.upsert_scheme.run({
+			name,
+			model_visible: 1,
+			category: "logging",
+			default_scope: "run",
+			writable_by: JSON.stringify(["system", "plugin", "model"]),
+		});
+	}
+	for (const name of LIFECYCLE_SCHEMES) {
+		// Lifecycle entries are client-addressable mirrors of server state.
+		// Not model-visible. System writes internally; plugins and clients
+		// write via the 6 primitives.
+		await db.upsert_scheme.run({
+			name,
+			model_visible: 0,
+			category: "logging",
+			default_scope: "run",
+			writable_by: JSON.stringify(["system", "plugin", "client"]),
 		});
 	}
 
 	for (const ctx of instances.values()) {
-		ctx.db = db;
-		ctx.entries = store;
 		for (const scheme of ctx.schemes) {
 			await db.upsert_scheme.run(scheme);
 		}
 	}
 
 	// Register default schemes for tools that plugins ensured but didn't registerScheme for
-	if (hooks) {
-		const registered = new Set();
-		for (const ctx of instances.values()) {
-			for (const s of ctx.schemes) registered.add(s.name);
-		}
-		for (const name of AUDIT_SCHEMES) registered.add(name);
-		for (const name of PROMPT_SCHEMES) registered.add(name);
-
-		for (const toolName of hooks.tools.names) {
-			if (registered.has(toolName)) continue;
-			await db.upsert_scheme.run({
-				name: toolName,
-				model_visible: 1,
-				category: "logging",
-			});
-		}
+	const registered = new Set();
+	for (const ctx of instances.values()) {
+		for (const s of ctx.schemes) registered.add(s.name);
 	}
+	for (const name of AUDIT_SCHEMES) registered.add(name);
+	for (const name of PROMPT_SCHEMES) registered.add(name);
 
-	if (store) store.loadSchemes(db);
+	for (const toolName of hooks.tools.names) {
+		if (registered.has(toolName)) continue;
+		await db.upsert_scheme.run({
+			name: toolName,
+			model_visible: 1,
+			category: "logging",
+			default_scope: "run",
+			writable_by: JSON.stringify(["model", "plugin"]),
+		});
+	}
 }
 
 function resolvePlugin(packageName) {
@@ -99,7 +185,7 @@ function resolvePlugin(packageName) {
 	throw new Error(`Package '${packageName}' not found locally or globally`);
 }
 
-async function importPlugin(packageName) {
+async function _importPlugin(packageName) {
 	const dir = resolvePlugin(packageName);
 	const pkg = JSON.parse(
 		(await import("node:fs")).readFileSync(join(dir, "package.json"), "utf8"),
@@ -108,133 +194,70 @@ async function importPlugin(packageName) {
 	return import(pathToFileURL(join(dir, entry)).href);
 }
 
-async function loadEnvPlugins(hooks) {
+async function collectFromEnv(descriptors) {
 	for (const [key, value] of Object.entries(process.env)) {
 		if (!key.startsWith("RUMMY_PLUGIN_") || !value) continue;
 		const name = key.replace("RUMMY_PLUGIN_", "").toLowerCase();
 		try {
-			const importPromise = isAbsolute(value)
-				? importAbsolute(value)
-				: importPlugin(value);
-			const { default: Plugin } = await withTimeout(
-				importPromise,
-				PLUGIN_LOAD_TIMEOUT,
-				`Plugin import timed out: ${value}`,
-			);
-			if (typeof Plugin?.register === "function") {
-				await withTimeout(
-					Plugin.register(hooks),
-					PLUGIN_LOAD_TIMEOUT,
-					`Plugin register timed out: ${value}`,
-				);
-			} else if (typeof Plugin === "function") {
-				const ctx = new PluginContext(name, hooks);
-				new Plugin(ctx);
-				instances.set(name, ctx);
-			}
-			console.log(`[RUMMY] Plugin ${name}: ${value}`);
+			const url = isAbsolute(value)
+				? await resolveAbsoluteUrl(value)
+				: await resolvePackageUrl(value);
+			descriptors.push({ name, url, source: `env:${value}` });
 		} catch (err) {
 			console.warn(`[RUMMY] Plugin ${name} (${value}): ${err.message}`);
 		}
 	}
 }
 
-async function importAbsolute(dir) {
+async function resolvePackageUrl(packageName) {
+	const dir = resolvePlugin(packageName);
+	const pkg = JSON.parse(
+		(await import("node:fs")).readFileSync(join(dir, "package.json"), "utf8"),
+	);
+	const entry = pkg.exports?.["."] || pkg.main || "index.js";
+	return pathToFileURL(join(dir, entry)).href;
+}
+
+async function resolveAbsoluteUrl(dir) {
 	const pkgPath = join(dir, "package.json");
 	if (!existsSync(pkgPath)) {
-		// Bare .js file
-		return import(pathToFileURL(dir).href);
+		return pathToFileURL(dir).href;
 	}
 	const pkg = JSON.parse(
 		(await import("node:fs")).readFileSync(pkgPath, "utf8"),
 	);
 	const entry = pkg.exports?.["."] || pkg.main || "index.js";
-	return import(pathToFileURL(join(dir, entry)).href);
+	return pathToFileURL(join(dir, entry)).href;
 }
 
-async function scanDir(dir, hooks, isRoot = false) {
+async function collectFromDir(dir, isRoot, descriptors) {
 	if (!existsSync(dir)) return;
+	if (!(await stat(dir)).isDirectory()) return;
 
-	let dirStats;
-	try {
-		dirStats = await stat(dir);
-	} catch (_err) {
-		return;
-	}
-
-	if (!dirStats.isDirectory()) {
-		if (process.env.RUMMY_DEBUG === "true") {
-			console.error(
-				`[RUMMY] Cannot scan plugin directory (not a directory): ${dir}`,
-			);
-		}
-		return;
-	}
-
-	let entries;
-	try {
-		entries = await readdir(dir);
-	} catch (err) {
-		if (process.env.RUMMY_DEBUG === "true") {
-			console.error(`[RUMMY] Failed to read directory ${dir}:`, err.message);
-		}
-		return;
-	}
-
-	for (const name of entries) {
+	for (const name of await readdir(dir)) {
 		if (name.endsWith(".test.js")) continue;
 
 		const fullPath = join(dir, name);
-		let stats;
-		try {
-			stats = await stat(fullPath);
-		} catch (_err) {
-			continue;
-		}
+		const stats = await stat(fullPath);
 
 		if (stats.isFile() && name.endsWith(".js")) {
-			if (name === "index.js" || name === `${basename(dir)}.js`) {
-				await loadPlugin(fullPath, hooks);
-			} else if (isRoot && name !== "index.js") {
-				await loadPlugin(fullPath, hooks);
+			const isEntryFile = name === "index.js" || name === `${basename(dir)}.js`;
+			if (isEntryFile || (isRoot && name !== "index.js")) {
+				descriptors.push({
+					name: basename(fullPath, ".js"),
+					url: pathToFileURL(fullPath).href,
+					source: fullPath,
+				});
 			}
 		} else if (stats.isDirectory()) {
 			if (existsSync(join(fullPath, "DISABLED"))) continue;
-			await scanDir(fullPath, hooks, false);
+			await collectFromDir(fullPath, false, descriptors);
 		}
 	}
 }
 
 const PLUGIN_LOAD_TIMEOUT = 10000;
 
-async function loadPlugin(filePath, hooks) {
-	try {
-		const url = pathToFileURL(filePath).href;
-		const { default: Plugin } = await withTimeout(
-			import(url),
-			PLUGIN_LOAD_TIMEOUT,
-			`Plugin import timed out: ${filePath}`,
-		);
-
-		if (typeof Plugin?.register === "function") {
-			await withTimeout(
-				Plugin.register(hooks),
-				PLUGIN_LOAD_TIMEOUT,
-				`Plugin register timed out: ${filePath}`,
-			);
-		} else if (typeof Plugin === "function") {
-			const name = basename(filePath, ".js");
-			const ctx = new PluginContext(name, hooks);
-			const _instance = new Plugin(ctx);
-			instances.set(name, ctx);
-		}
-	} catch (err) {
-		console.warn(
-			`[RUMMY] Plugin load failed: ${basename(filePath)} — ${err.message}`,
-		);
-	}
-}
-
 function withTimeout(promise, ms, message) {
 	return Promise.race([
 		promise,

package/src/plugins/instructions/README.md

@@ -1,15 +1,41 @@
-# instructions
+# instructions {#instructions_plugin}
 
-Projects the system prompt instructions into model context.
+Projects the model-facing instructions into the assembled packet.
+Cleanly split into a stable system-side base and a dynamic user-side
+phase directive so prompt caching holds across turns within a run.
 
 ## Registration
 
-- **View**: `full` — renders preamble + tool docs + persona.
-- **Event**: `turn.started` — writes `instructions://system` entry.
-- **Filter**: `instructions.toolDocs` — gathers docs from all tool plugins.
+- **View**: `full` — renders the `instructions.md` base (identity +
+  `[%TOOLS%]` + `[%TOOLDOCS%]` + optional persona) for the
+  `instructions://system` entry. Stable across turns.
+- **Event**: `turn.started` — writes `instructions://system` entry
+  with `{ persona, toolSet }` attributes.
+- **Filter**: `instructions.toolDocs` — gathers docs from all tool
+  plugins into a docsMap.
+- **Filter**: `assembly.user` (priority 250) — renders the current
+  phase's `instructions_10N.md` as `<instructions>` immediately
+  before `<prompt>`. Phase selected from the latest `<update status>`
+  emission in this turn's row set.
 
-## Behavior
+## Files
 
-Replaces the `[%TOOLS%]` placeholder in the preamble with the active
-tool list. Appends tool descriptions gathered via the `toolDocs` filter
-and persona text when present in attributes.
+- `instructions.js` — plugin registration and assembly logic.
+- `instructions.md` — the system-side base template. Static across
+  turns; only identity + `[%TOOLS%]` + `[%TOOLDOCS%]` placeholders.
+- `instructions_104.md` … `instructions_108.md` — phase-specific
+  directives keyed by the 1XY status encoding (Define / Discover /
+  Distill / Demote / Deploy).
+- `protocol.js` — placeholder module reserved for deterministic
+  protocol rule enforcement. Currently pass-through.
+
+## Cache shape
+
+- System message includes the base template + tool docs + persona.
+  Identical bytes every turn within a run → cache-stable.
+- User message includes `<instructions>` at priority 250 — changes
+  as the phase advances, which is expected cache-turnover territory.
+
+If you add a per-turn-dynamic piece to `instructions.md` by mistake,
+the system prompt changes every turn and the cache prefix collapses.
+Put anything turn-specific in a phase file instead.