@sublang/playbook 6.0.0 → 8.0.0

package/README.md

@@ -19,16 +19,23 @@ SubLang Playbook addresses both:
 
 ![Venn diagram: Skill is flexible, Workflow is deterministic, and Playbook sits in the intersection as both.](docs/assets/playbook-venn.svg)
 
-Vocabulary: the **Boss** is you; the **Captain** is the coordinating agent you talk to; **players** are the agents a playbook delegates work to.
+Vocabulary: the **Boss** is you; the **Captain** is the coordinating agent you
+talk to; a **role** is a playbook-local job such as `coder`; and a **player** is
+a stable Captain-session agent and provider conversation to which one or more
+roles bind. Roles describe the workflow, while player IDs decide which work
+shares conversation continuity.
 
-Run `playbook` for an interactive tmux UI powered by [cligent](https://github.com/sublang-ai/cligent), or `playbook run` for one-shot scripts and CI.
+Run `playbook` for an interactive tmux UI powered by [cligent](https://github.com/sublang-ai/cligent), or `playbook run` for the same Captain session without tmux in scripts and CI.
 
 ## Quick start
 
 Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, and **DECIDE** for independently proposed and reviewed specification decisions.
 CODE and DECIDE call REVIEW as a nested playbook.
 
-The interactive starter config uses Claude as both Captain and Coder, and Codex as Reviewer.
+The shared starter config uses Claude as both Captain and the `dev.coder`
+player, and Codex as `dev.reviewer`. CODE, REVIEW, and DECIDE bind their local
+roles explicitly to those two stable players, so nested and later engagements
+share a conversation only where their bindings name the same player ID.
 
 ```sh
 npm install -g @sublang/playbook
@@ -41,10 +48,11 @@ If an SDK is missing or older than cligent supports, Playbook prints the pinned
 Prerequisites:
 
 - Node.js >= 20.6.0
-- `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`
 - Authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY`
 - Authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`
 
+Interactive `playbook` additionally needs tmux 3.3 or newer and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.
+
 CODE works in the current directory and can edit and commit autonomously, so use a clean branch or worktree.
 
 ```sh
@@ -57,16 +65,23 @@ Type a task, enter `/code <task>` for implementation, or enter
 
 On first launch, Playbook writes its config to `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`.
 
-One-shot runs use separate defaults instead of the interactive lineup.
-Without configured `run` defaults, the Captain and every player use Claude; run standalone REVIEW with a Codex Reviewer using:
+The same config, compiled Captain, enabled playbooks, stable players, and
+nested calls power headless turns. Both front ends create the same durable
+logical session: copy the reported session ID to reopen an interactive session
+headlessly or a headless session interactively.
+Run REVIEW explicitly, or pipe a longer request to Captain:
 
 ```sh
-playbook run @sublang/playbook/review/registry "review the latest commit" --player reviewer=codex --json
+playbook run "/review review the latest commit"
+printf '%s\n' 'Implement the approved specification, then review it.' | playbook run
+# Later, either presentation can reopen the returned/reported session id:
+playbook --session 4f2c0000-0000-4000-8000-000000009ab1
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 "continue"
 ```
 
-CODE and DECIDE require interactive `playbook` because the one-shot host does not drive nested calls.
+`playbook run` prints the one Boss-visible Captain reply to stdout and operational status to stderr; CODE and DECIDE can complete their nested REVIEW calls there too.
 
-See [Using the CLI](docs/cli.md) for flags and session resume, [Configuring agents](docs/configuration.md) for lineups, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](CHANGELOG.md) for releases.
+See [Using the CLI](docs/cli.md) for flags and durable continuation, [Configuring agents](docs/configuration.md) for the shared lineup, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](CHANGELOG.md) for releases.
 
 ## Create your own playbook
 
