@sublang/playbook 11.0.0 → 12.1.0

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

@@ -4080,7 +4080,10 @@ function validateEffectLedgerAuthority(value, record, owner) {
   return authority;
 }
 
-function applyEffectLedgerCommands(
+// Exported for the private worktree host-capability constructor in
+// repository-effects.js, so an external host's in-memory ledger applies the
+// exact command semantics the durable Captain record applies.
+export function applyEffectLedgerCommands(
   ledgerValue,
   authority,
   uncertain,

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

@@ -23,7 +23,6 @@ export type PlayerInput = {
     readonly callerInput: string;
     readonly runResults: string;
     readonly irNumber?: string;
-    readonly irTask?: string;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
 };
@@ -36,16 +35,18 @@ export type PlayerOutput = {
     readonly coderOutput: string;
     readonly latestCommit: string;
     readonly irNumber: string;
-    readonly irTask: string;
 } | {
     readonly guard: 'moreTasks';
     readonly coderOutput: string;
     readonly latestCommit: string;
+    readonly irNumber: string;
     readonly irTask: string;
 } | {
     readonly guard: 'finalTask';
     readonly coderOutput: string;
     readonly latestCommit: string;
+    readonly irNumber: string;
+    readonly irTask: string;
 } | {
     readonly guard: 'needsBossReply';
     readonly question: string;
@@ -57,8 +58,13 @@ export type PlaybookInput = {
     readonly text: string;
 };
 export type ReviewOutput = {
-    readonly approvedCommit: 'latest';
     readonly noUnsettledFindings: true;
+    /**
+     * Exact repository revision at which the review scope was evaluated:
+     * the last review-fix commit when one landed, otherwise the clean
+     * round's receipt-observed HEAD (DR-045). Always present.
+     */
+    readonly evaluatedRevision: string;
 };
 export type CompactError = {
     readonly name: string;
@@ -66,16 +72,16 @@ export type CompactError = {
 };
 export type CodePlaybookOutput = {
     readonly status: 'complete';
-    /** Exact identity of the latest CODE-owned commit. */
+    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
-    /** Exact Coder final text produced after that commit. */
-    readonly lastCodeOutput: string;
+    /** Exact repository revision the final passing review evaluated. */
+    readonly finalEvaluatedRevision: string;
+    /** Every phase's review passed with no unsettled findings. */
+    readonly allReviewsPassed: true;
 } | {
     readonly status: 'review-failed';
-    /** Exact identity of the latest CODE-owned commit. */
+    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
-    /** Exact Coder final text produced after that commit. */
-    readonly lastCodeOutput: string;
     readonly error: CompactError;
 };
 export type CodingInput = {
@@ -88,7 +94,7 @@ export type CodingContext = {
     readonly latestCommit?: string;
     readonly irNumber?: string;
     readonly irTask?: string;
-    readonly nextIrTask?: string;
+    readonly evaluatedRevision?: string;
     readonly phase?: CodePhase;
     readonly completion?: 'complete' | 'review-failed';
     readonly reviewError?: CompactError;
@@ -146,9 +152,6 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
 } | {
     type: "rememberFinalTask";
     params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "advanceToNextIrTask";
-    params: import("xstate").NonReducibleUnknown;
 } | {
     type: "rememberPendingQuestion";
     params: import("xstate").NonReducibleUnknown;
@@ -211,16 +214,16 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
     params: unknown;
 }, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
     readonly status: "complete";
-    /** Exact identity of the latest CODE-owned commit. */
+    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
-    /** Exact Coder final text produced after that commit. */
-    readonly lastCodeOutput: string;
+    /** Exact repository revision the final passing review evaluated. */
+    readonly finalEvaluatedRevision: string;
+    /** Every phase's review passed with no unsettled findings. */
+    readonly allReviewsPassed: true;
 } | {
     readonly status: "review-failed";
-    /** Exact identity of the latest CODE-owned commit. */
+    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
-    /** Exact Coder final text produced after that commit. */
-    readonly lastCodeOutput: string;
     readonly error: CompactError;
 }, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "code";

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

@@ -3,56 +3,70 @@
 //
 // Generated by slc/gears2fsm.md from ./code.gears.md.
 import { assign, fromPromise, setup } from 'xstate';
+const APPENDED_PHASE_PROMPT = [
+    'Keep to the original intent and follow what it asks.',
+    'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
+    "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
+    'Make the commit message explain concisely what changed and why, including relevant verification.',
+    'Identify every new commit you make.',
+    'Coder is <coder-llm>.',
+];
 const FIRST_PHASE_PROMPT = [
     '> <caller-input>',
     '> <run-results>',
     '',
-    'Assess whether the coding intent can be completed well in one commit.',
-    'If yes, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.',
-    'Otherwise, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.',
+    'First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.',
+    'If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.',
+    '',
+    'For a new coding intent, assess whether it can be completed well in one commit.',
+    'If it can, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.',
+    'If it cannot, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.',
     'Plan affected spec updates before, with, or after their corresponding code changes, either as standalone IR tasks or as explicit work within related tasks.',
     '',
+    'For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
+    'Do not implement a later task in this phase.',
+    "Mark the IR's progress and deliverables when relevant.",
+    'If the IR will be finished after this phase, double-check that all acceptance criteria are met.',
+    '',
     'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
     '',
-    'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
-    "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
-    'Make the commit message explain concisely what changed and why, including relevant verification.',
-    'Coder is <coder-llm>; format the model token in conventional human form.',
+    ...APPENDED_PHASE_PROMPT,
 ].join('\n');
 const IR_TASK_PROMPT = [
-    '> <ir-task>',
+    '> <caller-input>',
+    '> <ir-number>',
     '> <run-results>',
     '',
-    'Read IR-<#> and implement exactly the next unfinished task, including corresponding tests or specs if any.',
+    'Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
     'Do not implement a later task in this phase.',
     "Mark the IR's progress and deliverables when relevant.",
     'If the IR will be finished after this phase, double-check that all acceptance criteria are met.',
     '',
-    'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
-    "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
-    'Make the commit message explain concisely what changed and why, including relevant verification.',
-    'Coder is <coder-llm>; format the model token in conventional human form.',
+    ...APPENDED_PHASE_PROMPT,
 ].join('\n');
+const NEEDS_BOSS_REPLY_RESULT = "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 FIRST_PHASE_RESULTS = {
     directCommit: 'Coder completed and committed the direct implementation phase. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
-    irCommit: 'Coder created and committed a new IR without implementing an IR task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber`, and `irTask` naming the exact next unfinished task.',
-    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>`.",
+    irCommit: 'Coder created and committed a new IR without implementing an IR task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.',
+    moreTasks: 'Coder continued an existing IR, completed and committed exactly its next unfinished task, and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.',
+    finalTask: 'Coder continued an existing IR and completed and committed its final task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.',
+    needsBossReply: NEEDS_BOSS_REPLY_RESULT,
 };
 const IR_TASK_RESULTS = {
-    moreTasks: 'Coder completed and committed the current IR task and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irTask` naming the exact next unfinished task.',
-    finalTask: 'Coder completed and committed the final IR task. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
-    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>`.",
+    moreTasks: "Coder completed and committed exactly the IR's next unfinished task and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
+    finalTask: "Coder completed and committed the IR's final task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
+    needsBossReply: NEEDS_BOSS_REPLY_RESULT,
 };
 const STATE_DESCRIPTIONS = {
     ready: 'Waiting for a coding intent.',
-    runFirstPhase: 'Coder is implementing one direct phase or committing a new intent record.',
-    reviewFirstCommit: 'The REVIEW playbook is checking the first phase commit.',
+    runFirstPhase: 'Coder is running the first coding phase: a direct implementation, a new intent record, or an existing intent-record task.',
+    reviewFirstCommit: 'The REVIEW playbook is checking the direct or new-IR phase commit.',
     runIrTask: 'Coder is implementing exactly one unfinished intent-record task.',
     reviewIrTask: 'The REVIEW playbook is checking the latest task commit.',
     awaitBossReply: 'Waiting for Boss to answer Coder.',
     failed: 'The coding workflow failed and is waiting for a new coding intent.',
     reportedReviewFailure: 'The coding workflow reported a REVIEW failure and the last code-owned commit.',
-    done: 'The coding workflow completed after REVIEW found no unsettled findings.',
+    done: "The coding workflow completed after every phase's REVIEW passed with no unsettled findings.",
 };
 function playbookMeta(stateId, role) {
     return {
@@ -89,6 +103,11 @@ function hasCommittedOutput(event) {
     return (outputString(event, 'coderOutput') !== undefined &&
         outputString(event, 'latestCommit') !== undefined);
 }
+function hasIrTaskOutput(event) {
+    return (hasCommittedOutput(event) &&
+        outputString(event, 'irNumber') !== undefined &&
+        outputString(event, 'irTask') !== undefined);
+}
 function isDirectCommit({ event }) {
     return (outputGuard(event, 'directCommit') &&
         hasCommittedOutput(event));
@@ -96,17 +115,15 @@ function isDirectCommit({ event }) {
 function isIrCommit({ event }) {
     return (outputGuard(event, 'irCommit') &&
         hasCommittedOutput(event) &&
-        outputString(event, 'irNumber') !== undefined &&
-        outputString(event, 'irTask') !== undefined);
+        outputString(event, 'irNumber') !== undefined);
 }
 function isMoreTasks({ event }) {
     return (outputGuard(event, 'moreTasks') &&
-        hasCommittedOutput(event) &&
-        outputString(event, 'irTask') !== undefined);
+        hasIrTaskOutput(event));
 }
 function isFinalTask({ event }) {
     return (outputGuard(event, 'finalTask') &&
-        hasCommittedOutput(event));
+        hasIrTaskOutput(event));
 }
 function needsBossReply({ event }) {
     return (outputGuard(event, 'needsBossReply') &&
@@ -116,11 +133,14 @@ function reviewOutput(event) {
     return isRecord(event) ? event.output : undefined;
 }
 function isReviewApprovedValue(value) {
-    return (isRecord(value) &&
-        Object.keys(value).sort().join('\0') ===
-            ['approvedCommit', 'noUnsettledFindings'].sort().join('\0') &&
-        value.approvedCommit === 'latest' &&
-        value.noUnsettledFindings === true);
+    if (!isRecord(value))
+        return false;
+    if (Reflect.ownKeys(value).some((key) => typeof key !== 'string' ||
+        (key !== 'noUnsettledFindings' && key !== 'evaluatedRevision'))) {
+        return false;
+    }
+    return (value.noUnsettledFindings === true &&
+        isNonEmptyString(value.evaluatedRevision));
 }
 function reviewApprovedFor(phase) {
     return ({ context, event }) => context.phase === phase && isReviewApprovedValue(reviewOutput(event));
@@ -265,16 +285,23 @@ function quoteRelay(label, value) {
     const lines = value.split('\n');
     return [`> ${label}: ${lines[0] ?? ''}`, ...lines.slice(1).map((line) => `> ${line}`)].join('\n');
 }
-function initialReviewText(context) {
+function reviewScopeLine(context) {
+    return (`> Review scope: the commit ${context.latestCommit ?? ''} ` +
+        'from this coding phase and its resulting repository state.');
+}
+function newIntentReviewText(context) {
     return [
-        quoteRelay('Initial intent', context.callerInput ?? ''),
+        quoteRelay('Original intent', context.callerInput ?? ''),
+        reviewScopeLine(context),
         quoteRelay('Coder output', context.coderOutput ?? ''),
     ].join('\n');
 }
 function irTaskReviewText(context) {
     return [
-        quoteRelay('IR task', context.irTask ?? ''),
+        quoteRelay('Original intent', context.callerInput ?? ''),
+        reviewScopeLine(context),
         quoteRelay('Coder output', context.coderOutput ?? ''),
+        quoteRelay('Current IR task', context.irTask ?? ''),
     ].join('\n');
 }
 const machineSetup = setup({
@@ -320,7 +347,7 @@ const machineSetup = setup({
                 latestCommit: undefined,
                 irNumber: undefined,
                 irTask: undefined,
-                nextIrTask: undefined,
+                evaluatedRevision: undefined,
                 phase: undefined,
                 completion: undefined,
                 reviewError: undefined,
@@ -340,8 +367,7 @@ const machineSetup = setup({
             coderOutput: outputString(event, 'coderOutput'),
             latestCommit: outputString(event, 'latestCommit'),
             irNumber: outputString(event, 'irNumber'),
-            irTask: outputString(event, 'irTask'),
-            nextIrTask: undefined,
+            irTask: undefined,
             phase: 'ir-created',
             pendingBossQuestion: undefined,
             bossReply: undefined,
@@ -349,7 +375,8 @@ const machineSetup = setup({
         rememberMoreTasks: assign(({ event }) => ({
             coderOutput: outputString(event, 'coderOutput'),
             latestCommit: outputString(event, 'latestCommit'),
-            nextIrTask: outputString(event, 'irTask'),
+            irNumber: outputString(event, 'irNumber'),
+            irTask: outputString(event, 'irTask'),
             phase: 'ir-task-more',
             pendingBossQuestion: undefined,
             bossReply: undefined,
@@ -357,15 +384,12 @@ const machineSetup = setup({
         rememberFinalTask: assign(({ event }) => ({
             coderOutput: outputString(event, 'coderOutput'),
             latestCommit: outputString(event, 'latestCommit'),
-            nextIrTask: undefined,
+            irNumber: outputString(event, 'irNumber'),
+            irTask: outputString(event, 'irTask'),
             phase: 'ir-task-final',
             pendingBossQuestion: undefined,
             bossReply: undefined,
         })),
-        advanceToNextIrTask: assign(({ context }) => ({
-            irTask: context.nextIrTask,
-            nextIrTask: undefined,
-        })),
         rememberPendingQuestion: assign(({ context, event }) => {
             const question = outputString(event, 'question');
             const output = playerOutput(event);
@@ -390,9 +414,14 @@ const machineSetup = setup({
             pendingBossQuestion: undefined,
             bossReply: undefined,
         }),
-        completeSuccessfully: assign({
-            completion: 'complete',
-            reviewError: undefined,
+        completeSuccessfully: assign(({ event }) => {
+            const output = reviewOutput(event);
+            const approved = isReviewApprovedValue(output) ? output : undefined;
+            return {
+                completion: 'complete',
+                evaluatedRevision: approved?.evaluatedRevision,
+                reviewError: undefined,
+            };
         }),
         completeWithReviewFailure: assign(({ event }) => ({
             completion: 'review-failed',
@@ -426,19 +455,26 @@ export const codingMachine = machineSetup.createMachine({
         if (!isNonEmptyString(lastCodeCommit)) {
             throw new Error('CODE reached a final state without a commit identity');
         }
-        const lastCodeOutput = context.coderOutput ?? '';
         if (context.completion === 'review-failed') {
             return {
                 status: 'review-failed',
                 lastCodeCommit,
-                lastCodeOutput,
                 error: context.reviewError ?? {
                     name: 'Error',
                     message: 'REVIEW failed without error detail.',
                 },
             };
         }
-        return { status: 'complete', lastCodeCommit, lastCodeOutput };
+        const finalEvaluatedRevision = context.evaluatedRevision;
+        if (!isNonEmptyString(finalEvaluatedRevision)) {
+            throw new Error('CODE completed without an evaluated repository revision');
+        }
+        return {
+            status: 'complete',
+            lastCodeCommit,
+            finalEvaluatedRevision,
+            allReviewsPassed: true,
+        };
     },
     states: {
         ready: {
@@ -503,6 +539,36 @@ export const codingMachine = machineSetup.createMachine({
                             'rememberIrCommit',
                         ],
                     },
+                    {
+                        guard: 'isMoreTasks',
+                        target: 'reviewIrTask',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'runFirstPhase',
+                                    target: 'reviewIrTask',
+                                    acceptedOutcome: 'moreTasks',
+                                },
+                            },
+                            'rememberMoreTasks',
+                        ],
+                    },
+                    {
+                        guard: 'isFinalTask',
+                        target: 'reviewIrTask',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'runFirstPhase',
+                                    target: 'reviewIrTask',
+                                    acceptedOutcome: 'finalTask',
+                                },
+                            },
+                            'rememberFinalTask',
+                        ],
+                    },
                     {
                         guard: 'needsBossReply',
                         target: 'awaitBossReply',
@@ -537,7 +603,7 @@ export const codingMachine = machineSetup.createMachine({
                     stateId: 'reviewFirstCommit',
                     sourceItem: 'CODE-2',
                     playbookId: 'review',
-                    text: initialReviewText(context),
+                    text: newIntentReviewText(context),
                 }),
                 onDone: [
                     {
@@ -582,7 +648,6 @@ export const codingMachine = machineSetup.createMachine({
                     ...(context.irNumber === undefined
                         ? {}
                         : { irNumber: context.irNumber }),
-                    ...(context.irTask === undefined ? {} : { irTask: context.irTask }),
                     ...(context.pendingBossQuestion === undefined
                         ? {}
                         : { pendingBossQuestion: context.pendingBossQuestion }),
@@ -661,7 +726,6 @@ export const codingMachine = machineSetup.createMachine({
                     {
                         guard: 'reviewApprovedMoreTasks',
                         target: 'runIrTask',
-                        actions: 'advanceToNextIrTask',
                     },
                     {
                         guard: 'reviewApprovedFinalTask',