@sublang/playbook 15.1.0 → 17.0.0

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

@@ -1,20 +1,56 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-// FSM object artifact compiled from decide.gears.md.
-// This module defines only the machine, actor contracts, and typed inputs.
-// The linked runtime supplies the player and nested-playbook actors.
+//
+// FSM object artifact compiled from ./decide.gears.md by gears2fsm.
+// It declares only the machine, its actor contracts, and typed inputs; the
+// linked runtime supplies the `player` and `playbook` actor implementations.
 import { assign, fromPromise, setup } from 'xstate';
-export const concurrentRoleSets = [['coder', 'reviewer']];
+import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+/**
+ * One role-id array per parallel group, in first-item source order; the inner
+ * array follows the `independent-proposals` item order (DECIDE-1, DECIDE-2).
+ */
+export const concurrentRoleSets = [
+    ['coder', 'reviewer'],
+];
+/** The literal nested-call target of DECIDE-4. */
+const REVIEW_PLAYBOOK_ID = 'review';
+const RESUMABLE_STATES = {
+    askCoderProposal: { sourceItem: 'DECIDE-1', roleId: 'coder' },
+    askReviewerProposal: { sourceItem: 'DECIDE-2', roleId: 'reviewer' },
+    synthesizeCommit: { sourceItem: 'DECIDE-3', roleId: 'coder' },
+};
+// ---------------------------------------------------------------------------
+// Prompts (each item's blockquote, verbatim) and local result contracts
+// ---------------------------------------------------------------------------
 const NEEDS_BOSS_REPLY_DESCRIPTION = "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
