@sublang/playbook 0.1.3 → 0.4.0

package/{code.gears.md → reference/sdlc/code.playbook/code.gears.md}

@@ -16,9 +16,8 @@ Players:
 When Boss gives a coding intent, Captain shall relay it to Coder along with the following prompt:
 > Assess whether this can be completed in a single commit, following best practices.
 > If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations.
-> Consult @specs/map.md for relevant context if needed; ensure it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; ensure @specs/map.md reflects the changes.
 > Do not commit.
-
 The resulting changes are Initial Changes.
 
 ### CODE-2
@@ -34,7 +33,6 @@ When a new IR or IR task passes review and is committed, Captain shall prompt Co
 > Implement one task at a time (including corresponding tests if any).
 > Stop after each task for review — do not commit yet.
 > If relevant, mark progress in the IR.
-
 The resulting changes are Initial Changes.
 
 ### CODE-4
@@ -52,7 +50,6 @@ When an IR is done, Captain shall prompt Coder:
 > Avoid implementation specifics.
 > Avoid redundant spec items.
 > Consult @specs/map.md for relevant context and update it to reflect your changes.
-
 ## Reviewer
 
 For each finding in a review round, Coder either addresses it with changes or challenges it with a rebuttal.
@@ -71,7 +68,7 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-6
@@ -81,7 +78,7 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 > Refer to the commit message.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-7
@@ -98,7 +95,7 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-8
@@ -113,7 +110,7 @@ When Committer commits Initial Changes from an IR task involving changes only in
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-9
@@ -123,7 +120,7 @@ When Committer commits Initial Changes from an IR task involving changes only ou
 > Refer to the commit message.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-10
@@ -140,7 +137,7 @@ When Committer commits Initial Changes from an IR task involving changes both in
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-11
@@ -155,7 +152,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-12
@@ -165,7 +162,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-13
@@ -182,7 +179,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 
 ### CODE-14
@@ -202,7 +199,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
 
@@ -213,7 +210,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
 
@@ -231,7 +228,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md for relevant context if needed; verify it reflects the changes.
+> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
 > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
 
@@ -243,8 +240,12 @@ When Coder makes any Initial Changes and Reviewer has not played since the last
 > Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
 > Coder is <coder-llm>.
 
+Result guard: `needsBossInput` — Committing requires additional Boss input or rescoping rather than a specific answer to resume this same state.
+
 ### CODE-19
 
 When Coder makes any Initial Changes and Reviewer has played since the last commit, or Reviewer raises no findings on uncommitted changes and Coder has played since the last commit, Captain shall prompt Committer:
 > Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
 > Coder is <coder-llm>; Reviewer is <reviewer-llm>.
+
+Result guard: `needsBossInput` — Committing requires additional Boss input or rescoping rather than a specific answer to resume this same state.

package/{code.playbook.d.ts → reference/sdlc/code.playbook/code.playbook.d.ts}

@@ -25,17 +25,25 @@ export type CodePlaybookOptions = CodingInput;
 declare function composePlayerPrompt(input: CaptainInput): string;
 declare function resolvePlayerId(input: CaptainInput): string;
 declare function adjudicate(input: CaptainInput, finalText: string, ports: PlaybookPorts, signal: AbortSignal): Promise<CaptainOutput>;
-declare function classifyBossText(text: string, ports: PlaybookPorts, signal: AbortSignal): Promise<CodingEvent | undefined>;
+declare function classifyBossText(text: string, ports: PlaybookPorts, signal: AbortSignal, snapshotOrState?: unknown): Promise<CodingEvent | undefined>;
 declare function captainBridge(ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined): import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>;
 interface StateMetadata {
     player: CaptainInput['player'];
     sourceItem: string;
     label: string;
 }
-declare function formatStateEntry(stateId: string): string;
+interface PendingBossQuestionForStatus {
+    resumeStateId: string;
+    sourceItem: string;
+    player: string;
+    question: string;
+}
+declare function pendingBossQuestionFromContext(context: Record<string, unknown>): PendingBossQuestionForStatus | undefined;
+declare function formatAwaitBossReplyEntry(context: Record<string, unknown>): string;
+declare function formatStateEntry(stateId: string, context?: Record<string, unknown>): string | undefined;
 declare function formatTransition(event: unknown): string | undefined;
-declare function formatBossEcho(text: string, eventType?: string): string;
-declare function formatRiders(context: Record<string, unknown>): string;
+declare function formatClassification(eventType: string): string;
+declare function stateTelemetryPayload(from: unknown, to: string, event: unknown, context: Record<string, unknown>): Record<string, unknown>;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     resolvePlayerId: typeof resolvePlayerId;
@@ -44,10 +52,12 @@ export declare const _internal: {
     captainBridge: typeof captainBridge;
     STATE_LABELS: Readonly<Record<string, string>>;
     stateMetadata: ReadonlyMap<string, StateMetadata>;
+    pendingBossQuestionFromContext: typeof pendingBossQuestionFromContext;
+    formatAwaitBossReplyEntry: typeof formatAwaitBossReplyEntry;
     formatStateEntry: typeof formatStateEntry;
     formatTransition: typeof formatTransition;
-    formatBossEcho: typeof formatBossEcho;
-    formatRiders: typeof formatRiders;
+    formatClassification: typeof formatClassification;
+    stateTelemetryPayload: typeof stateTelemetryPayload;
 };
 export default function createPlaybookRuntime(options: CodePlaybookOptions): PlaybookRuntime;
 export {};