@sublang/playbook 5.0.0 → 7.0.0

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

@@ -1,112 +1,247 @@
-type Player = 'Coder' | 'Reviewer' | 'Committer';
-type JumpableStateId = 'ready' | 'planAndImplement' | 'respondToReview' | 'continueIr' | 'summarizeSpecs' | 'reviewBossCommitSpecs' | 'reviewBossCommitCode' | 'reviewBossCommitMixed' | 'reviewIrTaskCommitSpecs' | 'reviewIrTaskCommitCode' | 'reviewIrTaskCommitMixed' | 'reviewChangesSpecs' | 'reviewChangesCode' | 'reviewChangesMixed' | 'reviewChangesAndChallengesSpecs' | 'reviewChangesAndChallengesCode' | 'reviewChangesAndChallengesMixed' | 'adjudicateChallenges' | 'commitCoderInitial' | 'commitJoint' | 'failed';
-type WorkflowKind = 'singleCommit' | 'iteration' | 'specSummary';
-type ChangeOrigin = 'bossIntent' | 'irTask';
-type ReviewSubject = 'commit' | 'changes';
-type AfterReview = 'continueIr' | 'summarizeSpecs' | 'done';
-type ResumableStateId = Exclude<JumpableStateId, 'ready' | 'failed'>;
-type PendingBossQuestion = {
-    questionId: ResumableStateId;
-    resumeStateId: ResumableStateId;
-    sourceItem: string;
-    player: Player;
-    question: string;
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
 };
