@sublang/playbook 9.0.0 → 11.0.0

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

@@ -8,9 +8,10 @@
 
 # The Captain and each stable session player carries its own defaults inline:
 # an adapter shorthand (claude, codex) or a block with
-# adapter/model/effort/permissions. A role may override only model or effort.
-# Omit an override to inherit the player default; set it to false to select
-# that provider's current default explicitly.
+# adapter/model/effort/fastMode/permissions. A role may override only model,
+# effort, or fastMode.
+# Omit an override to inherit the player default. For model and effort, false
+# selects the provider default; fastMode false is a literal disabled request.
 
 # Each adapter needs its vendor SDK installed as its own top-level
 # install root — they are optional peer dependencies, so you pay only
@@ -29,7 +30,7 @@
 # list, so those captains degrade to a prompt-level restriction (DR-013 A1).
 captain:
   adapter: claude
-  model: claude-opus-4-8
+  model: claude-opus-5
   effort: high
   permissions:
     mode: auto
@@ -45,19 +46,22 @@ notifications:
 # shares one provider conversation across those playbooks.
 players:
   dev.coder:
-    adapter: claude
-    model: claude-opus-4-8[1m]
-    effort: xhigh
+    adapter: codex
+    model: gpt-5.6-sol
+    effort: ultra
+    # Adapter-scoped fast mode is validated by the installed Cligent contract;
+    # omitting it takes the provider default.
+    fastMode: true
     permissions:
       mode: auto
+      writablePaths: ['.git']
 
   dev.reviewer:
-    adapter: codex
-    model: gpt-5.5
+    adapter: claude
+    model: claude-opus-5
     effort: xhigh
     permissions:
       mode: auto
-      writablePaths: ['.git']
 
 # Enabled playbooks. Each is loaded from its explicit `from` module; the
 # `<id>` key must equal that module's manifest id. `from`, `command`, and

package/reference/sdlc/code.playbook/session-store.d.ts

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export declare const RECORDS_STREAM_VERSION: 1;
+export declare function defaultSessionsDir(): string;
+export declare function openSessionStore(
+  sessionsDir: string,
+): PlaybookSessionStore;
+
+export type ReplayJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly ReplayJsonValue[]
+  | ReplayRecord;
+export type ReplayRecord = {
+  readonly [key: string]: ReplayJsonValue;
+};
+export interface ReplayStreamEntry {
+  readonly v: 1;
+  readonly seq: number;
+  readonly role?: string;
+  readonly record: ReplayRecord;
+}
+export interface ReplayStreamReadOptions {
+  readonly afterSeq?: number;
+}
+export interface ReplayStreamReadResult {
+  readonly entries: readonly ReplayStreamEntry[];
+  readonly lastReadableSeq: number;
+}
+export interface LeaseReplayStreamReadResult extends ReplayStreamReadResult {
+  readonly lastDurableSeq: number;
+  readonly incomplete: boolean;
+}
+export type ReplayStreamStatus =
+  | {
+      readonly lastReadableSeq: number;
+      readonly lastDurableSeq: number;
+      readonly incomplete: boolean;
+    }
+  | {
+      readonly lastReadableSeq: null;
+      readonly lastDurableSeq: null;
+      readonly incomplete: true;
+    };
+export interface PlaybookSessionSummary {
+  readonly schemaVersion: number;
+  readonly sessionId: string;
+  readonly state: 'settled' | 'uncertain';
+  readonly cwd: string;
+  readonly updatedAt: string;
+}
+export interface SkippedPlaybookSession {
+  readonly sessionId: string;
+  readonly reason: string;
+}
+export interface PlaybookSessionListResult {
+  readonly sessions: readonly PlaybookSessionSummary[];
+  readonly skipped: readonly SkippedPlaybookSession[];
+}
+export interface PlaybookSessionStore {
+  readonly sessionsDir: string;
+  list(): Promise<PlaybookSessionListResult>;
+  read(sessionId: string): Promise<PlaybookSessionSummary>;
+  readStream(
+    sessionId: string,
+    options?: ReplayStreamReadOptions,
+  ): Promise<ReplayStreamReadResult>;
+  acquire(sessionId: string): Promise<PlaybookSessionLease>;
+}
+export interface PlaybookSessionLease {
+  readonly sessionId: string;
+  readonly ownerToken: string;
+  append(record: object, role?: string): Promise<void>;
+  readStream(
+    options?: ReplayStreamReadOptions,
+  ): Promise<LeaseReplayStreamReadResult>;
+  streamStatus(): ReplayStreamStatus;
+  release(): Promise<ReplayStreamStatus>;
+}

