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

package/src/client/styles.ts

@@ -14,7 +14,7 @@ const BOARD_CSS = `
 /* ===== dsh-recursive Paper theme (run 16) ===== */
 
 /* Raw tokens: light (default) + dark + shared, scoped to the board/inspector. */
-.rec-board, .rec-inspector {
+.rec-board, .rec-inspector, .rec-spec {
   /* light */
   --rm3-light-background: #FFFFFF;
   --rm3-light-foreground: #111111;
@@ -673,6 +673,9 @@ const BOARD_CSS = `
   line-height: 1.7;
   padding: 0 6px;
   border-left: 2px solid transparent;
+  /* Containing block for the visually-hidden text that carries a task box's tick to a screen reader, so it
+     cannot be positioned against the page instead of against its own line. */
+  position: relative;
 }
 
 .rec-doc-line-current {
@@ -1097,8 +1100,302 @@ dl.rec-settings-rows {
   overflow-wrap: anywhere;
 }
 
+/* ===== Run-start spec sheet (tool.call.toolview key 'recursive_ask') =====
+   The document beside the run-start question. LIGHT is the only theme here: the sheet renders inline in a
+   transcript row, not on the board, so it does not own a data-theme attribute and must not inherit the
+   board's. The body is the ONLY scrolling box (a max-height cap with overflow-y: auto) so the decision
+   controls below it can never be pushed out of reach by a long document. */
+.rec-spec {
+  box-sizing: border-box;
+  margin: 6px 0;
+  padding: var(--board-space-12);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-lg);
+  background: var(--board-card);
+  color: var(--board-fg);
+  font-family: var(--board-font-sans);
+  font-size: var(--board-text-sm);
+  /* The one transition this sheet has. It is disabled outright under prefers-reduced-motion below. */
+  transition: border-color 160ms ease;
+}
+
+.rec-spec-header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--board-space-8);
+}
+
+.rec-spec-title {
+  margin: 0;
+  font-size: var(--board-text-sm);
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: var(--board-tracking-tight);
+  overflow-wrap: anywhere;
+}
+
+.rec-spec-tag {
+  flex: none;
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+}
+
+.rec-spec-path {
+  margin: 2px 0 var(--board-space-8);
+  font-family: var(--board-font-mono);
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  overflow-wrap: anywhere;
+}
+
+.rec-spec-notice {
+  margin: 0 0 var(--board-space-8);
+  padding: var(--board-space-8);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  background: var(--board-muted);
+  font-size: var(--board-text-xs);
+  line-height: 1.5;
+}
+
+/* An UNFILLED template is stated as a warning, never as a neutral fact: the whole point of this seat is that
+   nobody is nudged toward approving a hollow document. */
+.rec-spec-notice-unfilled {
+  border-color: var(--board-warning);
+  background: color-mix(in srgb, var(--board-warning) 10%, var(--board-card));
+}
+
+.rec-spec-unfilled-lead {
+  margin: 0 0 6px;
+  font-weight: var(--board-fw-semibold);
+  color: var(--board-warning);
+}
+
+.rec-spec-unfilled-why {
+  margin: 0 0 4px;
+  color: var(--board-muted-fg);
+}
+
+.rec-spec-unfilled-next {
+  margin: 6px 0 0;
+  font-weight: var(--board-fw-medium);
+}
+
+.rec-spec-evidence {
+  margin: 0 0 4px;
+  padding-left: 18px;
+  font-family: var(--board-font-mono);
+  font-size: var(--board-text-xs);
+}
+
+.rec-spec-evidence-item {
+  overflow-wrap: anywhere;
+}
+
+.rec-spec-notice-filled {
+  border-color: var(--board-success);
+  background: color-mix(in srgb, var(--board-success) 8%, var(--board-card));
+}
+
+.rec-spec-notice-error {
+  border-color: var(--board-error);
+}
+
+.rec-spec-question {
+  margin: 0 0 var(--board-space-8);
+}
+
+.rec-spec-question-lead,
+.rec-spec-question-options,
+.rec-spec-question-where {
+  margin: 0 0 4px;
+  font-size: var(--board-text-xs);
+  line-height: 1.5;
+}
+
+.rec-spec-question-where {
+  color: var(--board-muted-fg);
+}
+
+.rec-spec-decision {
+  margin: 0;
+  font-size: var(--board-text-xs);
+  font-weight: var(--board-fw-medium);
+}
+
+/* The document body: the one bounded scroller. Focusable (tabIndex=0) for the keyboard, and the border
+   marks the focus ring's home rather than relying on a colour change alone. */
+.rec-spec-body-scroll {
+  max-height: 420px;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  background: var(--board-muted);
+}
+
+.rec-spec-body-scroll:focus-visible {
+  outline: 2px solid var(--board-info);
+  outline-offset: 2px;
+}
+
+/* The rendered preview inside that scroller (PreviewLines from doc-viewer.tsx). The line blocks carry their
+   own padding so the marks — task boxes, gate readings — line up in a column down the left edge. */
+.rec-spec-body-scroll .rec-doc-lines {
+  padding: var(--board-space-12);
+}
+
+.rec-spec-body-scroll .rec-doc-line {
+  padding: 0;
+}
+
+/* Raw source is monospace, wrapping, and NOT reflowed: the same characters the preview was built from. */
+.rec-spec-text {
+  margin: 0;
+  padding: var(--board-space-12);
+  font-family: var(--board-font-mono);
+  font-size: var(--board-text-xs);
+  line-height: 1.55;
+  /* The document is shown VERBATIM: only wrapping is normalised, never the characters. */
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  tab-size: 2;
+}
+
+/* ===== The mode control (preview <-> raw source) =====
+   One real button, so Tab reaches it and Enter/Space press it; aria-pressed carries its state to a screen
+   reader and the role=status line beside it names the mode on screen in words. */
+.rec-spec-view {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--board-space-8);
+  margin: 0 0 var(--board-space-8);
+}
+
+.rec-spec-view-toggle {
+  flex: none;
+  padding: 4px 12px;
+  font-family: inherit;
+  font-size: var(--board-text-xs);
+  color: var(--board-fg);
+  background: var(--board-card);
+  border: 1px solid var(--board-border);
+  border-radius: 999px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.rec-spec-view-toggle:hover {
+  background: var(--board-accent);
+}
+
+.rec-spec-view-toggle:focus-visible {
+  outline: 2px solid var(--board-info);
+  outline-offset: 2px;
+}
+
+/* A pressed toggle says "the verbatim source is what you are reading" — marked, and not by colour alone. */
+.rec-spec-view-toggle[aria-pressed='true'] {
+  border-color: var(--board-info);
+  color: var(--board-info);
+  font-weight: var(--board-fw-semibold);
+}
+
+.rec-spec-view-toggle[aria-disabled='true'] {
+  opacity: 0.55;
+  cursor: default;
+}
+
+.rec-spec-view-state {
+  flex: 1 1 auto;
+  min-width: 0;
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  overflow-wrap: anywhere;
+}
+
+/* ===== Marks the PREVIEW must not hide (shared with the phase-doc viewer) =====
+   The scaffolded Phase 0 template ships unticked boxes and two FAIL gates; a preview that drew them as
+   generic body text would make an unfilled form look like a finished spec. */
+.rec-doc-sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+
+.rec-doc-todo {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+}
+
+.rec-doc-todo-check {
+  flex: none;
+  font-family: var(--board-font-mono);
+  font-size: 12.5px;
+  line-height: 1.7;
+  letter-spacing: var(--board-tracking-mono);
+}
+
+.rec-doc-todo-check-off {
+  color: var(--board-warning);
+  font-weight: var(--board-fw-semibold);
+}
+
+.rec-doc-todo-check-on {
+  color: var(--board-success);
+}
+
+/* An unticked box is stated, not merely greyed: the warning colour AND the mark together. */
+.rec-doc-todo-open .rec-doc-li-text {
+  color: var(--board-fg);
+}
+
+.rec-doc-todo-done .rec-doc-li-text {
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-gate {
+  font-family: var(--board-font-mono);
+  font-size: var(--board-text-xs);
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: var(--board-tracking-mono);
+  margin: 4px 0;
+  padding: 3px 8px;
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  display: inline-block;
+}
+
+.rec-doc-gate-fail {
+  color: var(--board-error);
+  border-color: var(--board-error);
+  background: color-mix(in srgb, var(--board-error) 8%, var(--board-card));
+}
+
+.rec-doc-gate-pass {
+  color: var(--board-success);
+  border-color: var(--board-success);
+  background: color-mix(in srgb, var(--board-success) 8%, var(--board-card));
+}
+
+.rec-spec-empty {
+  margin: 0;
+  padding: var(--board-space-12);
+  color: var(--board-muted-fg);
+  font-size: var(--board-text-xs);
+}
+
 @media (prefers-reduced-motion: reduce) {
   .rec-card, .rec-back, .rec-close, .rec-theme-toggle { transition: none; }
+  .rec-spec { transition: none; }
 }
 `
 

package/src/client/use-live.ts

@@ -23,15 +23,34 @@ function isEmpty(scope: LiveScope): boolean {
   return !scope.sessionId && !scope.cwd
 }
 
+/** Options for {@link useLiveProjection}. */
+export interface LiveProjectionOptions {
+  /**
+   * Skip the route entirely (default true).
+   *
+   * ⚠ THIS EXISTS FOR THE PER-CALL SEATS, NOT THE PANELS. A `tool.call.toolview` entry mounts once per Tool
+   * call in the transcript, so a seat that always subscribed would open one `/state` fetch and one SSE
+   * stream per call row. A row that has nothing to show passes `enabled: false` and asks nothing. The hook
+   * itself stays UNCONDITIONAL at every call site — a conditional hook is the run 13 crash, and the flag is
+   * how a caller keeps the call order fixed while making the request conditional.
+   */
+  enabled?: boolean
+}
+
 /**
  * Subscribe to the live route for one scope. Returns the current state. The SSE
  * feed pushes full frames on every fs change; a dropped stream (sleep/error)
  * triggers one refetch so the board never serves a stale fold.
+ *
+ * @param scope - sessionId PRIMARY + cwd fallback hint (host resolves the root).
+ * @param options - `enabled: false` clears the snapshot and never fetches.
  */
-export function useLiveProjection(scope: LiveScope): LiveProjectionSnapshot {
+export function useLiveProjection(scope: LiveScope, options: LiveProjectionOptions = {}): LiveProjectionSnapshot {
+  const { enabled = true } = options
   const [state, setState] = useState<LiveRecursiveState | null>(null)
 
   useEffect(() => {
+    if (!enabled) { setState(null); return }
     // Empty scope = no resolvable session row yet — render nothing, never fetch.
     if (isEmpty(scope)) { setState(null); return }
     // 0.1.18 (LIVE BUG 5): do NOT null the snapshot on scope change. 0.1.16
@@ -51,7 +70,9 @@ export function useLiveProjection(scope: LiveScope): LiveProjectionSnapshot {
     })
 
     return () => { disposed = true; disposeEvents() }
-  }, [scope.sessionId, scope.cwd])
+    // `enabled` belongs in the deps: it is read inside the effect, so leaving it out would keep a stale
+    // closure's verdict and mount the very stream the flag exists to avoid.
+  }, [scope.sessionId, scope.cwd, enabled])
 
   return state
 }

package/src/errors.ts

@@ -162,6 +162,19 @@ export 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',
+  },
 
   /* 5xxx — the runtime refused an operation it understands. */
 

package/src/recursive_ask.tool.ts

@@ -27,6 +27,7 @@ import {
   RUN_START_ARTIFACT,
   RUN_START_GATE,
   RUN_START_GATE_ID,
+  runStartSpecGuard,
 } from './run-start.ts'
 
 
@@ -294,7 +295,7 @@ export function pendingGateFor(artifactFile: string, artifactText: string | null
 export function createRecursiveAskTool(recursive: RecursiveRuntime) {
   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', description: 'tdd-mode | qa-signoff | gate-block | run-start. Required. `run-start` is phase 0: approving it records the approval and arms the run goal, which is what makes the harness drive rounds.' },
       runId: { type: 'string', description: 'Run id. Required; must resolve inside the current workspace.' },
@@ -326,6 +327,32 @@ export function createRecursiveAskTool(recursive: RecursiveRuntime) {
       // phase-0 record, and letting a caller aim the approval somewhere else is how an approval ends up
       // in a file no reader looks at. Every other gate keeps its per-gate default and its override.
       const artifact = (isRunStartGate(gateId) ? RUN_START_ARTIFACT : args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId as AskGateId]).trim()
+
+      // ⚠ THE ORDERING GUARD, AND IT COMES BEFORE THE QUESTION IS PUT TO ANYBODY. A scaffolded run's Phase 0
+      // document is a template: placeholder requirements, unchecked lists, FAIL gates. Raising "start this run
+      // or hold?" over that asks a person to approve a document that is not a spec — and until this change
+      // nothing even SHOWED it to them. So the gate refuses while the artifact is still the template, naming
+      // the artifact and quoting the placeholder lines, and records nothing.
+      //
+      // It runs before BOTH branches below on purpose: asking the channel first and refusing afterwards would
+      // put the card in front of the person anyway, which is the defect. A refusal here does not weaken any
+      // part of the gate's contract — the person's own answer still wins everywhere below, a spec still
+      // creates no goal, and the relay rules are untouched.
+      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,
+            // The question travels with the refusal so the caller can put the DECISION in the transcript while
+            // it cannot yet raise the card — the same shape the channel refusals use.
+            question: buildAskQuestionFor(RUN_START_GATE_ID),
+          } as unknown as JsonValue
+        }
+      }
+
       let question: AskQuestion
       try {
         question = buildAskQuestionFor(gateId)

package/src/run-spec.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 const ARTIFACT_MARKER_IDS = {
+  placeholder: 'placeholder',
+  uncheckedTodo: 'unchecked-todo',
+  failedGate: 'failed-gate',
+} as const
+
+export type ArtifactMarkerId = (typeof ARTIFACT_MARKER_IDS)[keyof typeof ARTIFACT_MARKER_IDS]
+
+/**
+ * `...` on a line of its own, or a bracketed/angle placeholder.
+ *
+ * The bracketed form is deliberately `<[^<>\n]+>` rather than `<.+>`: a greedy pattern would swallow a
+ * legitimate line that happens to contain two unrelated angle brackets, and the refusal it produced would
+ * name a line the person could not see a placeholder in.
+ */
+const PLACEHOLDER_RE = /(^\s*\.\.\.\s*$)|(\[[^[\]\n<>]{2,120}\])|(<[^<>\n]{2,120}>)/
+
+/** An unchecked task box: the template ships five of them and a filled spec has none in the TODO block. */
+const UNCHECKED_TODO_RE = /^\s*[-*]\s*\[ \]/
+
+/** The two FAIL gates the template ships (`Coverage: FAIL` / `Approval: FAIL`). */
+const FAILED_GATE_RE = /^\s*(Coverage|Approval):\s*FAIL\b/i
+
+/** Every marker, in the order they are reported for a single line. */
+const MARKER_PATTERNS: readonly { id: ArtifactMarkerId; re: RegExp }[] = [
+  { id: ARTIFACT_MARKER_IDS.placeholder, re: PLACEHOLDER_RE },
+  { id: ARTIFACT_MARKER_IDS.uncheckedTodo, re: UNCHECKED_TODO_RE },
+  { id: ARTIFACT_MARKER_IDS.failedGate, re: FAILED_GATE_RE },
+]
+
+/**
+ * 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 function markerIdsOnLine(line: string): ArtifactMarkerId[] {
+  const ids: ArtifactMarkerId[] = []
+  for (const pattern of MARKER_PATTERNS) {
+    if (pattern.re.test(line)) ids.push(pattern.id)
+  }
+  return ids
+}
+
+/**
+ * Does this line still carry a marker that PROVES the document is an unfilled template?
+ *
+ * ⚠ THE EVIDENCE IS NOT SYMMETRIC, and that asymmetry is the whole design. An angle-bracket placeholder or
+ * `[observable condition 1]` cannot appear in a document somebody actually wrote, so it REFUTES the spec's
+ * readiness. An unchecked box or a `FAIL` gate is weaker: a person may legitimately hold `Coverage: FAIL`
+ * open as an objection while still having written real requirements. So the strong markers decide, the weak
+ * ones are reported as context, and a real document is never refused on their account.
+ */
+function refutes(line: string): boolean {
+  return markerIdsOnLine(line).includes(ARTIFACT_MARKER_IDS.placeholder)
+}
+
+/**
+ * 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 function classifyArtifact(text: string): ArtifactVerdictResult {
+  const lines = text.split(/\r?\n/)
+  const hits: ArtifactMarkerHit[] = []
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] as string
+    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). */
+export function unfilledEvidence(result: ArtifactVerdictResult): ArtifactMarkerHit[] {
+  return result.hits.filter((hit) => hit.id === ARTIFACT_MARKER_IDS.placeholder)
+}
+
+/** The weak, contextual markers (unchecked boxes, FAIL gates). */
+export function contextEvidence(result: ArtifactVerdictResult): ArtifactMarkerHit[] {
+  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.
+ */
+export function describeEvidence(hits: readonly ArtifactMarkerHit[], limit = 3): string {
+  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
+}

package/src/run-start.ts

@@ -42,6 +42,8 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { getMdFieldValue } from './status.ts'
+import { classifyArtifact, describeEvidence, unfilledEvidence } from './run-spec.ts'
+import { toolError } from './errors.ts'
 
 /** The gate id `recursive_ask` answers for a run start. Deliberately NOT in ASK_GATE_IDS. */
 export const RUN_START_GATE_ID = 'run-start'
@@ -127,3 +129,60 @@ export function readRunStartApproval(root: string, runId: string): { approved: b
  * the same string instead of re-typing it (a re-typed reason is a caller that silently stops matching).
  */
 export const RUN_START_NOT_APPROVED = 'run not started: phase 0 approval has not been granted'
+
+/* ============================ THE ORDERING GUARD ============================ */
+
+/**
+ * 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 function runStartSpecGuard(root: string, runId: string): { ok: true } | { ok: false; reason: string } {
+  const content = readRunStartArtifact(root, runId)
+  if (content === null) {
+    // ⚠ A MISSING ARTIFACT IS REFUSED TOO, AND IT IS THE SAME DEFECT. Approving a run that has no Phase 0
+    // document is approving something nobody can read — the gate's own question ("approve phase 0 and start
+    // this run?") has no referent. The refusal names the path a reader can go and look at.
+    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) + ')'
+  // The evidence — line numbers and the placeholder text VERBATIM — travels in the detail: a refusal that
+  // asserts "it is a template" without quoting it is a refusal the caller can only take on trust.
+  return {
+    ok: false,
+    reason: toolError(
+      'RUN_START_SPEC_UNFILLED',
+      RUN_START_ARTIFACT + ' for run ' + JSON.stringify(runId) + ' still carries the template scaffold'
+      + contextNote + ': ' + describeEvidence(evidence),
+    ),
+  }
+}