@sublang/playbook 0.1.3 → 0.4.0

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

@@ -7,29 +7,40 @@
 //                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.
+// string replace, no escaping) and arranges labelled blocks around
+// the prompt body. Context blocks the body refers to as prior
+// material (`Boss intent:`, `Task description:`) are prepended;
+// action blocks the body refers to as material below
+// (`Review items:`, `Rebuttals:`) are appended after the body so the
+// CODE-N prompts' "review item below" / "rebuttal below" phrasing
+// matches the rendered layout. When a state resumes from a Boss
+// reply, the continuation preamble and Q/A blocks precede every
+// ordinary block. 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}`);
     }
-    if (input.reviews !== undefined) {
-        blocks.push(`Review items:\n${input.reviews}`);
-    }
-    if (input.challenges !== undefined) {
-        blocks.push(`Rebuttals:\n${input.challenges}`);
-    }
     if (input.taskDescription !== undefined) {
         blocks.push(`Task description:\n${input.taskDescription}`);
     }
@@ -44,6 +55,12 @@ function composePlayerPrompt(input) {
         body = body.replaceAll('<reviewer-llm>', input.reviewerPlayer);
     }
     blocks.push(body);
+    if (input.reviews !== undefined) {
+        blocks.push(`Review items:\n${input.reviews}`);
+    }
+    if (input.challenges !== undefined) {
+        blocks.push(`Rebuttals:\n${input.challenges}`);
+    }
     return blocks.join('\n\n');
 }
 // Player-id resolver — DR-004 §2.
@@ -102,6 +119,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 +165,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);
+    return classifyWithLlm(text, ports, signal, snapshotOrState);
 }
-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 } : {}),
-    };
-}
-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 +201,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 +231,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 +246,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,18 +330,28 @@ 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)
-//   ▸  Boss input echo
-//   ⮕  captain-invoking state entry (label + player + CODE-N)
-//   ⤷  transition (guard fired by the just-finished captain call)
-// Prompts and full player output ride the player panes; the Captain
-// pane keeps to the state-machine shape.
+// The Captain pane is a stream of three glyphs plus one bare
+// captain-speech act, designed so a reader can parse each line at a
+// glance:
+//   (no glyph)  bare FSM event type — host renders as captain speech
+//               (e.g., `captain> START_CODING`)
+//   ⤷           captain-invoking state entry: `<Player>: <label>`
+//   →           transition guard outcome (`· field=N` tallies
+//               appended); the host presenter owns any visual
+//               nesting under the preceding ⤷ entry
+//   ◆           failure state (with `lastError` data) and the
+//               `awaitBossReply` suspension state (custom payload)
+// The runtime emits no status line on entry to the idle state
+// (`ready`) or the terminal state (`done`); the next `boss>` prompt
+// is the implicit "turn over" signal. Prompts and full player output
+// ride the player panes; the Captain pane keeps to the state-machine
+// shape.
 const STATE_LABELS = {
     planAndImplement: 'plan & implement',
     respondToReview: 'respond to review',
@@ -345,26 +385,87 @@ 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',
 ]);
+// States whose entry the runtime does not surface on the Captain
+// pane per PBRT-3: the readline returning to its `boss>` prompt is
+// the implicit "turn over" signal, so a `◆ ready` / `◆ done`
+// tombstone is redundant.
+const SUPPRESSED_ENTRY_STATES = new Set([
+    'ready',
+    'done',
+]);
 // Captain-pane surface (PBRT-3): every captain-invoking state plus
-// the three terminal/idle states. Wider than the prior
-// "Boss-relevant" set per slc/link.md's default "emit on every
-// transition; let the host filter."
+// the quiescent states whose entry still carries information
+// (failure with `lastError`, awaitBossReply with the pending
+// question). `ready` and `done` flow through the inspect handler
+// but their entries are dropped before emitStatus per
+// SUPPRESSED_ENTRY_STATES above.
 const CAPTAIN_PANE_STATES = new Set([
     ...stateMetadata.keys(),
-    ...TERMINAL_STATES,
+    ...QUIESCENT_STATES,
 ]);
