@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,13 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 //
-// Generated by slc/gears2fsm.md from ./dev.gears.md.
+// FSM object artifact compiled from ./dev.gears.md by gears2fsm.
+// It defines only the machine, actor contracts, and typed inputs; the linked
+// runtime supplies the `player` and `playbook` actor implementations.
 import { assign, fromPromise, setup } from 'xstate';
+import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+/** DEV declares no parallel group. */
+export const concurrentRoleSets = [];
+// DEV-1: the item's blockquote, verbatim, with the outer GEARS marker removed.
 const PLAN_ANALYSIS_PROMPT = [
-    '> Original request: <development-request>',
-    '> Prior discussion: <discussion-context>',
-    '> Run results: <run-results>',
-    '',
     'Plan which playbooks run for this request; the playbooks do the work.',
     'Read the request, then the specs and the repository only as far as choosing the path requires.',
     'Do not change files or commit while planning or discussing the request.',
@@ -26,50 +28,79 @@ const PLAN_ANALYSIS_PROMPT = [
     'A question or exploratory discussion is not by itself authorization to create a durable decision or implement changes.',
     'Do not choose `decide then code` merely because the work is large, nor `code` merely because it is small.',
     'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
+    '',
+    '> Original request: <development-request>',
+    '> Prior discussion: <discussion-context>',
+    '> Run results: <run-results>',
 ].join('\n');
-const PLAN_ANALYSIS_RESULTS = {
-    discussionComplete: 'Analyst concluded the discussion after a Boss reply, with no repository work to follow.',
-    code: 'Analyst chose `code`: the existing decisions and spec items settle how the work is done. Output shall include `planningResult: <verbatim final text>`.',
-    decideThenCode: 'Analyst chose `decide then code`: the work turns on a point the specs leave open or contradict. Output shall include `planningResult: <verbatim final text>`.',
-    codeViaPullRequest: 'Analyst chose `code via pull request`: the existing decisions settle the work, and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
-    decideThenCodeViaPullRequest: 'Analyst chose `decide then code via pull request`: the work turns on a point the specs leave open or contradict, and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
-    needsBossReply: "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 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>`.";
+// DEV-1 local result contract: the authored `Results:` bullets in declared
+// order, plus the universal Boss-reply suspension.
+const PLAN_ANALYSIS_RESULT = {
+    discussionComplete: 'After a Boss reply that settles that no repository work should follow, Analyst concluded the discussion; dev completes without a child call or repository change.',
+    code: 'Analyst chose the code path because the existing decisions and spec items settle how the work is done. Output shall include `planningResult: <verbatim final text>`.',
+    decideThenCode: 'Analyst chose the decide then code path because the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict. Output shall include `planningResult: <verbatim final text>`.',
+    codeViaPullRequest: 'Analyst chose the code via pull request path because the existing decisions and spec items settle how the work is done and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
+    decideThenCodeViaPullRequest: 'Analyst chose the decide then code via pull request path because the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
+    needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 };
+// DEV-2 and DEV-3 and DEV-5: identical composed blockquotes.
+const PLANNED_CALL_TEMPLATE = [
+    '> Original request: <development-request>',
+    '> Prior discussion: <discussion-context>',
+    '> Planning result: <planning-result>',
+];
+// DEV-4.
+const CODE_AFTER_DECIDE_CALL_TEMPLATE = [
+    '> Original request: <development-request>',
+    '> Prior discussion: <discussion-context>',
+    '> Planning result: <planning-result>',
+    '> DECIDE commit: <decide-commit>',
+    '> Evaluated revision: <evaluated-revision>',
+];
+// DEV-6.
+const PULL_REQUEST_CALL_TEMPLATE = [
+    '> Original request: <development-request>',
+    '> Issue summary: <issue-summary>',
+    '> Branch: <branch>',
+    '> Base revision: <base-revision>',
+    '> CODE commit: <last-code-commit>',
+    '> Evaluated revision: <final-evaluated-revision>',
+];
 const STATE_DESCRIPTIONS = {
     ready: 'Waiting for a development request.',
-    planAnalysis: 'Analyst is choosing the development path.',
-    createBranch: 'The BRANCH playbook is preparing the pull-request branch for the planned development path.',
-    callCode: 'The CODE playbook is implementing the planned development path.',
-    callDecide: 'The DECIDE playbook is settling the durable decision the planned path requires.',
-    callCodeAfterDecide: 'The CODE playbook is implementing the decided development path.',
-    openPullRequest: 'The PR playbook is delivering the implemented branch through a pull request.',
-    awaitBossReply: 'Waiting for Boss to answer Analyst.',
-    failed: 'The development planning workflow failed and is waiting for a new development request.',
-    discussionComplete: 'The planning discussion concluded after a Boss reply with no repository work to follow.',
-    done: "The selected development path completed with the final child playbook's successful result.",
-    reportedChildFailure: "The development workflow relayed a child playbook's authored abort, failure, or insufficient terminal result.",
+    planAnalysis: 'Analyst chooses the development path in a short planning note.',
+    awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+    createBranch: 'The BRANCH playbook prepares the branch for the pull-request delivery path.',
+    callCode: 'The CODE playbook implements the planned development path.',
+    callDecide: 'The DECIDE playbook settles the decision the planned development path requires.',
+    callCodeAfterDecide: 'The CODE playbook implements the development path DECIDE settled.',
+    openPullRequest: 'The PR playbook delivers the implemented branch through a pull request.',
+    failed: 'DEV failed outside a child result contract and waits for a new development request.',
+    discussionComplete: 'After a Boss reply, the planning discussion concluded with no child call or repository change.',
+    done: "The selected development path completed with its final child playbook's successful result.",
+    reportedChildFailure: "DEV ended by relaying a child playbook's authored abort, failure, or result that did not prove the required success.",
 };
-function playbookMeta(stateId, role) {
+function playbookMeta(stateId) {
     return {
-        playbook: {
-            stateId,
-            description: STATE_DESCRIPTIONS[stateId],
-            ...(role === undefined ? {} : { role }),
-        },
+        playbook: { stateId, description: STATE_DESCRIPTIONS[stateId] },
+    };
+}
+function roleMeta(stateId, role) {
+    return {
+        playbook: { stateId, description: STATE_DESCRIPTIONS[stateId], role },
     };
 }
-// DR-048: a final state additionally declares whether its outcome means the
-// workflow succeeded or failed, so DEV's own caller learns that from the
-// machine rather than from DEV's output fields.
 function terminalMeta(stateId, terminal) {
     return {
-        playbook: {
-            stateId,
-            description: STATE_DESCRIPTIONS[stateId],
-            terminal,
-        },
+        playbook: { stateId, description: STATE_DESCRIPTIONS[stateId], terminal },
     };
 }
+const PLAN_ANALYSIS_QUESTION = {
+    resumeStateId: 'planAnalysis',
+    sourceItem: 'DEV-1',
+    asker: { kind: 'role', roleId: 'analyst' },
+};
 function isRecord(value) {
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {
         return false;
@@ -80,364 +111,247 @@ function isRecord(value) {
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
-function playerOutput(event) {
+// ---------------------------------------------------------------------------
+// Player output (DEV-1), narrowed structurally from an unknown done event.
+function playerOutputOf(event) {
     if (!isRecord(event))
         return undefined;
     return isRecord(event.output) ? event.output : undefined;
 }
-function outputGuard(event, guard) {
-    return playerOutput(event)?.guard === guard;
+function hasGuard(event, guard) {
+    return playerOutputOf(event)?.guard === guard;
 }
-function outputString(event, field) {
-    const value = playerOutput(event)?.[field];
+function outputText(event, field) {
+    const value = playerOutputOf(event)?.[field];
     return isNonEmptyString(value) ? value : undefined;
 }
-function isCodePath({ event }) {
-    return (outputGuard(event, 'code') &&
-        outputString(event, 'planningResult') !== undefined);
-}
-function isDecideThenCode({ event }) {
-    return (outputGuard(event, 'decideThenCode') &&
-        outputString(event, 'planningResult') !== undefined);
+function plannedPath(guard) {
+    return ({ event }) => hasGuard(event, guard) && outputText(event, 'planningResult') !== undefined;
 }
-// DR-050: the two pull-request outcomes select the same development paths
-// as `code` and `decide then code`, entered through `branch` first.
-function isCodeViaPullRequest({ event }) {
-    return (outputGuard(event, 'codeViaPullRequest') &&
-        outputString(event, 'planningResult') !== undefined);
-}
-function isDecideThenCodeViaPullRequest({ event, }) {
-    return (outputGuard(event, 'decideThenCodeViaPullRequest') &&
-        outputString(event, 'planningResult') !== undefined);
-}
-// Discussion complete is available only after a Boss reply: the round that
-// produced it must itself have been resumed with Boss's answer.
-function isDiscussionComplete({ context, event, }) {
-    return (outputGuard(event, 'discussionComplete') &&
+// Discussion complete is available only after a Boss reply: the Analyst
+// invocation that returns it must have been resumed with Boss's answer.
+function discussionCompleteAfterBossReply({ context, event, }) {
+    return (hasGuard(event, 'discussionComplete') &&
+        context.pendingBossQuestion !== undefined &&
         isNonEmptyString(context.bossReply));
 }
-function needsBossReply({ event }) {
-    return (outputGuard(event, 'needsBossReply') &&
-        outputString(event, 'question') !== undefined);
+function needsBossReplyWithQuestion({ event }) {
+    return (hasGuard(event, 'needsBossReply') && outputText(event, 'question') !== undefined);
+}
+function needsBossReplyWithoutQuestion({ event }) {
+    return (hasGuard(event, 'needsBossReply') && outputText(event, 'question') === undefined);
 }
+// ---------------------------------------------------------------------------
+// Child outputs, read only from each child's canonical structured result and
+// checked against the packaged public output interfaces.
 function childOutputOf(event) {
     return isRecord(event) ? event.output : undefined;
 }
-function isDecideSuccessValue(value) {
-    return (isRecord(value) &&
-        isNonEmptyString(value.decideCommit) &&
-        isNonEmptyString(value.evaluatedRevision) &&
-        value.noUnsettledFindings === true);
-}
-function isDecideSuccess({ event }) {
-    return isDecideSuccessValue(childOutputOf(event));
-}
-// BRANCH's canonical successful terminal output carries the exact name of
-// the new checked-out branch, the exact receipt-owned base revision, and the
-// issue summary; DEV consumes exactly those three by name and never defaults
-// a missing one.
-function isBranchSuccessValue(value) {
-    return (isRecord(value) &&
-        isNonEmptyString(value.branch) &&
-        isNonEmptyString(value.baseRevision) &&
-        isNonEmptyString(value.issueSummary));
-}
-function isBranchSuccessForCode({ context, event, }) {
-    return (context.pullRequestPath === 'code' &&
-        isBranchSuccessValue(childOutputOf(event)));
-}
-function isBranchSuccessForDecide({ context, event, }) {
-    return (context.pullRequestPath === 'decide-then-code' &&
-        isBranchSuccessValue(childOutputOf(event)));
-}
-// CODE's canonical successful terminal output discriminates completion with
-// `status: 'complete'`, carries the exact last CODE-owned commit, and
-// affirms that every phase's review passed.
-function isCodeSuccessValue(value) {
-    return (isRecord(value) &&
-        value.status === 'complete' &&
-        isNonEmptyString(value.lastCodeCommit) &&
-        value.allReviewsPassed === true);
-}
-// A plain path completes DEV on that proof alone, exactly as before DR-050.
-function isPlainCodeSuccess({ context, event, }) {
-    return (context.deliveryViaPullRequest !== true &&
-        isCodeSuccessValue(childOutputOf(event)));
-}
-// A pull-request path additionally consumes the exact final evaluated
-// repository revision for the `pr` call, so a CODE result lacking it does not
-// prove the success that path requires.
-function isCodeSuccessValueForPullRequest(value) {
-    return (isCodeSuccessValue(value) &&
-        isRecord(value) &&
-        isNonEmptyString(value.finalEvaluatedRevision));
-}
-function isCodeSuccessViaPullRequest({ context, event, }) {
-    return (context.deliveryViaPullRequest === true &&
-        isCodeSuccessValueForPullRequest(childOutputOf(event)));
-}
-function isStateValue(value, ancestors = new Set()) {
-    if (typeof value === 'string')
-        return true;
-    if (!isRecord(value) || ancestors.has(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));
-}
-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 isPlaybookState(value) {
-    if (!isRecord(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 nestedResultFromError(error) {
-    if (!(error instanceof Error))
-        return undefined;
-    const result = error.result;
-    return isRecord(result) ? result : undefined;
+function childErrorOf(event) {
+    return isRecord(event) ? event.error : undefined;
 }
-function isFailureTerminalRecord(value) {
-    if (!isRecord(value))
-        return false;
-    const allowed = new Set(['stateId', 'kind', 'description']);
-    return (Reflect.ownKeys(value).every((key) => typeof key === 'string' && allowed.has(key)) &&
-        isNonEmptyString(value.stateId) &&
-        value.kind === 'failure' &&
-        (!Object.prototype.hasOwnProperty.call(value, 'description') ||
-            typeof value.description === 'string'));
-}
-function normalizedChildFailure(error, playbookId) {
-    const result = nestedResultFromError(error);
-    if (result === undefined)
-        return undefined;
-    const allowed = new Set([
-        'status',
-        'playbookId',
-        'childSessionId',
-        'state',
-        ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
-    ]);
-    if (Reflect.ownKeys(result).some((key) => typeof key !== 'string' || !allowed.has(key)) ||
-        (result.status !== 'aborted' &&
-            result.status !== 'error' &&
-            result.status !== 'ok') ||
-        result.playbookId !== playbookId) {
+function branchSuccessOf(value) {
+    if (!isRecord(value) ||
+        value.status !== 'branched' ||
+        !isNonEmptyString(value.branch) ||
+        !isNonEmptyString(value.baseRevision) ||
+        !isNonEmptyString(value.issueSummary)) {
         return undefined;
     }
-    if (Object.prototype.hasOwnProperty.call(result, 'childSessionId') &&
-        !isNonEmptyString(result.childSessionId)) {
-        return undefined;
-    }
-    if (result.status === 'ok') {
-        if (!Object.prototype.hasOwnProperty.call(result, 'terminal') ||
-            !isFailureTerminalRecord(result.terminal) ||
-            !isNonEmptyString(result.childSessionId) ||
-            (Object.prototype.hasOwnProperty.call(result, 'state') &&
-                !isPlaybookState(result.state))) {
-            return undefined;
-        }
-        return {
-            status: 'ok',
-            ...(result.output === undefined
-                ? {}
-                : { output: result.output }),
-        };
-    }
-    if (Object.prototype.hasOwnProperty.call(result, 'state') &&
-        !isPlaybookState(result.state)) {
+    return {
+        branch: value.branch,
+        baseRevision: value.baseRevision,
+        issueSummary: value.issueSummary,
+    };
+}
+function decideSuccessOf(value) {
+    if (!isRecord(value) ||
+        value.noUnsettledFindings !== true ||
+        !isNonEmptyString(value.decideCommit) ||
+        !isNonEmptyString(value.evaluatedRevision)) {
         return undefined;
     }
-    let normalizedError;
-    if (Object.prototype.hasOwnProperty.call(result, 'error')) {
-        if (!isRecord(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') ||
-            !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 {
+        decideCommit: value.decideCommit,
+        evaluatedRevision: value.evaluatedRevision,
+    };
+}
+function codeSuccessOf(value) {
+    if (!isRecord(value) ||
+        value.status !== 'complete' ||
+        value.allReviewsPassed !== true ||
+        !isNonEmptyString(value.lastCodeCommit) ||
+        !isNonEmptyString(value.finalEvaluatedRevision)) {
         return undefined;
     }
     return {
-        status: result.status,
-        ...(normalizedError === undefined ? {} : { error: normalizedError }),
+        lastCodeCommit: value.lastCodeCommit,
+        finalEvaluatedRevision: value.finalEvaluatedRevision,
     };
 }
-function authoredChildFailureGuard(playbookId) {
-    return ({ event }) => {
-        const error = isRecord(event) ? event.error : undefined;
-        return normalizedChildFailure(error, playbookId) !== undefined;
-    };
+function branchSucceededFor(path) {
+    return ({ context, event }) => context.pullRequestPath === path &&
+        branchSuccessOf(childOutputOf(event)) !== undefined;
 }
-function authoredChildError(event, playbookId) {
-    const outer = isRecord(event) ? event.error : undefined;
-    const failure = normalizedChildFailure(outer, playbookId);
-    if (failure !== undefined && failure.status !== 'ok' && failure.error) {
-        return failure.error;
-    }
-    if (failure?.status === 'aborted') {
-        return {
-            name: 'AbortError',
-            message: `${playbookId.toUpperCase()} was aborted.`,
-        };
+function decideSucceeded({ event }) {
+    return decideSuccessOf(childOutputOf(event)) !== undefined;
+}
+function codeSucceededOnPullRequestPath({ context, event, }) {
+    return (context.pullRequestPath !== undefined &&
+        codeSuccessOf(childOutputOf(event)) !== undefined);
+}
+function codeSucceededOnPlainPath({ context, event, }) {
+    return (context.pullRequestPath === undefined &&
+        codeSuccessOf(childOutputOf(event)) !== undefined);
+}
+// ---------------------------------------------------------------------------
+// Authored rejected child results.
+export function authoredChildResult(error, expectedPlaybookId) {
+    if (!(error instanceof Error))
+        return undefined;
+    try {
+        const result = validatePlaybookCallResult(error.result, expectedPlaybookId);
+        return result.status !== 'ok' || result.terminal?.kind === 'failure'
+            ? result
+            : undefined;
     }
-    if (outer instanceof Error) {
-        return { name: outer.name || 'Error', message: outer.message };
+    catch {
+        return undefined;
     }
-    return { name: 'Error', message: String(outer) };
-}
-function relayedChildFailure(event, playbookId) {
-    const outer = isRecord(event) ? event.error : undefined;
-    const failure = normalizedChildFailure(outer, playbookId);
-    // DR-048: a completed child that reached an authored failure terminal
-    // relays its own output, exactly as a terminal result that did not prove
-    // success did before it was routed through the error path.
-    if (failure?.status === 'ok') {
+}
+function authoredResultFrom(playbookId) {
+    return ({ event }) => authoredChildResult(childErrorOf(event), playbookId) !== undefined;
+}
+function relayedChildResult(event, playbookId) {
+    const result = authoredChildResult(childErrorOf(event), playbookId);
+    if (result === undefined)
+        return undefined;
+    if (result.status === 'ok') {
+        // A child that completed at its own authored failure terminal relays its
+        // own output; an absent output is omitted rather than stored.
         return {
             playbookId,
             status: 'ok',
-            ...(failure.output === undefined ? {} : { output: failure.output }),
+            ...(result.output === undefined ? {} : { output: result.output }),
         };
     }
-    return {
-        playbookId,
-        status: failure?.status === 'aborted' ? 'aborted' : 'error',
-        error: authoredChildError(event, playbookId),
-    };
+    const error = result.error === undefined
+        ? {
+            name: 'AbortError',
+            message: `The ${playbookId} playbook call was aborted.`,
+        }
+        : { name: result.error.name, message: result.error.message };
+    return { playbookId, status: result.status, error };
 }
 function insufficientChildResult(event, playbookId) {
     const output = childOutputOf(event);
     return {
         playbookId,
         status: 'ok',
-        ...(output === undefined ? {} : { output: output }),
+        ...(output === undefined ? {} : { output }),
     };
 }
-/** Consumed planning Q&A rendered for later relayed discussion context. */
-export function renderDiscussionContext(exchanges) {
-    return exchanges
-        .map((exchange) => `Analyst question: ${exchange.question}\nBoss reply: ${exchange.answer}`)
-        .join('\n\n');
+function normalizedControlError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name.length > 0 ? error.name : 'Error',
+            message: error.message,
+            ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
+        };
+    }
+    return {
+        name: 'Error',
+        message: typeof error === 'string' ? error : 'Actor failed with a non-Error value.',
+    };
+}
+// ---------------------------------------------------------------------------
+// Discussion history and quoted-relay composition.
+/** One consumed Analyst question and Boss reply, as relayed discussion. */
+export function renderDiscussionExchange(question, answer) {
+    return `Analyst question: ${question}\nBoss reply: ${answer}`;
 }
-function archivedExchanges(context) {
+// Persists the answered pending Q&A pair into the typed discussion context
+// before the pending fields are replaced or cleared, so later calls relay it.
+function archivedDiscussion(context) {
     if (context.pendingBossQuestion === undefined ||
         !isNonEmptyString(context.bossReply)) {
-        return context.discussionExchanges;
+        return context.discussionContext;
     }
-    return [
-        ...context.discussionExchanges,
-        {
-            question: context.pendingBossQuestion.question,
-            answer: context.bossReply,
-        },
-    ];
-}
-function quotedRelay(values) {
-    return values
-        .filter(([, value]) => value.length > 0)
-        .map(([label, value]) => `${label}: ${value}`
-        .split('\n')
-        .map((line) => `> ${line}`)
-        .join('\n'))
-        .join('\n');
-}
-function planningRelayValues(context) {
-    return [
-        ['Original request', context.developmentRequest ?? ''],
-        ['Prior discussion', renderDiscussionContext(context.discussionExchanges)],
-        ['Planning result', context.planningResult ?? ''],
-    ];
-}
-function codeCallText(context) {
-    return quotedRelay(planningRelayValues(context));
-}
-function decideCallText(context) {
-    return quotedRelay(planningRelayValues(context));
+    const exchange = renderDiscussionExchange(context.pendingBossQuestion.question, context.bossReply);
+    return context.discussionContext.length > 0
+        ? `${context.discussionContext}\n\n${exchange}`
+        : exchange;
+}
+const RELAY_TOKEN = /<[a-z][a-z0-9-]*>/g;
+// Quoted-relay composition: an empty value contributes no line, every
+// continuation line of a multi-line value is quoted with `> ` (keeping LF/CRLF
+// separators), and no quoted line is inserted. Substitution is single-pass and
+// literal; a missing value keeps its placeholder literal.
+function composeRelay(template, values) {
+    const lines = [];
+    for (const line of template) {
+        const tokens = line.match(RELAY_TOKEN) ?? [];
+        if (tokens.some((token) => values[token] === ''))
+            continue;
+        const composed = line.replace(RELAY_TOKEN, (token) => {
+            const value = values[token];
+            return value === undefined
+                ? token
+                : value.replace(/\r?\n/g, (separator) => `${separator}> `);
+        });
+        lines.push(composed);
+    }
+    return lines.join('\n');
 }
-function codeAfterDecideCallText(context) {
-    return quotedRelay([
-        ...planningRelayValues(context),
-        ['DECIDE commit', context.decideCommit ?? ''],
-        ['Evaluated revision', context.evaluatedRevision ?? ''],
-    ]);
+function plannedCallValues(context) {
+    return {
+        '<development-request>': context.developmentRequest,
+        '<discussion-context>': context.discussionContext,
+        '<planning-result>': context.planningResult,
+    };
 }
-function branchCallText(context) {
-    return quotedRelay(planningRelayValues(context));
+function plannedCallText(context) {
+    return composeRelay(PLANNED_CALL_TEMPLATE, plannedCallValues(context));
+}
+function codeAfterDecideCallText(context) {
+    return composeRelay(CODE_AFTER_DECIDE_CALL_TEMPLATE, {
+        ...plannedCallValues(context),
+        '<decide-commit>': context.decideCommit,
+        '<evaluated-revision>': context.evaluatedRevision,
+    });
 }
-// DEV-6: every placeholder is substituted from typed context that only a
-// child's canonical structured result populated — never from player prose.
 function pullRequestCallText(context) {
-    return quotedRelay([
-        ['Original request', context.developmentRequest ?? ''],
-        ['Issue summary', context.issueSummary ?? ''],
-        ['Branch', context.branch ?? ''],
-        ['Base revision', context.baseRevision ?? ''],
-        ['CODE commit', context.lastCodeCommit ?? ''],
-        ['Evaluated revision', context.finalEvaluatedRevision ?? ''],
-    ]);
-}
-function acceptedPlanningPath(context, event, pullRequestPath) {
-    return {
-        planningResult: outputString(event, 'planningResult'),
-        discussionExchanges: archivedExchanges(context),
-        deliveryViaPullRequest: pullRequestPath !== undefined,
-        pullRequestPath,
-        pendingBossQuestion: undefined,
-        bossReply: undefined,
-    };
+    return composeRelay(PULL_REQUEST_CALL_TEMPLATE, {
+        '<development-request>': context.developmentRequest,
+        '<issue-summary>': context.issueSummary,
+        '<branch>': context.branch,
+        '<base-revision>': context.baseRevision,
+        '<last-code-commit>': context.lastCodeCommit,
+        '<final-evaluated-revision>': context.finalEvaluatedRevision,
+    });
+}
+// ---------------------------------------------------------------------------
+// Boss entry and reply surfaces.
+function startsDev({ event }) {
+    return (event.type === 'START_DEV' &&
+        typeof event.developmentRequest === 'string' &&
+        event.developmentRequest.trim().length > 0);
+}
+function emptyBossReply({ event }) {
+    return (event.type === 'BOSS_REPLY' &&
+        (typeof event.answer !== 'string' || event.answer.trim().length === 0));
+}
+function resumableStates(ids) {
+    return ids.map((id) => ({
+        guard: ({ context, event }) => event.type === 'BOSS_REPLY' &&
+            typeof event.answer === 'string' &&
+            event.answer.trim().length > 0 &&
+            context.pendingBossQuestion?.resumeStateId === id &&
+            (event.questionId === undefined || event.questionId === id),
+        target: `#${id}`,
+        reenter: true,
+        actions: 'rememberBossReply',
+    }));
 }
 const machineSetup = setup({
     types: {},
@@ -450,188 +364,159 @@ const machineSetup = setup({
         }),
     },
     guards: {
-        isDiscussionComplete,
-        isCodePath,
-        isDecideThenCode,
-        isCodeViaPullRequest,
-        isDecideThenCodeViaPullRequest,
-        needsBossReply,
-        isBranchSuccessForCode,
-        isBranchSuccessForDecide,
-        isCodeSuccessViaPullRequest,
-        isPlainCodeSuccess,
-        isDecideSuccess,
-        authoredBranchFailure: authoredChildFailureGuard('branch'),
-        authoredCodeFailure: authoredChildFailureGuard('code'),
-        authoredDecideFailure: authoredChildFailureGuard('decide'),
-        authoredPrFailure: authoredChildFailureGuard('pr'),
-        emptyBossReply: ({ event }) => event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
-        resumesPlanAnalysis: ({ context, event }) => event.type === 'BOSS_REPLY' &&
-            event.answer.trim().length > 0 &&
-            context.pendingBossQuestion?.resumeStateId === 'planAnalysis' &&
-            (event.questionId === undefined || event.questionId === 'planAnalysis'),
+        startsDev,
+        emptyBossReply,
+        discussionCompleteAfterBossReply,
+        codePlanned: plannedPath('code'),
+        decideThenCodePlanned: plannedPath('decideThenCode'),
+        codeViaPullRequestPlanned: plannedPath('codeViaPullRequest'),
+        decideThenCodeViaPullRequestPlanned: plannedPath('decideThenCodeViaPullRequest'),
+        needsBossReplyWithQuestion,
+        needsBossReplyWithoutQuestion,
+        branchSucceededForCode: branchSucceededFor('code'),
+        branchSucceededForDecide: branchSucceededFor('decide-then-code'),
+        decideSucceeded,
+        codeSucceededOnPullRequestPath,
+        codeSucceededOnPlainPath,
+        authoredBranchResult: authoredResultFrom('branch'),
+        authoredDecideResult: authoredResultFrom('decide'),
+        authoredCodeResult: authoredResultFrom('code'),
+        authoredPrResult: authoredResultFrom('pr'),
     },
     actions: {
         'playbook.acceptedOutcome': (_args, _params) => undefined,
-        startDev: assign(({ context, event }) => {
-            if (event.type !== 'START_DEV')
-                return {};
-            return {
-                runResults: context.runResults,
-                developmentRequest: event.developmentRequest,
-                discussionExchanges: [],
-                planningResult: undefined,
-                decideCommit: undefined,
-                evaluatedRevision: undefined,
-                deliveryViaPullRequest: false,
-                pullRequestPath: undefined,
-                branch: undefined,
-                baseRevision: undefined,
-                issueSummary: undefined,
-                lastCodeCommit: undefined,
-                finalEvaluatedRevision: undefined,
-                completion: undefined,
-                childOutput: undefined,
-                childFailure: undefined,
-                lastError: undefined,
-                pendingBossQuestion: undefined,
-                bossReply: undefined,
-            };
-        }),
+        startDev: assign(({ event }) => ({
+            developmentRequest: event.type === 'START_DEV' ? event.developmentRequest : undefined,
+            discussionContext: '',
+            planningResult: undefined,
+            pullRequestPath: undefined,
+            decideCommit: undefined,
+            evaluatedRevision: undefined,
+            branch: undefined,
+            baseRevision: undefined,
+            issueSummary: undefined,
+            lastCodeCommit: undefined,
+            finalEvaluatedRevision: undefined,
+            completion: undefined,
+            lastError: undefined,
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
         completeDiscussion: assign(({ context }) => ({
-            discussionExchanges: archivedExchanges(context),
-            completion: 'discussion-complete',
+            discussionContext: archivedDiscussion(context),
+            completion: { kind: 'discussion-complete' },
             pendingBossQuestion: undefined,
             bossReply: undefined,
         })),
-        rememberCodePath: assign(({ context, event }) => acceptedPlanningPath(context, event)),
-        rememberDecidePath: assign(({ context, event }) => acceptedPlanningPath(context, event)),
-        rememberCodeViaPullRequestPath: assign(({ context, event }) => acceptedPlanningPath(context, event, 'code')),
-        rememberDecideThenCodeViaPullRequestPath: assign(({ context, event }) => acceptedPlanningPath(context, event, 'decide-then-code')),
-        rememberPendingQuestion: assign(({ context, event }) => {
-            const question = outputString(event, 'question');
-            if (question === undefined || !outputGuard(event, 'needsBossReply')) {
-                return { lastError: new Error('Analyst question output was malformed') };
-            }
-            return {
-                discussionExchanges: archivedExchanges(context),
-                pendingBossQuestion: {
-                    questionId: 'planAnalysis',
-                    resumeStateId: 'planAnalysis',
-                    sourceItem: 'DEV-1',
-                    asker: { kind: 'role', roleId: 'analyst' },
-                    question,
-                },
-                bossReply: undefined,
-            };
-        }),
+        acceptPlainPlan: assign(({ context, event }) => ({
+            planningResult: outputText(event, 'planningResult'),
+            discussionContext: archivedDiscussion(context),
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        acceptPullRequestPlan: assign(({ context, event }, params) => ({
+            planningResult: outputText(event, 'planningResult'),
+            pullRequestPath: params.path,
+            discussionContext: archivedDiscussion(context),
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        setPendingBossQuestion: assign(({ context, event }, params) => ({
+            discussionContext: archivedDiscussion(context),
+            pendingBossQuestion: {
+                ...params,
+                questionId: params.resumeStateId,
+                question: outputText(event, 'question') ?? '',
+            },
+            bossReply: undefined,
+        })),
         rememberBossReply: assign(({ event }) => event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {}),
-        rememberEmptyBossReplyError: assign({
-            lastError: () => new Error('BOSS_REPLY received an empty answer'),
+        clearBossReplyContext: assign({
             pendingBossQuestion: undefined,
             bossReply: undefined,
         }),
         rememberBranchResult: assign(({ event }) => {
-            const output = childOutputOf(event);
-            if (!isBranchSuccessValue(output))
-                return {};
-            return {
-                branch: output.branch,
-                baseRevision: output.baseRevision,
-                issueSummary: output.issueSummary,
-            };
+            const success = branchSuccessOf(childOutputOf(event));
+            return success === undefined ? {} : { ...success };
         }),
         rememberDecideResult: assign(({ event }) => {
-            const output = childOutputOf(event);
-            if (!isDecideSuccessValue(output))
-                return {};
-            return {
-                decideCommit: output.decideCommit,
-                evaluatedRevision: output.evaluatedRevision,
-            };
+            const success = decideSuccessOf(childOutputOf(event));
+            return success === undefined ? {} : { ...success };
         }),
         rememberCodeResult: assign(({ event }) => {
-            const output = childOutputOf(event);
-            if (!isCodeSuccessValueForPullRequest(output))
-                return {};
-            return {
-                lastCodeCommit: output.lastCodeCommit,
-                finalEvaluatedRevision: output.finalEvaluatedRevision,
-            };
+            const success = codeSuccessOf(childOutputOf(event));
+            return success === undefined ? {} : { ...success };
         }),
-        completeWithChildSuccess: assign(({ event }) => {
+        completeWithChildSuccess: assign(({ event }, params) => {
             const output = childOutputOf(event);
             return {
-                completion: 'complete',
-                ...(output === undefined ? {} : { childOutput: output }),
+                completion: {
+                    kind: 'complete',
+                    childPlaybookId: params.childPlaybookId,
+                    ...(output === undefined ? {} : { childOutput: output }),
+                },
             };
         }),
-        completeWithInsufficientBranchResult: assign(({ event }) => ({
-            completion: 'child-failed',
-            childFailure: insufficientChildResult(event, 'branch'),
-        })),
-        completeWithInsufficientCodeResult: assign(({ event }) => ({
-            completion: 'child-failed',
-            childFailure: insufficientChildResult(event, 'code'),
-        })),
-        completeWithInsufficientDecideResult: assign(({ event }) => ({
-            completion: 'child-failed',
-            childFailure: insufficientChildResult(event, 'decide'),
-        })),
-        completeWithBranchFailure: assign(({ event }) => ({
-            completion: 'child-failed',
-            childFailure: relayedChildFailure(event, 'branch'),
-        })),
-        completeWithCodeFailure: assign(({ event }) => ({
-            completion: 'child-failed',
-            childFailure: relayedChildFailure(event, 'code'),
-        })),
-        completeWithDecideFailure: assign(({ event }) => ({
-            completion: 'child-failed',
-            childFailure: relayedChildFailure(event, 'decide'),
-        })),
-        completeWithPrFailure: assign(({ event }) => ({
-            completion: 'child-failed',
-            childFailure: relayedChildFailure(event, 'pr'),
+        completeWithInsufficientResult: assign(({ event }, params) => ({
+            completion: {
+                kind: 'child-failed',
+                childResult: insufficientChildResult(event, params.playbookId),
+            },
         })),
+        completeWithAuthoredChildResult: assign(({ event }, params) => {
+            const childResult = relayedChildResult(event, params.playbookId);
+            return childResult === undefined
+                ? {}
+                : { completion: { kind: 'child-failed', childResult } };
+        }),
         rememberActorError: assign(({ event }) => ({
-            lastError: event.error,
+            lastError: normalizedControlError(childErrorOf(event)),
         })),
         rememberMalformedPlayerOutput: assign({
-            lastError: () => new Error('Analyst result for DEV-1 did not match an available outcome.'),
+            lastError: {
+                name: 'MalformedActorOutput',
+                message: 'Analyst output for DEV-1 did not match an available declared result.',
+            },
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        }),
+        rememberMalformedBossReply: assign({
+            lastError: {
+                name: 'MalformedBossReply',
+                message: 'BOSS_REPLY carried an empty or whitespace-only answer.',
+            },
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
         }),
     },
 });
 export const devMachine = machineSetup.createMachine({
     id: 'dev',
+    description: 'Plans the development path for a request and runs the child playbooks it selects.',
     initial: 'ready',
     context: ({ input }) => ({
-        runResults: typeof input.runResults === 'string' ? input.runResults : '',
-        discussionExchanges: [],
-        deliveryViaPullRequest: false,
+        runResults: typeof input?.runResults === 'string' ? input.runResults : '',
+        discussionContext: '',
     }),
     output: ({ context }) => {
-        if (context.completion === 'discussion-complete') {
-            return { status: 'discussion-complete' };
-        }
-        if (context.completion === 'complete') {
-            return {
-                status: 'complete',
-                // `done` is entered by `pr` on a pull-request path and by `code` on a
-                // plain path; no other arm completes the workflow.
-                childPlaybookId: context.deliveryViaPullRequest ? 'pr' : 'code',
-                ...(context.childOutput === undefined
-                    ? {}
-                    : { childOutput: context.childOutput }),
-            };
+        const completion = context.completion;
+        if (completion === undefined) {
+            throw new Error('DEV reached a final state without a recorded completion');
         }
-        if (context.completion === 'child-failed') {
-            if (context.childFailure === undefined) {
-                throw new Error('DEV reached a final state without a child result');
-            }
-            return { status: 'child-failed', childResult: context.childFailure };
+        switch (completion.kind) {
+            case 'discussion-complete':
+                return { status: 'discussion-complete' };
+            case 'complete':
+                return {
+                    status: 'complete',
+                    childPlaybookId: completion.childPlaybookId,
+                    ...(completion.childOutput === undefined
+                        ? {}
+                        : { childOutput: completion.childOutput }),
+                };
+            case 'child-failed':
+                return { status: 'child-failed', childResult: completion.childResult };
         }
-        throw new Error('DEV reached a final state without a recorded completion');
     },
     states: {
         ready: {
@@ -640,13 +525,17 @@ export const devMachine = machineSetup.createMachine({
             meta: playbookMeta('ready'),
             tags: ['playbook.parked'],
             on: {
-                START_DEV: { target: 'planAnalysis', actions: 'startDev' },
+                START_DEV: {
+                    guard: 'startsDev',
+                    target: 'planAnalysis',
+                    actions: 'startDev',
+                },
             },
         },
         planAnalysis: {
             id: 'planAnalysis',
             description: STATE_DESCRIPTIONS.planAnalysis,
-            meta: playbookMeta('planAnalysis', 'analyst'),
+            meta: roleMeta('planAnalysis', 'analyst'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
@@ -655,9 +544,9 @@ export const devMachine = machineSetup.createMachine({
                     role: 'analyst',
                     sourceItem: 'DEV-1',
                     prompt: PLAN_ANALYSIS_PROMPT,
-                    result: PLAN_ANALYSIS_RESULTS,
+                    result: PLAN_ANALYSIS_RESULT,
                     developmentRequest: context.developmentRequest ?? '',
-                    discussionContext: renderDiscussionContext(context.discussionExchanges),
+                    discussionContext: context.discussionContext,
                     runResults: context.runResults,
                     ...(context.pendingBossQuestion === undefined
                         ? {}
@@ -668,7 +557,27 @@ export const devMachine = machineSetup.createMachine({
                 }),
                 onDone: [
                     {
-                        guard: 'isDiscussionComplete',
+                        guard: 'needsBossReplyWithQuestion',
+                        target: 'awaitBossReply',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'planAnalysis',
+                                    target: 'awaitBossReply',
+                                    acceptedOutcome: 'needsBossReply',
+                                },
+                            },
+                            { type: 'setPendingBossQuestion', params: PLAN_ANALYSIS_QUESTION },
+                        ],
+                    },
+                    {
+                        guard: 'needsBossReplyWithoutQuestion',
+                        target: 'failed',
+                        actions: 'rememberMalformedPlayerOutput',
+                    },
+                    {
+                        guard: 'discussionCompleteAfterBossReply',
                         target: 'discussionComplete',
                         actions: [
                             {
@@ -683,7 +592,7 @@ export const devMachine = machineSetup.createMachine({
                         ],
                     },
                     {
-                        guard: 'isCodePath',
+                        guard: 'codePlanned',
                         target: 'callCode',
                         actions: [
                             {
@@ -694,11 +603,11 @@ export const devMachine = machineSetup.createMachine({
                                     acceptedOutcome: 'code',
                                 },
                             },
-                            'rememberCodePath',
+                            'acceptPlainPlan',
                         ],
                     },
                     {
-                        guard: 'isDecideThenCode',
+                        guard: 'decideThenCodePlanned',
                         target: 'callDecide',
                         actions: [
                             {
@@ -709,11 +618,11 @@ export const devMachine = machineSetup.createMachine({
                                     acceptedOutcome: 'decideThenCode',
                                 },
                             },
-                            'rememberDecidePath',
+                            'acceptPlainPlan',
                         ],
                     },
                     {
-                        guard: 'isCodeViaPullRequest',
+                        guard: 'codeViaPullRequestPlanned',
                         target: 'createBranch',
                         actions: [
                             {
@@ -724,11 +633,11 @@ export const devMachine = machineSetup.createMachine({
                                     acceptedOutcome: 'codeViaPullRequest',
                                 },
                             },
-                            'rememberCodeViaPullRequestPath',
+                            { type: 'acceptPullRequestPlan', params: { path: 'code' } },
                         ],
                     },
                     {
-                        guard: 'isDecideThenCodeViaPullRequest',
+                        guard: 'decideThenCodeViaPullRequestPlanned',
                         target: 'createBranch',
                         actions: [
                             {
@@ -739,22 +648,10 @@ export const devMachine = machineSetup.createMachine({
                                     acceptedOutcome: 'decideThenCodeViaPullRequest',
                                 },
                             },
-                            'rememberDecideThenCodeViaPullRequestPath',
-                        ],
-                    },
-                    {
-                        guard: 'needsBossReply',
-                        target: 'awaitBossReply',
-                        actions: [
                             {
-                                type: 'playbook.acceptedOutcome',
-                                params: {
-                                    source: 'planAnalysis',
-                                    target: 'awaitBossReply',
-                                    acceptedOutcome: 'needsBossReply',
-                                },
+                                type: 'acceptPullRequestPlan',
+                                params: { path: 'decide-then-code' },
                             },
-                            'rememberPendingQuestion',
                         ],
                     },
                     {
@@ -762,7 +659,31 @@ export const devMachine = machineSetup.createMachine({
                         actions: 'rememberMalformedPlayerOutput',
                     },
                 ],
-                onError: { target: 'failed', actions: 'rememberActorError' },
+                onError: {
+                    target: 'failed',
+                    actions: ['rememberActorError', 'clearBossReplyContext'],
+                },
+            },
+        },
+        awaitBossReply: {
+            id: 'awaitBossReply',
+            description: STATE_DESCRIPTIONS.awaitBossReply,
+            meta: playbookMeta('awaitBossReply'),
+            tags: ['playbook.parked'],
+            on: {
+                BOSS_REPLY: [
+                    {
+                        guard: 'emptyBossReply',
+                        target: 'failed',
+                        actions: 'rememberMalformedBossReply',
+                    },
+                    ...resumableStates(['planAnalysis']),
+                ],
+                START_DEV: {
+                    guard: 'startsDev',
+                    target: 'planAnalysis',
+                    actions: 'startDev',
+                },
             },
         },
         createBranch: {
@@ -776,29 +697,35 @@ export const devMachine = machineSetup.createMachine({
                     stateId: 'createBranch',
                     sourceItem: 'DEV-5',
                     playbookId: 'branch',
-                    text: branchCallText(context),
+                    text: plannedCallText(context),
                 }),
                 onDone: [
                     {
-                        guard: 'isBranchSuccessForCode',
+                        guard: 'branchSucceededForCode',
                         target: 'callCode',
                         actions: 'rememberBranchResult',
                     },
                     {
-                        guard: 'isBranchSuccessForDecide',
+                        guard: 'branchSucceededForDecide',
                         target: 'callDecide',
                         actions: 'rememberBranchResult',
                     },
                     {
                         target: 'reportedChildFailure',
-                        actions: 'completeWithInsufficientBranchResult',
+                        actions: {
+                            type: 'completeWithInsufficientResult',
+                            params: { playbookId: 'branch' },
+                        },
                     },
                 ],
                 onError: [
                     {
-                        guard: 'authoredBranchFailure',
+                        guard: 'authoredBranchResult',
                         target: 'reportedChildFailure',
-                        actions: 'completeWithBranchFailure',
+                        actions: {
+                            type: 'completeWithAuthoredChildResult',
+                            params: { playbookId: 'branch' },
+                        },
                     },
                     { target: 'failed', actions: 'rememberActorError' },
                 ],
@@ -815,29 +742,38 @@ export const devMachine = machineSetup.createMachine({
                     stateId: 'callCode',
                     sourceItem: 'DEV-2',
                     playbookId: 'code',
-                    text: codeCallText(context),
+                    text: plannedCallText(context),
                 }),
                 onDone: [
                     {
-                        guard: 'isCodeSuccessViaPullRequest',
+                        guard: 'codeSucceededOnPullRequestPath',
                         target: 'openPullRequest',
                         actions: 'rememberCodeResult',
                     },
                     {
-                        guard: 'isPlainCodeSuccess',
+                        guard: 'codeSucceededOnPlainPath',
                         target: 'done',
-                        actions: 'completeWithChildSuccess',
+                        actions: {
+                            type: 'completeWithChildSuccess',
+                            params: { childPlaybookId: 'code' },
+                        },
                     },
                     {
                         target: 'reportedChildFailure',
-                        actions: 'completeWithInsufficientCodeResult',
+                        actions: {
+                            type: 'completeWithInsufficientResult',
+                            params: { playbookId: 'code' },
+                        },
                     },
                 ],
                 onError: [
                     {
-                        guard: 'authoredCodeFailure',
+                        guard: 'authoredCodeResult',
                         target: 'reportedChildFailure',
-                        actions: 'completeWithCodeFailure',
+                        actions: {
+                            type: 'completeWithAuthoredChildResult',
+                            params: { playbookId: 'code' },
+                        },
                     },
                     { target: 'failed', actions: 'rememberActorError' },
                 ],
@@ -854,24 +790,30 @@ export const devMachine = machineSetup.createMachine({
                     stateId: 'callDecide',
                     sourceItem: 'DEV-3',
                     playbookId: 'decide',
-                    text: decideCallText(context),
+                    text: plannedCallText(context),
                 }),
                 onDone: [
                     {
-                        guard: 'isDecideSuccess',
+                        guard: 'decideSucceeded',
                         target: 'callCodeAfterDecide',
                         actions: 'rememberDecideResult',
                     },
                     {
                         target: 'reportedChildFailure',
-                        actions: 'completeWithInsufficientDecideResult',
+                        actions: {
+                            type: 'completeWithInsufficientResult',
+                            params: { playbookId: 'decide' },
+                        },
                     },
                 ],
                 onError: [
                     {
-                        guard: 'authoredDecideFailure',
+                        guard: 'authoredDecideResult',
                         target: 'reportedChildFailure',
-                        actions: 'completeWithDecideFailure',
+                        actions: {
+                            type: 'completeWithAuthoredChildResult',
+                            params: { playbookId: 'decide' },
+                        },
                     },
                     { target: 'failed', actions: 'rememberActorError' },
                 ],
@@ -892,25 +834,34 @@ export const devMachine = machineSetup.createMachine({
                 }),
                 onDone: [
                     {
-                        guard: 'isCodeSuccessViaPullRequest',
+                        guard: 'codeSucceededOnPullRequestPath',
                         target: 'openPullRequest',
                         actions: 'rememberCodeResult',
                     },
                     {
-                        guard: 'isPlainCodeSuccess',
+                        guard: 'codeSucceededOnPlainPath',
                         target: 'done',
-                        actions: 'completeWithChildSuccess',
+                        actions: {
+                            type: 'completeWithChildSuccess',
+                            params: { childPlaybookId: 'code' },
+                        },
                     },
                     {
                         target: 'reportedChildFailure',
-                        actions: 'completeWithInsufficientCodeResult',
+                        actions: {
+                            type: 'completeWithInsufficientResult',
+                            params: { playbookId: 'code' },
+                        },
                     },
                 ],
                 onError: [
                     {
-                        guard: 'authoredCodeFailure',
+                        guard: 'authoredCodeResult',
                         target: 'reportedChildFailure',
-                        actions: 'completeWithCodeFailure',
+                        actions: {
+                            type: 'completeWithAuthoredChildResult',
+                            params: { playbookId: 'code' },
+                        },
                     },
                     { target: 'failed', actions: 'rememberActorError' },
                 ],
@@ -929,67 +880,58 @@ export const devMachine = machineSetup.createMachine({
                     playbookId: 'pr',
                     text: pullRequestCallText(context),
                 }),
-                // DR-048: `pr` declares its terminal kinds, so `onDone` alone proves
-                // its success; DEV consumes none of its fields by name.
-                onDone: { target: 'done', actions: 'completeWithChildSuccess' },
+                // `pr` success completes DEV with that result; a `pr` failure
+                // terminal arrives through `onError` and is relayed below.
+                onDone: {
+                    target: 'done',
+                    actions: {
+                        type: 'completeWithChildSuccess',
+                        params: { childPlaybookId: 'pr' },
+                    },
+                },
                 onError: [
                     {
-                        guard: 'authoredPrFailure',
+                        guard: 'authoredPrResult',
                         target: 'reportedChildFailure',
-                        actions: 'completeWithPrFailure',
+                        actions: {
+                            type: 'completeWithAuthoredChildResult',
+                            params: { playbookId: 'pr' },
+                        },
                     },
                     { target: 'failed', actions: 'rememberActorError' },
                 ],
             },
         },
-        awaitBossReply: {
-            id: 'awaitBossReply',
-            description: STATE_DESCRIPTIONS.awaitBossReply,
-            meta: playbookMeta('awaitBossReply'),
-            tags: ['playbook.parked'],
-            on: {
-                BOSS_REPLY: [
-                    {
-                        guard: 'emptyBossReply',
-                        target: '#failed',
-                        actions: 'rememberEmptyBossReplyError',
-                    },
-                    {
-                        guard: 'resumesPlanAnalysis',
-                        target: '#planAnalysis',
-                        reenter: true,
-                        actions: 'rememberBossReply',
-                    },
-                ],
-                START_DEV: { target: 'planAnalysis', actions: 'startDev' },
-            },
-        },
         failed: {
             id: 'failed',
             description: STATE_DESCRIPTIONS.failed,
             meta: playbookMeta('failed'),
             tags: ['playbook.parked'],
             on: {
-                START_DEV: { target: 'planAnalysis', actions: 'startDev' },
+                START_DEV: {
+                    guard: 'startsDev',
+                    target: 'planAnalysis',
+                    actions: 'startDev',
+                },
             },
         },
         discussionComplete: {
             id: 'discussionComplete',
+            type: 'final',
             description: STATE_DESCRIPTIONS.discussionComplete,
             meta: terminalMeta('discussionComplete', 'success'),
-            type: 'final',
         },
         done: {
             id: 'done',
+            type: 'final',
             description: STATE_DESCRIPTIONS.done,
             meta: terminalMeta('done', 'success'),
-            type: 'final',
         },
         reportedChildFailure: {
             id: 'reportedChildFailure',
+            type: 'final',
             description: STATE_DESCRIPTIONS.reportedChildFailure,
             meta: terminalMeta('reportedChildFailure', 'failure'),
-            type: 'final',
         },
     },
 });