@sublang/playbook 6.0.0 → 8.0.0

package/docs/configuration.md

@@ -3,7 +3,7 @@
 
 # Configuring agents
 
-`playbook` reads one config at
+Fresh launches and ordinary reopens read one config at
 `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`. The
 first launch seeds it from the bundled starter and prints the path;
 later launches reuse it untouched.
@@ -14,27 +14,35 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
 
 ## Anatomy
 
-The config is top-level (no `config:` wrapper): a `captain` agent (it
-runs the session Captain's hidden control calls, the hidden judge calls,
-and the replies you see in the Captain pane), optional
-`layout` / `notifications` / `theme`, and a `playbooks` map of enabled
-playbooks.
-
-Each `captain` or `players.<role>` value is either an adapter shorthand
-(`claude`, `codex`) or a block carrying that agent's own `adapter`,
-`model`, `effort`, and `permissions`. Settings are inline per agent, so
-tuning one player never changes another
-([DR-021](../specs/decisions/021-inline-agent-settings.md)). 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 `players` are launcher-owned;
-every other key is that playbook's option slice. The launcher injects
-the rest — you do not write host wiring by hand.
-
-The seeded config runs each Coder on Claude Opus 4.8 1m and each
-Reviewer on GPT-5.5:
+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.
+
+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
+a stable session-wide provider conversation with an exact ID such as
+`dev.coder`. A role uses only the player named by its binding; matching role
+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](../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
+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:
 
 ```yaml
 captain:
@@ -44,86 +52,116 @@ captain:
   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
+    permissions:
+      mode: auto
+      writablePaths:
+        - .git # allow git metadata writes under Codex auto mode
+
 playbooks:
   code:
     from: '@sublang/playbook/code/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto # protected auto mode for the Claude Coder
+    roles:
+      coder: dev.coder
 
   review:
     from: '@sublang/playbook/review/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths:
-            - .git # allow git metadata writes under Codex auto mode
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
 
   decide:
     from: '@sublang/playbook/decide/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths:
-            - .git
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
 ```
 
 The current bundled workflows accept no workflow-specific options.
-Each role's per-run prompt names its pinned `model`, else its `adapter`
+Each role's per-call prompt names its current `model`, else its player's
+`adapter`
 ([[playbook-runtime-4](../specs/packages/playbook-runtime.md#playbook-runtime-4)]),
 so commit trailers credit the concrete model rather than the adapter
 family.
 
-## Nested roles and sessions
+## Role binding forms
+
+The shortest binding is a scalar stable player ID:
+
+```yaml
+roles:
+  coder: dev.coder
+```
+
+Use a block to override only that role invocation's model or effort:
+
+```yaml
+roles:
+  coder:
+    player: dev.coder
+    model: claude-opus-4-8[1m]
+    effort: false # explicitly reset to this provider's default
+```
+
+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.
+
+## Sharing, isolation, and concurrency
+
+Two bindings that name the same player ID deliberately share one sequential
+provider conversation throughout the logical Captain session — across nested
+calls, returns, and later root engagements. CODE's and REVIEW's `coder` roles
+therefore share `dev.coder` in the starter, and DECIDE and its nested REVIEW
+share both starter players. Disposal of one playbook frame does not clear that
+session ledger.
+
+Two distinct player IDs stay isolated even when their agent blocks are
+byte-for-byte equal. To give standalone REVIEW an independent Coder, define a
+second top-level player and change only its binding:
+
+```yaml
+players:
+  review.coder:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    effort: xhigh
 
-The launcher creates a namespaced fallback player for every configured
-playbook role, but a nested call maps an exact same-name role to the
-nearest ancestor's effective player and backend conversation. CODE's
-nested REVIEW therefore continues CODE's `coder` and uses REVIEW's
-configured `reviewer`; DECIDE's nested REVIEW continues both of
-DECIDE's roles. A standalone REVIEW starts with REVIEW's own configured
-players, and every new root engagement starts fresh
-([DR-030](../specs/decisions/030-shared-mapped-player-continuity.md)).
+playbooks:
+  review:
+    from: '@sublang/playbook/review/registry'
+    roles:
+      coder: review.coder
+      reviewer: dev.reviewer
+```
 
-The separate fallback entries are still required because tmux creates
-its roster at launch time. The host changes which existing panes are
-visible as the active nested leaf changes; it does not create a new
-host player or backend agent session for a mapped role.
+Roles a manifest may run concurrently must bind to distinct IDs. DECIDE's
+`coder` and `reviewer` are concurrent, so aliasing both to one player rejects
+before registry import, host creation, or agent work.
 
 ## Choosing the Captain agent
 
 Every session-Captain call and adjudication call is hidden and runs
 tool-free, which is what keeps the Captain deciding and reporting
-instead of doing the work itself. Claude enforces
-that at the provider level. The Codex adapter cannot — it rejects any
-tool list — so a `captain:` on `codex` falls back to a prompt-level
-restriction
+instead of doing the work itself. Claude and Gemini enforce that at the
+provider level. The Codex, Kimi, and OpenCode adapters cannot — they
+reject any tool list — so a `captain:` using one of them falls back to a
+prompt-level restriction
 ([DR-013](../specs/decisions/013-routing-only-captain-control.md) A1).
-Codex remains a good choice for *players*, where full tools are wanted.
+Those adapters remain good choices for *players*, where full tools are wanted.
 
 Adapter readiness is intentionally light: `claude` is ready with local
 Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
@@ -138,52 +176,152 @@ recursively, other values replace):
 
 ```sh
 playbook --with fast-lineup.yaml
+playbook run --with fast-lineup.yaml "/code implement the approved change"
 ```
 
 ```yaml
-# fast-lineup.yaml — swap the Coder for one run; nothing is written back.
+# fast-lineup.yaml — retune the shared Coder; nothing is written back.
+players:
+  dev.coder:
+    model: claude-opus-4-8
+    effort: medium
+```
+
+Fragments merge into the agent block rather than replacing it, so
+settings the base defines and the fragment omits — here the adapter,
+instruction, and permissions — survive. Retuning a top-level player affects
+every bound role that does not override that field. To retune only one role,
+overlay its binding instead:
+
+```yaml
 playbooks:
   code:
-    players:
+    roles:
       coder:
-        adapter: codex
-        model: gpt-5.5
-        effort: medium
-        permissions:
-          mode: auto
-          # CODE's Coder commits, so Codex needs the `.git` grant to write
-          # repository metadata.
-          writablePaths:
-            - .git
+        player: dev.coder
+        effort: low
 ```
 
-Fragments merge into the agent block rather than replacing it, so
-settings the base defines and the fragment omits — here `mode: auto` —
-survive. Anything the adapter itself requires must still be stated: a
-role switched to `codex` needs its own `writablePaths` grant, because
-the base Claude block had no reason to carry one.
-
 The global file is never modified, and `--with` is not forwarded to
 `tmux-play` ([[playbook-cli-25](../specs/packages/playbook-cli.md#playbook-cli-25)]).
+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.
+
+## Durable shared configuration
+
+Fresh interactive and headless sessions use the same top-level Captain,
+players, role bindings, and playbooks. Both persist the same logical-session
+record, shell snapshot, player ledger, normalized catalog, structural agent
+envelopes, last-applied tuning, and absolute working directory. A session
+created by either front end can reopen through either front end with the same
+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.
+
+## External playbooks
+
+`slc playbook my-workflow.md` emits `my-workflow.ts` beside its artifact
+directory. That file already default-exports the registry manifest Playbook
+requires: `id`, `command`, `intent`, `requiredRoleIds`, `validateOptions`,
+and `createRuntime`. Enable it under `playbooks`, bind every role listed in
+its `requiredRoleIds`, and invoke its effective slash command through Captain:
+
+```yaml
+players:
+  my.worker: claude
+
+playbooks:
+  my-workflow:
+    from: /absolute/path/to/my-workflow.ts
+    roles:
+      worker: my.worker
+```
+
+```sh
+playbook run "/my-workflow perform the task"
+```
 
-## Defaults for `playbook run`
+A relative path-shaped `from` is resolved relative to the primary config
+file, not the invocation directory; an absolute path is clearest for an SLC
+entry emitted in a project working tree.
+Before either front end imports a filesystem registry, the shared launcher
+checks and, unless `--no-provision` is set, provisions its runtime engine
+links as described in [Using the CLI](cli.md#external-playbooks-and-engine-provisioning).
 
-An optional top-level `run` block supplies the non-interactive host's
-lineup so you stop retyping flags — `run.captain`, `run.players.<role>`,
-and a `run.player` catch-all for any other required role, each an
-`<adapter>[:<model>][@<effort>]` string. Flags win per role, and
-`resume` always keeps the lineup stored with the parked session
-([[playbook-cli-28](../specs/packages/playbook-cli.md#playbook-cli-28)],
-[DR-017](../specs/decisions/017-run-defaults-config.md)).
+## Migrating per-playbook players
+
+The former `playbooks.<id>.players` shape made agent configuration and local
+workflow roles the same thing. It is removed. For example, this legacy config
+gave CODE and REVIEW two separately configured `coder` entries:
 
 ```yaml
-run:
-  captain: claude:claude-opus-4-8@high
-  players:
-    coder: claude:claude-opus-4-8[1m]@xhigh
-    reviewer: codex:gpt-5.5@xhigh
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    players:
+      coder: { adapter: claude, model: claude-opus-4-8[1m] }
+  review:
+    from: '@sublang/playbook/review/registry'
+    players:
+      coder: { adapter: claude, model: claude-opus-4-8[1m] }
+      reviewer: { adapter: codex, model: gpt-5.5 }
 ```
 
+Move each provider agent into the flat top-level map, choose stable IDs, and
+bind the local roles explicitly:
+
+```yaml
+players:
+  dev.coder: { adapter: claude, model: claude-opus-4-8[1m] }
+  dev.reviewer: { adapter: codex, model: gpt-5.5 }
+
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    roles: { coder: dev.coder }
+  review:
+    from: '@sublang/playbook/review/registry'
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
+```
+
+The launcher intentionally does **not** perform this migration for you. It
+cannot know whether the two old `coder` blocks were meant to share one
+conversation or remain isolated. Reusing `dev.coder` above chooses sharing;
+using `code.coder` and `review.coder` would choose isolation. A surviving
+per-playbook `players` block therefore rejects before profile migration,
+registry preparation, or agent work.
+
+## Migrating direct runs from 6.x
+
+The top-level `run:` block is deliberately rejected rather than silently
+ignored or rewritten, because doing otherwise could change the agents after
+an upgrade. Re-express `run.captain`, `run.players`, and former `--player`
+bindings as top-level stable player blocks and explicit role bindings above;
+the old `run.player` catch-all has no shared equivalent, so configure every
+required role at `playbooks.<id>.roles.<role>`. Use a `--with` fragment for
+temporary compatible tuning changes. Move former `--option` values into their `playbooks.<id>`
+block, run from the desired directory instead of passing `--cwd`, enable a
+former positional `<from>` as a configured registry, and quote or pipe one
+`/command task` Boss message. Replace `resume` and `--last` with `--continue`
+or `--session`.
+
+The JSON response is now exactly `{ "sessionId": "…", "reply": "…" }`.
+Released direct-run session records are not complete Captain sessions and
+cannot be continued by the new host ([[playbook-cli-19](../specs/packages/playbook-cli.md#playbook-cli-19)],
+[[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
+[[playbook-cli-28](../specs/packages/playbook-cli.md#playbook-cli-28)]).
+
 ## Migrating from `profiles`
 
 Configs written before 3.0.0 carried a top-level `profiles` map. The

package/docs/embedding.md

@@ -16,8 +16,8 @@ your own host.
 The port and runtime contracts live in the type-only module
 [`@sublang/playbook/runtime`](../src/runtime.ts) — a public,
 semver-stable surface (`PlayerResult`, `PlaybookPorts`,
-`PlaybookRuntime`, `PlaybookSession`, `PlayerCallOptions`,
-`PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
+`PlaybookRuntime`, `PlaybookSession`, `PlaybookRoleBinding`,
+`PlayerCallOptions`, `PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
 `PlaybookTraceEvent`, and `PlaybookRuntimeFactory`) that imports no CODE
 or FSM types, so a host satisfies it once and inherits every playbook.
 The generated CODE, REVIEW, and DECIDE modules re-export their shared
@@ -37,6 +37,9 @@ import type {
   CaptainCallOptions,
   CaptainResult,
   PlaybookPorts,
+  PlaybookRoleBinding,
+  PlayerResult,
+  PlayerSessionStore,
 } from '@sublang/playbook/runtime';
 import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
@@ -53,6 +56,33 @@ declare const captainAdapter: {
   ): Promise<CaptainResult>;
 };
 
+declare const playerAdapter: {
+  run(
+    playerId: string,
+    prompt: string,
+    options: { signal: AbortSignal; resume: string | false },
+  ): Promise<PlayerResult>;
+};
+
+// Roles are local workflow identities. Players are stable provider
+// conversations owned by the logical Captain session. `promptIdentity` is
+// the current model name, or the player's adapter when provider-default is
+// selected; rebuild it from current compatible tuning on restore.
+const roleBindings = {
+  coder: {
+    playerId: 'team.coder',
+    promptIdentity: 'claude-opus-4-8[1m]',
+  },
+  reviewer: {
+    playerId: 'team.reviewer',
+    promptIdentity: 'gpt-5.5',
+  },
+} satisfies Readonly<Record<string, PlaybookRoleBinding>>;
+
+// Supply a frame-local role view over your session-wide player ledger.
+// Equal player IDs must select/update the same token; distinct IDs must not.
+declare const playerSessions: PlayerSessionStore;
+
 // Construct one host-wide lane and reuse it for every runtime. Passing each
 // call's signal to both the lane and adapter cancels queued and active work.
 const captainLane = new PQueue({ concurrency: 1 });
@@ -69,10 +99,16 @@ async function runCaptain(
 }
 
 const ports: PlaybookPorts = {
-  callPlayer: async (playerId, prompt, signal, { resume }) => {
+  callPlayer: async (roleId, prompt, signal, { resume }) => {
+    const binding = roleBindings[roleId as keyof typeof roleBindings];
+    if (binding === undefined) throw new Error(`Unknown role: ${roleId}`);
     // `resume === false` starts fresh; a string selects that player's
-    // prior backend conversation. Return the adapter's next token.
-    return { status: 'ok', finalText: 'done', resumeToken: 'next-token' };
+    // prior backend conversation. Return the adapter's next token; the
+    // runtime updates `playerSessions` only after validating this result.
+    return await playerAdapter.run(binding.playerId, prompt, {
+      signal,
+      resume,
+    });
   },
   callCaptain: async (prompt, signal, options) => {
     // Forward every option exactly: omission preserves configured tools, while
@@ -103,10 +139,7 @@ const ports: PlaybookPorts = {
   },
 };
 
-const runtime = createPlaybookRuntime({
-  coderLlm: 'claude-opus-4-8[1m]',
-  reviewerLlm: 'gpt-5.5',
-});
+const runtime = createPlaybookRuntime({});
 
 const playbookSessionId = randomUUID();
 await runtime.init({
@@ -114,6 +147,8 @@ await runtime.init({
   playbookId: 'review',
   rootSessionId: playbookSessionId,
   depth: 0,
+  roleBindings,
+  playerSessions,
   ports,
 });
 await runtime.handleBossInput({
@@ -125,23 +160,34 @@ await runtime.dispose();
 
 ## Sessions and traces
 
-Every init-to-dispose lifecycle is one playbook session. Its
+Every init-to-dispose lifecycle is one playbook session. Schema-3
 `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. Without `PlaybookSession.playerSessions`, a standalone runtime
-starts each player fresh and privately retains the latest opaque
-`resumeToken` its adapter returned.
-
-A composing host can instead supply a frame-local `PlayerSessionStore`
-view over one root-owned continuation map. The host maps each local role
-to its effective binding, so a nested exact same-name role selects and
-updates the ancestor conversation while an unmatched child role gets
-its own binding. Child return or disposal does not clear the root's
-token, and a new root engagement starts fresh. 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.
+sequence across exact Boss input, judge/player calls, FSM transitions, visible
+Captain work, nested playbook calls, status, settlement, and disposal. A
+shell-hosted player boundary keeps both identities: `roleId` says which local
+workflow job made the call, while `playerId` says which stable session
+conversation owned it. A standalone runtime retains the role without
+inventing host player identity.
+
+Without `PlaybookSession.playerSessions`, a standalone runtime starts each
+local role fresh and privately retains the latest opaque `resumeToken` its
+adapter returned. A composing host instead supplies a frame-local
+`PlayerSessionStore` view over one Captain-session ledger and explicit
+`roleBindings`. The store's methods receive local role IDs; the view resolves
+them to the configured stable player IDs. Equal IDs share one token and
+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
+`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.
 
 See
 [`code.playbook.test.ts`](../reference/sdlc/code.playbook/code.playbook.test.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "6.0.0",
+  "version": "8.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,7 +67,10 @@
     "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/session-store.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
     "reference/sdlc/review.playbook/review.gears.md",
@@ -140,7 +143,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "spex lint && vitest run",
+    "test": "spex lint && vitest run --exclude src/cligent-release-capabilities.test.ts && vitest run src/cligent-release-capabilities.test.ts",
     "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
     "smoke:release": "node scripts/release-smoke.mjs",
     "check:links": "node scripts/check-links.mjs",
@@ -151,7 +154,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.19.0",
+    "@sublang/cligent": "^0.22.0",
     "@sublang/spex": "^2.1.1",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

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

@@ -31,7 +31,7 @@
 //                deterministic entry mapping, the controller captain-call
 //                strategy with its single corrective re-ask (CAPPLAY-18),
 //                controller-port submission, and status formatting.
-// Compat:        spec.compat = { artifactSchema: 1, runtimeAbi: 1 }
+// Compat:        spec.compat = { artifactSchema: 2, runtimeAbi: 1 }
 //                (DR-022; checked at construction by the loading engine).
 import { createXStatePlaybookRuntime, defaultComposeCaptainPrompt, normalizeError, normalizeErrorCompact, parseJudgeJson, snapshotJsonValue, RUNTIME_ABI, } from '../../../src/xstate-runtime.js';
 import { captainMachine, } from './captain.fsm.js';
@@ -516,11 +516,11 @@ export const _internal = {
 // describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
 const runtimeSpec = {
     label: 'CAPTAIN',
-    compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+    compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
     snapshotOptions: snapshotCaptainOptions,
     machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
     classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) => classifyControllerTurn(text, ports, signal, snapshotOrState, boundary, options),
-    playerStates: {},
+    roleStates: {},
     classificationStatus: () => undefined,
     captainStrategy: controllerCaptainStrategy,
     // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —

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

@@ -31,7 +31,7 @@
 //                deterministic entry mapping, the controller captain-call
 //                strategy with its single corrective re-ask (CAPPLAY-18),
 //                controller-port submission, and status formatting.
-// Compat:        spec.compat = { artifactSchema: 1, runtimeAbi: 1 }
+// Compat:        spec.compat = { artifactSchema: 2, runtimeAbi: 1 }
 //                (DR-022; checked at construction by the loading engine).
 
 import {
@@ -798,7 +798,7 @@ export const _internal = {
 // describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
 const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
   label: 'CAPTAIN',
-  compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+  compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
   snapshotOptions: snapshotCaptainOptions,
   machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
   classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) =>
@@ -810,7 +810,7 @@ const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
       boundary,
       options,
     ) as Promise<import('xstate').EventObject | undefined>,
-  playerStates: {},
+  roleStates: {},
   classificationStatus: () => undefined,
   captainStrategy: controllerCaptainStrategy,
   // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —

package/reference/sdlc/code.md

@@ -4,7 +4,7 @@
 
 # Code
 
-Players:
+Roles:
 
 - Coder