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

package/README.md

@@ -179,7 +179,7 @@ control plane on disk is the only state it trusts across restarts.
 | `recursive_audit_team` | Fan a phase out across roles (audit) |
 | `recursive_review` | **Independent review** of the phase artifact, with a repair path |
 | `recursive_delegate` | **Delegate the work of a phase** to a durable child; it produces, you judge |
-| `recursive_ask` | Ask the workspace a question, with the control plane as context |
+| `recursive_ask` | Ask a **human** gate as a structured decision: `tdd-mode`, `qa-signoff`, `gate-block`, or `run-start` — the phase-0 approval that decides whether the run goal exists |
 | `recursive_preview` | Preview what a tool would do, without doing it |
 
 ### 4.2 The command surface
@@ -405,9 +405,20 @@ prove. Three facts shape the picture:
    the audit contract: `01-as-is`, `01.5-root-cause`, `02-to-be-plan`, `03-implementation-summary`,
    `03.5-code-review`, `04-test-summary`, `06-decisions-update`, `07-state-update`, `08-memory-impact`.
    `00-requirements`, `00-worktree` and `05-manual-qa` are not in it.
-3. **`recursive_ask` is not a subagent tool.** It carries the workflow's three **human** gates —
-   `ASK_GATE_IDS = ['tdd-mode', 'qa-signoff', 'gate-block']` — as structured decisions rather than prose, so the
-   answer is validated and citeable.
+3. **`recursive_ask` is not a subagent tool.** It carries the workflow's **four human gates** —
+   `tdd-mode`, `qa-signoff` and `gate-block` (the list in `ASK_GATE_IDS`), plus **`run-start`**, the
+   phase-0 approval that decides whether a run's goal exists at all — as structured decisions rather
+   than prose, so the answer is validated and citeable.
+
+   `run-start` is unlike the other three: it is the only gate that asks the harness's **blocking
+   human channel**, and the only one that **arms a goal**. Creating a spec therefore creates no goal;
+   nothing runs unattended until a person approves it. When the mounted channel cannot deliver the
+   question, the refusal **names the channel's own cause** (`RM5503`) instead of asserting one — and a
+   composition that cannot render a card at all can still record the decision explicitly by passing
+   `answer` with `relay: true`, which is reported as relayed rather than as a person's selection. A
+   person's own answer always wins, and a question that was cancelled, aborted or timed out is **never**
+   relayable. A channel that *did* reach a person whose answer was not one of the offered labels is
+   `RM5504`, which is a different event from `RM5503`.
 
 ```mermaid
 flowchart TB

package/lib/errors.d.ts

@@ -61,12 +61,30 @@ export declare const TOOL_ERRORS: {
         readonly problem: "this gate has no default artifact, so one must be named";
         readonly next: "pass artifact: <file> so the answer has somewhere durable to land";
     };
+    readonly RELAY_ONLY_FOR_RUN_START: {
+        readonly code: "RM1150";
+        readonly klass: "input";
+        readonly problem: "relay applies only to the run-start gate, which is the only gate that asks the user-questions channel";
+        readonly 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";
+    };
     readonly MISSING_RUN_ID: {
         readonly code: "RM1101";
         readonly klass: "input";
         readonly problem: "runId is required";
         readonly 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.
+     */
+    readonly BAD_RUN_ID: {
+        readonly code: "RM1107";
+        readonly klass: "input";
+        readonly problem: "runId is not a single directory name";
+        readonly next: "pass the run directory name such as 03-something, then call recursive_init again";
+    };
     readonly MISSING_ARTIFACT: {
         readonly code: "RM1102";
         readonly klass: "input";
@@ -139,12 +157,27 @@ export declare const TOOL_ERRORS: {
         readonly problem: "the run-start gate needs an answer, and this composition mounts no user-questions channel to ask one directly";
         readonly next: string;
     };
+    /**
+     * ⚠ 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.
+     */
     readonly RUN_START_UNANSWERED: {
         readonly code: "RM5503";
         readonly klass: "runtime";
-        readonly problem: "the user-questions channel mounted in this composition refused the run-start question, so no person was asked";
+        readonly problem: "the run-start question reached no decision: the mounted user-questions channel failed before a person answered it";
         readonly next: string;
     };
+    readonly RUN_START_ANSWER_UNUSABLE: {
+        readonly code: "RM5504";
+        readonly klass: "runtime";
+        readonly problem: "a person was asked to start this run and their answer was not one of the labels the run-start gate offered";
+        readonly 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";
+    };
     readonly RUNTIME_REFUSED: {
         readonly code: "RM5501";
         readonly klass: "runtime";