@@ -75,10 +90,12 @@ The separate [SLC compiler](https://github.com/sublang-ai/slc) requires Node.js
 ```sh
 npm install -g @sublang/slc
 slc playbook my-workflow.md
-playbook run ./my-workflow.ts "<your task>"
+# After enabling /absolute/path/to/my-workflow.ts in the shared config:
+playbook run "/my-workflow <your task>"
 ```
 
-SLC writes `my-workflow.ts` beside the source, and the inspectable intermediates and tests under `my-workflow.playbook/`; see the [SLC documentation](https://github.com/sublang-ai/slc#quick-start) for setup and phase commands.
+SLC writes `my-workflow.ts`, a registry entry ready for Playbook, beside the source, and the inspectable intermediates and tests under `my-workflow.playbook/`.
+Enable that entry and bind each role it declares under `playbooks.my-workflow` in the shared config, then invoke `/my-workflow`; see [External playbooks](docs/configuration.md#external-playbooks) and the [SLC documentation](https://github.com/sublang-ai/slc#quick-start).
 
 ## How it compiles
 

package/docs/cli.md

@@ -3,9 +3,13 @@
 
 # Using the CLI
 
-`playbook` has two surfaces: an interactive tmux-play session, and a
-one-shot non-interactive `run`. Agent settings for both come from the
-[config](configuration.md).
+`playbook` has two presentations of one configured Captain session: an
+interactive tmux-play UI and a headless `playbook run` turn for scripts and
+CI. Both use the same compiled Captain, enabled catalog, players, nested
+stack, and [config](configuration.md); only presentation differs.
+
+The interactive form requires tmux 3.3 or newer and `glow` on `PATH`;
+the headless form requires neither presentation tool.
 
 ## Installing agent SDKs
 
@@ -55,9 +59,11 @@ following it cannot install a version the gate refuses again
 ## Interactive
 
 ```sh
-playbook            # launch the configured playbooks in tmux-play
-playbook --list     # ids, slash commands, and intents; no launch
-playbook --help     # config path, auth pointers, agent-swap recipe
+playbook                         # fresh durable session in this directory
+playbook --cwd /path/to/repo     # fresh session in an explicit directory
+playbook --session <id>          # reopen either front end's settled session
+playbook --list                  # ids, slash commands, and intents; no launch
+playbook --help                  # config path, auth pointers, binding recipe
 ```
 
 Without a global install, `npx` runs the same bin — but name each
@@ -77,10 +83,21 @@ already present, since each distinct package set is a distinct tree —
 and replaying your original arguments, so the printed command works in
 one hop.
 
-The command resolves its config (seeding it on first run), composes a
-`tmux-play` config, checks adapter readiness, and launches. It exits
-with tmux-play's status, re-raises a terminating signal on itself, and
-exits `127` when it cannot launch at all
+For a managed launch, the outer command resolves current config (seeding it on
+first use), prepares the complete stored catalog and presenter, waits for the
+pane child to acquire the session lease and publish its settled turn-zero
+record, prints the verified session ID, and then attaches. A normal outer
+detach exits `0`; the pane child keeps owning the durable session and accepting
+turns until it shuts down. Preparation, attachment, or required cleanup
+failure prints its diagnostics and exits nonzero.
+
+Before native-client hand-off, SIGHUP, SIGINT, or SIGTERM aborts activation,
+joins the child, retires the lease, and only then re-raises the signal. At the
+synchronous native-client hand-off, ownership transfers before tmux starts, so
+later signals use native client detach or termination semantics and do not
+retire the pane child's session. Only `--config` and composed
+`--theme-diagnostics` use the stock subprocess boundary: those forms mirror
+its exit status or signal and exit `127` when it cannot be spawned
 ([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)],
 [[playbook-cli-2](../specs/packages/playbook-cli.md#playbook-cli-2)]).
 
@@ -105,10 +122,12 @@ untouched
 [[playbook-captain-2](../specs/packages/playbook-captain.md#playbook-captain-2)]).
 
 The current CODE, REVIEW, and DECIDE workflows take their deterministic
-initial event from the selecting Boss turn. CODE and DECIDE then call
-REVIEW as a nested playbook: an exact same-name child role continues the
-ancestor's player pane and backend conversation, while any additional
-role uses REVIEW's configured fallback. When a player surfaces a
+initial event from the selecting Boss turn. CODE and DECIDE then call REVIEW
+as a nested playbook. Local role names do not imply continuity: each frame
+uses the exact stable player IDs configured under its `roles` map. Equal IDs
+share one pane and provider conversation across nested and later root
+engagements; distinct IDs remain isolated even when their agent settings are
+identical. When a player surfaces a
 clarifying question the FSM parks, the pane shows the question, and a
 judge classifies your next turn as its reply or a fresh directive that
 abandons it
@@ -123,78 +142,149 @@ turn's reported outcome; a turn that changed nothing ends with an
 ordinary reply and no saved-counts line
 ([[playbook-captain-19](../specs/packages/playbook-captain.md#playbook-captain-19)]).
 
-## Non-interactive
+## Headless
 
-`playbook run <from> [task]` runs one playbook once, without tmux-play
-and without an interactive config entry. For example, run REVIEW
-directly against the latest commit:
+`playbook run [input]` submits one exact Boss turn to the same Captain that
+the interactive pane hosts, without constructing tmux. The shared config
+selects the Captain, enabled playbooks, players, options, provisioning, and
+readiness; a slash command selects a playbook through Captain, and ordinary
+text remains a conversational Captain turn.
 
 ```sh
-playbook run @sublang/playbook/review/registry "review the latest commit" \
-  --player coder=claude --player reviewer=codex --cwd ./my-repo
+cd ./my-repo
+playbook run "/review review the latest commit"
+playbook run "/code implement the approved specification"
+printf '%s\n' 'Summarize the current work and propose the next step.' | playbook run
 ```
 
-`[task]` is read from stdin when omitted — pipe long or multi-line
-intents the same way you would to `claude -p` or `codex exec`.
+When `[input]` is absent, stdin is read to EOF as verbatim UTF-8 text.
+Use `--` before one flag-shaped input. Plain stdout is exactly the one
+Boss-visible Captain reply plus a line feed; status and diagnostics use
+stderr, and `--verbose` adds only telemetry topic names to stderr.
+`--json` instead prints exactly `{"sessionId":"…","reply":"…"}`.
 
 | Flag | Meaning |
 | --- | --- |
-| `--player <role>=<agent>` | bind a required role |
-| `--captain <agent>` | set the captain/judge agent |
-| `--option <key>=<value>` | a registry-defined playbook option (none in the current bundled workflows) |
-| `--cwd <dir>` | the agents' working directory |
-| `--json` | one envelope: `outcome`, `sessionId`, output or questions |
-| `--no-provision` | never create engine links beside a filesystem `<from>` |
-
-`<agent>` is `<adapter>[:<model>][@<effort>]` — `codex:gpt-5.5@xhigh`,
-or `claude@high` for the default model at high reasoning effort. The
-model keeps every interior colon (`opencode:ollama/llama3:8b@max`), and
-an unsupported effort is rejected up front naming the adapter's
-supported values. Roles and the captain default to `claude` unless the
-config supplies [run defaults](configuration.md#defaults-for-playbook-run).
-
-Exit codes: `0` terminal, `1` bad argument or module, `2` failure, `3`
-the playbook needs a Boss reply
+| `--with <path>` | overlay current config for a fresh session or compatible ordinary reopen; repeatable |
+| `--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 |
+| `--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 |
+| `--` | end options before one literal input or reply |
+| `-h`, `--help` | print the complete grammar without reading stdin or config |
+
+Exit `0` means the Captain turn and its durable hand-off were presented,
+even when the selected action reported rejection or failure through the
+Captain reply. Argument, config, catalog, readiness, or pre-turn setup errors
+exit `1`; a started-turn, persistence, lease-release, or presentation failure
+exits `2` with stdout empty. SIGINT, SIGTERM, and SIGHUP preserve the
+uncertain boundary, withhold stdout, and are re-raised after lease retirement
 ([[playbook-cli-18](../specs/packages/playbook-cli.md#playbook-cli-18)]).
 
-### Engine provisioning
+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`
+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
+conversation sharing or isolation; see [Migrating per-playbook
+players](configuration.md#migrating-per-playbook-players).
+
+### Piping a Spex update prompt
+
+`spex scaffold --update` refreshes its scaffold before printing guidance and
+a fenced reconciliation prompt. Force Spex's non-interactive agent-file
+selection, capture its successful output, extract the first fenced prompt,
+and pass only that prompt to Captain:
+
+```sh
+update_output="$(spex scaffold --update </dev/null)" &&
+printf '%s\n' "$update_output" |
+  awk '/^```$/{if (++n==2) exit; next} n==1' |
+  playbook run
+```
+
+The capture prevents a failed Spex command from launching Playbook. Without
+`--lang`, the first fenced block is the sole structure reconciliation or
+legacy-migration prompt; a language switch adds a second translation prompt.
+
+### External playbooks and engine provisioning
 
-A compiled playbook module imports `xstate` and
-`@sublang/playbook/xstate-runtime` from its own directory. When a
-filesystem `<from>` cannot resolve them — typically under a global
-install with no project-local packages —
-`playbook run` provisions them automatically before loading: it creates
-`node_modules/xstate` and `node_modules/@sublang/playbook` beside the
-module as symlinks to the running host's own packages and prints one
-line naming what it linked
+Enable an external registry in the shared config and invoke its effective
+slash command; a path-shaped `playbooks.<id>.from` is resolved relative to
+the primary config file. Before either front end imports a configured
+filesystem registry, the shared launcher checks whether that module can
+resolve `xstate` and `@sublang/playbook/xstate-runtime`. When needed, it
+creates engine symlinks beside the module and prints one provisioning line
 ([[playbook-cli-36](../specs/packages/playbook-cli.md#playbook-cli-36)],
 [DR-024](../specs/decisions/024-runtime-engine-provisioning.md)).
-A directory where the imports already resolve is never touched — a
-project-local install always wins — and `--no-provision` disables the
-mechanism entirely.
 
-If the module's directory is a git repository, add `node_modules/` to
-its `.gitignore` so the provisioned links never land in commits made by
-player agents working there.
+A directory where both imports already resolve is untouched, and
+`--no-provision` disables new links for either fresh front end. If the
+module's directory is a git repository, add `node_modules/` to its
+`.gitignore` so provisioned links never enter player commits.
 
-### Resuming a parked run
+### Continuing a Captain session
 
-When the playbook stops to ask something, the run is parked, not lost:
-the question prints to stdout, the session is saved under
-`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`, and stderr
-names the command that continues it.
+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:
 
 ```sh
-playbook run resume 4f2c…9ab1 "keep the scope small; skip the docs"
-playbook run resume --last   # most recently parked session; reply on stdin
+# Reopen the latest settled session headlessly:
+playbook run --continue "keep the scope small; skip the docs"
+
+# Reopen one exact session in either presentation:
+playbook --session 4f2c0000-0000-4000-8000-000000009ab1
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1
 ```
 
-A resumed run picks up exactly where it parked — same session id, same
-workflow state, and each agent continues its own conversation — then
-prints the final output and exits `0`, or parks again and exits `3`. The
-lineup, options, and working directory are stored with the session, so
-`resume` takes no binding flags. In scripts, capture the session id from
-the `--json` envelope, like Claude Code's `session_id` or
-`codex exec resume`
+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
+settled or pending child start. One exclusive writer owns the session, so a
+detached interactive pane child remains the owner until it shuts down; a
+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
 ([[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
-[DR-014](../specs/decisions/014-durable-one-shot-run-sessions.md)).
+[DR-032](../specs/decisions/032-explicit-roles-session-players.md)).
+
+### Recovering an uncertain turn
+
+Before model work, the runner takes one exclusive session lease and writes an
+uncertain marker. If the process is interrupted after effects may
+have begun but before settlement is durable, ordinary continuation refuses
+to guess. Choose explicitly:
+
+```sh
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --retry-uncertain
+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
+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.