@sublang/playbook 0.4.2 → 0.6.0

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

@@ -15,8 +15,9 @@ 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 or @specs/meta.md for relevant context if needed; ensure @specs/map.md reflects the changes.
+> If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations and stop without implementing any IR task.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Ensure @specs/map.md reflects the changes.
 > Do not commit.
 The resulting changes are Initial Changes.
 
@@ -49,11 +50,11 @@ When an IR is done, Captain shall prompt Coder:
 > The set should be complete and coherent.
 > Avoid implementation specifics.
 > Avoid redundant spec items.
-> Consult @specs/map.md for relevant context and update it to reflect your changes.
+> Ensure @specs/map.md reflects the changes.
 ## Reviewer
 
 For each finding in a review round, Coder either addresses it with changes or challenges it with a rebuttal.
-Any code change to address findings starts a new round of review, no matter if some findings are also rebutted.
+Any code change to address findings starts a new round of review, even if some findings are also rebutted.
 Rounds continue until Reviewer raises no findings.
 
 ### CODE-5
@@ -64,12 +65,15 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-6
 
@@ -78,8 +82,10 @@ 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 or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-7
 
@@ -89,14 +95,17 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > 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 or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-8
 
@@ -106,12 +115,15 @@ When Committer commits Initial Changes from an IR task involving changes only in
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-9
 
@@ -120,8 +132,10 @@ 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 or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-10
 
@@ -131,105 +145,125 @@ When Committer commits Initial Changes from an IR task involving changes both in
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > 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 or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-11
 
 When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only in @specs/user/, @specs/dev/, or @specs/test/ without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
-> Review the unstaged/untracked changes.
+> Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-12
 
 When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside @specs/user/, @specs/dev/, and @specs/test/ without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
-> Review the unstaged/untracked changes.
+> Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-13
 
 When Coder makes unreviewed changes (outside of any Initial Changes) involving changes both in and outside @specs/user/, @specs/dev/, and @specs/test/ without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
-> Review the unstaged/untracked changes.
+> Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > 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 or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 
 ### CODE-14
 
 When Coder raises rebuttals without making code changes, Captain shall relay them to Reviewer along with the following prompt:
 > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
+> Do not edit files or commit; report findings only.
 
 ### CODE-15
 
 When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only in @specs/user/, @specs/dev/, or @specs/test/ and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
-> Review the unstaged/untracked changes.
+> Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
-> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
 
 ### CODE-16
 
 When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside @specs/user/, @specs/dev/, and @specs/test/ and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
-> Review the unstaged/untracked changes.
+> Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
-> Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
 
 ### CODE-17
 
 When Coder makes unreviewed changes (outside of any Initial Changes) involving changes both in and outside @specs/user/, @specs/dev/, and @specs/test/ and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
-> Review the unstaged/untracked changes.
+> Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
 > 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 or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
 > If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
 > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
 
 ## Committer
@@ -238,6 +272,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 
 When Coder makes any Initial Changes and Reviewer has not 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).
+> Write concisely.
 > Coder is <coder-llm>.
 > Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
 
@@ -247,6 +282,7 @@ Result guard: `needsBossInput` — Committing requires additional Boss input or
 
 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).
+> Write concisely.
 > Coder is <coder-llm>; Reviewer is <reviewer-llm>.
 > Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
 

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

@@ -22,6 +22,16 @@ export interface PlaybookRuntime {
     dispose(): Promise<void>;
 }
 export type CodePlaybookOptions = CodingInput;
+declare function normalizeErrorCompact(err: unknown): {
+    name: string;
+    message: string;
+} | undefined;
+declare function normalizeErrorFull(err: unknown): {
+    name: string;
+    message: string;
+    stack?: string;
+} | undefined;
+declare function normalizeEventForTelemetry(event: unknown): unknown;
 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>;
@@ -39,8 +49,9 @@ interface PendingBossQuestionForStatus {
     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 formatAwaitBossReplyQuestion(context: Record<string, unknown>): string;
+declare function formatAwaitBossReplyMarker(context: Record<string, unknown>): string;
+declare function formatStateEntry(stateId: string): string | undefined;
 declare function formatTransition(event: unknown): string | undefined;
 declare function formatClassification(eventType: string): string;
 declare function stateTelemetryPayload(from: unknown, to: string, event: unknown, context: Record<string, unknown>): Record<string, unknown>;
@@ -53,11 +64,16 @@ export declare const _internal: {
     STATE_LABELS: Readonly<Record<string, string>>;
     stateMetadata: ReadonlyMap<string, StateMetadata>;
     pendingBossQuestionFromContext: typeof pendingBossQuestionFromContext;
-    formatAwaitBossReplyEntry: typeof formatAwaitBossReplyEntry;
+    formatAwaitBossReplyQuestion: typeof formatAwaitBossReplyQuestion;
+    formatAwaitBossReplyMarker: typeof formatAwaitBossReplyMarker;
     formatStateEntry: typeof formatStateEntry;
     formatTransition: typeof formatTransition;
     formatClassification: typeof formatClassification;
     stateTelemetryPayload: typeof stateTelemetryPayload;
+    normalizeErrorCompact: typeof normalizeErrorCompact;
+    normalizeErrorFull: typeof normalizeErrorFull;
+    normalizeEventForTelemetry: typeof normalizeEventForTelemetry;
+    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
 };
 export default function createPlaybookRuntime(options: CodePlaybookOptions): PlaybookRuntime;
 export {};