package/reference/sdlc/code.playbook/session-store.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import {
+  RECORDS_STREAM_VERSION,
+  createCaptainSessionStore,
+  defaultCaptainSessionsDir,
+} from './bin/session-store.js';
+
+export { RECORDS_STREAM_VERSION };
+
+export function defaultSessionsDir() {
+  return defaultCaptainSessionsDir();
+}
+
+export function openSessionStore(sessionsDir) {
+  if (typeof sessionsDir !== 'string') {
+    throw new TypeError('session store path must be a string');
+  }
+  return wrapStore(createCaptainSessionStore({ sessionsDir }));
+}
+
+function wrapStore(store) {
+  return Object.freeze({
+    sessionsDir: store.sessionsDir,
+    list: async () => projectListResult(await store.listSummaries()),
+    read: async (sessionId) =>
+      projectSummary(await store.readSummary(sessionId)),
+    readStream: async (sessionId, options) =>
+      projectReadResult(await store.readStream(sessionId, options)),
+    acquire: async (sessionId) => wrapLease(await store.acquire(sessionId)),
+  });
+}
+
+function wrapLease(lease) {
+  let finalStatus;
+  let releaseInFlight;
+
+  const release = () => {
+    if (finalStatus !== undefined) return Promise.resolve(finalStatus);
+    if (releaseInFlight !== undefined) return releaseInFlight;
+    const operation = lease.release();
+    releaseInFlight = operation.then(
+      (status) => {
+        finalStatus = projectStatus(status);
+        return finalStatus;
+      },
+      (cause) => {
+        releaseInFlight = undefined;
+        throw cause;
+      },
+    );
+    return releaseInFlight;
+  };
+
+  return Object.freeze({
+    sessionId: lease.sessionId,
+    ownerToken: lease.ownerToken,
+    append: (record, role) => lease.append(record, role),
+    readStream: async (options) => {
+      if (finalStatus !== undefined) {
+        throw new Error('released session lease has no live replay reader');
+      }
+      return projectLeaseReadResult(await lease.readStream(options));
+    },
+    streamStatus: () => finalStatus ?? projectStatus(lease.streamStatus()),
+    release,
+  });
+}
+
+function projectListResult(result) {
+  return Object.freeze({
+    sessions: Object.freeze(result.sessions.map(projectSummary)),
+    skipped: Object.freeze(
+      result.skipped.map(({ sessionId, reason }) =>
+        Object.freeze({ sessionId, reason }),
+      ),
+    ),
+  });
+}
+
+function projectSummary(summary) {
+  return Object.freeze({
+    schemaVersion: summary.schemaVersion,
+    sessionId: summary.sessionId,
+    state: summary.state,
+    cwd: summary.cwd,
+    updatedAt: summary.updatedAt,
+  });
+}
+
+function projectReadResult(result) {
+  return Object.freeze({
+    entries: Object.freeze([...result.entries]),
+    lastReadableSeq: result.lastReadableSeq,
+  });
+}
+
+function projectLeaseReadResult(result) {
+  return Object.freeze({
+    ...projectReadResult(result),
+    lastDurableSeq: result.lastDurableSeq,
+    incomplete: result.incomplete,
+  });
+}
+
+function projectStatus(status) {
+  return Object.freeze({
+    lastReadableSeq: status.lastReadableSeq,
+    lastDurableSeq: status.lastDurableSeq,
+    incomplete: status.incomplete,
+  });
+}

package/reference/sdlc/decide.md

@@ -23,32 +23,40 @@ Consult @specs/map.md for relevant context and @specs/meta.md for spec requireme
 Do not change any files.
 ```
 
-Neither role's player shall receive the other role's proposal until both proposals are complete and Coder has committed Coder's own proposal.
+Neither role's player shall receive the other role's proposal until both proposals are complete.
+Each proposal is complete only when its player affirmatively provides a complete design proposal.
+A progress report, status update, or promise of a later proposal supports no proposal outcome.
 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:
+When both proposals are complete, Captain shall give Coder the following instruction, with the complete topic and Reviewer's complete proposal inserted under their own labels in quotes (`>`):
 
 ```markdown
