@sublang/playbook 3.1.0 → 5.0.0

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -10,6 +10,13 @@
 # settings inline: an adapter shorthand (claude, codex) or a block with
 # adapter/model/effort/permissions. Retuning one agent never changes
 # another.
+
+# Each adapter needs its vendor SDK installed as its own top-level
+# install root — they are optional peer dependencies, so you pay only
+# for the vendors named below:
+#   claude -> npm install -g @anthropic-ai/claude-agent-sdk
+#   codex  -> npm install -g @openai/codex-sdk
+# Drop an adapter from this file and you can skip its SDK entirely.
 # Every seeded agent runs in cligent's protected auto mode
 # (permissions.mode: auto): claude maps it to permissionMode auto, codex to
 # on-request + auto_review. Codex roles also grant writablePaths: ['.git']

package/reference/sdlc/discuss.playbook/discuss.playbook.js

@@ -520,6 +520,13 @@ function normalizeErrorCompact(err) {
 function normalizeErrorFull(err) {
     return err === undefined || err === null ? undefined : normalizeError(err);
 }
+// DR-028's unified empty predicate: a missing, empty, or whitespace-only
+// `finalText` on an `ok` player result is the one shape that earns exactly
+// one corrective re-ask before the existing failure path applies. Mirrors
+// the shared engine's predicate (PBRT-9).
+function isEmptyFinalText(finalText) {
+    return finalText === undefined || finalText.trim().length === 0;
+}
 function isAbortFailure(error, signal) {
     if (!signal.aborted)
         return false;
@@ -944,16 +951,29 @@ export const createPlaybookRuntime = (options) => {
             throw error;
         }
         combined.throwIfAborted();
-        const { playerId, result } = await callPlayer(input, combined);
+        let { playerId, result } = await callPlayer(input, combined);
+        if (result.status === 'ok' && isEmptyFinalText(result.finalText)) {
+            // DR-028: an `ok` result whose finalText is missing, empty, or
+            // whitespace-only earns exactly one corrective re-ask — the same
+            // composed call repeated, traced by runPlayerCall as its own
+            // player-call pair, with the resume selection re-read from the
+            // token map the first result left (PBRT-38). An abort that lands
+            // between the two calls ends the turn without the re-ask (aborts
+            // are never retried), and a rejecting finish emission rejects
+            // `callPlayer` itself, so it never reaches this branch (PBRT-47).
+            combined.throwIfAborted();
+            ({ playerId, result } = await callPlayer(input, combined));
+        }
         if (result.status !== 'ok') {
             throw new Error(`player "${playerId}" returned status "${result.status}"${result.error ? `: ${result.error}` : ''}`);
         }
-        if (result.finalText === undefined) {
+        const finalText = result.finalText ?? '';
+        if (isEmptyFinalText(finalText)) {
             throw new Error(`player "${playerId}" returned status "ok" with no finalText`);
         }
         combined.throwIfAborted();
         try {
-            const prompt = buildAdjudicatorPrompt(input, result.finalText);
+            const prompt = buildAdjudicatorPrompt(input, finalText);
             return parseAdjudication(await callJudge(prompt, combined, 'player-output-adjudication', input.stateId), input);
         }
         catch (error) {
@@ -1028,8 +1048,23 @@ export const createPlaybookRuntime = (options) => {
             inspect,
         });
     };
+    // PBRT-6: the single seam that stops this runtime's actor. Stopping a
+    // still-running actor fires one more `@xstate.snapshot` for the *unchanged*
+    // state value with `status: 'stopped'`; `inspect` cannot tell that disposal
+    // artifact from a state entry, so unsuppressed it re-emits the parked
+    // state's telemetry and a phantom self-loop transition. Suppression is a
+    // property of stopping, not a rule each caller must remember — every stop
+    // goes through here so no later site can reintroduce the omission.
+    const stopActor = () => {
+        if (!actor)
+            return;
+        suppressInspectionEmissions = true;
+        actor.stop();
+    };
     const startActor = () => {
         createRuntimeActor();
+        // A fresh actor's emissions are real state entries again.
+        suppressInspectionEmissions = false;
         actor?.start();
     };
     const driveToQuiescence = async () => {
@@ -1114,9 +1149,8 @@ export const createPlaybookRuntime = (options) => {
                 // A state that cannot even normalize has no disposal descriptor.
             }
         }
-        suppressInspectionEmissions = true;
         try {
-            actor?.stop();
+            stopActor();
         }
         catch {
             // Preserve the original startup failure.
@@ -1327,7 +1361,7 @@ export const createPlaybookRuntime = (options) => {
                     else {
                         await emitBoundaryStatus(event.type, currentState());
                         if (actor.getSnapshot().status === 'done') {
-                            actor.stop();
+                            stopActor();
                             startActor();
                         }
                         actor.send(event);
@@ -1442,9 +1476,7 @@ export const createPlaybookRuntime = (options) => {
                 }
                 const finalState = currentState();
                 const failures = [];
-                if (actor) {
-                    actor.stop();
-                }
+                stopActor();
                 try {
                     await drainBoundaryCallsAndEmissions();
                 }

package/reference/sdlc/discuss.playbook/discuss.playbook.ts

@@ -713,6 +713,14 @@ function normalizeErrorFull(
   return err === undefined || err === null ? undefined : normalizeError(err);
 }
 
+// DR-028's unified empty predicate: a missing, empty, or whitespace-only
+// `finalText` on an `ok` player result is the one shape that earns exactly
+// one corrective re-ask before the existing failure path applies. Mirrors
+// the shared engine's predicate (PBRT-9).
+function isEmptyFinalText(finalText: string | undefined): boolean {
+  return finalText === undefined || finalText.trim().length === 0;
+}
+
 function isAbortFailure(error: unknown, signal: AbortSignal): boolean {
   if (!signal.aborted) return false;
   if (Object.is(error, signal.reason)) return true;
@@ -1263,7 +1271,19 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
       }
       combined.throwIfAborted();
 
-      const { playerId, result } = await callPlayer(input, combined);
+      let { playerId, result } = await callPlayer(input, combined);
+      if (result.status === 'ok' && isEmptyFinalText(result.finalText)) {
+        // DR-028: an `ok` result whose finalText is missing, empty, or
+        // whitespace-only earns exactly one corrective re-ask — the same
+        // composed call repeated, traced by runPlayerCall as its own
+        // player-call pair, with the resume selection re-read from the
+        // token map the first result left (PBRT-38). An abort that lands
+        // between the two calls ends the turn without the re-ask (aborts
+        // are never retried), and a rejecting finish emission rejects
+        // `callPlayer` itself, so it never reaches this branch (PBRT-47).
+        combined.throwIfAborted();
+        ({ playerId, result } = await callPlayer(input, combined));
+      }
       if (result.status !== 'ok') {
         throw new Error(
           `player "${playerId}" returned status "${result.status}"${
@@ -1271,7 +1291,8 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
           }`,
         );
       }
-      if (result.finalText === undefined) {
+      const finalText = result.finalText ?? '';
+      if (isEmptyFinalText(finalText)) {
         throw new Error(
           `player "${playerId}" returned status "ok" with no finalText`,
         );
@@ -1279,7 +1300,7 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
       combined.throwIfAborted();
 
       try {
-        const prompt = buildAdjudicatorPrompt(input, result.finalText);
+        const prompt = buildAdjudicatorPrompt(input, finalText);
         return parseAdjudication(
           await callJudge(
             prompt,
@@ -1399,8 +1420,23 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
     });
   };
 
+  // PBRT-6: the single seam that stops this runtime's actor. Stopping a
+  // still-running actor fires one more `@xstate.snapshot` for the *unchanged*
+  // state value with `status: 'stopped'`; `inspect` cannot tell that disposal
+  // artifact from a state entry, so unsuppressed it re-emits the parked
+  // state's telemetry and a phantom self-loop transition. Suppression is a
+  // property of stopping, not a rule each caller must remember — every stop
+  // goes through here so no later site can reintroduce the omission.
+  const stopActor = (): void => {
+    if (!actor) return;
+    suppressInspectionEmissions = true;
+    actor.stop();
+  };
+
   const startActor = (): void => {
     createRuntimeActor();
+    // A fresh actor's emissions are real state entries again.
+    suppressInspectionEmissions = false;
     actor?.start();
   };
 
@@ -1499,9 +1535,8 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
         // A state that cannot even normalize has no disposal descriptor.
       }
     }
-    suppressInspectionEmissions = true;
     try {
-      actor?.stop();
+      stopActor();
     } catch {
       // Preserve the original startup failure.
     }
@@ -1736,7 +1771,7 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
           } else {
             await emitBoundaryStatus(event.type, currentState());
             if (actor.getSnapshot().status === 'done') {
-              actor.stop();
+              stopActor();
               startActor();
             }
 
@@ -1859,9 +1894,7 @@ export const createPlaybookRuntime: PlaybookRuntimeFactory<
         }
         const finalState = currentState();
         const failures: unknown[] = [];
-        if (actor) {
-          actor.stop();
-        }
+        stopActor();
         try {
           await drainBoundaryCallsAndEmissions();
         } catch (error) {

package/slc/gears2fsm.md

@@ -193,6 +193,49 @@ Both direct-Captain states additionally receive the universal
 `needsBossReply` result. Their guards and actions shall use those exact
 case-sensitive names so the compiled adjudication contract remains stable.
 
+For a controller playbook — one whose Source declares DR-029's session-scoped
+controller policy: a session Captain that runs for the whole host session,
+receives every Boss turn, and operates the working playbooks from outside the
+engagement stack (DR-029) — the compiler shall apply the additive
+controller decision-state class below. The class joins the stable compiler
+contract beside the decide-call-observe vocabulary above; that vocabulary and
+the universal `needsBossReply` rule stay untouched for the artifacts that
+consume them.
+The controller machine shall be a session loop, not a finite errand: a
+quiescent conversational hub (tag `playbook.parked`) receives each Boss turn;
+the controller decision state decides it over the closed action set; a
+`respond` selection settles its turn in the decision call itself, its
+validated `text` being the turn's captain speech; an acting selection's host
+settlement becomes the outcome report grounding one closing-reply call; and
+the machine returns to the hub for the next turn. Returning to the hub after
+a settled turn completes the session loop's turn; it is not the idle-hub
+routing that [Transitions](#transitions) reserves for recovery.
+Because the hub receives every Boss turn, a controller state carries no
+Boss-reply suspension: the compiler shall not add `needsBossReply` to a
+controller machine's `invoke.input.result` maps — a clarifying question to
+Boss is a `respond` selection.
+The machine shall declare no terminal result output and shall keep exactly
+one reachable `type: 'final'` shutdown state entered only by the host's
+teardown event. The completion rule of
+[Errors and termination](#errors-and-termination) applies unamended: its
+output clause binds only where Source declares a terminal result, which a
+controller Source does not.
+The controller decision state's direct-Captain result contract discriminates
+the closed action set of DR-029. Its guard discriminants are a stable
+compiler contract, not names the compiler may invent — `respond`, `start`,
+`switch`, `dismiss`, `deliver`, and `runtime` — with each guard's required
+payload fields:
+
+- `respond` requires `text`;
+- `start` and `switch` each require `playbookId` and `input`;
+- `runtime` requires `actionId`;
+- `dismiss` and `deliver` require none — a `deliver` result in particular
+  carries no text payload: the host is authoritative for the delivered text,
+  so the contract declares no field for it.
+
+The decision state's guards and actions shall use those exact case-sensitive
+names so the compiled controller contract remains stable.
+
 ## States
 
 Each state shall declare:
@@ -588,11 +631,20 @@ cannot supply alone, the machine shall suspend that task in a quiescent wait
 state and resume the same task with the Q+A in the next prompt.
 This is a third Boss surface alongside `BOSS_INTERRUPT` and Boss entry events.
 
-Every captain- and player-invoking state supports this path.
+Every captain- and player-invoking state supports this path, with one
+exception the compiler shall apply, not infer: the states of a controller
+machine ([Setup](#setup), controller decision-state class) carry no
+Boss-reply suspension, because its hub already receives every Boss turn and a
+clarifying question to Boss is a `respond` selection over the closed action
+set. The rule below is therefore universal over workflow states and silent
+about that class; in particular, adding `needsBossReply` to the controller
+decision state would add a seventh outcome to a closed six-action contract
+whose guard discriminants [Setup](#setup) fixes, and is nonconformant.
 There is no source-level opt-in annotation and no `needsBossReply` result metadata in GEARS output.
 The FSM compiler shall preserve the GEARS blockquote as the state's domain `prompt` body and shall not inject any Boss-question instruction into `invoke.input.prompt`.
 
-For every captain- and player-invoking state, the compiler shall add
+For every captain- and player-invoking state outside a controller machine,
+the compiler shall add
 `needsBossReply` to the state's `invoke.input.result` map.
 The description shall be the standard adjudicator-facing text: