@sublang/playbook 10.0.0 → 11.0.0

package/README.md

@@ -63,7 +63,7 @@ playbook
 Type a task, enter `/code <task>` for implementation, or enter
 `/decide <question>` for an independently proposed and reviewed decision.
 
-On first launch, Playbook writes its config to `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`.
+On first launch, Playbook writes its config to `${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml`. A config left at the former `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` is moved there on the next launch, unless a relative primary locator would change targets; that case is rejected unchanged with absolute replacements.
 
 The same config, compiled Captain, enabled playbooks, stable players, and
 nested calls power headless turns. Both front ends create the same durable

package/docs/cli.md

@@ -188,7 +188,7 @@ The former positional `<from>`, `resume`, `--player`, `--captain`,
 `--option`, `--cwd`, `--last`, run-only `--config`, and top-level `run:`
 config are removed from `playbook run`. Enable a registry under `playbooks`,
 declare provider agents once under top-level `players`, bind every local role
-under `playbooks.<id>.roles`, tune compatible model and effort in a `--with`
+under `playbooks.<id>.roles`, tune compatible model, effort, and fast mode in a `--with`
 overlay, invoke the effective `/command`, and run from the working directory
 you want agents to use. Legacy `playbooks.<id>.players` blocks are rejected and
 are not auto-migrated because choosing equal or distinct new player IDs chooses
@@ -231,12 +231,13 @@ module's directory is a git repository, add `node_modules/` to its
 
 ### Continuing a Captain session
 
