@possumtech/rummy 2.0.1 → 2.1.0

package/src/plugins/index.js

@@ -3,28 +3,18 @@ import { existsSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
+import config from "../agent/config.js";
 import PluginContext from "../hooks/PluginContext.js";
 
+const { PLUGINS_LOAD_TIMEOUT } = config;
+
 let globalPrefix;
 function getGlobalPrefix() {
 	globalPrefix ??= execSync("npm prefix -g", { encoding: "utf8" }).trim();
 	return globalPrefix;
 }
 
-/**
- * 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.
- */
+// Walk filesystem + env vars, import, instantiate; constructors must stay declarative.
 export async function registerPlugins(dirs = [], hooks) {
 	const uniqueDirs = [...new Set(dirs.map((d) => join(d)))];
 
@@ -39,12 +29,22 @@ export async function registerPlugins(dirs = [], hooks) {
 		try {
 			const module = await withTimeout(
 				import(d.url),
-				PLUGIN_LOAD_TIMEOUT,
+				PLUGINS_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}`);
+			// Core plugins live on disk and are part of rummy's contract;
+			// their failure is structural and must crash. Third-party
+			// plugins (RUMMY_PLUGIN_<x>) are user-installed and may be
+			// busted; we log loudly and continue without them.
+			if (d.source.startsWith("env:")) {
+				console.error(
+					`[RUMMY] Plugin import failed: ${d.name} — ${err.message}`,
+				);
+				continue;
+			}
+			throw new Error(`Core plugin '${d.name}' import failed`, { cause: err });
 		}
 	}
 
@@ -53,7 +53,11 @@ export async function registerPlugins(dirs = [], hooks) {
 		try {
 			await instantiatePlugin(r, hooks, instances);
 		} catch (err) {
-			console.warn(`[RUMMY] Plugin load failed: ${r.name} — ${err.message}`);
+			if (r.source.startsWith("env:")) {
+				console.error(`[RUMMY] Plugin load failed: ${r.name} — ${err.message}`);
+				continue;
+			}
+			throw new Error(`Core plugin '${r.name}' load failed`, { cause: err });
 		}
 	}
 	return instances;
@@ -63,7 +67,7 @@ async function instantiatePlugin({ name, Plugin, source }, hooks, instances) {
 	if (typeof Plugin?.register === "function") {
 		await withTimeout(
 			Plugin.register(hooks),
-			PLUGIN_LOAD_TIMEOUT,
+			PLUGINS_LOAD_TIMEOUT,
 			`Plugin register timed out: ${source}`,
 		);
 		return;
@@ -89,26 +93,14 @@ const AUDIT_SCHEMES = [
 
 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).
+// Lifecycle entries mirror server state; writable by system/plugin/client.
 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, 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.
- */
+// Bootstraps audit/prompt/log/lifecycle schemes; called after DB is ready.
 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,
@@ -118,8 +110,6 @@ export async function initPlugins(db, hooks, instances) {
 		});
 	}
 	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,
@@ -138,9 +128,6 @@ export async function initPlugins(db, hooks, instances) {
 		});
 	}
 	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,
@@ -156,7 +143,7 @@ export async function initPlugins(db, hooks, instances) {
 		}
 	}
 
-	// Register default schemes for tools that plugins ensured but didn't registerScheme for
+	// Default scheme for tools that ensureTool'd but didn't registerScheme.
 	const registered = new Set();
 	for (const ctx of instances.values()) {
 		for (const s of ctx.schemes) registered.add(s.name);
@@ -177,7 +164,6 @@ export async function initPlugins(db, hooks, instances) {
 }
 
 function resolvePlugin(packageName) {
-	// Check local node_modules first, then global
 	const localDir = join(process.cwd(), "node_modules", packageName);
 	if (existsSync(join(localDir, "package.json"))) return localDir;
 	const globalDir = join(getGlobalPrefix(), "lib", "node_modules", packageName);
@@ -256,8 +242,6 @@ async function collectFromDir(dir, isRoot, descriptors) {
 	}
 }
 
-const PLUGIN_LOAD_TIMEOUT = 10000;
-
 function withTimeout(promise, ms, message) {
 	return Promise.race([
 		promise,

package/src/plugins/instructions/README.md

@@ -29,6 +29,24 @@ phase directive so prompt caching holds across turns within a run.
 - `protocol.js` — placeholder module reserved for deterministic
   protocol rule enforcement. Currently pass-through.
 
+## Navigation validation
+
+`validateNavigation(status, rummy)` rejects illegal stage transitions
+emitted via `<update status="N">`:
+
+- **Forward skip** — `nextPhase > currentPhase + 1`. Models advancing
+  more than one stage at once are jumping past required work. Returns
+  and continuations (`nextPhase ≤ currentPhase`) always pass.
+- **Status 200 outside Deployment** — 200 is Deployment Completion.
+  Emitting it from earlier phases skips the actual Deployment work.
+- **Deployment with prior prompts** — entering or remaining in
+  Deployment (phase 7) requires zero visible PRIOR prompts. Covers
+  167 (entry), 177 / 200 (continuation, completion).
+
+On rejection the update entry is marked `rejected` (the phase router
+skips it) and an error log is emitted; rejections count as normal
+strikes.
+
 ## Cache shape
 
 - System message includes the base template + tool docs + persona.

package/src/plugins/instructions/instructions.js

@@ -6,12 +6,7 @@ const baseInstructions = readFileSync(
 	"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).
+// 1XY phase routing; see plugin README.
 const PHASES = [4, 5, 6, 7, 8, 9];
 const phaseInstructions = Object.fromEntries(
 	PHASES.flatMap((p) => {
@@ -28,14 +23,7 @@ function phaseForStatus(status) {
 	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.
+// Latest non-rejected update status from materialized rows.
 function latestUpdateStatusFromRows(rows) {
 	let bestTurn = -1;
 	let bestStatus = null;
@@ -49,9 +37,6 @@ function latestUpdateStatusFromRows(rows) {
 				: 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;
@@ -74,19 +59,11 @@ export default class Instructions {
 			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);
+		core.filter("assembly.user", this.assembleInstructions.bind(this), 200);
 		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.
-	 */
+	// Project instructions://system through the visible view; called once per turn.
 	async resolveSystemPrompt(rummy) {
 		const { entries: store, runId, hooks } = rummy;
 		const entries = await store.getEntriesByPattern(
@@ -111,30 +88,16 @@ export default class Instructions {
 		});
 	}
 
-	/**
-	 * 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.
-	 */
+	// Reject illegal stage navigation; see plugin README.
 	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 (status === 200 && currentPhase !== 7) {
+			return { ok: false, reason: "Illegal navigation attempt" };
+		}
 		if (nextPhase === 7) {
 			const visible = await this.#countVisiblePriorPrompts(rummy);
 			if (visible > 0) {
@@ -148,11 +111,7 @@ export default class Instructions {
 	}
 
 	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.
+		// `**` not `*`: update slugs may contain URL-encoded `/`.
 		const updates = await rummy.entries.getEntriesByPattern(
 			rummy.runId,
 			"log://*/update/**",
@@ -179,16 +138,7 @@ export default class Instructions {
 		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.
-	 */
+	// Latest phase-7 success (status=200); state-machine knowledge lives here, not AgentLoop.
 	findLatestSummary(logEntries) {
 		return logEntries
 			.filter((e) => {
@@ -210,9 +160,7 @@ export default class Instructions {
 		);
 		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.
+		// Exclude the latest prompt; only PRIOR prompts trigger demote-before-Deployment.
 		let maxNum = -1;
 		for (const p of visible) {
 			const m = /^prompt:\/\/(\d+)$/.exec(p.path);
@@ -230,10 +178,7 @@ export default class Instructions {
 		const toolSet = rummy.toolSet
 			? [...rummy.toolSet]
 			: this.#core.hooks.tools.names;
-		// 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.
+		// instructions://system stays cache-stable; phase selection at assembly.user.
 		await store.set({
 			runId,
 			turn,
@@ -242,8 +187,6 @@ export default class Instructions {
 			state: "resolved",
 			writer: "system",
 			attributes: {
-				// runRow.persona is a nullable TEXT column; absent row is
-				// a system bug — let the null propagate if runRow exists.
 				persona: runRow.persona,
 				toolSet,
 			},
@@ -259,7 +202,6 @@ export default class Instructions {
 			{},
 			{ toolSet: activeTools },
 		);
-		// Hidden tools are excluded at the registry level (see ToolRegistry).
 		const sorted = this.#core.hooks.tools.advertisedNames.filter((n) =>
 			activeTools.has(n),
 		);
@@ -275,12 +217,7 @@ export default class Instructions {
 		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.
+	// Render <instructions> for current phase; absent phase file → no block.
 	assembleInstructions(content, ctx) {
 		const status = latestUpdateStatusFromRows(ctx.rows);
 		const step = phaseInstructions[phaseForStatus(status)];

package/src/plugins/instructions/instructions.md

@@ -2,32 +2,33 @@ XML Commands Available: [%TOOLS%]
 
 # FCRM State Machine
 
-You are a Folksonomic Context Relevance Maximization (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`
+YOU MUST ONLY perform the actions corresponding with your current stage:
+* Decomposition Stage: Determine, define, and decompose key unknown and unresolved into unknown:// entries
+* Distillation Stage: discovering relevant source entries, then distilling into known:// entries to resolve unknowns
+* Demotion Stage: Demote the unknown entries, source entries, prompts, and log events after distillation is completed
+* Deployment Stage: Act on the current prompt after relevant context is distilled and irrelevant context is demoted
+* Resolution Stage: Evaluation of context relevance maximization, state machine compliance, and prompt resolution.
 
 ## 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="..."/>
+* visible: Full entry body in context, uses `tokens="N"` context budget
+* summarized: Short summary in context, very small context budget penalty
+* archived: Hidden from context, recallable later by path reference or pattern search
 
-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.
+* Leverage the FCRM's Visibility States with folksonomic taxonomies and tags to store and recall unlimited information.
+* When an entry is "visible", it will appear in both the summarized and visible sections.
+* The `tokens="N"` shows how much context is consumed if "visible". Entries consume very few tokens when summarized.
 
-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.
+YOU MUST NOT allow the `tokens="N"` sum of source entries, prompts, or log events to exceed `tokensFree` budget.
 
 # 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/>
+YOU MUST NOT use shell commands for file operations. Files are also entries that require XML Commands.
+Example: <set path="projectFile.txt">new file content</set>
+Example: <get path="src/*.txt" manifest/>
 
-Tip: Project files, entries, prompts, and log events are all accessible with the XML Commands.
+* Files, entries, prompts, and log events are all accessible with the XML Commands.
+* Entries without a `{scheme}://` are files. They can be read and modified through the unified XML Commands interface.
 
 [%TOOLDOCS%]

package/src/plugins/instructions/instructions_104.md

@@ -1,7 +1,8 @@
-# Definition Stage: YOU MUST ONLY create topical, taxonomized, and tagged unknown:// entries for missing information
+# Decomposition Stage: YOU MUST ONLY create topical, taxonomized, and tagged unknown:// entries
 
-Example: <set path="unknown://countries/france/capital" summary="countries,france,capital,geography,trivia">What is the capital of France?</set>
+YOU MUST decompose the prompt into the key information, issues, and items that are unknown and/or unresolved.
 
+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>
+## Turn Termination (CHOOSE ONLY ONE):
+* Decomposition Stage Completion: <update status="145">prompt decomposed</update>

package/src/plugins/instructions/instructions_105.md

@@ -1,30 +1,31 @@
-# Discovery Stage: YOU MUST select an unknown:// entry, then discover its source entries and distill them into known:// entries
+# Distillation 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 reference all related source entries and prompts in the `# Related` list
 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.
+* Check the `tokens="N"` of the source entries against the `tokensFree="N"` constraint before promoting entries.
+* You can use <get path="..." manifest/> to list paths and their token amounts for bulk operations without performing them.
+* You can use <get path="..." line="X" limit="Y"/> to read subsets of entries that would exceed your `tokensFree` budget.
+* Don't accidentally set the current prompt to `archived`.
 
-## Example:
-	<get path="**" preview>capital</get>
+Example:
+	<get path="**" manifest>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">
+		# Related
+		[trivia question](prompt://3)
+		[unknown resolving](unknown://countries/france/capital)
+		[source entry](trivia/capitals.csv)
+
 		# 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"/>
@@ -33,6 +34,6 @@ Tip: You can use <get path="..." line="X" limit="Y"/> to read subsets of entries
 	<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>
+* Decomposition Stage Return: <update status="154">additional unknowns identified; returning to Decomposition Stage</update>
+* Distillation Stage Continuation: <update status="155">discovering and distilling more for the selected unknown</update>
+* Distillation Stage Completion: <update status="156">this unknown's known entries written</update>

package/src/plugins/instructions/instructions_106.md

@@ -1,21 +1,22 @@
 # 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"/>
+Example:
+	<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.
+* You need room to think. Demote large prompts and source entries, then iterate them with <get path="..." line="N" limit="N"/> as necessary.
+* When demoting prompts, prefer "summarized" to "archived" to avoid losing necessary context.
 
 ## 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>
+* Decomposition Stage Return: <update status="164">additional unknowns identified; returning to Decomposition Stage</update>
+* Distillation Stage Return: <update status="165">more unknowns remain; returning to Distillation 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

@@ -1,10 +1,17 @@
-# Deployment Stage
+# Deployment Stage: YOU MUST act on the prompt.
 
-YOU MUST act on the prompt.
+YOU MUST attempt to deterministically verify your actions, outputs, or answers before declaring completion, if possible.
+
+Example: verifying deliverable before completion
+	<set path="sum.js">console.log(process.argv.slice(2).reduce((a, b) => a + Number(b), 0));</set>
+	<sh>[ -f sum.js ] && node --version && node sum.js 2 2 | grep -qx 4</sh>
+	<update status="177">sum.js written, node available, ran cleanly, correct output?</update>
+
+Example: <update status="200">Paris</update>
 
 ## 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>
+* Decomposition Stage Return: <update status="174">additional unknowns identified; returning to Decomposition Stage</update>
+* Distillation Stage Return: <update status="175">selected unknown not yet resolved; returning to Distillation Stage</update>
+* Demotion Stage Return: <update status="176">context not yet sufficiently demoted; 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>
+* Deployment Stage Completion: <update status="200">{direct answer (summary of actions performed if prompt not a question)}</update>

package/src/plugins/known/README.md

@@ -1,13 +1,17 @@
 # known {#known_plugin}
 
-Writes knowledge entries into the store at full visibility.
+Writes knowledge entries into the store at full visibility, and renders
+the project's data surface as the bifurcated `<summarized>` /
+`<visible>` blocks at the top of the user message.
 
 ## Registration
 
 - **Tool**: `known`
 - **Category**: `data`
 - **Handler**: Upserts the entry body at the target path with status 200.
-- **Filter**: `assembly.system` at priority 100 — renders `<knowns>` section.
+- **Filters**:
+  - `assembly.user` priority 50 — renders `<summarized>`.
+  - `assembly.user` priority 75 — renders `<visible>`.
 
 ## Projection
 
@@ -15,7 +19,23 @@ Shows `# known {path}` followed by the entry body.
 
 ## Assembly
 
-Filters turn_context rows where `category === "data"`. Renders all
-data entries (files, knowledge, skills, URLs) into the `<knowns>` section
-of the system message. Third-party plugins that register with
-`category: "data"` automatically appear here.
+Filters `ctx.rows` where `category === "data"`. Two separate blocks
+emit at the top of the user message in this order:
+
+- `<summarized>` — each data entry whose visibility is `visible` or
+  `summarized`, rendered under its scheme tag with the plugin's
+  summary projection as body (truncated knowns, code symbols,
+  page abstracts — whatever the plugin's `summary()` hook produces).
+  Plus the named carve-out: archived prompts pass through
+  (visibility="archived") so the model can `<get>` the active prompt
+  back after demotion.
+- `<visible>` — each data entry whose visibility is `visible`,
+  rendered with the plugin's visible projection (full body) as the
+  tag body. A visible entry appears in *both* blocks: summary
+  projection up top, full body below.
+
+This split lets `<summarized>` stay cache-stable across promote/demote
+operations — only `<visible>` mutates when the model promotes a
+summary or demotes a visible entry. Third-party plugins that register
+with `category: "data"` automatically appear in both blocks under
+their scheme tag.