-Turn your proposal into the necessary spec items or DRs.
+Synthesize your independent proposal with Reviewer's proposal below.
+Keep to the original topic below and follow what it asks.
+Keep the best, essential parts of either proposal and reject any point that is unsound, unnecessary, or outside the topic.
+Turn the resulting design into the necessary DRs and/or spec items.
 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.
+Do not change code or implement the design.
 
 Commit the result as one new commit, following @specs/packages/git.md.
 Make the commit message explain concisely what changed and why.
-Include exactly one final-response line beginning `Commit: `, followed only by the exact commit identity; other final-response content may appear on other lines.
-Coder is <coder-llm>; format the model token in conventional human form.
+Identify every new commit you make.
+Coder is <coder-llm> and Reviewer is <reviewer-llm>.
+
+> Original topic: \<caller-topic\>
+> Reviewer's independent proposal: \<reviewer-proposal\>
 ```
 
-After Coder commits, Captain shall call playbook `review`:
+No transition shall depend on a fixed presentation format of either player's reply.
+Captain shall use the repository-effect receipt as the authoritative identity of Coder's new `decide`-owned commit.
+
+After Coder commits, Captain shall call playbook `review` with the following input in quotes (`>`):
 
-> 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\>.
+> Original intent: \<caller-topic\>
+> Review scope: the `decide`-owned commit \<decide-commit\> and its resulting repository state.
+> Coder output: \<coder-output\>
 
-`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.
+`decide` is complete only when `review` returns a result that applies to the supplied review scope, gives the exact evaluated repository revision, and affirmatively establishes that no unsettled findings remain.
+It then returns the `decide`-owned commit and that evaluated revision to its caller.
+When `review` returns an authored abort or failure, or a terminal result that does not establish those facts, `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

@@ -127,6 +127,13 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
     logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
     id: string | undefined;
 }, {
+    type: "playbook.acceptedOutcome";
+    params: {
+        readonly source: string;
+        readonly target: string;
+        readonly acceptedOutcome: string;
+    };
+} | {
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 } | {

package/reference/sdlc/decide.playbook/decide.fsm.js

@@ -23,7 +23,6 @@ const COMMIT_CODER_PROMPT = [
     '',
     'Commit the result as one new commit, following @specs/packages/git.md.',
     'Make the commit message explain concisely what changed and why.',
-    'Include exactly one final-response line beginning `Commit: `, followed only by the exact commit identity; other final-response content may appear on other lines.',
     'Coder is <coder-llm>; format the model token in conventional human form.',
 ].join('\n');
 const REVIEW_INPUT_TEMPLATE = [
@@ -59,13 +58,6 @@ function commitOutput(event) {
         !isNonEmptyString(output.latestCommit)) {
         return undefined;
     }
-    const commitLines = output.coderOutput
-        .split('\n')
-        .filter((line) => line.startsWith('Commit: '));
-    if (commitLines.length !== 1 ||
-        commitLines[0] !== `Commit: ${output.latestCommit}`) {
-        return undefined;
-    }
     return {
         coderOutput: output.coderOutput,
         latestCommit: output.latestCommit,
@@ -305,6 +297,7 @@ export const decideMachine = setup({
         }),
     },
     actions: {
+        'playbook.acceptedOutcome': (_args, _params) => undefined,
         copyStartTopic: assign({
             callerTopic: ({ event }) => event.type === 'START_DECIDE' ? event.callerTopic : undefined,
             coderProposal: undefined,
@@ -514,14 +507,24 @@ export const decideMachine = setup({
                                     {
                                         guard: 'needsBossReplyWithQuestion',
                                         target: 'waiting',
-                                        actions: {
-                                            type: 'setPendingBossQuestion',
-                                            params: {
-                                                ...stateMetadata.askCoderProposal,
-                                                resumeStateId: 'askCoderProposal',
-                                                question: '',
+                                        actions: [
+                                            {
+                                                type: 'playbook.acceptedOutcome',
+                                                params: {
+                                                    source: 'askCoderProposal',
+                                                    target: 'waitCoderProposalReply',
+                                                    acceptedOutcome: 'needsBossReply',
+                                                },
                                             },
-                                        },
+                                            {
+                                                type: 'setPendingBossQuestion',
+                                                params: {
+                                                    ...stateMetadata.askCoderProposal,
+                                                    resumeStateId: 'askCoderProposal',
+                                                    question: '',
+                                                },
+                                            },
+                                        ],
                                     },
                                     {
                                         guard: 'needsBossReplyWithoutQuestion',
@@ -535,6 +538,16 @@ export const decideMachine = setup({
                                         guard: 'coderProposed',
                                         target: 'complete',
                                         actions: [
+                                            {
+                                                type: 'playbook.acceptedOutcome',
+                                                params: ({ context }) => ({
+                                                    source: 'askCoderProposal',
+                                                    target: context.stagedReviewerResult === undefined
+                                                        ? 'coderProposalComplete'
+                                                        : 'commitCoderProposal',
+                                                    acceptedOutcome: 'proposed',
+                                                }),
+                                            },
                                             'stageCoderProposal',
                                             {
                                                 type: 'clearBranchBossReplyContext',
@@ -630,14 +643,24 @@ export const decideMachine = setup({
                                     {
                                         guard: 'needsBossReplyWithQuestion',
                                         target: 'waiting',
-                                        actions: {
-                                            type: 'setPendingBossQuestion',
-                                            params: {
-                                                ...stateMetadata.askReviewerProposal,
-                                                resumeStateId: 'askReviewerProposal',
-                                                question: '',
+                                        actions: [
+                                            {
+                                                type: 'playbook.acceptedOutcome',
+                                                params: {
+                                                    source: 'askReviewerProposal',
+                                                    target: 'waitReviewerProposalReply',
+                                                    acceptedOutcome: 'needsBossReply',
+                                                },
                                             },
-                                        },
+                                            {
+                                                type: 'setPendingBossQuestion',
+                                                params: {
+                                                    ...stateMetadata.askReviewerProposal,
+                                                    resumeStateId: 'askReviewerProposal',
+                                                    question: '',
+                                                },
+                                            },
+                                        ],
                                     },
                                     {
                                         guard: 'needsBossReplyWithoutQuestion',
@@ -651,6 +674,16 @@ export const decideMachine = setup({
                                         guard: 'reviewerProposed',
                                         target: 'complete',
                                         actions: [
+                                            {
+                                                type: 'playbook.acceptedOutcome',
+                                                params: ({ context }) => ({
+                                                    source: 'askReviewerProposal',
+                                                    target: context.stagedCoderResult === undefined
+                                                        ? 'reviewerProposalComplete'
+                                                        : 'commitCoderProposal',
+                                                    acceptedOutcome: 'proposed',
+                                                }),
+                                            },
                                             'stageReviewerProposal',
                                             {
                                                 type: 'clearBranchBossReplyContext',
@@ -748,14 +781,24 @@ export const decideMachine = setup({
                     {
                         guard: 'needsBossReplyWithQuestion',
                         target: 'awaitBossReply',
-                        actions: {
-                            type: 'setPendingBossQuestion',
-                            params: {
-                                ...stateMetadata.commitCoderProposal,
-                                resumeStateId: 'commitCoderProposal',
-                                question: '',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'commitCoderProposal',
+                                    target: 'awaitBossReply',
+                                    acceptedOutcome: 'needsBossReply',
+                                },
                             },
-                        },
+                            {
+                                type: 'setPendingBossQuestion',
+                                params: {
+                                    ...stateMetadata.commitCoderProposal,
+                                    resumeStateId: 'commitCoderProposal',
+                                    question: '',
+                                },
+                            },
+                        ],
                     },
                     {
                         guard: 'needsBossReplyWithoutQuestion',
@@ -769,6 +812,14 @@ export const decideMachine = setup({
                         guard: 'committed',
                         target: 'reviewCommit',
                         actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'commitCoderProposal',
+                                    target: 'reviewCommit',
+                                    acceptedOutcome: 'committed',
+                                },
+                            },
                             'rememberCommit',
                             {
                                 type: 'clearBranchBossReplyContext',