runcastle 1.4.4 → 1.4.6

package/index.js

@@ -44,7 +44,7 @@ function agentDigestFillRank(relPath) {
   const i = AGENT_DIGEST_FILL_ORDER.indexOf(relPath.toLowerCase());
   return i === -1 ? AGENT_DIGEST_FILL_ORDER.length : i;
 }
-var AGENT_DIGEST_DOCS, WITHHELD_FEATURE_DOCS, AGENT_DIGEST_FILL_ORDER;
+var AGENT_DIGEST_DOCS, PREVIEW_FILE = "preview.html", WITHHELD_FEATURE_DOCS, AGENT_DIGEST_FILL_ORDER;
 var init_docs = __esm(() => {
   AGENT_DIGEST_DOCS = ["brief.md", "decisions.md", "spec.md"];
   WITHHELD_FEATURE_DOCS = {
@@ -263,7 +263,7 @@ var init_schemas = __esm(() => {
     "drive-fix"
   ]);
   PROJECT_SESSION_KINDS = ["prepare", "project"];
-  SessionPurpose = z3.enum(["resolve-conflict", "start-lap"]);
+  SessionPurpose = z3.enum(["resolve-conflict", "start-lap", "self-plan"]);
   MergeBranchPair = z3.object({
     mergeFrom: z3.string(),
     mergeInto: z3.string()
@@ -1658,8 +1658,9 @@ ${why.replace(/\n/g, `\r
     containment?.kill();
     fireExit(code ?? 0, signal ? 1 : undefined);
   });
+  child.stdin?.on("error", () => {});
   function sendToHost(obj) {
-    if (!child.stdin || child.stdin.destroyed)
+    if (exitFired || !child.stdin || child.stdin.destroyed)
       return;
     try {
       child.stdin.write(JSON.stringify(obj) + `
@@ -2626,7 +2627,7 @@ function noteDocsChange(ctx, featureId, filename) {
   const entry = watches.get(featureId);
   if (!entry)
     return;
-  if (filename !== null && !filename.endsWith(".md"))
+  if (filename !== null && !filename.endsWith(".md") && filename !== PREVIEW_FILE)
     return;
   if (filename)
     entry.changed.add(filename);
@@ -2653,6 +2654,7 @@ function emitDocsChanged(ctx, featureId) {
 }
 var DOCS_WATCH_DEBOUNCE_MS = 300, watches;
 var init_docs_watch = __esm(() => {
+  init_src();
   init_events();
   init_feature_docs();
   init_repo();
@@ -3575,6 +3577,9 @@ function chatBranchName(slug, unique) {
 function burnWorktreePath(repoPath, branch) {
   return join6(repoPath, ".sandcastle", "worktrees", branch.replace(/\//g, "-"));
 }
+async function excludeBurnWorktrees(repoPath) {
+  await excludePath(repoPath, BURN_WORKTREES_PATTERN);
+}
 async function excludeFilePath(repoPath) {
   const raw = (await git(repoPath).raw(["rev-parse", "--git-path", "info/exclude"])).trim();
   return resolve3(repoPath, raw);
@@ -4615,7 +4620,7 @@ async function mergeInProgress(g) {
     return false;
   }
 }
-var DOCS_PATHSPEC = "docs/features", MIGRATION_DIR_RE, DRIZZLE_SQL_RE, DENY_DIRTY = "Working tree has uncommitted changes \u2014 commit or stash first", DENY_ACTIVE = "A test drive is already active \u2014 stop it first", DENY_ACTIVE_RUN = "Feature has an active run \u2014 wait for it to finish", DENY_NONE_ACTIVE = "No test drive is active", DENY_DRY_RUN_ACTIVE = "A preparation dry-run is in progress \u2014 stop it first", DENY_NO_DRY_RUN = "No preparation dry-run is in progress", DENY_NO_REVIEW_DRIVE = "No review drive is in progress for this feature", INITIAL_COMMIT_SUBJECT = "runcastle: initial commit", TICKET_BRANCH_PREFIX = "runcastle/ticket/", CHAT_BRANCH_PREFIX = "runcastle/chat/", PROJECT_BRANCH = "runcastle/project", TEMP_BRANCH_PREFIXES, TEMP_BRANCH_SLUG_MAX = 16, testDriveState, reviewDriveRelease, readinessTiming, DRY_RUN_SLUG = "prep-dry-run", PROJECT_DRIVE_SLUG = "project-drive", DENY_NO_PROJECT_DRIVE = "No project drive is running for this project";
+var DOCS_PATHSPEC = "docs/features", MIGRATION_DIR_RE, DRIZZLE_SQL_RE, DENY_DIRTY = "Working tree has uncommitted changes \u2014 commit or stash first", DENY_ACTIVE = "A test drive is already active \u2014 stop it first", DENY_ACTIVE_RUN = "Feature has an active run \u2014 wait for it to finish", DENY_NONE_ACTIVE = "No test drive is active", DENY_DRY_RUN_ACTIVE = "A preparation dry-run is in progress \u2014 stop it first", DENY_NO_DRY_RUN = "No preparation dry-run is in progress", DENY_NO_REVIEW_DRIVE = "No review drive is in progress for this feature", INITIAL_COMMIT_SUBJECT = "runcastle: initial commit", TICKET_BRANCH_PREFIX = "runcastle/ticket/", CHAT_BRANCH_PREFIX = "runcastle/chat/", PROJECT_BRANCH = "runcastle/project", TEMP_BRANCH_PREFIXES, TEMP_BRANCH_SLUG_MAX = 16, BURN_WORKTREES_PATTERN = ".sandcastle/worktrees/", testDriveState, reviewDriveRelease, readinessTiming, DRY_RUN_SLUG = "prep-dry-run", PROJECT_DRIVE_SLUG = "project-drive", DENY_NO_PROJECT_DRIVE = "No project drive is running for this project";
 var init_git = __esm(() => {
   init_src();
   init_paths();
@@ -4773,6 +4778,9 @@ function entrySkillsFor(kind) {
 function chatKickoffFor(runtime, opening) {
   return opening === "ideate" ? `Proceed with your task: invoke the ${skillRef(runtime, "ideate")} skill and drive this ` + "feature's ideation to completion." : `Proceed with your task: invoke the ${skillRef(runtime, "revisit")} skill and continue this ` + "feature's conversation.";
 }
+function selfPlanKickoffFor(runtime) {
+  return "Proceed with your task: no human is present and nobody will reply to you. Invoke the " + `${skillRef(runtime, "ideate")} skill and follow its "${PLANNING_WITHOUT_A_HUMAN}" section ` + "to plan this feature by yourself, through the preview, the spec and the tickets, in this one run.";
+}
 function kickoffLinesFor(runtime) {
   const skill = (name) => skillRef(runtime, name);
   return {
@@ -4788,7 +4796,7 @@ function projectTriageKickoffFor(runtime) {
 function prepareConfirmKickoffFor(runtime) {
   return `Proceed with your task: invoke the ${skillRef(runtime, "prepare")} skill. Every prepared field already ` + "has a value, so this is a confirmation, not a preparation \u2014 tell me what is recorded and " + "how stale it is, ask whether it still holds, and stop. Do not re-derive a settled value.";
 }
-var PACK = "runcastle", SPELLINGS, ENTRY_SKILLS;
+var PACK = "runcastle", SPELLINGS, ENTRY_SKILLS, PLANNING_WITHOUT_A_HUMAN = "Planning without a human";
 var init_skills = __esm(() => {
   SPELLINGS = {
     "claude-code": (skill) => `/${PACK}:${skill}`,
@@ -4829,7 +4837,8 @@ function chatOpening(feature, planning) {
 function renderSystemPrompt(feature, kind, lap, purpose, runtime = DEFAULT_RUNTIME, carried, planning) {
   if (lap !== undefined)
     return renderRevisitPrompt(feature, lap, purpose, runtime, carried);
-  if (kind === "chat" && chatOpening(feature, planning) === "revisit") {
+  const selfPlan = purpose === "self-plan";
+  if (kind === "chat" && !selfPlan && chatOpening(feature, planning) === "revisit") {
     return renderRevisitPrompt(feature, lap, purpose, runtime, carried);
   }
   const docs2 = featureDocsRel(feature.slug);
@@ -4862,12 +4871,26 @@ function renderSystemPrompt(feature, kind, lap, purpose, runtime = DEFAULT_RUNTI
     noCodeRule(docs2),
     otherEntrySkillsRule(),
     "",
+    ...selfPlan ? [selfPlanRule(), ""] : [],
     "## Your task",
     `Begin by invoking the \`${skillRef(runtime, "ideate")}\` skill and drive the ideation session to completion.`,
     ""
   ].join(`
 `);
 }
+function selfPlanRule() {
+  return [
+    "## No human is present",
+    "This is a self-planning run: nobody is watching and nobody will reply.",
+    "- Never end your turn to ask a question \u2014 ending the turn ends the run. Ask your design",
+    "  questions of yourself, as the skill describes, and answer them.",
+    "- A refused tool is not a wait: do not retry it or wait for approval. Decide on what you",
+    "  know and treat that decision as a candidate to check first.",
+    `- Follow the ideation skill's "${PLANNING_WITHOUT_A_HUMAN}" section through the preview, the`,
+    "  spec and the tickets, in this one run."
+  ].join(`
+`);
+}
 function reviewEvidenceSection(lap, docs2, carried) {
   const evidence = carried?.reviewEvidence ?? [];
   return [
@@ -5451,6 +5474,10 @@ var init_skills_root = __esm(() => {
 });
 
 // src/launcher/runtimes/types.ts
+function assertHeadlessKickoff(headless, line) {
+  if (headless && !line)
+    throw new Error("a headless launch needs a kickoff line as its prompt");
+}
 function assertKickoffArgv(line) {
   if (line !== undefined && line.length > MAX_KICKOFF_ARGV) {
     throw new Error(`kickoff line is ${line.length} characters; maximum is ${MAX_KICKOFF_ARGV}`);
@@ -5461,9 +5488,11 @@ var MAX_KICKOFF_ARGV = 30000;
 // src/launcher/runtimes/claude.ts
 function buildClaudeArgs(input) {
   assertKickoffArgv(input.kickoffLine);
+  assertHeadlessKickoff(input.headless, input.kickoffLine);
   const permissionMode = input.permissionMode ?? "acceptEdits";
-  const resume = input.resumeSessionId ? ["--resume", input.resumeSessionId] : [];
+  const resume = input.resumeSessionId && !input.headless ? ["--resume", input.resumeSessionId] : [];
   return [
+    ...input.headless ? ["-p"] : [],
     ...resume,
     "--settings",
     input.settingsPath,
@@ -5526,7 +5555,8 @@ var init_claude = __esm(() => {
           model: input.model,
           ...input.resumeSessionId ? { resumeSessionId: input.resumeSessionId } : {},
           ...input.kickoffLine ? { kickoffLine: input.kickoffLine } : {},
-          strictMcp: input.config.sessionMcp === "runcastleOnly"
+          strictMcp: input.config.sessionMcp === "runcastleOnly",
+          ...input.headless ? { headless: true } : {}
         }),
         env: {
           RUNCASTLE_SESSION_ID: input.session.id,
@@ -7136,12 +7166,16 @@ function toml(value) {
 function approvalPolicyFor(permissionMode) {
   return permissionMode === undefined || permissionMode === "acceptEdits" ? "never" : "on-request";
 }
+function sandboxModeFor(permissionMode, platform) {
+  return platform === "win32" && approvalPolicyFor(permissionMode) === "never" ? "danger-full-access" : "workspace-write";
+}
 function renderCodexConfig(input) {
   const { session, config: config2, model, worktreePath, inheritedMcpServers, permissionMode } = input;
+  const platform = input.platform ?? process.platform;
   return [
     `# Generated by runcastle for session ${session.id} \u2014 rewritten at every launch.`,
     `model = ${toml(model)}`,
-    'sandbox_mode = "workspace-write"',
+    `sandbox_mode = ${toml(sandboxModeFor(permissionMode, platform))}`,
     `approval_policy = ${toml(approvalPolicyFor(permissionMode))}`,
     "check_for_update_on_startup = false",
     "",
@@ -7155,6 +7189,7 @@ function renderCodexConfig(input) {
     "[mcp_servers.runcastle]",
     `url = ${toml(`${serverUrlFor(config2)}/mcp`)}`,
     `http_headers = { "X-Runcastle-Session" = ${toml(session.id)} }`,
+    'default_tools_approval_mode = "approve"',
     ""
   ].join(`
 `);
@@ -7263,6 +7298,9 @@ function gitInfoDir(worktreePath) {
 }
 function buildCodexArgs(input) {
   assertKickoffArgv(input.kickoffLine);
+  assertHeadlessKickoff(input.headless, input.kickoffLine);
+  if (input.headless)
+    return ["exec", "--dangerously-bypass-hook-trust", input.kickoffLine];
   return [
     ...input.resumeSessionId ? ["resume", input.resumeSessionId] : [],
     "--dangerously-bypass-hook-trust",
@@ -7335,7 +7373,8 @@ var init_codex = __esm(() => {
         files,
         argv: buildCodexArgs({
           ...input.resumeSessionId ? { resumeSessionId: input.resumeSessionId } : {},
-          ...input.kickoffLine ? { kickoffLine: input.kickoffLine } : {}
+          ...input.kickoffLine ? { kickoffLine: input.kickoffLine } : {},
+          ...input.headless ? { headless: true } : {}
         }),
         env: {
           CODEX_HOME: home,
@@ -7970,6 +8009,12 @@ function listDocs(ctx, feature) {
     return { relPath: e.name, title: readTitle(path, e.name), ...writtenAt(path) };
   }).sort((a, b) => a.relPath.localeCompare(b.relPath));
 }
+function previewSummary(ctx, feature) {
+  const path = featureDocPath(projectForFeature(ctx, feature), feature, PREVIEW_FILE);
+  if (!existsSync12(path))
+    return null;
+  return { relPath: PREVIEW_FILE, ...writtenAt(path) };
+}
 function readDoc(ctx, feature, relPath) {
   const project = projectForFeature(ctx, feature);
   const dir = featureDocsDir(project, feature);
@@ -8002,6 +8047,7 @@ function readTitle(path, fallback) {
 }
 var CHARTER_FILE = "CONTEXT.md", ADR_DIR_REL = "docs/adr", SUPERSEDED_RE;
 var init_knowledge = __esm(() => {
+  init_src();
   init_errors();
   init_events();
   init_feature_docs();
@@ -57790,6 +57836,7 @@ async function runReviewGates(input) {
     mkdirSync10(reviewGateLogDir(ticketId), { recursive: true });
     await discardBranch();
     await pinBranchAt(project3.repoPath, branch, sha);
+    await excludeBurnWorktrees(project3.repoPath);
     while (results.length < commands.length) {
       await withSandbox(branch, async (sandbox3) => {
         for (const [i, command] of commands.entries()) {
@@ -60552,6 +60599,7 @@ async function burnTicket(ctx, ticket, config2, token, model, hostAgentVersions,
       await clearAttachments(burnWorktreePath(project3.repoPath, branch), project3.repoPath);
     }
   };
+  await excludeBurnWorktrees(project3.repoPath);
   const ticketJson = buildTicketJson(ticket);
   const featureBrief = buildFeatureBrief(feature);
   const docsDigest = blocks.docsDigest;
@@ -61659,6 +61707,7 @@ function getFeatureFull(ctx, id3) {
     sessions: listSessionsByFeature(ctx, id3).map((session) => session.kind === "chat" && session.status === "ended" && !session.ccSessionId ? { ...session, title: null, transcriptMissing: true } : session),
     runs: listRunsByFeature(ctx, id3),
     docs: listDocs(ctx, feature),
+    preview: previewSummary(ctx, feature),
     dependsOn: dependsOnOf(ctx, id3),
     blocks: blocksOf(ctx, id3)
   };
@@ -64724,7 +64773,7 @@ function ptyExitMessage(exitCode) {
   const label = typeof exitCode === "number" ? String(exitCode) : "unknown";
   return `terminal exited (code ${label})`;
 }
-function chatKickoffHeader(ctx, feature, runtime5 = DEFAULT_RUNTIME) {
+function chatKickoffHeader(ctx, feature, runtime5 = DEFAULT_RUNTIME, opening = chatKickoffFor(runtime5, chatOpening(feature, planningFacts(ctx, feature)))) {
   const counts = new Map;
   for (const ticket of listByFeature(ctx, feature.id)) {
     counts.set(ticket.status, (counts.get(ticket.status) ?? 0) + 1);
@@ -64737,7 +64786,6 @@ function chatKickoffHeader(ctx, feature, runtime5 = DEFAULT_RUNTIME) {
     const outcome = !latestRun ? "never driven" : latestReview?.status === "done" ? "passed" : latestReview?.status === "failed" ? "failed" : "unverified";
     review = ` Drive outcome: ${outcome}; see the review evidence in get_feature_context.`;
   }
-  const opening = chatKickoffFor(runtime5, chatOpening(feature, planningFacts(ctx, feature)));
   return `${opening} Feature state: ${feature.phase}; lap ${feature.lap}; tickets: ${ticketSummary}; latest run: ${latestRun?.status ?? "none"}.${review} Call get_feature_context for the full picture.`;
 }
 function assertRuntimeReady(runtime5, opts) {
@@ -64764,6 +64812,21 @@ function assertSpawnable(ctx, feature, excludeSessionId) {
     throw new GateError(`a ${live[0].kind} session is already live for ${feature.slug} \u2014 only one terminal per feature; end or resume it first`);
   }
 }
+function isSelfPlan(input) {
+  return input.kind === "chat" && input.purpose === "self-plan";
+}
+function assertSelfPlannable(ctx, feature) {
+  if (feature.phase !== "planning") {
+    throw new GateError(`${feature.slug} is past planning, so there is nothing for it to plan by itself \u2014 open the chat to change it`);
+  }
+  if (chatOpening(feature, planningFacts(ctx, feature)) !== "ideate") {
+    throw new GateError(`${feature.slug} already has planning on record (decisions, a spec or tickets), so it cannot plan itself from scratch \u2014 open the chat to carry on`);
+  }
+  assertSpawnable(ctx, feature);
+}
+function selfPlanRunningError(feature) {
+  return new GateError(`${feature.slug} is planning itself \u2014 stop the run first, then open the chat to pick up where it got to`);
+}
 async function ensureWorktree(ctx, project3, feature) {
   const running3 = activeRunFor(ctx, feature.id);
   const besideRun = !!running3 && workflowClaimsFeatureBranch(running3.workflow);
@@ -64845,7 +64908,11 @@ async function launchSession(ctx, input, opts = {}) {
   requireNotDraft(feature);
   if (input.kind === "chat") {
     const liveChat = activeSessionsForFeature(ctx, feature.id).find((s) => s.kind === "chat");
-    if (liveChat && isStartLap(feature, input))
+    if (liveChat?.purpose === "self-plan")
+      throw selfPlanRunningError(feature);
+    if (isSelfPlan(input))
+      assertSelfPlannable(ctx, feature);
+    else if (liveChat && isStartLap(feature, input))
       endSession(ctx, liveChat.id);
     else if (liveChat)
       return briefLiveChat(ctx, feature, liveChat, input);
@@ -64865,8 +64932,9 @@ async function launchSession(ctx, input, opts = {}) {
   });
   const carried = startLapCarriedWork(ctx, feature.id);
   const plan = planLaunchKickoff(feature, input, carried);
+  const selfPlan = isSelfPlan(input);
   if (input.kind === "chat") {
-    const header = chatKickoffHeader(ctx, feature, runtime5.id);
+    const header = chatKickoffHeader(ctx, feature, runtime5.id, selfPlan ? selfPlanKickoffFor(runtime5.id) : undefined);
     plan.line = plan.line ? `${plan.line} ${header}` : header;
   }
   let resumeSessionId;
@@ -64879,6 +64947,8 @@ async function launchSession(ctx, input, opts = {}) {
       markSessionEnded(ctx, session.id);
       throw e;
     }
+  }
+  if (input.kind === "chat" && !selfPlan) {
     const prior = mostRecentResumableSession(ctx, feature.id, "chat");
     if (prior?.ccSessionId) {
       resumedFrom = prior;
@@ -64918,12 +64988,13 @@ async function launchSession(ctx, input, opts = {}) {
   const kickoffLine = resumeSessionId && input.kind !== "chat" ? undefined : kickoffLineFor(input.kind, plan.line, runtime5.id);
   emit(ctx, feature.id, {
     type: "session.launching",
-    message: `launching ${input.kind} session`,
+    message: selfPlan ? "launching a self-planning run" : `launching ${input.kind} session`,
     data: {
       sessionId: session.id,
       kind: input.kind,
       worktreePath,
-      ...modelStamp(model)
+      ...modelStamp(model),
+      ...input.purpose ? { purpose: input.purpose } : {}
     }
   });
   if (resumeSessionId) {
@@ -64960,7 +65031,8 @@ async function launchSession(ctx, input, opts = {}) {
     model: model.id,
     resumeSessionId,
     resumeSourceSessionId: resumedFrom?.id,
-    kickoffLine
+    kickoffLine,
+    ...selfPlan ? { headless: true } : {}
   });
   if (opts.spawn === false) {
     emit(ctx, feature.id, {
@@ -65306,6 +65378,15 @@ function handlePtyExit(ctx, feature, session, meta, exitCode) {
       }
     });
   }
+  if (session.purpose === "self-plan" && feature) {
+    const current2 = getFeatureRow(ctx, feature.id);
+    const complete4 = current2.ticketsReadyLap === current2.lap;
+    emitForSession(ctx, session, {
+      type: "session.self_plan_ended",
+      message: complete4 ? "planning finished" : "planning stopped before the plan was complete",
+      data: { sessionId: session.id, complete: complete4, exitCode: exitCode ?? null }
+    });
+  }
   emitForSession(ctx, session, {
     type: "session.pty_exited",
     message: ptyExitMessage(exitCode),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Burn tickets into shipped features with Claude Code.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/skills/packs/runcastle/skills/ideate/SKILL.md

@@ -22,12 +22,14 @@ Everything happens in this one window. **Never compact. Never `/clear`. Never su
 
 - `mcp__runcastle__get_feature_context` / `mcp__runcastle__read_feature_doc` / `mcp__runcastle__list_tickets` / `mcp__runcastle__get_ticket` — the record.
 - `mcp__runcastle__create_feature({ title, oneLiner, brief, draft: true, dependsOn? })` — park scope creep as a draft feature (§1), with `dependsOn: [<this feature's slug>]` when it builds on this one. `draft: true` is the only door open to you; a full create belongs to the project session.
-- `mcp__runcastle__complete_phase` — the phase boundaries (§3), and the ones `/runcastle:spec` and `/runcastle:tickets` cross after you.
+- `mcp__runcastle__complete_phase` — the phase boundaries (§4), and the ones `/runcastle:spec` and `/runcastle:tickets` cross after you.
 - `mcp__runcastle__emit_tickets` — used by `/runcastle:tickets`, not by you directly.
 - `mcp__runcastle__record_event` — the feature timeline. Most state changes already emit their own event; only reach for this when the timeline would otherwise have no record at all.
 
 ## 1. Grill relentlessly
 
+This is the **grill path**: the human is here and answers. When your briefing says no human is present, take the **self-planning path** in "Planning without a human" below instead; the rules of this section do not bind it.
+
 Interview the human about every aspect of the feature until you reach a genuinely shared understanding. Walk each branch of the design tree, resolving dependencies between decisions one at a time.
 
 - **One question at a time.** Wait for the answer before the next. Asking several at once is bewildering.
@@ -38,7 +40,19 @@ Interview the human about every aspect of the feature until you reach a genuinel
 - **Park scope creep instead of swallowing it.** When something surfaces that is plainly its own feature, say so and offer to park it: `mcp__runcastle__create_feature({ title, oneLiner, brief, draft: true })` creates a parked draft — no branch, nothing written — with the `brief` carrying why you deferred it and what it must not swallow. When the parked scope builds on this feature, also pass `dependsOn: [<this feature's slug>]` so it cannot be started before this one merges. Then get back to this feature. Drafts are the only thing you may create here; a full create belongs to the project session.
 - **A feature bigger than expected gets a thin lap 1.** The project session sizes features to fit one ideation window before they reach you, so this is rare. When a feature still turns out bigger than this window mid-grill, do not grind on and do not split it yourself: put the slicing question to the human again, recommend a thin lap 1, and park the rest under the spec's `## Later laps`.
 
-Do not move on until the human confirms you have reached shared understanding.
+On the grill path, do not move on until the human confirms you have reached shared understanding. That confirmation happens on the preview (§3), not in chat alone.
+
+## 1a. Planning without a human
+
+This is the **self-planning path**. It applies only when your briefing says no human is present; with a human here, §1 stands and this section does not. You still look up facts, model the domain and park scope creep as §1 says. What changes is who answers.
+
+- **One turn.** Do the whole plan in this one turn. Never end the turn to ask a question or to report progress: nobody will reply, and ending the turn ends the run.
+- **Frontier rounds.** Work in rounds. A round is every open question that does not depend on an unanswered one. Write each as you would put it to the human, with your recommended answer and the main alternative, then accept your own recommendations and record them. Then ask what those answers opened: that is the next round. Write each round to `decisions.md` as it is decided (§2), not at the end, so a run that dies keeps what it had.
+- **Depth rule.** Record a decision only if it changes what the feature is or does for its users, or the human might reasonably overturn it. Anything an engineer would settle while building (wording, internal formats, test coverage) is not a question; it goes to the spec as detail.
+- **Exactly one challenger.** When a round would be empty, run one separate agent: the Agent tool in Claude Code, `spawn_agent` in Codex. Give it only the brief and `decisions.md`. Ask it for (a) design branches never asked, within the depth rule, and (b) decisions it would have made differently, with its reason. Do not tell it what you expect to hear. Ask its branches as one more round and decide them, with whatever they open. A decision it disagrees with is marked challenged with its reason (§2), and your own answer stands. There is no second pass, and no requirement that the pass come back empty. If you have no tool that runs a separate agent, challenge your own plan as a separate pass and write in `decisions.md` that the challenge was not independent.
+- **A refused tool is not a wait.** If a tool is refused, do not retry it and do not wait: decide on what you know, and treat that decision as a candidate to check first.
+- **Check first.** Pick at most five decisions for the human to check first: guesses about the human's intent that the brief did not settle, decisions that force several others, and decisions the challenger disagreed with. They open the preview's decisions part (`./references/preview.md`).
+- **Straight through.** Then draw the preview and run its self-check (§3, steps 1 and 2), but do not tell the human to look and do not wait: complete ideation (§4), run `/runcastle:spec`, then `/runcastle:tickets` (§5). End with one closing message (§6): the plan was made without the human, how many decisions it holds, and which are to check first.
 
 ## 2. Lock decisions incrementally
 
@@ -50,24 +64,64 @@ The moment a decision locks, append it to `docs/features/<slug>/decisions.md`
 **Why:** <the reason / the trade-off chosen over the alternatives>
 ```
 
+A decision you made without the human (the self-planning path, §1a) keeps that shape and adds one line naming the main alternative it was chosen over. A decision the challenger disagreed with adds a further line with its reason:
+
+```markdown
+## <n>. <short decision title>
+**Decision:** <the choice>
+**Why:** <the reason>
+**Assumed.** Alternative: <the main alternative>.
+**Challenged:** <the challenger's reason>.
+```
+
+For example:
+
+```markdown
+## 4. Tags and dates are left out of the PDF
+**Decision:** The PDF carries the title and body only.
+**Why:** The brief asks for the note, not its filing.
+**Assumed.** Alternative: a small footer with tags and the last-edited date.
+```
+
+When the human later confirms or changes such a decision, the session doing the edit removes its `**Assumed.**` and `**Challenged:**` lines; from then on it reads as any other decision.
+
 Keep `decisions.md` free of implementation minutiae — it is the record of *what was decided and why*, the raw material spec and tickets are built from. `complete_phase` checkpoints the file into git for you; you just write it. The file is the record — do not narrate it onto the timeline as you go.
 
-## 3. Complete ideation
+## 3. Draw the preview, then wait for the human to look
+
+**The preview is what the human confirms shared understanding on.** It is one self-contained page, `docs/features/<slug>/preview.html`, that shows the feature and every decision; the human reads the feature by looking at it.
+
+1. **Draw it.** When the decisions are locked, read `./references/preview.md` (the rules) and write `preview.html` from `./references/preview-starter.html`.
+2. **Check it against `decisions.md`.** Every decision appears by its number and title. Fix the preview before anyone sees it.
+
+On the self-planning path (§1a) steps 1 and 2 are the whole of this section: go straight on to §4. Steps 3 to 5 are the grill path.
 
-When the human confirms shared understanding and the open questions are answered or explicitly deferred:
+3. **Tell the human to look, then wait.** Say the preview is on the feature's **Overview**, under the Burn row, and that the "Preview ready" notice in Chat leads there. Then stop and wait for their answer.
+4. **A correction is a decision edit plus a redraw.** Edit the decision in `decisions.md` and redraw the preview in the same move, then ask them to look again.
+5. **Only after the human confirms**, complete ideation (§4).
+
+**Never skip the preview on your own judgement** — not because the feature is small, not because the grill went quickly. A small feature gets a small preview. **If the human says to skip it**, write no file and go straight on to §4.
+
+**The redraw rule.** While the feature is at planning, any later edit to `decisions.md` — in this session or after it — updates `preview.html` in the same move, before anything else.
+
+## 4. Complete ideation
+
+On the grill path, when the human confirms shared understanding on the preview and the open questions are answered or explicitly deferred. On the self-planning path (§1a), as soon as the preview passes its check, without waiting:
 
 `mcp__runcastle__complete_phase({ phase: "ideation" })` → returns `{ ok: true, nextPhase, nextStep }`. It does not refuse and it does not move the feature: ideation, spec and tickets are three steps inside **Planning**, and this records the milestone on the timeline. `nextStep` is the next step still missing its artifact, read off disk rather than stored — so if `decisions.md` is not written yet it comes back as `"ideation"` again, which is your cue to write it. It logs its own timeline event; do not add one.
 
-## 4. Spec → tickets — stay in this window
+## 5. Spec → tickets — stay in this window
 
 Invoke `/runcastle:spec` (it writes `spec.md` and completes the `spec` phase); when it returns, invoke `/runcastle:tickets`.
 
 Do not open a new session for these. They run here, on top of everything you just learned.
 
-## 5. Close — hand off to the human
+## 6. Close — hand off to the human
 
 `/runcastle:tickets` ends by emitting tickets to the runcastle store. When it returns, your job is **done**. Tell the human plainly:
 
 > Tickets are in the runcastle UI. Review the ticket cards and click **Burn** to start the AFK agents. That is the next step — I will stop here.
 
+On the self-planning path (§1a), the closing message also says that the plan was made without the human, how many decisions it holds, and which are to check first, by number and title. Then end the turn; the run is done.
+
 Do **not** start burning. Burn and Merge are the only two clicks in the whole pipeline, and both belong to the human. (You do not write code here either — that rule is in your injected prompt and enforced by the edit guard, not restated as advice.)