@sublang/playbook 15.1.0 → 16.0.0

package/reference/sdlc/decide.playbook/decide.gears.md

@@ -3,32 +3,32 @@
 
 # Decide
 
-## Roles
+Roles:
 
 - Coder
 - Reviewer
 
-## Independent proposals
+The caller supplies the topic including any specific context.
+No transition shall depend on a fixed presentation format of either player's reply.
 
-The caller supplies a topic as `callerTopic`.
-Coder and Reviewer receive the complete topic concurrently and independently.
-Neither role's player receives the other role's proposal before both proposals are complete.
-A proposal is complete only when its player affirmatively provides a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome.
-A Boss interrupt during the parallel proposal pair restarts the complete pair with the new `callerTopic`.
+## Independent proposals
 
 ### DECIDE-1
 
 Parallel group: independent-proposals
 
-When the caller gives a topic, Captain shall relay the complete topic to Coder in quotes and prompt Coder:
+Captain shall not wait for Reviewer's proposal before requesting Coder's, and Coder's player shall not receive Reviewer's proposal until both proposals are complete.
+A Boss interrupt during the parallel proposal pair restarts the whole pair so both players receive the same new topic and remain independent.
+
+When the caller gives a topic, or when a Boss interrupt restarts the parallel proposal pair with a new topic, Captain shall relay the complete topic to Coder in quotes and prompt Coder:
 
-> > Original topic: <caller-topic>
->
 > Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 > Propose your design.
 > Keep your proposal coherent, focused, and concise.
 > Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 > Do not change any files.
+>
+> > Original topic: <caller-topic>
 
 Results:
 - `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>`.
@@ -37,15 +37,18 @@ Results:
 
 Parallel group: independent-proposals
 
-When the caller gives a topic, Captain shall relay the complete topic to Reviewer in quotes and prompt Reviewer:
+Captain shall not wait for Coder's proposal before requesting Reviewer's, and Reviewer's player shall not receive Coder's proposal until both proposals are complete.
+A Boss interrupt during the parallel proposal pair restarts the whole pair so both players receive the same new topic and remain independent.
+
+When the caller gives a topic, or when a Boss interrupt restarts the parallel proposal pair with a new topic, Captain shall relay the complete topic to Reviewer in quotes and prompt Reviewer:
 
-> > Original topic: <caller-topic>
->
 > Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 > Propose your design.
 > Keep your proposal coherent, focused, and concise.
 > Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 > Do not change any files.
+>
+> > Original topic: <caller-topic>
 
 Results:
 - `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>`.
@@ -54,7 +57,10 @@ Results:
 
 ### DECIDE-3
 
-When both independent proposals are complete, Captain shall relay the complete topic and Reviewer's complete proposal to Coder under their own labels in quotes and prompt Coder:
+No transition shall depend on a fixed presentation format of Coder's reply.
+Captain shall use the repository-effect receipt as the authoritative identity of Coder's new `decide`-owned commit.
+
+When both proposals are complete, Captain shall relay the complete topic and Reviewer's complete proposal to Coder under their own labels in quotes and prompt Coder:
 
 > Synthesize your independent proposal with Reviewer's proposal below.
 > Keep to the original topic below and follow what it asks.
@@ -72,20 +78,21 @@ When both independent proposals are complete, Captain shall relay the complete t
 > > Reviewer's independent proposal: <reviewer-proposal>
 
 Results:
-- `committed`: Coder synthesized both proposals and committed the resulting design as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
-
-No transition depends on a fixed presentation format of either player's reply; the repository-effect receipt is the authoritative identity of Coder's new `decide`-owned commit.
+- `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>`.
 
 ## Review
 
 ### DECIDE-4
 
-When Coder commits, Captain shall call playbook `review` with the following input in quotes:
+When Coder has committed, Captain shall call playbook `review`:
 
 > > 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; `decide` then returns the `decide`-owned commit and that evaluated revision to the caller.
