@sublang/playbook 0.1.2 → 0.2.0

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

@@ -7,7 +7,7 @@
 //                Committer→{coder per CODE-18/19} (CODE-19 wires both
 //                coderPlayer and reviewerPlayer; Coder wins as the
 //                alias's first alternative)
-// Boss event:    slash-prefix (LLM-classifier fallback)
+// Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
 
 import { createActor, fromPromise } from 'xstate';
@@ -18,7 +18,11 @@ import {
   type CodingEvent,
   type CodingInput,
 } from './code.fsm.js';
-import { enumerateCaptainStates } from './code.fsm.introspect.js';
+import {
+  enumerateAwaitBossReply,
+  enumerateCaptainStates,
+  enumerateRootEvents,
+} from './code.fsm.introspect.js';
 
 // Public contract — `PlayerResult`, `PlaybookPorts`, `PlaybookRuntime`,
 // `CodePlaybookOptions`, and the default `createPlaybookRuntime` factory
@@ -49,6 +53,12 @@ export interface PlaybookRuntime {
 
 export type CodePlaybookOptions = CodingInput;
 
+const BOSS_REPLY_ERRORS = {
+  missingQuestion: "needsBossReply outcome missing 'question' field",
+  unregisteredState: (stateId: string) =>
+    `state ${stateId} declared needsBossReply but is not registered as resumable`,
+} as const;
+
 // Internal capabilities (DR-004 §10). Each ships with its final
 // signature; behavior lands in the per-capability task noted by the
 // TODO marker.
@@ -56,9 +66,22 @@ export type CodePlaybookOptions = CodingInput;
 // Player-prompt composer — DR-004 §6.
 // Substitutes the three placeholder tokens in `input.prompt` (literal
 // string replace, no escaping) and prepends labelled blocks for any
-// populated structured field. The FSM's prompt body is never re-flowed.
+// populated structured field. When a state resumes from a Boss reply,
+// the continuation preamble and Q/A blocks precede the ordinary
+// labelled blocks. The FSM's prompt body is never re-flowed.
+
 function composePlayerPrompt(input: CaptainInput): string {
   const blocks: string[] = [];
+  if (
+    input.pendingBossQuestion !== undefined &&
+    input.bossReply !== undefined
+  ) {
+    blocks.push(
+      'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.',
+    );
+    blocks.push(`Boss question:\n${input.pendingBossQuestion.question}`);
+    blocks.push(`Boss reply:\n${input.bossReply}`);
+  }
   if (input.intent !== undefined) {
     blocks.push(`Boss intent:\n${input.intent}`);
   }
@@ -153,6 +176,9 @@ async function adjudicate(
   // the judge response.
   for (const field of extractRequiredFields(input.result[guard])) {
     if (typeof obj[field] !== 'string') {
+      if (guard === 'needsBossReply' && field === 'question') {
+        throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
+      }
       throw new Error(
         `adjudicate: judge response missing required field "${field}" for guard "${guard}"`,
       );
@@ -204,46 +230,22 @@ function parseJudgeJson(raw: string): unknown {
 }
 
 // Boss-event classifier — DR-004 §3.
-// Slash forms tried first; unknown slash forms surface as
-// emitStatus and return undefined per slc/link.md ("Unknown
-// commands surface as emitStatus, not as a silently-dropped
-// turn"). Anything that isn't a slash form falls through to the
-// LLM classifier via ports.callJudge with a fixed prompt that
-// names the four event types and their payload shapes.
+// Every non-empty Boss turn goes through ports.callJudge. Slash-prefixed
+// text is ordinary content once a host has routed the turn to this
+// playbook; `/command` selection belongs outside handleBossInput. The
+// classifier is state-aware so awaitBossReply can distinguish a direct
+// answer (BOSS_REPLY) from a fresh directive that abandons the pending
+// question through the FSM's existing transitions.
 async function classifyBossText(
   text: string,
   ports: PlaybookPorts,
   signal: AbortSignal,
+  snapshotOrState?: unknown,
 ): Promise<CodingEvent | undefined> {
   const trimmed = text.trim();
   if (trimmed === '') return undefined;
 
-  if (trimmed === '/start' || trimmed.startsWith('/start ')) {
-    return { type: 'START_CODING', intent: trimmed.slice('/start'.length).trim() };
-  }
-  if (trimmed === '/continue' || trimmed.startsWith('/continue ')) {
-    return {
-      type: 'CONTINUE_IR',
-      irNumber: trimmed.slice('/continue'.length).trim(),
-    };
-  }
-  if (trimmed === '/summarize' || trimmed.startsWith('/summarize ')) {
-    return {
-      type: 'SUMMARIZE_IR',
-      irNumber: trimmed.slice('/summarize'.length).trim(),
-    };
-  }
-  if (trimmed === '/interrupt' || trimmed.startsWith('/interrupt ')) {
-    return parseInterruptSlash(trimmed, ports);
-  }
-
-  if (trimmed.startsWith('/')) {
-    const cmd = trimmed.split(/\s+/)[0];
-    await ports.emitStatus(`Unknown slash command: ${cmd}`);
-    return undefined;
-  }
-
-  return classifyWithLlm(trimmed, ports, signal);
+  return classifyWithLlm(text, ports, signal, snapshotOrState);
 }
 
 // JumpableStateId is internal to code.fsm.ts (not exported), so
@@ -253,31 +255,20 @@ type JumpableStateId = Extract<
   { type: 'BOSS_INTERRUPT' }
 >['targetId'];
 
-async function parseInterruptSlash(
-  trimmed: string,
-  ports: PlaybookPorts,
-): Promise<CodingEvent | undefined> {
-  const rest = trimmed.slice('/interrupt'.length).trim();
-  if (rest === '') {
-    await ports.emitStatus('/interrupt requires a stateId');
-    return undefined;
-  }
-  const firstSpace = rest.search(/\s/);
-  const targetId = firstSpace === -1 ? rest : rest.slice(0, firstSpace);
-  const intent = firstSpace === -1 ? '' : rest.slice(firstSpace).trim();
-  return {
-    type: 'BOSS_INTERRUPT',
-    targetId: targetId as JumpableStateId,
-    ...(intent ? { intent } : {}),
-  };
-}
+const rootEvents = enumerateRootEvents(codingMachine);
+const bossInterruptTargets = rootEvents.bossInterruptTargetDescriptions;
+const bossInterruptTargetIds: ReadonlySet<string> = new Set(
+  bossInterruptTargets.map((target) => target.stateId),
+);
 
 async function classifyWithLlm(
   text: string,
   ports: PlaybookPorts,
   signal: AbortSignal,
+  snapshotOrState?: unknown,
 ): Promise<CodingEvent | undefined> {
-  const prompt = buildClassifierPrompt(text);
+  const state = classifierState(snapshotOrState);
+  const prompt = buildClassifierPrompt(text, state);
   const raw = await ports.callJudge(prompt, signal);
   const parsed = parseJudgeJson(raw);
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
@@ -298,6 +289,10 @@ async function classifyWithLlm(
       : {};
 
   switch (eventType) {
+    case 'NO_ACTION':
+    case 'NO_FSM_ACTION':
+    case 'NONE':
+      return undefined;
     case 'START_CODING': {
       if (typeof payload.intent !== 'string') {
         await ports.emitStatus('Classifier omitted intent for START_CODING');
@@ -326,6 +321,12 @@ async function classifyWithLlm(
         );
         return undefined;
       }
+      if (!bossInterruptTargetIds.has(payload.targetId)) {
+        await ports.emitStatus(
+          `Classifier supplied invalid targetId for BOSS_INTERRUPT: ${payload.targetId}`,
+        );
+        return undefined;
+      }
       return {
         type: 'BOSS_INTERRUPT',
         targetId: payload.targetId as JumpableStateId,
@@ -337,6 +338,19 @@ async function classifyWithLlm(
           : {}),
       };
     }
+    case 'BOSS_REPLY': {
+      if (state.value !== 'awaitBossReply') {
+        await ports.emitStatus(
+          'Classifier returned BOSS_REPLY outside awaitBossReply',
+        );
+        return undefined;
+      }
+      if (typeof payload.answer !== 'string') {
+        await ports.emitStatus('Classifier omitted answer for BOSS_REPLY');
+        return undefined;
+      }
+      return { type: 'BOSS_REPLY', answer: payload.answer };
+    }
     default:
       await ports.emitStatus(
         `Classifier returned unknown event type: ${eventType}`,
@@ -345,22 +359,76 @@ async function classifyWithLlm(
   }
 }
 
-function buildClassifierPrompt(text: string): string {
-  return [
+interface ClassifierState {
+  value: unknown;
+  context: Record<string, unknown>;
+}
+
+function classifierState(snapshotOrState: unknown): ClassifierState {
+  if (
+    snapshotOrState !== null &&
+    typeof snapshotOrState === 'object' &&
+    'value' in snapshotOrState
+  ) {
+    const candidate = snapshotOrState as {
+      value?: unknown;
+      context?: unknown;
+    };
+    return {
+      value: candidate.value,
+      context:
+        candidate.context !== null &&
+        typeof candidate.context === 'object' &&
+        !Array.isArray(candidate.context)
+          ? (candidate.context as Record<string, unknown>)
+          : {},
+    };
+  }
+  return { value: snapshotOrState, context: {} };
+}
+
+function buildClassifierPrompt(text: string, state: ClassifierState): string {
+  const currentState =
+    typeof state.value === 'string' ? state.value : 'unknown';
+  const pendingBossQuestion = pendingBossQuestionFromContext(state.context);
+  const lines = [
     'Classify the following Boss message into exactly one of these events.',
     'Respond with JSON: { "event": "<TYPE>", "payload": { ...fields } }.',
+    'Use { "event": "NO_ACTION", "payload": {} } when no FSM action should be taken.',
+    '',
+    `Current state: ${currentState}`,
+  ];
+  if (pendingBossQuestion !== undefined) {
+    lines.push(
+      `Pending Boss question: ${pendingBossQuestion.question}`,
+      `Pending resume state: ${pendingBossQuestion.resumeStateId}`,
+    );
+  }
+  lines.push(
     '',
     'Events:',
     '- START_CODING: payload { intent: "<free-form goal>" }',
     '- CONTINUE_IR: payload { irNumber: "<number>" }',
     '- SUMMARIZE_IR: payload { irNumber: "<number>" }',
     '- BOSS_INTERRUPT: payload { targetId: "<stateId>", intent?: "<free-form goal>", irNumber?: "<number>" }',
+    '  targetId must be one of these jumpable states:',
+  );
+  for (const target of bossInterruptTargets) {
+    lines.push(`  - ${target.stateId}: ${target.description}`);
+  }
+  if (currentState === 'awaitBossReply') {
+    lines.push('- BOSS_REPLY: payload { answer: "<verbatim Boss answer>" }');
+  } else {
+    lines.push('- BOSS_REPLY: valid only when Current state is awaitBossReply');
+  }
+  lines.push(
     '',
     'Boss message:',
     '```',
     text,
     '```',
-  ].join('\n');
+  );
+  return lines.join('\n');
 }
 
 // Captain-actor bridge — DR-004 §7. One PromiseActorLogic that the
@@ -397,7 +465,14 @@ function captainBridge(
           'captainBridge: callPlayer returned status=ok with no finalText',
         );
       }
-      return adjudicate(input, result.finalText, ports, activeSignal);
+      const output = await adjudicate(
+        input,
+        result.finalText,
+        ports,
+        activeSignal,
+      );
+      validateBossReplyOutput(input, output);
+      return output;
     },
   );
 }
@@ -405,7 +480,7 @@ function captainBridge(
 // Captain pane display — PBRT-3 / PBRT-14.
 // The Captain pane is a stream keyed on four glyphs so a reader can
 // parse each line at a glance:
-//   ◆  terminal entry (ready / done / failed)
+//   ◆  basic idle entry (ready / done / failed)
 //   ▸  Boss input echo
 //   ⮕  captain-invoking state entry (label + player + CODE-N)
 //   ⤷  transition (guard fired by the just-finished captain call)
@@ -458,23 +533,109 @@ const stateMetadata: ReadonlyMap<string, StateMetadata> = (() => {
   return m;
 })();
 
-const TERMINAL_STATES: ReadonlySet<string> = new Set([
+const stateIdBySourceItem: ReadonlyMap<string, string> = new Map(
+  [...stateMetadata.entries()].map(([stateId, meta]) => [
+    meta.sourceItem,
+    stateId,
+  ]),
+);
+
+const registeredResumableStateIds: ReadonlySet<string> = new Set(
+  enumerateAwaitBossReply(codingMachine).bossReplyTransitions.map(
+    (transition) => transition.target,
+  ),
+);
+
+function validateBossReplyOutput(
+  input: CaptainInput,
+  output: CaptainOutput,
+): void {
+  if (output.guard !== 'needsBossReply') return;
+  if (typeof output.question !== 'string') {
+    throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
+  }
+  const stateId = stateIdBySourceItem.get(input.sourceItem);
+  if (stateId === undefined || !registeredResumableStateIds.has(stateId)) {
+    throw new Error(
+      BOSS_REPLY_ERRORS.unregisteredState(stateId ?? input.sourceItem),
+    );
+  }
+}
+
+const QUIESCENT_STATES: ReadonlySet<string> = new Set([
   'ready',
+  'awaitBossReply',
   'done',
   'failed',
 ]);
 
+// awaitBossReply is quiescent too, but uses a custom single-line
+// status frame rather than the plain `◆ <state>` entry.
+const BASIC_IDLE_GLYPH_STATES: ReadonlySet<string> = new Set(
+  [...QUIESCENT_STATES].filter((stateId) => stateId !== 'awaitBossReply'),
+);
+
 // Captain-pane surface (PBRT-3): every captain-invoking state plus
-// the three terminal/idle states. Wider than the prior
+// the quiescent states. Wider than the prior
 // "Boss-relevant" set per slc/link.md's default "emit on every
 // transition; let the host filter."
 const CAPTAIN_PANE_STATES: ReadonlySet<string> = new Set([
   ...stateMetadata.keys(),
-  ...TERMINAL_STATES,
+  ...QUIESCENT_STATES,
 ]);
 
-function formatStateEntry(stateId: string): string {
-  if (TERMINAL_STATES.has(stateId)) return `◆ ${stateId}`;
+interface PendingBossQuestionForStatus {
+  resumeStateId: string;
+  sourceItem: string;
+  player: string;
+  question: string;
+}
+
+function pendingBossQuestionFromContext(
+  context: Record<string, unknown>,
+): PendingBossQuestionForStatus | undefined {
+  const pending = context.pendingBossQuestion;
+  if (pending === undefined || typeof pending !== 'object') {
+    return undefined;
+  }
+  const candidate = pending as Partial<
+    Record<keyof PendingBossQuestionForStatus, unknown>
+  >;
+  if (
+    typeof candidate.resumeStateId !== 'string' ||
+    typeof candidate.sourceItem !== 'string' ||
+    typeof candidate.player !== 'string' ||
+    typeof candidate.question !== 'string'
+  ) {
+    return undefined;
+  }
+  return {
+    resumeStateId: candidate.resumeStateId,
+    sourceItem: candidate.sourceItem,
+    player: candidate.player,
+    question: candidate.question,
+  };
+}
+
+function questionExcerpt(question: string): string {
+  return question.replace(/[\r\n]+/g, ' ').slice(0, 80);
+}
+
+function formatAwaitBossReplyEntry(context: Record<string, unknown>): string {
+  const pending = pendingBossQuestionFromContext(context);
+  const resumeStateId = pending?.resumeStateId ?? 'unknown';
+  const player = pending?.player ?? 'unknown';
+  const sourceItem = pending?.sourceItem ?? 'unknown';
+  const question = questionExcerpt(pending?.question ?? '');
+  return `◆ awaiting Boss reply · ${resumeStateId} · ${player} · ${sourceItem} · q=${JSON.stringify(question)}`;
+}
+
+function formatStateEntry(
+  stateId: string,
+  context: Record<string, unknown> = {},
+): string {
+  if (stateId === 'awaitBossReply') return formatAwaitBossReplyEntry(context);
+  if (BASIC_IDLE_GLYPH_STATES.has(stateId)) return `◆ ${stateId}`;
   const meta = stateMetadata.get(stateId);
   if (!meta) return `⮕ ${stateId}`;
   return `⮕ ${meta.label}  ${meta.player} per ${meta.sourceItem}`;
@@ -519,6 +680,22 @@ function formatRiders(context: Record<string, unknown>): string {
   return parts.length > 0 ? `  ${parts.join(' ')}` : '';
 }
 
+function stateTelemetryPayload(
+  from: unknown,
+  to: string,
+  event: unknown,
+  context: Record<string, unknown>,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = { from, to, event };
+  if (to === 'awaitBossReply') {
+    const pendingBossQuestion = pendingBossQuestionFromContext(context);
+    if (pendingBossQuestion !== undefined) {
+      payload.pendingBossQuestion = pendingBossQuestion;
+    }
+  }
+  return payload;
+}
+
 // Internal export surface for tests. Not part of the stable public API;
 // the leading underscore signals "subject to change." Each member is
 // referenced here so `noUnusedLocals` stays clean while later tasks
@@ -531,10 +708,13 @@ export const _internal = {
   captainBridge,
   STATE_LABELS,
   stateMetadata,
+  pendingBossQuestionFromContext,
+  formatAwaitBossReplyEntry,
   formatStateEntry,
   formatTransition,
   formatBossEcho,
   formatRiders,
+  stateTelemetryPayload,
 };
 
 export default function createPlaybookRuntime(
@@ -602,10 +782,16 @@ export default function createPlaybookRuntime(
           const from = priorState;
           priorState = to;
           // Telemetry on every transition (PBRT-14).
+          const context = snap.context ?? {};
           enqueueEmit(() =>
             ports.emitTelemetry({
               topic: 'playbook.fsm.state',
-              payload: { from, to, event: inspectionEvent.event },
+              payload: stateTelemetryPayload(
+                from,
+                to,
+                inspectionEvent.event,
+                context,
+              ),
             }),
           );
           // Captain pane (PBRT-3 / PBRT-14): show the transition
@@ -618,9 +804,9 @@ export default function createPlaybookRuntime(
           if (transitionLine !== undefined) {
             enqueueEmit(() => ports.emitStatus(transitionLine));
           }
-          const entryLine = formatStateEntry(to);
+          const entryLine = formatStateEntry(to, context);
           const riderSuffix = stateMetadata.has(to)
-            ? formatRiders(snap.context ?? {})
+            ? formatRiders(context)
             : '';
           const message = entryLine + riderSuffix;
           if (to === 'failed') {
@@ -657,10 +843,15 @@ export default function createPlaybookRuntime(
       }
       activeSignal = signal;
       try {
-        // 1. Classify text into an FSM event (slash → event; else LLM).
-        const event = await classifyBossText(text, savedPorts, signal);
-        // Unknown slash or empty input — classifier already surfaced
-        // status; nothing to send.
+        // 1. Classify non-empty text into an FSM event through the judge.
+        const event = await classifyBossText(
+          text,
+          savedPorts,
+          signal,
+          actor.getSnapshot(),
+        );
+        // Empty input, no-action classifier output, or invalid classifier
+        // output — nothing to send.
         if (event === undefined) {
           await drainEmissions();
           return;
@@ -739,5 +930,5 @@ function driveToQuiescence(
 
 function isQuiescent(snap: { value: unknown }): boolean {
   const v = snap.value;
-  return v === 'ready' || v === 'failed' || v === 'done';
+  return typeof v === 'string' && QUIESCENT_STATES.has(v);
 }

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

@@ -15,6 +15,10 @@ captain:
   from: ./code.tmux-play.js
   adapter: claude
   model: claude-opus-4-7
+  # Agents run in cligent's classifier/reviewer-protected auto mode
+  # (cligent DR-005): claude → permissionMode auto, codex → auto_review.
+  permissions:
+    mode: auto
   options:
     # Substituted into the <coder-llm> placeholder in player prompts
     # (DR-004 §6).
@@ -29,5 +33,9 @@ captain:
 roles:
   - id: coder
     adapter: claude
+    permissions:
+      mode: auto
   - id: reviewer
     adapter: codex
+    permissions:
+      mode: auto

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

@@ -10,6 +10,8 @@ captain:
   from: "@sublang/playbook/code/tmux-play"
   adapter: claude
   model: claude-opus-4-7
+  permissions:
+    mode: auto
   options:
     coderPlayer: claude
     reviewerPlayer: codex
@@ -17,5 +19,9 @@ captain:
 roles:
   - id: coder
     adapter: claude
+    permissions:
+      mode: auto
   - id: reviewer
     adapter: codex
+    permissions:
+      mode: auto