@sublang/playbook 0.1.3 → 0.2.0

package/{code.gears.md → reference/sdlc/code.playbook/code.gears.md}

@@ -18,7 +18,6 @@ When Boss gives a coding intent, Captain shall relay it to Coder along with the
 > If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations.
 > Consult @specs/map.md for relevant context if needed; ensure it reflects the changes.
 > Do not commit.
-
 The resulting changes are Initial Changes.
 
 ### CODE-2
@@ -34,7 +33,6 @@ When a new IR or IR task passes review and is committed, Captain shall prompt Co
 > 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 Initial Changes.
 
 ### CODE-4
@@ -52,7 +50,6 @@ When an IR is done, Captain shall prompt Coder:
 > Avoid implementation specifics.
 > Avoid redundant spec items.
 > Consult @specs/map.md for relevant context and update it to reflect your changes.
-
 ## Reviewer
 
 For each finding in a review round, Coder either addresses it with changes or challenges it with a rebuttal.
@@ -243,8 +240,12 @@ When Coder makes any Initial Changes and Reviewer has not played since the last
 > Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
 > Coder is <coder-llm>.
 
+Result guard: `needsBossInput` — Committing requires additional Boss input or rescoping rather than a specific answer to resume this same state.
+
 ### CODE-19
 
 When Coder makes any Initial Changes and Reviewer has played since the last commit, or Reviewer raises no findings on uncommitted changes and Coder has played since the last commit, Captain shall prompt Committer:
 > Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
 > Coder is <coder-llm>; Reviewer is <reviewer-llm>.
+
+Result guard: `needsBossInput` — Committing requires additional Boss input or rescoping rather than a specific answer to resume this same state.

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

@@ -25,17 +25,26 @@ export type CodePlaybookOptions = CodingInput;
 declare function composePlayerPrompt(input: CaptainInput): string;
 declare function resolvePlayerId(input: CaptainInput): string;
 declare function adjudicate(input: CaptainInput, finalText: string, ports: PlaybookPorts, signal: AbortSignal): Promise<CaptainOutput>;
-declare function classifyBossText(text: string, ports: PlaybookPorts, signal: AbortSignal): Promise<CodingEvent | undefined>;
+declare function classifyBossText(text: string, ports: PlaybookPorts, signal: AbortSignal, snapshotOrState?: unknown): Promise<CodingEvent | undefined>;
 declare function captainBridge(ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined): import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>;
 interface StateMetadata {
     player: CaptainInput['player'];
     sourceItem: string;
     label: string;
 }
-declare function formatStateEntry(stateId: string): string;
+interface PendingBossQuestionForStatus {
+    resumeStateId: string;
+    sourceItem: string;
+    player: string;
+    question: string;
+}
+declare function pendingBossQuestionFromContext(context: Record<string, unknown>): PendingBossQuestionForStatus | undefined;
+declare function formatAwaitBossReplyEntry(context: Record<string, unknown>): string;
+declare function formatStateEntry(stateId: string, context?: Record<string, unknown>): string;
 declare function formatTransition(event: unknown): string | undefined;
 declare function formatBossEcho(text: string, eventType?: string): string;
 declare function formatRiders(context: Record<string, unknown>): string;
+declare function stateTelemetryPayload(from: unknown, to: string, event: unknown, context: Record<string, unknown>): Record<string, unknown>;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     resolvePlayerId: typeof resolvePlayerId;
@@ -44,10 +53,13 @@ export declare const _internal: {
     captainBridge: typeof captainBridge;
     STATE_LABELS: Readonly<Record<string, string>>;
     stateMetadata: ReadonlyMap<string, StateMetadata>;
+    pendingBossQuestionFromContext: typeof pendingBossQuestionFromContext;
+    formatAwaitBossReplyEntry: typeof formatAwaitBossReplyEntry;
     formatStateEntry: typeof formatStateEntry;
     formatTransition: typeof formatTransition;
     formatBossEcho: typeof formatBossEcho;
     formatRiders: typeof formatRiders;
+    stateTelemetryPayload: typeof stateTelemetryPayload;
 };
 export default function createPlaybookRuntime(options: CodePlaybookOptions): PlaybookRuntime;
 export {};

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

@@ -7,20 +7,32 @@
 //                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';
 import { codingMachine, } from './code.fsm.js';
-import { enumerateCaptainStates } from './code.fsm.introspect.js';
+import { enumerateAwaitBossReply, enumerateCaptainStates, enumerateRootEvents, } from './code.fsm.introspect.js';
+const BOSS_REPLY_ERRORS = {
+    missingQuestion: "needsBossReply outcome missing 'question' field",
+    unregisteredState: (stateId) => `state ${stateId} declared needsBossReply but is not registered as resumable`,
+};
 // Internal capabilities (DR-004 §10). Each ships with its final
 // signature; behavior lands in the per-capability task noted by the
 // TODO marker.
 // 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) {
     const blocks = [];
+    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}`);
     }
@@ -102,6 +114,9 @@ async function adjudicate(input, finalText, ports, signal) {
     // 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}"`);
         }
     }
@@ -145,58 +160,24 @@ function parseJudgeJson(raw) {
     }
 }
 // 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.