-An authored `review` abort or failure, or a terminal result that does not establish those facts, terminates with the failure and the last `decide`-owned commit reported to the caller.
-Any other nested-call error parks `decide` as failed and retains the control-plane error.
+The input is relayed to `review` in quotes (`>`); `<decide-commit>` is the `decide`-owned commit identified by the repository-effect receipt.
+`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.
+It then returns the `decide`-owned commit and that evaluated revision to its caller.
+When `review` returns an authored abort or failure, or a terminal result that does not establish those facts, `decide` shall report the failure and the last `decide`-owned commit to its caller.
+When the nested `review` call fails outside that authored result contract, `decide` shall park as failed and retain the control-plane error instead of reporting an authored review outcome.

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

@@ -1,64 +1,16 @@
-import { normalizeErrorCompact, normalizeErrorFull } from '../../../src/xstate-runtime.js';
-import { type PlayerInput, type DecideEvent, type DecideInput, type PendingBossQuestion } from './decide.fsm.js';
-import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
-import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlayerResult, PlayerSessionStore, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlAction, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType } from '@sublang/playbook/runtime';
-export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlayerResult, PlayerSessionStore, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlAction, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, };
-type RoleId = 'coder' | 'reviewer';
-export type PlaybookRuntimeOptions = DecideInput;
-export type DecidePlaybookHostCapabilities = PlaybookHostConstructionCapabilities;
-export interface DecidePlaybookRuntimeConstruction {
-    readonly configuredOptions: PlaybookRuntimeOptions;
-    readonly hostCapabilities: DecidePlaybookHostCapabilities;
+import { type XStatePromptIdentity, type PlaybookPlayerInput, type XStatePlaybookRuntimeConstruction, type XStatePlaybookRuntimeFactory } from '@sublang/playbook/xstate-runtime';
+export type { PlayerResult, PlayerCallOptions, PlayerSessionStore, CaptainResult, CaptainCallOptions, JsonValue, NormalizedError, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookStateValue, PlaybookState, PlaybookPendingCall, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookPorts, PlaybookTraceEvent, PlaybookTraceType, PlaybookControlReceipt, PlaybookControlView, } from '@sublang/playbook/runtime';
+export interface PlaybookRuntimeOptions {
 }
-type PromptIdentity = (roleId: RoleId) => string;
-declare function composePlayerPrompt(input: PlayerInput, promptIdentity: PromptIdentity, resuming?: boolean): string;
-declare function requiredFieldsFor(description: string): string[];
-declare function extractJson(raw: string): Record<string, unknown> | null;
-declare function buildClassifierPrompt(text: string, ctx: {
-    state: PlaybookState;
-    pendingQuestions: readonly PendingBossQuestion[];
-}): string;
-declare function parseClassification(raw: string, text: string, pendingQuestionIds?: readonly string[]): DecideEvent | {
-    type: 'NO_ACTION';
-} | null;
-declare function buildAdjudicatorPrompt(input: PlayerInput, playerOutput: string, correction?: {
-    readonly reply: string;
-    readonly error: string;
-}): string;
-declare function combineSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal;
-declare function pendingQuestionsFromContext(context: Record<string, unknown>): PendingBossQuestion[];
-declare function pendingQuestionsForState(state: PlaybookState, context: Record<string, unknown>): PendingBossQuestion[];
-export declare const createPlaybookRuntime: PlaybookRuntimeFactory<DecidePlaybookRuntimeConstruction>;
+export type PlaybookHostCapabilities = XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, {
+    readonly authority: object;
+}>['hostCapabilities'];
+export declare function validateOptions(value: unknown): PlaybookRuntimeOptions;
 export declare const _internal: {
-    composePlayerPrompt: typeof composePlayerPrompt;
-    requiredFieldsFor: typeof requiredFieldsFor;
-    extractJson: typeof extractJson;
-    buildClassifierPrompt: typeof buildClassifierPrompt;
-    parseClassification: typeof parseClassification;
-    buildAdjudicatorPrompt: typeof buildAdjudicatorPrompt;
-    combineSignals: typeof combineSignals;
-    pendingQuestionsFromContext: typeof pendingQuestionsFromContext;
-    pendingQuestionsForState: typeof pendingQuestionsForState;
-    normalizeErrorCompact: typeof normalizeErrorCompact;
-    normalizeErrorFull: typeof normalizeErrorFull;
-    STATE_DESCRIPTIONS: Readonly<Record<string, string>>;
-    ROLE_STATES: readonly [{
-        readonly stateId: "askCoderProposal";
-        readonly role: "coder";
-        readonly sourceItem: "DECIDE-1";
-    }, {
-        readonly stateId: "askReviewerProposal";
-        readonly role: "reviewer";
-        readonly sourceItem: "DECIDE-2";
-    }, {
-        readonly stateId: "commitCoderProposal";
-        readonly role: "coder";
-        readonly sourceItem: "DECIDE-3";
-    }];
-    ROLE_STATE_IDS: ReadonlySet<string>;
-    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
-    BOSS_INTERRUPT_TARGETS: readonly ["independentProposals"];
+    composePlayerPrompt: (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean) => string;
+    RESUMABLE_STATE_IDS: ReadonlySet<string>;
     UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
-    TELEMETRY_TOPIC: string;
+    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
 };
+declare const createPlaybookRuntime: XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3>;
 export default createPlaybookRuntime;