@try-works/dsh-recursive-mode 0.4.3 → 0.4.5

package/src/policy-globs.ts

@@ -419,14 +419,36 @@ function lockOrderRule(artifact: unknown, runDir: string | undefined): ToolPolic
 /**
  * Locked-artifact write rule: a denial when the target carries
  * `Status: LOCKED`, `null` otherwise. Only a run-tree `*.md` is a candidate —
- * the same admission test the pre-T16 branch used.
+ * the same admission test the pre-T16 branch used, now asked of the RESOLVED
+ * path as well (see the ADMISSION note below).
+ *
+ * A caller with no `worktreeRoot` still gets `null` for every target, absolute
+ * ones included: that is the pre-existing behaviour and it is left alone here —
+ * the guard always carries a root, so nothing that reaches it changes.
  */
 function lockedWriteRule(target: string | null, worktreeRoot: string | undefined): ToolPolicyPredicateMatch | null {
   if (!target || !worktreeRoot) return null
   const normalized = target.replace(/\\/g, '/')
-  if (!normalized.endsWith('.md') || !normalized.includes('/.recursive/run/')) return null
+  if (!normalized.endsWith('.md')) return null
   const abs = resolveFrom(worktreeRoot, normalized)
-  if (!abs || getLockStatus(abs) !== 'LOCKED') return null
+  if (!abs) return null
+  // ADMISSION — a target is a candidate when it NAMES the run tree, and the marker is
+  // looked for on the path the target RESOLVES to as well as on the string as written.
+  //
+  // The string test alone requires a separator BEFORE `.recursive`, so it admitted an
+  // ABSOLUTE target and missed a REPO-RELATIVE one (`.recursive/run/<id>/00-requirements.md`,
+  // the form a model actually types, and its backslash spelling too). The rule then
+  // ABSTAINED, the phase baseline saw a write INSIDE the run tree — allowed by design — and
+  // the catch-all allowed a write to an artifact whose `Status:` is LOCKED. The resolved test
+  // is the fix, and it is the same question asked of the path the string names; `getLockStatus`
+  // below already used `abs`, so the two halves of this rule now agree on one path.
+  //
+  // The string test is KEPT rather than replaced, so that no absolute spelling denied today
+  // becomes allowed: a literal target that carries the marker but resolves away from it
+  // (`…/.recursive/run/../…`) is still admitted, exactly as before.
+  const resolved = abs.replace(/\\/g, '/')
+  if (!normalized.includes('/.recursive/run/') && !resolved.includes('/.recursive/run/')) return null
+  if (getLockStatus(abs) !== 'LOCKED') return null
   return { verdict: 'deny', detail: normalized + ' carries Status: LOCKED (reopen explicitly to edit)' }
 }
 

package/src/policy-write.ts

@@ -18,7 +18,7 @@
  *    present-but-empty value would stop the deferral and pin the choice to nothing, which is a different state
  *    from "unconfigured" and not one a user can see. Absence is the honest representation of "I have no opinion".
  *
- * 3. **WRITE ATOMICALLY.** A temp file and a rename, the same pattern the preset installer uses. A policy file
+ * 3. **WRITE ATOMICALLY.** A temp file and a rename, the same pattern the preset installer used, before it was retired. A policy file
  *    half-written because a process died mid-write would make `loadRouterPolicy` fall back to the built-in
  *    self-audit policy — and it does that SILENTLY, on purpose (it never throws). So a torn write here would look
  *    exactly like "the user configured nothing", for every role, until someone read the file.

package/src/recursive_ask.tool.ts

@@ -22,12 +22,44 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 import { toolError } from './errors.ts'
+import {
+  RUN_START_APPROVE,
+  RUN_START_ARTIFACT,
+  RUN_START_GATE,
+  RUN_START_GATE_ID,
+} from './run-start.ts'
 
 
 /** The identifiers the workflow uses for its three human gates. */
 export const ASK_GATE_IDS = ['tdd-mode', 'qa-signoff', 'gate-block'] as const
 export type AskGateId = (typeof ASK_GATE_IDS)[number]
 
