castle-web-cli 0.4.124 → 0.4.126

package/dist/agent-prompts.js

@@ -20,7 +20,7 @@ const TRANSCRIPT_LIMIT = 40;
 // deck contents (ROUTER_DECK_CONTENTS_BUDGET, 40KB), the task board, and this
 // turn's instruction.
 const TRANSCRIPT_BYTE_BUDGET = 32 * 1024;
-const ROUTER_RULES = `You are Castle's create assistant: the fast conversational router for a game-making session. The deck (game project) lives in the current directory and runs live in a pane right next to this chat.
+const BASE_ROUTER_RULES = `You are Castle's create assistant: the fast conversational router for a game-making session. The deck (game project) lives in the current directory and runs live in a pane right next to this chat.
 
 What a deck is: a normal web project served by vite -- index.html plus plain JS/JSX modules, with real npm dependencies (more can be installed), the castle-web-sdk package, and usually a kit framework whose engine, behaviors, scenes, editors, and drawings are ordinary files in this directory. The web platform is fully available (DOM, canvas, npm libraries like react, three, etc.). The deck's Quick reference and file list below describe its setup; the full CLAUDE.md / AGENTS.md has deeper detail. NEVER claim something is impossible or unsupported on the platform without checking that context (or, for specifics it doesn't cover, the deck's files) first.
 
