@try-works/dsh-recursive-mode 0.4.4 → 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";
@@ -133,6 +151,33 @@ export declare const TOOL_ERRORS: {
         readonly problem: "the run has unresolved delegated work, so this phase cannot lock yet";
         readonly next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again";
     };
+    readonly RUN_START_NO_CHANNEL: {
+        readonly code: "RM5502";
+        readonly klass: "runtime";
+        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 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";

package/lib/goals-projection.d.ts

@@ -81,12 +81,42 @@ export declare function isRunGoal(goal: GoalViewLike | undefined, runId: string)
  * Sync a run's durable goal to the requested phase. Safe: never touches a goal
  * whose objective is not this run's marker, and never re-creates over a
  * non-complete foreign goal.
+ *
+ * ⚠ `approved` IS THE PHASE-0 GATE, and it defaults to the SAFE direction. A goal is not a label:
+ * `create` returns an ARMED view and the harness starts driving autonomous goal rounds for the
+ * session, so creating one is starting the run. The owner's rule is that phase 0 requires explicit
+ * approval, which means the projection must be unable to arm anything on its own — hence a default of
+ * `false` and an explicit refusal in EVERY branch that would call `create`, including the two
+ * replace-a-completed-goal branches (an unapproved run cannot have reached `complete`, but "cannot
+ * happen" is what the single unguarded branch relied on too).
+ *
+ * ⚠ AND IT IS REACHED ON ORDINARY WORK, so the unapproved path is QUIET AND IDEMPOTENT: no goal is
+ * created, nothing is written, no error is thrown, and the run's artifacts are untouched. The caller
+ * reads {@link RUN_START_NOT_APPROVED} to tell "this run has not been started yet" apart from a real
+ * failure, so a normal phase step never surfaces a warning.
+ *
+ * `approved` is passed IN rather than read here because this module is pure: it takes the goal service
+ * seam and nothing else, and the plugin's own filesystem reads live in the runtime (see
+ * `RecursiveRuntime.readRunStartApproval`).
+ */
+export declare function syncRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, runState: RunState, approved?: boolean): SyncResult;
+/**
+ * Block the current run goal (used on a gate-block). Never touches a foreign goal.
+ *
+ * ⚠ A RUN THAT WAS NEVER STARTED HAS NO GOAL TO BLOCK, so this reports the unapproved state in the
+ * same words as {@link syncRunGoal} rather than "no current goal to block": the caller's question is
+ * "why is there no goal", and the answer must not depend on which entry point happened to ask.
  */
-export declare function syncRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, runState: RunState): SyncResult;
-/** Block the current run goal (used on a gate-block). Never touches a foreign goal. */
 export declare function blockRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, reason: {
     code: string;
     message: string;
 }): SyncResult;
-/** Bridge a run's blocked goal back to active (used on a reopen). */
-export declare function resumeRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string): SyncResult;
+/**
+ * Bridge a run's blocked goal back to active (used on a reopen).
+ *
+ * ⚠ REOPEN IS NOT A BACK DOOR TO STARTING A RUN. It routes through {@link syncRunGoal}, so a reopen of
+ * an unapproved run cannot create the goal that init deliberately withheld. An APPROVED run is
+ * unaffected: its approval outlives the reopen, because the approval is a durable line in the run's
+ * own Phase 0 artifact rather than a value held in memory (verified in `tests/run-start-approval.spec.ts`).
+ */
+export declare function resumeRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, approved?: boolean): SyncResult;