@sublang/playbook 0.1.2 → 0.2.0

package/README.md

@@ -34,9 +34,12 @@ committer loop end to end.
 
 The reference is the canonical worked example —
 [CODE source](reference/sdlc/code.md) →
-[gears](code.gears.md) →
-[FSM](code.fsm.ts) → runtime — with the
-runtime ported to cligent's `tmux-play` host out of the box.
+[gears](reference/sdlc/code.playbook/code.gears.md) →
+[FSM](reference/sdlc/code.playbook/code.fsm.ts) → runtime — with
+the runtime ported to cligent's `tmux-play` host out of the box.
+The compiled artifacts live under
+[`reference/sdlc/code.playbook/`](reference/sdlc/code.playbook),
+the slc pipeline's `<basename>.<pipeline>/` output directory.
 
 ### Install (users)
 
@@ -53,6 +56,9 @@ Each adapter reads its own auth: the Claude SDK uses your local
 Claude Code auth (or `ANTHROPIC_API_KEY`); the Codex SDK uses your
 local codex CLI auth (or `OPENAI_API_KEY`).
 
+The bundled configs run each agent in cligent's protected auto mode
+(`permissions.mode: auto`), suppressing routine approval prompts.
+
 Then launch the reference playbook in a `tmux-play` session:
 
 ```sh
@@ -77,7 +83,7 @@ pnpm build
 pnpm test
 ```
 
-`pnpm install` resolves `@sublang/cligent` (≥ 0.3.0) from the registry;
+`pnpm install` resolves `@sublang/cligent` (^0.4.0) from the registry;
 no local link required. To point pnpm at a local `cligent` checkout
 instead, copy
 [`pnpm-workspace.yaml.example`](pnpm-workspace.yaml.example)
@@ -85,11 +91,11 @@ into place; the override is gitignored so it never leaks into a
 production install.
 
 Drive a Boss turn against the source tree (uses the developer
-[`tmux-play.config.yaml`](tmux-play.config.yaml)
+[`tmux-play.config.yaml`](reference/sdlc/code.playbook/tmux-play.config.yaml)
 that imports the compiled adapter via relative path):
 
 ```sh
-pnpm exec tmux-play --config tmux-play.config.yaml
+pnpm exec tmux-play --config reference/sdlc/code.playbook/tmux-play.config.yaml
 ```
 
 `pnpm exec` resolves `tmux-play` from the package's local
@@ -98,16 +104,16 @@ installed globally.
 
 ### Running a Boss turn
 
