@sublang/playbook 5.0.0 → 7.0.0

package/docs/embedding.md

@@ -8,7 +8,7 @@ one host, and [spex](https://github.com/sublang-ai/spex) (the desktop
 app) is another. This guide shows how to wire a playbook runtime into
 your own host.
 
-> **Release note:** this guide targets the semver-stable 1.0 six-port
+> **Release note:** this guide targets the current semver-stable six-port
 > contract; see the [CHANGELOG](../CHANGELOG.md) for migration details.
 
 ## The runtime contract
@@ -17,11 +17,11 @@ 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`,
-`CaptainCallOptions`, `CaptainResult`, `PlaybookTraceEvent`, and
-`PlaybookRuntimeFactory`) that imports no CODE or FSM types, so a host
-satisfies it once and inherits every playbook. The CODE runtime
-re-exports `PlayerResult`, `PlaybookPorts`, `PlaybookSession`, and
-`PlaybookRuntime` from `@sublang/playbook/code/playbook`;
+`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
+runtime contract types from their public `playbook` subpaths;
 `PlaybookRuntimeFactory` is available from `@sublang/playbook/runtime`.
 
 Generated linked runtimes reuse the XState integration engine exposed
@@ -32,7 +32,7 @@ nested-playbook bridge.
 ## Constructing a runtime against your own ports
 
 ```ts
-import createPlaybookRuntime from '@sublang/playbook/code/playbook';
+import createPlaybookRuntime from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
   CaptainResult,
@@ -104,20 +104,20 @@ const ports: PlaybookPorts = {
 };
 
 const runtime = createPlaybookRuntime({
-  coderPlayer: 'claude',
-  reviewerPlayer: 'codex',
+  coderLlm: 'claude-opus-4-8[1m]',
+  reviewerLlm: 'gpt-5.5',
 });
 
 const playbookSessionId = randomUUID();
 await runtime.init({
   sessionId: playbookSessionId,
-  playbookId: 'code',
+  playbookId: 'review',
   rootSessionId: playbookSessionId,
   depth: 0,
   ports,
 });
 await runtime.handleBossInput({
-  text: 'Start fixing the bug',
+  text: 'Review the latest commit against the requested intent',
   signal: new AbortController().signal,
 });
 await runtime.dispose();
@@ -129,11 +129,19 @@ Every init-to-dispose lifecycle is one playbook session. Its
 `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. Each resolved player starts fresh in a new playbook session
-and then resumes only from the latest opaque `resumeToken` its adapter
-returned; 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.
+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.
 
 See
 [`code.playbook.test.ts`](../reference/sdlc/code.playbook/code.playbook.test.ts)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "5.0.0",
+  "version": "7.0.0",
   "type": "module",
-  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
+  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, and DECIDE workflows driven by GEARS specs.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -40,7 +40,8 @@
     "slc/optimize.md",
     "reference/sdlc/captain.md",
     "reference/sdlc/code.md",
-    "reference/sdlc/discuss.md",
+    "reference/sdlc/review.md",
+    "reference/sdlc/decide.md",
     "reference/sdlc/captain.playbook/captain.gears.md",
     "reference/sdlc/captain.playbook/captain.fsm.ts",
     "reference/sdlc/captain.playbook/captain.fsm.js",
@@ -66,19 +67,31 @@
     "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/session-store.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
