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

package/src/recursive_worktree.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { toolError } from './errors.ts'
+import { RUN_ID_EXAMPLES, RUN_ID_RULE, runIdProblem } from './run-id.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
@@ -7,13 +8,29 @@ import type { RecursiveRuntime } from './runtime.ts'
  * `recursive_worktree` — create a linked git worktree for a run and/or
  * promote a branch up the dev/stage/main chain. Workspace-scoped: the
  * operations run under the SESSION's control-plane root only.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO, and this is the worst place to be without the rule: a `create`
+ * builds TWO things out of the id — the linked worktree directory `.worktrees/<runId>` AND the git branch
+ * `recursive/<runId>` (git accepts '/' inside a ref) — so a path-shaped id used to leave a worktree and a
+ * ref behind, not just a folder. MEASURED pre-fix, per id, against a fresh repo: `nested/child-run`
+ * returned ok:true and created BOTH `.worktrees/nested/child-run` and
+ * `refs/heads/recursive/nested/child-run`, while the shapes git itself refuses as ref syntax
+ * (`recursive//tmp/x`, `recursive/C:…`, `.hidden-run`, a trailing space) failed the worktree add and
+ * created neither. The rule is `run-id.ts` and is not restated here; the gate sits at this boundary, ahead
+ * of `createRunWorktree`, so the refusal no longer depends on git happening to dislike the ref name.
+ *
+ * The refusal is `BAD_RUN_ID` (RM1107), composed exactly as `recursive_init` composes it — same code, same
+ * detail, same sentence. One message for one rule is what keeps a caller from having to learn a second
+ * vocabulary for the same defect, and the shared remedy it carries ("call recursive_init again") is right
+ * for this tool as well: a `create` for a run that does not exist yet is exactly what `recursive_init`
+ * with `createWorktree: true` does.
  */
 export function createRecursiveWorktreeTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_worktree',
     description: 'Create a linked git worktree for a recursive-mode run and/or promote a branch up the dev/stage/main chain. Workspace-scoped under the current session workspace.',
     parameters: {
-      runId: { type: 'string', description: 'Run id the worktree is created for (e.g. 03-something). Required for create.' },
+      runId: { type: 'string', description: 'Run id the worktree is created for — the NAME of the run (e.g. 03-something), never a path: ' + RUN_ID_RULE + '. A path-shaped id is refused for create. Required for create.' },
       action: { type: 'string', description: 'create | promote | status. Default: create.' },
       fromBranch: { type: 'string', description: 'Source branch for a promote action (the branch holding the new commits).' },
       toBranch: { type: 'string', description: 'Promotion target branch for a promote action (feature -> dev -> stage -> main).' },
@@ -35,7 +52,15 @@ export function createRecursiveWorktreeTool(recursive: RecursiveRuntime) {
         if (!args.runId || args.runId.trim() === '') {
           return { error: toolError('MISSING_CREATE_RUN_ID') } as const
         }
-        const result = recursive.createRunWorktree(root, args.runId.trim(), args.baseBranch?.trim() || undefined)
+        const runId = args.runId.trim()
+        // BEFORE `createRunWorktree`: that call builds `.worktrees/<runId>` and cuts the branch
+        // `recursive/<runId>`, so a path-shaped id that reaches it has already created both. The gate is
+        // on the name; `run-id.ts` says why the join itself is not the thing to change.
+        const problem = runIdProblem(runId)
+        if (problem !== null) {
+          return { error: toolError('BAD_RUN_ID', problem + ' - run ids allow ' + RUN_ID_RULE + ' - e.g. ' + RUN_ID_EXAMPLES) } as const
+        }
+        const result = recursive.createRunWorktree(root, runId, args.baseBranch?.trim() || undefined)
         return result as unknown as JsonValue
       }
       if (action === 'promote') {

package/src/run-id.ts

@@ -0,0 +1,100 @@
+/**
+ * A RUN ID IS A NAME, NOT A PATH.
+ *
+ * WHY THIS MODULE EXISTS. Every consumer of a run id JOINS it onto a directory
+ * that already carries the meaning "the run layer":
+ *
+ *     join(root, '.recursive', 'run', runId)   // runtime.ts, run.ts, handoff.ts, scratch.ts
+ *     join(repoRoot, '.worktrees', runId)      // worktree.ts (a linked worktree)
+ *     'recursive/' + runId                     // worktree.ts (the run's git branch)
+ *
+ * `join` is a PATH operation: absolute paths, drive specifiers and `..` segments
+ * are all legal input to it, and each one silently changes what the call means.
+ * A caller who passes `E:\tmp\rm-live-diagnostics\01-calculator-lib` is asking
+ * for a run "on another drive"; what they get is a `mkdir` of
+ *
+ *     <workspace>\.recursive\run\E:\tmp\rm-live-diagnostics\01-calculator-lib
+ *
+ * which is not drive-qualified at all — on POSIX and Windows alike the colon is
+ * just another character in a relative component. The result is a bogus nested
+ * folder INSIDE the workspace, created before anything can refuse it, surfacing
+ * far away as an ENOENT-shaped runtime failure (RM5501) with the operator's
+ * filesystem already dirty.
+ *
+ * SO THE RULE IS ENFORCED WHERE THE NAME ENTERS, and NOT by teaching the runtime
+ * to accept a path. The joins in `runtime.ts` are CORRECT for a name; what was
+ * missing was a gate on the name. Do not "fix" this back: a run on another drive
+ * or in a worktree is reached through the session's control-plane root
+ * (`recursive_worktree`, `00-worktree.md`) — the run layer is never relocated by
+ * smuggling a path into the id.
+ *
+ * The charset below is deliberately the SAME one the read path already uses
+ * (`live-route.ts` `DOC_SAFE_RE`) so a name this gate accepts is a name that
+ * route can serve.
+ */
+
+/**
+ * The accepted shape, as prose that can be embedded in a model-facing parameter
+ * description and in a refusal detail, so the rule is stated once.
+ */
+export const RUN_ID_RULE = 'letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no ".." segment'
+
+/** Two ids in the shapes the scaffold convention actually produces. */
+export const RUN_ID_EXAMPLES = '01-calculator-lib, fixture-run'
+
+/**
+ * Longest run id accepted. Directory-name components cap at 255 bytes on NTFS
+ * and ext4; a run id also becomes a git ref component (`recursive/<runId>`) and
+ * a prefix of every lock/receipt filename inside the run, so the ceiling is set
+ * well below the filesystem limit rather than at it.
+ */
+export const RUN_ID_MAX_LENGTH = 100
+
+/** Directory-name charset — the read path's `DOC_SAFE_RE`, verbatim. */
+const RUN_ID_CHARS = /^[A-Za-z0-9._-]+$/
+
+/**
+ * Why a run id is refused, or `null` when it is a usable NAME.
+ *
+ * The returned string is the SPECIFIC problem (which rule the id broke), with no
+ * trailing punctuation and no sentence of its own, so a caller can hand it to
+ * `toolError('BAD_RUN_ID', …)` as the detail. `RUN_ID_RULE` states the shape.
+ *
+ * The order of the checks is part of the message quality: a Windows absolute
+ * path is reported as a drive-qualified path (what the caller passed) rather
+ * than as a separator complaint (what that path is made of).
+ */
+export function runIdProblem(raw: string): string | null {
+  if (raw === '') return 'runId is empty'
+  if (raw.length > RUN_ID_MAX_LENGTH) return 'runId is ' + raw.length + ' characters, over the ' + RUN_ID_MAX_LENGTH + ' allowed'
+  // A Windows drive-QUALIFIED path (`E:\x`, and the drive-relative `E:x` too).
+  if (/^[A-Za-z]:/.test(raw)) return 'runId is a Windows drive-qualified path, starting with "' + raw.slice(0, 2) + '"'
+  // Path separators: an absolute POSIX path, a UNC path, or any nested path.
+  if (raw.includes('/') || raw.includes('\\')) {
+    return 'runId contains the path separator "' + (raw.includes('/') ? '/' : '\\') + '"'
+  }
+  // A colon that is not a drive prefix is still unmappable on Windows (NTFS
+  // alternate data streams), and the run id is a Windows directory name.
+  if (raw.includes(':')) return 'runId contains a colon (":"), which is a drive and stream separator on Windows'
+  // `..` makes the join resolve to the PARENT of the run layer.
+  if (raw.includes('..')) return 'runId contains a ".." segment, which escapes the run directory'
+  // `.` and `..` are the parent/current directory segments, and a trailing dot is
+  // stripped by the Win32 path parser — `03-foo.` and `03-foo` would then be two
+  // names for one directory.
+  if (raw.startsWith('.')) return 'runId starts with ".", which makes it a hidden name or a relative path segment'
+  if (raw.endsWith('.')) return 'runId ends with "."'
+  if (!RUN_ID_CHARS.test(raw)) {
+    // Whitespace inside the name is called out separately because the caller can
+    // see the id they typed and cannot see why it is refused: the tool trims the
+    // ENDS (so `" 03-x "` already names `03-x`), but an interior space is not
+    // normalized anywhere and would create a directory the caller cannot retype.
+    if (/\s/.test(raw)) return 'runId contains a space or other whitespace character inside the name'
+    return 'runId contains a character outside the allowed set'
+  }
+  return null
+}
+
+/** True when `raw` is a usable run NAME. Convenience for callers that only branch. */
+export function isValidRunId(raw: string): boolean {
+  return runIdProblem(raw) === null
+}

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

@@ -20,9 +20,15 @@
  *      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.
+ *      only their selection is recorded; a caller-supplied answer cannot stand in for it. A channel that
+ *      RESOLVES with an answer the gate does not recognise is a person's decision the gate cannot record
+ *      and it ends the call (RM5504). A channel that FAILS ends the call too (RM5503), naming the cause the
+ *      channel threw — and there the caller may take the relayed route deliberately, with `relay=true`,
+ *      which the result reports as `source: "relayed"` rather than as a person's own selection, so a
+ *      composition whose channel cannot deliver the question can still start a run. A failure that means
+ *      the question was cancelled, aborted, or timed out is never relayable. Only a composition with no
+ *      channel at all falls back to the relayed answer unconditionally, 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
@@ -36,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'
@@ -121,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),
+    ),
+  }
+}