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

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/delegation.ts

@@ -559,9 +559,18 @@ export async function delegateContinuable(input: {
         // turn-shaped caller resumes on a later turn instead of treating the round
         // as lost, and so `accepted` stays false — an unobserved round is never an
         // approval.
+        //
+        // ⚠ THE SENTENCE NAMES THE CHILD, and that is not decoration. The advice this
+        // reason carries ("resume with the SAME child") is UNACTIONABLE without the id,
+        // so a caller that reads it and does not also read `childId` can only report the
+        // park, not act on it — and the record built from this reason is exactly where a
+        // live run read "no settlement" as "the child is dead" and went around its own
+        // reviewer. `resumeChild` is the field that consumes this id.
         return {
           ok: false,
-          reason: 'no settlement has landed for round ' + (round + 1) + ' yet (the child is still working)',
+          reason: 'no settlement has landed for round ' + (round + 1) + ' yet, so the round is PARKED, not failed: '
+            + 'the child may still be working. Resume it on a later turn with childId ' + String(childId)
+            + ' (the `resumeChild` argument) — do not start a second child.',
           childId,
           messageIds,
           rounds,
@@ -774,8 +783,43 @@ export interface ActionRecordInput {
    * nothing else: a delegation that FAILED and a delegation that NEVER HAPPENED read identically, which is what
    * let me conclude for three rounds that the host was not scheduling children. The caller ALREADY passed
    * `stopReason`, and the live record said `n/a` — because there was no result to take a stop reason from.
+   *
+   * ⚠ AND IT IS EMITTED ONLY FOR A GENUINE FAILURE. A PARKED round is neither accepted nor failed, so it
+   * carries {@link ActionRecordInput.parked} instead: calling a live child a failure is the defect this
+   * field's own history is made of.
    */
   failure?: string
+  /**
+   * ⚠ THE THIRD STATE, AND WHY `success` COULD NOT CARRY IT.
+   *
+   * A continuable round that has not settled is NOT a failure — `ContinuableDelegationLike.parked` says so in
+   * its own doc comment, and the tool result already surfaces it. The RECORD did not: a live run's child was
+   * parked, the record said `Status: failed` with "the child never reported, or never ran", the main agent
+   * read that as a dead child and obtained the review elsewhere — while the child was still working and
+   * replied eighteen minutes later. `success: false` cannot express "still in flight", because a genuinely
+   * dead child also produces `success: false`, so a second field is required rather than a cleverer boolean.
+   *
+   * When true, the record says `parked` and carries a `Parked:` line (never a `Failure:` line) whose text
+   * states only what is KNOWN, names the `childId`, and names the resume step. It takes precedence over
+   * `success`: an unobserved round is never an acceptance, whatever a caller passes alongside it.
+   */
+  parked?: boolean
+}
+
+/**
+ * The status a record states, in ONE place, because the three states are the fix and a second writer would
+ * drift from this one.
+ *
+ * The wording is chosen for two readers at once. The MODEL reads it to decide whether to resume or to give up
+ * and obtain the result another way — the exact decision the live defect got wrong — so the token must not
+ * read as a failure and must not need the rest of the document to be understood. A HUMAN reading the run tree
+ * months later needs to tell "died" from "still working" at a glance. Hence `parked (still running; no
+ * settlement yet)`: a third token rather than a renamed second, qualified with the two facts that separate it
+ * from `failed`, and short enough to sit in a status line.
+ */
+export function actionRecordStatus(input: Pick<ActionRecordInput, 'success' | 'parked'>): string {
+  if (input.parked === true) return 'parked (still running; no settlement yet)'
+  return input.success ? 'accepted' : 'failed'
 }
 
 function slugify(value: string): string {
@@ -794,7 +838,10 @@ function slugify(value: string): string {
  *     `Code Refs` strictly inside ## Inputs Provided. The linter resolves each of
  *     those through the heading body, so a field under another heading is not
  *     found at all.
- * A success:false attempt is written with a failed status and is NOT accepted.
+ * A success:false attempt is written with a failed status and is NOT accepted. A round that PARKED is written
+ * with a status of its own (`parked (still running; no settlement yet)`, see {@link actionRecordStatus}) and a
+ * `Parked:` line instead of a `Failure:` one, because no settlement is not a death: it is the caller's signal to
+ * resume the same child. Only a genuine failure carries `Failure:`.
  */
 export function writeActionRecord(input: ActionRecordInput): string {
   const { root, runId } = input
@@ -844,11 +891,18 @@ export function writeActionRecord(input: ActionRecordInput): string {
     '- Phase: ' + input.phase,
     '- Purpose: ' + input.purpose,
     '- Execution Mode: ' + input.executionMode,
-    '- Status: ' + (input.success ? 'accepted' : 'failed'),
+    '- Status: ' + actionRecordStatus(input),
     // ⚠ EMITTED ONLY WHEN A REASON IS GIVEN, so a caller that says nothing produces the record it always did.
     // Not politeness: this record's shape is asserted by specs, and a first attempt that always emitted the line
     // failed 13 tests across 5 files. A change to a shared surface should be additive where it can be.
-    ...(input.success === false && input.failure !== undefined ? ['- Failure: ' + input.failure] : []),
+    //
+    // ⚠ AND `parked` IS THE ONE STATE THAT MUST NOT WEAR THE `Failure:` LABEL. This line used to be
+    // `input.success === false && input.failure !== undefined`, which is true of a PARKED round as well — so a
+    // live child that was still working was recorded, on the same line, as a failure. A parked round is not a
+    // failure, so it gets its own field and states only what is established.
+    ...(input.success === false && input.failure !== undefined
+      ? [input.parked === true ? '- Parked: ' + input.failure : '- Failure: ' + input.failure]
+      : []),
     '- Stop Reason: ' + (input.stopReason ?? 'n/a'),
     // Timestamp LAST in Metadata. This USED to be load-bearing: `getHeadingBody` ended
     // its capture with a `\Z` that JavaScript reads as a literal `Z`, so a body was

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
+}