+/**
+ * PHASE 0 — THE FOURTH GATE, AND WHY IT IS NOT IN `ASK_GATE_IDS`.
+ *
+ * The three above are the WORKFLOW's gates, and their membership is asserted as exactly those three.
+ * Starting a run is a different kind of decision — it decides whether there is a run at all, and
+ * approving it ARMS A GOAL the harness will keep driving — so its data lives in `run-start.ts` with its
+ * own contract and its own options. Widening the workflow's gate list must not silently widen what may
+ * start a run.
+ */
+export type AskAnyGateId = AskGateId | typeof RUN_START_GATE_ID
+
+/** Is this gate id the run-start gate? */
+export function isRunStartGate(gateId: string): boolean {
+  return gateId === RUN_START_GATE_ID
+}
+
+/** Every gate id `recursive_ask` accepts, workflow gates first. */
+export function askGateIds(): string[] {
+  return [...ASK_GATE_IDS, RUN_START_GATE_ID]
+}
+
+/** The artifact a gate's answer belongs in — the run-start gate's is fixed to the Phase 0 requirements. */
+export function askGateArtifact(gateId: AskAnyGateId): string {
+  return isRunStartGate(gateId) ? RUN_START_ARTIFACT : GATE_DEFAULT_ARTIFACT[gateId as AskGateId]
+}
+
 /** The plugin's own documented bounds — see the module comment on why these are not a claimed mirror. */
 export const MAX_HEADER_CHARS = 12
 export const MAX_LABEL_CHARS = 30
@@ -137,6 +169,42 @@ export function buildAskQuestion(gateId: AskGateId): AskQuestion {
   })
 }
 
+/**
+ * PHASE 0 — build the question for ANY accepted gate, including the run-start gate.
+ *
+ * A separate entry point rather than a widened `buildAskQuestion` so the three workflow gates keep the
+ * exact signature and behaviour their callers (and `runtime.phaseRules`) already rely on.
+ */
+export function buildAskQuestionFor(gateId: AskAnyGateId): AskQuestion {
+  if (isRunStartGate(gateId)) {
+    return validateAskQuestion({
+      id: RUN_START_GATE.id,
+      header: RUN_START_GATE.header,
+      question: RUN_START_GATE.question,
+      options: RUN_START_GATE.options.map((option) => ({ ...option })),
+    })
+  }
+  return buildAskQuestion(gateId as AskGateId)
+}
+
+/**
+ * PHASE 0 — validate an answer to ANY accepted gate.
+ *
+ * The run-start gate accepts only the labels IT offered, exactly like the other three, and the check is
+ * the same `ASK_GATES`-shaped test against its own options. An answer of `maybe` is refused rather than
+ * recorded, because a recorded non-answer is the failure mode this whole change exists to prevent.
+ */
+export function validateAskAnswerFor(gateId: AskAnyGateId, answer: string): string {
+  if (isRunStartGate(gateId)) {
+    const offered = RUN_START_GATE.options.map((option) => option.label) as readonly string[]
+    if (!offered.includes(answer)) {
+      throw new AskValidationError('answer', 'must be one of ' + offered.join(' | ') + ' (got ' + JSON.stringify(answer) + ')')
+    }
+    return answer
+  }
+  return validateAskAnswer(gateId as AskGateId, answer)
+}
+
 /**
  * Validate an answer against its gate.
  *
@@ -218,35 +286,42 @@ export function pendingGateFor(artifactFile: string, artifactText: string | null
  * ⚠ THE WRITE-BACK IS A MARKER LINE, REPLACED IN PLACE when the artifact already carries one. A
  * second `TDD Mode:` line would leave two answers to one question and make "what was decided?"
  * depend on which a reader found first.
+ *
+ * ⚠ PHASE 0 — `run-start` IS RECORDED BY THE PLUGIN, NEVER BY A BARE MARKER WRITE. See
+ * `recordRunStartAnswer`: it is the only path that can arm a run goal, it prefers the blocking human
+ * channel, and it fails closed when no person can be reached.
  */
 export function createRecursiveAskTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_ask',
