@sublang/playbook 4.0.0 → 6.0.0

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

@@ -0,0 +1,88 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Decide
+
+## Players
+
+- Boss: the human user (default)
+- Captain: the coordinating agent (default)
+- Coder
+- Reviewer
+
+## Independent proposals
+
+The caller supplies a topic as `callerTopic`.
+Coder and Reviewer receive the complete topic concurrently and independently.
+Neither player receives the other player's proposal before both proposals finish and Coder commits Coder's own proposal.
+A Boss interrupt during the parallel proposal pair restarts the complete pair with the new `callerTopic`.
+
+### 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:
+
+> > <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.
+
+Results:
+- `proposed`: Coder completed an independent proposal. Output shall include `coderProposal: <verbatim final text>`.
+
+### DECIDE-2
+
+Parallel group: independent-proposals
+
+When the caller gives a topic, Captain shall relay the complete topic to Reviewer in quotes and prompt Reviewer:
+
+> > <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.
+
+Results:
+- `proposed`: Reviewer completed an independent proposal. Output shall include `reviewerProposal: <verbatim final text>`.
+
+## Commit Coder's proposal
+
+### DECIDE-3
+
+When both independent proposals are complete, Captain shall prompt Coder:
+
+> Turn your proposal into the necessary spec items or DRs.
+> Follow @specs/meta.md and update @specs/map.md when needed.
+> Do not inspect or incorporate Reviewer's proposal before this commit.
+> Do not change code or implement the proposal.
+>
+> Commit the result as one new commit, following @specs/packages/git.md.
+> Make the commit message explain concisely what changed and why.
+> Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
+> Coder is <coder-llm>; format the model token in conventional human form.
+
+Results:
+- `committed`: Coder committed Coder's proposal. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+
+## Review
+
+### DECIDE-4
+
+When Coder commits, Captain shall call playbook `review`:
+
+> Review the latest commit as a spec-design change against the initial intent.
+> Compare it with your independent proposal and take the best of both.
+> Make your suggestions.
+>
+> Initial intent: <caller-topic>.
+> Coder's independent proposal: <coder-proposal>.
+
+The successful child output is DECIDE's terminal output.
+An authored child abort, failure, or invalid approval terminates with the failure and `latestCommit` reported to the caller.
+Any other nested-call error parks `decide` as failed and retains the control-plane error.

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

@@ -0,0 +1,67 @@
+import { type PlayerInput, type PlayerOutput, type DecideEvent, type DecideInput, type PendingBossQuestion } from './decide.fsm.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 PlayerName = 'Coder' | 'Reviewer';
+export interface PlaybookRuntimeOptions extends DecideInput {
+    playerBinding?: Partial<Record<PlayerName, string>>;
+}
+declare function composePlayerPrompt(input: PlayerInput): string;
+declare function resolvePlayerId(input: PlayerInput, binding: Record<PlayerName, string>): 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): string;
+declare function parseAdjudication(raw: string, input: PlayerInput, finalText: string): PlayerOutput;
+declare function combineSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal;
+declare function normalizeErrorCompact(err: unknown): {
+    name: string;
+    message: string;
+} | undefined;
+declare function normalizeErrorFull(err: unknown): {
+    name: string;
+    message: string;
+    stack?: string;
+} | undefined;
+declare function pendingQuestionsFromContext(context: Record<string, unknown>): PendingBossQuestion[];
+export declare const createPlaybookRuntime: PlaybookRuntimeFactory<PlaybookRuntimeOptions>;
+export declare const _internal: {
+    composePlayerPrompt: typeof composePlayerPrompt;
+    resolvePlayerId: typeof resolvePlayerId;
+    requiredFieldsFor: typeof requiredFieldsFor;
+    extractJson: typeof extractJson;
+    buildClassifierPrompt: typeof buildClassifierPrompt;
+    parseClassification: typeof parseClassification;
+    buildAdjudicatorPrompt: typeof buildAdjudicatorPrompt;
+    parseAdjudication: typeof parseAdjudication;
+    combineSignals: typeof combineSignals;
+    pendingQuestionsFromContext: typeof pendingQuestionsFromContext;
+    normalizeErrorCompact: typeof normalizeErrorCompact;
+    normalizeErrorFull: typeof normalizeErrorFull;
+    DEFAULT_PLAYER_BINDING: Readonly<Record<PlayerName, string>>;
+    STATE_DESCRIPTIONS: Readonly<Record<string, string>>;
+    PLAYER_STATES: readonly [{
+        readonly stateId: "askCoderProposal";
+        readonly player: "Coder";
+        readonly sourceItem: "DECIDE-1";
+    }, {
+        readonly stateId: "askReviewerProposal";
+        readonly player: "Reviewer";
+        readonly sourceItem: "DECIDE-2";
+    }, {
+        readonly stateId: "commitCoderProposal";
+        readonly player: "Coder";
+        readonly sourceItem: "DECIDE-3";
+    }];
+    PLAYER_STATE_IDS: ReadonlySet<string>;
+    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
+    BOSS_INTERRUPT_TARGETS: readonly ["independentProposals"];
+    CONTINUATION_PREAMBLE: string;
+    TELEMETRY_TOPIC: string;
+};
+export default createPlaybookRuntime;