-Interactive and headless commands write the same logical-session records under
-`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`. A fresh interactive
-child persists turn zero before printing `playbook: session <id>` and opening
-Boss input; a fresh headless turn returns the same kind of ID in `--json`.
-After the current writer exits or explicitly hands off, either presentation
-can reopen either origin:
+Interactive and headless commands write the same logical-session records in
+the configured [`sessions` directory](configuration.md#session-storage), whose
+default is `${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`. A fresh
+interactive child persists turn zero before printing `playbook: session <id>`
+and opening Boss input; a fresh headless turn returns the same kind of ID in
+`--json`. After the current writer exits or explicitly hands off, either
+presentation can reopen either origin:
 
 ```sh
 # Reopen the newest session stored for this working directory headlessly:
@@ -265,13 +266,56 @@ competing front end fails closed instead of forking the history.
 An ordinary reopen reads current config and any opening `--with` fragments,
 projects them to the stored catalog and player roster, and requires the stored
 role bindings plus every structural setting to remain exact. Compatible
-current `model` and `effort` selections apply to the next call, including an
-explicit boolean `false` provider-default reset. The retained provider token
-is never silently replaced by a fresh conversation if that selection is not
-supported
+current `model`, `effort`, and optional `fastMode` settings apply to the next
+call. Boolean `false` explicitly resets model or effort to the provider
+default, but `fastMode: false` is a literal disabled request; omission selects
+the fast-mode provider default or inherits the player value at a role binding.
+The retained provider token is never silently replaced by a fresh conversation
+if a requested setting is not 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)).
 
+### Following replay history
+
+Beside each `<session-id>.json` manifest, both front ends tee every observed
+host record in order to `<session-id>.records.jsonl`. Each complete line is a
+version-1 envelope with a writer-assigned sequence contiguous from `1`, the
+opaque record, and an optional local playbook role where the trace establishes
+one unambiguously. The stream is a mode-`0600` regular non-symlink file inside
+the private sessions directory. Readers consume only the complete
+newline-terminated prefix; a final partial line is not presented as a record.
+
+The replay projection recursively removes provider `resumeToken` fields and
+string-valued `resume` selections while preserving `resume: false`. It is
+therefore useful for following and presentation, but it cannot resume an agent
+conversation and does not replace the private canonical manifest. External
+hosts can follow this stream without taking the writer lease through the
+published [`@sublang/playbook/session-store`
+facade](embedding.md#sharing-the-cli-session-store).
+
+Streams are unbounded in this version: neither front end prunes them, and
+retention remains tied to the deferred session-deletion policy. Removing
+provider credentials does not make the remaining replay content non-sensitive;
+protect the prompts, replies, tool calls, events, and timestamps it contains as
+sensitive session data.
+
+Replay recording is fail-soft after the canonical session lease is valid. If
+initialization, sanitization, append, repair, publication synchronization, or a
+checkpoint fails, recording stops for that lease without changing the agent
+turn, durable session settlement, reply, or exit outcome. The headless command
+attempts this warning once on stderr:
+
+```text
+playbook run: warning: replay history for session "<session-id>" may be incomplete; recording has stopped
+```
+
+The interactive child instead presents one Captain status with the same
+`warning: replay history ...` text and writes no raw stderr diagnostic. A later
+lease gets its own warning only if its replay writer independently becomes
+incomplete. The public facade emits no warning; an embedding host decides how
+to present the `incomplete` status it receives
+([[playbook-cli-84](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-84)]).
+
 ### Reconciling possible repository effects
 
 For each governed player call, Playbook records a Git baseline before the call
@@ -307,8 +351,9 @@ playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --discard-uncertain
 ```
 
 Retry reads no input and reuses the byte-exact recorded turn and its exact
-attempted Captain, player, and per-role model/effort selections; current config
-cannot retune that attempt, and retry may duplicate external effects. Discard
+attempted Captain, player, and per-role model, effort, and fast-mode settings;
+current config 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

package/docs/configuration.md

@@ -4,22 +4,35 @@
 # Configuring agents
 
 Fresh launches and ordinary reopens read one config at
-`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`. The
+`${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml`. The
 first launch seeds it from the bundled starter and prints the path;
 later launches reuse it untouched.
 
+On the first launching command after upgrading Playbook, it moves a config from the
+former `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` path
+when the canonical path is absent. The one-time move preserves bytes and
+permissions and leaves no compatibility alias, so running an older Spex host
+afterward could seed a second file at the former path.
+
+The current guard rejects relocation when a legacy relative `sessions` value
+or relative filesystem `playbooks.<id>.from` would resolve differently below
+the new directory. It leaves the former file unchanged and names every
+target-preserving absolute replacement. Apply those replacements and retry;
+Playbook does not rewrite the user-authored file.
+
 ```sh
-$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
+$EDITOR "${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml"
 ```
 
 ## Anatomy
 
 The config is top-level (no `config:` wrapper): a `captain` agent, one flat
 `players` map of stable Captain-session agents, a `playbooks` map of enabled
-workflows and their explicit role bindings, and optional `layout` /
-`notifications` / `theme`. The Captain runs hidden control and judge calls and
-writes the replies you see in the Captain pane or on headless stdout. The three
-presentation fields apply only to interactive tmux; headless runs ignore them.
+workflows and their explicit role bindings, an optional `sessions` storage
+locator, and optional `layout` / `notifications` / `theme`. The Captain runs
+hidden control and judge calls and writes the replies you see in the Captain
+pane or on headless stdout. The three presentation fields apply only to
+interactive tmux; headless runs ignore them.
 
 A **role** is local to a playbook artifact: CODE's `coder` and REVIEW's `coder`
 have the same semantic name but remain separate declarations. A **player** is
@@ -29,11 +42,12 @@ names, nesting, and ancestry never infer a binding.
 
 Each `captain` or `players.<player-id>` value is either an adapter shorthand
 (`claude`, `codex`) or a block carrying that agent's own `adapter`, `model`,
-`effort`, `instruction`, and `permissions`. Settings are inline per stable
-agent ([DR-021](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/021-inline-agent-settings.md)). Dots in a
-player ID are literal characters, not YAML hierarchy. Other adapter IDs pass
-through to `tmux-play` with a warning because `playbook` cannot preflight their
-auth.
+`effort`, `fastMode`, `instruction`, and `permissions`. Settings are inline per
+stable agent
+([DR-021](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/021-inline-agent-settings.md)).
+Dots in a player ID are literal characters, not YAML hierarchy. Other adapter
+IDs pass through to `tmux-play` with a warning because `playbook` cannot
+preflight their auth.
 
 Within a `playbooks.<id>` block, `from` (the registry module), `command` (an
 optional slash-command override), and `roles` are launcher-owned; every other
@@ -41,34 +55,35 @@ key is that playbook's option slice. Every manifest role must be present
 exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
-The seeded config runs the stable Coder player on Claude Opus 4.8 1m and the
-stable Reviewer player on GPT-5.5:
+The seeded config runs the stable Coder player on GPT-5.6 Sol with fast mode
+enabled and the stable Reviewer player on Claude Opus 5:
 
 ```yaml
 captain:
   adapter: claude
-  model: claude-opus-4-8
+  model: claude-opus-5
   effort: high
   permissions:
     mode: auto # protected auto mode for the Claude Captain
 
 players:
   dev.coder:
-    adapter: claude
-    model: claude-opus-4-8[1m]
-    effort: xhigh
-    permissions:
-      mode: auto # protected auto mode for the Claude Coder
-
-  dev.reviewer:
     adapter: codex
-    model: gpt-5.5
-    effort: xhigh
+    model: gpt-5.6-sol
+    effort: ultra
+    fastMode: true
     permissions:
       mode: auto
       writablePaths:
         - .git # allow git metadata writes under Codex auto mode
 
+  dev.reviewer:
+    adapter: claude
+    model: claude-opus-5
+    effort: xhigh
+    permissions:
+      mode: auto # protected auto mode for the Claude Reviewer
+
 playbooks:
   code:
     from: '@sublang/playbook/code/registry'
@@ -104,21 +119,26 @@ roles:
   coder: dev.coder
 ```
 
-Use a block to override only that role invocation's model or effort:
+Use a block to override only that role invocation's model, effort, or fast
+mode:
 
 ```yaml
 roles:
   coder:
     player: dev.coder
-    model: claude-opus-4-8[1m]
+    model: gpt-5.6-sol
     effort: false # explicitly reset to this provider's default
+    fastMode: false # literal disabled request, not a default sentinel
 ```
 
-Omitting `model` or `effort` inherits that player's top-level default. The
-boolean `false` is different: it selects the provider default explicitly, so a
-resumed conversation cannot accidentally retain an earlier selection. A role
-binding cannot override adapter, instruction, permissions, workspace, or tool
-posture; those define the stable player envelope.
+Omitting any override inherits that player's top-level default. For `model`
+and `effort`, boolean `false` selects the provider default explicitly, so a
+resumed conversation cannot accidentally retain an earlier selection. For
+`fastMode`, `false` is a literal request to disable fast mode; omitting the
+top-level setting selects the provider default. A present fast-mode boolean is
+accepted only for adapters Cligent reports as supporting it. A role binding
+cannot override adapter, instruction, permissions, workspace, or tool posture;
+those define the stable player envelope.
 
 ## Sharing, isolation, and concurrency
 
@@ -136,9 +156,9 @@ second top-level player and change only its binding:
 ```yaml
 players:
   review.coder:
-    adapter: claude
-    model: claude-opus-4-8[1m]
-    effort: xhigh
+    adapter: codex
+    model: gpt-5.6-sol
+    effort: ultra
 
 playbooks:
   review:
@@ -183,8 +203,9 @@ playbook run --with fast-lineup.yaml "/code implement the approved change"
 # fast-lineup.yaml — retune the shared Coder; nothing is written back.
 players:
   dev.coder:
-    model: claude-opus-4-8
+    model: gpt-5.6-sol
     effort: medium
+    fastMode: false
 ```
 
 Fragments merge into the agent block rather than replacing it, so
@@ -207,9 +228,37 @@ The global file is never modified, and `--with` is not forwarded to
 Overlays apply when creating a fresh session and as current-config input for a
 compatible ordinary reopen. A selected session keeps its stored catalog,
 player roster, role bindings, adapter, instruction, permissions, and working
-directory; only model and effort may change. The next call reapplies both
-complete selections. An uncertain retry accepts no tuning overlay and uses the
-exact attempted selections already stored with that turn.
+directory; only model, effort, and fast mode may change. The next call reapplies
+both complete model and effort selections and the optional effective fast-mode
+boolean. An uncertain retry accepts no tuning overlay and uses the exact
+attempted settings already stored with that turn.
+
+## Session storage
+
+Both front ends select canonical session manifests and write replay streams in
+one directory, where external hosts may keep their own sidecars too. Set the
+optional top-level `sessions` key to move that shared store:
+
+```yaml
+sessions: ./state/playbook-sessions
+```
+
+The value must be a nonempty filesystem path. When the key is absent, the
+directory is
+`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions`. An absolute path is
+used as given; `~` and `~/...` expand from the home directory, while `~user`
+is rejected. Every other value, including a bare relative path such as the one
+above, resolves against the primary config file's directory rather than the
+invocation directory. A `sessions` value in a `--with` overlay replaces the
+primary value, with later overlays winning.
+
+Launch validates that the resolved path can serve as the mode-`0700`, real,
+non-symlink session store before selecting a record or starting agent work and
+fails closed when it cannot. The non-launching `playbook --list` command still
+validates the locator's syntax but does not inspect that directory's filesystem
+usability. The resolved locator is launch configuration only: it never enters
+a persisted structural or execution projection
+([[playbook-cli-78](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-78)]).
 
 ## Durable shared configuration
 
@@ -223,9 +272,9 @@ public UUID. Presentation-only fields are inert headlessly.
 An ordinary reopen reads current config and opening overlays, but first
 projects them to the stored playbooks and referenced players. An unrelated new
 entry cannot enter or invalidate the session. Structural drift fails closed;
-compatible model or effort changes apply on the next provider call. Legacy
-record, shell, runtime-snapshot, and trace schemas are rejected rather than
-having role or player identity guessed.
+compatible model, effort, or fast-mode changes apply on the next provider
+call. Legacy record, shell, runtime-snapshot, and trace schemas are rejected
+rather than having role or player identity guessed.
 
 ## External playbooks
 

package/docs/embedding.md

@@ -220,6 +220,94 @@ 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.
 
+## Sharing the CLI session store
+
+An external host that needs the CLI's canonical session validation and
+token-free replay format can use the narrow, semver-stable
+`@sublang/playbook/session-store` facade. It shares the CLI's private store and
+validators by construction but exposes no canonical manifest, snapshot,
+provider credential, effect ledger, recovery operation, or turn-lifecycle
+operation:
+
+```ts
+import {
+  defaultSessionsDir,
+  openSessionStore,
+} from '@sublang/playbook/session-store';
+
+const store = openSessionStore(defaultSessionsDir());
+const { sessions, skipped } = await store.list();
+
+const sessionId = sessions[0]?.sessionId;
+if (sessionId !== undefined) {
+  const summary = await store.read(sessionId);
+  console.log(summary.sessionId, summary.state, summary.cwd);
+
+  const first = await store.readStream(sessionId);
+  const next = await store.readStream(sessionId, {
+    afterSeq: first.lastReadableSeq,
+  });
+  console.log(next.entries, skipped);
+}
+```
+
+`list()` reports valid summaries and separately reports skipped canonical
+manifests with their validation or cutover reason. A summary has exactly
+`schemaVersion`, `sessionId`, `state`, `cwd`, and `updatedAt`. A lease-free
+`readStream()` returns complete envelopes and `lastReadableSeq` only: it makes
+no claim that another process has durably checkpointed the observed bytes or
+that its live writer remains complete. An absent stream reads as empty, and
+acquiring its lease does not require a manifest; only `read()` requires a
+canonical session summary. Pass an absolute path to `openSessionStore()` when
+using a directory other than the environment-derived default.
+
+Writing requires the one exclusive session lease. The writer assigns envelope
+version and sequence, serializes overlapping appends in invocation order, and
+strips provider resume credentials from every accepted record:
+
+```ts
+const lease = await store.acquire(
+  '4f2c0000-0000-4000-8000-000000009ab1',
+);
+try {
+  await lease.append({ type: 'host_notice', message: 'attached' });
+  const status = lease.streamStatus();
+  console.log(status);
+  if (status.lastReadableSeq !== null) {
+    const replay = await lease.readStream();
+    console.log(replay.lastReadableSeq, replay.lastDurableSeq);
+  }
+} finally {
+  const finalStatus = await lease.release();
+  console.log(finalStatus);
+}
+```
+
+`streamStatus()` synchronously returns the current live status. If initialization
+could not establish a trustworthy whole-stream boundary, it returns
+`{ lastReadableSeq: null, lastDurableSeq: null, incomplete: true }`, and
+`lease.readStream()` rejects rather than return partial history.
+An `append()` suppressed before release by either unavailable initialization or
+a numeric incomplete latch resolves `undefined` without recording the supplied
+record, so fulfillment alone does not prove persistence.
+
+Always release a successfully acquired lease. `release()` closes append
+admission, drains earlier appends, attempts the final checkpoint, retires the
+lease, and returns the final `lastReadableSeq`, `lastDurableSeq`, and
+`incomplete` status. A replay initialization failure reports unavailable null
+boundaries; a later sanitization, repair, or persistence failure latches
+numeric `incomplete` status. Either state suppresses later replay work on that
+lease and remains isolated from canonical session lifecycle work. The facade
+writes no warning to stdout or stderr; the embedding host owns any presentation
+of that status.
+
+For control flow, a missing canonical manifest from `read()` uses
+`Error.code === 'PLAYBOOK_SESSION_NOT_FOUND'`, and a competing live or foreign
+lease uses `Error.code === 'PLAYBOOK_SESSION_LEASE_ACTIVE'`. Do not match error
+messages or assume those codes for malformed input, unsafe storage, an
+indeterminate owner probe, or another storage failure
+([[playbook-cli-73](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-73)]).
+
 See
 [`code.playbook.test.ts`](https://github.com/sublang-ai/playbook/blob/main/reference/sdlc/code.playbook/code.playbook.test.ts)
 for the full range of port shapes (classifier, judge, abort, interrupt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "10.0.0",
+  "version": "11.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",
@@ -67,12 +67,15 @@
     "reference/sdlc/code.playbook/playbook-captain.ts",
     "reference/sdlc/code.playbook/playbook-captain.js",
     "reference/sdlc/code.playbook/playbook-captain.d.ts",
+    "reference/sdlc/code.playbook/session-store.js",
+    "reference/sdlc/code.playbook/session-store.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "reference/sdlc/code.playbook/bin/playbook.js",
     "reference/sdlc/code.playbook/bin/launch-config.js",
     "reference/sdlc/code.playbook/bin/run.js",
     "reference/sdlc/code.playbook/bin/interactive-session.js",
+    "reference/sdlc/code.playbook/bin/replay-observer.js",
     "reference/sdlc/code.playbook/bin/session-store.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
@@ -127,6 +130,10 @@
       "types": "./reference/sdlc/code.playbook/playbook-captain.d.ts",
       "default": "./reference/sdlc/code.playbook/playbook-captain.js"
     },
+    "./session-store": {
+      "types": "./reference/sdlc/code.playbook/session-store.d.ts",
+      "default": "./reference/sdlc/code.playbook/session-store.js"
+    },
     "./slc/*": "./slc/*",
     "./review/playbook": {
       "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",
@@ -158,7 +165,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.23.0",
+    "@sublang/cligent": "^0.24.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/code.md

@@ -8,35 +8,44 @@ Roles:
 
 - Coder
 
-The caller supplies the coding intent including any specific context.
+The caller supplies a coding request together with any relevant context.
 
-A coding intent follows either one direct implementation phase or an IR sequence consisting of a new-IR phase and one phase for each IR task.
+A new coding intent follows either one direct implementation phase or an IR sequence consisting of a new-IR phase followed by one phase for each IR task.
+An existing IR follows one IR-task phase for each remaining unfinished task, starting with its next unfinished task.
 Each phase ends with one new Coder commit (owned by `code`).
 After each `code`-owned commit, Captain shall call the `review` playbook and wait until it passes with no unsettled findings.
 Playbook `review` owns every review round and every review-fix commit.
-Do not amend any reviewed commit.
+Do not rewrite any existing commit.
 
 When `review` passes a direct implementation phase, `code` is complete.
 When `review` passes a new IR or a nonfinal IR-task phase, Captain shall continue with the next unfinished IR-task phase.
 When `review` passes the final IR-task phase, `code` is complete.
-When `review` returns an authored abort or failure, or a terminal result that does not prove exact approval, `code` shall start no further phase and shall report the failure and the last `code`-owned commit to its caller.
+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` shall start no further phase and shall report the failure and the last `code`-owned commit to its caller.
 When the nested `review` call fails outside that authored result contract, `code` shall park as failed and retain the control-plane error instead of reporting an authored review outcome.
 
 At the start of the first phase, Captain shall relay to Coder the complete caller input and any relevant run results in quotes (`>`), along with the following instruction:
 
 ```markdown
-Assess whether the coding intent can be completed well in one commit.
-If yes, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.
-Otherwise, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.
+First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.
+If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.
+
+For a new coding intent, assess whether it can be completed well in one commit.
+If it can, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.
+If it cannot, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.
 Plan affected spec updates before, with, or after their corresponding code changes, either as standalone IR tasks or as explicit work within related tasks.
 
+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.
+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.
 ```
 
-At the start of every IR-task phase, Captain shall relay to Coder the exact next task and any relevant run results in quotes (`>`), along with the following instruction:
+At the start of every later IR-task phase, Captain shall relay to Coder the original caller input, the IR identity, and any relevant run results in quotes (`>`), along with the following instruction:
 
 ```markdown
-Read IR-<#> and implement exactly the next unfinished task, including corresponding tests or specs if any.
+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.
 If the IR will be finished after this phase, double-check that all acceptance criteria are met.
@@ -45,18 +54,29 @@ If the IR will be finished after this phase, double-check that all acceptance cr
 At the start of *every* phase, Captain shall append the following instruction:
 
 ```markdown
+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.
 Make the commit message explain concisely what changed and why, including relevant verification.
-Coder is <coder-llm>; format the model token in conventional human form.
+Identify every new commit you make.
+Coder is <coder-llm>.
 ```
 
-After the first phase (either direct implementation or a new-IR phase), Captain shall call playbook `review` and input the following in quotes (`>`):
+Every new-intent phase has two semantic outcomes: direct implementation and new IR; the new-IR outcome identifies the created IR.
+Every IR-task phase, including the first phase for an existing IR, identifies the IR and the implemented task, and has two semantic outcomes: more tasks and final task.
+The first phase therefore has four semantic outcomes — direct implementation, new IR, more tasks, and final task — plus the Boss question when the continued IR is ambiguous.
+Each semantic outcome requires affirmative support in Coder's result, but no phase transition shall depend on a fixed presentation format of Coder's reply.
+Captain shall use the repository-effect receipt as the authoritative identity of the phase's new commit.
+
+At the end of every phase, Captain shall call playbook `review` and input the following in quotes (`>`):
 
-> Initial intent: \<caller-input\>
+> Original intent: \<caller-input\>
+> Review scope: the commit \<code-commit\> from this coding phase and its resulting repository state.
 > Coder output: \<coder-output\>
 
-After every IR-task phase, Captain shall call playbook `review` and input the following in quotes (`>`):
+For an IR-task phase, Captain shall additionally input the following in quotes (`>`):
 
-> IR task: \<ir-task\>
-> Coder output: \<coder-output\>
+> 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 successful completion, `code` returns 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.