@@ -82,6 +82,64 @@ Conversation style:
 - The user sees a live task board above the chat -- never re-announce task status yourself.
 - Spawning a task does NOT apply the change -- tasks run for minutes and finish on the board. Talk about spawned work in future tense ("this will dial the shake back"), and NEVER ask how a change feels right after spawning it -- the user cannot have tried it yet. Save "how is it?" for things whose task already finished.
 - The user playtests in the pane beside this chat; finished work shows up there after a reload.`;
+// Appended to the rules above for a deck with the plan doc on -- see
+// planSession in agent.ts for which decks those are. One self-contained block,
+// so a deck without it gets the pre-plan prompt byte for byte.
+//
+// Every rule here answers to a section of the plan format spec; two of them
+// deliberately supersede rules in the block above (pairing a question with
+// task directives, and holding follow-up questions back), which is why they say
+// so out loud rather than quietly contradicting them.
+const PLAN_RULES = `Reading the user, fresh from EACH message -- the same user hands you a spec, then a fragment, then delegates:
+- CLEAR SPEC (mechanics named, a reference given, "like X but Y"): the gaps are closed. Build what they said; never probe taste they already expressed.
+- FRAGMENT ("something with ants", "a cozy game about tea?"): gaps they cannot name yet. Draw their taste out on the few dimensions that decide whether this feels like THEIRS -- while building, never instead of building.
+- A fragment is not only a whole-game ask. "how about some obstacles?", "make it feel brighter" name a slice and leave its taste open: build the part they named, and probe the ONE dimension you were about to settle for them. Deciding it silently is how a deck becomes yours instead of theirs.
+- DELEGATION ("surprise me", "you decide"): the open calls are yours. Decide; probe nothing.
+- Praise, a question, plain conversation: answer it and do NOTHING else -- no tasks, no probe, no chips, no plan fence. Never manufacture work to seem engaged.
+
+Probing while you build. A probe is one short plain question plus 2-4 tappable options, written inline as [[double brackets]]:
+
+  The ants are going up on screen now -- while that builds: what are YOU in this world?
+  [[Guide them with trails]] [[Command each ant]] [[Just watch them live]]
+
+- Tapping one sends its text as the user's next message; they can ignore it and type anything else, and the build continues either way. Never phrase a probe as if an answer were required.
+- Spawn the work the answer cannot invalidate AND attach the probe in the same reply -- this supersedes the rules above against pairing a question with task directives. But NEVER spawn work a pending probe could invalidate: there is no telling a running task anything.
+- At most ONE probe open at a time; none on spec, delegation, or conversation turns; never re-probe something answered. Probe feel and identity -- what the player DOES, how it should feel, the goal shape, the tone -- never implementation.
+- Chips NEVER stand on their own: a probe's question is the line right before them, and a probe is the only thing they are for. Alone they read as answers to a question nobody asked.
+- Praise is where the pull to offer something is strongest and most wrong: "oh nice, that works great" gets one plain sentence and nothing else. Vary it -- a compliment that always gets the same reply stops reading as one.
+
+The plan (plan.md). The deck's plan is a real file at the deck root, yours to keep and the user's to edit, where you decide in the open: it outlives this conversation, which gets trimmed with age, and task agents are given the parts that constrain them. It is rendered above. You never edit files, so you change it by emitting OPERATIONS, one per line, in a fence:
+
+\`\`\`castle-plan
+identity: Calm and mesmerizing -- their word was "hypnotic".
+decide+ no-losing: nothing kills an ant ("losing ants feels bad" -- user)
+open+ goal-shape: whether there is a goal at all
+tried+ predators: they made the colony tense ("nobody wanted to watch" -- task a1b2c3)
+now+ ant-trails: draw a path the ants follow
+now- food-hauling
+\`\`\`
+
+- \`decide+\` / \`open+\` / \`tried+\` / \`now+\` add one line to \`## Decisions\` / \`## Open questions\` / \`## Tried\` / \`## Now\`; the \`-\` op, carrying just the label, removes it. Nothing else in the file changes -- including what the user has been writing in it.
+- Lines read \`<label>: <text>\`. Labels are short, kebab-case, and STABLE: never renamed, reused when work picks back up on the same thing. \`+\` on a label already there REPLACES its line -- the update path, and the correction path.
+- \`decide+\` and \`tried+\` MUST QUOTE their source: \`("<their own words>" -- user)\` for something the user actually said, \`("<its own words>" -- task <id>)\` for a note a finished task left. The quote is checked against the real text, so copy it -- a few words, one unbroken run, no \`...\`. One whose quote is missing or is not in its source -- anything you are inferring -- is filed as a proposal under \`## Open questions\` instead, which is what it is. Quoted taste only; ASK for the rest.
+- The line lands with its quote attached: \`decide+ no-losing: nothing kills an ant ("losing ants feels bad" -- user)\` writes \`- no-losing: nothing kills an ant ("losing ants feels bad" -- user)\`. Write the line in THEIR words -- if it says more than the quote does, quote more or say less. When the quote carries the whole thing, leave your sentence out (\`decide+ no-losing: ("losing ants feels bad" -- user)\`) -- but a quote that only approves ("sounds good", "as possible") carries nothing, so there the line must say the thing it approved.
+- \`identity:\` lines replace \`## What this game is\` outright: send all of them (at most 6) in the one fence.
+- \`## Now\` is the work in flight, and its labels join the plan to the tasks: every \`\`\`castle-task fence carries \`item: <label>\` -- one already in \`## Now\`, or one this reply's fence adds. A chore belonging to no item says \`item: -\`.
+- Finishing an item is \`now- <label>\`; whatever should outlive it goes to Decisions / Tried in the SAME fence, and the rest is meant to be forgotten. An item that leaves \`## Now\` with nothing promoted takes everything the two of you settled while building it with it. You never write what EXISTS: \`## Built\` is derived from the tasks for you, and board rows are not plan lines.
+- Ops are for inflection points -- a decision crystallizes, an experiment concludes, the user reflects, an item starts or finishes. A turn that changed nothing about the plan carries no fence at all.
+- THE USER SHAPING THE GAME IS AN INFLECTION POINT. A mechanic, a rule, an entity, a mood, a difficulty they ask for is taste, not a chore: it goes in with \`decide+\` quoting the words they used, in the same reply that spawns the work. Early on nearly every ask is one of these, and a plan that holds only what is in flight has kept nothing.
+- A bare number, a knob setting, or a bug they want gone is not taste -- just do the tweak. The REASON they give for one is: "make the islands bigger, it's already pretty hard" is a \`decide+\` about the difficulty they want, not about island size.
+- Put the fence AFTER your task fences: tasks spawn the moment their fence closes, so one in front just delays the user's first build.
+- NOTHING in \`## Open questions\` may be answered by anything else in the same reply, fence or task: asking and deciding are different acts. A probe IS the top open question, asked in its own words.
+- An ask that goes against a \`## Decisions\` line: say what was decided and why in one sentence BEFORE you build it. They may well have changed their mind -- that is theirs to say, and the line is yours to raise.
+- No plan.md yet and the deck is getting work? Open one here with the ops the moment supports: an \`identity:\` line, the \`## Now\` items you are spawning, an \`open+\` for what you are guessing at. SPARSE AND TRUE, and never in place of their actual ask.
+
+Promotion. Finished tasks leave notes worth keeping, listed above with the id of the task that left each. Promote the keepers by quoting the note itself and citing its task; let the rest go -- they are offered once.
+
+If the user asks you to ease off the questions or the plan upkeep, record that with a \`decide+\` quoting the ask, and honor it -- keep \`## Now\` current, quietly.`;
+function routerRules(plan) {
+    return plan ? `${BASE_ROUTER_RULES}\n\n${PLAN_RULES}` : BASE_ROUTER_RULES;
+}
 function renderTranscriptLine(m) {
     if (m.role === "user")
         return `user: ${m.text}`;
@@ -92,7 +150,7 @@ function renderTranscriptLine(m) {
 }
 // Cut a line to fit `budget` BYTES without splitting a multi-byte character
 // (a half-written character would render as a replacement glyph mid-sentence).
-function truncateToBytes(line, budget) {
+export function truncateToBytes(line, budget) {
     const buf = Buffer.from(line, "utf8");
     if (buf.byteLength <= budget)
         return line;
@@ -132,17 +190,602 @@ function renderTranscript(messages) {
     const plural = elided === 1 ? "message" : "messages";
     return `(${elided} earlier ${plural} trimmed to keep this prompt within its size limit)\n\n${kept.join("\n\n")}`;
 }
-function renderTasks(tasks) {
+// Per-section line caps from the plan format. Nothing enforces them on the
+// file -- ops touch one line each and the user writes what they like -- so one
+// runaway section is trimmed here instead, and can never crowd the rest of the
+// plan out of the digest. Key is the lowercased heading; "" is the title +
+// pitch ahead of the first heading, which only the user writes.
+const PLAN_SECTION_CAPS = {
+    "": 2,
+    "what this game is": 6,
+    decisions: 12,
+    "open questions": 7,
+    now: 10,
+    tried: 8,
+};
+const PLAN_SECTION_DEFAULT_CAP = 8;
+const PLAN_DIGEST_BYTE_BUDGET = 3 * 1024;
+const BUILT_MAX_LINES = 15;
+// plan.md's sections in the order they are written and rendered, with the
+// heading each is created as. `built` is listed for its POSITION only: it is
+// derived into the digest from finished tasks (see deriveBuiltLines) and is
+// never a section of the file.
+const PLAN_SECTION_HEADINGS = {
+    "": "",
+    "what this game is": "## What this game is",
+    decisions: "## Decisions",
+    "open questions": "## Open questions",
+    now: "## Now",
+    built: "## Built",
+    tried: "## Tried",
+};
+const PLAN_SECTION_ORDER = Object.keys(PLAN_SECTION_HEADINGS);
+// A section the plan format doesn't name (the user is free to add one) sorts
+// last rather than jumping the order.
+function sectionRank(key) {
+    const at = PLAN_SECTION_ORDER.indexOf(key);
+    return at < 0 ? PLAN_SECTION_ORDER.length : at;
+}
+// The sections a task agent is given. `## Open questions` is withheld on
+// purpose: a task must never resolve taste, and not showing it the menu is
+// cheaper than policing it. `## Now` is withheld too except for the one line
+// naming this task's own item -- the rest is other agents' work.
+const TASK_PLAN_SECTIONS = new Set(["what this game is", "decisions", "tried"]);
+function parsePlanSections(fileText) {
+    const sections = [{ heading: "", key: "", lines: [] }];
+    for (const raw of fileText.split("\n")) {
+        const heading = /^##\s+(.*)$/.exec(raw.trim());
+        if (heading) {
+            sections.push({
+                heading: raw.trim(),
+                key: heading[1].trim().toLowerCase(),
+                lines: [],
+            });
+        }
+        else {
+            sections[sections.length - 1].lines.push(raw);
+        }
+    }
+    return sections;
+}
+const OP_SECTION = {
+    decide: "decisions",
+    open: "open questions",
+    tried: "tried",
+    now: "now",
+    identity: "what this game is",
+};
+const OP_LINE = /^(decide|open|tried|now)\s*([+-])\s*(.*)$/i;
+const IDENTITY_LINE = /^identity\s*:\s*(.*)$/i;
+const LABELED_TEXT = /^([^\s:]+)\s*:\s*(.+)$/;
+// The trailing annotation, and what it says inside. Kept separate so an op's
+// own parenthetical -- `the hop is floaty (never bouncy)` -- is left alone:
+// only a parenthetical that says `from:` or names a source is an annotation.
+// Dash and quote glyphs vary with whatever produced the line, so both are.
+const SOURCE_SUFFIX = /\s*\((from:)?\s*([^()]*?)\s*\)\s*$/i;
+// The same annotation with the brackets left off, which the model does now and
+// then (measured 26-08-15: 1 of 10 taste ops in a t1 run, quote and task id
+// both exact). A quote is REQUIRED in this form -- a bare `-- user` at the end
+// of a line is something ordinary prose could land on by accident, where a
+// quoted fragment followed by a source is not.
+// The delimiters are matched by KIND rather than as one class of glyph: a
+// quote delimited by double quotes may contain an apostrophe, and "it's
+// already pretty hard" is exactly the kind of thing a person says. Measured
+// 26-08-18: a class that excluded every quote glyph anywhere inside dropped
+// three verifiable quotes of one message for that apostrophe alone.
+const QUOTED_RUN = `(?:["“”][^"“”]+["“”]|['‘’][^'‘’]+['‘’])`;
+const BARE_SOURCE = new RegExp(`\\s*[;,]?\\s*(${QUOTED_RUN}\\s*(?:--+|[–—])\\s*(?:user|task\\s+\\S+))\\s*$`, 'i');
+const SOURCE_BODY = /^(?:["'‘’“”](.+)["'‘’“”]\s*(?:--+|[–—,-]|from:)\s*)?(?:(user)|task\s+(\S+))$/i;
+// A trailing quote with no attributor at all -- `bigger islands -- "it's
+// already pretty hard"`. Measured 26-08-18: the router wrote this shape 3 of 3
+// times on one case, throwing away a quote that was verbatim and verifiable,
+// for want of the word "user". Read as a user quote, which is the only claim it
+// can make good on: nothing lands unless the words are really in something the
+// user said, so an unattributed quote of a TASK note still routes to
+// `## Open questions` exactly as it does today.
+const UNATTRIBUTED_QUOTE = new RegExp(`\\s*[;,]?\\s*(?:--+|[–—])\\s*(${QUOTED_RUN})\\s*$`);
+// The quote left OUTSIDE the annotation -- `bigger islands -- "it's already
+// pretty hard" (user)`. The attributor is explicit here, so a quoted run at the
+// end of what remains is the quote it is pointing at, and reading it that way
+// costs nothing: the words still have to be in something the user said.
+// Measured 26-08-18: this shape, not the missing attributor, is what threw away
+// all three of one case's captures.
+const TRAILING_QUOTE = new RegExp(`\\s*(?:[;,]\\s*)?(?:(?:--+|[–—])\\s*)?(${QUOTED_RUN})\\s*$`);
+// Split a trailing `("<quote>" -- user)` / `("<quote>" -- task <id>)` off an
+// op's text. A source the grammar does not recognize is dropped rather than
+// kept as prose: the claim survives, its provenance does not, and the op is
+// treated as unsourced. So is a quoteless one -- a citation nobody can check is
+// the thing this grammar exists to stop being enough.
+function takeSource(text) {
+    const match = SOURCE_SUFFIX.exec(text);
+    const bare = match ? null : BARE_SOURCE.exec(text);
+    const annotation = match ?? bare;
+    if (!annotation) {
+        const loose = UNATTRIBUTED_QUOTE.exec(text);
+        if (!loose)
+            return { text };
+        return {
+            text: text.slice(0, loose.index).trim(),
+            source: { kind: "user", quote: loose[1].slice(1, -1).trim() },
+        };
+    }
+    const body = SOURCE_BODY.exec(match ? match[2] : annotation[1]);
+    if (!body && !match?.[1])
+        return { text };
+    const stripped = text.slice(0, annotation.index).trim();
+    let quote = body?.[1]?.trim() || undefined;
+    if (!body)
+        return { text: stripped };
+    let rest = stripped;
+    if (!quote) {
+        const trailing = TRAILING_QUOTE.exec(stripped);
+        if (trailing) {
+            quote = trailing[1].slice(1, -1).trim();
+            rest = stripped.slice(0, trailing.index).trim();
+        }
+    }
+    if (body[2])
+        return { text: rest, source: { kind: "user", quote } };
+    return { text: rest, source: { kind: "task", id: body[3], quote } };
+}
+const QUOTE_GLYPHS = /["'‘’‚‛′“”„‟″]/g;
+const DASH_GLYPHS = /[‐-―−]/g;
+const EDGE_PUNCT = /^['.,;:!?()[\]{}\s-]+|['.,;:!?()[\]{}\s-]+$/g;
+function normalizeQuote(text) {
+    return text
+        .replace(QUOTE_GLYPHS, "'")
+        .replace(DASH_GLYPHS, "-")
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .replace(EDGE_PUNCT, "");
+}
+// Does `fragment` appear verbatim in `sourceText`? Verbatim in substance rather
+// than in bytes: a model copying a phrase out of a chat message reliably
+// straightens the quotes and dashes a phone keyboard produced and re-wraps the
+// whitespace, and failing a citation over a smart apostrophe would teach the
+// router to stop quoting. The words and their order have to match exactly.
+//
+// Exported so the eval harness checks a fence with the byte-identical function
+// the runtime applies it with.
+export function quoteMatches(fragment, sourceText) {
+    const needle = normalizeQuote(fragment);
+    return needle !== "" && normalizeQuote(sourceText).includes(needle);
+}
+export function parsePlanOps(body) {
+    const ops = [];
+    const unparsed = [];
+    for (const raw of body.split("\n")) {
+        // A leading bullet is tolerated: plan.md's own lines are bullets, so the
+        // model reaches for one out of habit, and refusing a line whose intent is
+        // unambiguous would cost real plan updates for nothing.
+        const line = raw.trim().replace(/^[-*]\s+/, "");
+        if (!line)
+            continue;
+        const identity = IDENTITY_LINE.exec(line);
+        if (identity?.[1].trim()) {
+            ops.push({ verb: "identity", remove: false, label: "", text: identity[1].trim() });
+            continue;
+        }
+        const op = OP_LINE.exec(line);
+        const verb = op?.[1].toLowerCase();
+        const rest = op?.[3].trim() ?? "";
+        if (!verb || !rest) {
+            unparsed.push(line);
+            continue;
+        }
+        if (op?.[2] === "-") {
+            ops.push({ verb, remove: true, label: rest.split(/[\s:]/)[0], text: "" });
+            continue;
+        }
+        const labeled = LABELED_TEXT.exec(rest);
+        const { text, source } = takeSource(labeled?.[2].trim() ?? "");
+        // A taste op may be nothing but its quote. Since the landed line IS the
+        // quote, the router's own sentence is vestigial, and it writes `decide+
+        // six-five: "6 letters, 5 guesses" -- user` accordingly -- 12 of 80 op
+        // lines in the first run of that rule, every one of them well-formed in
+        // intent. The grammar admits the shape its own rule invites.
+        if (!labeled || (!text && !source?.quote)) {
+            unparsed.push(line);
+            continue;
+        }
+        ops.push({ verb, remove: false, label: labeled[1], text, source });
+    }
+    return { ops, unparsed };
+}
+function insertByOrder(sections, section) {
+    const rank = sectionRank(section.key);
+    const at = sections.findIndex((s) => sectionRank(s.key) > rank);
+    if (at < 0)
+        sections.push(section);
+    else
+        sections.splice(at, 0, section);
+}
+function sectionFor(sections, key) {
+    const existing = sections.find((s) => s.key === key);
+    if (existing)
+        return existing;
+    const created = {
+        heading: PLAN_SECTION_HEADINGS[key] ?? `## ${key}`,
+        key,
+        lines: [],
+    };
+    insertByOrder(sections, created);
+    return created;
+}
+function labelAt(section, label) {
+    if (!section)
+        return -1;
+    const want = label.toLowerCase();
+    return section.lines.findIndex((l) => planItemLabel(l)?.toLowerCase() === want);
+}
+// Sourced means: the quote is really a fragment of what the user said, or of
+// what the cited task handed in. Naming a real source is not enough -- a
+// citation can point at something that exists and still attach a claim that
+// source never made, which is the whole of what the quote is checked for. A
+// cited id that names no task has no material at all, so it cannot verify.
+function isSourced(op, sources) {
+    const quote = op.source?.quote;
+    if (!op.source || !quote)
+        return false;
+    if (op.source.kind === "user") {
+        return (sources?.userMessages ?? []).some((m) => quoteMatches(quote, m));
+    }
+    const reported = sources?.taskReports?.get(op.source.id ?? "");
+    return Boolean(reported) && quoteMatches(quote, reported ?? "");
+}
+// The quote rides into the file with the line it backs: a decision the user
+// reads should show the words it came from, and the next turn's digest carries
+// them back to the router as the standard its own lines are held to.
+// The line is the router's sentence, quote appended -- the quote-only form
+// (26-08-18, one night) lost the content whenever the quoted words were
+// ratification rather than substance (`- fewest-strokes: "as possible" --
+// user`, from a live sitting), which is what the 1b" ruling that killed
+// quote-only ops predicted. The ~1-in-3 of sentences a strict judge grades as
+// saying more than their quote is ACCEPTED: Eric read the flagged examples
+// (26-08-18) and called them "close enough to the written intent" -- an
+// entailment judge built to police them was torn back out the same day as not
+// worth a model call. The periodic fidelity monitor remains the drift
+// tripwire. An op whose text is empty still lands as its quote alone -- there
+// the quote IS the whole content.
+function sourceLine(label, source, text) {
+    const who = source.kind === "user" ? "user" : `task ${source.id}`;
+    if (!text.trim())
+        return `- ${label}: "${source.quote}" -- ${who}`;
+    return `- ${label}: ${text} ("${source.quote}" -- ${who})`;
+}
+function isTasteAdd(op) {
+    return !op.remove && (op.verb === "decide" || op.verb === "tried");
+}
+function applyOne(sections, op, notices, sources) {
+    // The one transform in the whole write path: taste the router cannot source
+    // becomes a question instead of a decision. It is asked rather than dropped
+    // -- the observation may well be right, it just isn't the router's to settle.
+    const taste = isTasteAdd(op);
+    const routed = taste && !isSourced(op, sources);
+    const key = routed ? "open questions" : OP_SECTION[op.verb];
+    if (op.remove) {
+        const section = sections.find((s) => s.key === key);
+        const at = labelAt(section, op.label);
+        if (!section || at < 0) {
+            notices.push(`\`${op.verb}- ${op.label}\` matched no line in ${PLAN_SECTION_HEADINGS[key]}`);
+            return false;
+        }
+        section.lines.splice(at, 1);
+        return true;
+    }
+    const line = taste && !routed && op.source
+        ? sourceLine(op.label, op.source, op.text)
+        : `- ${op.label}: ${op.text}${routed ? " (proposed -- confirm?)" : ""}`;
+    const section = sectionFor(sections, key);
+    const at = labelAt(section, op.label);
+    if (at >= 0) {
+        if (section.lines[at].trim() === line)
+            return false;
+        section.lines[at] = line;
+    }
+    else {
+        let end = section.lines.length;
+        while (end > 0 && !section.lines[end - 1].trim())
+            end -= 1;
+        section.lines.splice(end, 0, line);
+    }
+    if (routed) {
+        const why = op.source?.quote
+            ? `quoted words that are not in ${op.source.kind === "user" ? "anything the user said" : `anything task ${op.source.id} reported`}`
+            : "carried no quote of its source";
+        notices.push(`\`${op.verb}+ ${op.label}\` ${why}, so it is an open question now, not a decision -- promote it with a verbatim quote once you can point at one.`);
+    }
+    return true;
+}
+// Re-emit the file from its sections: headings in order, one blank line before
+// each, no trailing whitespace. Only lines an op touched differ from what came
+// in -- everything else, including whatever the user wrote, comes back through.
+function renderPlanFile(sections) {
+    const out = [];
+    for (const section of sections) {
+        const lines = [...section.lines];
+        while (lines.length > 0 && !lines[lines.length - 1].trim())
+            lines.pop();
+        if (section.heading) {
+            if (out.length > 0)
+                out.push("");
+            out.push(section.heading);
+        }
+        out.push(...lines);
+    }
+    return out.join("\n").trim();
+}
+// Apply `ops` to a plan file's text. `sources` is the material a taste op's
+// quote is checked against; an op whose quote is not in it is routed to
+// `## Open questions` as a proposal, the same as one that cited nothing.
+export function applyPlanOps(fileText, ops, sources) {
+    const sections = parsePlanSections(fileText);
+    const notices = [];
+    const identity = [];
+    const closed = [];
+    let applied = 0;
+    for (const op of ops) {
+        if (op.verb === "identity")
+            identity.push(`- ${op.text}`);
+        else if (applyOne(sections, op, notices, sources)) {
+            applied += 1;
+            if (op.verb === "now" && op.remove)
+                closed.push(op.label);
+        }
+    }
+    // Closing an item is the moment its taste stops being visible anywhere: the
+    // board rows go, the transcript ages out, and none of it is in the file. The
+    // rule to promote first is a rule the router routinely skips, and the runtime
+    // cannot write the promotion itself -- plan.md has two writers and neither is
+    // this code -- so it says on the next turn what it can see went missing.
+    if (closed.length > 0 && !ops.some((op) => isTasteAdd(op) && isSourced(op, sources))) {
+        for (const label of closed) {
+            notices.push(`\`now- ${label}\` closed the item with nothing promoted -- if anything you settled while building it should outlive it, add it now with a \`decide+\` or \`tried+\` quoting where it came from.`);
+        }
+    }
+    // Identity is the one section written whole rather than by line: it is six
+    // lines of the deck's own voice, and rewriting it a line at a time would
+    // leave halves of two different readings standing.
+    if (identity.length > 0) {
+        const section = sectionFor(sections, OP_SECTION.identity);
+        if (section.lines.map((l) => l.trim()).filter(Boolean).join("\n") !== identity.join("\n")) {
+            section.lines = identity;
+            applied += 1;
+        }
+    }
+    return { text: renderPlanFile(sections), applied, notices };
+}
+// Blank lines are dropped rather than reproduced: the digest is read, not
+// edited, and the file's spacing is pure byte cost here.
+function trimSection(section) {
+    const cap = PLAN_SECTION_CAPS[section.key] ?? PLAN_SECTION_DEFAULT_CAP;
+    const kept = [];
+    let trimmed = false;
+    for (const line of section.lines) {
+        if (!line.trim())
+            continue;
+        if (kept.length >= cap) {
+            trimmed = true;
+            break;
+        }
+        kept.push(line.trim());
+    }
+    return { lines: kept, trimmed };
+}
+function planItemLabel(line) {
+    return /^[-*]\s*([^\s:]+)\s*:/.exec(line)?.[1];
+}
+// The machine half of the digest: which board rows belong to this plan item.
+// It is joined in here, never written into plan.md -- the file stays prose with
+// two human writers, and everything the runtime knows rides in the render.
+function overlayItemTasks(line, tasks) {
+    const label = planItemLabel(line);
+    if (!label)
+        return line;
+    const rows = tasks.filter((t) => t.item === label);
+    if (rows.length === 0)
+        return line;
+    return `${line}  [${rows.map((t) => `${t.status}: ${t.title}`).join("; ")}]`;
+}
+// Which section gives up a line next when the digest is over budget: the
+// longest, so no section is starved by a neighbour's length. Nothing is trimmed
+// below its last line -- a plan at every cap otherwise loses whole sections off
+// the end.
+//
+// `## Built` yields only once nothing else can, because a PARTIAL list of what
+// exists reads as the whole list: measured 26-08-15, a mature deck whose Built
+// was trimmed to five lines had its router re-spawn work that already existed
+// on 3 of 15 covered-work samples, and on the same fixtures with Built whole,
+// none -- some of those turns telling the user the thing was already there
+// instead of building it again. The exemption is free: the digest lands on the
+// same bytes either way, the taste sections just yield them.
+function trimVictim(sections) {
+    const longestOf = (eligible) => {
+        let longest;
+        for (const section of sections) {
+            if (section.lines.length <= 1 || !eligible(section))
+                continue;
+            if (!longest || section.lines.length > longest.lines.length)
+                longest = section;
+        }
+        return longest;
+    };
+    // Decisions is spared until everything else is down to a line, for the same
+    // reason Built is spared entirely: a decision the router cannot see is a
+    // decision it builds against (4.4's beat 5; the wall's P1 3/3). The capture
+    // rules (26-08-18) make Decisions the fastest-growing section, which under
+    // longest-first trimming made it the STANDING victim -- the instrument
+    // caught the fourth Decisions line failing to survive the digest at caps
+    // before any real deck did.
+    return (longestOf((s) => s.key !== "built" && s.key !== "decisions") ??
+        longestOf((s) => s.key !== "built") ??
+        longestOf(() => true));
+}
+function builtLine(work) {
+    const files = work.files?.length ? ` (files: ${work.files.join(", ")})` : "";
+    const knobs = work.knobs?.length ? ` (knobs: ${work.knobs.join(", ")})` : "";
+    return `- ${work.item}: ${work.what}${files}${knobs}`;
+}
+// `## Built`, derived: one line per plan item finished work reported on, newest
+// first. Latest-wins per item rather than a log -- the section answers "what
+// exists now", and a per-task history would grow with every task the deck ever
+// ran. What is evicted is still on disk in the task handoffs.
+function deriveBuiltLines(finished) {
+    const latest = new Map();
+    for (const work of finished) {
+        if (!work.item.trim() || work.item === "-" || !work.what.trim())
+            continue;
+        const prev = latest.get(work.item);
+        if (!prev || (work.at ?? "") >= (prev.at ?? ""))
+            latest.set(work.item, work);
+    }
+    const newestFirst = [...latest.values()].sort((a, b) => (b.at ?? "").localeCompare(a.at ?? ""));
+    const lines = newestFirst.slice(0, BUILT_MAX_LINES).map(builtLine);
+    const dropped = newestFirst.length - lines.length;
+    if (dropped > 0)
+        lines.push(`(${dropped} more in the archive)`);
+    return lines;
+}
+function fitPlanSections(plan, tasks) {
+    const sections = [];
+    for (const section of parsePlanSections(plan.fileText ?? "")) {
+        const { lines, trimmed } = trimSection(section);
+        if (lines.length === 0 && !section.heading)
+            continue;
+        sections.push({
+            heading: section.heading,
+            key: section.key,
+            lines: section.key === "now"
+                ? lines.map((l) => overlayItemTasks(l, tasks))
+                : lines,
+            trimmed,
+        });
+    }
+    const built = deriveBuiltLines(plan.finishedWork ?? []);
+    if (built.length > 0) {
+        insertByOrder(sections, {
+            heading: "## Built",
+            key: "built",
+            lines: built,
+            trimmed: false,
+        });
+    }
+    const render = () => sections
+        .map((s) => [s.heading, ...s.lines, s.trimmed ? "(trimmed)" : ""]
+        .filter(Boolean)
+        .join("\n"))
+        .join("\n\n");
+    while (Buffer.byteLength(render(), "utf8") > PLAN_DIGEST_BYTE_BUDGET) {
+        const victim = trimVictim(sections);
+        if (!victim)
+            break;
+        victim.lines.pop();
+        victim.trimmed = true;
+    }
+    // Backstop for a plan whose remaining one-line-per-section still overruns
+    // (pathological line lengths); the 8KB file cap upstream keeps it rare.
+    const rendered = render();
+    if (Buffer.byteLength(rendered, "utf8") <= PLAN_DIGEST_BYTE_BUDGET) {
+        return rendered;
+    }
+    return `${truncateToBytes(rendered, PLAN_DIGEST_BYTE_BUDGET).trimEnd()}\n(trimmed)`;
+}
+// The plan as the router sees it: the file (capped, with board status joined
+// onto its items and `## Built` derived in) plus the nominations waiting on its
+// next fence.
+//
+// The nominations are appended AFTER the file's byte budget rather than inside
+// it. They are small and bounded, and they are the input to promotion -- a
+// long plan crowding them out would silently stop promotion working at exactly
+// the point a deck most needs it.
+export function renderPlanDigest(plan, tasks) {
+    const fitted = fitPlanSections(plan, tasks);
+    // A deck can have finished work before it has a plan.md -- what exists is
+    // still worth showing, and saying the file is missing is what gets one
+    // drafted.
+    const parts = [
+        plan.fileText?.trim()
+            ? fitted
+            : ["(no plan.md yet)", fitted].filter(Boolean).join("\n\n"),
+    ];
+    const nominations = plan.pendingDurables ?? [];
+    if (nominations.length > 0) {
+        parts.push(`Notes from finished work, not in the plan yet -- promote the keepers with a \`decide+\` / \`tried+\` quoting the note and citing its task, let the rest go:\n${nominations
+            .map((n) => `- task ${n.taskId} (${n.taskTitle}): ${n.text}`)
+            .join("\n")}`);
+    }
+    const notices = plan.notices ?? [];
+    if (notices.length > 0) {
+        parts.push(`Plan upkeep from the runtime -- act on each this turn:\n${notices
+            .map((n) => `- ${n}`)
+            .join("\n")}`);
+    }
+    return parts.join("\n\n");
+}
+// The non-empty lines of `## Open questions`, for the runtime's agenda nudge
+// (agent.ts): a standing question the router keeps not asking gets named in a
+// notice, since five wordings of a prompt rule for the same behavior all
+// measured 0 (26-08-18) while the notice-shaped close rule measured real.
+export function planOpenQuestionLines(fileText) {
+    const section = parsePlanSections(fileText).find((s) => s.key === "open questions");
+    return (section?.lines ?? []).map((l) => l.trim()).filter(Boolean);
+}
+// The slice one task agent gets: the constraints and the don't-rebuilds, plus
+// the single item line its own work belongs to. See TASK_PLAN_SECTIONS for what
+// is deliberately left out.
+export function renderTaskPlanSlice(fileText, item, finishedWork) {
+    const sections = parsePlanSections(fileText);
+    const parts = [];
+    // Only this item's own Built line: what already exists where this task is
+    // about to work, so it extends rather than rebuilds. Other items' work is
+    // not its business.
+    const built = deriveBuiltLines((finishedWork ?? []).filter((w) => item && w.item === item));
+    let builtDone = built.length === 0;
+    const pushBuilt = () => {
+        if (builtDone)
+            return;
+        parts.push(["## Built", ...built].join("\n"));
+        builtDone = true;
+    };
+    for (const section of sections) {
+        if (section.key !== "" && !TASK_PLAN_SECTIONS.has(section.key))
+            continue;
+        const { lines } = trimSection(section);
+        if (lines.length === 0)
+            continue;
+        if (sectionRank(section.key) > sectionRank("built"))
+            pushBuilt();
+        parts.push([section.heading, ...lines].filter(Boolean).join("\n"));
+    }
+    pushBuilt();
+    const itemLine = item
+        ? sections
+            .find((s) => s.key === "now")
+            ?.lines.map((l) => l.trim())
+            .find((l) => planItemLabel(l) === item)
+        : undefined;
+    if (itemLine)
+        parts.push(`The plan item your task belongs to:\n${itemLine}`);
+    return parts.join("\n\n");
+}
+// `showItems` is the plan opt's presence, not the row's. A deck that ran with
+// the plan doc on and then switched it off still has item labels on its old
+// task records, and rendering them would put plan vocabulary in the prompt of a
+// deck that opted out -- which is both meaningless there (nothing tells that
+// router what an item is) and a break in the byte-identity the opt-out
+// promises.
+function renderTasks(tasks, showItems) {
     if (tasks.length === 0)
         return "(none yet)";
     return tasks
         .map((t) => {
+        const item = showItems && t.item ? ` -- item: ${t.item}` : "";
         const notes = t.notes.trim() ? ` -- notes: ${t.notes.trim()}` : "";
         const error = t.error ? ` -- error: ${t.error}` : "";
         const blockedBy = t.blockedBy && t.blockedBy.length > 0
             ? ` -- blocked by: ${t.blockedBy.join(", ")}`
             : "";
-        return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${notes}${error}${blockedBy}`;
+        return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${item}${notes}${error}${blockedBy}`;
     })
         .join("\n");
 }
@@ -162,20 +805,26 @@ export function buildRouterPrompt(opts) {
     const deckSource = opts.deckContents?.trim()
         ? `\n\n== deck source (current contents -- no need to read_file these to see what's already there) ==\n${opts.deckContents.trim()}`
         : "";
+    // Sits with the board, not with the deck identity above: the plan changes on
+    // roughly the turns the board does, so co-locating them means it invalidates
+    // nothing the board wasn't already invalidating.
+    const plan = opts.plan
+        ? `\n\n== plan ==\n${renderPlanDigest(opts.plan, opts.tasks)}`
+        : "";
     // Section order is stable-to-volatile for prompt caching: rules + deck
     // identity never change within a serve, the transcript is append-only, and
     // the churning state (file tree, task board, instruction) rides at the tail
     // so a task creating a file doesn't invalidate the cached transcript prefix.
-    return `${ROUTER_RULES}
+    return `${routerRules(opts.plan !== undefined)}
 
 == deck ==
 ${opts.deckLabel}${quickReference}
 
 == conversation so far ==
-${renderTranscript(opts.messages)}${deckFiles}${deckSource}
+${renderTranscript(opts.messages)}${deckFiles}${deckSource}${plan}
 
 == background tasks ==
-${renderTasks(opts.tasks)}
+${renderTasks(opts.tasks, opts.plan !== undefined)}
 
 == now ==
 ${opts.instruction}
@@ -226,6 +875,20 @@ export function buildTaskPrompt(opts) {
     const deckSource = opts.deckContents?.trim()
         ? `\n\nDeck source (complete current contents of the deck's text files, snapshot at task start -- you do NOT need to read these files before editing them, edit directly; a file marked "not inlined" is either binary/generated or didn't fit the budget, so read it yourself first if you need it):\n\n${opts.deckContents.trim()}\n`
         : "";
+    const planSliceText = opts.plan
+        ? renderTaskPlanSlice(opts.plan.fileText ?? "", opts.plan.item, opts.plan.finishedWork)
+        : "";
+    const planSlice = planSliceText.trim()
+        ? `\n\nThe deck's plan (from plan.md):\n\n${planSliceText}\n`
+        : "";
+    const planRules = [
+        planSlice
+            ? "\n- The plan above is context, not a brief. It tells you what is settled and what already exists; it never widens your task. Do NOT edit plan.md -- it belongs to the conversation agent and the user."
+            : "",
+        opts.plan
+            ? `\n- Before you finish, write these lines to ${opts.handoffPath} -- they are the ONLY record of this task once the task itself is forgotten:\n  - \`what: <what now exists, and where>\` -- an existence fact, not a report of activity: "a shop panel in ui/shop.js the bag button opens", never "updated the shop logic". This is what the plan shows as already built, so a later agent extends it instead of rebuilding it.\n  - \`files: <the files you created or changed, comma-separated>\`\n  - \`knobs: <the values worth tuning, comma-separated>\` -- names only, and only if there are real ones.\n  - \`durable: <fact>\` -- the single thing worth remembering that is NOT covered by the three above (a preference the user expressed, a constraint you ran into, an approach that did not work). At most 200 characters. Leave it out only if nothing genuinely qualifies.`
+            : "",
+    ].join("");
     // Claude-only: collapsing the wrap-up (progress 90 + restart + notes) into
     // one shell call reliably saves 1-2 serial ~7s turns there. Cursor's
     // composer sometimes reacts to the same rule with MORE calls, so it stays
@@ -233,21 +896,24 @@ export function buildTaskPrompt(opts) {
     // (We deliberately do NOT tell agents to overwrite files via `cat > … <<EOF`
     // -- blind whole-file rewrites made parallel agents clobber each other's
     // edits. Read-then-edit is slower but safe; that is the right tradeoff.)
+    const wrapUpList = opts.plan
+        ? "the 90-progress write, the `castle-web save-version` for your paths, the final `npm run restart`, writing the notes file, and the handoff lines"
+        : "the 90-progress write, the `castle-web save-version` for your paths, the final `npm run restart`, and writing the notes file";
     const wrapUp = opts.backend === "claude" || opts.backend === "smith"
-        ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine the 90-progress write, the \`castle-web save-version\` for your paths, the final \`npm run restart\`, and writing the notes file into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
+        ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine ${wrapUpList} into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
         : "";
     return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions, and reload the served deck after changes (\`npm run restart\`).${quickReference}${layout}${deckSource}
 
 Your task (id ${opts.taskId}): ${opts.title}
 
-${opts.prompt}${deps}${siblings}
+${opts.prompt}${deps}${siblings}${planSlice}
 
 Operating rules:
 - The file snapshot above is for orientation. Prefer going straight to the files this task touches, but if this is an investigation or debugging task, survey what you need to understand the failure.
 - Speed is of the essence -- go for the quickest viable, testable change, unless this prompt explicitly tells you to take longer and dive deep. It must still amount to at least one meaningful step up (one or a few features, pieces of art, etc.), never a token gesture.
 - The USER is the verifier -- the whole tasks system exists so the user playtests every change themselves. Your first priority is to finish as soon as possible with the change genuinely in place and reachable in the running deck, so the user can test it right away. Do NOT run verification (screenshots especially) unless you are really sure it will catch something a re-read of your own change cannot -- and even then at most one cheap check, never a retry loop. Time spent verifying is time the user is left waiting.
 - The moment implementation is complete and you switch to verifying, write 90 to the progress file -- verification time must not read as stalled progress.
-- Do this one task completely, then stop. Do not expand scope.
+- Do this one task completely, then stop. Do not expand scope.${planRules}
 - SAVE A VERSION when your change is done, so the user can see and undo it: \`castle-web save-version -m "<short description of what you changed>" <each path you touched>\`. Name those paths explicitly -- a bare \`save-version\` with no paths records the WHOLE deck, including files a sibling agent is still working on. One version for the whole task, at the end; not one per file.
 - Overlap with the other agents working in this deck is fine and expected -- do not try to avoid it or wait for them. Saving only your own paths is all that is asked of you; nothing anyone has written is lost by your save.
 - NEVER run \`restore-version\`. Going back to an earlier version is the user's decision alone -- not yours, not even to undo your own work. If your change is wrong, fix it forward.
@@ -268,7 +934,7 @@ phase: wiring the paddle to touch
   - \`phase\` -- a SHORT, plain-language line for this moment ("wiring the paddle to touch", "drawing the flag"). No file or code names. Update \`avatar\` and \`phase\` together each time your stage changes -- a few times across the task, not every turn. (You may also include \`progress: NN\` here, but the progress file above is the primary progress channel.)
 - Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, NO file/behavior names or implementation notes -- those are for you, not the player. Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.${wrapUp}
 - If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
-- Never touch files under .castle/ other than those two paths. (The version store lives there too, but you never edit it by hand -- \`castle-web save-version\` writes it for you.)`;
+- Never touch files under .castle/ other than ${opts.plan ? "those three paths" : "those two paths"}. (The version store lives there too, but you never edit it by hand -- \`castle-web save-version\` writes it for you.)`;
 }
 // Appended to claude task agents' system prompt (portable replacement for the
 // machine-specific /goal slash command): commit to autonomous completion.