-    description: 'Ask one of the three human gates as a structured decision (tdd-mode, qa-signoff, gate-block), or record the answer. Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. 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. One ask per step.',
     parameters: {
-      gate: { type: 'string', description: 'tdd-mode | qa-signoff | gate-block. Required.' },
+      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.' },
-      artifact: { type: 'string', description: 'Artifact file the answer belongs in. Optional; defaults per gate (gate-block has none, so it is required for that gate).' },
-      answer: { type: 'string', description: 'One of the gate\'s option labels. Omit to ASK.' },
+      artifact: { type: 'string', description: 'Artifact file the answer belongs in. Optional; defaults per gate (gate-block has none, so it is required for that gate; run-start is always recorded in 00-requirements.md).' },
+      answer: { type: 'string', description: 'One of the gate\'s option labels. Omit to ASK. For run-start, the labels are: ' + RUN_START_GATE.options.map((option) => option.label).join(' | ') + '.' },
     },
     output: {
       schema: { type: 'json' },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
     async execute(args: { gate?: string; runId?: string; artifact?: string; answer?: string }, exec) {
-      const gateId = (args.gate ?? '').trim() as AskGateId
+      const gateId = (args.gate ?? '').trim() as AskAnyGateId
       const runId = args.runId?.trim() ?? ''
       if (runId === '') return { error: toolError('MISSING_RUN_ID') } as const
-      if (!ASK_GATE_IDS.includes(gateId)) {
-        return { error: toolError('BAD_ASK_GATE', 'gate must be one of ' + ASK_GATE_IDS.join(' | ')) } as const
+      if (!askGateIds().includes(gateId)) {
+        return { error: toolError('BAD_ASK_GATE', 'gate must be one of ' + askGateIds().join(' | ')) } as const
       }
       const root = await recursive.resolveWorkspaceRoot(exec.agent)
       if (!root) return { error: toolError('NO_WORKSPACE') } as const
 
-      const artifact = (args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId]).trim()
+      // The run-start gate's artifact is FIXED: the Phase 0 requirements document is the run's own
+      // 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()
       let question: AskQuestion
       try {
-        question = buildAskQuestion(gateId)
+        question = buildAskQuestionFor(gateId)
       } catch (err) {
         // The plugin's own gate data failing validation is a defect, so it is reported as one
         // rather than asked: a malformed card would be answered by a person who cannot fix it.
@@ -254,23 +329,149 @@ export function createRecursiveAskTool(recursive: RecursiveRuntime) {
       }
 
       // ASK.
-      if (args.answer === undefined) {
-        return { gate: gateId, marker: ASK_GATES[gateId].marker, artifact, question } as unknown as JsonValue
+      //
+      // ⚠ PHASE 0 EXCEPTION, AND IT IS THE WHOLE POINT OF THE CHANNEL. For the three workflow gates a
+      // question is answered by relaying a label, so "no answer means ask". Starting a run is the decision
+      // that creates the armed goal, so when this composition mounts the blocking human channel the
+      // question is PUT TO THE PERSON whether or not an answer argument arrived — a caller cannot skip the
+      // person by supplying one. Only a composition with no channel falls back to the relayed answer.
+      const channelMounted = recursive.userQuestionsChannel !== null
+      if (args.answer === undefined && !(isRunStartGate(gateId) && channelMounted)) {
+        return { gate: gateId, marker: isRunStartGate(gateId) ? RUN_START_GATE.marker : ASK_GATES[gateId as AskGateId].marker, artifact, question } as unknown as JsonValue
       }
 
       // RECORD.
-      let answer: string
-      try {
-        answer = validateAskAnswer(gateId, args.answer)
-      } catch (err) {
-        return { error: toolError('BAD_ASK_ANSWER', err instanceof Error ? err.message : String(err)) } as const
+      let answer: string | undefined
+      if (args.answer === undefined) {
+        answer = undefined
+      } else {
+        try {
+          answer = validateAskAnswerFor(gateId, args.answer)
+        } catch (err) {
+          return { error: toolError('BAD_ASK_ANSWER', err instanceof Error ? err.message : String(err)) } as const
+        }
       }
       if (artifact === '') {
         return { error: toolError('MISSING_ASK_ARTIFACT', 'this gate needs an explicit artifact to record into') } as const
       }
-      const marker = answerMarker(gateId, answer)
+      if (isRunStartGate(gateId)) {
+        return recordRunStartAnswer(recursive, root, runId, answer, exec) as unknown as JsonValue
+      }
+      const marker = answerMarker(gateId as AskGateId, answer as string)
       const written = recursive.recordAskAnswer(root, runId, artifact, marker)
       return { gate: gateId, answer, marker, artifact, path: written.path, replaced: written.replaced } as unknown as JsonValue
     },
   })
 }
+
+/**
+ * PHASE 0 — record the answer to the run-start gate, and start the run only if it says so.
+ *
+ * ⚠ THIS GATE NEVER ACCEPTS A RELAYED ANSWER WHILE A HUMAN CHANNEL IS MOUNTED. That is the rule that makes
+ * an approval a human act rather than an inference: when `ctx.userQuestions` is present, the question is
+ * PUT TO THE PERSON and nothing else can settle it — not the caller's own `answer` argument, and not a
+ * fabrication, because `ask()` resolves only with a real selection. A person's decline is likewise final
+ * for that call and cannot be overridden by a model that asked for `Start run` in the same breath.
+ *
+ * ⚠ AND WHEN NO CHANNEL IS MOUNTED, THE RELAYED ANSWER IS THE ONLY POSSIBLE SOURCE, so it is used — that
+ * is the same contract the other three gates have always had, and refusing it would leave a composition
+ * without the channel unable to start any run at all. The question is surfaced first by the ASK branch
+ * (the card data the host renders), and the model's `answer` is that person's selection coming back.
+ *
+ * ⚠ WHAT THE GATE THEREFORE DOES *NOT* CLAIM, stated rather than implied: in a composition with no
+ * `userQuestions` channel, a plugin cannot verify that a person was really asked, so a model could in
+ * principle relay a label nobody gave. That is a property of the relay, not of this gate — and it is the
+ * reason the channel is consulted in preference whenever it exists. See the header of `run-start.ts`.
+ */
+export async function recordRunStartAnswer(
+  recursive: RecursiveRuntime,
+  root: string,
+  runId: string,
+  answer: string | undefined,
+  exec: { agent?: unknown; signal?: unknown; callId?: unknown },
+): Promise<Record<string, unknown>> {
+  // 1. ASK THE PERSON DIRECTLY when this composition mounts the channel. An abort or a dismissal is not
+  //    consent, so it settles nothing — and, because the channel was available, it does not hand the
+  //    decision back to the caller either (that is the refusal below).
+  const channel = recursive.userQuestionsChannel
+  const fromChannel = channel ? await askRunStartDirectly(channel, exec) : null
+  if (channel !== null && fromChannel === null) {
+    // The channel exists, so a person COULD have been asked and was not: no answerer, no live root agent,
+    // a dismissal, an abort, or a selection that is not one of this gate's labels. An approval nobody
+    // gave is not recorded, and neither is the caller's argument.
+    return { error: toolError('RUN_START_UNANSWERED') }
+  }
+  const final = fromChannel ?? answer
+  if (final === undefined) {
+    // No channel and no answer: there is nothing a person said, so nothing is recorded.
+    return { error: toolError('RUN_START_NO_CHANNEL') }
+  }
+
+  // 2. Validate the decision that is about to become durable. A channel selection has already been
+  //    filtered to the gate's own labels; a relayed answer has not, and a marker recording an unoffered
+  //    label would read as a decision while being a transcription error.
+  let decided: string
+  try {
+    decided = validateAskAnswerFor(RUN_START_GATE_ID, final)
+  } catch (err) {
+    return { error: toolError('BAD_ASK_ANSWER', err instanceof Error ? err.message : String(err)) }
+  }
+
+  // 3. Record it, and start the run only for the approving label. A `Hold` is recorded as the decision it
+  //    is — declaring the run not started belongs in the run's own record — and starts nothing.
+  const outcome = recursive.approveRunStart(root, runId, exec.agent as never, decided)
+  return {
+    gate: RUN_START_GATE_ID,
+    answer: decided,
+    artifact: RUN_START_ARTIFACT,
+    // Where the decision came from matters to a reader of the transcript: a direct answer is the person's
+    // own selection; a relayed one came back through the model.
+    source: fromChannel === null ? 'relayed' : 'user-questions',
+    path: outcome.path,
+    replaced: outcome.replaced,
+    // `armed` is the answer to "did the harness get a goal to drive?": the run is started only when the
+    // marker took AND the projection armed the goal, so both are reported rather than one implying the
+    // other.
+    armed: outcome.ok && outcome.goal.ok,
+    goal: outcome.goal,
+  }
+}
+
+/**
+ * Ask the run-start question through the blocking channel and return the selection, or null when the
+ * person was not reachable (no answerer, no live root agent, a dismissal, an abort).
+ *
+ * The selection is filtered to the gate's OWN labels before it is returned: a question a UI answered with
+ * a free-text custom value must not become an approval just because it arrived on the right channel.
+ */
+async function askRunStartDirectly(
+  channel: NonNullable<RecursiveRuntime['userQuestionsChannel']>,
+  exec: { agent?: unknown; signal?: unknown; callId?: unknown },
+): Promise<string | null> {
+  const known = RUN_START_GATE.options.map((option) => option.label) as readonly string[]
+  try {
+    // The agent is passed as the LIVE handle the host gave this tool call. The real service validates it
+    // against its own registry and rejects when it is not the live root, so a fabricated handle can never
+    // produce an answer here.
+    const settled = await channel.ask({
+      questions: [{
+        id: RUN_START_GATE.id,
+        header: RUN_START_GATE.header,
+        question: RUN_START_GATE.question,
+        options: RUN_START_GATE.options.map((option) => ({ ...option })),
+      }],
+      agent: exec.agent,
+      signal: exec.signal,
+      // Links the card to this tool call, the way plan-mode's exit does.
+      wait: { callId: exec.callId },
+    } as never)
+    const item = settled.answers.find((entry) => entry.id === RUN_START_GATE.id)
+    const selected = item?.selected?.filter((label) => known.includes(label)) ?? []
+    if (selected.length !== 1) return null
+    return selected[0]
+  } catch {
+    // Quiet by design: the caller reports the situation, and this function's job is only to say whether a
+    // person answered.
+    return null
+  }
+}

package/src/recursive_init.tool.ts

@@ -3,10 +3,25 @@ import { codeRuntimeRefusal, toolError } from './errors.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
+/**
+ * PHASE 0 — SCAFFOLDING IS NOT STARTING, AND THE TOOL SAYS SO AT THE MOMENT IT MATTERS.
+ *
+ * A spec may legitimately exist before a run does: this tool writes the run directory and every phase
+ * document, and it still does. What it must NOT do is start the run, because starting is creating and
+ * arming the goal the harness drives autonomous rounds from. That is the owner's rule — *"phase 0
+ * requires explicit approval to start a run and goal"* — so the description below names the gate and the
+ * result carries `runStartApproval`, which is the pointer a caller needs: the run is inert until
+ * `recursive_ask` answers `run-start`.
+ *
+ * `runStartApproval` is read from the run's own Phase 0 artifact on every call, so it is the TRUE state
+ * rather than "this call created something": re-initialising an APPROVED run reports `approved: true`
+ * (and the run keeps its goal), which is what a caller re-scaffolding a run it already started needs to
+ * see.
+ */
 export function createRecursiveInitTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_init',
-    description: 'Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it.',
+    description: 'Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it. THIS DOES NOT START THE RUN: no goal exists until the user approves phase 0 through recursive_ask gate=run-start, so the result carries runStartApproval — read it and ask.',
     parameters: {
       runId: { type: 'string', description: 'Run id (e.g. 03-something). Required.' },
       createWorktree: { type: 'boolean', description: 'If true, create a linked worktree at .worktrees/<runId>/ and scaffold the run inside it (default: false).' },

package/src/run-start.ts

@@ -0,0 +1,123 @@
+/**
+ * PHASE 0 — STARTING A RUN IS A HUMAN DECISION, NOT A SIDE EFFECT OF SCAFFOLDING.
+ *
+ * THE DEFECT THIS CLOSES. `recursive_init` scaffolded a run and the plugin then CREATED AND ARMED a
+ * goal for it in the same breath (`syncRunGoal`'s "no current goal -> create and arm" branch). A goal
+ * is not a label: `goals.create` returns an ARMED view, and the harness immediately begins driving
+ * autonomous goal rounds for the session. So asking for a run spec was enough to start an unattended
+ * run — the owner's rule is the opposite: *"creating a spec before a run exists should not create a
+ * goal. Phase 0 requires explicit approval to start a run and goal."*
+ *
+ * WHAT "APPROVAL" IS, EXACTLY. The approving label of the `run-start` gate of `recursive_ask`
+ * (`Start run`, as opposed to `Hold`), recorded here as a durable `- Run Start: Start run` line in the
+ * run's Phase 0 requirements artifact. Three things make that an explicit human act rather than an
+ * inference:
+ *
+ *   1. NO DEFAULT, AND THE VALUE IS THE DECISION. The line is written by the gate itself into the Phase 0
+ *      requirements document, and the gate REFUSES an answer that is not one of the labels it offered.
+ *      An unoffered answer is a transcription error wearing the shape of a decision, and a `Hold` is not
+ *      an approval in any spelling — see {@link readRunStartApproval}, which matches the approving VALUE
+ *      and nothing else, so the presence of a `Run Start` line is never on its own consent.
+ *   2. IT IS ASKED, NOT ASSUMED. When the composition mounts `ctx.userQuestions` — the harness's own
+ *      blocking human channel, the same one plan-mode's exit uses — the question is PUT TO THE PERSON and
+ *      only their selection is recorded; a caller-supplied answer cannot stand in for it, and a channel
+ *      that cannot reach anyone ends the call without a decision (RM5503). Only a composition with no
+ *      channel at all falls back to the relayed answer, which is the contract the other three gates have.
+ *   3. THE GOAL CANNOT BE CREATED WITHOUT IT. `syncRunGoal` refuses to create a goal for a run whose
+ *      approval record is absent, in EVERY branch that would create one — not only the "no goal yet"
+ *      branch. That is the property `tests/run-start-approval.spec.ts` asserts, because a single
+ *      unguarded branch is exactly how this defect existed in the first place.
+ *
+ * A SPEC MAY EXIST BEFORE A RUN EXISTS, and this module does not forbid that: the scaffold, the Phase
+ * 0 artifacts and every later phase document are all created by `recursive_init` as before. What is
+ * withheld is the GOAL — the object that makes the harness drive rounds. A run that is scaffolded and
+ * never approved is a spec: readable, editable, lockable, and inert.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getMdFieldValue } from './status.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'
+
+/** The Phase 0 artifact the approval is recorded in. */
+export const RUN_START_ARTIFACT = '00-requirements.md'
+
+/** The artifact field the approval reads back from. */
+export const RUN_START_MARKER = 'Run Start'
+
+/** The approving label. The ONLY label that starts a run. */
+export const RUN_START_APPROVE = 'Start run'
+
+/** The withholding label: the spec stays a spec. */
+export const RUN_START_HOLD = 'Hold'
+
+/**
+ * WHY THIS GATE IS NOT IN `ASK_GATE_IDS`. Those three are the WORKFLOW's gates — phase-3 test
+ * evidence, phase-5 sign-off, resolving a gate block — and their membership is asserted as exactly
+ * three. Starting a run is a different kind of decision: it is the one that decides whether there is
+ * a run at all. It lives here, with its own contract, so widening the workflow's gate list cannot
+ * quietly widen what may start a run.
+ */
+export const RUN_START_GATE = {
+  id: RUN_START_GATE_ID,
+  header: 'Start run',
+  question: 'Approve phase 0 and start this run? Approving creates an armed goal the harness will keep driving.',
+  options: [
+    { label: RUN_START_APPROVE, description: 'Record the approval and arm the run goal.' },
+    { label: RUN_START_HOLD, description: 'Leave the spec inert: no run goal, no autonomous rounds.' },
+  ],
+  marker: RUN_START_MARKER,
+} as const
+
+/** The durable line an approval writes. */
+export function runStartApprovalLine(): string {
+  return '- ' + RUN_START_MARKER + ': ' + RUN_START_APPROVE
+}
+
+/** Is a `run-start` answer the approving one? */
+export function isRunStartApproval(answer: string): boolean {
+  return answer.trim() === RUN_START_APPROVE
+}
+
+/** Where the Phase 0 requirements artifact lives for a run rooted at `root`. */
+export function runStartArtifactPath(root: string, runId: string): string {
+  return join(root, '.recursive', 'run', runId, RUN_START_ARTIFACT)
+}
+
+/** The artifact text, or null when the file is absent (a read failure is not an approval). */
+export function readRunStartArtifact(root: string, runId: string): string | null {
+  try {
+    return readFileSync(runStartArtifactPath(root, runId), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The approval state of a run, read from its Phase 0 artifact.
+ *
+ * ⚠ MATCHED ON THE VALUE, NOT ON THE LINE'S PRESENCE. `getMdFieldValue` returns the field's VALUE, so
+ * a recorded `- Run Start: Hold` is refused here — a check for "is there a Run Start line?" would read
+ * a refusal as consent, which is the one mistake this whole module exists to prevent.
+ */
+export function readRunStartApproval(root: string, runId: string): { approved: boolean; artifact: string; reason: string } {
+  const content = readRunStartArtifact(root, runId)
+  if (content === null) {
+    return { approved: false, artifact: RUN_START_ARTIFACT, reason: 'the Phase 0 requirements artifact does not exist yet' }
+  }
+  const value = getMdFieldValue(content, RUN_START_MARKER)
+  if (value === null) {
+    return { approved: false, artifact: RUN_START_ARTIFACT, reason: 'no ' + RUN_START_MARKER + ' decision has been recorded' }
+  }
+  if (!isRunStartApproval(value)) {
+    return { approved: false, artifact: RUN_START_ARTIFACT, reason: RUN_START_MARKER + ' is ' + JSON.stringify(value) + ', which does not start a run' }
+  }
+  return { approved: true, artifact: RUN_START_ARTIFACT, reason: '' }
+}
+
+/**
+ * The ONE refusal reason the projection returns before approval, exported so every caller branches on
+ * 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'