@try-works/dsh-recursive-mode 0.4.6 → 0.4.7

package/lib/errors.d.ts

@@ -151,6 +151,19 @@ export declare const TOOL_ERRORS: {
         readonly problem: "the run has unresolved delegated work, so this phase cannot lock yet";
         readonly next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again";
     };
+    /**
+     * THE ORDERING DEFECT, AS A CODE. `recursive_ask gate=run-start` used to raise "start this run or hold?"
+     * over a Phase 0 document that was still the scaffold `recursive_init` wrote — placeholder requirements,
+     * unchecked lists, `FAIL` gates — and nothing put that document in front of the person either. The owner:
+     * *"i was never shown the spec before that so how could i approve if i havent seen it"*. Approving an
+     * unfilled template is not a decision about a spec, so the gate refuses to be raised until there is one.
+     */
+    readonly RUN_START_SPEC_UNFILLED: {
+        readonly code: "RM4404";
+        readonly klass: "state";
+        readonly problem: "the Phase 0 requirements document is still the unfilled template, so there is no run spec for a person to approve";
+        readonly next: "fill the requirements document in (define the requirement ids and their acceptance criteria, and complete the TODO list) and then call recursive_ask with gate: run-start again";
+    };
     readonly RUN_START_NO_CHANNEL: {
         readonly code: "RM5502";
         readonly klass: "runtime";

package/lib/index.js

@@ -5480,6 +5480,19 @@ const TOOL_ERRORS = {
 		problem: "the run has unresolved delegated work, so this phase cannot lock yet",
 		next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again"
 	},
+	/**
+	* THE ORDERING DEFECT, AS A CODE. `recursive_ask gate=run-start` used to raise "start this run or hold?"
+	* over a Phase 0 document that was still the scaffold `recursive_init` wrote — placeholder requirements,
+	* unchecked lists, `FAIL` gates — and nothing put that document in front of the person either. The owner:
+	* *"i was never shown the spec before that so how could i approve if i havent seen it"*. Approving an
+	* unfilled template is not a decision about a spec, so the gate refuses to be raised until there is one.
+	*/
+	RUN_START_SPEC_UNFILLED: {
+		code: "RM4404",
+		klass: "state",
+		problem: "the Phase 0 requirements document is still the unfilled template, so there is no run spec for a person to approve",
+		next: "fill the requirements document in (define the requirement ids and their acceptance criteria, and complete the TODO list) and then call recursive_ask with gate: run-start again"
+	},
 	RUN_START_NO_CHANNEL: {
 		code: "RM5502",
 		klass: "runtime",
@@ -6864,6 +6877,79 @@ function extractAndGroup(runner, env, options = {}) {
 	};
 }
 //#endregion
+//#region src/run-spec.ts
+/** The named evidence classes, so a reader can tell a placeholder from an unmet gate. */
+const ARTIFACT_MARKER_IDS = {
+	placeholder: "placeholder",
+	uncheckedTodo: "unchecked-todo",
+	failedGate: "failed-gate"
+};
+/** Every marker, in the order they are reported for a single line. */
+const MARKER_PATTERNS = [
+	{
+		id: ARTIFACT_MARKER_IDS.placeholder,
+		re: /(^\s*\.\.\.\s*$)|(\[[^[\]\n<>]{2,120}\])|(<[^<>\n]{2,120}>)/
+	},
+	{
+		id: ARTIFACT_MARKER_IDS.uncheckedTodo,
+		re: /^\s*[-*]\s*\[ \]/
+	},
+	{
+		id: ARTIFACT_MARKER_IDS.failedGate,
+		re: /^\s*(Coverage|Approval):\s*FAIL\b/i
+	}
+];
+/**
+* Which marker a single line carries, or null.
+*
+* Exported because the client prints the marker NAMES beside the quoted lines, and a second classifier that
+* re-derived them would be a second answer to the same question.
+*/
+function markerIdsOnLine(line) {
+	const ids = [];
+	for (const pattern of MARKER_PATTERNS) if (pattern.re.test(line)) ids.push(pattern.id);
+	return ids;
+}
+/**
+* Classify one artifact's text.
+*
+* A verdict of `unfilled` means the document still carries the template's own placeholder text — the
+* evidence travels with it, line by line, so the refusal (and the client notice) can name what is missing
+* instead of asserting a state the reader cannot check.
+*/
+function classifyArtifact(text) {
+	const lines = text.split(/\r?\n/);
+	const hits = [];
+	for (let i = 0; i < lines.length; i += 1) {
+		const line = lines[i];
+		for (const id of markerIdsOnLine(line)) hits.push({
+			id,
+			line: i + 1,
+			text: line.trim()
+		});
+	}
+	return {
+		verdict: hits.some((hit) => hit.id === ARTIFACT_MARKER_IDS.placeholder) ? "unfilled" : "filled",
+		hits
+	};
+}
+/** The unfilled evidence only (what a refusal names). */
+function unfilledEvidence(result) {
+	return result.hits.filter((hit) => hit.id === ARTIFACT_MARKER_IDS.placeholder);
+}
+/**
+* One line naming what is missing, for a refusal sentence.
+*
+* The line number and the text are both quoted: "line 12: <short title>" is a thing a reader can go and
+* look at, while "the requirements are not filled in" is an assertion they would have to take on trust.
+*/
+function describeEvidence(hits, limit = 3) {
+	const shown = hits.slice(0, limit).map((hit) => "line " + String(hit.line) + ": " + hit.text);
+	const rest = hits.length - shown.length;
+	const suffix = rest > 0 ? " (and " + String(rest) + " more)" : "";
+	return shown.join(" | ") + suffix;
+}
+//#endregion
 //#region src/run-start.ts
 /**
 * PHASE 0 — STARTING A RUN IS A HUMAN DECISION, NOT A SIDE EFFECT OF SCAFFOLDING.
@@ -6986,6 +7072,43 @@ function readRunStartApproval(root, runId) {
 * the same string instead of re-typing it (a re-typed reason is a caller that silently stops matching).
 */
 const RUN_START_NOT_APPROVED = "run not started: phase 0 approval has not been granted";
+/**
+* PHASE 0 — THE GATE CANNOT BE RAISED BEFORE THERE IS A SPEC TO DECIDE ABOUT.
+*
+* THE DEFECT. `recursive_init` scaffolds Phase 0 as a TEMPLATE, and `recursive_ask gate=run-start` raised
+* "start this run or hold?" over it immediately — while every requirement was still `<short title>`, every
+* acceptance criterion was still `[observable condition 1]`, and nothing put the document in front of the
+* person at all. The owner: *"the card ui for accepting the spec appeared, but i was never shown the spec
+* before that so how could i approve if i havent seen it"*. Approving an unfilled template is not a decision
+* about a spec; there is no spec yet, and a card that asks the question anyway teaches a person to answer
+* without reading.
+*
+* ⚠ WHAT THIS DOES *NOT* TOUCH. It does not weaken the gate's own contract, it does not add a second way to
+* start a run, and it does not make the plugin the decider: it only refuses to ASK. A person's own answer
+* still wins (`recordRunStartAnswer` is unchanged), a spec still creates no goal, and cancellation / abort /
+* timeout are still unrelayable. The check runs BEFORE the question is put to anybody, so no card is shown
+* for a document that cannot be approved meaningfully.
+*
+* ⚠ AND IT IS A CHECK ON THE DOCUMENT, NOT ON THE CALLER. A `runId` that does not resolve is not this
+* refusal's business — the ask path already reports that — so the guard says `ok: true` there and lets the
+* existing route handle it.
+*/
+function runStartSpecGuard(root, runId) {
+	const content = readRunStartArtifact(root, runId);
+	if (content === null) return {
+		ok: false,
+		reason: toolError("RUN_START_SPEC_UNFILLED", "there is no Phase 0 document to approve: " + runStartArtifactPath(root, runId) + " does not exist yet")
+	};
+	const verdict = classifyArtifact(content);
+	if (verdict.verdict === "filled") return { ok: true };
+	const evidence = unfilledEvidence(verdict);
+	const context = verdict.hits.filter((hit) => hit.id !== "placeholder");
+	const contextNote = context.length === 0 ? "" : " (it also carries " + String(context.length) + " unfinished marker(s) of its own, starting at line " + String(context[0]?.line ?? 0) + ")";
+	return {
+		ok: false,
+		reason: toolError("RUN_START_SPEC_UNFILLED", "00-requirements.md for run " + JSON.stringify(runId) + " still carries the template scaffold" + contextNote + ": " + describeEvidence(evidence))
+	};
+}
 //#endregion
 //#region src/recursive_ask.tool.ts
 /**
@@ -7201,7 +7324,7 @@ function pendingGateFor(artifactFile, artifactText) {
 function createRecursiveAskTool(recursive) {
 	return defineTool({
 		name: "recursive_ask",
-		description: "Ask a human gate as a structured decision (tdd-mode, qa-signoff, gate-block), or ASK TO START A RUN (run-start: nothing runs, and no goal exists, until this gate is approved). Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. For run-start the mounted human channel is asked first and its own selection wins; when that channel cannot deliver the question, the refusal names the cause and `relay=true` with an explicit `answer` records the person's relayed approval. One ask per step.",
+		description: "Ask a human gate as a structured decision (tdd-mode, qa-signoff, gate-block), or ASK TO START A RUN (run-start: nothing runs, and no goal exists, until this gate is approved). Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. For run-start the mounted human channel is asked first and its own selection wins; when that channel cannot deliver the question, the refusal names the cause and `relay=true` with an explicit `answer` records the person's relayed approval. The run-start gate is REFUSED while the Phase 0 requirements document is still the unfilled template — the refusal quotes the placeholder lines, and there is nothing to approve until they are written. One ask per step.",
 		parameters: {
 			gate: {
 				type: "string",
@@ -7240,6 +7363,16 @@ function createRecursiveAskTool(recursive) {
 			const root = await recursive.resolveWorkspaceRoot(exec.agent);
 			if (!root) return { error: toolError("NO_WORKSPACE") };
 			const artifact = (isRunStartGate(gateId) ? RUN_START_ARTIFACT : args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId]).trim();
+			if (isRunStartGate(gateId)) {
+				const guard = runStartSpecGuard(root, runId);
+				if (!guard.ok) return {
+					error: guard.reason,
+					gate: RUN_START_GATE_ID,
+					runId,
+					artifact: RUN_START_ARTIFACT,
+					question: buildAskQuestionFor(RUN_START_GATE_ID)
+				};
+			}
 			let question;
 			try {
 				question = buildAskQuestionFor(gateId);

package/lib/run-spec.d.ts

@@ -0,0 +1,78 @@
+/**
+ * IS THIS RUN SPEC STILL A HOLLOW TEMPLATE? — one answer, two callers.
+ *
+ * WHY THIS MODULE EXISTS. `recursive_init` scaffolds Phase 0 as a TEMPLATE: the requirement block
+ * still reads `### \`R1\` <short title>`, the acceptance criteria are still `[observable condition 1]`,
+ * the checklists are still unchecked and both gates still read `FAIL`. The owner's defect report is that
+ * `recursive_ask gate=run-start` raised the "start this run or hold?" gate while the document was in
+ * exactly that state — *"i was never shown the spec before that so how could i approve if i havent seen
+ * it"*. Approving an unfilled template is not a decision about a spec; there is no spec yet.
+ *
+ * So the QUESTION "is this document still the template?" must have ONE answer, and two consumers need it:
+ *
+ *   1. the SERVER gate (`recursive_ask`), which must REFUSE to raise the run-start question while the
+ *      answer is yes, and
+ *   2. the CLIENT sheet (`client/spec-sheet.tsx`), which must SAY SO plainly rather than dress a hollow
+ *      document up as an approvable one — the honesty rule of `client/settings-view.ts`, applied to a
+ *      document instead of a value.
+ *
+ * ⚠ THIS MODULE IS NODE-FREE ON PURPOSE. It is reached by both halves of the bundle, and the client bundle
+ * is a BROWSER closure: a `node:fs` import anywhere in its graph breaks the page. So the file reading stays
+ * in `run-start.ts` (which owns the artifact path) and this module takes TEXT and returns a VERDICT.
+ *
+ * ⚠ AND IT PINS THE TEMPLATE, NOT A COPY OF IT. The markers below are the literal lines
+ * `init-templates.ts::requirementsContent` writes. A checker that instead carried its own copy of the whole
+ * template would silently stop matching the moment the template changed; a checker that carried a CHECKSUM
+ * would call every edited document filled and every untouched one unfilled on the strength of a byte count.
+ * Naming the placeholder markers is the check that keeps meaning what it says.
+ */
+/** What the checker decided about one artifact's text. */
+export type ArtifactVerdict = 'unfilled' | 'filled';
+/** One piece of evidence found in the document, quoted with its line number. */
+export interface ArtifactMarkerHit {
+    /** Stable id of the marker that matched. */
+    id: string;
+    /** 1-based line number in the document as it was read. */
+    line: number;
+    /** The line verbatim, trimmed of surrounding whitespace. */
+    text: string;
+}
+/** The verdict plus the evidence for it. */
+export interface ArtifactVerdictResult {
+    verdict: ArtifactVerdict;
+    /** Marker hits, in line order. Empty exactly when the verdict is `filled`. */
+    hits: ArtifactMarkerHit[];
+}
+/** The named evidence classes, so a reader can tell a placeholder from an unmet gate. */
+export declare const ARTIFACT_MARKER_IDS: {
+    readonly placeholder: "placeholder";
+    readonly uncheckedTodo: "unchecked-todo";
+    readonly failedGate: "failed-gate";
+};
+export type ArtifactMarkerId = (typeof ARTIFACT_MARKER_IDS)[keyof typeof ARTIFACT_MARKER_IDS];
+/**
+ * Which marker a single line carries, or null.
+ *
+ * Exported because the client prints the marker NAMES beside the quoted lines, and a second classifier that
+ * re-derived them would be a second answer to the same question.
+ */
+export declare function markerIdsOnLine(line: string): ArtifactMarkerId[];
+/**
+ * Classify one artifact's text.
+ *
+ * A verdict of `unfilled` means the document still carries the template's own placeholder text — the
+ * evidence travels with it, line by line, so the refusal (and the client notice) can name what is missing
+ * instead of asserting a state the reader cannot check.
+ */
+export declare function classifyArtifact(text: string): ArtifactVerdictResult;
+/** The unfilled evidence only (what a refusal names). */
+export declare function unfilledEvidence(result: ArtifactVerdictResult): ArtifactMarkerHit[];
+/** The weak, contextual markers (unchecked boxes, FAIL gates). */
+export declare function contextEvidence(result: ArtifactVerdictResult): ArtifactMarkerHit[];
+/**
+ * One line naming what is missing, for a refusal sentence.
+ *
+ * The line number and the text are both quoted: "line 12: <short title>" is a thing a reader can go and
+ * look at, while "the requirements are not filled in" is an assertion they would have to take on trust.
+ */
+export declare function describeEvidence(hits: readonly ArtifactMarkerHit[], limit?: number): string;

package/lib/run-start.d.ts

@@ -53,3 +53,30 @@ export declare function readRunStartApproval(root: string, runId: string): {
  * the same string instead of re-typing it (a re-typed reason is a caller that silently stops matching).
  */
 export declare const RUN_START_NOT_APPROVED = "run not started: phase 0 approval has not been granted";
+/**
+ * PHASE 0 — THE GATE CANNOT BE RAISED BEFORE THERE IS A SPEC TO DECIDE ABOUT.
+ *
+ * THE DEFECT. `recursive_init` scaffolds Phase 0 as a TEMPLATE, and `recursive_ask gate=run-start` raised
+ * "start this run or hold?" over it immediately — while every requirement was still `<short title>`, every
+ * acceptance criterion was still `[observable condition 1]`, and nothing put the document in front of the
+ * person at all. The owner: *"the card ui for accepting the spec appeared, but i was never shown the spec
+ * before that so how could i approve if i havent seen it"*. Approving an unfilled template is not a decision
+ * about a spec; there is no spec yet, and a card that asks the question anyway teaches a person to answer
+ * without reading.
+ *
+ * ⚠ WHAT THIS DOES *NOT* TOUCH. It does not weaken the gate's own contract, it does not add a second way to
+ * start a run, and it does not make the plugin the decider: it only refuses to ASK. A person's own answer
+ * still wins (`recordRunStartAnswer` is unchanged), a spec still creates no goal, and cancellation / abort /
+ * timeout are still unrelayable. The check runs BEFORE the question is put to anybody, so no card is shown
+ * for a document that cannot be approved meaningfully.
+ *
+ * ⚠ AND IT IS A CHECK ON THE DOCUMENT, NOT ON THE CALLER. A `runId` that does not resolve is not this
+ * refusal's business — the ask path already reports that — so the guard says `ok: true` there and lets the
+ * existing route handle it.
+ */
+export declare function runStartSpecGuard(root: string, runId: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + 13 recursive_* tools (recursive_status, recursive_init, recursive_lock, recursive_lint, recursive_closeout, recursive_scratch, recursive_worktree, recursive_phase, recursive_audit_team, recursive_review, recursive_delegate, recursive_ask, recursive_preview)",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/client/contract.ts

@@ -62,6 +62,16 @@ export interface ClientSlots {
 /** A registered slot's options. */
 export interface SlotOptions {
   name: string
+  /**
+   * The dispatch key of a KEYED seat (`tool.call.toolview` is one), required there and ignored elsewhere.
+   *
+   * ⚠ THIS FIELD WAS MISSING AND ITS ABSENCE WAS NOT COSMETIC: `slots.ts` registers the run-start spec sheet
+   * on `tool.call.toolview` under the tool's wire name, and the harness's own options type makes `key`
+   * mandatory for a keyed slot (`KindOptions` in `packages/client/ui-slots`, where a keyed registration with
+   * no key THROWS `keyed slot "<name>" requires options.key`). Without the field here the face did not match
+   * the API it describes, so `tsc --noEmit` rejected the registration and the sheet was unreachable code.
+   */
+  key?: string
   id?: string
   order?: number
   label?: string

package/src/client/doc-viewer.tsx

@@ -25,6 +25,27 @@ export interface DocLine {
   text: string;
   /** table: data rows (header separator row dropped); first row is the header. */
   cells?: string[][];
+  /**
+   * li: the item WAS a `- [ ]` / `- [x]` task box, and whether it was ticked.
+   *
+   * ⚠ THIS IS A FIELD ON `li`, NOT A NEW KIND, ON PURPOSE. A task box is a list item — it keeps the bullet
+   * layout, the line index and the search behaviour every existing `li` has — and the ONE thing the reader
+   * must be able to see that a plain string cannot carry is the BOX ITSELF. The scaffolded Phase 0 template
+   * ships seven unticked boxes, so "is this still the template?" is partly a question about these marks.
+   *
+   * ⚠ AND THE BOX IS NOT LEFT IN `text`. `text` is the item's CONTENT, exactly the shape the base parser
+   * already produces for a plain bullet, so `search`/`copy` and every other consumer of a line's text see the
+   * words rather than the syntax. The tick survives as this field, and the renderer draws the mark back.
+   */
+  checked?: boolean;
+  /**
+   * plain: this line is a `Coverage:` / `Approval:` GATE reading, and how it reads.
+   *
+   * Same reasoning as `checked`: a gate line is a line of text, so it stays `plain` and gains the one fact
+   * the renderer cannot re-derive — whether it currently says PASS or FAIL, which is exactly what a person
+   * must be able to see before approving the document that contains it.
+   */
+  gate?: 'pass' | 'fail';
 }
 
 /** Inline segment parsed from line text (bold / code span / link). */
@@ -34,10 +55,33 @@ export interface InlineSegment {
   href?: string;
 }
 
+/**
+ * A list item: the text AFTER its marker. The marker is consumed here exactly as the base parser consumed
+ * it — `text` is the item's CONTENT, and the renderer draws the `- ` / box back from `kind` + `checked`.
+ */
+const BULLET_RE = /^\s*[-*]\s+(.+)$/;
+
+/**
+ * A task box (`[ ]`, `[x]`, `[X]`) at the front of a list item, split into its tick and the rest of the item.
+ *
+ * The tick is the one fact a reader of the document cannot recover from the text alone once the box has been
+ * recognised, so it travels as `checked`; everything after it is the item's content, as for any other bullet.
+ */
+const TASK_BOX_RE = /^\[([ xX])\]\s*(.*)$/;
+
+/** A gate reading: `Coverage: FAIL` / `Approval: PASS`, as `run-spec.ts` reads the same lines. */
+const GATE_RE = /^\s*(?:Coverage|Approval)\s*:\s*(PASS|FAIL)\s*$/i;
+
 /**
  * Markdown -> line tokens. Base is parsePlan (blank/h1-h4/li/plain, MIT),
  * extended for fenced code blocks (one code line per block) and pipe tables
  * (one table line per block, header separator row dropped).
+ *
+ * AND EXTENDED FOR WHAT THE RUN ARTIFACTS ACTUALLY CONTAIN — the task boxes and gate readings the
+ * scaffolded `00-requirements.md` ships (`- [ ] …`, `Coverage: FAIL`, `Approval: FAIL`), because a preview
+ * that renders an unticked box and a FAIL gate as generic body text hides the two marks a person who is
+ * being asked to approve the document most needs to see. Both are additive FIELDS on the existing `li` and
+ * `plain` kinds, so no line is retyped, no character is dropped, and every existing caller keeps working.
  */
 export function parseDoc(plan: string): DocLine[] {
   const raw = String(plan == null ? '' : plan).split('\n');
@@ -83,9 +127,21 @@ export function parseDoc(plan: string): DocLine[] {
       i += 1;
       continue;
     }
-    // list item
-    const li = /^\s*[-*]\s+(.+)$/.exec(line);
-    if (li) { out.push({ kind: 'li', text: li[1] }); i += 1; continue; }
+    // list item — a task box is CLASSIFIED (its tick kept as `checked`) and its text is the item's CONTENT,
+    // which is the shape the base parser already produces for a bullet. The marker and the box are DRAWN by
+    // the renderer from `kind` + `checked`, so no line is retyped and the reader still sees `- [ ] item`.
+    const item = BULLET_RE.exec(line);
+    if (item) {
+      const box = TASK_BOX_RE.exec(item[1]);
+      out.push(box === null
+        ? { kind: 'li', text: item[1] }
+        : { kind: 'li', text: box[2], checked: box[1] !== ' ' });
+      i += 1;
+      continue;
+    }
+    // gate reading: `Coverage: FAIL` / `Approval: PASS`
+    const gate = GATE_RE.exec(line);
+    if (gate) { out.push({ kind: 'plain', text: line, gate: gate[1].toUpperCase() === 'FAIL' ? 'fail' : 'pass' }); i += 1; continue; }
     out.push({ kind: 'plain', text: line });
     i += 1;
   }
@@ -137,12 +193,41 @@ function inlineNodes(segments: InlineSegment[], baseKey: string): ReactNode[] {
   });
 }
 
+/**
+ * The mark of a task box.
+ *
+ * ⚠ THE MARK REPLACES `[ ]` / `[x]` IN PLACE, GLYPH FOR GLYPH. The parser hands over the item's content
+ * without the box, so what the reader sees is `- [ ] item` where the document says `- [x] item`: same line,
+ * same position, same length of reading — and the box is still legible as a box rather than as an assertion
+ * about the item.
+ *
+ * ⚠ AND THE TICK IS CARRIED TWICE — once as that glyph for the eye and once as text, visually hidden, for the
+ * ear — because the two bracket forms are read inconsistently by screen readers, and the whole point of the
+ * mark is that "this box is not ticked" survives every way of reading it. This span carries NO separator of
+ * its own: the item's text follows it directly, separated by the leading space on that text (see
+ * `lineElement`), so that neither side of the boundary has a trailing space to lose.
+ */
+function todoMark(line: DocLine, key: string): ReactNode {
+  const done = line.checked === true;
+  const cls = 'rec-doc-todo-check' + (done ? ' rec-doc-todo-check-on' : ' rec-doc-todo-check-off');
+  return createElement('span', { key, className: cls, title: done ? 'done' : 'not done' },
+    createElement('span', { 'aria-hidden': 'true' }, done ? '[x]' : '[ ]'),
+    createElement('span', { className: 'rec-doc-sr' }, done ? 'done:' : 'not done:'),
+  );
+}
+
 /**
  * Render one parsed line as a React element. Headings/bullets get parsePlan
  * sizing; code/table get block layout; inline markup applies to plain-ish text.
+ *
+ * ⚠ ONE RENDERER, TWO READERS. `DocViewer` and the run-start spec sheet's preview both come through here,
+ * so a mark that means "unticked box" or "gate reads FAIL" cannot mean one thing in the phase-doc viewer and
+ * another in the document a person is approving. Exported for that reason alone.
  */
-function lineElement(line: DocLine, i: number, isCurrent: boolean): ReactNode {
+export function lineElement(line: DocLine, i: number, isCurrent = false): ReactNode {
   const cls = 'rec-doc-line rec-doc-' + line.kind + (isCurrent ? ' rec-doc-line-current' : '');
+  const gateCls = line.gate === undefined ? '' : ' rec-doc-gate rec-doc-gate-' + line.gate;
+  const todoCls = line.checked === undefined ? '' : ' rec-doc-todo' + (line.checked ? ' rec-doc-todo-done' : ' rec-doc-todo-open');
   if (line.kind === 'blank') return createElement('div', { key: i, 'data-line': String(i), className: cls }, null);
   if (line.kind === 'code') return createElement('pre', { key: i, 'data-line': String(i), className: cls + ' rec-doc-pre' }, createElement('code', { className: 'rec-doc-code' }, line.text));
   if (line.kind === 'table') {
@@ -157,8 +242,43 @@ function lineElement(line: DocLine, i: number, isCurrent: boolean): ReactNode {
     );
   }
   const nodes = inlineNodes(parseInline(line.text), String(i));
-  if (line.kind === 'li') return createElement('div', { key: i, 'data-line': String(i), className: cls }, createElement('span', { className: 'rec-doc-bullet' }, '•'), createElement('span', { className: 'rec-doc-li-text' }, nodes));
-  return createElement('div', { key: i, 'data-line': String(i), className: cls }, nodes);
+  // ⚠ THE PREVIEW LINE IS THE DOCUMENT'S OWN LINE. The parser keeps list content MARKER-FREE (the base
+  // parser's shape), so the renderer puts the marker back: `- ` for a bullet, and a drawn box IN PLACE OF
+  // the `[ ]` / `[x]` for a task box. That is what lets a reader check the preview against the source and
+  // see at a glance that an unticked box is unticked.
+  //
+  // ⚠ AND THE SEPARATOR IS A NON-BREAKING SPACE WRITTEN AS AN ESCAPE, ON THE ITEM'S SIDE OF THE MARK.
+  // Measured, twice: a text node that ENDS in a space loses it (so a `'- '` bullet glyph renders as `-`,
+  // and a minifier carries that through to the shipped bundle, turning every bullet into `-item`), and a
+  // plain leading space is normalised away by the JSX transform before React ever sees it. An ESCAPED
+  // non-breaking space is neither trailing nor transformable, so it is what these separators are.
+  const SPACER = '\u00A0';
+  if (line.kind === 'li' && line.checked !== undefined) {
+    return createElement('div', { key: i, 'data-line': String(i), className: cls + todoCls },
+      createElement('span', { className: 'rec-doc-bullet' }, '-'),
+      todoMark(line, 'todo-' + String(i)),
+      createElement('span', { className: 'rec-doc-li-text' }, SPACER, nodes));
+  }
+  if (line.kind === 'li') return createElement('div', { key: i, 'data-line': String(i), className: cls }, createElement('span', { className: 'rec-doc-bullet' }, '-'), createElement('span', { className: 'rec-doc-li-text' }, SPACER, nodes));
+  return createElement('div', { key: i, 'data-line': String(i), className: cls + gateCls }, nodes);
+}
+
+/**
+ * The parsed lines as elements — the preview built from `parseDoc` + `lineElement`, with no shell of its own.
+ *
+ * ⚠ THIS IS WHAT MAKES A SECOND RENDERER UNNECESSARY. Any surface that wants to show a run artifact as a
+ * PREVIEW (the phase-doc viewer's body, the run-start spec sheet's document body) renders these nodes inside
+ * whatever frame it owns, so the markdown is parsed and drawn exactly once in the plugin. `keyBase` namespaces
+ * the React keys when several of these are on screen at once; `current` is the vim cursor line, which the
+ * spec sheet never sets.
+ */
+export function PreviewLines({ lines, keyBase = 'doc', current = -1 }: { lines: DocLine[]; keyBase?: string; current?: number }): ReactNode {
+  return createElement('div', { className: 'rec-doc-lines', 'data-preview-lines': String(lines.length) },
+    ...lines.map((line, i) => createElement(
+      'div',
+      { key: keyBase + '-line-' + String(i), className: 'rec-doc-line-wrap' },
+      lineElement(line, i, i === current),
+    )));
 }
 
 /**
@@ -269,11 +389,10 @@ export function DocViewer({ runId, worktreeRoot, fileName, theme, onClose }: Doc
     }
   };
 
-  const matchSet = new Set(matches);
-  const activeLine = matches.length > 0 ? matches[activeMatch] : -1;
-
-  const lineEls = docLines.map((line, i) => lineElement(line, i, i === cursor));
-
+  // NOTE: `n`/`N` move the cursor to the matching line, which is marked `rec-doc-line-current` by
+  // `PreviewLines` below. The lines themselves are NOT individually match-highlighted — they were not
+  // before this file gained a shared preview renderer either, and inventing a highlight here would change
+  // how the phase-doc viewer draws a document as a side effect of the run-start spec sheet's work.
   const searchBar = searchOpen ? createElement('div', { className: 'rec-doc-search' },
     createElement('input', { className: 'rec-doc-search-input', value: query, placeholder: '/ search doc…', onChange: onSearchChange, onKeyDown: onSearchKey }),
     createElement('span', { className: 'rec-doc-search-count' }, matches.length > 0 ? (activeMatch + 1) + '/' + matches.length : (query ? '0' : '')),
@@ -296,7 +415,7 @@ export function DocViewer({ runId, worktreeRoot, fileName, theme, onClose }: Doc
     createElement('div', { className: 'rec-doc-body' },
       text === null && error === null ? createElement('p', { className: 'rec-doc-text' }, 'Loading doc…') : null,
       error !== null ? createElement('p', { className: 'rec-doc-text rec-doc-error' }, error) : null,
-      text !== null ? lineEls : null,
+      text !== null ? createElement(PreviewLines, { lines: docLines, keyBase: 'doc', current: cursor }) : null,
     ),
     createElement('footer', { className: 'rec-doc-footer' },
       createElement('div', { className: statusCls, role: 'status' }, statusText),

package/src/client/slots.ts

@@ -22,6 +22,7 @@ import { isRecursivePreset, currentWorkspacePath } from './contract.ts'
 import { Board } from './board.tsx'
 import { Inspector } from './inspector.tsx'
 import { RecursiveSettings, RecursiveSettingsLive, type RecursiveSettingsSeatProps } from './settings.tsx'
+import { RunStartSpecSheet, RUN_START_TOOL_NAME } from './spec-sheet.tsx'
 import { useLiveProjection } from './use-live.ts'
 import { boardState, useBoardState } from './open-state.ts'
 import { injectBoardStyles } from './styles.ts'
@@ -138,6 +139,17 @@ export function registerSlots(ctx: ClientContext): () => void {
     return createElement(RecursiveBoardOverlay, { useSessions, useWorkspaces: props?.useWorkspaces })
   })))
 
+  // RUN-START SPEC SHEET (tool.call.toolview, keyed by tool name). The seat that exists exactly while a
+  // `recursive_ask` call is on screen — and the only one that can render BESIDE the question card, because
+  // the composer is a chain and the run-start gate's pending interaction is a question, not an approval (see
+  // the header of spec-sheet.tsx for the three structural reasons `conversation.approval.detail` cannot be
+  // it). The view returns null for every other gate, so `tdd-mode` / `qa-signoff` / `gate-block` calls keep
+  // the generic tool row they have today.
+  disposers.push(ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
+    name: 'tool.call.toolview',
+    key: RUN_START_TOOL_NAME,
+  }, RunStartSpecSheet)))
+
   // Settings section (root scope, always present; no gate — configuration is always available).
   // The seat receives the shell's `close` PLUS the root standard kit (useSessions/useWorkspaces,
   // scoped-slots standardProps), so the panel can subscribe to the SAME live route the board