-export type CaptainInput = {
-    stateId: ResumableStateId;
-    sourceItem: string;
-    prompt: string;
-    result: Record<string, string>;
-    intent?: string;
-    irNumber?: string;
-    taskDescription?: string;
-    reviews?: string;
-    challenges?: string;
-    coderPlayer?: string;
-    reviewerPlayer?: string;
-    committerPlayer?: string;
-    pendingBossQuestion?: PendingBossQuestion;
-    bossReply?: string;
+export type CodeStateId = 'runFirstPhase' | 'reviewFirstCommit' | 'runIrTask' | 'reviewIrTask';
+export type CodeSourceItem = 'CODE-1' | 'CODE-2' | 'CODE-3' | 'CODE-4';
+export type CodePhase = 'direct' | 'ir-created' | 'ir-task-more' | 'ir-task-final';
+export type PendingBossQuestion = {
+    readonly questionId: 'runFirstPhase' | 'runIrTask';
+    readonly resumeStateId: 'runFirstPhase' | 'runIrTask';
+    readonly sourceItem: 'CODE-1' | 'CODE-3';
+    readonly player: 'Coder';
+    readonly question: string;
 };
-export type PlayerInput = CaptainInput & {
-    player: Player;
+export type PlayerInput = {
+    readonly stateId: 'runFirstPhase' | 'runIrTask';
+    readonly player: 'Coder';
+    readonly sourceItem: 'CODE-1' | 'CODE-3';
+    readonly prompt: string;
+    readonly result: Readonly<Record<string, string>>;
+    readonly callerInput: string;
+    readonly runResults: string;
+    readonly coderPlayer: string;
+    readonly irNumber?: string;
+    readonly irTask?: string;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
 };
-export type CaptainOutput = {
-    guard: string;
-    irNumber?: string;
-    taskDescription?: string;
-    reviews?: string;
-    challenges?: string;
-    summary?: string;
-    question?: string;
-    [k: string]: unknown;
+export type PlayerOutput = {
+    readonly guard: 'directCommit';
+    readonly coderOutput: string;
+    readonly latestCommit: string;
+} | {
+    readonly guard: 'irCommit';
+    readonly coderOutput: string;
+    readonly latestCommit: string;
+    readonly irNumber: string;
+    readonly irTask: string;
+} | {
+    readonly guard: 'moreTasks';
+    readonly coderOutput: string;
+    readonly latestCommit: string;
+    readonly irTask: string;
+} | {
+    readonly guard: 'finalTask';
+    readonly coderOutput: string;
+    readonly latestCommit: string;
+} | {
+    readonly guard: 'needsBossReply';
+    readonly question: string;
+};
+export type PlaybookInput = {
+    readonly stateId: 'reviewFirstCommit' | 'reviewIrTask';
+    readonly sourceItem: 'CODE-2' | 'CODE-4';
+    readonly playbookId: 'review';
+    readonly text: string;
+};
+export type ReviewOutput = {
+    readonly approvedCommit: 'latest';
+    readonly noUnsettledFindings: true;
+};
+export type CompactError = {
+    readonly name: string;
+    readonly message: string;
+};
+export type CodePlaybookOutput = {
+    readonly status: 'complete';
+    /** Exact identity of the latest CODE-owned commit. */
+    readonly lastCodeCommit: string;
+    /** Exact Coder final text produced after that commit. */
+    readonly lastCodeOutput: string;
+} | {
+    readonly status: 'review-failed';
+    /** Exact identity of the latest CODE-owned commit. */
+    readonly lastCodeCommit: string;
+    /** Exact Coder final text produced after that commit. */
+    readonly lastCodeOutput: string;
+    readonly error: CompactError;
 };
-export type PlayerOutput = CaptainOutput;
 export type CodingInput = {
-    intent?: string;
-    irNumber?: string;
-    coderPlayer?: string;
-    reviewerPlayer?: string;
-    committerPlayer?: string;
+    readonly coderPlayer?: string;
+    readonly runResults?: string;
 };
-export type CodingContext = CodingInput & {
-    workflow?: WorkflowKind;
-    changeOrigin?: ChangeOrigin;
-    reviewSubject?: ReviewSubject;
-    afterReview?: AfterReview;
-    taskDescription?: string;
-    reviews?: string;
-    challenges?: string;
-    lastResult?: CaptainOutput;
-    lastError?: unknown;
-    pendingBossQuestion?: PendingBossQuestion;
-    bossReply?: string;
+export type CodingContext = {
+    readonly coderPlayer: string;
+    readonly runResults: string;
+    readonly callerInput?: string;
+    readonly coderOutput?: string;
+    readonly latestCommit?: string;
+    readonly irNumber?: string;
+    readonly irTask?: string;
+    readonly nextIrTask?: string;
+    readonly phase?: CodePhase;
+    readonly completion?: 'complete' | 'review-failed';
+    readonly reviewError?: CompactError;
+    readonly lastError?: unknown;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
 };
 export type CodingEvent = {
-    type: 'START_CODING';
-    intent: string;
+    readonly type: 'START_CODE';
+    readonly callerInput: string;
+} | {
+    readonly type: 'BOSS_REPLY';
+    readonly answer: string;
+    readonly questionId?: 'runFirstPhase' | 'runIrTask';
+};
+export declare const codingMachine: import("xstate").StateMachine<CodingContext, {
+    readonly type: "START_CODE";
+    readonly callerInput: string;
 } | {
-    type: 'CONTINUE_IR';
-    irNumber: string;
+    readonly type: "BOSS_REPLY";
+    readonly answer: string;
+    readonly questionId?: "runFirstPhase" | "runIrTask";
+}, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+}, {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
 } | {
-    type: 'SUMMARIZE_IR';
-    irNumber: string;
+    src: "player";
+    logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "rememberActorError";
+    params: import("xstate").NonReducibleUnknown;
 } | {
-    type: 'BOSS_INTERRUPT';
-    targetId: JumpableStateId;
-    intent?: string;
-    irNumber?: string;
+    type: "startCoding";
+    params: import("xstate").NonReducibleUnknown;
 } | {
-    type: 'BOSS_REPLY';
-    answer: string;
-    questionId?: ResumableStateId;
-};
-export declare const codingMachine: import("xstate").StateMachine<CodingContext, {
-    type: "START_CODING";
-    intent: string;
+    type: "rememberDirectCommit";
+    params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "CONTINUE_IR";
-    irNumber: string;
+    type: "rememberIrCommit";
+    params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "SUMMARIZE_IR";
-    irNumber: string;
+    type: "rememberMoreTasks";
+    params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "BOSS_INTERRUPT";
-    targetId: JumpableStateId;
-    intent?: string;
-    irNumber?: string;
+    type: "rememberFinalTask";
+    params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "BOSS_REPLY";
-    answer: string;
-    questionId?: ResumableStateId;
-}, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<CaptainOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+    type: "advanceToNextIrTask";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberPendingQuestion";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberEmptyBossReplyError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeSuccessfully";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithReviewFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithInvalidReviewOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedPlayerOutput";
+    params: import("xstate").NonReducibleUnknown;
 }, {
-    src: "player";
-    logic: import("xstate").PromiseActorLogic<CaptainOutput, PlayerInput, import("xstate").EventObject>;
-    id: string | undefined;
-}, never, never, never, {}, string, CodingInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
-    states?: {} | undefined;
-    id?: string | undefined | undefined;
+    type: "needsBossReply";
+    params: unknown;
+} | {
+    type: "isDirectCommit";
+    params: unknown;
+} | {
+    type: "isIrCommit";
+    params: unknown;
+} | {
+    type: "isMoreTasks";
+    params: unknown;
+} | {
+    type: "isFinalTask";
+    params: unknown;
+} | {
+    type: "authoredReviewFailure";
+    params: unknown;
+} | {
+    type: "reviewApprovedDirect";
+    params: unknown;
+} | {
+    type: "reviewApprovedIrCreated";
+    params: unknown;
+} | {
+    type: "reviewApprovedMoreTasks";
+    params: unknown;
+} | {
+    type: "reviewApprovedFinalTask";
+    params: unknown;
+} | {
+    type: "emptyBossReply";
+    params: unknown;
+} | {
+    type: "resumesFirstPhase";
+    params: unknown;
+} | {
+    type: "resumesIrTask";
+    params: unknown;
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask", string, CodingInput, {
+    readonly status: "complete";
+    /** Exact identity of the latest CODE-owned commit. */
+    readonly lastCodeCommit: string;
+    /** Exact Coder final text produced after that commit. */
+    readonly lastCodeOutput: string;
+} | {
+    readonly status: "review-failed";
+    /** Exact identity of the latest 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";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly runFirstPhase: {
+            id: "runFirstPhase";
+        };
+        readonly reviewFirstCommit: {
+            id: "reviewFirstCommit";
+        };
+        readonly runIrTask: {
+            id: "runIrTask";
+        };
+        readonly reviewIrTask: {
+            id: "reviewIrTask";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly done: {
+            id: "done";
+        };
+    };
 }>;
-export {};
+export default codingMachine;

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

@@ -1,54 +1,36 @@
-import type { CodingContext, PlayerInput, codingMachine } from './code.fsm.js';
-export interface CaptainStateInfo {
-    readonly stateId: string;
-    readonly sourceItem: string;
-    readonly getInput: (context: Partial<CodingContext>) => PlayerInput;
-    readonly transitions: ReadonlyArray<CaptainTransition>;
-}
-export interface CaptainTransition {
+import type { CodingContext, PlaybookInput, PlayerInput, codingMachine } from './code.fsm.js';
+export type TransitionGuard = (args: {
+    context: CodingContext;
+    event: unknown;
+}) => boolean;
+export interface InvokingTransition {
     readonly index: number;
     readonly target: string;
-    readonly guard: TransitionGuard;
+    readonly guard?: TransitionGuard;
     readonly actions: unknown;
 }
-export interface AwaitBossReplyInfo {
+export interface PlayerStateInfo {
     readonly stateId: string;
-    readonly bossReplyTransitions: ReadonlyArray<BossReplyTransition>;
-    readonly transitions: ReadonlyArray<AwaitBossReplyTransition>;
+    readonly sourceItem: string;
+    readonly getInput: (context: CodingContext) => PlayerInput;
+    readonly transitions: readonly InvokingTransition[];
 }
-export interface BossReplyTransition {
-    readonly index: number;
-    readonly target: string;
-    readonly guard: TransitionGuard;
-    readonly actions: unknown;
+export interface NestedPlaybookStateInfo {
+    readonly stateId: string;
+    readonly sourceItem: string;
+    readonly getInput: (context: CodingContext) => PlaybookInput;
+    readonly transitions: readonly InvokingTransition[];
 }
-export interface AwaitBossReplyTransition {
-    readonly eventType: string;
-    readonly index: number;
-    readonly target: string;
-    readonly guard: TransitionGuard;
-    readonly actions: unknown;
+export interface AwaitBossReplyInfo {
+    readonly stateId: 'awaitBossReply';
+    readonly bossReplyTransitions: readonly InvokingTransition[];
 }
-export type TransitionGuard = (args: {
-    context: CodingContext;
-    event: unknown;
-}) => boolean;
-export interface RootEventTable {
-    readonly startCoding: {
-        readonly target: string;
-    };
-    readonly continueIr: {
-        readonly target: string;
-    };
-    readonly summarizeIr: {
+export declare function enumeratePlayerStates(machine: typeof codingMachine): readonly PlayerStateInfo[];
+export declare const enumerateCaptainStates: typeof enumeratePlayerStates;
+export declare function enumerateNestedPlaybookStates(machine: typeof codingMachine): readonly NestedPlaybookStateInfo[];
+export declare function enumerateAwaitBossReply(machine: typeof codingMachine): AwaitBossReplyInfo;
+export declare function enumerateRootEvents(machine: typeof codingMachine): {
+    readonly startCode: {
         readonly target: string;
     };
-    readonly bossInterruptTargets: ReadonlyArray<string>;
-    readonly bossInterruptTargetDescriptions: ReadonlyArray<{
-        readonly stateId: string;
-        readonly description: string;
-    }>;
-}
-export declare function enumerateCaptainStates(machine: typeof codingMachine): readonly CaptainStateInfo[];
-export declare function enumerateRootEvents(machine: typeof codingMachine): RootEventTable;
-export declare function enumerateAwaitBossReply(machine: typeof codingMachine): AwaitBossReplyInfo;
+};

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

@@ -1,77 +1,72 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-export function enumerateCaptainStates(machine) {
-    const states = getRawConfig(machine).states ?? {};
-    const out = [];
-    for (const [stateId, def] of Object.entries(states)) {
-        const invoke = def.invoke;
-        if (!invoke || invoke.src !== 'player' || typeof invoke.input !== 'function') {
-            continue;
-        }
-        const inputFn = invoke.input;
-        const getInput = (context) => inputFn({ context });
-        const probe = getInput({});
-        const transitions = toArmArray(invoke.onDone).map((arm, index) => ({
-            index,
-            target: stripIdPrefix(String(arm.target ?? '')),
-            guard: arm.guard ?? alwaysTrue,
-            actions: arm.actions,
-        }));
-        out.push({
-            stateId,
-            sourceItem: probe.sourceItem,
-            getInput,
-            transitions,
-        });
-    }
-    return out;
+function rawConfig(machine) {
+    return machine.config;
 }
-export function enumerateRootEvents(machine) {
-    const cfg = getRawConfig(machine);
-    const readyOn = (cfg.states?.ready?.on ?? {});
-    const rootOn = (cfg.on ?? {});
-    const bossInterruptTargets = toArmArray(rootOn.BOSS_INTERRUPT).map((arm) => stripIdPrefix(String(arm.target ?? '')));
-    return {
-        startCoding: { target: stripIdPrefix(String(readyOn.START_CODING?.target ?? '')) },
-        continueIr: { target: stripIdPrefix(String(readyOn.CONTINUE_IR?.target ?? '')) },
-        summarizeIr: { target: stripIdPrefix(String(readyOn.SUMMARIZE_IR?.target ?? '')) },
-        bossInterruptTargets,
-        bossInterruptTargetDescriptions: bossInterruptTargets.map((stateId) => {
-            const description = cfg.states?.[stateId]?.description;
-            return {
-                stateId,
-                description: typeof description === 'string' ? description : '',
-            };
-        }),
-    };
+function arms(value) {
+    if (value === undefined || value === null)
+        return [];
+    return (Array.isArray(value) ? value : [value]);
 }
-export function enumerateAwaitBossReply(machine) {
-    const stateId = 'awaitBossReply';
-    const awaitOn = getRawConfig(machine).states?.[stateId]?.on ?? {};
-    const transitions = Object.entries(awaitOn).flatMap(([eventType, value]) => toArmArray(value).map((arm, index) => ({
-        eventType,
-        index,
-        target: stripIdPrefix(String(arm.target ?? '')),
-        guard: arm.guard ?? alwaysTrue,
-        actions: arm.actions,
-    })));
-    const bossReplyTransitions = toArmArray(awaitOn.BOSS_REPLY).map((arm, index) => ({
+function targetName(target) {
+    const value = String(target ?? '');
+    return value.startsWith('#') ? value.slice(1) : value;
+}
+function transitions(value) {
+    return arms(value).map((arm, index) => ({
         index,
-        target: stripIdPrefix(String(arm.target ?? '')),
-        guard: arm.guard ?? alwaysTrue,
+        target: targetName(arm.target),
+        ...(arm.guard === undefined ? {} : { guard: arm.guard }),
         actions: arm.actions,
     }));
-    return { stateId, bossReplyTransitions, transitions };
 }
-function getRawConfig(machine) {
-    return machine.config;
+export function enumeratePlayerStates(machine) {
+    const states = rawConfig(machine).states ?? {};
+    return Object.entries(states).flatMap(([stateId, state]) => {
+        const invoke = state.invoke;
+        if (invoke?.src !== 'player' || invoke.input === undefined)
+            return [];
+        const getInput = (context) => invoke.input?.({ context });
+        const input = getInput({ coderPlayer: 'Coder', runResults: '' });
+        return [
+            {
+                stateId,
+                sourceItem: input.sourceItem,
+                getInput,
+                transitions: transitions(invoke.onDone),
+            },
+        ];
+    });
 }
-function toArmArray(value) {
-    if (value === undefined || value === null)
-        return [];
-    return (Array.isArray(value) ? value : [value]);
+// Backward-compatible internal name retained for repository conformance tools.
+export const enumerateCaptainStates = enumeratePlayerStates;
+export function enumerateNestedPlaybookStates(machine) {
+    const states = rawConfig(machine).states ?? {};
+    return Object.entries(states).flatMap(([stateId, state]) => {
+        const invoke = state.invoke;
+        if (invoke?.src !== 'playbook' || invoke.input === undefined)
+            return [];
+        const getInput = (context) => invoke.input?.({ context });
+        const input = getInput({ coderPlayer: 'Coder', runResults: '' });
+        return [
+            {
+                stateId,
+                sourceItem: input.sourceItem,
+                getInput,
+                transitions: transitions(invoke.onDone),
+            },
+        ];
+    });
 }
-function stripIdPrefix(target) {
-    return target.startsWith('#') ? target.slice(1) : target;
+export function enumerateAwaitBossReply(machine) {
+    const on = rawConfig(machine).states?.awaitBossReply?.on ?? {};
+    return {
+        stateId: 'awaitBossReply',
+        bossReplyTransitions: transitions(on.BOSS_REPLY),
+    };
+}
+export function enumerateRootEvents(machine) {
+    const on = rawConfig(machine).states?.ready?.on ?? {};
+    const start = arms(on.START_CODE)[0];
+    return { startCode: { target: targetName(start?.target) } };
 }
-const alwaysTrue = () => true;