@sublang/playbook 17.3.0 → 17.4.1

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

@@ -11,7 +11,7 @@ Roles:
 
 ### CODE-1
 
-Each phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
+Each completed phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
 Captain uses the repository-effect receipt as the authoritative identity of the phase's new commit.
 When the request may continue an existing IR that it does not identify unambiguously, Coder asks Boss before changing files, and Boss's answer resumes this same phase.
 
@@ -28,13 +28,19 @@ When the first coding phase begins for the caller's coding request and any relev
 > For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 > Do not implement a later task in this phase.
 > Mark the IR's progress and deliverables when relevant.
+> After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+> Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+> Report only what the IR and completed work establish, in ordinary prose without a required marker.
 > If the IR will be finished after this phase, double-check that all acceptance criteria are met.
 >
 > Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 >
 > Keep to the original intent and follow what it asks.
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
-> Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
+> If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.
+> Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.
+> After the answer allows completion, make exactly one phase-owned commit before REVIEW.
+> When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
 > Make the commit message explain concisely what changed and why, including relevant verification.
 > Identify every new commit you make.
 > Credit every AI that contributed to this commit: Coder <coder-llm>.
@@ -47,6 +53,7 @@ Results:
 - `irCommit`: Coder decomposed the new coding intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.
 - `moreTasks`: Coder continued an existing IR, implemented exactly its next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.
 - `finalTask`: Coder continued an existing IR, implemented its final unfinished task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.
+- `needsBossReply`: At the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome. Output shall include `question: <verbatim question text from the acting agent's prose>`.
 
 ### CODE-2
 
@@ -59,6 +66,10 @@ When a direct implementation or new-IR phase ends with its one new `code`-owned
 > > Coder output: <coder-output>
 
 A nested `review` passes the phase only when its result applies to that supplied review scope, returns the exact evaluated repository revision, and affirmatively establishes that no unsettled findings remain.
+On each successful nested REVIEW, Captain shall freeze the previous phase review as one record from the canonical child result and the phase's accepted receipt-owned scope: exact phase kind (direct, new intent or IR task), phase outcome, CODE scope commit, REVIEW evaluated revision, and IR/task identity when present.
+CODE scope commit and evaluated revision remain distinct because REVIEW may create fix commits.
+No caller option, player prose or repository status text supplies this record.
+The record survives permitted restoration and the current task's Boss-answer continuation, and a fresh run or explicit Boss interruption clears it.
 When `review` passes a direct implementation phase, `code` is complete and returns to its caller the exact last `code`-owned commit, the exact final evaluated repository revision, and the fact that every phase's review passed with no unsettled findings.
 When `review` passes a new-IR phase, Captain continues with the next unfinished IR-task phase.
 When `review` returns an authored abort or failure, or a terminal result that does not establish that the supplied scope was evaluated with no unsettled findings, `code` starts no further phase and reports the failure and the last `code`-owned commit to its caller.
@@ -66,7 +77,9 @@ When the nested `review` call fails outside that authored result contract, `code
 
 ### CODE-3
 
-Each phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
+When absent, the previous phase review reads "No accepted prior-phase review is available.".
+
+Each completed phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
 Captain uses the repository-effect receipt as the authoritative identity of the phase's new commit.
 
 When a later IR-task phase begins, Captain shall prompt Coder:
@@ -74,11 +87,20 @@ When a later IR-task phase begins, Captain shall prompt Coder:
 > Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 > Do not implement a later task in this phase.
 > Mark the IR's progress and deliverables when relevant.
+> After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+> Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+> Report only what the IR and completed work establish, in ordinary prose without a required marker.
 > If the IR will be finished after this phase, double-check that all acceptance criteria are met.
+> Use the quoted previous-phase review only for its exact recorded scope; committed pending-review text may predate that canonical result.
+> Before treating it as current review evidence, verify clean current HEAD equals its evaluatedRevision; a mismatch is not approval.
+> It does not replace independent review of this task or any new owner or release decision.
 >
 > Keep to the original intent and follow what it asks.
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
-> Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
+> If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.
+> Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.
+> After the answer allows completion, make exactly one phase-owned commit before REVIEW.
+> When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
 > Make the commit message explain concisely what changed and why, including relevant verification.
 > Identify every new commit you make.
 > Credit every AI that contributed to this commit: Coder <coder-llm>.
@@ -86,10 +108,12 @@ When a later IR-task phase begins, Captain shall prompt Coder:
 > > Original request: <caller-input>
 > > IR number: <ir-number>
 > > Run results: <run-results>
+> > Previous phase review: <previous-phase-review>
 
 Results:
 - `moreTasks`: Coder implemented exactly the IR's next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the IR, and `irTask` naming the implemented task.
 - `finalTask`: Coder implemented the IR's final unfinished task and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the IR, and `irTask` naming the implemented task.
+- `needsBossReply`: At the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome. Output shall include `question: <verbatim question text from the acting agent's prose>`.
 
 ### CODE-4
 
