@sublang/playbook 0.6.0 → 0.8.0

package/README.md

@@ -84,7 +84,7 @@ playbook-code --help
 
 The seed template runs each agent in cligent's protected auto mode
 (`permissions.mode: auto`), suppressing routine approval prompts. Its
-Codex Coder also grants `permissions.writablePaths: [.git]` so git
+Codex Reviewer also grants `permissions.writablePaths: [.git]` so git
 metadata writes stay available under auto mode without switching to
 bypass permissions.
 
@@ -108,40 +108,41 @@ the runtime binds to those host-configuration invariants per
 `<coder-llm>` / `<reviewer-llm>` substitution strings from each role's
 `model` when pinned and `adapter` otherwise — so the Committer's
 commit-message trailers can name the concrete model
-(e.g. `claude-opus-4-8`) rather than the adapter family (`claude`).
+(e.g. `claude-opus-4-8[1m]`) rather than the adapter family
+(`claude`).
 
 `players.committer` is an optional alias naming which role — `coder`
 or `reviewer` — runs the commit turn; the seeded overlay points it at
-the Reviewer. Absent the alias the Committer falls back to the Coder
+the Coder. Absent the alias the Committer falls back to the Coder
 ([PBRT-8](specs/user/playbook-runtime.md#pbrt-8)).
 
-For example, the seeded overlay runs the Coder on Codex and the
-Reviewer on Claude, with the Committer aliased to the Reviewer:
+For example, the seeded overlay runs the Coder on Claude Opus 4.8 1m
+and the Reviewer on GPT-5.5, with the Committer aliased to the Coder:
 
 ```yaml
 captain:
   adapter: claude
-  model: claude-sonnet-4-6
+  model: claude-opus-4-8
   reasoningEffort: high
   permissions:
     mode: auto
 
 players:
   coder:              # role key must stay `coder` — see PBRT-4
-    adapter: codex
-    model: gpt-5.5
+    adapter: claude
+    model: claude-opus-4-8[1m]
     reasoningEffort: xhigh
     permissions:
       mode: auto
-      writablePaths:
-        - .git          # allow git metadata writes under Codex auto mode
   reviewer:           # role key must stay `reviewer` — see PBRT-4
-    adapter: claude
-    model: claude-opus-4-8
+    adapter: codex
+    model: gpt-5.5
     reasoningEffort: xhigh
     permissions:
       mode: auto
-  committer: reviewer   # which role commits — `coder` or `reviewer`
+      writablePaths:
+        - .git          # allow git metadata writes under Codex auto mode
+  committer: coder      # which role commits — `coder` or `reviewer`
 ```
 
 Normal `playbook-code` runs use the seeded path above. If you need a
@@ -170,15 +171,13 @@ pnpm test
 in the checked-in `pnpm-lock.yaml` — the same version CI installs
 via `--frozen-lockfile`, so contributor checkouts and CI agree.
 The published `package.json` declares `@sublang/cligent` as
-`latest`, so an end-user install with no lockfile (e.g., `npm
-install -g @sublang/playbook`) instead resolves whichever cligent
-release currently carries the `latest` dist-tag at install time
-(see [RELEASE-14](specs/dev/release.md#release-14)). To bump the
-contributor pin to today's `latest`, run
+`^0.13.0`, so an end-user install with no lockfile (e.g., `npm
+install -g @sublang/playbook`) resolves a compatible cligent 0.13.x
+release (see [RELEASE-14](specs/dev/release.md#release-14)). To
+refresh the contributor pin within that range, run
 `pnpm update @sublang/cligent` and commit the resulting
-`pnpm-lock.yaml` change — a plain `pnpm install` won't refresh the
-pin, since pnpm sees `specifier: latest` in the lockfile as
-already matching `package.json` and skips re-resolving the tag.
+`pnpm-lock.yaml` change. To adopt a later cligent minor, update the
+`package.json` specifier and lockfile together.
 No local link required for any of this. To point pnpm at a local
 `cligent` checkout
 instead, copy
@@ -225,12 +224,19 @@ registered.
 ### Embedding the runtime in your own host
 
 The runtime is host-agnostic; the `tmux-play` adapter is one 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`,
+`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`, and `PlaybookRuntime` from
+`@sublang/playbook/code/playbook`; `PlaybookRuntimeFactory` is available
+from `@sublang/playbook/runtime`.
 Construct the runtime against your own ports:
 
 ```ts
-import createPlaybookRuntime, {
-  type PlaybookPorts,
-} from '@sublang/playbook/code/playbook';
+import createPlaybookRuntime from '@sublang/playbook/code/playbook';
+import type { PlaybookPorts } from '@sublang/playbook/runtime';
 
 const ports: PlaybookPorts = {
   callPlayer: async (playerId, prompt, signal) => { /* … */ },
@@ -257,6 +263,25 @@ See
 for the full range of port shapes (classifier, judge, abort, interrupt,
 status/telemetry) the runtime is contract-tested against.
 
+### Reading the published spec contracts
+
+The authored compiler-phase specs ship in the package and are exposed
+as a public, semver-stable surface under `@sublang/playbook/slc/*`.
+Resolve and read one with `import.meta.resolve` plus `fs`:
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const url = import.meta.resolve('@sublang/playbook/slc/link.md');
+const link = await readFile(fileURLToPath(url), 'utf8');
+```
+
+The three specs are [`slc/text2gears.md`](slc/text2gears.md),
+[`slc/gears2fsm.md`](slc/gears2fsm.md), and [`slc/link.md`](slc/link.md)
+— the FSM-to-runtime contract that `@sublang/playbook/runtime` projects
+into TypeScript.
+
 ## Workflow
 
 playbook is itself spec-driven: the compiler phases are specs in `slc/`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and Playbook Captain shell for a coder/reviewer/committer loop driven by GEARS spec items.",
   "license": "Apache-2.0",
@@ -25,6 +25,12 @@
     "node": ">=20.6.0"
   },
   "files": [
+    "src/runtime.ts",
+    "src/runtime.js",
+    "src/runtime.d.ts",
+    "slc/link.md",
+    "slc/gears2fsm.md",
+    "slc/text2gears.md",
     "reference/sdlc/code.playbook/code.fsm.ts",
     "reference/sdlc/code.playbook/code.fsm.js",
     "reference/sdlc/code.playbook/code.fsm.d.ts",
@@ -53,6 +59,10 @@
     "playbook-code": "reference/sdlc/code.playbook/bin/playbook-code.js"
   },
   "exports": {
+    "./runtime": {
+      "types": "./src/runtime.d.ts",
+      "default": "./src/runtime.js"
+    },
     "./code/playbook": {
       "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
       "default": "./reference/sdlc/code.playbook/code.playbook.js"
@@ -64,7 +74,8 @@
     "./code/tmux-play": {
       "types": "./reference/sdlc/code.playbook/code.tmux-play.d.ts",
       "default": "./reference/sdlc/code.playbook/code.tmux-play.js"
-    }
+    },
+    "./slc/*": "./slc/*"
   },
   "scripts": {
     "build": "tsc",
@@ -78,7 +89,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@openai/codex-sdk": "^0.139.0",
-    "@sublang/cligent": "latest",
+    "@sublang/cligent": "^0.13.0",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"
   },

package/reference/sdlc/code.playbook/bin/playbook-code.js

@@ -264,8 +264,15 @@ export function composeRuntimeConfig(
   const composed = {};
   const theme = overlayConfig.theme ?? base?.theme;
   if (theme !== undefined) composed.theme = theme;
-  const layout = overlayConfig.layout ?? base?.layout;
-  if (layout !== undefined) composed.layout = layout;
+  // PBCODE-16/17: an overlay `layout` is the user's own tmux-play layout
+  // and is carried through verbatim; a base-inherited `layout` is
+  // reconciled so it round-trips onto the composed coder + reviewer roster
+  // (cligent normalizes the base layout to the base config's own roster).
+  if (overlayConfig.layout !== undefined) {
+    composed.layout = overlayConfig.layout;
+  } else if (base?.layout !== undefined) {
+    composed.layout = composeInheritedLayout(base.layout);
+  }
   const notifications = overlayConfig.notifications ?? base?.notifications;
   if (notifications !== undefined) composed.notifications = notifications;
   composed.captain = captain;
@@ -273,6 +280,33 @@ export function composeRuntimeConfig(
   return composed;
 }
 
+// PBCODE-17: reconcile a base-inherited `layout` so it round-trips onto
+// the composed `coder` + `reviewer` roster. cligent's loaded base `layout`
+// is normalized to the base config's own roster and shape: `initialVisible`
+// names the base config's players (cligent rejects ids outside the composed
+// roster) and the normalized output carries both the `columnWeights` alias
+// and the canonical `singlePlayerColumnWeights` / `multiPlayerColumnWeights`
+// (cligent emits the pair on load but rejects it on reload). Drop
+// `initialVisible` — CODE shows its full composed roster, which cligent
+// restores when the field is omitted — and drop the `columnWeights` alias
+// whenever the canonical field for the alias's shape is present, carrying
+// window and weights through otherwise. An overlay `layout` is the user's
+// own and is not reconciled.
+function composeInheritedLayout(layout) {
+  if (!isObject(layout)) return layout;
+  const result = { ...layout };
+  delete result.initialVisible;
+  const alias = result.columnWeights;
+  if (Array.isArray(alias)) {
+    const conflictsSingle =
+      alias.length === 2 && result.singlePlayerColumnWeights !== undefined;
+    const conflictsMulti =
+      alias.length === 3 && result.multiPlayerColumnWeights !== undefined;
+    if (conflictsSingle || conflictsMulti) delete result.columnWeights;
+  }
+  return result;
+}
+
 export function adaptersFromComposedConfig(config) {
   const adapters = new Set();
   const captainAdapter = config?.captain?.adapter;

package/reference/sdlc/code.playbook/code.playbook.d.ts

@@ -1,26 +1,6 @@
 import { type CaptainInput, type CaptainOutput, type CodingEvent, type CodingInput } from './code.fsm.js';
-export interface PlayerResult {
-    status: 'ok' | 'aborted' | 'error';
-    finalText?: string;
-    error?: string;
-}
-export interface PlaybookPorts {
-    callPlayer(playerId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
-    callJudge(prompt: string, signal: AbortSignal): Promise<string>;
-    emitStatus(message: string, data?: unknown): Promise<void>;
-    emitTelemetry(event: {
-        topic: string;
-        payload: unknown;
-    }): Promise<void>;
-}
-export interface PlaybookRuntime {
-    init(ports: PlaybookPorts): Promise<void>;
-    handleBossInput(turn: {
-        text: string;
-        signal: AbortSignal;
-    }): Promise<void>;
-    dispose(): Promise<void>;
-}
+import type { PlaybookPorts, PlaybookRuntime, PlayerResult } from '@sublang/playbook/runtime';
+export type { PlayerResult, PlaybookPorts, PlaybookRuntime };
 export type CodePlaybookOptions = CodingInput;
 declare function normalizeErrorCompact(err: unknown): {
     name: string;
@@ -76,4 +56,3 @@ export declare const _internal: {
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
 };
 export default function createPlaybookRuntime(options: CodePlaybookOptions): PlaybookRuntime;
-export {};

package/reference/sdlc/code.playbook/code.playbook.js

@@ -11,6 +11,9 @@
 //                alias's first alternative)
 // Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
+// Contract:      PlayerResult / PlaybookPorts / PlaybookRuntime imported
+//                and re-exported from @sublang/playbook/runtime
+//                (slc/link.md §Output, DR-004 Addendum A4)
 import { createActor, fromPromise } from 'xstate';
 import { codingMachine, } from './code.fsm.js';
 import { enumerateAwaitBossReply, enumerateCaptainStates, enumerateRootEvents, } from './code.fsm.introspect.js';

package/reference/sdlc/code.playbook/code.playbook.ts

@@ -11,6 +11,9 @@
 //                alias's first alternative)
 // Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
+// Contract:      PlayerResult / PlaybookPorts / PlaybookRuntime imported
+//                and re-exported from @sublang/playbook/runtime
+//                (slc/link.md §Output, DR-004 Addendum A4)
 
 import { createActor, fromPromise } from 'xstate';
 import {
@@ -25,33 +28,20 @@ import {
   enumerateCaptainStates,
   enumerateRootEvents,
 } from './code.fsm.introspect.js';
-
-// Public contract — `PlayerResult`, `PlaybookPorts`, `PlaybookRuntime`,
-// `CodePlaybookOptions`, and the default `createPlaybookRuntime` factory
-// per slc/link.md and DR-004 §10.
-
-export interface PlayerResult {
-  status: 'ok' | 'aborted' | 'error';
-  finalText?: string;
-  error?: string;
-}
-
-export interface PlaybookPorts {
-  callPlayer(
-    playerId: string,
-    prompt: string,
-    signal: AbortSignal,
-  ): Promise<PlayerResult>;
-  callJudge(prompt: string, signal: AbortSignal): Promise<string>;
-  emitStatus(message: string, data?: unknown): Promise<void>;
-  emitTelemetry(event: { topic: string; payload: unknown }): Promise<void>;
-}
-
-export interface PlaybookRuntime {
-  init(ports: PlaybookPorts): Promise<void>;
-  handleBossInput(turn: { text: string; signal: AbortSignal }): Promise<void>;
-  dispose(): Promise<void>;
-}
+import type {
+  PlaybookPorts,
+  PlaybookRuntime,
+  PlayerResult,
+} from '@sublang/playbook/runtime';
+
+// Public contract. `PlayerResult`, `PlaybookPorts`, and `PlaybookRuntime`
+// are re-exported from the shared `@sublang/playbook/runtime` module
+// (slc/link.md §Output, DR-004 Addendum A4) so this playbook and any
+// future one resolve one contract definition rather than redefining it.
+// `CodePlaybookOptions` and the default `createPlaybookRuntime` factory
+// (typed `PlaybookRuntimeFactory<CodePlaybookOptions>`) stay
+// CODE-specific.
+export type { PlayerResult, PlaybookPorts, PlaybookRuntime };
 
 export type CodePlaybookOptions = CodingInput;
 

package/reference/sdlc/code.playbook/playbook-code.config.template.yaml

@@ -27,7 +27,7 @@
 #   instead of requiring bypass permissions.
 # - players.committer optionally aliases the Committer to a role
 #   (coder or reviewer); that role's pane runs the commit turn. The
-#   seeded value is reviewer; omit it to fall back to the coder.
+#   seeded value is coder; omitting it uses the same Coder fallback.
 # - layout sizes the tmux window (layout.window: columns × rows) and
 #   sets the relative column widths (layout.columnWeights) for the
 #   Boss/Captain, Coder, and Reviewer columns.
@@ -49,24 +49,24 @@ notifications:
 
 captain:
   adapter: claude
-  model: claude-sonnet-4-6
+  model: claude-opus-4-8
   reasoningEffort: high
   permissions:
     mode: auto
 
 players:
   coder:
-    adapter: codex
-    model: gpt-5.5
+    adapter: claude
+    model: claude-opus-4-8[1m]
     reasoningEffort: xhigh
     permissions:
       mode: auto
-      writablePaths:
-        - .git
   reviewer:
-    adapter: claude
-    model: claude-opus-4-8
+    adapter: codex
+    model: gpt-5.5
     reasoningEffort: xhigh
     permissions:
       mode: auto
-  committer: reviewer
+      writablePaths:
+        - .git
+  committer: coder

package/reference/sdlc/code.playbook/tmux-play.config.yaml

@@ -19,12 +19,15 @@ captain:
   # shim that delegates to the same shell with CODE registered.
   from: ./playbook-captain.js
   adapter: claude
-  model: claude-sonnet-4-6
+  model: claude-opus-4-8
   reasoningEffort: high
   # Agents run in cligent's classifier/reviewer-protected auto mode
   # (cligent DR-005): claude → permissionMode auto, codex → auto_review.
   permissions:
     mode: auto
+  options:
+    code:
+      committer: coder
 
 # `players[].id` shall match the baked playerId strings the adapter
 # routes to. The CODE playbook bakes Coder→'coder' and
@@ -38,7 +41,7 @@ captain:
 players:
   - id: coder
     adapter: claude
-    model: claude-opus-4-7
+    model: claude-opus-4-8[1m]
     reasoningEffort: xhigh
     permissions:
       mode: auto
@@ -48,3 +51,5 @@ players:
     reasoningEffort: xhigh
     permissions:
       mode: auto
+      writablePaths:
+        - .git

package/reference/sdlc/code.playbook/tmux-play.production.config.yaml

@@ -13,15 +13,18 @@ notifications:
 captain:
   from: "@sublang/playbook/playbook-captain"
   adapter: claude
-  model: claude-sonnet-4-6
+  model: claude-opus-4-8
   reasoningEffort: high
   permissions:
     mode: auto
+  options:
+    code:
+      committer: coder
 
 players:
   - id: coder
     adapter: claude
-    model: claude-opus-4-7
+    model: claude-opus-4-8[1m]
     reasoningEffort: xhigh
     permissions:
       mode: auto
@@ -31,3 +34,5 @@ players:
     reasoningEffort: xhigh
     permissions:
       mode: auto
+      writablePaths:
+        - .git

package/slc/gears2fsm.md

@@ -0,0 +1,209 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# GEARS-to-Finite-State-Machine Transformation
+
+Second phase of a playbook (a state-machine agent orchestrating other agents).
+Transforms normative GEARS spec items into an XState v5 finite state machine.
+
+- Source: GEARS spec items produced by the first phase.
+- Target: an XState v5 machine object artifact [[1]].
+
+Target is an object artifact only: it defines the machine, actor contracts, and typed inputs, but shall not bind a runner or supply concrete runtime implementations.
+
+## Formats
+
+| Role | Format | Extension |
+| --- | --- | --- |
+| source | gears | .md |
+| target | fsm | .ts |
+
+## Setup
+
+The artifact shall use XState v5's `setup(...)` then `.createMachine(...)` [[10]].
+The `types` block shall declare `context`, `events`, machine `input`, and a typed `Captain` actor contract [[11]].
+The artifact shall not import a runner or bake in a concrete Captain implementation; any actor placeholder shall fail explicitly (e.g., throw `'captain actor must be provided by the runner'`).
+
+`CaptainInput` shall be a typed object with at least:
+
+- `player`: the [player](text2gears.md#players) Captain is to invoke;
+- `sourceItem`: the GEARS item ID this state realizes;
+- `prompt`: the source item's full final prompt, verbatim;
+- `result`: a record whose keys are the valid guard names this invocation may return.
+
+`CaptainOutput` shall be a discriminated object with `guard: string` and any extracted fields downstream states need.
+
+Guard names shall be specified and interpreted **per state**, not as a global union.
+A global union encourages name reuse with divergent semantics and couples unrelated states.
+Shared helpers may accept `string`, but each state's `invoke.input.result` is the authoritative local contract.
+
+## States
+
+Each state shall declare:
+
+- a stable `id` (for `#id` targeting and Boss interrupts);
+- an intuitive state key (the property name under `states: { ... }`);
+- a one-line `description` (for inspector tools and documentation);
+- if it invokes Captain: `invoke.input` carrying `player`, `sourceItem`, `prompt`, `result` (per [Setup](#setup)).
+
+The source item ID shall live in `invoke.input.sourceItem`, not in a comment — this keeps the GEARS-to-state mapping machine-readable.
+A state's `invoke.input.player` shall match its source item's player.
+
+Captain returns a discriminated result with `guard` set to one of `input.result`'s keys [[4]].
+Guards [[5]] on `onDone` transitions inspect `event.output.guard` to route.
+
+Example:
+
+```typescript
+invoke: {
+    src: 'captain',
+    input: ({ context }): CaptainInput => ({
+        player: 'Reviewer',
+        sourceItem: '<ITEM-A>',
+        prompt: [
+            'Flag any issues or improvements (numbered; no duplication).',
+            "Think thoroughly — don't just approve or reject.",
+        ].join('\n'),
+        result: {
+            hasFindings: 'Reviewer raised issues or suggestions.',
+            noFindings: 'Reviewer has no findings.',
+        },
+    }),
+    onDone: [...],
+    onError: { target: 'failed', actions: 'rememberCaptainError' },
+}
+```
+
+## Mapping
+
+Each Source spec item shall map to exactly one state in Target.
+A state's `invoke.input.sourceItem` shall be that item's ID, and `invoke.input.prompt` shall carry the item's prompt verbatim.
+
+Per text2gears [composition](text2gears.md#composition), each spec item already carries the full final prompt for one state behavior, with no duplicate lines.
+The FSM compiler shall not concatenate prompts across items, re-compose them, or silently dedupe.
+A spec item that still contains duplicate prompt lines is malformed; the compiler shall reject or flag it rather than silently propagate the duplication into `invoke.input.prompt`.
+
+## Context and prompts
+
+Context fields used to drive guards or compose prompts shall be **typed and named**.
+The compiler shall not branch on untyped properties of `lastResult`; persistent routing decisions belong in typed context fields. (`lastResult` is for inspection only.)
+
+Prompts shall pass only the **specific extracted fields** the player needs.
+The compiler shall not dump `JSON.stringify(lastResult)` or any opaque blob: it leaks internal `guard` strings, wastes tokens, and confuses the LLM.
+
+Player bindings and per-run parameters shall flow in via the machine's `input` and be copied into context at start-up.
+The artifact shall not bake in player bindings, model names, or per-run values.
+
+## Transitions
+
+A transition fires on an event — typically `onDone` (actor completed) [[4]].
+When multiple are possible, a synchronous guard [[5]] picks the path.
+Transitions shall persist relevant typed fields from `event.output` to context via `assign` [[6]] so downstream prompts can read them.
+Transitions shall be self-driving when source items define the next obligation.
+Routing to an idle hub is for recovery, unrecoverable Boss input, or one-shot entry events — not the happy path.
+
+### Auto-advance on approval
+
+A review/approval state's success outcome shall **target the next workflow step**, not idle back to a hub.
+Returning to Boss on success is a defect: it forces manual stepping.
+
+### Don't re-validate what already passed
+
+A state following an approval shall not enter a fresh approval of the same content — that adds latency and risks ping-pong loops.
+A state may route through approval once when its input came from an unreviewed branch (e.g., re-do without an intervening review).
+
+### One feedback cycle across phases
+
+When the source has a feedback cycle, all phases that need feedback shall reuse it, not duplicate it per phase.
+Phases may set typed routing fields so terminal outcomes return to the originating branch.
+
+## Boss control
+
+[Boss](text2gears.md#players) input enters the machine through three surfaces: pre-emptive interrupts on active states, typed entry events on idle or recoverable states, and Boss replies to player questions that suspended the FSM in a dedicated wait state.
+
+### Boss interrupts
+
+Boss may interrupt any active state at any time. Every jumpable state shall have a stable `id` [[9]].
+The runtime sends `{ type: 'BOSS_INTERRUPT', targetId: '<id>' }`; the root machine handles it with one guarded transition per jumpable state targeting `#<id>` with `reenter: true` [[7]][[8]][[9]], so invoked actors restart cleanly.
+The compiler shall emit a `bossInterrupts(ids)` helper rather than hand-writing one transition per state.
+XState automatically stops the current state's invoked actor on transition [[2]].
+
+### Boss entry events vs. BOSS_INTERRUPT
+
+`BOSS_INTERRUPT` jumps into an **active** machine, pre-empting whichever state is running.
+**Boss entry events** start or resume from idle or recoverable states when Boss-supplied parameters can't be inferred from machine state alone.
+Entry events shall be typed alongside `BOSS_INTERRUPT` and populate context via a dedicated action.
+The two surfaces shall not be collapsed: `BOSS_INTERRUPT` cannot carry payload, and a parameterless entry event may collapse to interrupt-style routing only when state-jump semantics are identical.
+Entry events shall not be root-level transitions from every active state unless the workflow supports pre-emption; they belong on idle and recoverable states (e.g., `failed`).
+
+### Boss-reply suspension
+
+When a captain-invoking state needs a Boss decision the player cannot supply alone, the machine shall suspend in a dedicated quiescent state and resume the same state with the Q+A in the next prompt.
+This is a third Boss surface alongside `BOSS_INTERRUPT` and Boss entry events.
+
+Every captain-invoking state supports this path.
+There is no source-level opt-in annotation and no `needsBossReply` result metadata in GEARS output.
+The FSM compiler shall preserve the GEARS blockquote as the state's domain `prompt` body and shall not inject any Boss-question instruction into `invoke.input.prompt`.
+
+For every captain-invoking state, the compiler shall add `needsBossReply` to the state's `invoke.input.result` map.
+The description shall be the standard adjudicator-facing text:
+
+```text
+The player's prose surfaces a clarifying question for Boss that the player cannot answer alone. Output shall include `question: <verbatim question text from the player's prose>`.
+```
+
+It shall include the load-bearing substring ``Output shall include `question:`` so the runtime's adjudicator requires `question` in the JSON reply.
+The linked runtime composes player prompts per [link.md "Player prompt composition"](link.md#player-prompt-composition), without adding a player-visible Boss-question instruction.
+
+The machine shall declare:
+
+- An `awaitBossReply` state with stable `id: 'awaitBossReply'` and `description: 'Waiting for Boss to answer a player question.'`.
+- A `BOSS_REPLY` event carrying `{ answer: string }`.
+- Context fields `pendingBossQuestion?: { resumeStateId, sourceItem, player, question }` and `bossReply?: string`.
+  Field provenance is normative: `resumeStateId`, `sourceItem`, and `player` shall come from the suspended state's invocation metadata; only `question` shall come from adjudicated player output.
+
+The compiler shall emit three helpers:
+
+- `resumableStates(ids)` — emits one `BOSS_REPLY` arm per registered state on `awaitBossReply.on.BOSS_REPLY`, each guarded on `context.pendingBossQuestion?.resumeStateId === '<id>'` and targeting `'#<id>'` with `reenter: true`.
+  The compiler shall register every captain-invoking state id with this helper.
+  The helper is analogous to `bossInterrupts(ids)`.
+- `setPendingBossQuestion` — `assign({ pendingBossQuestion: <new>, bossReply: undefined })`.
+  Used on every `needsBossReply` arm; clearing `bossReply` here prevents a follow-up question from inheriting the prior answer.
+- `clearBossReplyContext` — `assign({ pendingBossQuestion: undefined, bossReply: undefined })`.
+  Used on every transition out of `awaitBossReply` other than the resume arm, and on every non-`needsBossReply` outcome of a captain-invoking state.
+
+`awaitBossReply` is a quiescent state for the runtime's drive loop.
+It shall declare the standard `bossInterrupts(ids)` handler with `actions: clearBossReplyContext`, so a Boss interrupt event abandons a pending question.
+The machine's root-level Boss entry events shall be re-declared on `awaitBossReply` with `actions: clearBossReplyContext`, so a fresh Boss directive while waiting starts a fresh turn and clears stale context.
+
+A captain-invoking state's `invoke.input` function shall carry `pendingBossQuestion` and `bossReply` fields when present so the linked runtime can compose the continuation prompt.
+When both fields are present, the linked runtime shall compose the continuation preamble and labelled Q&A blocks per [link.md "Player prompt composition"](link.md#player-prompt-composition).
+The FSM artifact shall not bake the continuation preamble into the GEARS-derived `prompt` body.
+
+The following malformed states shall route to `failed` per [Errors and termination](#errors-and-termination):
+
+- Captain output has `guard: 'needsBossReply'` but no `question` field.
+- Captain output declares `needsBossReply` from a state not registered with `resumableStates(ids)`.
+- `BOSS_REPLY` fired with empty or whitespace-only `answer`.
+
+## Errors and termination
+
+Every `invoke` shall declare an `onError` handler routing to a dedicated `failed` state, with the error captured in `context.lastError` for inspection.
+`failed` is not `final`: Boss may interrupt out of it to recover.
+
+Every machine shall declare at least one `type: 'final'` state (typically `done`) reachable on completion.
+A never-terminating machine is a defect: the runner has no completion signal.
+
+## References
+
+[1]: https://stately.ai/docs/xstate "XState Official Documentation"
+[2]: https://stately.ai/docs/invoke "Invoke — invoking actors from states"
+[3]: https://stately.ai/docs/input "Input — passing data to invoked actors"
+[4]: https://stately.ai/docs/output "Output — receiving actor results via onDone"
+[5]: https://stately.ai/docs/guards "Guards — synchronous transition conditions"
+[6]: https://stately.ai/docs/context "Context — persistent state and assign"
+[7]: https://stately.ai/docs/transitions "Transitions — reenter, root-level routing"
+[8]: https://stately.ai/docs/parent-states "Parent states — root-level event handling"
+[9]: https://stately.ai/docs/finite-states "Finite states — state IDs"
+[10]: https://stately.ai/docs/setup "Setup — typed machine setup"
+[11]: https://stately.ai/docs/actors "Actors — typed actor contracts"

package/slc/link.md

@@ -0,0 +1,341 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# FSM-to-Runtime Linking
+
+Third phase of a playbook (a state-machine agent orchestrating other agents).
+Compiles the [gears2fsm](gears2fsm.md) artifact into a **`PlaybookRuntime`**: a host-agnostic runner that:
+
+- Drives the FSM.
+- Classifies Boss input into typed events.
+- Runs the Captain-actor against the playbook's players.
+- Adjudicates player output into FSM guards.
+- Surfaces transitions as status/telemetry.
+
+The runtime is invoked through the stable `PlaybookPorts` contract.
+Presentation layers (tmux-play, web, CLI, tests) implement the four ports once and inherit every playbook.
+
+- Source: an XState v5 machine artifact (`.fsm.ts`) produced by gears2fsm.
+- Target: a `PlaybookRuntime` factory module — TypeScript, host-agnostic.
+
+Hosts are out of scope for this phase.
+Each host has a small adapter (~30 lines) that loads a `PlaybookRuntime` module and supplies the host's primitives as `PlaybookPorts`.
+The adapter shall speak only `PlaybookPorts` to the runtime and shall not leak host types back into it.
+
+The link compiler shall not modify the FSM artifact and shall not re-derive Captain prompts, result keys, or guard semantics — those are fixed by the FSM.
+
+## Formats
+
+| Role | Format | Extension |
+| --- | --- | --- |
+| source | fsm | .ts |
+| target | playbook | .ts |
+
+## PlaybookRuntime contract
+
+The emitted module shall default-export a factory of the following shape:
+
+```typescript
+interface PlaybookRuntime {
+  init(ports: PlaybookPorts): Promise<void>;
+  handleBossInput(turn: { text: string; signal: AbortSignal }): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+type PlaybookRuntimeFactory<Options = unknown> = (
+  options: Options,
+) => PlaybookRuntime;
+
+export default function createPlaybookRuntime(
+  options: PlaybookRuntimeOptions,
+): PlaybookRuntime;
+```
+
+The default export conforms to `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`, the generic factory type the shared contract module exposes (§Output).
+
+`init` receives the host's ports, constructs the XState actor with FSM `input` derived from `options`, and starts the actor.
+The runtime owns the actor for its lifetime; `handleBossInput` runs one turn, and `dispose` stops the actor and drains pending port emissions.
+
+`PlaybookRuntimeOptions` is host-agnostic and carries only *per-run* knobs such as identity strings (e.g., model names a playbook substitutes into prompt placeholders) and strategy overrides the linker exposes.
+The link compiler emits a typed options interface per playbook based on the FSM's `CodingInput` (or equivalent).
+
+Player binding is a *linker-time* input baked into the emitted runtime by default.
+A linker may also expose it via `PlaybookRuntimeOptions` for per-run remapping; the contract requires only that the runtime ship with a deterministic binding it applies at every `callPlayer` site.
+
+## PlaybookPorts contract
+
+```typescript
+interface PlaybookPorts {
+  callPlayer(playerId: string, prompt: string, signal: AbortSignal):
+    Promise<PlayerResult>;
+  callJudge(prompt: string, signal: AbortSignal):
+    Promise<string>;
+  emitStatus(message: string, data?: unknown): Promise<void>;
+  emitTelemetry(event: { topic: string; payload: unknown }): Promise<void>;
+}
+
+interface PlayerResult {
+  status: 'ok' | 'aborted' | 'error';
+  finalText?: string;
+  error?: string;
+}
+```
+
+`PlayerResult` mirrors cligent's `PlayerRunResult` shape ([TMUX-033](https://github.com/sublang-ai/cligent/blob/main/specs/user/tmux-play.md#tmux-033)), so a tmux-play port adapter is direct assignment.
+The runtime treats `status !== 'ok'` as a player failure and routes it through the FSM's error path (§Abort).
+
+`callJudge` returns free-form text.
+The runtime parses it per the state's adjudication strategy (§Captain adjudication).
+One port serves both classifier and adjudicator — they vary only in prompt.
+
+`emitStatus` is human-readable; `emitTelemetry` is structured.
+Both are async and shall be ordered, awaited, and never-dropped; the runtime awaits each emission before issuing the next.
+
+The runtime never speaks to LLMs directly and never touches host types beyond `PlaybookPorts`.
+
+## Linker inputs
+
+The link compiler shall accept:
+
+- The FSM artifact (path to a `.fsm.ts`).
+- A **player binding** mapping GEARS players (declared in the
+  [text2gears](text2gears.md#players) source) to opaque player-identifier
+  strings.
+- An **adjudication strategy** (default: LLM-judge per state) and a
+  **Boss-event mapping** (default: free-text judge classification).
+  Both strategies are host-agnostic.
+
+The host's identity does not enter compilation; the linked module runs unchanged under any host that implements `PlaybookPorts`.
+
+## Player binding
+
+Each GEARS state names exactly one player (`invoke.input.player`).
+The linker shall map every named player to a `playerId` string used in `PlaybookPorts.callPlayer(playerId, …)`.
+The host adapter routes that opaque string to its concrete primitive.
+
+For composite players declared with aliases (e.g., `Committer = Coder | Reviewer`), the linker shall resolve the alias **per source item**.
+Resolution inspects the `CaptainInput` fields populated at that state:
+
+- If only one `<playerName>Player` field is present, bind to that player.
+- If multiple are present, prefer the first-listed alternative in the alias declaration order.
+- If none are present, fall back to the alias's first alternative.
+
+Resolution shall be deterministic and recorded in the emitted module so future maintainers can audit it without re-running the linker.
+
+The linker shall not invent player identifiers and shall not silently collapse aliases at the FSM level — composite players keep their `player: 'Committer'` value on `CaptainInput`; resolution decides only the `callPlayer` invocation.
+
+## Player prompt composition
+
+The runtime shall compose the actual player prompt from the state's `CaptainInput`.
+`input.prompt` is the GEARS-derived domain prompt body and shall not be mutated, re-flowed, or treated as a place to store framework control instructions.
+
+The composer may prepend structured labelled blocks from typed `CaptainInput` fields the FSM exposes (for example `Boss intent:`, `Review items:`, `Rebuttals:`, or `Task description:`).
+Those blocks are outside the domain prompt body.
+
+The composer shall not inject a player-visible Boss-question instruction.
+Boss-question detection is adjudicator-facing: it comes from the state's `needsBossReply` result description, not from extra prompt text.
+
+When `CaptainInput` carries both `pendingBossQuestion` and `bossReply`, the composer shall prepend the continuation preamble and labelled Q&A blocks before ordinary structured blocks and before the domain prompt body:
+
+```text
+You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.
+
+Boss question:
+<pendingBossQuestion.question>
+
+Boss reply:
+<bossReply>
+```
+
+The continuation preamble is framework text supplied by the runtime.
+It is not part of the GEARS blockquote and shall not appear in `invoke.input.prompt`.
+
+## Boss-event mapping
+
+The FSM's `events` union enumerates every Boss-originated event.
+The runtime receives Boss input as a free-form string (`handleBossInput.text`) and shall classify each non-empty turn into one of the FSM's events plus its payload, or no FSM action, by invoking `callJudge`.
+Empty or whitespace-only text produces no event and no port call.
+
+The classifier prompt shall demand JSON against the FSM's typed event union and any state-specific Boss input contract, including the payload fields required for each event.
+When the FSM supports a Boss-reply suspension state, the prompt shall include the current state and the pending Boss question so the judge can distinguish a reply from a fresh directive.
+
+A playbook runtime shall not define slash-prefix commands for states or features inside that playbook.
+The `/command` namespace is reserved for host-level or playbook-selection UX before a turn reaches `handleBossInput`.
+If a host forwards text beginning with `/` to `handleBossInput`, the runtime treats it as ordinary Boss text and classifies it through `callJudge`.
+
+Hosts that receive structured control input shall resolve host-level concerns before choosing a playbook runtime.
+Once they call `handleBossInput`, they shall pass the Boss content as text and shall not pre-classify in-playbook FSM events or rely on slash forms as a runtime protocol.
+
+`BOSS_INTERRUPT` (or the FSM's equivalent explicit-state-jump event) is reached only by the judge choosing it and supplying its required target payload.
+It is *not* an abort surface; aborts go through the abort signal and the strategies in §Abort.
+Hosts where the abort signal is terminal (e.g., SIGINT runs shutdown) shall not route abort to `BOSS_INTERRUPT`.
+
+## Captain adjudication
+
+After a player call returns, the runtime shall coerce `result.finalText` into one of the **per-state** `invoke.input.result` keys.
+It shall also extract any payload fields the state's `result` description names as required.
+
+Two default adjudication strategies, in selection order:
+
+- **LLM-judge** (default): construct a fresh prompt for `callJudge` that
+  names the source item's player, includes the player's verbatim output,
+  lists the `result` keys with their descriptions, and demands a JSON
+  `{ guard, …payloadFields }` answer keyed to exactly one of the
+  declared guards. The judge prompt shall not interpret the player's
+  output, paraphrase it, or alter the FSM's `result` text — it carries
+  the description verbatim.
+- **Marker-parse** (alternative): a deterministic parser that scans the
+  player output for a terminal control line such as
+  `FSM-RESULT: { "guard": "...", ... }`. Useful when player adapters can
+  be steered to emit structured trailers and the operator wants to avoid
+  the extra LLM call.
+
+The linker may select different strategies per state; the default is **LLM-judge for every state**.
+
+The adjudicator shall fail loudly on:
+
+- A guard the state does not declare,
+- A missing payload field the state's `result` description requires,
+- An empty / malformed response.
+
+Adjudicator failures are control-plane errors.
+The runtime shall propagate them by throwing out of `handleBossInput` after attempting cleanup.
+The host adapter surfaces the throw on its control-plane channel (cligent surfaces such throws as `runtime_error` per [TMUX-025](https://github.com/sublang-ai/cligent/blob/main/specs/user/tmux-play.md#tmux-025)).
+The host's player-result channels (`player_finished` and equivalents) are reserved for failures the player itself produced; the host emits them when `callPlayer` resolves with `status !== 'ok'`.
+
+## Session lifecycle
+
+The `PlaybookRuntime` shall:
+
+- In `init`, construct the XState actor with FSM `input` derived from
+  `options`. The actor is session-scoped, not turn-scoped. Subscribe to
+  actor snapshots so each transition can be surfaced via `emitStatus`
+  and `emitTelemetry` before the next event fires. Start the actor.
+- Per `handleBossInput`:
+  1. Classify `turn.text` through the Boss-event mapping.
+     If it produces no event, return after draining any port emissions.
+  2. If the actor is in a `final` state, dispose and reconstruct it —
+     `final` is terminal and cannot accept new events.
+  3. Send the classified event to the actor.
+  4. **Drive to quiescence**: each time the actor invokes its `captain`
+     actor, await the invoke's input, build a player prompt, call
+     `callPlayer`, adjudicate, and resolve the invoke. Repeat until the
+     actor's snapshot value is a state that takes a Boss event
+     (typically `ready` or `failed`) or a `final` state.
+- In `dispose`, stop the actor and drain pending port emissions.
+
+The actor's `lastError` field shall be surfaced via `emitStatus` when the machine enters its `failed` state.
+
+## Abort
+
+`handleBossInput.signal` is the abort surface.
+The runtime shall honor it at every `callPlayer`/`callJudge` and at every poll between transitions.
+On abort, the runtime shall drive the actor to a quiescent state before returning from the turn.
+Three strategies are permitted; the linker selects per FSM:
+
+- **Natural rejection** — the runtime's Captain actor (e.g.,
+  `fromPromise`) ends the invocation by rejecting, and the FSM routes
+  the rejection through `onError` to a quiescent sink. The cancelled
+  port call may *itself* reject, or it may resolve with
+  `PlayerResult { status: 'aborted' | 'error' }` that the runtime
+  inspects and converts into a Captain-actor rejection. Either shape
+  is permitted — the contract is on the Captain-actor boundary, not on
+  the port's promise behavior. Preferred when every Captain-invoking
+  state's `onError` lands somewhere quiescent; the FSM's own error
+  wiring is the abort path.
+- **Synthetic pre-emption to a quiescent target** — send the FSM's
+  pre-emption event (e.g., `BOSS_INTERRUPT { targetId: <state> }`) with
+  a target that is itself quiescent (typically `ready` or `failed`).
+  The runtime shall not pick the active state as the target:
+  `gears2fsm.md` prescribes `reenter: true` for `bossInterrupts`, so
+  re-entering the active state restarts its `invoke` and spawns a
+  fresh player call.
+- **Programmatic stop** — `actor.stop()` and report the turn as aborted
+  via `emitStatus`. Reserved for FSMs with neither `onError` wiring nor
+  a pre-emption event.
+
+Whether the host's outer abort (e.g., SIGINT) is recoverable or terminal is the host's concern.
+The runtime exits `handleBossInput` cleanly in either case; the host decides whether to call `dispose` afterward.
+
+## Status and telemetry
+
+The runtime shall emit, at minimum:
+
+- One `emitStatus` per Boss-relevant transition (entering a state whose
+  semantics matter to Boss — e.g., `respondToReview`, `failed`). The
+  default is to emit on every transition and let the host filter; hosts
+  may bind a stricter rule.
+- One `emitTelemetry` per state transition under a namespaced topic
+  (recommended `playbook.fsm.state`), with payload `{ from, to, event }`.
+  Observers consume telemetry; the runtime never interprets the topic.
+
+Player prompts and adjudicator JSON ride the host's own record channels when the host has them (cligent's `captain_*` / `player_*`).
+The runtime shall not duplicate them into `emitTelemetry`.
+
+## Output
+
+The link compiler emits **one** TypeScript module that:
+
+- Imports the FSM artifact by relative path.
+- Imports XState's actor primitives (`createActor`, `fromPromise`,
+  `setup`'s `.provide`).
+- Exports `createPlaybookRuntime` and the typed `PlaybookRuntimeOptions`
+  interface for that playbook.
+- Holds no host-specific types and no host primitive calls. The runtime
+  speaks only `PlaybookPorts`.
+- Records the linker inputs (FSM path, player binding, strategies) in a
+  top-of-file header comment so the file is reproducible from the same
+  inputs.
+- Sources the contract types (`PlayerResult`, `PlaybookPorts`,
+  `PlaybookRuntime`, `PlaybookRuntimeFactory`) from a single shared
+  type-only module instead of redefining them, and re-exports the names
+  its consumers import, so every linked playbook shares one contract
+  definition. The shared module imports no FSM or host types, so the
+  dependency runs one way — from each linked module to the shared
+  contract, never the reverse.
+
+## Host adaptation (informative, not normative)
+
+A host integrates with playbooks via a small adapter that:
+
+1. Accepts a path to a `PlaybookRuntime` module (either as a direct
+   import in a playbook-specific adapter, or via the host's config
+   surface in a generic adapter).
+2. Imports the module and constructs the runtime with options forwarded
+   verbatim from the host config.
+3. Implements `PlaybookPorts` by wrapping the host's own primitives —
+   for cligent/tmux-play this is `callPlayer ← context.callPlayer`,
+   `callJudge ← context.callCaptain`, `emitStatus`/`emitTelemetry` ←
+   `session.emitStatus`/`session.emitTelemetry`.
+4. Calls `runtime.init(ports)` once at session start, forwards each
+   Boss turn to `runtime.handleBossInput`, and calls
+   `runtime.dispose()` at session end.
+
+The adapter is ~30 lines regardless of which playbook is loaded.
+Its location is a project-organization choice:
+
+- **Playbook repo** — simplest when the playbook author owns the integration; keeps host primitives a lower-layer dependency.
+- **Host repo** — when the host author wants to ship an opt-in playbook Captain.
+- **Third package** — otherwise.
+
+This spec is silent on the choice; the contract is the same in any location.
+
+## Out of scope
+
+- Defining player prompts, result keys, or guard semantics — those
+  belong in the GEARS source and the FSM artifact.
+- Host adapter implementations, host configuration, presentation
+  layouts — where these live is a per-project decision (see
+  §Host adaptation); this spec only constrains the `PlaybookPorts`
+  contract they satisfy.
+- Persisting FSM context across sessions, multi-Boss orchestration, or
+  visualizer rendering — separate hosts/observers may add them without
+  changing this spec.
+
+New behavior in any of these areas requires a separate slc spec.
+
+## References
+
+[1]: [text2gears](text2gears.md) "First phase: text → GEARS spec items."
+[2]: [gears2fsm](gears2fsm.md) "Second phase: GEARS items → FSM artifact."
+[3]: https://stately.ai/docs/actors "XState actors — `createActor`, snapshots, abort signal handling."

package/slc/text2gears.md

@@ -0,0 +1,85 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Text-to-GEARS Transformation
+
+First phase of a playbook (a state-machine agent orchestrating other agents).
+Transforms a user's procedure description into normative GEARS [[1]] spec items.
+
+- Source: free-form natural-language description.
+- Target: a package of GEARS spec items.
+
+The second phase (spec items → state machine) is out of scope.
+
+## Formats
+
+| Role | Format | Extension |
+| --- | --- | --- |
+| source | text | .md |
+| target | gears | .md |
+
+## Players
+
+Players name AI agents and the user.
+
+Two default players:
+
+- Boss: the human user
+- Captain: the coordinating agent
+
+Source may declare additional players in an opening `Players:` section.
+A player may alias other players with `=` and `|`; Boss picks one at runtime.
+E.g.:
+
+- Coder
+- Reviewer
+- Committer = Coder | Reviewer
+
+Capitalize English player names (e.g., `Writer`); quote non-English names (e.g., `作者`) when needed to distinguish from prose.
+
+## Behaviors
+
+Each spec item names a condition, the player to prompt, and the prompt itself.
+Prompts shall be blockquoted, one point per line.
+
+E.g.:
+
+```markdown
+### CODE-10
+
+When Reviewer is about to review any change, Captain shall prompt Reviewer:
+> Flag any issues or improvements (numbered; no duplication).
+> Think thoroughly — don't just approve or reject.
+> If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
+```
+
+Target should be written in the same language as Source.
+
+## Composition
+
+Source snippets may overlap or duplicate.
+When composing them into a spec item, text2gears shall deduplicate identical prompt lines.
+
+Each spec item addresses one state behavior and carries its full final prompt (the static part).
+Cross-item duplication is acceptable: spec items are compiled artifacts; Source is what users maintain.
+
+Test: a human shall be able to simulate a run by copying any single item's prompt verbatim — no cross-item composition needed.
+
+### Placeholders vs literals
+
+Use `<placeholder>` for dynamic values in blockquoted prompts.
+Everything else inside a blockquote is static text, not an example; examples belong in surrounding prose.
+
+### Split by content discriminator
+
+Partition items by every variable that determines prompt content — including accumulated state when the trigger alone doesn't.
+
+### Prune dead disjuncts
+
+Drop disjunctive branches incompatible with the rest of an item's condition or prompt.
+Dead branches mislead readers and downstream phases.
+
+## References
+
+[1]: [GEARS syntax](/specs/meta.md#item-syntax)

package/src/runtime.d.ts

@@ -0,0 +1,23 @@
+export interface PlayerResult {
+    status: 'ok' | 'aborted' | 'error';
+    finalText?: string;
+    error?: string;
+}
+export interface PlaybookPorts {
+    callPlayer(playerId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
+    callJudge(prompt: string, signal: AbortSignal): Promise<string>;
+    emitStatus(message: string, data?: unknown): Promise<void>;
+    emitTelemetry(event: {
+        topic: string;
+        payload: unknown;
+    }): Promise<void>;
+}
+export interface PlaybookRuntime {
+    init(ports: PlaybookPorts): Promise<void>;
+    handleBossInput(turn: {
+        text: string;
+        signal: AbortSignal;
+    }): Promise<void>;
+    dispose(): Promise<void>;
+}
+export type PlaybookRuntimeFactory<Options = unknown> = (options: Options) => PlaybookRuntime;

package/src/runtime.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Public runtime contract for @sublang/playbook — the type-only single
+// source for the PlaybookPorts / PlaybookRuntime contract authored in
+// slc/link.md. It imports no CODE or FSM types, so the dependency runs
+// one way: linked playbook runtimes (e.g. code.playbook.ts) import and
+// re-export these names rather than redefining them
+// (PBRT-5, PBRT-34, DR-004 Addendum A4).
+export {};

package/src/runtime.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Public runtime contract for @sublang/playbook — the type-only single
+// source for the PlaybookPorts / PlaybookRuntime contract authored in
+// slc/link.md. It imports no CODE or FSM types, so the dependency runs
+// one way: linked playbook runtimes (e.g. code.playbook.ts) import and
+// re-export these names rather than redefining them
+// (PBRT-5, PBRT-34, DR-004 Addendum A4).
+
+export interface PlayerResult {
+  status: 'ok' | 'aborted' | 'error';
+  finalText?: string;
+  error?: string;
+}
+
+export interface PlaybookPorts {
+  callPlayer(
+    playerId: string,
+    prompt: string,
+    signal: AbortSignal,
+  ): Promise<PlayerResult>;
+  callJudge(prompt: string, signal: AbortSignal): Promise<string>;
+  emitStatus(message: string, data?: unknown): Promise<void>;
+  emitTelemetry(event: { topic: string; payload: unknown }): Promise<void>;
+}
+
+export interface PlaybookRuntime {
+  init(ports: PlaybookPorts): Promise<void>;
+  handleBossInput(turn: { text: string; signal: AbortSignal }): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+export type PlaybookRuntimeFactory<Options = unknown> = (
+  options: Options,
+) => PlaybookRuntime;