-    "reference/sdlc/discuss.playbook/discuss.gears.md",
-    "reference/sdlc/discuss.playbook/discuss.fsm.ts",
-    "reference/sdlc/discuss.playbook/discuss.fsm.js",
-    "reference/sdlc/discuss.playbook/discuss.fsm.d.ts",
-    "reference/sdlc/discuss.playbook/discuss.playbook.ts",
-    "reference/sdlc/discuss.playbook/discuss.playbook.js",
-    "reference/sdlc/discuss.playbook/discuss.playbook.d.ts",
-    "reference/sdlc/discuss.playbook/discuss.registry.ts",
-    "reference/sdlc/discuss.playbook/discuss.registry.js",
-    "reference/sdlc/discuss.playbook/discuss.registry.d.ts",
+    "reference/sdlc/review.playbook/review.gears.md",
+    "reference/sdlc/review.playbook/review.fsm.ts",
+    "reference/sdlc/review.playbook/review.fsm.js",
+    "reference/sdlc/review.playbook/review.fsm.d.ts",
+    "reference/sdlc/review.playbook/review.playbook.ts",
+    "reference/sdlc/review.playbook/review.playbook.js",
+    "reference/sdlc/review.playbook/review.playbook.d.ts",
+    "reference/sdlc/review.playbook/review.registry.ts",
+    "reference/sdlc/review.playbook/review.registry.js",
+    "reference/sdlc/review.playbook/review.registry.d.ts",
+    "reference/sdlc/decide.playbook/decide.gears.md",
+    "reference/sdlc/decide.playbook/decide.fsm.ts",
+    "reference/sdlc/decide.playbook/decide.fsm.js",
+    "reference/sdlc/decide.playbook/decide.fsm.d.ts",
+    "reference/sdlc/decide.playbook/decide.playbook.ts",
+    "reference/sdlc/decide.playbook/decide.playbook.js",
+    "reference/sdlc/decide.playbook/decide.playbook.d.ts",
+    "reference/sdlc/decide.playbook/decide.registry.ts",
+    "reference/sdlc/decide.playbook/decide.registry.js",
+    "reference/sdlc/decide.playbook/decide.registry.d.ts",
     "docs"
   ],
   "bin": {
@@ -110,18 +123,26 @@
       "default": "./reference/sdlc/code.playbook/playbook-captain.js"
     },
     "./slc/*": "./slc/*",