-The Boss pane accepts four slash commands per
-[PBRT-1](specs/user/playbook-runtime.md#pbrt-1):
-
-- `/start <intent>` — begin a single coding turn
-- `/continue <#>` — pick up an IR task
-- `/summarize <#>` — turn an IR's commits into spec items
-- `/interrupt <stateId> [intent]` — preempt the FSM into a named state
+The Boss pane takes plain-language turns; the judge classifies each
+into an FSM event (start a coding turn, continue or summarize an IR,
+interrupt to a named state, or nothing) per
+[PBRT-1](specs/user/playbook-runtime.md#pbrt-1).
+When a player surfaces a clarifying question
+the FSM parks at `awaitBossReply` and the pane shows the question; your
+next turn is normally classified as the reply, or a fresh directive
+abandons it ([PBRT-2](specs/user/playbook-runtime.md#pbrt-2)).
 
-Anything else falls through to an LLM classifier. The Captain pane
-streams the state machine progression with a four-glyph vocabulary —
+The Captain pane streams the state machine with a four-glyph vocabulary —
 `◆ ▸ ⮕ ⤷` per [PBRT-3](specs/user/playbook-runtime.md#pbrt-3) — while
 player prompts ride their own panes.
 
@@ -135,14 +141,14 @@ const runtime = createPlaybookRuntime({
 
 await runtime.init(ports);
 await runtime.handleBossInput({
-  text: '/start fix the bug',
+  text: 'Start fixing the bug',
   signal: new AbortController().signal,
 });
 await runtime.dispose();
 ```
 
 See
-[`code.playbook.test.ts`](code.playbook.test.ts)
+[`code.playbook.test.ts`](reference/sdlc/code.playbook/code.playbook.test.ts)
 for the full range of port shapes (classifier, judge, abort, interrupt,
 status/telemetry) the runtime is contract-tested against.
 
@@ -175,7 +181,10 @@ package.
 - Node.js ≥ 20.6.0 (the `playbook-code` shim uses
   `import.meta.resolve`, unflagged since this release)
 - pnpm 9 (for the reference package)
-- A configured `tmux-play` host (for live Boss turns)
+- A configured `tmux-play` host (for live Boss turns) — requires
+  `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation)
+  on `PATH`; cligent 0.4+ uses `glow` to render Markdown pane
+  output and fails fast without it
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and tmux-play adapter for a coder/reviewer/committer loop driven by GEARS spec items.",
   "license": "Apache-2.0",
@@ -25,34 +25,34 @@
     "node": ">=20.6.0"
   },
   "files": [
-    "code.fsm.ts",
-    "code.fsm.js",
-    "code.fsm.d.ts",
-    "code.fsm.introspect.ts",
-    "code.fsm.introspect.js",
-    "code.fsm.introspect.d.ts",
-    "code.playbook.ts",
-    "code.playbook.js",
-    "code.playbook.d.ts",
-    "code.tmux-play.ts",
-    "code.tmux-play.js",
-    "code.tmux-play.d.ts",
-    "code.gears.md",
-    "tmux-play.config.yaml",
-    "tmux-play.production.config.yaml",
-    "bin"
+    "reference/sdlc/code.playbook/code.fsm.ts",
+    "reference/sdlc/code.playbook/code.fsm.js",
+    "reference/sdlc/code.playbook/code.fsm.d.ts",
+    "reference/sdlc/code.playbook/code.fsm.introspect.ts",
+    "reference/sdlc/code.playbook/code.fsm.introspect.js",
+    "reference/sdlc/code.playbook/code.fsm.introspect.d.ts",
+    "reference/sdlc/code.playbook/code.playbook.ts",
+    "reference/sdlc/code.playbook/code.playbook.js",
+    "reference/sdlc/code.playbook/code.playbook.d.ts",
+    "reference/sdlc/code.playbook/code.tmux-play.ts",
+    "reference/sdlc/code.playbook/code.tmux-play.js",
+    "reference/sdlc/code.playbook/code.tmux-play.d.ts",
+    "reference/sdlc/code.playbook/code.gears.md",
+    "reference/sdlc/code.playbook/tmux-play.config.yaml",
+    "reference/sdlc/code.playbook/tmux-play.production.config.yaml",
+    "reference/sdlc/code.playbook/bin"
   ],
   "bin": {
-    "playbook-code": "bin/playbook-code.js"
+    "playbook-code": "reference/sdlc/code.playbook/bin/playbook-code.js"
   },
   "exports": {
     "./code/playbook": {
-      "types": "./code.playbook.d.ts",
-      "default": "./code.playbook.js"
+      "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
+      "default": "./reference/sdlc/code.playbook/code.playbook.js"
     },
     "./code/tmux-play": {
-      "types": "./code.tmux-play.d.ts",
-      "default": "./code.tmux-play.js"
+      "types": "./reference/sdlc/code.playbook/code.tmux-play.d.ts",
+      "default": "./reference/sdlc/code.playbook/code.tmux-play.js"
     }
   },
   "scripts": {
@@ -66,7 +66,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@openai/codex-sdk": "^0.130.0",
-    "@sublang/cligent": "^0.3.0",
+    "@sublang/cligent": "^0.4.0",
     "xstate": "^5.19.4"
   },
   "devDependencies": {

package/{code.fsm.d.ts → reference/sdlc/code.playbook/code.fsm.d.ts}

@@ -4,6 +4,13 @@ type WorkflowKind = 'singleCommit' | 'iteration' | 'specSummary';
 type ChangeOrigin = 'bossIntent' | 'irTask';
 type ReviewSubject = 'commit' | 'changes';
 type AfterReview = 'continueIr' | 'summarizeSpecs' | 'done';
+type ResumableStateId = Exclude<JumpableStateId, 'ready' | 'failed'>;
+type PendingBossQuestion = {
+    resumeStateId: ResumableStateId;
+    sourceItem: string;
+    player: Player;
+    question: string;
+};
 export type CaptainInput = {
     player: Player;
     sourceItem: string;
@@ -16,6 +23,8 @@ export type CaptainInput = {
     challenges?: string;
     coderPlayer?: string;
     reviewerPlayer?: string;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
 };
 export type CaptainOutput = {
     guard: string;
@@ -24,6 +33,7 @@ export type CaptainOutput = {
     reviews?: string;
     challenges?: string;
     summary?: string;
+    question?: string;
     [k: string]: unknown;
 };
 export type CodingInput = {
@@ -43,6 +53,8 @@ export type CodingContext = CodingInput & {
     challenges?: string;
     lastResult?: CaptainOutput;
     lastError?: unknown;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
 };
 export type CodingEvent = {
     type: 'START_CODING';
@@ -58,6 +70,9 @@ export type CodingEvent = {
     targetId: JumpableStateId;
     intent?: string;
     irNumber?: string;
+} | {
+    type: 'BOSS_REPLY';
+    answer: string;
 };
 export declare const codingMachine: import("xstate").StateMachine<CodingContext, {
     type: "START_CODING";
@@ -73,6 +88,9 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
     targetId: JumpableStateId;
     intent?: string;
     irNumber?: string;
+} | {
+    type: "BOSS_REPLY";
+    answer: string;
 }, {
     [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>> | undefined;
 }, {

package/{code.fsm.introspect.d.ts → reference/sdlc/code.playbook/code.fsm.introspect.d.ts}

@@ -9,6 +9,25 @@ export interface CaptainTransition {
     readonly index: number;
     readonly target: string;
     readonly guard: TransitionGuard;
+    readonly actions: unknown;
+}
+export interface AwaitBossReplyInfo {
+    readonly stateId: string;
+    readonly bossReplyTransitions: ReadonlyArray<BossReplyTransition>;
+    readonly transitions: ReadonlyArray<AwaitBossReplyTransition>;
+}
+export interface BossReplyTransition {
+    readonly index: number;
+    readonly target: string;
+    readonly guard: TransitionGuard;
+    readonly actions: unknown;
+}
+export interface AwaitBossReplyTransition {
+    readonly eventType: string;
+    readonly index: number;
+    readonly target: string;
+    readonly guard: TransitionGuard;
+    readonly actions: unknown;
 }
 export type TransitionGuard = (args: {
     context: CodingContext;
@@ -25,6 +44,11 @@ export interface RootEventTable {
         readonly target: string;
     };
     readonly bossInterruptTargets: ReadonlyArray<string>;
+    readonly bossInterruptTargetDescriptions: ReadonlyArray<{
+        readonly stateId: string;
+        readonly description: string;
+    }>;
 }
 export declare function enumerateCaptainStates(machine: typeof codingMachine): readonly CaptainStateInfo[];
 export declare function enumerateRootEvents(machine: typeof codingMachine): RootEventTable;
+export declare function enumerateAwaitBossReply(machine: typeof codingMachine): AwaitBossReplyInfo;

package/{code.fsm.introspect.js → reference/sdlc/code.playbook/code.fsm.introspect.js}

@@ -15,6 +15,7 @@ export function enumerateCaptainStates(machine) {
             index,
             target: stripIdPrefix(String(arm.target ?? '')),
             guard: arm.guard ?? alwaysTrue,
+            actions: arm.actions,
         }));
         out.push({
             stateId,
@@ -29,13 +30,39 @@ export function enumerateRootEvents(machine) {
     const cfg = getRawConfig(machine);
     const readyOn = (cfg.states?.ready?.on ?? {});
     const rootOn = (cfg.on ?? {});
+    const bossInterruptTargets = toArmArray(rootOn.BOSS_INTERRUPT).map((arm) => stripIdPrefix(String(arm.target ?? '')));
     return {
         startCoding: { target: stripIdPrefix(String(readyOn.START_CODING?.target ?? '')) },
         continueIr: { target: stripIdPrefix(String(readyOn.CONTINUE_IR?.target ?? '')) },
         summarizeIr: { target: stripIdPrefix(String(readyOn.SUMMARIZE_IR?.target ?? '')) },
-        bossInterruptTargets: toArmArray(rootOn.BOSS_INTERRUPT).map((arm) => stripIdPrefix(String(arm.target ?? ''))),
+        bossInterruptTargets,
+        bossInterruptTargetDescriptions: bossInterruptTargets.map((stateId) => {
+            const description = cfg.states?.[stateId]?.description;
+            return {
+                stateId,
+                description: typeof description === 'string' ? description : '',
+            };
+        }),
     };
 }
+export function enumerateAwaitBossReply(machine) {
+    const stateId = 'awaitBossReply';
+    const awaitOn = getRawConfig(machine).states?.[stateId]?.on ?? {};
+    const transitions = Object.entries(awaitOn).flatMap(([eventType, value]) => toArmArray(value).map((arm, index) => ({
+        eventType,
+        index,
+        target: stripIdPrefix(String(arm.target ?? '')),
+        guard: arm.guard ?? alwaysTrue,
+        actions: arm.actions,
+    })));
+    const bossReplyTransitions = toArmArray(awaitOn.BOSS_REPLY).map((arm, index) => ({
+        index,
+        target: stripIdPrefix(String(arm.target ?? '')),
+        guard: arm.guard ?? alwaysTrue,
+        actions: arm.actions,
+    }));
+    return { stateId, bossReplyTransitions, transitions };
+}
 function getRawConfig(machine) {
     return machine.config;
 }

package/{code.fsm.introspect.ts → reference/sdlc/code.playbook/code.fsm.introspect.ts}

@@ -34,6 +34,28 @@ export interface CaptainTransition {
   readonly index: number;
   readonly target: string;
   readonly guard: TransitionGuard;
+  readonly actions: unknown;
+}
+
+export interface AwaitBossReplyInfo {
+  readonly stateId: string;
+  readonly bossReplyTransitions: ReadonlyArray<BossReplyTransition>;
+  readonly transitions: ReadonlyArray<AwaitBossReplyTransition>;
+}
+
+export interface BossReplyTransition {
+  readonly index: number;
+  readonly target: string;
+  readonly guard: TransitionGuard;
+  readonly actions: unknown;
+}
+
+export interface AwaitBossReplyTransition {
+  readonly eventType: string;
+  readonly index: number;
+  readonly target: string;
+  readonly guard: TransitionGuard;
+  readonly actions: unknown;
 }
 
 export type TransitionGuard = (args: {
@@ -46,6 +68,10 @@ export interface RootEventTable {
   readonly continueIr: { readonly target: string };
   readonly summarizeIr: { readonly target: string };
   readonly bossInterruptTargets: ReadonlyArray<string>;
+  readonly bossInterruptTargetDescriptions: ReadonlyArray<{
+    readonly stateId: string;
+    readonly description: string;
+  }>;
 }
 
 type RawInvoke = {
@@ -54,9 +80,14 @@ type RawInvoke = {
   onDone?: unknown;
 };
 
-type RawStateDef = { invoke?: RawInvoke; on?: Record<string, unknown> };
+type RawStateDef = {
+  description?: unknown;
+  invoke?: RawInvoke;
+  on?: Record<string, unknown>;
+};
 
 type RawArm = { target?: unknown; guard?: TransitionGuard };
+type RawArmWithActions = RawArm & { actions?: unknown };
 
 type RawConfig = {
   states?: Record<string, RawStateDef>;
@@ -82,6 +113,7 @@ export function enumerateCaptainStates(
         index,
         target: stripIdPrefix(String(arm.target ?? '')),
         guard: arm.guard ?? alwaysTrue,
+        actions: arm.actions,
       }),
     );
     out.push({
@@ -103,23 +135,58 @@ export function enumerateRootEvents(
     { target?: string }
   >;
   const rootOn = (cfg.on ?? {}) as Record<string, unknown>;
+  const bossInterruptTargets = toArmArray(rootOn.BOSS_INTERRUPT).map((arm) =>
+    stripIdPrefix(String(arm.target ?? '')),
+  );
   return {
     startCoding: { target: stripIdPrefix(String(readyOn.START_CODING?.target ?? '')) },
     continueIr: { target: stripIdPrefix(String(readyOn.CONTINUE_IR?.target ?? '')) },
     summarizeIr: { target: stripIdPrefix(String(readyOn.SUMMARIZE_IR?.target ?? '')) },
-    bossInterruptTargets: toArmArray(rootOn.BOSS_INTERRUPT).map((arm) =>
-      stripIdPrefix(String(arm.target ?? '')),
-    ),
+    bossInterruptTargets,
+    bossInterruptTargetDescriptions: bossInterruptTargets.map((stateId) => {
+      const description = cfg.states?.[stateId]?.description;
+      return {
+        stateId,
+        description: typeof description === 'string' ? description : '',
+      };
+    }),
   };
 }
 
+export function enumerateAwaitBossReply(
+  machine: typeof codingMachine,
+): AwaitBossReplyInfo {
+  const stateId = 'awaitBossReply';
+  const awaitOn = getRawConfig(machine).states?.[stateId]?.on ?? {};
+  const transitions = Object.entries(awaitOn).flatMap(([eventType, value]) =>
+    toArmArray(value).map(
+      (arm, index): AwaitBossReplyTransition => ({
+        eventType,
+        index,
+        target: stripIdPrefix(String(arm.target ?? '')),
+        guard: arm.guard ?? alwaysTrue,
+        actions: arm.actions,
+      }),
+    ),
+  );
+  const bossReplyTransitions = toArmArray(awaitOn.BOSS_REPLY).map(
+    (arm, index): BossReplyTransition => ({
+      index,
+      target: stripIdPrefix(String(arm.target ?? '')),
+      guard: arm.guard ?? alwaysTrue,
+      actions: arm.actions,
+    }),
+  );
+  return { stateId, bossReplyTransitions, transitions };
+}
+
 function getRawConfig(machine: typeof codingMachine): RawConfig {
   return (machine as unknown as { config: RawConfig }).config;
 }
 
-function toArmArray(value: unknown): RawArm[] {
+function toArmArray(value: unknown): RawArmWithActions[] {
   if (value === undefined || value === null) return [];
-  return (Array.isArray(value) ? value : [value]) as RawArm[];
+  return (Array.isArray(value) ? value : [value]) as RawArmWithActions[];
 }
 
 function stripIdPrefix(target: string): string {