-const INDEPENDENT_PROPOSAL_PROMPT = [
-    '> Original topic: <caller-topic>',
+/** DECIDE-1 blockquote; `<caller-topic>` is carried as `callerTopic`. */
+const CODER_PROPOSAL_PROMPT = [
+    '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.',
     '',
+    '> Original topic: <caller-topic>',
+].join('\n');
+/** DECIDE-2 blockquote; `<caller-topic>` is carried as `callerTopic`. */
+const REVIEWER_PROPOSAL_PROMPT = [
     '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.',
+    '',
+    '> Original topic: <caller-topic>',
 ].join('\n');
+/**
+ * DECIDE-3 blockquote. `<caller-topic>` is carried as `callerTopic` and
+ * `<reviewer-proposal>` as `reviewerProposal`. `<coder-llm>` and
+ * `<reviewer-llm>` are local-role prompt identities of Coder and Reviewer: the
+ * linker resolves them through the invocation-scoped `promptIdentity(roleId)`
+ * lookup, so they stay literal here and have no machine or actor-input field.
+ */
 const SYNTHESIZE_COMMIT_PROMPT = [
     "Synthesize your independent proposal with Reviewer's proposal below.",
     'Keep to the original topic below and follow what it asks.',
@@ -31,270 +67,460 @@ const SYNTHESIZE_COMMIT_PROMPT = [
     '> Original topic: <caller-topic>',
     "> Reviewer's independent proposal: <reviewer-proposal>",
 ].join('\n');
-const REVIEW_INPUT_TEMPLATE = [
+const CODER_PROPOSAL_RESULT = {
+    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>`.',
+    needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+};
+const REVIEWER_PROPOSAL_RESULT = {
+    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>`.',
+    needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+};
+const SYNTHESIZE_COMMIT_RESULT = {
+    committed: 'Coder synthesized the proposals into the necessary DRs and/or spec items and committed the result as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
+    needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+};
+/** DECIDE-4 blockquote: the `review` call-text template, verbatim. */
+const REVIEW_COMMIT_TEMPLATE = [
     '> Original intent: <caller-topic>',
     '> Review scope: the `decide`-owned commit <decide-commit> and its resulting repository state.',
+    "> Coder's independent proposal: <coder-proposal>",
     '> Coder output: <coder-output>',
 ].join('\n');
-function composeReviewInput(callerTopic, decideCommit, coderOutput) {
-    const fields = {
-        '<caller-topic>': callerTopic ?? '',
-        '<decide-commit>': decideCommit ?? '',
-        '<coder-output>': coderOutput ?? '',
+// ---------------------------------------------------------------------------
+// State descriptions and public metadata
+// ---------------------------------------------------------------------------
+const STATE_DESCRIPTIONS = {
+    ready: 'Waiting for the caller to give a topic to decide.',
+    independentProposals: 'Coder and Reviewer independently propose designs for the topic in parallel.',
+    coderProposalRegion: "Coder's independent proposal branch.",
+    askCoderProposal: 'Coder is independently proposing a design for the topic.',
+    awaitCoderProposalReply: "Waiting for Boss to answer Coder's question about its independent proposal.",
+    coderProposalStaged: "Coder's independent proposal is complete and staged for the join.",
+    reviewerProposalRegion: "Reviewer's independent proposal branch.",
+    askReviewerProposal: 'Reviewer is independently proposing a design for the topic.',
+    awaitReviewerProposalReply: "Waiting for Boss to answer Reviewer's question about its independent proposal.",
+    reviewerProposalStaged: "Reviewer's independent proposal is complete and staged for the join.",
+    synthesizeCommit: 'Coder synthesizes both proposals into the necessary DRs and/or spec items and commits the result as one new commit.',
+    awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+    reviewCommit: 'The review playbook examines the decide-owned commit.',
+    failed: 'DECIDE parked after a control-plane failure and waits for Boss to restart or resume it.',
+    reportedReviewFailure: "DECIDE reported review's abort, failure, or unestablished result to its caller with the last decide-owned commit.",
+    done: 'DECIDE completed: review established no unsettled findings for the decide-owned commit at the reported evaluated revision.',
+};
+function playbookMeta(stateId, role) {
+    return {
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            ...(role === undefined ? {} : { role }),
+        },
     };
-    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;
-const isNonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0;
-const coderProposed = ({ event }) => {
-    const output = outputOf(event);
-    return output.guard === 'proposed' && isNonEmptyString(output.coderProposal);
-};
-const reviewerProposed = ({ event }) => {
-    const output = outputOf(event);
-    return (output.guard === 'proposed' && isNonEmptyString(output.reviewerProposal));
-};
-function commitOutput(event) {
-    const output = outputOf(event);
-    if (output.guard !== 'committed' ||
-        !isNonEmptyString(output.coderOutput) ||
-        !isNonEmptyString(output.latestCommit)) {
-        return undefined;
-    }
+function terminalMeta(stateId, terminal) {
     return {
-        coderOutput: output.coderOutput,
-        latestCommit: output.latestCommit,
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            terminal,
+        },
     };
 }
-const committed = ({ event }) => commitOutput(event) !== undefined;
-const needsBossReplyWithQuestion = ({ event }) => {
-    const output = outputOf(event);
-    return output.guard === 'needsBossReply' && isNonEmptyString(output.question);
-};
-const needsBossReplyWithoutQuestion = ({ event }) => {
-    const output = outputOf(event);
-    return (output.guard === 'needsBossReply' && !isNonEmptyString(output.question));
-};
-const pendingQuestionIds = (context) => Object.keys(context.pendingBossQuestions ?? {});
-const resolvedQuestionId = (context, event) => {
-    if (event.type !== 'BOSS_REPLY')
-        return undefined;
-    if (event.questionId)
-        return event.questionId;
-    const ids = pendingQuestionIds(context);
-    return ids.length === 1 ? ids[0] : undefined;
-};
-const bossReplyTargets = (stateId, requireAnswer) => ({ context, event }) => event.type === 'BOSS_REPLY' &&
-    resolvedQuestionId(context, event) === stateId &&
-    (requireAnswer
-        ? event.answer.trim().length > 0
-        : event.answer.trim().length === 0);
-const bossReplyFields = (context, stateId) => ({
-    ...(context.pendingBossQuestions?.[stateId]
-        ? { pendingBossQuestion: context.pendingBossQuestions[stateId] }
-        : {}),
-    ...(context.bossReplies?.[stateId]
-        ? { bossReply: context.bossReplies[stateId] }
-        : {}),
-});
-const withoutKey = (record, stateId) => {
-    if (!record || record[stateId] === undefined)
-        return record;
-    const next = { ...record };
-    delete next[stateId];
-    return Object.keys(next).length > 0 ? next : undefined;
-};
-const withNeedsBossReply = (result) => ({
-    ...result,
-    needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
-});
-const isPlainRecord = (value) => typeof value === 'object' &&
-    value !== null &&
-    !Array.isArray(value) &&
-    (Object.getPrototypeOf(value) === Object.prototype ||
-        Object.getPrototypeOf(value) === null);
-const isExactKeys = (value, keys) => {
-    const ownKeys = Reflect.ownKeys(value);
-    return (ownKeys.length === keys.length &&
-        ownKeys.every((key) => typeof key === 'string' && keys.includes(key)));
-};
-function isStateValue(value, ancestors = new Set()) {
-    if (typeof value === 'string')
-        return true;
-    if (!isPlainRecord(value) || ancestors.has(value))
+// ---------------------------------------------------------------------------
+// Structural narrowing helpers
+// ---------------------------------------------------------------------------
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isPlainRecord(value) {
+    if (!isObject(value) || Array.isArray(value))
         return false;
-    const next = new Set(ancestors).add(value);
-    return Reflect.ownKeys(value).every((key) => typeof key === 'string' &&
-        Object.prototype.propertyIsEnumerable.call(value, key) &&
-        isStateValue(value[key], next));
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
 }
-function isStringArray(value) {
-    return (Array.isArray(value) &&
-        Reflect.ownKeys(value).length === value.length + 1 &&
-        Reflect.ownKeys(value).every((key) => {
-            if (key === 'length')
-                return true;
-            return (typeof key === 'string' &&
-                /^(0|[1-9][0-9]*)$/.test(key) &&
-                Number(key) < value.length);
-        }) &&
-        value.every((entry) => isNonEmptyString(entry)) &&
-        new Set(value).size === value.length);
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
 }
-function isPlaybookState(value) {
-    if (!isPlainRecord(value))
-        return false;
-    const allowed = new Set([
-        'value',
-        'activeStateIds',
-        'tags',
-        'status',
-        'quiescent',
-        'stateId',
-    ]);
-    if (Reflect.ownKeys(value).some((key) => typeof key !== 'string' || !allowed.has(key)) ||
-        !Object.prototype.hasOwnProperty.call(value, 'value') ||
-        !Object.prototype.hasOwnProperty.call(value, 'activeStateIds') ||
-        !Object.prototype.hasOwnProperty.call(value, 'tags') ||
-        !Object.prototype.hasOwnProperty.call(value, 'status') ||
-        !Object.prototype.hasOwnProperty.call(value, 'quiescent')) {
-        return false;
-    }
-    return (isStateValue(value.value) &&
-        isStringArray(value.activeStateIds) &&
-        isStringArray(value.tags) &&
-        (value.status === 'active' ||
-            value.status === 'done' ||
-            value.status === 'error' ||
-            value.status === 'stopped') &&
-        typeof value.quiescent === 'boolean' &&
-        (!Object.prototype.hasOwnProperty.call(value, 'stateId') ||
-            (isNonEmptyString(value.stateId) &&
-                value.activeStateIds.length === 1 &&
-                value.activeStateIds[0] === value.stateId)));
+function isResumableStateId(value) {
+    return (value === 'askCoderProposal' ||
+        value === 'askReviewerProposal' ||
+        value === 'synthesizeCommit');
 }
-// 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, ['evaluatedRevision', 'noUnsettledFindings'])) {
+/** The actor's `output`, narrowed structurally from an unknown done event. */
+function actorOutput(event) {
+    if (!isObject(event))
         return undefined;
+    const output = event.output;
+    return isPlainRecord(output) ? output : undefined;
+}
+function outputString(event, field) {
+    const value = actorOutput(event)?.[field];
+    return isNonEmptyString(value) ? value : undefined;
+}
+function outputGuardIs(event, guard) {
+    return actorOutput(event)?.guard === guard;
+}
+/** The actor's `error`, narrowed structurally from an unknown error event. */
+function actorError(event) {
+    return isObject(event) ? event.error : undefined;
+}
+/** Normalizes any thrown or malformed value to a JSON-safe error record. */
+function errorRecord(value) {
+    if (value instanceof Error) {
+        return {
+            name: isNonEmptyString(value.name) ? value.name : 'Error',
+            message: typeof value.message === 'string' ? value.message : '',
+            ...(typeof value.stack === 'string' ? { stack: value.stack } : {}),
+        };
     }
-    if (!isNonEmptyString(output.evaluatedRevision) ||
-        output.noUnsettledFindings !== true) {
-        return undefined;
+    if (isObject(value) && typeof value.message === 'string') {
+        return {
+            name: isNonEmptyString(value.name) ? value.name : 'Error',
+            message: value.message,
+        };
     }
     return {
-        evaluatedRevision: output.evaluatedRevision,
-        noUnsettledFindings: true,
+        name: 'Error',
+        message: typeof value === 'string'
+            ? value
+            : 'The actor failed with a non-Error value.',
     };
 }
-const validReviewSuccess = ({ event }) => reviewSuccessFrom(event) !== undefined;
-function normalizedChildFailure(error) {
+function withoutKey(record, stateId) {
+    const next = {};
+    for (const key of Object.keys(record)) {
+        if (!isResumableStateId(key) || key === stateId)
+            continue;
+        const value = record[key];
+        if (value !== undefined)
+            next[key] = value;
+    }
+    return next;
+}
+/**
+ * Strict JSON validation: null, booleans, finite numbers, strings, exact
+ * arrays, and plain records of enumerable own data properties. Cycle
+ * detection tracks only the active recursion path.
+ */
+function isJsonValue(value, path = new Set()) {
+    if (value === null)
+        return true;
+    switch (typeof value) {
+        case 'boolean':
+        case 'string':
+            return true;
+        case 'number':
+            return Number.isFinite(value);
+        case 'object':
+            break;
+        default:
+            return false;
+    }
+    const container = value;
+    if (path.has(container))
+        return false;
+    path.add(container);
+    try {
+        if (Array.isArray(container)) {
+            if (Object.getPrototypeOf(container) !== Array.prototype)
+                return false;
+            const keys = Reflect.ownKeys(container);
+            if (keys.length !== container.length + 1)
+                return false;
+            const lengthDescriptor = Object.getOwnPropertyDescriptor(container, 'length');
+            if (lengthDescriptor === undefined ||
+                lengthDescriptor.configurable !== false ||
+                lengthDescriptor.enumerable !== false ||
+                lengthDescriptor.value !== container.length) {
+                return false;
+            }
+            for (let index = 0; index < container.length; index += 1) {
+                const descriptor = Object.getOwnPropertyDescriptor(container, String(index));
+                if (descriptor === undefined ||
+                    !descriptor.enumerable ||
+                    !('value' in descriptor) ||
+                    !isJsonValue(descriptor.value, path)) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        const prototype = Object.getPrototypeOf(container);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        for (const key of Reflect.ownKeys(container)) {
+            if (typeof key !== 'string')
+                return false;
+            const descriptor = Object.getOwnPropertyDescriptor(container, key);
+            if (descriptor === undefined ||
+                !descriptor.enumerable ||
+                !('value' in descriptor) ||
+                !isJsonValue(descriptor.value, path)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    finally {
+        path.delete(container);
+    }
+}
+// ---------------------------------------------------------------------------
+// Actor-output narrowing (declared per-state result contracts)
+// ---------------------------------------------------------------------------
+function isCoderProposed(event) {
+    return (outputGuardIs(event, 'proposed') &&
+        outputString(event, 'coderProposal') !== undefined);
+}
+function isReviewerProposed(event) {
+    return (outputGuardIs(event, 'proposed') &&
+        outputString(event, 'reviewerProposal') !== undefined);
+}
+function isCommitted(event) {
+    return (outputGuardIs(event, 'committed') &&
+        outputString(event, 'coderOutput') !== undefined &&
+        outputString(event, 'latestCommit') !== undefined);
+}
+function isNeedsBossReply(event) {
+    return (outputGuardIs(event, 'needsBossReply') &&
+        outputString(event, 'question') !== undefined);
+}
+// ---------------------------------------------------------------------------
+// Nested `review` results
+// ---------------------------------------------------------------------------
+/**
+ * Recognizes an authored rejected child result: a validated public result
+ * whose status is `aborted` or `error`, or `ok` at the child's own authored
+ * failure terminal. Anything else is a control-plane error.
+ */
+export function authoredChildResult(error, expectedPlaybookId) {
     if (!(error instanceof Error))
         return undefined;
-    const result = error.result;
-    if (!isPlainRecord(result))
-        return undefined;
-    const allowed = new Set([
-        'status',
-        'playbookId',
-        'childSessionId',
-        'state',
-        'error',
-    ]);
-    if (Reflect.ownKeys(result).some((key) => typeof key !== 'string' || !allowed.has(key)) ||
-        (result.status !== 'aborted' && result.status !== 'error') ||
-        result.playbookId !== 'review' ||
-        Object.prototype.hasOwnProperty.call(result, 'output')) {
-        return undefined;
+    try {
+        const result = validatePlaybookCallResult(error.result, expectedPlaybookId);
+        return result.status !== 'ok' || result.terminal?.kind === 'failure'
+            ? result
+            : undefined;
     }
-    if (Object.prototype.hasOwnProperty.call(result, 'childSessionId') &&
-        !isNonEmptyString(result.childSessionId)) {
+    catch {
         return undefined;
     }
-    if (Object.prototype.hasOwnProperty.call(result, 'state') &&
-        !isPlaybookState(result.state)) {
+}
+/**
+ * DECIDE-4's acceptance predicate on the builtin `review` public interface:
+ * the result gives the exact evaluated repository revision and affirmatively
+ * establishes that no unsettled findings remain. The shared bridge correlates
+ * the result with the supplied review scope.
+ */
+function reviewApprovalFrom(event) {
+    const output = actorOutput(event);
+    if (output === undefined)
+        return undefined;
+    if (output.noUnsettledFindings !== true ||
+        !isNonEmptyString(output.evaluatedRevision)) {
         return undefined;
     }
-    let normalizedError;
-    if (Object.prototype.hasOwnProperty.call(result, 'error')) {
-        if (!isPlainRecord(result.error))
-            return undefined;
-        const errorKeys = Reflect.ownKeys(result.error);
-        if (errorKeys.some((key) => typeof key !== 'string' ||
-            (key !== 'name' && key !== 'message' && key !== 'stack')) ||
-            !Object.prototype.hasOwnProperty.call(result.error, 'name') ||
-            !Object.prototype.hasOwnProperty.call(result.error, 'message')) {
-            return undefined;
-        }
-        if (!isNonEmptyString(result.error.name) ||
-            typeof result.error.message !== 'string' ||
-            (Object.prototype.hasOwnProperty.call(result.error, 'stack') &&
-                typeof result.error.stack !== 'string')) {
-            return undefined;
-        }
-        normalizedError = {
-            name: result.error.name,
-            message: result.error.message,
-        };
-    }
-    else if (result.status === 'error') {
+    return {
+        noUnsettledFindings: true,
+        evaluatedRevision: output.evaluatedRevision,
+    };
+}
+/** Reported status, compact error, and evidence of an authored review failure. */
+function authoredReviewFailureOf(event) {
+    const result = authoredChildResult(actorError(event), REVIEW_PLAYBOOK_ID);
+    if (result === undefined)
         return undefined;
+    if (result.status === 'ok') {
+        // `ok` at review's own authored failure terminal: a review failure whose
+        // own output is relayed as evidence.
+        const description = result.terminal?.description;
+        return {
+            status: 'error',
+            error: {
+                name: 'ReviewFailed',
+                message: isNonEmptyString(description)
+                    ? `review ended at its authored failure terminal: ${description}`
+                    : 'review ended at its authored failure terminal.',
+            },
+            evidence: {
+                playbookId: REVIEW_PLAYBOOK_ID,
+                status: 'ok',
+                ...(result.output === undefined ? {} : { output: result.output }),
+            },
+        };
     }
+    const error = result.error !== undefined
+        ? { name: result.error.name, message: result.error.message }
+        : { name: 'AbortError', message: 'The review call was aborted.' };
     return {
         status: result.status,
-        playbookId: 'review',
-        ...(normalizedError ? { error: normalizedError } : {}),
+        error,
+        evidence: { playbookId: REVIEW_PLAYBOOK_ID, status: result.status, error },
+    };
+}
+const REVIEW_NOT_ESTABLISHED = {
+    name: 'ReviewNotEstablished',
+    message: 'review returned a terminal result that does not establish the exact evaluated repository revision with no unsettled findings.',
+};
+// ---------------------------------------------------------------------------
+// Nested call text composition (DECIDE-4 quoted relays)
+// ---------------------------------------------------------------------------
+const REVIEW_PLACEHOLDER = /<caller-topic>|<decide-commit>|<coder-proposal>|<coder-output>/g;
+/**
+ * Composes the `review` call text from the verbatim template, one line at a
+ * time: a quoted relay line whose value is empty contributes no line, and a
+ * multi-line value is quoted line by line. The composer adds no empty quoted
+ * line of its own.
+ */
+function reviewCallText(context) {
+    const values = {
+        '<caller-topic>': context.callerTopic,
+        '<decide-commit>': context.decideCommit,
+        '<coder-proposal>': context.coderProposal,
+        '<coder-output>': context.coderOutput,
+    };
+    const lines = [];
+    for (const line of REVIEW_COMMIT_TEMPLATE.split('\n')) {
+        const tokens = line.match(REVIEW_PLACEHOLDER) ?? [];
+        if (tokens.some((token) => values[token] === ''))
+            continue;
+        lines.push(line.replace(REVIEW_PLACEHOLDER, (token) => (values[token] ?? token).split('\n').join('\n> ')));
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Player input mapping (pure reads of typed, entry-validated context)
+// ---------------------------------------------------------------------------
+function bossReplyFields(context, stateId) {
+    const pendingBossQuestion = context.pendingBossQuestions[stateId];
+    const bossReply = context.bossReplies[stateId];
+    return {
+        ...(pendingBossQuestion === undefined ? {} : { pendingBossQuestion }),
+        ...(bossReply === undefined ? {} : { bossReply }),
     };
 }
-const authoredReviewFailure = ({ event }) => normalizedChildFailure(event.error) !== undefined;
+// ---------------------------------------------------------------------------
+// Context snapshots
+// ---------------------------------------------------------------------------
+const INITIAL_CONTEXT = {
+    callerTopic: '',
+    stagedCoderProposal: '',
+    stagedReviewerProposal: '',
+    coderProposal: '',
+    reviewerProposal: '',
+    coderOutput: '',
+    decideCommit: '',
+    evaluatedRevision: '',
+    reviewStatus: null,
+    reviewError: null,
+    reviewEvidence: null,
+    lastError: null,
+    pendingBossQuestions: {},
+    bossReplies: {},
+};
+/**
+ * A fresh run for a topic: clears every staged and promoted proposal, the
+ * commit, review evidence, errors, and every pending Boss question and reply.
+ */
+function freshRun(callerTopic) {
+    return { ...INITIAL_CONTEXT, callerTopic };
+}
+/** Context reset shared by every exit into `failed`. */
+const FAILURE_RESET = {
+    pendingBossQuestions: {},
+    bossReplies: {},
+    stagedCoderProposal: '',
+    stagedReviewerProposal: '',
+};
+/**
+ * A synthesis restart keeps the topic and the promoted proposals, and clears
+ * the prior commit, review evidence, error, and every pending question.
+ */
+const SYNTHESIS_RESTART = {
+    coderOutput: '',
+    decideCommit: '',
+    evaluatedRevision: '',
+    reviewStatus: null,
+    reviewError: null,
+    reviewEvidence: null,
+    lastError: null,
+    pendingBossQuestions: {},
+    bossReplies: {},
+};
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+/**
+ * Accepted-outcome marker (artifact schema 3). `target` names the public
+ * state the next snapshot shows after the transition's macrostep.
+ */
+function acceptedOutcome(source, target, outcome) {
+    return {
+        type: 'playbook.acceptedOutcome',
+        params: { source, target, acceptedOutcome: outcome },
+    };
+}
+/** Root `BOSS_INTERRUPT` arms, one per jumpable state. */
 function bossInterrupts(ids) {
-    return ids.map((id) => ({
-        guard: ({ event }) => event.type === 'BOSS_INTERRUPT' &&
-            event.targetId === id &&
-            typeof event.bossIntent === 'string' &&
-            event.bossIntent.trim().length > 0,
-        target: `#${id}`,
+    return ids.map((targetId) => ({
+        guard: { type: 'interruptTargets', params: { targetId } },
+        target: `#${targetId}`,
         reenter: true,
-        actions: 'copyInterruptedTopic',
+        actions: 'restartFromInterrupt',
     }));
 }
+/** Keyed `BOSS_REPLY` arms of the wait that resumes the given working leaves. */
 function resumableStates(ids) {
-    return ids.map((id) => ({
-        guard: ({ context, event }) => event.type === 'BOSS_REPLY' &&
-            event.answer.trim().length > 0 &&
-            resolvedQuestionId(context, event) === id,
-        target: `#${id}`,
-        reenter: true,
-        actions: 'rememberBossReply',
-    }));
+    return ids.flatMap((stateId) => [
+        {
+            guard: { type: 'bossReplyIsEmpty', params: { stateId } },
+            target: '#failed',
+            actions: 'rememberEmptyBossReply',
+        },
+        {
+            guard: { type: 'bossReplyResumes', params: { stateId } },
+            target: `#${stateId}`,
+            reenter: true,
+            actions: { type: 'rememberBossReply', params: { stateId } },
+        },
+    ]);
 }
-const stateMetadata = {
-    askCoderProposal: {
-        sourceItem: 'DECIDE-1',
-        asker: { kind: 'role', roleId: 'coder' },
-    },
-    askReviewerProposal: {
-        sourceItem: 'DECIDE-2',
-        asker: { kind: 'role', roleId: 'reviewer' },
-    },
-    commitCoderProposal: {
-        sourceItem: 'DECIDE-3',
-        asker: { kind: 'role', roleId: 'coder' },
-    },
+/**
+ * At the root synthesis wait, where no other task is active, a keyed
+ * `BOSS_REPLY` that names no pending question fails the run.
+ */
+const unknownBossReplyArm = {
+    guard: 'bossReplyNamesNoPendingQuestion',
+    target: '#failed',
+    actions: 'rememberUnknownBossReply',
 };
+const startDecideArm = {
+    guard: 'validStartTopic',
+    target: '#independentProposals',
+    actions: 'startDecide',
+};
+function suspendArm(stateId, wait) {
+    return {
+        guard: 'needsBossReply',
+        target: `#${wait}`,
+        actions: [
+            acceptedOutcome(stateId, wait, 'needsBossReply'),
+            { type: 'setPendingBossQuestion', params: { stateId } },
+        ],
+    };
+}
+function malformedPlayerOutputArm(sourceItem) {
+    return {
+        target: '#failed',
+        actions: { type: 'rememberMalformedPlayerOutput', params: { sourceItem } },
+    };
+}
+const playerOnError = {
+    target: '#failed',
+    actions: 'rememberActorError',
+};
+// ---------------------------------------------------------------------------
+// Machine
+// ---------------------------------------------------------------------------
 export const decideMachine = setup({
     types: {
         context: {},
@@ -310,673 +536,480 @@ export const decideMachine = setup({
             throw new Error('playbook actor must be provided by the runner');
         }),
     },
+    guards: {
+        validStartTopic: ({ event }) => event.type === 'START_DECIDE' && isNonEmptyString(event.callerTopic),
+        // Each arm guards its target id and every typed precondition for
+        // entering that target safely.
+        interruptTargets: ({ context, event }, params) => {
+            if (event.type !== 'BOSS_INTERRUPT')
+                return false;
+            if (event.targetId !== params.targetId)
+                return false;
+            if (event.targetId === 'independentProposals') {
+                return isNonEmptyString(event.callerTopic);
+            }
+            return (isNonEmptyString(context.callerTopic) &&
+                isNonEmptyString(context.coderProposal) &&
+                isNonEmptyString(context.reviewerProposal));
+        },
+        // A branch completing after its sibling has staged its proposal also
+        // completes the join, so its accepted outcome lands on `synthesizeCommit`.
+        coderProposedJoining: ({ context, event }) => isCoderProposed(event) &&
+            isNonEmptyString(context.stagedReviewerProposal) &&
+            isNonEmptyString(context.callerTopic),
+        coderProposed: ({ event }) => isCoderProposed(event),
+        reviewerProposedJoining: ({ context, event }) => isReviewerProposed(event) &&
+            isNonEmptyString(context.stagedCoderProposal) &&
+            isNonEmptyString(context.callerTopic),
+        reviewerProposed: ({ event }) => isReviewerProposed(event),
+        committed: ({ context, event }) => isCommitted(event) &&
+            isNonEmptyString(context.callerTopic) &&
+            isNonEmptyString(context.coderProposal),
+        needsBossReply: ({ event }) => isNeedsBossReply(event),
+        reviewApproved: ({ context, event }) => isNonEmptyString(context.decideCommit) &&
+            reviewApprovalFrom(event) !== undefined,
+        authoredReviewFailure: ({ context, event }) => isNonEmptyString(context.decideCommit) &&
+            authoredReviewFailureOf(event) !== undefined,
+        bossReplyNamesNoPendingQuestion: ({ context, event }) => event.type === 'BOSS_REPLY' &&
+            (!isResumableStateId(event.questionId) ||
+                context.pendingBossQuestions[event.questionId] === undefined),
+        bossReplyIsEmpty: ({ context, event }, params) => event.type === 'BOSS_REPLY' &&
+            event.questionId === params.stateId &&
+            context.pendingBossQuestions[params.stateId] !== undefined &&
+            !isNonEmptyString(event.answer),
+        bossReplyResumes: ({ context, event }, params) => event.type === 'BOSS_REPLY' &&
+            event.questionId === params.stateId &&
+            context.pendingBossQuestions[params.stateId] !== undefined &&
+            isNonEmptyString(event.answer) &&
+            isNonEmptyString(context.callerTopic),
+    },
     actions: {
         'playbook.acceptedOutcome': (_args, _params) => undefined,
-        copyStartTopic: assign({
-            callerTopic: ({ event }) => event.type === 'START_DECIDE' ? event.callerTopic : undefined,
-            coderProposal: undefined,
-            reviewerProposal: undefined,
-            latestCommit: undefined,
-            coderOutput: undefined,
-            reviewResult: undefined,
-            reviewFailure: undefined,
-            lastResult: undefined,
-            lastError: undefined,
-            pendingBossQuestions: undefined,
-            bossReplies: undefined,
-            stagedCoderResult: undefined,
-            stagedReviewerResult: undefined,
-        }),
-        copyInterruptedTopic: assign({
-            callerTopic: ({ event }) => event.type === 'BOSS_INTERRUPT' ? event.bossIntent : undefined,
-            coderProposal: undefined,
-            reviewerProposal: undefined,
-            latestCommit: undefined,
-            coderOutput: undefined,
-            reviewResult: undefined,
-            reviewFailure: undefined,
-            lastResult: undefined,
-            lastError: undefined,
-            pendingBossQuestions: undefined,
-            bossReplies: undefined,
-            stagedCoderResult: undefined,
-            stagedReviewerResult: undefined,
-        }),
-        stageCoderProposal: assign({
-            stagedCoderResult: ({ event }) => outputOf(event),
-            lastResult: ({ event }) => outputOf(event),
-            lastError: undefined,
-        }),
-        stageReviewerProposal: assign({
-            stagedReviewerResult: ({ event }) => outputOf(event),
-            lastResult: ({ event }) => outputOf(event),
-            lastError: undefined,
+        startDecide: assign(({ event }) => event.type === 'START_DECIDE' ? freshRun(event.callerTopic) : {}),
+        // A new topic restarts the whole proposal pair from a fresh run; a
+        // synthesis restart keeps the topic and the promoted proposals.
+        restartFromInterrupt: assign(({ event }) => {
+            if (event.type !== 'BOSS_INTERRUPT')
+                return {};
+            return event.targetId === 'independentProposals'
+                ? freshRun(event.callerTopic)
+                : SYNTHESIS_RESTART;
         }),
-        promoteProposals: assign({
-            coderProposal: ({ context }) => context.stagedCoderResult?.coderProposal,
-            reviewerProposal: ({ context }) => context.stagedReviewerResult?.reviewerProposal,
-            stagedCoderResult: undefined,
-            stagedReviewerResult: undefined,
-            lastResult: undefined,
-            lastError: undefined,
-        }),
-        rememberCommit: assign({
-            latestCommit: ({ event }) => outputOf(event).latestCommit,
-            coderOutput: ({ event }) => outputOf(event).coderOutput,
-            lastResult: ({ event }) => outputOf(event),
-            lastError: undefined,
-        }),
-        rememberReviewSuccess: assign({
-            reviewResult: ({ event }) => reviewSuccessFrom(event),
-            reviewFailure: undefined,
-            lastError: undefined,
-        }),
-        rememberReviewFailure: assign({
-            reviewFailure: ({ event }) => normalizedChildFailure(event.error),
-            lastError: undefined,
+        // Each branch assigns only its own staged result.
+        stageCoderProposal: assign(({ context, event }) => ({
+            stagedCoderProposal: outputString(event, 'coderProposal') ?? '',
+            pendingBossQuestions: withoutKey(context.pendingBossQuestions, 'askCoderProposal'),
+            bossReplies: withoutKey(context.bossReplies, 'askCoderProposal'),
+        })),
+        stageReviewerProposal: assign(({ context, event }) => ({
+            stagedReviewerProposal: outputString(event, 'reviewerProposal') ?? '',
+            pendingBossQuestions: withoutKey(context.pendingBossQuestions, 'askReviewerProposal'),
+            bossReplies: withoutKey(context.bossReplies, 'askReviewerProposal'),
+        })),
+        // The join promotes both staged proposals atomically.
+        promoteProposals: assign(({ context }) => ({
+            coderProposal: context.stagedCoderProposal,
+            reviewerProposal: context.stagedReviewerProposal,
+            stagedCoderProposal: '',
+            stagedReviewerProposal: '',
+            pendingBossQuestions: {},
+            bossReplies: {},
+        })),
+        rememberCommit: assign(({ context, event }) => ({
+            coderOutput: outputString(event, 'coderOutput') ?? '',
+            decideCommit: outputString(event, 'latestCommit') ?? '',
+            lastError: null,
+            pendingBossQuestions: withoutKey(context.pendingBossQuestions, 'synthesizeCommit'),
+            bossReplies: withoutKey(context.bossReplies, 'synthesizeCommit'),
+        })),
+        setPendingBossQuestion: assign(({ context, event }, params) => {
+            const question = outputString(event, 'question');
+            if (question === undefined)
+                return {};
+            const { sourceItem, roleId } = RESUMABLE_STATES[params.stateId];
+            const pending = {
+                questionId: params.stateId,
+                resumeStateId: params.stateId,
+                sourceItem,
+                asker: { kind: 'role', roleId },
+                question,
+            };
+            return {
+                pendingBossQuestions: {
+                    ...context.pendingBossQuestions,
+                    [params.stateId]: pending,
+                },
+                bossReplies: withoutKey(context.bossReplies, params.stateId),
+            };
         }),
-        rememberReviewProtocolFailure: assign({
-            reviewFailure: {
-                status: 'error',
-                playbookId: 'review',
-                error: {
-                    name: 'ReviewProtocolError',
-                    message: 'REVIEW returned without the evaluated repository revision and a no-unsettled-findings result for the supplied scope.',
+        rememberBossReply: assign(({ context, event }, params) => event.type === 'BOSS_REPLY'
+            ? {
+                bossReplies: {
+                    ...context.bossReplies,
+                    [params.stateId]: event.answer,
                 },
+            }
+            : {}),
+        rememberEmptyBossReply: assign({
+            lastError: {
+                name: 'MalformedBossReply',
+                message: 'BOSS_REPLY carried an empty answer.',
             },
-            lastError: undefined,
+            ...FAILURE_RESET,
         }),
-        rememberActorError: assign({
-            lastError: ({ event }) => event.error,
-        }),
-        rememberMalformedActorOutput: assign({
-            lastError: ({ event }) => event.output,
-        }),
-        rememberMalformedBossReply: assign({
-            lastError: ({ event }) => event,
+        rememberUnknownBossReply: assign({
+            lastError: {
+                name: 'MalformedBossReply',
+                message: 'BOSS_REPLY names no pending question.',
+            },
+            ...FAILURE_RESET,
         }),
-        setPendingBossQuestion: assign({
-            pendingBossQuestions: ({ context, event }, params) => ({
-                ...context.pendingBossQuestions,
-                [params.resumeStateId]: {
-                    ...params,
-                    questionId: params.resumeStateId,
-                    question: outputOf(event).question ?? '',
+        rememberMalformedPlayerOutput: assign(({ event }, params) => {
+            const output = actorOutput(event);
+            return {
+                lastError: {
+                    name: 'MalformedPlayerOutput',
+                    message: output?.guard === 'needsBossReply'
+                        ? `Player output for ${params.sourceItem} declared needsBossReply without a question.`
+                        : `Player output for ${params.sourceItem} did not match an outcome declared for its state.`,
                 },
-            }),
-            bossReplies: ({ context }, params) => withoutKey(context.bossReplies, params.resumeStateId),
-            lastResult: ({ event }) => outputOf(event),
-            lastError: undefined,
-        }),
-        rememberBossReply: assign({
-            bossReplies: ({ context, event }) => {
-                const questionId = resolvedQuestionId(context, event);
-                return event.type === 'BOSS_REPLY' && questionId
-                    ? { ...context.bossReplies, [questionId]: event.answer }
-                    : context.bossReplies;
-            },
-            lastError: undefined,
+                ...FAILURE_RESET,
+            };
         }),
-        clearBranchBossReplyContext: assign({
-            pendingBossQuestions: ({ context }, params) => withoutKey(context.pendingBossQuestions, params.stateId),
-            bossReplies: ({ context }, params) => withoutKey(context.bossReplies, params.stateId),
+        rememberActorError: assign(({ event }) => ({
+            lastError: errorRecord(actorError(event)),
+            ...FAILURE_RESET,
+        })),
+        rememberReviewApproval: assign(({ event }) => {
+            const approval = reviewApprovalFrom(event);
+            if (approval === undefined)
+                return {};
+            const output = actorOutput(event);
+            const reviewEvidence = {
+                playbookId: REVIEW_PLAYBOOK_ID,
+                status: 'ok',
+                ...(isJsonValue(output) ? { output } : {}),
+            };
+            return {
+                evaluatedRevision: approval.evaluatedRevision,
+                reviewStatus: null,
+                reviewError: null,
+                reviewEvidence,
+                lastError: null,
+            };
         }),
-        clearProposalRoundContext: assign({
-            pendingBossQuestions: undefined,
-            bossReplies: undefined,
-            stagedCoderResult: undefined,
-            stagedReviewerResult: undefined,
+        rememberUnestablishedReview: assign(({ event }) => {
+            const output = actorOutput(event);
+            const reviewEvidence = {
+                playbookId: REVIEW_PLAYBOOK_ID,
+                status: 'ok',
+                ...(isJsonValue(output) ? { output } : {}),
+            };
+            return {
+                evaluatedRevision: '',
+                reviewStatus: 'error',
+                reviewError: REVIEW_NOT_ESTABLISHED,
+                reviewEvidence,
+                lastError: null,
+            };
         }),
-        clearBossReplyContext: assign({
-            pendingBossQuestions: undefined,
-            bossReplies: undefined,
+        rememberAuthoredReviewFailure: assign(({ event }) => {
+            const failure = authoredReviewFailureOf(event);
+            return failure === undefined
+                ? {}
+                : {
+                    evaluatedRevision: '',
+                    reviewStatus: failure.status,
+                    reviewError: failure.error,
+                    reviewEvidence: failure.evidence,
+                    lastError: null,
+                };
         }),
     },
-    guards: {
-        coderProposed,
-        reviewerProposed,
-        committed,
-        needsBossReplyWithQuestion,
-        needsBossReplyWithoutQuestion,
-        validReviewSuccess,
-        authoredReviewFailure,
-    },
 }).createMachine({
     id: 'decide',
+    description: 'DECIDE: independent Coder and Reviewer proposals, a synthesized decide-owned commit, and a nested review.',
     initial: 'ready',
-    context: () => ({}),
+    context: () => INITIAL_CONTEXT,
     output: ({ context }) => {
-        if (context.reviewResult) {
-            if (!context.latestCommit) {
-                throw new Error('DECIDE completed without its decide-owned commit');
-            }
+        const commit = context.decideCommit;
+        if (!isNonEmptyString(commit)) {
+            throw new Error('DECIDE reached a final state without its decide-owned commit');
+        }
+        if (context.reviewStatus !== null) {
             return {
-                decideCommit: context.latestCommit,
-                evaluatedRevision: context.reviewResult.evaluatedRevision,
-                noUnsettledFindings: true,
+                lastDecideCommit: commit,
+                noUnsettledFindings: false,
+                reviewStatus: context.reviewStatus,
+                ...(context.reviewError === null ? {} : { error: context.reviewError }),
             };
         }
-        if (!context.latestCommit || !context.reviewFailure) {
-            throw new Error('DECIDE reached a final state without a result');
+        const evaluatedRevision = context.evaluatedRevision;
+        if (!isNonEmptyString(evaluatedRevision)) {
+            throw new Error('DECIDE completed without the evaluated repository revision');
         }
         return {
-            lastDecideCommit: context.latestCommit,
-            noUnsettledFindings: false,
-            reviewStatus: context.reviewFailure.status,
-            ...(context.reviewFailure.error
-                ? { error: context.reviewFailure.error }
-                : {}),
+            decideCommit: commit,
+            evaluatedRevision,
+            noUnsettledFindings: true,
         };
     },
     on: {
-        BOSS_INTERRUPT: bossInterrupts(['independentProposals']),
+        BOSS_INTERRUPT: bossInterrupts([
+            'independentProposals',
+            'synthesizeCommit',
+        ]),
     },
     states: {
         ready: {
             id: 'ready',
-            tags: 'playbook.parked',
-            description: 'Waiting for a topic to decide.',
-            meta: {
-                playbook: {
-                    stateId: 'ready',
-                    description: 'Waiting for a topic to decide.',
-                },
-            },
+            description: STATE_DESCRIPTIONS.ready,
+            meta: playbookMeta('ready'),
+            tags: ['playbook.parked'],
             on: {
-                START_DECIDE: {
-                    guard: ({ event }) => event.callerTopic.trim().length > 0,
-                    target: 'independentProposals',
-                    actions: 'copyStartTopic',
-                },
+                START_DECIDE: startDecideArm,
             },
         },
         independentProposals: {
             id: 'independentProposals',
+            description: STATE_DESCRIPTIONS.independentProposals,
+            meta: playbookMeta('independentProposals'),
             type: 'parallel',
-            description: 'Coder and Reviewer prepare independent proposals.',
-            meta: {
-                playbook: {
-                    stateId: 'independentProposals',
-                    description: 'Coder and Reviewer prepare independent proposals.',
-                },
-            },
+            // No group-level BOSS_REPLY handler: a reply is handled only by the
+            // branch wait whose pending question it names, and a reply naming no
+            // pending branch question moves no branch.
             states: {
-                coder: {
-                    initial: 'working',
+                coderProposalRegion: {
+                    id: 'coderProposalRegion',
+                    description: STATE_DESCRIPTIONS.coderProposalRegion,
+                    meta: playbookMeta('coderProposalRegion'),
+                    initial: 'askCoderProposal',
                     states: {
-                        working: {
+                        askCoderProposal: {
                             id: 'askCoderProposal',
-                            tags: 'playbook.busy',
-                            description: 'Coder independently proposes a spec design.',
-                            meta: {
-                                playbook: {
-                                    stateId: 'askCoderProposal',
-                                    description: 'Coder independently proposes a spec design.',
-                                    role: 'coder',
-                                },
-                            },
+                            description: STATE_DESCRIPTIONS.askCoderProposal,
+                            meta: playbookMeta('askCoderProposal', 'coder'),
+                            tags: ['playbook.busy'],
                             invoke: {
                                 src: 'player',
                                 input: ({ context }) => ({
                                     stateId: 'askCoderProposal',
-                                    sourceItem: 'DECIDE-1',
                                     role: 'coder',
-                                    prompt: INDEPENDENT_PROPOSAL_PROMPT,
-                                    result: withNeedsBossReply({
-                                        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>`.',
-                                    }),
+                                    sourceItem: 'DECIDE-1',
+                                    prompt: CODER_PROPOSAL_PROMPT,
+                                    result: CODER_PROPOSAL_RESULT,
                                     callerTopic: context.callerTopic,
                                     ...bossReplyFields(context, 'askCoderProposal'),
                                 }),
                                 onDone: [
+                                    suspendArm('askCoderProposal', 'awaitCoderProposalReply'),
                                     {
-                                        guard: 'needsBossReplyWithQuestion',
-                                        target: 'waiting',
+                                        guard: 'coderProposedJoining',
+                                        target: 'coderProposalStaged',
                                         actions: [
-                                            {
-                                                type: 'playbook.acceptedOutcome',
-                                                params: {
-                                                    source: 'askCoderProposal',
-                                                    target: 'waitCoderProposalReply',
-                                                    acceptedOutcome: 'needsBossReply',
-                                                },
-                                            },
-                                            {
-                                                type: 'setPendingBossQuestion',
-                                                params: {
-                                                    ...stateMetadata.askCoderProposal,
-                                                    resumeStateId: 'askCoderProposal',
-                                                    question: '',
-                                                },
-                                            },
-                                        ],
-                                    },
-                                    {
-                                        guard: 'needsBossReplyWithoutQuestion',
-                                        target: '#failed',
-                                        actions: [
-                                            'rememberMalformedActorOutput',
-                                            'clearProposalRoundContext',
+                                            acceptedOutcome('askCoderProposal', 'synthesizeCommit', 'proposed'),
+                                            'stageCoderProposal',
                                         ],
                                     },
                                     {
                                         guard: 'coderProposed',
-                                        target: 'complete',
+                                        target: 'coderProposalStaged',
                                         actions: [
-                                            {
-                                                type: 'playbook.acceptedOutcome',
-                                                params: ({ context }) => ({
-                                                    source: 'askCoderProposal',
-                                                    target: context.stagedReviewerResult === undefined
-                                                        ? 'coderProposalComplete'
-                                                        : 'commitCoderProposal',
-                                                    acceptedOutcome: 'proposed',
-                                                }),
-                                            },
+                                            acceptedOutcome('askCoderProposal', 'coderProposalStaged', 'proposed'),
                                             'stageCoderProposal',
-                                            {
-                                                type: 'clearBranchBossReplyContext',
-                                                params: { stateId: 'askCoderProposal' },
-                                            },
-                                        ],
-                                    },
-                                    {
-                                        target: '#failed',
-                                        actions: [
-                                            'rememberMalformedActorOutput',
-                                            'clearProposalRoundContext',
                                         ],
                                     },
+                                    malformedPlayerOutputArm('DECIDE-1'),
                                 ],
-                                onError: {
-                                    target: '#failed',
-                                    actions: [
-                                        'rememberActorError',
-                                        'clearProposalRoundContext',
-                                    ],
-                                },
+                                onError: playerOnError,
                             },
                         },
-                        waiting: {
-                            id: 'waitCoderProposalReply',
-                            tags: 'playbook.parked',
-                            description: 'Coder waits for Boss to answer a question.',
-                            meta: {
-                                playbook: {
-                                    stateId: 'waitCoderProposalReply',
-                                    description: 'Coder waits for Boss to answer a question.',
-                                },
-                            },
+                        awaitCoderProposalReply: {
+                            id: 'awaitCoderProposalReply',
+                            description: STATE_DESCRIPTIONS.awaitCoderProposalReply,
+                            meta: playbookMeta('awaitCoderProposalReply'),
+                            tags: ['playbook.parked'],
                             on: {
-                                BOSS_REPLY: [
-                                    {
-                                        guard: bossReplyTargets('askCoderProposal', false),
-                                        target: '#failed',
-                                        actions: [
-                                            'rememberMalformedBossReply',
-                                            'clearProposalRoundContext',
-                                        ],
-                                    },
-                                    {
-                                        guard: bossReplyTargets('askCoderProposal', true),
-                                        target: 'working',
-                                        actions: 'rememberBossReply',
-                                    },
-                                ],
+                                BOSS_REPLY: resumableStates(['askCoderProposal']),
                             },
                         },
-                        complete: {
+                        coderProposalStaged: {
+                            id: 'coderProposalStaged',
+                            description: STATE_DESCRIPTIONS.coderProposalStaged,
+                            meta: playbookMeta('coderProposalStaged'),
                             type: 'final',
-                            description: 'Coder proposal is staged for the parallel join.',
-                            meta: {
-                                playbook: {
-                                    stateId: 'coderProposalComplete',
-                                    description: 'Coder proposal is staged for the parallel join.',
-                                },
-                            },
                         },
                     },
                 },
-                reviewer: {
-                    initial: 'working',
+                reviewerProposalRegion: {
+                    id: 'reviewerProposalRegion',
+                    description: STATE_DESCRIPTIONS.reviewerProposalRegion,
+                    meta: playbookMeta('reviewerProposalRegion'),
+                    initial: 'askReviewerProposal',
                     states: {
-                        working: {
+                        askReviewerProposal: {
                             id: 'askReviewerProposal',
-                            tags: 'playbook.busy',
-                            description: 'Reviewer independently proposes a spec design.',
-                            meta: {
-                                playbook: {
-                                    stateId: 'askReviewerProposal',
-                                    description: 'Reviewer independently proposes a spec design.',
-                                    role: 'reviewer',
-                                },
-                            },
+                            description: STATE_DESCRIPTIONS.askReviewerProposal,
+                            meta: playbookMeta('askReviewerProposal', 'reviewer'),
+                            tags: ['playbook.busy'],
                             invoke: {
                                 src: 'player',
                                 input: ({ context }) => ({
                                     stateId: 'askReviewerProposal',
-                                    sourceItem: 'DECIDE-2',
                                     role: 'reviewer',
-                                    prompt: INDEPENDENT_PROPOSAL_PROMPT,
-                                    result: withNeedsBossReply({
-                                        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>`.',
-                                    }),
+                                    sourceItem: 'DECIDE-2',
+                                    prompt: REVIEWER_PROPOSAL_PROMPT,
+                                    result: REVIEWER_PROPOSAL_RESULT,
                                     callerTopic: context.callerTopic,
                                     ...bossReplyFields(context, 'askReviewerProposal'),
                                 }),
                                 onDone: [
+                                    suspendArm('askReviewerProposal', 'awaitReviewerProposalReply'),
                                     {
-                                        guard: 'needsBossReplyWithQuestion',
-                                        target: 'waiting',
-                                        actions: [
-                                            {
-                                                type: 'playbook.acceptedOutcome',
-                                                params: {
-                                                    source: 'askReviewerProposal',
-                                                    target: 'waitReviewerProposalReply',
-                                                    acceptedOutcome: 'needsBossReply',
-                                                },
-                                            },
-                                            {
-                                                type: 'setPendingBossQuestion',
-                                                params: {
-                                                    ...stateMetadata.askReviewerProposal,
-                                                    resumeStateId: 'askReviewerProposal',
-                                                    question: '',
-                                                },
-                                            },
-                                        ],
-                                    },
-                                    {
-                                        guard: 'needsBossReplyWithoutQuestion',
-                                        target: '#failed',
+                                        guard: 'reviewerProposedJoining',
+                                        target: 'reviewerProposalStaged',
                                         actions: [
-                                            'rememberMalformedActorOutput',
-                                            'clearProposalRoundContext',
+                                            acceptedOutcome('askReviewerProposal', 'synthesizeCommit', 'proposed'),
+                                            'stageReviewerProposal',
                                         ],
                                     },
                                     {
                                         guard: 'reviewerProposed',
-                                        target: 'complete',
+                                        target: 'reviewerProposalStaged',
                                         actions: [
-                                            {
-                                                type: 'playbook.acceptedOutcome',
-                                                params: ({ context }) => ({
-                                                    source: 'askReviewerProposal',
-                                                    target: context.stagedCoderResult === undefined
-                                                        ? 'reviewerProposalComplete'
-                                                        : 'commitCoderProposal',
-                                                    acceptedOutcome: 'proposed',
-                                                }),
-                                            },
+                                            acceptedOutcome('askReviewerProposal', 'reviewerProposalStaged', 'proposed'),
                                             'stageReviewerProposal',
-                                            {
-                                                type: 'clearBranchBossReplyContext',
-                                                params: { stateId: 'askReviewerProposal' },
-                                            },
-                                        ],
-                                    },
-                                    {
-                                        target: '#failed',
-                                        actions: [
-                                            'rememberMalformedActorOutput',
-                                            'clearProposalRoundContext',
                                         ],
                                     },
+                                    malformedPlayerOutputArm('DECIDE-2'),
                                 ],
-                                onError: {
-                                    target: '#failed',
-                                    actions: [
-                                        'rememberActorError',
-                                        'clearProposalRoundContext',
-                                    ],
-                                },
+                                onError: playerOnError,
                             },
                         },
-                        waiting: {
-                            id: 'waitReviewerProposalReply',
-                            tags: 'playbook.parked',
-                            description: 'Reviewer waits for Boss to answer a question.',
-                            meta: {
-                                playbook: {
-                                    stateId: 'waitReviewerProposalReply',
-                                    description: 'Reviewer waits for Boss to answer a question.',
-                                },
-                            },
+                        awaitReviewerProposalReply: {
+                            id: 'awaitReviewerProposalReply',
+                            description: STATE_DESCRIPTIONS.awaitReviewerProposalReply,
+                            meta: playbookMeta('awaitReviewerProposalReply'),
+                            tags: ['playbook.parked'],
                             on: {
-                                BOSS_REPLY: [
-                                    {
-                                        guard: bossReplyTargets('askReviewerProposal', false),
-                                        target: '#failed',
-                                        actions: [
-                                            'rememberMalformedBossReply',
-                                            'clearProposalRoundContext',
-                                        ],
-                                    },
-                                    {
-                                        guard: bossReplyTargets('askReviewerProposal', true),
-                                        target: 'working',
-                                        actions: 'rememberBossReply',
-                                    },
-                                ],
+                                BOSS_REPLY: resumableStates(['askReviewerProposal']),
                             },
                         },
-                        complete: {
+                        reviewerProposalStaged: {
+                            id: 'reviewerProposalStaged',
+                            description: STATE_DESCRIPTIONS.reviewerProposalStaged,
+                            meta: playbookMeta('reviewerProposalStaged'),
                             type: 'final',
-                            description: 'Reviewer proposal is staged for the parallel join.',
-                            meta: {
-                                playbook: {
-                                    stateId: 'reviewerProposalComplete',
-                                    description: 'Reviewer proposal is staged for the parallel join.',
-                                },
-                            },
                         },
                     },
                 },
             },
+            // The join: taken only after both regions reach final; it promotes both
+            // staged proposals atomically before DECIDE-3 begins.
             onDone: {
-                target: 'commitCoderProposal',
+                target: 'synthesizeCommit',
                 actions: 'promoteProposals',
             },
         },
-        commitCoderProposal: {
-            id: 'commitCoderProposal',
-            tags: 'playbook.busy',
-            description: 'Coder synthesizes both proposals and commits the design.',
-            meta: {
-                playbook: {
-                    stateId: 'commitCoderProposal',
-                    description: 'Coder synthesizes both proposals and commits the design.',
-                    role: 'coder',
-                },
-            },
+        synthesizeCommit: {
+            id: 'synthesizeCommit',
+            description: STATE_DESCRIPTIONS.synthesizeCommit,
+            meta: playbookMeta('synthesizeCommit', 'coder'),
+            tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
-                    stateId: 'commitCoderProposal',
-                    sourceItem: 'DECIDE-3',
+                    stateId: 'synthesizeCommit',
                     role: 'coder',
+                    sourceItem: 'DECIDE-3',
                     prompt: SYNTHESIZE_COMMIT_PROMPT,
-                    result: withNeedsBossReply({
-                        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>`.',
-                    }),
+                    result: SYNTHESIZE_COMMIT_RESULT,
                     callerTopic: context.callerTopic,
                     reviewerProposal: context.reviewerProposal,
-                    ...bossReplyFields(context, 'commitCoderProposal'),
+                    ...bossReplyFields(context, 'synthesizeCommit'),
                 }),
                 onDone: [
-                    {
-                        guard: 'needsBossReplyWithQuestion',
-                        target: 'awaitBossReply',
-                        actions: [
-                            {
-                                type: 'playbook.acceptedOutcome',
-                                params: {
-                                    source: 'commitCoderProposal',
-                                    target: 'awaitBossReply',
-                                    acceptedOutcome: 'needsBossReply',
-                                },
-                            },
-                            {
-                                type: 'setPendingBossQuestion',
-                                params: {
-                                    ...stateMetadata.commitCoderProposal,
-                                    resumeStateId: 'commitCoderProposal',
-                                    question: '',
-                                },
-                            },
-                        ],
-                    },
-                    {
-                        guard: 'needsBossReplyWithoutQuestion',
-                        target: 'failed',
-                        actions: [
-                            'rememberMalformedActorOutput',
-                            'clearBossReplyContext',
-                        ],
-                    },
+                    suspendArm('synthesizeCommit', 'awaitBossReply'),
                     {
                         guard: 'committed',
                         target: 'reviewCommit',
                         actions: [
-                            {
-                                type: 'playbook.acceptedOutcome',
-                                params: {
-                                    source: 'commitCoderProposal',
-                                    target: 'reviewCommit',
-                                    acceptedOutcome: 'committed',
-                                },
-                            },
+                            acceptedOutcome('synthesizeCommit', 'reviewCommit', 'committed'),
                             'rememberCommit',
-                            {
-                                type: 'clearBranchBossReplyContext',
-                                params: { stateId: 'commitCoderProposal' },
-                            },
-                        ],
-                    },
-                    {
-                        target: 'failed',
-                        actions: [
-                            'rememberMalformedActorOutput',
-                            'clearBossReplyContext',
                         ],
                     },
+                    malformedPlayerOutputArm('DECIDE-3'),
                 ],
-                onError: {
-                    target: 'failed',
-                    actions: ['rememberActorError', 'clearBossReplyContext'],
-                },
+                onError: playerOnError,
             },
         },
         awaitBossReply: {
             id: 'awaitBossReply',
-            tags: 'playbook.parked',
-            description: 'Waiting for Boss to answer Coder’s question.',
-            meta: {
-                playbook: {
-                    stateId: 'awaitBossReply',
-                    description: 'Waiting for Boss to answer Coder’s question.',
-                },
-            },
+            description: STATE_DESCRIPTIONS.awaitBossReply,
+            meta: playbookMeta('awaitBossReply'),
+            tags: ['playbook.parked'],
             on: {
                 BOSS_REPLY: [
-                    {
-                        guard: bossReplyTargets('commitCoderProposal', false),
-                        target: 'failed',
-                        actions: [
-                            'rememberMalformedBossReply',
-                            'clearBossReplyContext',
-                        ],
-                    },
-                    ...resumableStates(['commitCoderProposal']),
+                    unknownBossReplyArm,
+                    ...resumableStates(['synthesizeCommit']),
                 ],
+                START_DECIDE: startDecideArm,
             },
         },
         reviewCommit: {
             id: 'reviewCommit',
-            tags: 'playbook.suspended',
-            description: 'REVIEW examines the committed proposal.',
-            meta: {
-                playbook: {
-                    stateId: 'reviewCommit',
-                    description: 'REVIEW examines the committed proposal.',
-                },
-            },
+            description: STATE_DESCRIPTIONS.reviewCommit,
+            meta: playbookMeta('reviewCommit'),
+            tags: ['playbook.suspended'],
             invoke: {
                 src: 'playbook',
                 input: ({ context }) => ({
                     stateId: 'reviewCommit',
                     sourceItem: 'DECIDE-4',
-                    playbookId: 'review',
-                    text: composeReviewInput(context.callerTopic, context.latestCommit, context.coderOutput),
+                    playbookId: REVIEW_PLAYBOOK_ID,
+                    text: reviewCallText(context),
                 }),
                 onDone: [
                     {
-                        guard: 'validReviewSuccess',
+                        guard: 'reviewApproved',
                         target: 'done',
-                        actions: 'rememberReviewSuccess',
+                        actions: 'rememberReviewApproval',
                     },
                     {
                         target: 'reportedReviewFailure',
-                        actions: 'rememberReviewProtocolFailure',
+                        actions: 'rememberUnestablishedReview',
                     },
                 ],
                 onError: [
                     {
                         guard: 'authoredReviewFailure',
                         target: 'reportedReviewFailure',
-                        actions: 'rememberReviewFailure',
-                    },
-                    {
-                        target: 'failed',
-                        actions: 'rememberActorError',
+                        actions: 'rememberAuthoredReviewFailure',
                     },
+                    { target: 'failed', actions: 'rememberActorError' },
                 ],
             },
         },
         failed: {
             id: 'failed',
-            tags: 'playbook.parked',
-            description: 'DECIDE failed and is waiting for a new topic.',
-            meta: {
-                playbook: {
-                    stateId: 'failed',
-                    description: 'DECIDE failed and is waiting for a new topic.',
-                },
-            },
+            description: STATE_DESCRIPTIONS.failed,
+            meta: playbookMeta('failed'),
+            tags: ['playbook.parked'],
             on: {
-                START_DECIDE: {
-                    guard: ({ event }) => event.callerTopic.trim().length > 0,
-                    target: 'independentProposals',
-                    actions: 'copyStartTopic',
-                },
+                START_DECIDE: startDecideArm,
             },
         },
         reportedReviewFailure: {
             id: 'reportedReviewFailure',
+            description: STATE_DESCRIPTIONS.reportedReviewFailure,
+            meta: terminalMeta('reportedReviewFailure', 'failure'),
             type: 'final',
-            description: 'DECIDE reports REVIEW’s failure and its last commit.',
-            meta: {
-                playbook: {
-                    stateId: 'reportedReviewFailure',
-                    description: 'DECIDE reports REVIEW’s failure and its last commit.',
-                    // DR-048: this final state means the workflow failed, so a caller
-                    // learns that from the machine rather than from DECIDE's output.
-                    terminal: 'failure',
-                },
-            },
         },
         done: {
             id: 'done',
+            description: STATE_DESCRIPTIONS.done,
+            meta: terminalMeta('done', 'success'),
             type: 'final',
-            description: 'DECIDE completed with an approved commit.',
-            meta: {
-                playbook: {
-                    stateId: 'done',
-                    description: 'DECIDE completed with an approved commit.',
-                    terminal: 'success',
-                },
-            },
         },
     },
 });