@sublang/playbook 15.0.0 → 16.0.0

package/reference/sdlc/decide.md

@@ -56,6 +56,7 @@ After Coder commits, Captain shall call playbook `review` with the following inp
 
 > Original intent: \<caller-topic\>
 > Review scope: the `decide`-owned commit \<decide-commit\> and its resulting repository state.
+> Coder's independent proposal: \<coder-proposal\>
 > Coder output: \<coder-output\>
 
 `decide` is complete only when `review` returns a result that applies to the supplied review scope, gives the exact evaluated repository revision, and affirmatively establishes that no unsettled findings remain.

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

@@ -1,133 +1,212 @@
+import type { PlaybookCallResult } from '@sublang/playbook/runtime';
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
-type Role = 'coder' | 'reviewer';
-export declare const concurrentRoleSets: readonly [readonly ["coder", "reviewer"]];
-type JumpableStateId = 'independentProposals';
-type ResumableStateId = 'askCoderProposal' | 'askReviewerProposal' | 'commitCoderProposal';
+export interface CompactError {
+    readonly name: string;
+    readonly message: string;
+}
+export interface ErrorRecord {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+/** Canonical lowercase local ids of the source roles Coder and Reviewer. */
+export type DecideRoleId = 'coder' | 'reviewer';
+export type DecideSourceItem = 'DECIDE-1' | 'DECIDE-2' | 'DECIDE-3' | 'DECIDE-4';
+/** Delegated-player working leaves; each is its own Boss-reply resume target. */
+export type ResumableStateId = 'askCoderProposal' | 'askReviewerProposal' | 'synthesizeCommit';
+/**
+ * Root `BOSS_INTERRUPT` targets: the parallel proposal pair as one jumpable
+ * unit (DECIDE-1, DECIDE-2), and the synthesis leaf (DECIDE-3). Branch working
+ * leaves and waits are never interrupt targets.
+ */
+export type JumpableStateId = 'independentProposals' | 'synthesizeCommit';
+/**
+ * One role-id array per parallel group, in first-item source order; the inner
+ * array follows the `independent-proposals` item order (DECIDE-1, DECIDE-2).
+ */
+export declare const concurrentRoleSets: readonly (readonly DecideRoleId[])[];
+/** The literal nested-call target of DECIDE-4. */
+declare const REVIEW_PLAYBOOK_ID: "review";
 export interface PendingBossQuestion {
-    questionId: ResumableStateId;
-    resumeStateId: ResumableStateId;
-    sourceItem: string;
-    asker: {
-        kind: 'role';
-        roleId: Role;
+    readonly questionId: ResumableStateId;
+    readonly resumeStateId: ResumableStateId;
+    readonly sourceItem: 'DECIDE-1' | 'DECIDE-2' | 'DECIDE-3';
+    readonly asker: {
+        readonly kind: 'role';
+        readonly roleId: DecideRoleId;
     };
-    question: string;
+    readonly question: string;
 }
-type PendingBossQuestions = Partial<Record<ResumableStateId, PendingBossQuestion>>;
-type BossReplies = Partial<Record<ResumableStateId, string>>;
-type PendingBossQuestionParams = Omit<PendingBossQuestion, 'questionId'>;
-export interface ReviewSuccessOutput {
-    evaluatedRevision: string;
-    noUnsettledFindings: true;
+export type PendingBossQuestions = Partial<Record<ResumableStateId, PendingBossQuestion>>;
+export type BossReplies = Partial<Record<ResumableStateId, string>>;
+declare const CODER_PROPOSAL_RESULT: {
+    readonly proposed: "Coder affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `coderProposal: <verbatim final text>`.";
+    readonly 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>`.";
+};
+declare const REVIEWER_PROPOSAL_RESULT: {
+    readonly proposed: "Reviewer affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `reviewerProposal: <verbatim final text>`.";
+    readonly 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>`.";
+};
+declare const SYNTHESIZE_COMMIT_RESULT: {
+    readonly committed: "Coder synthesized the proposals into the necessary DRs and/or spec items and committed the result as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.";
+    readonly 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>`.";
+};
+interface PlayerInputBase {
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
 }
-export interface DecideSuccessOutput {
-    decideCommit: string;
-    evaluatedRevision: string;
-    noUnsettledFindings: true;
+/** DECIDE-1: relays `<caller-topic>` as `callerTopic`. */
+export interface CoderProposalInput extends PlayerInputBase {
+    readonly stateId: 'askCoderProposal';
+    readonly role: 'coder';
+    readonly sourceItem: 'DECIDE-1';
+    readonly prompt: string;
+    readonly result: typeof CODER_PROPOSAL_RESULT;
+    /** `<caller-topic>`: the caller's complete topic. */
+    readonly callerTopic: string;
 }
-export interface DecideFailureOutput {
-    lastDecideCommit: string;
-    noUnsettledFindings: false;
-    reviewStatus: 'aborted' | 'error';
-    error?: {
-        name: string;
-        message: string;
-    };
+/** DECIDE-2: relays `<caller-topic>` as `callerTopic`. */
+export interface ReviewerProposalInput extends PlayerInputBase {
+    readonly stateId: 'askReviewerProposal';
+    readonly role: 'reviewer';
+    readonly sourceItem: 'DECIDE-2';
+    readonly prompt: string;
+    readonly result: typeof REVIEWER_PROPOSAL_RESULT;
+    /** `<caller-topic>`: the caller's complete topic. */
+    readonly callerTopic: string;
 }
-export type DecideOutput = DecideSuccessOutput | DecideFailureOutput;
-interface ChildFailure {
-    status: 'aborted' | 'error';
-    playbookId: 'review';
-    error?: {
-        name: string;
-        message: string;
-    };
+/**
+ * DECIDE-3: relays `<caller-topic>` as `callerTopic` and
+ * `<reviewer-proposal>` as `reviewerProposal`.
+ */
+export interface SynthesizeCommitInput extends PlayerInputBase {
+    readonly stateId: 'synthesizeCommit';
+    readonly role: 'coder';
+    readonly sourceItem: 'DECIDE-3';
+    readonly prompt: string;
+    readonly result: typeof SYNTHESIZE_COMMIT_RESULT;
+    /** `<caller-topic>`: the caller's complete topic. */
+    readonly callerTopic: string;
+    /** `<reviewer-proposal>`: Reviewer's complete independent proposal. */
+    readonly reviewerProposal: string;
 }
-export interface DecideContext {
-    callerTopic?: string;
-    coderProposal?: string;
-    reviewerProposal?: string;
-    latestCommit?: string;
-    coderOutput?: string;
-    reviewResult?: ReviewSuccessOutput;
-    reviewFailure?: ChildFailure;
-    lastResult?: PlayerOutput;
-    lastError?: unknown;
-    pendingBossQuestions?: PendingBossQuestions;
-    bossReplies?: BossReplies;
-    stagedCoderResult?: PlayerOutput;
-    stagedReviewerResult?: PlayerOutput;
+export type PlayerInput = CoderProposalInput | ReviewerProposalInput | SynthesizeCommitInput;
+export interface NeedsBossReplyOutput {
+    readonly guard: 'needsBossReply';
+    readonly question: string;
 }
-export type DecideEvent = {
-    type: 'START_DECIDE';
-    callerTopic: string;
-} | {
-    type: 'BOSS_INTERRUPT';
-    targetId: JumpableStateId;
-    bossIntent: string;
+export type CoderProposalOutput = {
+    readonly guard: 'proposed';
+    readonly coderProposal: string;
+} | NeedsBossReplyOutput;
+export type ReviewerProposalOutput = {
+    readonly guard: 'proposed';
+    readonly reviewerProposal: string;
+} | NeedsBossReplyOutput;
+export type SynthesizeCommitOutput = {
+    readonly guard: 'committed';
+    readonly coderOutput: string;
+    /** Effect-owned: the runtime fills it from the repository receipt. */
+    readonly latestCommit: string;
+} | NeedsBossReplyOutput;
+export type PlayerOutput = CoderProposalOutput | ReviewerProposalOutput | SynthesizeCommitOutput;
+/** DECIDE-4: literal call of the builtin `review` playbook. */
+export interface PlaybookInput {
+    readonly stateId: 'reviewCommit';
+    readonly sourceItem?: 'DECIDE-4';
+    readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+    readonly text: string;
+}
+/** A successful call yields the child's own JSON-safe machine output. */
+export type PlaybookOutput = JsonValue | undefined;
+/** Public output interface of the packaged builtin `review`. */
+export interface ReviewOutput {
+    readonly noUnsettledFindings: true;
+    readonly evaluatedRevision: string;
+}
+/** Sanitized completed-result evidence of the `review` call that ended DECIDE. */
+export type CompletedReviewResult = {
+    readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+    readonly status: 'ok';
+    readonly output?: JsonValue;
 } | {
-    type: 'BOSS_REPLY';
-    questionId?: ResumableStateId;
-    answer: string;
+    readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+    readonly status: 'aborted' | 'error';
+    readonly error: CompactError;
 };
+/** The machine reads no input: the caller's topic arrives on `START_DECIDE`. */
 export type DecideInput = Readonly<Record<string, never>>;
-export interface PlayerInput {
-    stateId: ResumableStateId;
-    sourceItem: string;
-    prompt: string;
-    result: Record<string, string>;
-    role: Role;
-    callerTopic?: string;
-    reviewerProposal?: string;
-    pendingBossQuestion?: PendingBossQuestion;
-    bossReply?: string;
-}
-type AdditionalPlayerFields = {
-    coderProposal?: string;
-    reviewerProposal?: string;
-    coderOutput?: string;
-    latestCommit?: string;
-    question?: string;
-    readonly [key: string]: unknown;
-};
-export type PlayerOutput = ({
-    guard: 'proposed';
-    coderProposal: string;
-} & AdditionalPlayerFields) | ({
-    guard: 'proposed';
-    reviewerProposal: string;
-} & AdditionalPlayerFields) | ({
-    guard: 'committed';
-    coderOutput: string;
-    latestCommit: string;
-} & AdditionalPlayerFields) | ({
-    guard: 'needsBossReply';
-    question: string;
-} & AdditionalPlayerFields);
-export interface PlaybookInput {
-    stateId: 'reviewCommit';
-    sourceItem: 'DECIDE-4';
-    playbookId: 'review';
-    text: string;
+export type ReviewStatus = 'aborted' | 'error';
+/**
+ * Typed run context. A text field holds `''` until its producer runs; every
+ * transition that enters a consumer guards the fields it reads as non-empty.
+ */
+export interface DecideContext {
+    /** `<caller-topic>`: set by `START_DECIDE` or a restarting interrupt. */
+    readonly callerTopic: string;
+    /** Branch-staged proposals; the parallel join promotes them atomically. */
+    readonly stagedCoderProposal: string;
+    readonly stagedReviewerProposal: string;
+    /** `<coder-proposal>`: Coder's promoted independent proposal. */
+    readonly coderProposal: string;
+    /** `<reviewer-proposal>`: Reviewer's promoted independent proposal. */
+    readonly reviewerProposal: string;
+    /** `<coder-output>`: Coder's verbatim final synthesis text. */
+    readonly coderOutput: string;
+    /** `<decide-commit>`: DECIDE-3's accepted, receipt-owned `latestCommit`. */
+    readonly decideCommit: string;
+    /** Revision evaluated by the passing `review`. */
+    readonly evaluatedRevision: string;
+    /** Reported status when `review` did not pass the commit. */
+    readonly reviewStatus: ReviewStatus | null;
+    /** Compact failure DECIDE reports when `review` did not pass the commit. */
+    readonly reviewError: CompactError | null;
+    /** Sanitized evidence of the `review` result that ended DECIDE. */
+    readonly reviewEvidence: CompletedReviewResult | null;
+    readonly lastError: ErrorRecord | null;
+    readonly pendingBossQuestions: PendingBossQuestions;
+    readonly bossReplies: BossReplies;
 }
-export declare const decideMachine: import("xstate").StateMachine<DecideContext, {
-    type: "START_DECIDE";
-    callerTopic: string;
+export type DecideEvent = {
+    readonly type: 'START_DECIDE';
+    readonly callerTopic: string;
 } | {
-    type: "BOSS_INTERRUPT";
-    targetId: JumpableStateId;
-    bossIntent: string;
+    readonly type: 'BOSS_INTERRUPT';
+    readonly targetId: 'independentProposals';
+    /** The new topic both proposal players receive. */
+    readonly callerTopic: string;
 } | {
-    type: "BOSS_REPLY";
-    questionId?: ResumableStateId;
-    answer: string;
-}, {
-    [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;
+    readonly type: 'BOSS_INTERRUPT';
+    readonly targetId: 'synthesizeCommit';
+} | {
+    readonly type: 'BOSS_REPLY';
+    readonly questionId: string;
+    readonly answer: string;
+};
+/** Exactly the catalog's public `decide` output interface. */
+export type DecideOutput = {
+    readonly decideCommit: string;
+    readonly evaluatedRevision: string;
+    readonly noUnsettledFindings: true;
+} | {
+    readonly lastDecideCommit: string;
+    readonly noUnsettledFindings: false;
+    readonly reviewStatus: ReviewStatus;
+    readonly error?: CompactError;
+};
+/**
+ * Recognizes an authored rejected child result: a validated public result
+ * whose status is `aborted` or `error`, or `ok` at the child's own authored
+ * failure terminal. Anything else is a control-plane error.
+ */
+export declare function authoredChildResult(error: unknown, expectedPlaybookId: string): PlaybookCallResult | undefined;
+export declare const decideMachine: import("xstate").StateMachine<DecideContext, import("xstate").AnyEventObject, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, 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>;
+    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
     id: string | undefined;
 } | {
     src: "player";
@@ -145,12 +224,33 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "rememberBossReply";
+    params: {
+        readonly stateId: ResumableStateId;
+    };
+} | {
+    type: "rememberMalformedPlayerOutput";
+    params: {
+        readonly sourceItem: DecideSourceItem;
+    };
+} | {
+    type: "rememberAuthoredReviewFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingBossQuestion";
+    params: {
+        readonly stateId: ResumableStateId;
+    };
+} | {
+    type: "restartFromInterrupt";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberEmptyBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "copyInterruptedTopic";
+    type: "rememberUnknownBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "copyStartTopic";
+    type: "startDecide";
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "stageCoderProposal";
@@ -165,61 +265,71 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
     type: "rememberCommit";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberReviewSuccess";
-    params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "rememberReviewFailure";
+    type: "rememberReviewApproval";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberReviewProtocolFailure";
+    type: "rememberUnestablishedReview";
     params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "needsBossReply";
+    params: unknown;
 } | {
-    type: "rememberMalformedActorOutput";
-    params: import("xstate").NonReducibleUnknown;
+    type: "authoredReviewFailure";
+    params: unknown;
 } | {
-    type: "rememberMalformedBossReply";
-    params: import("xstate").NonReducibleUnknown;
+    type: "committed";
+    params: unknown;
 } | {
-    type: "setPendingBossQuestion";
-    params: PendingBossQuestionParams;
+    type: "interruptTargets";
+    params: {
+        readonly targetId: JumpableStateId;
+    };
 } | {
-    type: "clearBranchBossReplyContext";
+    type: "bossReplyIsEmpty";
     params: {
-        stateId: ResumableStateId;
+        readonly stateId: ResumableStateId;
     };
 } | {
-    type: "clearProposalRoundContext";
-    params: import("xstate").NonReducibleUnknown;
+    type: "bossReplyResumes";
+    params: {
+        readonly stateId: ResumableStateId;
+    };
 } | {
-    type: "clearBossReplyContext";
-    params: import("xstate").NonReducibleUnknown;
-}, {
-    type: "authoredReviewFailure";
+    type: "bossReplyNamesNoPendingQuestion";
     params: unknown;
 } | {
-    type: "committed";
+    type: "validStartTopic";
     params: unknown;
 } | {
-    type: "coderProposed";
+    type: "coderProposedJoining";
     params: unknown;
 } | {
-    type: "reviewerProposed";
+    type: "coderProposed";
     params: unknown;
 } | {
-    type: "needsBossReplyWithQuestion";
+    type: "reviewerProposedJoining";
     params: unknown;
 } | {
-    type: "needsBossReplyWithoutQuestion";
+    type: "reviewerProposed";
     params: unknown;
 } | {
-    type: "validReviewSuccess";
+    type: "reviewApproved";
     params: unknown;
-}, never, "done" | "failed" | "ready" | "awaitBossReply" | "reportedReviewFailure" | "commitCoderProposal" | "reviewCommit" | {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "synthesizeCommit" | "reviewCommit" | "reportedReviewFailure" | {
     independentProposals: {
-        coder: "complete" | "working" | "waiting";
-        reviewer: "complete" | "working" | "waiting";
+        coderProposalRegion: "askCoderProposal" | "awaitCoderProposalReply" | "coderProposalStaged";
+        reviewerProposalRegion: "askReviewerProposal" | "awaitReviewerProposalReply" | "reviewerProposalStaged";
     };
-}, string, Readonly<Record<string, never>>, DecideSuccessOutput | DecideFailureOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+}, string, Readonly<Record<string, never>>, {
+    readonly decideCommit: string;
+    readonly evaluatedRevision: string;
+    readonly noUnsettledFindings: true;
+} | {
+    readonly lastDecideCommit: string;
+    readonly noUnsettledFindings: false;
+    readonly reviewStatus: ReviewStatus;
+    readonly error?: CompactError;
+}, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "decide";
     states: {
         readonly ready: {
@@ -228,32 +338,38 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
         readonly independentProposals: {
             id: "independentProposals";
             states: {
-                readonly coder: {
+                readonly coderProposalRegion: {
+                    id: "coderProposalRegion";
                     states: {
-                        readonly working: {
+                        readonly askCoderProposal: {
                             id: "askCoderProposal";
                         };
-                        readonly waiting: {
-                            id: "waitCoderProposalReply";
+                        readonly awaitCoderProposalReply: {
+                            id: "awaitCoderProposalReply";
+                        };
+                        readonly coderProposalStaged: {
+                            id: "coderProposalStaged";
                         };
-                        readonly complete: {};
                     };
                 };
-                readonly reviewer: {
+                readonly reviewerProposalRegion: {
+                    id: "reviewerProposalRegion";
                     states: {
-                        readonly working: {
+                        readonly askReviewerProposal: {
                             id: "askReviewerProposal";
                         };
-                        readonly waiting: {
-                            id: "waitReviewerProposalReply";
+                        readonly awaitReviewerProposalReply: {
+                            id: "awaitReviewerProposalReply";
+                        };
+                        readonly reviewerProposalStaged: {
+                            id: "reviewerProposalStaged";
                         };
-                        readonly complete: {};
                     };
                 };
             };
         };
-        readonly commitCoderProposal: {
-            id: "commitCoderProposal";
+        readonly synthesizeCommit: {
+            id: "synthesizeCommit";
         };
         readonly awaitBossReply: {
             id: "awaitBossReply";