@sublang/playbook 5.0.0 → 6.0.0

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -20,6 +20,7 @@ import type {
   PlaybookPorts,
   PlaybookRunResult,
   PlaybookRuntime,
+  PlayerSessionStore,
   PlaybookState,
 } from '@sublang/playbook/runtime';
 import {
@@ -71,7 +72,11 @@ interface Enablement {
   optionInput: unknown;
   boundPlayers: readonly RegistryPlayer[];
   hostPlayerId: (localRole: string) => string;
-  visiblePlayerIds?: readonly string[];
+}
+
+interface EffectivePlayerBinding {
+  readonly hostPlayerId: string;
+  readonly player: RegistryPlayer;
 }
 
 interface EngagementFrame {
@@ -81,6 +86,8 @@ interface EngagementFrame {
   sessionId: string;
   rootSessionId: string;
   depth: number;
+  playerBindings: ReadonlyMap<string, EffectivePlayerBinding>;
+  playerResumeTokens: Map<string, string>;
   parent?: {
     frame: EngagementFrame;
     callId: string;
@@ -874,9 +881,6 @@ async function buildEnablements(
       optionInput: record.options,
       boundPlayers,
       hostPlayerId: (localRole) => `${entry.id}-${localRole}`,
-      visiblePlayerIds: entry.requiredRoleIds.map(
-        (role) => `${entry.id}-${role}`,
-      ),
     });
   }
   return { entries, byCommand, byId, enablementById };
@@ -956,6 +960,29 @@ export function createPlaybookCaptainShell(
   const frameLabel = (frame: EngagementFrame): string =>
     `/${frame.enablement.command}`;
 
+  const bindingFor = (
+    frame: EngagementFrame,
+    localRole: string,
+  ): EffectivePlayerBinding => {
+    const binding = frame.playerBindings.get(localRole);
+    if (!binding) {
+      throw new Error(
+        `${frameLabel(frame)} resolved undeclared player role ${JSON.stringify(localRole)}`,
+      );
+    }
+    return binding;
+  };
+
+  const summaryIncludes = (frame: EngagementFrame): boolean => {
+    const owner = activeTurnSummary?.owner;
+    if (!owner) return false;
+    for (let current: EngagementFrame | undefined = frame; current; ) {
+      if (current === owner) return true;
+      current = current.parent?.frame;
+    }
+    return false;
+  };
+
   const requireSession = (): CaptainSession => {
     if (!session) {
       throw new Error('init must be called first');
@@ -1170,7 +1197,8 @@ export function createPlaybookCaptainShell(
     const previousActiveIds = new Set(frame.state?.activeStateIds ?? []);
     frame.state = state;
 
-    if (activeTurnSummary?.owner === frame) {
+    const summary = activeTurnSummary;
+    if (summary && summaryIncludes(frame)) {
       for (const stateId of state.activeStateIds) {
         const newlyActive = !previousActiveIds.has(stateId);
         const structuredEntry =
@@ -1179,9 +1207,9 @@ export function createPlaybookCaptainShell(
         if (!newlyActive && !structuredEntry) continue;
         const countLabel = stateCountLabel(stateId, frame.entry);
         if (countLabel) {
-          activeTurnSummary.stateCounts.set(
+          summary.stateCounts.set(
             countLabel,
-            (activeTurnSummary.stateCounts.get(countLabel) ?? 0) + 1,
+            (summary.stateCounts.get(countLabel) ?? 0) + 1,
           );
         }
       }
@@ -1213,7 +1241,7 @@ export function createPlaybookCaptainShell(
       }
       const context = activeContext;
       signal.throwIfAborted();
-      const hostPlayerId = frame.enablement.hostPlayerId(playerId);
+      const hostPlayerId = bindingFor(frame, playerId).hostPlayerId;
       const result = await trackHostCall(
         frame,
         context.callPlayer(hostPlayerId, prompt, {
@@ -1228,8 +1256,9 @@ export function createPlaybookCaptainShell(
       // CAPTAIN-20: only a player call that actually produced work is an
       // interruption the Boss was spared. A call that errored or aborted
       // saved nothing, so it never feeds the saved-counts gate.
-      if (activeTurnSummary?.owner === frame && result.status === 'ok') {
-        activeTurnSummary.counts.interruptions++;
+      const summary = activeTurnSummary;
+      if (summary && summaryIncludes(frame) && result.status === 'ok') {
+        summary.counts.interruptions++;
       }
       return {
         status: result.status,
@@ -1289,12 +1318,14 @@ export function createPlaybookCaptainShell(
         throw new Error('callCaptain returned status=ok with no finalText');
       }
       const guard = guardFromJudgeReply(result.finalText);
+      const summary = activeTurnSummary;
       if (
         guard &&
-        activeTurnSummary?.owner === frame &&
+        summary &&
+        summaryIncludes(frame) &&
         frame.entry.summaryPolicy?.copyPasteGuardNames.includes(guard)
       ) {
-        activeTurnSummary.counts.copyPastes++;
+        summary.counts.copyPastes++;
       }
       return result.finalText;
     },
@@ -1329,8 +1360,10 @@ export function createPlaybookCaptainShell(
   // visibility for that playbook's generated host players. A pane
   // reconciliation failure is display-only in tmux-play and does not
   // reject; the legacy path carries no generated set and skips this.
-  const requestVisibility = async (enablement: Enablement): Promise<void> => {
-    const ids = enablement.visiblePlayerIds;
+  const requestVisibility = async (frame: EngagementFrame): Promise<void> => {
+    const ids = [...new Set(
+      [...frame.playerBindings.values()].map(({ hostPlayerId }) => hostPlayerId),
+    )];
     if (!ids || ids.length === 0 || !activeContext) return;
     try {
       await activeContext.setVisiblePlayers(ids);
@@ -1375,9 +1408,37 @@ export function createPlaybookCaptainShell(
   ): EngagementFrame => {
     const entry = enablement.entry;
     const sessionId = allocateSessionId();
+    const playerBindings = new Map<string, EffectivePlayerBinding>();
+    for (const role of entry.requiredRoleIds) {
+      let inherited: EffectivePlayerBinding | undefined;
+      for (
+        let ancestor = parent?.frame;
+        ancestor && inherited === undefined;
+        ancestor = ancestor.parent?.frame
+      ) {
+        inherited = ancestor.playerBindings.get(role);
+      }
+      if (inherited) {
+        playerBindings.set(role, inherited);
+        continue;
+      }
+      const configured = enablement.boundPlayers.find(
+        (player) => player.id === role,
+      ) ?? { id: role };
+      playerBindings.set(role, {
+        hostPlayerId: enablement.hostPlayerId(role),
+        player: configured,
+      });
+    }
+    const playerResumeTokens =
+      parent?.frame.playerResumeTokens ?? new Map<string, string>();
     const runtime = entry.createRuntime({
       captainOptions: enablement.optionInput,
-      players: enablement.boundPlayers,
+      players: [...playerBindings].map(([role, { player }]) => ({
+        id: role,
+        ...(player.adapter === undefined ? {} : { adapter: player.adapter }),
+        ...(player.model === undefined ? {} : { model: player.model }),
+      })),
     });
     return {
       entry,
@@ -1386,11 +1447,45 @@ export function createPlaybookCaptainShell(
       sessionId,
       rootSessionId: parent?.frame.rootSessionId ?? sessionId,
       depth: parent ? parent.frame.depth + 1 : 0,
+      playerBindings,
+      playerResumeTokens,
       ...(parent ? { parent } : {}),
       inFlightHostCalls: new Set(),
     };
   };
 
+  const playerSessionStore = (frame: EngagementFrame): PlayerSessionStore => ({
+    select(playerId) {
+      const binding = bindingFor(frame, playerId);
+      return frame.playerResumeTokens.get(binding.hostPlayerId) ?? false;
+    },
+    update(playerId, resumeToken) {
+      const binding = bindingFor(frame, playerId);
+      if (resumeToken === undefined) {
+        frame.playerResumeTokens.delete(binding.hostPlayerId);
+      } else {
+        frame.playerResumeTokens.set(binding.hostPlayerId, resumeToken);
+      }
+    },
+    snapshot() {
+      const tokens: Record<string, string> = {};
+      for (const [playerId, binding] of frame.playerBindings) {
+        const token = frame.playerResumeTokens.get(binding.hostPlayerId);
+        if (token !== undefined) tokens[playerId] = token;
+      }
+      return tokens;
+    },
+    restore(tokens) {
+      for (const binding of frame.playerBindings.values()) {
+        frame.playerResumeTokens.delete(binding.hostPlayerId);
+      }
+      for (const [playerId, token] of Object.entries(tokens)) {
+        const binding = bindingFor(frame, playerId);
+        frame.playerResumeTokens.set(binding.hostPlayerId, token);
+      }
+    },
+  });
+
   const initFrame = async (frame: EngagementFrame): Promise<void> => {
     await frame.runtime.init({
       sessionId: frame.sessionId,
@@ -1403,6 +1498,7 @@ export function createPlaybookCaptainShell(
           }
         : {}),
       depth: frame.depth,
+      playerSessions: playerSessionStore(frame),
       ports: createPorts(frame),
     });
   };
@@ -1599,7 +1695,7 @@ export function createPlaybookCaptainShell(
     }
     let visibilityError: unknown;
     try {
-      await requestVisibility(parent.enablement);
+      await requestVisibility(parent);
     } catch (error) {
       visibilityError = error;
     }
@@ -1720,7 +1816,7 @@ export function createPlaybookCaptainShell(
     // boundary — a `setVisiblePlayers` or telemetry rejection here leaves the
     // runtime uninvoked and owes the Boss the CAPTAIN-34 reply rather than an
     // exception filed against an effect that never ran.
-    await requestVisibility(frame.enablement);
+    await requestVisibility(frame);
     await setMode('engaged.driving', 'submit');
     const result = await runEffect(() =>
       frame.runtime.handleBossInput({ text, signal }),
@@ -1867,7 +1963,7 @@ export function createPlaybookCaptainShell(
       cleanupError = error;
     }
     if (frames.includes(parent)) {
-      await requestVisibility(parent.enablement);
+      await requestVisibility(parent);
     }
     if (cleanupError !== undefined) throw cleanupError;
   };
@@ -2005,7 +2101,7 @@ export function createPlaybookCaptainShell(
       }
       if (frames.includes(parent)) {
         try {
-          await requestVisibility(parent.enablement);
+          await requestVisibility(parent);
         } catch (visibilityError) {
           visibilityControlFailure = true;
           boundaryError = new AggregateError(

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

@@ -20,7 +20,7 @@
 # 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']
-# so commit turns can write git metadata under the codex sandbox.
+# so they can inspect and work with repository metadata under the sandbox.
 
 # The Captain/Judge agent.
 # Captain routing/adjudication calls run tool-free. Claude enforces that at
@@ -40,11 +40,25 @@ notifications:
 
 # Enabled playbooks. Each is loaded from its explicit `from` module; the
 # `<id>` key must equal that module's manifest id. `from`, `command`, and
-# `players` are launcher-owned; every other key (e.g. CODE's `committer`)
-# is that playbook's option slice.
+# `players` are launcher-owned; every other key is that playbook's option
+# slice.
+#
+# Nested calls map roles by exact id. CODE and DECIDE call REVIEW with the
+# same `coder` and `reviewer` ids, so those child roles continue the nearest
+# ancestor sessions. A standalone REVIEW uses its own bindings below.
 playbooks:
   code:
     from: "@sublang/playbook/code/registry"
+    players:
+      coder:
+        adapter: claude
+        model: claude-opus-4-8[1m]
+        effort: xhigh
+        permissions:
+          mode: auto
+
+  review:
+    from: "@sublang/playbook/review/registry"
     players:
       coder:
         adapter: claude
@@ -59,26 +73,23 @@ playbooks:
         permissions:
           mode: auto
           writablePaths: ['.git']
-    committer: coder
 
-# The DISCUSS playbook: two agents converge on spec items or decision
-# records. `committer` picks which player runs Committer commits
-# (default: host).
-#  discuss:
-#    from: "@sublang/playbook/discuss/registry"
-#    players:
-#      host:
-#        adapter: claude
-#        model: claude-opus-4-8
-#        permissions:
-#          mode: auto
-#      participant:
-#        adapter: codex
-#        model: gpt-5.5
-#        permissions:
-#          mode: auto
-#          writablePaths: ['.git']
-#    committer: host
+  decide:
+    from: "@sublang/playbook/decide/registry"
+    players:
+      coder:
+        adapter: claude
+        model: claude-opus-4-8[1m]
+        effort: xhigh
+        permissions:
+          mode: auto
+      reviewer:
+        adapter: codex
+        model: gpt-5.5
+        effort: xhigh
+        permissions:
+          mode: auto
+          writablePaths: ['.git']
 
 # Non-interactive `playbook run` defaults (optional). Each value is an
 # agent string <adapter>[:<model>][@<effort>]; `player` is the catch-all

package/reference/sdlc/decide.md

@@ -0,0 +1,54 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
+
+# Decide
+
+Players:
+
+- Coder
+- Reviewer
+
+The caller supplies the topic including any specific context.
+
+When the caller gives a topic, Captain shall relay the complete topic in quotes (`>`) to Coder and Reviewer concurrently and independently.
+Captain shall not wait for either proposal before requesting the other.
+Captain shall give each player the following instruction:
+
+```markdown
+Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
+Propose your design.
+Keep your proposal coherent, focused, and concise.
+Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
+Do not change any files.
+```
+
+Neither player shall receive the other's proposal until both proposals are complete and Coder has committed Coder's own proposal.
+A Boss interrupt during the parallel proposal pair shall restart the whole pair so both players receive the same new topic and remain independent.
+
+When both proposals are complete, Captain shall then give Coder the following instruction:
+
+```markdown
+Turn your proposal into the necessary spec items or DRs.
+Follow @specs/meta.md and update @specs/map.md when needed.
+Do not inspect or incorporate Reviewer's proposal before this commit.
+Do not change code or implement the proposal.
+
+Commit the result as one new commit, following @specs/packages/git.md.
+Make the commit message explain concisely what changed and why.
+Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
+Coder is <coder-llm>; format the model token in conventional human form.
+```
+
+After Coder commits, Captain shall call playbook `review`:
+
+> Review the latest commit as a spec-design change against the initial intent.
+> Compare it with your independent proposal and take the best of both.
+> Make your suggestions.
+>
+> Initial intent: \<caller-topic\>.
+> Coder's independent proposal: \<coder-proposal\>.
+
+`decide` is complete when `review` returns the approved latest commit and the fact that no unsettled findings remain.
+When `review` returns an authored abort or failure, or a terminal result that does not prove exact approval, `decide` shall report the failure and the last `decide`-owned commit to its caller.
+When the nested `review` call fails outside that authored result contract, `decide` shall park as failed and retain the control-plane error instead of reporting an authored review outcome.

package/reference/sdlc/decide.playbook/decide.fsm.d.ts

@@ -0,0 +1,261 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+type Player = 'Coder' | 'Reviewer';
+type JumpableStateId = 'independentProposals';
+type ResumableStateId = 'askCoderProposal' | 'askReviewerProposal' | 'commitCoderProposal';
+export interface PendingBossQuestion {
+    questionId: ResumableStateId;
+    resumeStateId: ResumableStateId;
+    sourceItem: string;
+    player: Player;
+    question: string;
+}
+type PendingBossQuestions = Partial<Record<ResumableStateId, PendingBossQuestion>>;
+type BossReplies = Partial<Record<ResumableStateId, string>>;
+type PendingBossQuestionParams = Omit<PendingBossQuestion, 'questionId'>;
+export interface ReviewSuccessOutput {
+    approvedCommit: 'latest';
+    noUnsettledFindings: true;
+}
+export interface DecideFailureOutput {
+    lastDecideCommit: string;
+    noUnsettledFindings: false;
+    reviewStatus: 'aborted' | 'error';
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export type DecideOutput = ReviewSuccessOutput | DecideFailureOutput;
+interface ChildFailure {
+    status: 'aborted' | 'error';
+    playbookId: 'review';
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export interface DecideContext {
+    coderLlm: string;
+    callerTopic?: string;
+    coderProposal?: string;
+    reviewerProposal?: string;
+    latestCommit?: string;
+    reviewResult?: ReviewSuccessOutput;
+    reviewFailure?: ChildFailure;
+    lastResult?: PlayerOutput;
+    lastError?: unknown;
+    pendingBossQuestions?: PendingBossQuestions;
+    bossReplies?: BossReplies;
+    stagedCoderResult?: PlayerOutput;
+    stagedReviewerResult?: PlayerOutput;
+}
+export type DecideEvent = {
+    type: 'START_DECIDE';
+    callerTopic: string;
+} | {
+    type: 'BOSS_INTERRUPT';
+    targetId: JumpableStateId;
+    bossIntent: string;
+} | {
+    type: 'BOSS_REPLY';
+    questionId?: ResumableStateId;
+    answer: string;
+};
+export interface DecideInput {
+    coderLlm: string;
+}
+export interface PlayerInput {
+    stateId: ResumableStateId;
+    sourceItem: string;
+    prompt: string;
+    result: Record<string, string>;
+    player: Player;
+    callerTopic?: string;
+    coderLlm?: string;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
+}
+type AdditionalPlayerFields = {
+    coderProposal?: string;
+    reviewerProposal?: string;
+    coderOutput?: string;
+    latestCommit?: string;
+    question?: string;
+    readonly [key: string]: unknown;
+};
+export type PlayerOutput = ({
+    guard: 'proposed';
+    coderProposal: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'proposed';
+    reviewerProposal: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'committed';
+    coderOutput: string;
+    latestCommit: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'needsBossReply';
+    question: string;
+} & AdditionalPlayerFields);
+export interface PlaybookInput {
+    stateId: 'reviewCommit';
+    sourceItem: 'DECIDE-4';
+    playbookId: 'review';
+    text: string;
+}
+export declare const decideMachine: import("xstate").StateMachine<DecideContext, {
+    type: "START_DECIDE";
+    callerTopic: string;
+} | {
+    type: "BOSS_INTERRUPT";
+    targetId: JumpableStateId;
+    bossIntent: string;
+} | {
+    type: "BOSS_REPLY";
+    questionId?: ResumableStateId;
+    answer: string;
+}, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+}, {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "player";
+    logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "rememberActorError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "clearBossReplyContext";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "copyInterruptedTopic";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "copyStartTopic";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "stageCoderProposal";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "stageReviewerProposal";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "promoteProposals";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCommit";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewSuccess";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewProtocolFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedActorOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingBossQuestion";
+    params: PendingBossQuestionParams;
+} | {
+    type: "clearBranchBossReplyContext";
+    params: {
+        stateId: ResumableStateId;
+    };
+} | {
+    type: "clearProposalRoundContext";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "authoredReviewFailure";
+    params: unknown;
+} | {
+    type: "committed";
+    params: unknown;
+} | {
+    type: "coderProposed";
+    params: unknown;
+} | {
+    type: "reviewerProposed";
+    params: unknown;
+} | {
+    type: "needsBossReplyWithQuestion";
+    params: unknown;
+} | {
+    type: "needsBossReplyWithoutQuestion";
+    params: unknown;
+} | {
+    type: "validReviewSuccess";
+    params: unknown;
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "commitCoderProposal" | "reviewCommit" | "reportedReviewFailure" | {
+    independentProposals: {
+        coder: "complete" | "working" | "waiting";
+        reviewer: "complete" | "working" | "waiting";
+    };
+}, string, DecideInput, ReviewSuccessOutput | DecideFailureOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "decide";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly independentProposals: {
+            id: "independentProposals";
+            states: {
+                readonly coder: {
+                    states: {
+                        readonly working: {
+                            id: "askCoderProposal";
+                        };
+                        readonly waiting: {
+                            id: "waitCoderProposalReply";
+                        };
+                        readonly complete: {};
+                    };
+                };
+                readonly reviewer: {
+                    states: {
+                        readonly working: {
+                            id: "askReviewerProposal";
+                        };
+                        readonly waiting: {
+                            id: "waitReviewerProposalReply";
+                        };
+                        readonly complete: {};
+                    };
+                };
+            };
+        };
+        readonly commitCoderProposal: {
+            id: "commitCoderProposal";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly reviewCommit: {
+            id: "reviewCommit";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly reportedReviewFailure: {
+            id: "reportedReviewFailure";
+        };
+        readonly done: {
+            id: "done";
+        };
+    };
+}>;
+export default decideMachine;