@@ -104,6 +128,10 @@ When an IR-task phase, including the first phase for an existing IR, ends with i
 > > Current IR task: <ir-task>
 
 A nested `review` passes the phase only when its result applies to that supplied review scope, returns the exact evaluated repository revision, and affirmatively establishes that no unsettled findings remain.
+On each successful nested REVIEW, Captain shall freeze the previous phase review as one record from the canonical child result and the phase's accepted receipt-owned scope: exact phase kind (direct, new intent or IR task), phase outcome, CODE scope commit, REVIEW evaluated revision, and IR/task identity when present.
+CODE scope commit and evaluated revision remain distinct because REVIEW may create fix commits.
+No caller option, player prose or repository status text supplies this record.
+The record survives permitted restoration and the current task's Boss-answer continuation, and a fresh run or explicit Boss interruption clears it.
 When `review` passes a nonfinal IR-task phase, Captain continues with the next unfinished IR-task phase.
 When `review` passes the final IR-task phase, `code` is complete and returns to its caller the exact last `code`-owned commit, the exact final evaluated repository revision, and the fact that every phase's review passed with no unsettled findings.
 When `review` returns an authored abort or failure, or a terminal result that does not establish that the supplied scope was evaluated with no unsettled findings, `code` starts no further phase and reports the failure and the last `code`-owned commit to its caller.

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

@@ -3,7 +3,11 @@ import type { Effort, PermissionPolicy } from '@sublang/cligent';
 import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookFailureCause, PlaybookRuntime, PlaybookRuntimeSnapshot, PlaybookStepRecord } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
+import type { Attachment } from '@sublang/cligent';
+import type { SessionAssetRef } from './session-assets.js';
 interface SessionAgent {
+    /** Mutable next-turn execution capability; never structural identity. */
+    readonly browser?: boolean;
     readonly adapter: string;
     readonly model: TuningSelection;
     readonly effort: TuningSelection<Effort>;
@@ -40,7 +44,7 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
     readonly rootPlaybookId: string;
     readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
 }
-type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey>>;
+type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser'>>;
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 export interface ProgressChange {
     snapshot?: PlaybookCaptainShellSnapshot | null;
@@ -48,6 +52,10 @@ export interface ProgressChange {
         kind: PlaybookStepRecord['kind'] | 'preparation' | 'completion' | 'answer';
         runtimeSessionId: string;
         playbookId: string;
+        workerEvidence?: {
+            boundaryId: string;
+            playerId: string;
+        };
     };
 }
 export interface InterruptedReport {
@@ -57,6 +65,9 @@ export interface InterruptedReport {
     unresolvedEffects?: readonly PlaybookCaptainUnresolvedEffect[];
 }
 export interface PlaybookCaptainDeps {
+    onTurnAttachments?: (references: readonly SessionAssetRef[]) => void;
+    beginPreparationMedia?: (runtimeSessionId: string) => () => void;
+    resolveAttachments?: (references: readonly SessionAssetRef[], signal: AbortSignal) => Promise<readonly Attachment[]>;
     /** Stop the host's active turn, including admitted tool calls, on preparation expiry or a required save failure. */
     abortPreparation?: (reason?: string) => void;
     recordProgress?: (change: ProgressChange) => Promise<void>;
@@ -164,6 +175,7 @@ export interface PlaybookCaptainFrameSnapshot {
     readonly parentCallId?: string;
     readonly request?: string;
     readonly inputs?: readonly string[];
+    readonly attachments?: readonly SessionAssetRef[];
     readonly options: JsonValue;
     readonly roleBindings: Readonly<Record<string, string>>;
     readonly runtime: DeepReadonly<PlaybookRuntimeSnapshot>;
@@ -186,6 +198,7 @@ interface PlaybookCaptainShellSnapshotFields {
         readonly journal: number;
     };
     readonly journal: readonly PlaybookCaptainJournalRecord[];
+    readonly pendingAttachments?: readonly SessionAssetRef[];
     readonly lastAction?: 'respond' | 'start' | 'switch' | 'resume' | 'dismiss' | 'deliver' | 'runtime' | 'recover';
     readonly lastSettlementStatus?: 'ok' | 'rejected' | 'failed';
 }
@@ -241,6 +254,9 @@ export interface PlaybookCaptainSettlement {
 }
 /** tmux and headless front ends share this one durable Captain shell API. */
 export interface PlaybookCaptainShell extends Captain {
+    /** Bind already-owned evidence to the next visible Boss turn without changing its text. */
+    setTurnAttachments(references: readonly SessionAssetRef[]): void;
+    recordMediaEvidence(reference: SessionAssetRef, runtimeSessionId?: string): void;
     installRetainedGenerations(generations: Readonly<Record<string, PlaybookCaptainRetainedGeneration>>): Promise<void>;
     exportSnapshot(): PlaybookCaptainShellSnapshot | undefined;
     exportSettlement(): PlaybookCaptainSettlement | undefined;