-    "./discuss/playbook": {
-      "types": "./reference/sdlc/discuss.playbook/discuss.playbook.d.ts",
-      "default": "./reference/sdlc/discuss.playbook/discuss.playbook.js"
+    "./review/playbook": {
+      "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",
+      "default": "./reference/sdlc/review.playbook/review.playbook.js"
     },
-    "./discuss/registry": {
-      "types": "./reference/sdlc/discuss.playbook/discuss.registry.d.ts",
-      "default": "./reference/sdlc/discuss.playbook/discuss.registry.js"
+    "./review/registry": {
+      "types": "./reference/sdlc/review.playbook/review.registry.d.ts",
+      "default": "./reference/sdlc/review.playbook/review.registry.js"
+    },
+    "./decide/playbook": {
+      "types": "./reference/sdlc/decide.playbook/decide.playbook.d.ts",
+      "default": "./reference/sdlc/decide.playbook/decide.playbook.js"
+    },
+    "./decide/registry": {
+      "types": "./reference/sdlc/decide.playbook/decide.registry.d.ts",
+      "default": "./reference/sdlc/decide.playbook/decide.registry.js"
     }
   },
   "scripts": {
     "build": "tsc",
-    "test": "vitest run",
+    "test": "spex lint && vitest run",
     "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
     "smoke:release": "node scripts/release-smoke.mjs",
     "check:links": "node scripts/check-links.mjs",
@@ -133,7 +154,7 @@
   },
   "dependencies": {
     "@sublang/cligent": "^0.19.0",
-    "@sublang/spex": "^0.3.0",
+    "@sublang/spex": "^2.1.1",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"

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

@@ -520,6 +520,8 @@ const runtimeSpec = {
     snapshotOptions: snapshotCaptainOptions,
     machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
     classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) => classifyControllerTurn(text, ports, signal, snapshotOrState, boundary, options),
+    playerStates: {},
+    classificationStatus: () => undefined,
     captainStrategy: controllerCaptainStrategy,
     // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —
     // the settlement evidence the machine retains for its decision and reply

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

@@ -810,6 +810,8 @@ const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
       boundary,
       options,
     ) as Promise<import('xstate').EventObject | undefined>,
+  playerStates: {},
+  classificationStatus: () => undefined,
   captainStrategy: controllerCaptainStrategy,
   // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —
   // the settlement evidence the machine retains for its decision and reply

package/reference/sdlc/code.md

@@ -1,105 +1,63 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 <!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
 
 # Code
 
 Players:
 
 - Coder
-- Reviewer
-- Committer = Coder | Reviewer
-
-## Coder
-
-When Boss gives a coding intent, Captain shall relay it to Coder along with the following prompt:
-> Assess whether this can be completed in a single commit, following best practices.
-> If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/intents (or @specs/iterations in older scaffolds) and stop without implementing any IR task.
-> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
-> Ensure @specs/map.md reflects the changes.
-> Do not commit.
-The resulting changes are regarded as Initial Changes.
-
-When Reviewer raises any findings, Captain shall relay them to Coder along with the following prompt:
-> For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
-> Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.
-
-When a new IR or IR task passes review and is committed, Captain shall prompt Coder:
-> Continue to implement IR-<#> if not all deliverables and tasks are done.
-> Implement one task at a time (including corresponding tests if any).
-> Stop after each task for review — do not commit yet.
-> If relevant, mark progress in the IR.
-The resulting changes are regarded as Initial Changes.
-
-When an IR is done, Captain shall prompt Coder:
-> Read IR-<#> and corresponding commits.
-> According to @specs/meta.md, add or update spec items to fully capture:
->
-> - the external behavior users rely on,
-> - the internal system behavior, and
-> - the integration/system test cases.
->
-> The spec items should be the *minimal* set needed to reimplement code without the IR.
-> The set should be complete and coherent.
-> Avoid implementation specifics.
-> Avoid redundant spec items.
-> Ensure @specs/map.md reflects the changes.
-
-## Reviewer
-
-For each finding in a review round, Coder either addresses it with changes or challenges it with a rebuttal.
-Any code change to address findings starts a new round of review, even if some findings are also rebutted.
-Rounds continue until Reviewer raises no findings.
-
-Spec item files are the files under @specs/ that hold spec items — @specs/packages/ and @specs/compositions/ in the current layout, or @specs/user/, @specs/dev/, and @specs/test/ in the legacy one; decision and intent records (iteration records in older scaffolds), @specs/map.md, and @specs/meta.md are not spec item files.
-
-When Reviewer begins the first review round on changes from a Boss coding intent, Captain shall relay the intent to Reviewer.
-
-When Reviewer begins the first review round on changes from an IR task, Captain shall relay the IR's task description to Reviewer.
-
-When Committer commits Initial Changes, Captain shall prompt Reviewer to begin a review round:
-> Review the latest commit.
-> Refer to the commit message.
-
-When any changes are made by Coder but not reviewed (outside of any Initial Changes), Captain shall prompt Reviewer to begin a review round:
-> Review the unstaged and untracked changes in the context of the staged changes.
-> Understand the intent.
-
-When Reviewer begins a review round involving spec item files, Captain shall prompt Reviewer:
-> Verify any affected spec items are:
->
-> - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
-> - Minimal: essential and concise; every item earns its place; also check with other items.
-> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
->
-> Flag anything missing, redundant, over-specified, or under-specified.
-
-When Reviewer begins a review round involving any changes outside spec item files, Captain shall prompt Reviewer:
-> Flag any issues or improvements (numbered; no duplication).
-> Think thoroughly — don't just approve or reject.
-
-When Reviewer begins any review round, Captain shall prompt Reviewer:
-> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
-> Verify @specs/map.md reflects the changes.
-> If the change is ready to commit or push, don't raise nitpicks.
-> Do not edit files or commit; report findings only.
-
-When Coder raises any rebuttals, Captain shall relay them to Reviewer along with the following prompt:
-> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
-> Do not edit files or commit; report findings only.
-
-## Committer
-
-When Coder makes any Initial Changes or Reviewer raises no findings on uncommitted changes, Captain shall prompt Committer:
-> Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
-> If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
-> Write the commit message concisely.
-
-When Captain prompts Committer and only Coder has played since the last commit, Captain shall also append:
-> Coder is \<coder-llm\>.
-
-When Captain prompts Committer and both Coder and Reviewer have played since the last commit, Captain shall also append:
-> Coder is \<coder-llm\>; Reviewer is \<reviewer-llm\>.
-
-When Captain prompts Committer, Captain shall also append:
-> Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
+
+The caller supplies the coding intent including any specific 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.
+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.
+
+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 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.
+Plan affected spec updates before, with, or after their corresponding code changes, either as standalone IR tasks or as explicit work within related tasks.
+
+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:
+
+```markdown
+Read IR-<#> and implement exactly the 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.
+```
+
+At the start of *every* phase, Captain shall append the following instruction:
+
+```markdown
+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.
+Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
+Coder is <coder-llm>; format the model token in conventional human form.
+```
+
+After the first phase (either direct implementation or a new-IR phase), Captain shall call playbook `review` and input the following in quotes (`>`):
+
+> Initial intent: \<caller-input\>
+> Coder output: \<coder-output\>
+
+After every IR-task phase, Captain shall call playbook `review` and input the following in quotes (`>`):
+
+> IR task: \<ir-task\>
+> Coder output: \<coder-output\>