-async function classifyBossText(text, ports, signal) {
+// 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, ports, signal, snapshotOrState) {
     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);
-}
-async function parseInterruptSlash(trimmed, ports) {
-    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,
-        ...(intent ? { intent } : {}),
-    };
+    return classifyWithLlm(text, ports, signal, snapshotOrState);
 }
-async function classifyWithLlm(text, ports, signal) {
-    const prompt = buildClassifierPrompt(text);
+const rootEvents = enumerateRootEvents(codingMachine);
+const bossInterruptTargets = rootEvents.bossInterruptTargetDescriptions;
+const bossInterruptTargetIds = new Set(bossInterruptTargets.map((target) => target.stateId));
+async function classifyWithLlm(text, ports, signal, snapshotOrState) {
+    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)) {
@@ -215,6 +196,10 @@ async function classifyWithLlm(text, ports, signal) {
         ? obj.payload
         : {};
     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');
@@ -241,6 +226,10 @@ async function classifyWithLlm(text, ports, signal) {
                 await ports.emitStatus('Classifier omitted targetId for BOSS_INTERRUPT');
                 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,
@@ -252,27 +241,63 @@ async function classifyWithLlm(text, ports, signal) {
                     : {}),
             };
         }
+        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}`);
             return undefined;
     }
 }
-function buildClassifierPrompt(text) {
-    return [
+function classifierState(snapshotOrState) {
+    if (snapshotOrState !== null &&
+        typeof snapshotOrState === 'object' &&
+        'value' in snapshotOrState) {
+        const candidate = snapshotOrState;
+        return {
+            value: candidate.value,
+            context: candidate.context !== null &&
+                typeof candidate.context === 'object' &&
+                !Array.isArray(candidate.context)
+                ? candidate.context
+                : {},
+        };
+    }
+    return { value: snapshotOrState, context: {} };
+}
+function buildClassifierPrompt(text, state) {
+    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.',
         '',
-        '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>" }',
-        '',
-        'Boss message:',
-        '```',
-        text,
-        '```',
-    ].join('\n');
+        `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, '```');
+    return lines.join('\n');
 }
 // Captain-actor bridge — DR-004 §7. One PromiseActorLogic that the
 // codingMachine invokes from every captain-invoking state. Per turn:
@@ -300,13 +325,15 @@ function captainBridge(ports, getActiveSignal) {
         if (result.finalText === undefined) {
             throw new Error('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;
     });
 }
 // 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)
@@ -345,21 +372,73 @@ const stateMetadata = (() => {
     }
     return m;
 })();
-const TERMINAL_STATES = new Set([
+const stateIdBySourceItem = new Map([...stateMetadata.entries()].map(([stateId, meta]) => [
+    meta.sourceItem,
+    stateId,
+]));
+const registeredResumableStateIds = new Set(enumerateAwaitBossReply(codingMachine).bossReplyTransitions.map((transition) => transition.target));
+function validateBossReplyOutput(input, output) {
+    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 = 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 = 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 = new Set([
     ...stateMetadata.keys(),
-    ...TERMINAL_STATES,
+    ...QUIESCENT_STATES,
 ]);
-function formatStateEntry(stateId) {
-    if (TERMINAL_STATES.has(stateId))
+function pendingBossQuestionFromContext(context) {
+    const pending = context.pendingBossQuestion;
+    if (pending === undefined || typeof pending !== 'object') {
+        return undefined;
+    }
+    const candidate = pending;
+    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) {
+    return question.replace(/[\r\n]+/g, ' ').slice(0, 80);
+}
+function formatAwaitBossReplyEntry(context) {
+    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, context = {}) {
+    if (stateId === 'awaitBossReply')
+        return formatAwaitBossReplyEntry(context);
+    if (BASIC_IDLE_GLYPH_STATES.has(stateId))
         return `◆ ${stateId}`;
     const meta = stateMetadata.get(stateId);
     if (!meta)
@@ -402,6 +481,16 @@ function formatRiders(context) {
     }
     return parts.length > 0 ? `  ${parts.join(' ')}` : '';
 }
+function stateTelemetryPayload(from, to, event, context) {
+    const payload = { 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
@@ -414,10 +503,13 @@ export const _internal = {
     captainBridge,
     STATE_LABELS,
     stateMetadata,
+    pendingBossQuestionFromContext,
+    formatAwaitBossReplyEntry,
     formatStateEntry,
     formatTransition,
     formatBossEcho,
     formatRiders,
+    stateTelemetryPayload,
 };
 export default function createPlaybookRuntime(options) {
     let actor;
@@ -475,9 +567,10 @@ export default function createPlaybookRuntime(options) {
                 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
                 // guard first (when this is an actor-done transition with
@@ -490,9 +583,9 @@ export default function createPlaybookRuntime(options) {
                 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') {
@@ -519,10 +612,10 @@ export default function createPlaybookRuntime(options) {
             }
             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;
@@ -594,5 +687,5 @@ function driveToQuiescence(actor) {
 }
 function isQuiescent(snap) {
     const v = snap.value;
-    return v === 'ready' || v === 'failed' || v === 'done';
+    return typeof v === 'string' && QUIESCENT_STATES.has(v);
 }