@sublang/playbook 11.0.0 → 12.1.0

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

@@ -6,7 +6,8 @@
 // Role metadata: Coder→coder (canonical local role)
 // Boss event:    deterministic START_CODE entry; exact Boss text becomes
 //                callerInput; pending Coder questions retain BOSS_REPLY
-// Adjudication:  LLM judge per player state; coderOutput is carried verbatim
+// Adjudication:  LLM judge per player state; coderOutput is carried verbatim;
+//                the first phase decides among four semantic outcomes
 // Nested call:   literal review target through the shared bridge
 // Compat:        artifact schema 3 / runtime ABI 1
 
@@ -195,7 +196,7 @@ const runtimeSpec = {
     runFirstPhase: {
       role: 'coder',
       label:
-        'Coder is implementing one direct phase or committing a new intent record.',
+        'Coder is running the first coding phase: a direct implementation, a new intent record, or an existing intent-record task.',
     },
     runIrTask: {
       role: 'coder',
@@ -213,6 +214,23 @@ const runtimeSpec = {
           repositoryDisposition: 'one-descendant-commit',
         },
         irCommit: {
+          fields: {
+            coderOutput: 'presentation',
+            latestCommit: 'effect',
+            irNumber: 'semantic',
+          },
+          repositoryDisposition: 'one-descendant-commit',
+        },
+        moreTasks: {
+          fields: {
+            coderOutput: 'presentation',
+            latestCommit: 'effect',
+            irNumber: 'semantic',
+            irTask: 'semantic',
+          },
+          repositoryDisposition: 'one-descendant-commit',
+        },
+        finalTask: {
           fields: {
             coderOutput: 'presentation',
             latestCommit: 'effect',
@@ -231,6 +249,7 @@ const runtimeSpec = {
           fields: {
             coderOutput: 'presentation',
             latestCommit: 'effect',
+            irNumber: 'semantic',
             irTask: 'semantic',
           },
           repositoryDisposition: 'one-descendant-commit',
@@ -239,6 +258,8 @@ const runtimeSpec = {
           fields: {
             coderOutput: 'presentation',
             latestCommit: 'effect',
+            irNumber: 'semantic',
+            irTask: 'semantic',
           },
           repositoryDisposition: 'one-descendant-commit',
         },

package/reference/sdlc/code.playbook/host-capabilities.d.ts

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type PlaybookRepositoryDisposition =
+  | 'unchanged'
+  | 'one-descendant-commit'
+  | 'deferred';
+export type RepositoryReceiptClassification =
+  | 'unchanged'
+  | 'one-descendant-commit'
+  | 'multiple-commits'
+  | 'rewritten-or-non-descendant'
+  | 'worktree-only-change'
+  | 'concurrent-or-foreign-change'
+  | 'observation-ambiguous';
+export declare const REPOSITORY_RECEIPT_CLASSIFICATIONS: readonly RepositoryReceiptClassification[];
+
+export interface RepositoryIdentity {
+  readonly worktree: string;
+  readonly gitDir: string;
+}
+export interface PlaybookRepositoryObservation extends RepositoryIdentity {
+  readonly head: string;
+  readonly projection: Readonly<Record<string, JsonValue>>;
+  readonly projectionDigest: string;
+}
+export interface PlaybookRepositoryReceipt {
+  readonly classification: RepositoryReceiptClassification;
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly commitOid?: string;
+}
+export interface RepositoryReceiptOptions {
+  readonly allowedDispositions: readonly PlaybookRepositoryDisposition[];
+}
+
+export declare function observeGitRepository(
+  cwd: string,
+): Promise<PlaybookRepositoryObservation>;
+export declare function classifyRepositoryReceipt(
+  baseline: PlaybookRepositoryObservation,
+  after: PlaybookRepositoryObservation,
+  options: RepositoryReceiptOptions,
+): Promise<PlaybookRepositoryReceipt>;
+export declare function captureRepositoryReceipt(
+  baseline: PlaybookRepositoryObservation,
+  options: RepositoryReceiptOptions,
+): Promise<PlaybookRepositoryReceipt>;
+
+export interface PlaybookPendingBossQuestion {
+  readonly questionId: string;
+  readonly asker:
+    | { readonly kind: 'captain' }
+    | { readonly kind: 'role'; readonly roleId: string };
+  readonly question: string;
+  readonly sourceItem?: string;
+}
+export interface PlaybookEffectBoundary {
+  readonly sequence: number;
+  readonly boundaryId: string;
+  readonly attemptId: string;
+  readonly attemptNumber: number;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly turnId: number;
+  readonly callId: string;
+  readonly roleId: string;
+  readonly sourceStateId: string;
+  readonly sourceOutcomeSchema: JsonValue;
+  readonly dispositions: readonly PlaybookRepositoryDisposition[];
+  readonly canonicalWorktree: RepositoryIdentity;
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly physicalReceipt?: PlaybookRepositoryReceipt;
+  readonly finalText?: string;
+  readonly semanticCandidate?: JsonValue;
+  readonly initialSemanticCandidate?: JsonValue;
+  readonly correctionBudget: {
+    readonly limit: 1;
+    readonly spent: boolean;
+  };
+  readonly cohortId?: string;
+  readonly logicalOperationId?: string;
+}
+export type PlaybookEffectBoundaryStart = Omit<
+  PlaybookEffectBoundary,
+  | 'sequence'
+  | 'attemptId'
+  | 'attemptNumber'
+  | 'after'
+  | 'physicalReceipt'
+  | 'finalText'
+  | 'semanticCandidate'
+  | 'initialSemanticCandidate'
+>;
+export type EffectBoundarySeed = Omit<
+  PlaybookEffectBoundaryStart,
+  'playbookId' | 'canonicalWorktree' | 'baseline' | 'cohortId'
+>;
+export interface PlaybookEffectLogicalOperation {
+  readonly sequence: number;
+  readonly operationId: string;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly boundaryIds: readonly string[];
+  readonly originalBaseline: PlaybookRepositoryObservation;
+  readonly checkpoint?: PlaybookRepositoryObservation;
+  readonly pendingQuestion?: PlaybookPendingBossQuestion;
+  readonly playerContinuation?: JsonValue;
+  readonly checkpointRestorationEligible: boolean;
+  readonly logicalReceipt?: PlaybookRepositoryReceipt;
+}
+export interface PlaybookEffectLedger {
+  readonly schemaVersion: 1;
+  readonly revision: number;
+  readonly boundaries: readonly PlaybookEffectBoundary[];
+  readonly logicalOperations: readonly PlaybookEffectLogicalOperation[];
+}
+export type PlaybookEffectLedgerCommand =
+  | {
+      readonly kind: 'start-boundaries';
+      readonly boundaries: readonly [
+        PlaybookEffectBoundaryStart,
+        ...PlaybookEffectBoundaryStart[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-boundaries';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        },
+        ...{
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        }[],
+      ];
+    }
+  | {
+      readonly kind: 'append-logical-operations';
+      readonly operations: readonly [
+        Omit<PlaybookEffectLogicalOperation, 'sequence'>,
+        ...Omit<PlaybookEffectLogicalOperation, 'sequence'>[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-logical-operations';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        },
+        ...{
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        }[],
+      ];
+    };
+export type PlaybookEffectLedgerCommandBatch = readonly [
+  PlaybookEffectLedgerCommand,
+  ...PlaybookEffectLedgerCommand[],
+];
+export interface PlaybookEffectLedgerCapability {
+  snapshot(): PlaybookEffectLedger;
+  writeAhead(
+    commands: PlaybookEffectLedgerCommandBatch,
+  ): Promise<PlaybookEffectLedger>;
+}
+
+interface RepositoryOperationSettlement<T> {
+  readonly status: 'fulfilled';
+  readonly value: T;
+}
+interface RepositoryOperationRejection {
+  readonly status: 'rejected';
+  readonly reason: unknown;
+}
+export interface RepositoryExclusiveCompletion<T> {
+  readonly boundary: PlaybookEffectBoundary;
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly outcomeReceipt: PlaybookRepositoryReceipt;
+}
+interface RepositoryDeferredBinding {
+  readonly operationId: string;
+  readonly pendingQuestion: PlaybookPendingBossQuestion;
+  readonly playerContinuation: JsonValue;
+}
+export interface RepositoryCompletionEvidence {
+  readonly finalText?: string;
+  readonly semanticCandidate?: JsonValue;
+  readonly deferred?: RepositoryDeferredBinding;
+  readonly unresolved?: true;
+}
+export interface RepositoryExclusiveResult<T> {
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly effectLedger: PlaybookEffectLedger;
+  readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface RepositoryDeferredContinuationResult<T> {
+  readonly status: 'continued';
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly logicalReceipt?: PlaybookRepositoryReceipt;
+  readonly effectLedger: PlaybookEffectLedger;
+  readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface RepositoryDeferredCheckpointMismatch {
+  readonly status: 'checkpoint-mismatch' | 'ineligible';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+interface RepositoryDeferredParked {
+  readonly status: 'parked';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+interface RepositoryDeferredRestoreResult {
+  readonly status: 'restored' | 'checkpoint-mismatch' | 'ineligible';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+export interface RepositoryCapability {
+  runExclusive<T>(options: {
+    readonly signal?: AbortSignal;
+    readonly effectBoundary: EffectBoundarySeed;
+    readonly operation: (context: {
+      readonly baseline: PlaybookRepositoryObservation;
+      readonly identity: RepositoryIdentity;
+    }) => Promise<T>;
+    readonly completeEffectBoundary: (
+      completion: RepositoryExclusiveCompletion<T>,
+    ) => RepositoryCompletionEvidence | Promise<RepositoryCompletionEvidence>;
+  }): Promise<RepositoryExclusiveResult<T>>;
+  runDeferred<T>(options: {
+    readonly mode: 'continue';
+    readonly signal?: AbortSignal;
+    readonly operationId: string;
+    readonly effectBoundary: EffectBoundarySeed;
+    readonly operation: (context: {
+      readonly baseline: PlaybookRepositoryObservation;
+      readonly identity: RepositoryIdentity;
+      readonly playerContinuation: JsonValue;
+    }) => Promise<T>;
+    readonly completeEffectBoundary: (
+      completion: RepositoryExclusiveCompletion<T>,
+    ) => RepositoryCompletionEvidence | Promise<RepositoryCompletionEvidence>;
+  }): Promise<
+    RepositoryDeferredContinuationResult<T> | RepositoryDeferredCheckpointMismatch
+  >;
+  runDeferred(options: {
+    readonly mode: 'park' | 'restore';
+    readonly signal?: AbortSignal;
+    readonly operationId: string;
+  }): Promise<RepositoryDeferredParked | RepositoryDeferredRestoreResult>;
+}
+export interface HostCapabilities {
+  readonly repository: RepositoryCapability;
+  readonly effectLedger: PlaybookEffectLedgerCapability;
+}
+export interface WorktreeRepositoryCapability extends RepositoryCapability {
+  readonly identity: RepositoryIdentity;
+  observe(): Promise<PlaybookRepositoryObservation>;
+}
+export interface WorktreeHostCapabilities extends HostCapabilities {
+  readonly repository: WorktreeRepositoryCapability;
+}
+export interface WorktreeHostCapabilitiesOptions {
+  readonly cwd: string;
+  readonly playbookId: string;
+  readonly requiredRoleIds: readonly string[];
+  readonly concurrentRoleSets?: readonly (readonly string[])[];
+  readonly effectLedger?: PlaybookEffectLedger;
+}
+export declare function createWorktreeHostCapabilities(
+  options: WorktreeHostCapabilitiesOptions,
+): Promise<WorktreeHostCapabilities>;
+export declare function createFailClosedHostCapabilities(): HostCapabilities;

package/reference/sdlc/code.playbook/host-capabilities.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// DR-046: the public `@sublang/playbook/host-capabilities` facade. Every
+// member is the CLI host's own repository-effect implementation; this module
+// only narrows the accepted arguments to the declared surface.
+
+import {
+  REPOSITORY_RECEIPT_CLASSIFICATIONS,
+  captureRepositoryReceipt as capture,
+  classifyRepositoryReceipt as classify,
+  createFailClosedHostCapabilities,
+  createWorktreeHostCapabilities,
+  observeGitRepository as observe,
+} from './bin/repository-effects.js';
+
+export {
+  REPOSITORY_RECEIPT_CLASSIFICATIONS,
+  createFailClosedHostCapabilities,
+  createWorktreeHostCapabilities,
+};
+
+export async function observeGitRepository(cwd) {
+  return observe(cwd);
+}
+
+export async function classifyRepositoryReceipt(baseline, after, options) {
+  return classify(baseline, after, receiptOptions(options));
+}
+
+export async function captureRepositoryReceipt(baseline, options) {
+  return capture(baseline, receiptOptions(options));
+}
+
+function receiptOptions(options) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('repository receipt options must be an object');
+  }
+  return { allowedDispositions: options.allowedDispositions };
+}

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

@@ -63,13 +63,24 @@ players:
     permissions:
       mode: auto
 
+  # DEV's planner stays a distinct player: equal ids deliberately share one
+  # provider conversation, and planning context must not bleed into review
+  # conversations (DR-044).
+  dev.analyst:
+    adapter: claude
+    model: claude-opus-5
+    effort: xhigh
+    permissions:
+      mode: auto
+
 # Enabled playbooks. Each is loaded from its explicit `from` module; the
 # `<id>` key must equal that module's manifest id. `from`, `command`, and
 # `roles` are launcher-owned; every other key is that playbook's option
 # slice.
 #
-# Every manifest role is bound explicitly. These three playbooks intentionally
-# reuse the same two stable players; change an id to isolate its conversation.
+# Every manifest role is bound explicitly. CODE, REVIEW, and DECIDE
+# intentionally reuse the same two stable players, while DEV keeps its own
+# Analyst; change an id to isolate its conversation.
 playbooks:
   code:
     from: "@sublang/playbook/code/registry"
@@ -87,3 +98,8 @@ playbooks:
     roles:
       coder: dev.coder
       reviewer: dev.reviewer
+
+  dev:
+    from: "@sublang/playbook/dev/registry"
+    roles:
+      analyst: dev.analyst

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

@@ -19,7 +19,12 @@ type PendingBossQuestions = Partial<Record<ResumableStateId, PendingBossQuestion
 type BossReplies = Partial<Record<ResumableStateId, string>>;
 type PendingBossQuestionParams = Omit<PendingBossQuestion, 'questionId'>;
 export interface ReviewSuccessOutput {
-    approvedCommit: 'latest';
+    evaluatedRevision: string;
+    noUnsettledFindings: true;
+}
+export interface DecideSuccessOutput {
+    decideCommit: string;
+    evaluatedRevision: string;
     noUnsettledFindings: true;
 }
 export interface DecideFailureOutput {
@@ -31,7 +36,7 @@ export interface DecideFailureOutput {
         message: string;
     };
 }
-export type DecideOutput = ReviewSuccessOutput | DecideFailureOutput;
+export type DecideOutput = DecideSuccessOutput | DecideFailureOutput;
 interface ChildFailure {
     status: 'aborted' | 'error';
     playbookId: 'review';
@@ -45,6 +50,7 @@ export interface DecideContext {
     coderProposal?: string;
     reviewerProposal?: string;
     latestCommit?: string;
+    coderOutput?: string;
     reviewResult?: ReviewSuccessOutput;
     reviewFailure?: ChildFailure;
     lastResult?: PlayerOutput;
@@ -74,6 +80,7 @@ export interface PlayerInput {
     result: Record<string, string>;
     role: Role;
     callerTopic?: string;
+    reviewerProposal?: string;
     pendingBossQuestion?: PendingBossQuestion;
     bossReply?: string;
 }
@@ -139,9 +146,6 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
 } | {
     type: "rememberBossReply";
     params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "clearBossReplyContext";
-    params: import("xstate").NonReducibleUnknown;
 } | {
     type: "copyInterruptedTopic";
     params: import("xstate").NonReducibleUnknown;
@@ -186,6 +190,9 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
 } | {
     type: "clearProposalRoundContext";
     params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "clearBossReplyContext";
+    params: import("xstate").NonReducibleUnknown;
 }, {
     type: "authoredReviewFailure";
     params: unknown;
@@ -212,7 +219,7 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
         coder: "complete" | "working" | "waiting";
         reviewer: "complete" | "working" | "waiting";
     };
-}, string, Readonly<Record<string, never>>, ReviewSuccessOutput | DecideFailureOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+}, string, Readonly<Record<string, never>>, DecideSuccessOutput | DecideFailureOutput, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "decide";
     states: {
         readonly ready: {

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

@@ -15,30 +15,40 @@ const INDEPENDENT_PROPOSAL_PROMPT = [
     'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
     'Do not change any files.',
 ].join('\n');
-const COMMIT_CODER_PROMPT = [
-    'Turn your proposal into the necessary spec items or DRs.',
+const SYNTHESIZE_COMMIT_PROMPT = [
+    "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.',
-    '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>",
 ].join('\n');
 const REVIEW_INPUT_TEMPLATE = [
-    '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>',
 ].join('\n');
-function composeReviewInput(callerTopic, coderProposal) {
+function composeReviewInput(callerTopic, decideCommit, coderOutput) {
     const fields = {
         '<caller-topic>': callerTopic ?? '',
-        '<coder-proposal>': coderProposal ?? '',
+        '<decide-commit>': decideCommit ?? '',
+        '<coder-output>': coderOutput ?? '',
     };
-    return REVIEW_INPUT_TEMPLATE.replace(/<caller-topic>|<coder-proposal>/g, (placeholder) => fields[placeholder]);
+    return REVIEW_INPUT_TEMPLATE.replace(/<caller-topic>|<decide-commit>|<coder-output>/g, (placeholder, offset, source) => {
+        const value = fields[placeholder];
+        const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
+        return source.slice(lineStart, offset).startsWith('> ')
+            ? value.replaceAll('\n', '\n> ')
+            : value;
+    });
 }
 const outputOf = (event) => event.output;
 const playbookOutputOf = (event) => event.output;
@@ -170,19 +180,23 @@ function isPlaybookState(value) {
                 value.activeStateIds.length === 1 &&
                 value.activeStateIds[0] === value.stateId)));
 }
+// DECIDE supplied `review` a scope rooted at the `decide`-owned commit, so a
+// result applies to that scope only when it is the exact declared terminal
+// contract: the evaluated repository revision plus the affirmative
+// no-unsettled-findings fact. Any other shape does not establish those facts.
 function reviewSuccessFrom(event) {
     const output = playbookOutputOf(event);
     if (!isPlainRecord(output))
         return undefined;
-    if (!isExactKeys(output, ['approvedCommit', 'noUnsettledFindings'])) {
+    if (!isExactKeys(output, ['evaluatedRevision', 'noUnsettledFindings'])) {
         return undefined;
     }
-    if (output.approvedCommit !== 'latest' ||
+    if (!isNonEmptyString(output.evaluatedRevision) ||
         output.noUnsettledFindings !== true) {
         return undefined;
     }
     return {
-        approvedCommit: 'latest',
+        evaluatedRevision: output.evaluatedRevision,
         noUnsettledFindings: true,
     };
 }
@@ -303,6 +317,7 @@ export const decideMachine = setup({
             coderProposal: undefined,
             reviewerProposal: undefined,
             latestCommit: undefined,
+            coderOutput: undefined,
             reviewResult: undefined,
             reviewFailure: undefined,
             lastResult: undefined,
@@ -317,6 +332,7 @@ export const decideMachine = setup({
             coderProposal: undefined,
             reviewerProposal: undefined,
             latestCommit: undefined,
+            coderOutput: undefined,
             reviewResult: undefined,
             reviewFailure: undefined,
             lastResult: undefined,
@@ -346,6 +362,7 @@ export const decideMachine = setup({
         }),
         rememberCommit: assign({
             latestCommit: ({ event }) => outputOf(event).latestCommit,
+            coderOutput: ({ event }) => outputOf(event).coderOutput,
             lastResult: ({ event }) => outputOf(event),
             lastError: undefined,
         }),
@@ -364,7 +381,7 @@ export const decideMachine = setup({
                 playbookId: 'review',
                 error: {
                     name: 'ReviewProtocolError',
-                    message: 'REVIEW returned without an approved latest commit and a no-findings result.',
+                    message: 'REVIEW returned without the evaluated repository revision and a no-unsettled-findings result for the supplied scope.',
                 },
             },
             lastError: undefined,
@@ -429,8 +446,16 @@ export const decideMachine = setup({
     initial: 'ready',
     context: () => ({}),
     output: ({ context }) => {
-        if (context.reviewResult)
-            return context.reviewResult;
+        if (context.reviewResult) {
+            if (!context.latestCommit) {
+                throw new Error('DECIDE completed without its decide-owned commit');
+            }
+            return {
+                decideCommit: context.latestCommit,
+                evaluatedRevision: context.reviewResult.evaluatedRevision,
+                noUnsettledFindings: true,
+            };
+        }
         if (!context.latestCommit || !context.reviewFailure) {
             throw new Error('DECIDE reached a final state without a result');
         }
@@ -498,7 +523,7 @@ export const decideMachine = setup({
                                     role: 'coder',
                                     prompt: INDEPENDENT_PROPOSAL_PROMPT,
                                     result: withNeedsBossReply({
-                                        proposed: 'Coder completed an independent proposal. Output shall include `coderProposal: <verbatim final text>`.',
+                                        proposed: 'Coder affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `coderProposal: <verbatim final text>`.',
                                     }),
                                     callerTopic: context.callerTopic,
                                     ...bossReplyFields(context, 'askCoderProposal'),
@@ -634,7 +659,7 @@ export const decideMachine = setup({
                                     role: 'reviewer',
                                     prompt: INDEPENDENT_PROPOSAL_PROMPT,
                                     result: withNeedsBossReply({
-                                        proposed: 'Reviewer completed an independent proposal. Output shall include `reviewerProposal: <verbatim final text>`.',
+                                        proposed: 'Reviewer affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `reviewerProposal: <verbatim final text>`.',
                                     }),
                                     callerTopic: context.callerTopic,
                                     ...bossReplyFields(context, 'askReviewerProposal'),
@@ -757,11 +782,11 @@ export const decideMachine = setup({
         commitCoderProposal: {
             id: 'commitCoderProposal',
             tags: 'playbook.busy',
-            description: 'Coder writes and commits Coder’s independent proposal.',
+            description: 'Coder synthesizes both proposals and commits the design.',
             meta: {
                 playbook: {
                     stateId: 'commitCoderProposal',
-                    description: 'Coder writes and commits Coder’s independent proposal.',
+                    description: 'Coder synthesizes both proposals and commits the design.',
                     role: 'coder',
                 },
             },
@@ -771,10 +796,12 @@ export const decideMachine = setup({
                     stateId: 'commitCoderProposal',
                     sourceItem: 'DECIDE-3',
                     role: 'coder',
-                    prompt: COMMIT_CODER_PROMPT,
+                    prompt: SYNTHESIZE_COMMIT_PROMPT,
                     result: withNeedsBossReply({
-                        committed: "Coder committed Coder's proposal. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
+                        committed: 'Coder synthesized both proposals and committed the resulting design as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
                     }),
+                    callerTopic: context.callerTopic,
+                    reviewerProposal: context.reviewerProposal,
                     ...bossReplyFields(context, 'commitCoderProposal'),
                 }),
                 onDone: [
@@ -881,7 +908,7 @@ export const decideMachine = setup({
                     stateId: 'reviewCommit',
                     sourceItem: 'DECIDE-4',
                     playbookId: 'review',
-                    text: composeReviewInput(context.callerTopic, context.coderProposal),
+                    text: composeReviewInput(context.callerTopic, context.latestCommit, context.coderOutput),
                 }),
                 onDone: [
                     {