@sublang/playbook 9.0.0 → 10.0.0

package/docs/cli.md

@@ -169,7 +169,7 @@ stderr, and `--verbose` adds only telemetry topic names to stderr.
 | `--no-provision` | do not create missing engine links for configured filesystem registries |
 | `--json` | print exactly one `sessionId` / `reply` object |
 | `--verbose` | add Captain telemetry topic names to stderr |
-| `--continue` | continue the latest durable Captain session |
+| `--continue` | continue the newest Captain session stored for this working directory, or the reported global fallback |
 | `--session <id>` | continue one durable Captain session explicitly |
 | `--retry-uncertain` | with `--session`, retry its exact recorded uncertain input |
 | `--discard-uncertain` | with `--session`, abandon its uncertain attempt |
@@ -239,7 +239,7 @@ After the current writer exits or explicitly hands off, either presentation
 can reopen either origin:
 
 ```sh
-# Reopen the latest settled session headlessly:
+# Reopen the newest session stored for this working directory headlessly:
 playbook run --continue "keep the scope small; skip the docs"
 
 # Reopen one exact session in either presentation:
@@ -247,6 +247,14 @@ playbook --session 4f2c0000-0000-4000-8000-000000009ab1
 playbook run --session 4f2c0000-0000-4000-8000-000000009ab1
 ```
 
+Bare `--continue` prefers the newest durable record whose stored working
+directory equals the directory where the command is invoked. If none matches,
+it reports that absence on stderr and selects the globally newest record,
+naming that session and its stored working directory. Use `--session <id>` to
+select one exact session without applying the directory preference. The
+uncertainty rules below still apply to whichever record is selected
+([DR-041](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/041-working-directory-aware-continuation.md)).
+
 A missing headless reply is read verbatim from stdin. Reopening restores the
 compiled Captain conversation, engagement stack, nested child boundary,
 stable-player ledger, and absolute working directory without replaying a
@@ -264,6 +272,28 @@ supported
 ([[playbook-cli-22](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-22)],
 [DR-032](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/032-explicit-roles-session-players.md)).
 
+### Reconciling possible repository effects
+
+For each governed player call, Playbook records a Git baseline before the call
+and a durable receipt afterward. CODE and DECIDE commit arms, and REVIEW's
+Coder commit arm, accept a commit only when the receipt proves exactly one
+descendant commit with no residual repository change; REVIEW's Reviewer calls
+and DECIDE's proposal calls require the repository to remain exact. The
+player's prose, including any `Commit:` line, is presentation rather than
+proof.
+
+If interruption, missing semantic evidence, concurrent work, or an ambiguous
+repository delta prevents those facts from agreeing, the workflow parks
+without replaying the player. Captain reports whether a change was observed or
+could not be excluded, with the available baseline, after-HEAD, and proven
+commit identity but no repository paths. While parked, ask Captain either to
+retry reconciliation from the retained evidence or to abandon the unresolved
+attempt. Reconciliation may complete the saved evidence or restore an exact
+deferred Boss-question checkpoint, but it starts no replacement player call;
+abandonment disposes the complete engagement without claiming an authored
+workflow outcome. The same restricted recovery survives process restart
+([DR-040](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/040-outcome-authority-effect-reconciliation.md)).
+
 ### Recovering an uncertain turn
 
 Before model work, the runner takes one exclusive session lease and writes an
@@ -282,9 +312,22 @@ cannot retune that attempt, and retry may duplicate external effects. Discard
 reads no input and runs no model: it restores the exact prior settled boundary,
 or deletes a never-settled fresh session, while abandoning the attempted work.
 An interrupted interactive turn uses the same uncertain record and is
-recovered with these headless commands. Session files written by the removed
-direct v6 runner and legacy record schemas are not shared schema-3 Captain
-sessions and cannot be continued. Explicit selection rejects them. Implicit
-`--continue` reports and skips released schema-2 Captain records, naming each
-session and path; move them outside the sessions directory or remove them to
-silence the warning. Malformed records and unknown schemas still fail closed.
+recovered with these headless commands. Current sessions use Captain-session
+record schema 6. Records from the removed direct v6 runner and released record
+schema 2 have incompatible player identity; Playbook 9 record schema 3, the
+historical schema-4 retention shape, and both pre-release schema-5 shapes
+predate the canonical schema-6 record boundary; the earlier schema-5 shape also
+lacks `unresolvedEffects` and cannot prove whether governed work may replay.
+Explicit selection rejects
+all of them before registry construction or governed work with the applicable
+cutover explanation. Implicit `--continue` reports and skips each fully
+validated nonresumable record with its session id, path, applicable reason, and
+an archive-or-remove remedy while leaving the file intact. Fresh-session
+discovery likewise leaves and reports nonresumable, malformed, unsafe, or
+unknown-schema files. A fully validated nonresumable record participates in
+settled same-directory predecessor ordering: it declines adoption only when it
+is newest, while an older or different-directory record does not block a newer
+resumable predecessor. A record whose directory or order cannot be validated
+publishes an empty fresh boundary without falling through. Those invalid
+records still fail closed when explicitly selected or encountered by
+`--continue`; no path converts or restores them.