-function formatStateEntry(stateId) {
-    if (TERMINAL_STATES.has(stateId))
-        return `◆ ${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 (SUPPRESSED_ENTRY_STATES.has(stateId))
+        return undefined;
+    if (stateId === 'failed')
+        return '◆ failed';
     const meta = stateMetadata.get(stateId);
     if (!meta)
-        return `⮕ ${stateId}`;
-    return `⮕ ${meta.label}  ${meta.player} per ${meta.sourceItem}`;
+        return `⤷ ${stateId}`;
+    return `⤷ ${meta.player}: ${meta.label}`;
 }
 function formatTransition(event) {
     const output = event?.output;
@@ -378,29 +479,25 @@ function formatTransition(event) {
             tallies.push(`${field}=${items ? items.length : 1}`);
         }
     }
-    const suffix = tallies.length > 0 ? `  ${tallies.join(' ')}` : '';
-    return `⤷ ${output.guard}${suffix}`;
+    const suffix = tallies.length > 0 ? ` · ${tallies.join(' · ')}` : '';
+    // No leading whitespace: visual nesting under the preceding ⤷
+    // entry is the host presenter's concern (cligent's writeStatusLine
+    // emits status messages verbatim, with its own chrome but no
+    // continuation indent; layout is its job, not ours).
+    return `→ ${output.guard}${suffix}`;
 }
-function formatBossEcho(text, eventType) {
-    return eventType !== undefined
-        ? `▸ BOSS  ${text}  → ${eventType}`
-        : `▸ BOSS  ${text}`;
+function formatClassification(eventType) {
+    return eventType;
 }
-// Rider fields PBRT-14 names — surfaced inline on a state entry
-// whenever the FSM context populates them, regardless of which
-// captain-invoking state is being entered. Routing-only context
-// (reviewSubject, afterReview, etc.) stays out of the pane and is
-// visible via emitTelemetry instead.
-const RIDER_FIELDS = ['intent', 'irNumber', 'taskDescription'];
-function formatRiders(context) {
-    const parts = [];
-    for (const f of RIDER_FIELDS) {
-        const v = context[f];
-        if (typeof v === 'string' && v.length > 0) {
-            parts.push(`${f}=${JSON.stringify(v)}`);
+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 parts.length > 0 ? `  ${parts.join(' ')}` : '';
+    return payload;
 }
 // Internal export surface for tests. Not part of the stable public API;
 // the leading underscore signals "subject to change." Each member is
@@ -414,10 +511,12 @@ export const _internal = {
     captainBridge,
     STATE_LABELS,
     stateMetadata,
+    pendingBossQuestionFromContext,
+    formatAwaitBossReplyEntry,
     formatStateEntry,
     formatTransition,
-    formatBossEcho,
-    formatRiders,
+    formatClassification,
+    stateTelemetryPayload,
 };
 export default function createPlaybookRuntime(options) {
     let actor;
@@ -475,9 +574,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,18 +590,16 @@ export default function createPlaybookRuntime(options) {
                 if (transitionLine !== undefined) {
                     enqueueEmit(() => ports.emitStatus(transitionLine));
                 }
-                const entryLine = formatStateEntry(to);
-                const riderSuffix = stateMetadata.has(to)
-                    ? formatRiders(snap.context ?? {})
-                    : '';
-                const message = entryLine + riderSuffix;
+                const entryLine = formatStateEntry(to, context);
+                if (entryLine === undefined)
+                    return;
                 if (to === 'failed') {
                     const lastError = snap.context
                         ?.lastError;
-                    enqueueEmit(() => ports.emitStatus(message, { lastError }));
+                    enqueueEmit(() => ports.emitStatus(entryLine, { lastError }));
                 }
                 else {
-                    enqueueEmit(() => ports.emitStatus(message));
+                    enqueueEmit(() => ports.emitStatus(entryLine));
                 }
             },
         });
@@ -519,20 +617,21 @@ 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;
                 }
-                // 2. Captain-pane Boss-input echo (PBRT-14): the verbatim
-                //    Boss text and the FSM event it classified to, before
-                //    the FSM advances. Enqueued so it interleaves cleanly
-                //    with the inspect-driven transition emissions.
+                // 2. Captain-pane classification line (PBRT-14): the bare
+                //    FSM event type, emitted before the FSM advances so the
+                //    host can render it as captain speech (e.g.,
+                //    `captain> START_CODING`). Enqueued so it interleaves
+                //    cleanly with the inspect-driven transition emissions.
                 const echoPorts = savedPorts;
-                enqueueEmit(() => echoPorts.emitStatus(formatBossEcho(text, event.type)));
+                enqueueEmit(() => echoPorts.emitStatus(formatClassification(event.type)));
                 // 3. final state ('done') cannot accept new events — dispose
                 //    and reconstruct per DR-004 §5.
                 if (actor.getSnapshot().status === 'done') {
@@ -594,5 +693,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);
 }