@try-works/dsh-recursive-mode 0.4.5 → 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

@@ -65,12 +65,30 @@ export const TOOL_ERRORS = {
     problem: 'this gate has no default artifact, so one must be named',
     next: 'pass artifact: <file> so the answer has somewhere durable to land',
   },
+  RELAY_ONLY_FOR_RUN_START: {
+    code: 'RM1150',
+    klass: 'input',
+    problem: 'relay applies only to the run-start gate, which is the only gate that asks the user-questions channel',
+    next: 'drop relay for this gate and answer it with one of its own labels, or call recursive_ask with gate: run-start when the decision is whether to start the run',
+  },
   MISSING_RUN_ID: {
     code: 'RM1101',
     klass: 'input',
     problem: 'runId is required',
     next: 'call recursive_status with no runId to see the latest run id in this workspace',
   },
+  /**
+   * A run id is the NAME of the run directory and is joined onto the run layer
+   * as one path segment, so a path-shaped id is refused before any directory is
+   * created. See `run-id.ts` for the rule and for why it is not the runtime that
+   * learns to accept a path.
+   */
+  BAD_RUN_ID: {
+    code: 'RM1107',
+    klass: 'input',
+    problem: 'runId is not a single directory name',
+    next: 'pass the run directory name such as 03-something, then call recursive_init again',
+  },
   MISSING_ARTIFACT: {
     code: 'RM1102',
     klass: 'input',
@@ -144,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. */
 
@@ -153,11 +184,26 @@ export const TOOL_ERRORS = {
     problem: 'the run-start gate needs an answer, and this composition mounts no user-questions channel to ask one directly',
     next: 'call recursive_ask with gate: run-start and no answer to surface the question, then retry with answer: ' + '"Start run"',
   },
+  /**
+   * ⚠ RM5503 USED TO LIE. Its text asserted "so no person was asked" for EVERY cause, because the caller
+   * that produced it had already thrown the cause away — and a live session showed the cost: the gate
+   * failed 22.9 s into the call with a reason nobody could see, and its `Next:` clause prescribed the very
+   * call that had just failed, so no route to start a run remained. The problem statement now claims only
+   * what the gate knows (no decision came back), and the cause travels in the `detail` the caller
+   * supplies. `RUN_START_ANSWER_UNUSABLE` carries the one case this entry must NOT cover: a person was
+   * reached and their answer was not an approval.
+   */
   RUN_START_UNANSWERED: {
     code: 'RM5503',
     klass: 'runtime',
-    problem: 'the user-questions channel mounted in this composition refused the run-start question, so no person was asked',
-    next: 'use recursive_ask without an answer to surface the question, and retry it with answer: ' + '"Start run" once the user has approved the run start',
+    problem: 'the run-start question reached no decision: the mounted user-questions channel failed before a person answered it',
+    next: 'read the cause named in the detail, fix it and call recursive_ask again, or - when this composition cannot deliver the question at all - call recursive_ask with answer: ' + '"Start run"' + ' and relay=true to record the person\'s explicit approval as a relayed one',
+  },
+  RUN_START_ANSWER_UNUSABLE: {
+    code: 'RM5504',
+    klass: 'runtime',
+    problem: 'a person was asked to start this run and their answer was not one of the labels the run-start gate offered',
+    next: 'call recursive_ask again and have the person choose exactly "Start run" or "Hold"; a skipped or custom answer is not an approval, and no relayed answer can replace a decision the person made',
   },
   RUNTIME_REFUSED: {
     code: 'RM5501',