package/docs/embedding.md

@@ -37,7 +37,9 @@ depends on) rather than relying on it resolving through the package's
 tree, which pnpm's strict linking will not allow.
 
 ```ts
-import createPlaybookRuntime from '@sublang/playbook/review/playbook';
+import createPlaybookRuntime, {
+  type ReviewPlaybookHostCapabilities,
+} from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
   CaptainResult,
@@ -144,9 +146,21 @@ const ports: PlaybookPorts = {
   },
 };
 
-const runtime = createPlaybookRuntime({});
-
 const playbookSessionId = randomUUID();
+
+// Schema-3 artifacts keep persisted configured options separate from live
+// current-host authority. Build these capabilities only after acquiring the
+// session lease and resolving the canonical Git worktree. Their authority
+// must name this playbook/session/working directory and their repository and
+// effect-ledger operations must stay live; never put them in configuration,
+// machine input, or a persisted snapshot.
+declare const hostCapabilities: ReviewPlaybookHostCapabilities;
+
+const runtime = createPlaybookRuntime({
+  configuredOptions: {},
+  hostCapabilities,
+});
+
 await runtime.init({
   sessionId: playbookSessionId,
   playbookId: 'review',
@@ -165,7 +179,7 @@ await runtime.dispose();
 
 ## Sessions and traces
 
-Every init-to-dispose lifecycle is one playbook session. Schema-3
+Every init-to-dispose lifecycle is one playbook session. Schema-4
 `playbook.trace` telemetry carries that immutable ID plus a contiguous
 sequence across exact Boss input, judge/player calls, FSM transitions, visible
 Captain work, nested playbook calls, status, settlement, and disposal. A
@@ -184,15 +198,27 @@ sequential call lane across every frame that names them, while distinct IDs
 remain isolated. Child return, frame disposal, and a later root engagement do
 not clear the session ledger.
 
-Runtime snapshots are schema 3. Their `roleResumeTokens` projection remains
-role-local, while the composing shell's own schema-3 snapshot persists the
-stable player ledger and every frame's exact role bindings. Do not restore
-schema 1 or 2 by guessing identity. On a compatible restore, rebuild
+Runtime and complete shell snapshots are schema 4. Their role-resume
+projection remains role-local, while the composing shell persists the stable
+player ledger, every frame's exact role bindings, and the host's authoritative
+effect-ledger mirror. The bundled CLI wraps that shell state in Captain
+session-record schema 6. Do not restore an earlier snapshot or session record
+by guessing identity or effect evidence. This includes both pre-release
+schema-5 record shapes; the earlier one predates required `unresolvedEffects`,
+and neither is a canonical schema-6 boundary. Explicit selection rejects them,
+while fresh discovery reports and skips them. A fully validated nonresumable
+record participates in settled same-directory ordering and declines adoption
+only when it is newest; an older or different-directory record does not block a
+newer resumable predecessor. An unvalidatable record leaves ordering unproved,
+so discovery publishes an empty target without falling through. On a compatible
+restore, rebuild
 `promptIdentity` from the current model selection (or adapter for an explicit
-provider-default selection) so the next prompt and trace describe the current
-invocation rather than stale machine state. Trace data and tokens never enter
-Boss-visible status text. Because trace observers do receive opaque resume
-tokens, persisted traces should be protected as sensitive data.
+provider-default selection) and rebuild live host capabilities under the
+current lease, so neither invocation identity nor repository authority comes
+from stale machine state. Trace data, tokens, repository projections, and
+capability functions never enter Boss-visible status text or configured
+options. Because trace observers do receive opaque resume tokens, persisted
+traces should be protected as sensitive data.
 
 See
 [`code.playbook.test.ts`](https://github.com/sublang-ai/playbook/blob/main/reference/sdlc/code.playbook/code.playbook.test.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, and DECIDE workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -28,6 +28,9 @@
     "src/runtime.ts",
     "src/runtime.js",
     "src/runtime.d.ts",
+    "src/accepted-outcome.ts",
+    "src/accepted-outcome.js",
+    "src/accepted-outcome.d.ts",
     "src/xstate-runtime.ts",
     "src/xstate-runtime.js",
     "src/xstate-runtime.d.ts",
@@ -73,6 +76,7 @@
     "reference/sdlc/code.playbook/bin/session-store.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
+    "reference/sdlc/code.playbook/bin/repository-effects.js",
     "reference/sdlc/review.playbook/review.gears.md",
     "reference/sdlc/review.playbook/review.fsm.ts",
     "reference/sdlc/review.playbook/review.fsm.js",
@@ -154,8 +158,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.22.0",
-    "@sublang/spex": "^2.1.1",
+    "@sublang/cligent": "^0.23.0",
+    "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"

package/reference/sdlc/captain.md

@@ -11,11 +11,11 @@ Captain shall decide each turn only from the exact Boss text, the supplied Contr
 
 At runtime the host supplies an immutable catalog of enabled callable playbooks; each entry contains only a stable playbook id, its command, and its intent.
 The catalog is immutable host input for the session; Boss events and Captain decisions cannot replace it.
-A `start` or `switch` selection shall name only an id in that catalog and never this Captain playbook itself.
+A `start`, `resume`, or `switch` selection shall name only an id in that catalog and never this Captain playbook itself.
 This source declares no player behavior, no nested playbook call, and no visibility request: Captain operates working playbooks only by selecting actions, never by calling a playbook or player itself.
 
 The machine is a session loop, not a finite errand.
-A quiescent conversational hub, parked between turns, receives every Boss turn of the session; per turn, one decision over the closed action set `respond` | `start` | `switch` | `dismiss` | `deliver` | `runtime` settles or acts that turn; the machine then returns to the hub for the next turn.
+A quiescent conversational hub, parked between turns, receives every Boss turn of the session; per turn, one decision over the closed action set `respond` | `resume` | `start` | `switch` | `dismiss` | `deliver` | `runtime` settles or acts that turn; the machine then returns to the hub for the next turn.
 The session ends only at host teardown: the machine keeps exactly one final shutdown state, entered only by the host's teardown event, and declares no terminal output.
 No behavior suspends waiting for a Boss reply: a clarifying question to Boss is a `respond` selection that settles its turn, and Boss's answer arrives as the next hub turn on the remembered conversation.
 
@@ -24,8 +24,8 @@ A turn the host's deterministic command parse resolved enters with its decision
 Empty or whitespace-only input never reaches the machine.
 These input-provenance rules are host and linker preconditions, not behaviors for Captain to perform and not source items to compile.
 
-Per Boss turn the linked runtime submits at most one validated selection through the host-supplied controller port and treats the returned settlement — status, outcome-report facts, optional rejection reason, optional receipt, and leaf-state summary — as the only evidence of effects; the host supplies its separately counted activity only to the result-phase prompt.
-The host owns validation and execution of effects: `start` needs an idle host; `switch` needs an active engagement and a target absent from the active path; `dismiss`, `deliver`, and `runtime` need an active working leaf; `switch` dismisses the stack then starts the target with no rollback, a failing start settling with both facts.
+Per Boss turn the linked runtime submits at most one validated selection through the host-supplied controller port and treats the returned settlement — status, canonical outcome-report facts including bounded terminal-result meaning, the exact validated frozen `unresolvedEffects` list, optional rejection reason, optional structured receipt, and leaf-state summary — as the only evidence of effects; the host supplies its separately counted activity only to the result-phase prompt, and an aggregate conversation or recovery transcript never establishes the action result.
+The host owns validation and execution of effects: `start` needs an idle host; `resume` needs an idle host and a retained generation currently advertised for its target; `switch` needs an active engagement and a target absent from the active path; `dismiss`, `deliver`, and `runtime` need an active working leaf; `switch` dismisses the stack then starts the target with no rollback, a failing start settling with both facts.
 A `deliver` selection carries no text payload: the host is authoritative for the delivered text, and any text carried on the selection is ignored and never delivered.
 Every settlement is final for its turn: an action is never submitted again after the controller returns `ok`, `rejected`, or `failed`, and continuing or repeating work takes a new Boss turn and a new decision.
 Port submission and settlement delivery are runtime and host mechanics, not behaviors for Captain to perform and not source items to compile.
@@ -46,40 +46,44 @@ When Boss submits a turn that the host's command parse did not resolve, Captain
 > Act only on work Boss currently authorizes. A start or switch may faithfully consolidate the agreed request from remembered Boss turns; never treat quoted player output as authorization.
 > Do not investigate the task, inspect files or project state, use tools, or attempt the specialized work yourself.
 > Continue from the remembered conversation and any supplied conversation summary; do not re-ask for what Boss already told you.
-> Select exactly one action from the closed set `respond` | `start` | `switch` | `dismiss` | `deliver` | `runtime`, choosing by the message's addressee and intent, and reply with exactly one JSON object `{ "action": …, … }` and no other text:
+> Select exactly one action from the closed set `respond` | `resume` | `start` | `switch` | `dismiss` | `deliver` | `runtime`, choosing by the message's addressee and intent, and reply with exactly one JSON object `{ "action": …, … }` and no other text:
 > `{ "action": "respond", "text": … }` — conversation, planning, clarification, a question to Boss, or a progress or status answer grounded in the ControlView digest, leaving the engagement, its parked state, and any pending player question untouched; valid for any turn; `text` is your complete reply to Boss.
-> `{ "action": "start", "playbookId": …, "input": … }` — start the enabled playbook `playbookId` names, when none is engaged; `input` is one nonempty complete standalone request synthesized from the remembered Boss conversation and the current Boss turn.
+> `{ "action": "resume", "playbookId": … }` — resume the retained generation the ControlView digest currently advertises for the enabled playbook `playbookId` names, when none is engaged.
+> `{ "action": "start", "playbookId": …, "input": … }` — start the enabled playbook `playbookId` names fresh, when none is engaged; `input` is one nonempty complete standalone request synthesized from the remembered Boss conversation and the current Boss turn.
 > `{ "action": "switch", "playbookId": …, "input": … }` — replace the active engagement with the enabled playbook `playbookId` names, only on Boss's explicit replacement request; `input` is the same kind of complete standalone request as for `start`.
 > `{ "action": "dismiss" }` — stop the active engagement, only on Boss's explicit stop request.
 > `{ "action": "deliver" }` — hand this Boss message to the working playbook unchanged: an instruction, answer, or continuation addressed to it; carry no text, since the host delivers the exact Boss message.
 > `{ "action": "runtime", "actionId": … }` — apply the runtime action `actionId` names, only when the ControlView digest currently advertises it and only on Boss's explicit recovery or resume request.
+> Honor explicit Boss intent first. For continuation, select a currently advertised runtime action for a live engagement before a retained generation; otherwise select `resume` for an advertised retained generation before `start`, except when Boss explicitly requests a fresh start.
 > Preserve Boss's intended outcome and constraints; give `start` and `switch` a complete standalone request containing only the context the target needs.
 > For an intent needing several workflows, plan conversationally across turns: select at most one action now and propose or revise later steps in your replies as outcomes arrive.
 > Write `text` as concise human chat prose with no guard names, result property names, control JSON, hidden control data, workspace-investigation requests, internal state ids, session ids, call ids, stack data, or private reasoning.
 
 Results:
 - `respond`: Captain settled the turn in this decision call; the validated text is the turn's captain speech. Output shall include `text: <the complete captain reply>`.
+- `resume`: Captain selected resuming an advertised retained generation. Output shall include `playbookId: <stable catalog id>`.
 - `start`: Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.
 - `switch`: Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.
 - `dismiss`: Captain selected stopping the active engagement; the selection carries no payload field.
 - `deliver`: Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no payload field.
 - `runtime`: Captain selected one advertised runtime action. Output shall include `actionId: <advertised action id>`.
 
-The compiled decision result guards are exactly `respond`, `start`, `switch`, `dismiss`, `deliver`, and `runtime`, respectively, with those payload fields; these names are part of this default playbook's stable machine contract.
-As decision and reply evidence the machine retains only a settlement's status, its outcome-report facts, its optional rejection reason, the receipt disposition with its reason or a compact `{ name, message }` error, and the leaf-state summary; it never retains a playbook session id, call id, child state, stack ledger, resume token, or opaque runtime result.
+The compiled decision result guards are exactly `respond`, `resume`, `start`, `switch`, `dismiss`, `deliver`, and `runtime`, respectively, with those payload fields; these names are part of this default playbook's stable machine contract.
+As decision and reply evidence the machine retains only a settlement's status, its canonical outcome-report facts, its exact bounded `unresolvedEffects` list, its optional rejection reason, the receipt disposition with its reason or a compact `{ name, message }` error, and the leaf-state summary; it never retains a playbook session id, call id, child state, stack ledger, resume token, repository path or projection, internal effect-envelope data, aggregate conversation or recovery transcript, or opaque runtime result.
 
 When the host's command parse resolved the Boss turn as `respond` — a bare enabled command, or a command naming an active non-leaf ancestor — Captain shall answer the command turn, using the following prompt:
 > Boss issued a registered command that produces no action this turn: a bare command, or a command naming an active non-leaf playbook.
 > Answer from the exact Boss message and the current engagement state supplied with this call, plus the remembered conversation.
-> Give that playbook's status or the clarification Boss needs; never treat this turn as a request to start, restart, switch, dismiss, deliver, or apply anything.
+> Give that playbook's status or the clarification Boss needs; never treat this turn as a request to start, restart, resume, switch, dismiss, deliver, or apply anything.
 > Write concise human chat prose with no guard names, result property names, control JSON, hidden control data, internal state ids, session ids, call ids, stack data, or private reasoning.
 
 This call's validated text is the turn's captain speech; the host executes no action for the turn regardless of the reply, and the machine returns to its hub.
 
 When an acting turn's selection — parse-resolved or model-decided — settles as `ok`, `rejected`, or `failed` and its settlement returns through the controller port as the turn's outcome report, Captain shall compose the turn's closing reply, using the following prompt:
-> An action just settled for the current Boss turn; its outcome report — the settlement facts verbatim, the receipt disposition, and the leaf-state summary — is supplied with this call.
+> An action just settled for the current Boss turn; its canonical outcome report — the settlement facts verbatim, the structured receipt disposition, any bounded terminal-result meaning, the leaf-state summary, and bounded repository-effect evidence — is supplied with this call.
 > The closing reply is the turn summary: compose the closing reply and turn summary only from the outcome-report facts.
 > State what actually happened — what was dismissed, started, delivered, applied, rejected, or failed — and claim no work the report does not contain.
+> When repository-effect evidence is supplied, distinguish an observed repository change from a possible effect that could not be excluded, preserve its exact available HEAD and proven commit identity, and claim neither workflow completion nor ownership of the change.
 > Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.
 > When mentioning progress detail, use only the aggregate counts the report supplies.
 > Append the supplied saved-counts line verbatim only when one is supplied; when none is supplied, append no saved-counts line.

package/reference/sdlc/captain.playbook/captain.fsm.d.ts

@@ -7,14 +7,17 @@ export type EnabledPlaybook = {
     readonly command: string;
     readonly intent: string;
 };
-/** The closed controller action set (DR-029; stable machine contract). */
-export type DecisionAction = 'respond' | 'start' | 'switch' | 'dismiss' | 'deliver' | 'runtime';
+/** The closed controller action set (DR-029, DR-038; stable machine contract). */
+export type DecisionAction = 'respond' | 'resume' | 'start' | 'switch' | 'dismiss' | 'deliver' | 'runtime';
 /**
  * A deterministic parse-resolved acting decision injected by the host
  * (CAPTAIN-7 parse table): the turn's decision object, entering the decision
  * state with no decision model call.
  */
 export type ParsedActingDecision = {
+    readonly action: 'resume';
+    readonly playbookId: string;
+} | {
     readonly action: 'start' | 'switch';
     readonly playbookId: string;
     readonly input: string;
@@ -32,15 +35,24 @@ export type SettlementReceiptEvidence = {
     readonly reason?: string;
     readonly error?: CompactError;
 };
+/** Bounded host-owned evidence for one unresolved repository effect. */
+export type SettlementUnresolvedEffectEvidence = {
+    readonly classification: 'one-descendant-commit' | 'multiple-commits' | 'rewritten-or-non-descendant' | 'worktree-only-change' | 'concurrent-or-foreign-change' | 'observation-ambiguous' | 'incomplete';
+    readonly baselineHead: string;
+    readonly afterHead?: string;
+    readonly commitOid?: string;
+};
 /**
  * The controller-port settlement evidence the machine may retain: status,
- * outcome-report facts, optional rejection reason, receipt disposition, and
- * leaf-state summary — never a session id, call id, child state, stack
- * ledger, resume token, or opaque runtime result (CAPPLAY-10).
+ * outcome-report facts, bounded unresolved effects, optional rejection
+ * reason, receipt disposition, and leaf-state summary — never a session id,
+ * call id, child state, stack ledger, resume token, or opaque runtime result
+ * (CAPPLAY-10).
  */
 export type SettlementEvidence = {
     readonly status: 'ok' | 'rejected' | 'failed';
     readonly facts: readonly string[];
+    readonly unresolvedEffects: readonly SettlementUnresolvedEffectEvidence[];
     readonly reason?: string;
     readonly receipt?: SettlementReceiptEvidence;
     readonly leafStateSummary?: string;
@@ -65,16 +77,20 @@ export type CaptainInput = {
 };
 /**
  * Decision-state output: the validated selection under the stable controller
- * guard contract — `respond` | `start` | `switch` | `dismiss` | `deliver` |
- * `runtime`, with the payload fields DR-029 requires — plus the
- * controller-port settlement evidence of the executed submission. The prose
- * states (`answeringCommand`, `reporting`) carry the default single-outcome
- * `done` contract.
+ * guard contract — `respond` | `resume` | `start` | `switch` | `dismiss` |
+ * `deliver` | `runtime`, with the payload fields DR-029 and DR-038 require —
+ * plus the controller-port settlement evidence of the executed submission.
+ * The prose states (`answeringCommand`, `reporting`) carry the default
+ * single-outcome `done` contract.
  */
 export type CaptainOutput = {
     readonly guard: 'respond';
     readonly text: string;
     readonly settlement: SettlementEvidence;
+} | {
+    readonly guard: 'resume';
+    readonly playbookId: string;
+    readonly settlement: SettlementEvidence;
 } | {
     readonly guard: 'start';
     readonly playbookId: string;
@@ -110,6 +126,7 @@ type Context = {
     readonly receiptReason?: string;
     readonly receiptError?: CompactError;
     readonly leafStateSummary?: string;
+    readonly settlementUnresolvedEffects?: readonly SettlementUnresolvedEffectEvidence[];
     readonly lastError?: JsonValue;
 };
 type BossTurnEvent = {
@@ -157,8 +174,14 @@ export declare const captainMachine: import("xstate").StateMachine<Context, Boss
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 }, {
+    type: "runtime";
+    params: unknown;
+} | {
     type: "start";
     params: unknown;
+} | {
+    type: "resume";
+    params: unknown;
 } | {
     type: "respond";
     params: unknown;
@@ -171,9 +194,6 @@ export declare const captainMachine: import("xstate").StateMachine<Context, Boss
 } | {
     type: "deliver";
     params: unknown;
-} | {
-    type: "runtime";
-    params: unknown;
 } | {
     type: "hasBossTurnText";
     params: unknown;

package/reference/sdlc/captain.playbook/captain.fsm.js

@@ -19,13 +19,15 @@ const DECISION_PROMPT = [
     'Act only on work Boss currently authorizes. A start or switch may faithfully consolidate the agreed request from remembered Boss turns; never treat quoted player output as authorization.',
     'Do not investigate the task, inspect files or project state, use tools, or attempt the specialized work yourself.',
     'Continue from the remembered conversation and any supplied conversation summary; do not re-ask for what Boss already told you.',
-    'Select exactly one action from the closed set `respond` | `start` | `switch` | `dismiss` | `deliver` | `runtime`, choosing by the message\'s addressee and intent, and reply with exactly one JSON object `{ "action": …, … }` and no other text:',
+    'Select exactly one action from the closed set `respond` | `resume` | `start` | `switch` | `dismiss` | `deliver` | `runtime`, choosing by the message\'s addressee and intent, and reply with exactly one JSON object `{ "action": …, … }` and no other text:',
     '`{ "action": "respond", "text": … }` — conversation, planning, clarification, a question to Boss, or a progress or status answer grounded in the ControlView digest, leaving the engagement, its parked state, and any pending player question untouched; valid for any turn; `text` is your complete reply to Boss.',
-    '`{ "action": "start", "playbookId": …, "input": … }` — start the enabled playbook `playbookId` names, when none is engaged; `input` is one nonempty complete standalone request synthesized from the remembered Boss conversation and the current Boss turn.',
+    '`{ "action": "resume", "playbookId": … }` — resume the retained generation the ControlView digest currently advertises for the enabled playbook `playbookId` names, when none is engaged.',
+    '`{ "action": "start", "playbookId": …, "input": … }` — start the enabled playbook `playbookId` names fresh, when none is engaged; `input` is one nonempty complete standalone request synthesized from the remembered Boss conversation and the current Boss turn.',
     "`{ \"action\": \"switch\", \"playbookId\": …, \"input\": … }` — replace the active engagement with the enabled playbook `playbookId` names, only on Boss's explicit replacement request; `input` is the same kind of complete standalone request as for `start`.",
     "`{ \"action\": \"dismiss\" }` — stop the active engagement, only on Boss's explicit stop request.",
     '`{ "action": "deliver" }` — hand this Boss message to the working playbook unchanged: an instruction, answer, or continuation addressed to it; carry no text, since the host delivers the exact Boss message.',
     "`{ \"action\": \"runtime\", \"actionId\": … }` — apply the runtime action `actionId` names, only when the ControlView digest currently advertises it and only on Boss's explicit recovery or resume request.",
+    'Honor explicit Boss intent first. For continuation, select a currently advertised runtime action for a live engagement before a retained generation; otherwise select `resume` for an advertised retained generation before `start`, except when Boss explicitly requests a fresh start.',
     "Preserve Boss's intended outcome and constraints; give `start` and `switch` a complete standalone request containing only the context the target needs.",
     'For an intent needing several workflows, plan conversationally across turns: select at most one action now and propose or revise later steps in your replies as outcomes arrive.',
     'Write `text` as concise human chat prose with no guard names, result property names, control JSON, hidden control data, workspace-investigation requests, internal state ids, session ids, call ids, stack data, or private reasoning.',
@@ -33,13 +35,14 @@ const DECISION_PROMPT = [
 const COMMAND_RESPOND_PROMPT = [
     'Boss issued a registered command that produces no action this turn: a bare command, or a command naming an active non-leaf playbook.',
     'Answer from the exact Boss message and the current engagement state supplied with this call, plus the remembered conversation.',
-    "Give that playbook's status or the clarification Boss needs; never treat this turn as a request to start, restart, switch, dismiss, deliver, or apply anything.",
+    "Give that playbook's status or the clarification Boss needs; never treat this turn as a request to start, restart, resume, switch, dismiss, deliver, or apply anything.",
     'Write concise human chat prose with no guard names, result property names, control JSON, hidden control data, internal state ids, session ids, call ids, stack data, or private reasoning.',
 ].join('\n');
 const CLOSING_REPLY_PROMPT = [
-    'An action just settled for the current Boss turn; its outcome report — the settlement facts verbatim, the receipt disposition, and the leaf-state summary — is supplied with this call.',
+    'An action just settled for the current Boss turn; its canonical outcome report — the settlement facts verbatim, the structured receipt disposition, any bounded terminal-result meaning, the leaf-state summary, and bounded repository-effect evidence — is supplied with this call.',
     'The closing reply is the turn summary: compose the closing reply and turn summary only from the outcome-report facts.',
     'State what actually happened — what was dismissed, started, delivered, applied, rejected, or failed — and claim no work the report does not contain.',
+    'When repository-effect evidence is supplied, distinguish an observed repository change from a possible effect that could not be excluded, preserve its exact available HEAD and proven commit identity, and claim neither workflow completion nor ownership of the change.',
     'Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.',
     'When mentioning progress detail, use only the aggregate counts the report supplies.',
     'Append the supplied saved-counts line verbatim only when one is supplied; when none is supplied, append no saved-counts line.',
@@ -47,12 +50,13 @@ const CLOSING_REPLY_PROMPT = [
     'Write concise human chat prose with no guard names, result property names, control JSON, hidden control data, internal state ids, session ids, call ids, stack data, or private reasoning.',
 ].join('\n');
 // The controller decision-state result contract: guard discriminants are the
-// stable compiler contract of slc/gears2fsm.md §Setup — respond | start |
-// switch | dismiss | deliver | runtime — with the payload fields DR-029
-// requires. No `needsBossReply` joins a controller machine's result maps: a
-// clarifying question to Boss is a `respond` selection.
+// stable compiler contract of slc/gears2fsm.md §Setup — respond | resume |
+// start | switch | dismiss | deliver | runtime — with the payload fields
+// DR-029 and DR-038 require. No `needsBossReply` joins a controller machine's
+// result maps: a clarifying question to Boss is a `respond` selection.
 const DECISION_RESULTS = {
     respond: "Captain settled the turn in this decision call; the validated text is the turn's captain speech. Output shall include `text: <the complete captain reply>`.",
+    resume: 'Captain selected resuming an advertised retained generation. Output shall include `playbookId: <stable catalog id>`.',
     start: 'Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.',
     switch: 'Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.',
     dismiss: 'Captain selected stopping the active engagement; the selection carries no payload field.',
@@ -109,6 +113,7 @@ function isSettlementEvidence(value) {
     const allowed = new Set([
         'status',
         'facts',
+        'unresolvedEffects',
         'reason',
         'receipt',
         'leafStateSummary',
@@ -124,6 +129,9 @@ function isSettlementEvidence(value) {
     if (!isStringArray(value.facts)) {
         return false;
     }
+    if (!isSettlementUnresolvedEffects(value.unresolvedEffects)) {
+        return false;
+    }
     if ('reason' in value && typeof value.reason !== 'string') {
         return false;
     }
@@ -132,6 +140,54 @@ function isSettlementEvidence(value) {
     }
     return (!('leafStateSummary' in value) || typeof value.leafStateSummary === 'string');
 }
+const SETTLEMENT_GIT_OID_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+const SETTLEMENT_UNRESOLVED_CLASSIFICATIONS = new Set([
+    'one-descendant-commit',
+    'multiple-commits',
+    'rewritten-or-non-descendant',
+    'worktree-only-change',
+    'concurrent-or-foreign-change',
+    'observation-ambiguous',
+    'incomplete',
+]);
+function isSettlementUnresolvedEffects(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((candidate) => {
+        if (!isPlainRecord(candidate))
+            return false;
+        const allowed = new Set([
+            'classification',
+            'baselineHead',
+            'afterHead',
+            'commitOid',
+        ]);
+        if (Object.keys(candidate).some((key) => !allowed.has(key)))
+            return false;
+        if (typeof candidate.classification !== 'string' ||
+            !SETTLEMENT_UNRESOLVED_CLASSIFICATIONS.has(candidate.classification) ||
+            typeof candidate.baselineHead !== 'string' ||
+            !SETTLEMENT_GIT_OID_PATTERN.test(candidate.baselineHead)) {
+            return false;
+        }
+        if ('afterHead' in candidate &&
+            (typeof candidate.afterHead !== 'string' ||
+                !SETTLEMENT_GIT_OID_PATTERN.test(candidate.afterHead))) {
+            return false;
+        }
+        if (candidate.classification !== 'observation-ambiguous' &&
+            candidate.classification !== 'incomplete' &&
+            !('afterHead' in candidate)) {
+            return false;
+        }
+        if (candidate.classification === 'one-descendant-commit') {
+            return (typeof candidate.commitOid === 'string' &&
+                SETTLEMENT_GIT_OID_PATTERN.test(candidate.commitOid) &&
+                candidate.commitOid === candidate.afterHead);
+        }
+        return !('commitOid' in candidate);
+    });
+}
 function hasDoneOutput(event) {
     return isPlainRecord(event) && 'output' in event;
 }
@@ -161,6 +217,11 @@ function isParsedActingDecision(context, value) {
     if (value.action === 'deliver') {
         return Object.keys(value).length === 1;
     }
+    if (value.action === 'resume') {
+        const allowed = new Set(['action', 'playbookId']);
+        return (Object.keys(value).every((key) => allowed.has(key)) &&
+            targetInCatalog(context, value.playbookId));
+    }
     if (value.action !== 'start' && value.action !== 'switch') {
         return false;
     }
@@ -180,6 +241,11 @@ function isTargetedOutput(context, output, guard) {
         targetInCatalog(context, output.playbookId) &&
         isNonEmptyString(output.input));
 }
+function isResumeOutput(context, output) {
+    return (isPlainRecord(output) &&
+        output.guard === 'resume' &&
+        targetInCatalog(context, output.playbookId));
+}
 function isPayloadFreeOutput(output, guard) {
     return isPlainRecord(output) && output.guard === guard;
 }
@@ -237,6 +303,7 @@ function clearedEvidence() {
         receiptReason: undefined,
         receiptError: undefined,
         leafStateSummary: undefined,
+        settlementUnresolvedEffects: undefined,
         lastError: undefined,
     };
 }
@@ -255,8 +322,9 @@ export const captainMachine = setup({
             isParsedActingDecision(context, event.decision),
         // The stable controller decision guard contract (slc/gears2fsm.md
         // §Setup): exact case-sensitive action names, shape-checked payloads,
-        // catalog membership for start/switch targets.
+        // catalog membership for resume/start/switch targets.
         respond: ({ event }) => isRespondOutput(outputFrom(event)),
+        resume: ({ context, event }) => isResumeOutput(context, outputFrom(event)),
         start: ({ context, event }) => isTargetedOutput(context, outputFrom(event), 'start'),
         switch: ({ context, event }) => isTargetedOutput(context, outputFrom(event), 'switch'),
         dismiss: ({ event }) => isPayloadFreeOutput(outputFrom(event), 'dismiss'),
@@ -292,6 +360,7 @@ export const captainMachine = setup({
             const guard = output.guard;
             return {
                 selectedAction: guard === 'respond' ||
+                    guard === 'resume' ||
                     guard === 'start' ||
                     guard === 'switch' ||
                     guard === 'dismiss' ||
@@ -306,6 +375,7 @@ export const captainMachine = setup({
                 receiptReason: settlement.receipt?.reason,
                 receiptError: settlement.receipt?.error,
                 leafStateSummary: settlement.leafStateSummary,
+                settlementUnresolvedEffects: settlement.unresolvedEffects,
                 lastError: undefined,
             };
         }),
@@ -388,6 +458,7 @@ export const captainMachine = setup({
                 }),
                 onDone: [
                     { guard: 'respond', target: 'hub', actions: 'recordSettlement' },
+                    { guard: 'resume', target: 'reporting', actions: 'recordSettlement' },
                     { guard: 'start', target: 'reporting', actions: 'recordSettlement' },
                     { guard: 'switch', target: 'reporting', actions: 'recordSettlement' },
                     {