@sublang/playbook 0.4.2 → 0.5.0

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

@@ -4,8 +4,10 @@
 // Generated by slc/link.md (FSM-to-Runtime linker).
 // Source FSM:    ./code.fsm.ts
 // Player bind:   Coder→coder, Reviewer→reviewer,
-//                Committer→{coder per CODE-18/19} (CODE-19 wires both
-//                coderPlayer and reviewerPlayer; Coder wins as the
+//                Committer→ configured committerPlayer alias when set
+//                (per-run remapping via options — PBRT-8); else the
+//                baked CODE-18/19 fallback (coder-first: CODE-19 wires
+//                both coderPlayer and reviewerPlayer, Coder wins as the
 //                alias's first alternative)
 // Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
@@ -59,6 +61,70 @@ const BOSS_REPLY_ERRORS = {
     `state ${stateId} declared needsBossReply but is not registered as resumable`,
 } as const;
 
+// Required-payload fields whose value is the player's verbatim long-form
+// prose. The runtime carries `finalText.trim()` into these fields rather
+// than asking the judge to round-trip the text through JSON. Short
+// extracted fields (`question`, `taskDescription`, `irNumber`, …) stay
+// judge-extracted — they are not in this set.
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  'reviews',
+  'challenges',
+]);
+
+// Normalize an unknown error value to the compact `{ name, message }`
+// shape used by Captain-pane / status emissions. Returns `undefined`
+// for nullish input so callers can omit absent errors.
+function normalizeErrorCompact(
+  err: unknown,
+): { name: string; message: string } | undefined {
+  if (err === undefined || err === null) return undefined;
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message };
+  }
+  if (typeof err === 'object') {
+    const o = err as Record<string, unknown>;
+    if (typeof o.message === 'string') {
+      return {
+        name: typeof o.name === 'string' ? o.name : 'Error',
+        message: o.message,
+      };
+    }
+  }
+  return { name: 'Error', message: String(err) };
+}
+
+// Normalize an unknown error value to the full `{ name, message, stack }`
+// shape used by telemetry emissions. Returns `undefined` for nullish
+// input. `stack` is omitted when not available on the source value.
+function normalizeErrorFull(
+  err: unknown,
+): { name: string; message: string; stack?: string } | undefined {
+  const compact = normalizeErrorCompact(err);
+  if (compact === undefined) return undefined;
+  if (err instanceof Error) {
+    return err.stack !== undefined ? { ...compact, stack: err.stack } : compact;
+  }
+  if (typeof err === 'object' && err !== null) {
+    const stack = (err as Record<string, unknown>).stack;
+    if (typeof stack === 'string') {
+      return { ...compact, stack };
+    }
+  }
+  return compact;
+}
+
+// Normalize any `error` field inside a telemetry event so failed
+// transitions don't leak raw Error instances through the channel.
+function normalizeEventForTelemetry(event: unknown): unknown {
+  if (event === null || typeof event !== 'object' || Array.isArray(event)) {
+    return event;
+  }
+  const e = event as Record<string, unknown>;
+  if (!('error' in e)) return event;
+  const normalized = normalizeErrorFull(e.error);
+  return { ...e, error: normalized };
+}
+
 // Internal capabilities (DR-004 §10). Each ships with its final
 // signature; behavior lands in the per-capability task noted by the
 // TODO marker.
@@ -117,15 +183,21 @@ function composePlayerPrompt(input: CaptainInput): string {
   return blocks.join('\n\n');
 }
 
-// Player-id resolver — DR-004 §2.
+// Player-id resolver — DR-004 §2 / PBRT-8.
 // Non-composite: Coder→'coder', Reviewer→'reviewer'. The composite
-// Committer (= Coder | Reviewer per code.gears.md) resolves per
-// populated <playerName>Player field on `CaptainInput`: prefer
-// `coderPlayer` (CODE-18 wires only coderPlayer; CODE-19 wires both
-// so coderPlayer still wins as the alias's first alternative), fall
-// back to `reviewerPlayer` only if a future gear ships a
-// reviewer-only Committer item, and finally to the alias's first
-// alternative (Coder) when neither is set.
+// Committer (= Coder | Reviewer per code.gears.md) resolves to the
+// configured alias when present: `input.committerPlayer`, the
+// validated `captain.options.code.committer` (PBRT-8 / PBRT-30),
+// already a baked player id ('coder' / 'reviewer'). Absent a
+// configured alias it falls back to the DR-004 §2 baked binding by
+// populated <playerName>Player field: prefer `coderPlayer` (CODE-18
+// wires only coderPlayer; CODE-19 wires both so coderPlayer still wins
+// as the alias's first alternative), fall back to `reviewerPlayer`
+// only if a future gear ships a reviewer-only Committer item, and
+// finally to the alias's first alternative (Coder) when neither is
+// set. The alias selects only the host pane; it is not a PBRT-4
+// identity string, so it leaves <coder-llm> / <reviewer-llm>
+// untouched and `input.player` stays `Committer` (PLAYBOOK-3).
 function resolvePlayerId(input: CaptainInput): string {
   switch (input.player) {
     case 'Coder':
@@ -133,6 +205,7 @@ function resolvePlayerId(input: CaptainInput): string {
     case 'Reviewer':
       return 'reviewer';
     case 'Committer':
+      if (input.committerPlayer !== undefined) return input.committerPlayer;
       if (input.coderPlayer !== undefined) return 'coder';
       if (input.reviewerPlayer !== undefined) return 'reviewer';
       return 'coder';
@@ -180,8 +253,17 @@ async function adjudicate(
   // required fields with the literal phrase
   //   Output shall include `<fieldName>: <...>`
   // so we extract those tokens and require each to be a string in
-  // the judge response.
+  // the judge response — except for VERBATIM_PAYLOAD_FIELDS
+  // (`reviews`, `challenges`), where the runtime substitutes
+  // `finalText.trim()` so the long-form prose is not round-tripped
+  // through judge JSON. Short extracted fields like `question` and
+  // `taskDescription` keep the existing extract-and-validate path.
+  const verbatim = finalText.trim();
   for (const field of extractRequiredFields(input.result[guard])) {
+    if (VERBATIM_PAYLOAD_FIELDS.has(field)) {
+      obj[field] = verbatim;
+      continue;
+    }
     if (typeof obj[field] !== 'string') {
       if (guard === 'needsBossReply' && field === 'question') {
         throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
@@ -214,7 +296,10 @@ function buildJudgePrompt(input: CaptainInput, finalText: string): string {
   lines.push(
     'Pick exactly one outcome by `guard` and return JSON ' +
       '`{ guard, …payloadFields }`. Required payload fields are ' +
-      'named in the outcome description.',
+      'named in the outcome description. Do not copy long-form ' +
+      'verbatim fields (`reviews`, `challenges`) — the runtime ' +
+      "carries the player's output into those fields verbatim, " +
+      'so any value you supply for them will be overwritten.',
   );
   lines.push('');
   for (const [key, description] of Object.entries(input.result)) {
@@ -223,17 +308,137 @@ function buildJudgePrompt(input: CaptainInput, finalText: string): string {
   return lines.join('\n');
 }
 
+// Judge replies are meant to be a single JSON object, but LLMs
+// routinely wrap them in prose ("Here is the result: …"), Markdown
+// code fences, or trailing commentary, and occasionally emit a
+// trailing comma or truncate the tail (a dropped closing brace, an
+// unterminated string). parseJudgeJson is deliberately lenient: it
+// first tries a strict parse of the (optionally fenced) body, then
+// scans every `{`/`[` as a possible start in document order and
+// returns the first recoverable object. At each start it prefers a
+// strict balanced span and falls back to a repaired (trailing-comma /
+// truncation) span, so a damaged object earlier in the prose is not
+// overridden by a cleaner one later. Scanning every start (not just
+// the first bracket) keeps a bracketed fragment in surrounding prose —
+// e.g. an aside like `see [1]` or `{n/a}` before the real object —
+// from masking a later, genuinely valid object. Both callers
+// (classification and adjudication) expect an object, so plain objects
+// win over arrays/scalars; the first value of any shape is remembered
+// so a legitimately array/scalar reply still surfaces to the caller's
+// own object check. Only a reply from which no JSON value can be
+// recovered is treated as malformed and throws, preserving the
+// control-plane error contract (PBRT-7, PBRT-10).
 function parseJudgeJson(raw: string): unknown {
-  let text = raw.trim();
-  const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
-  if (fence) text = fence[1].trim();
+  const fenced = stripCodeFence(raw.trim());
+  // Fast path: a well-formed (optionally fenced) JSON body.
   try {
-    return JSON.parse(text);
-  } catch (e) {
-    throw new Error(
-      `adjudicate: judge response is not valid JSON: ${(e as Error).message}`,
-    );
+    return JSON.parse(fenced);
+  } catch {
+    // Fall through to lenient extraction + repair.
   }
+  const starts: number[] = [];
+  for (let i = 0; i < fenced.length; i++) {
+    const ch = fenced[i];
+    if (ch === '{' || ch === '[') starts.push(i);
+  }
+  // Walk starts in document order. At each start prefer a strict
+  // balanced span (most trustworthy) and fall back to a repaired one
+  // for a trailing-comma / truncated tail, so the earliest intended
+  // object wins even when it needs repair. Return the first plain
+  // object; remember the first value of any shape so a legitimately
+  // array/scalar reply still surfaces to the caller's own object check.
+  let firstValue: { value: unknown } | undefined;
+  for (const start of starts) {
+    let parsedHere: { value: unknown } | undefined;
+    for (const repair of [false, true]) {
+      const candidate = extractJsonValue(fenced, start, repair);
+      if (candidate === undefined) continue;
+      try {
+        parsedHere = { value: JSON.parse(candidate) };
+      } catch {
+        continue; // not parseable this way — try repair, then next start
+      }
+      break; // prefer the strict span at this start over its repair
+    }
+    if (parsedHere === undefined) continue;
+    if (isPlainObject(parsedHere.value)) return parsedHere.value;
+    if (firstValue === undefined) firstValue = parsedHere;
+  }
+  if (firstValue !== undefined) return firstValue.value;
+  throw new Error('adjudicate: judge response is not valid JSON');
+}
+
+function isPlainObject(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Strip a single Markdown code fence that wraps the whole string.
+function stripCodeFence(text: string): string {
+  const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+  return fence ? fence[1].trim() : text;
+}
+
+// Scan from `start` (a `{`/`[` index), tracking string and
+// bracket-nesting state, and emit the balanced JSON value rooted
+// there. Anything after the top-level value closes is ignored (so a
+// trailing code fence or commentary does not matter). With
+// `repair === false` the span is returned only if it actually closes,
+// and trailing commas are left intact — so the caller can prefer a
+// cleanly-balanced span before attempting repair; if input ends
+// before the value closes, undefined is returned. With
+// `repair === true` common damage is fixed: a trailing comma before a
+// close is removed, an unterminated string is closed, and any
+// brackets still open at end-of-input are closed in order.
+function extractJsonValue(
+  text: string,
+  start: number,
+  repair: boolean,
+): string | undefined {
+  const stack: string[] = [];
+  let out = '';
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+      continue;
+    }
+    if (ch === '{' || ch === '[') {
+      stack.push(ch === '{' ? '}' : ']');
+      out += ch;
+      continue;
+    }
+    if (ch === '}' || ch === ']') {
+      if (repair) out = dropTrailingComma(out);
+      out += ch;
+      stack.pop();
+      if (stack.length === 0) return out; // top-level value complete
+      continue;
+    }
+    out += ch;
+  }
+  // End of input before the top-level value closed.
+  if (!repair) return undefined; // strict pass: no balanced span here
+  if (inString) out += '"';
+  out = dropTrailingComma(out);
+  while (stack.length > 0) out += stack.pop();
+  return out;
+}
+
+// Remove a trailing comma (and any whitespace after it) at the end of
+// the accumulated output, so `{"a":1,}` / `[1,2,]` and truncated
+// `{"a":1,` repair to valid JSON.
+function dropTrailingComma(out: string): string {
+  return out.replace(/,(\s*)$/, '$1');
 }
 
 // Boss-event classifier — DR-004 §3.
@@ -277,7 +482,17 @@ async function classifyWithLlm(
   const state = classifierState(snapshotOrState);
   const prompt = buildClassifierPrompt(text, state);
   const raw = await ports.callJudge(prompt, signal);
-  const parsed = parseJudgeJson(raw);
+  let parsed: unknown;
+  try {
+    parsed = parseJudgeJson(raw);
+  } catch {
+    // No JSON value could be recovered. Classification failures are
+    // non-fatal — unlike adjudication, which throws to the failure
+    // state (PBRT-10) — so surface one status and take no FSM action,
+    // consistent with the other invalid-reply paths below (PBRT-7).
+    await ports.emitStatus('Classifier reply was not recoverable JSON');
+    return undefined;
+  }
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     await ports.emitStatus('Classifier returned a non-object JSON response');
     return undefined;
@@ -638,24 +853,37 @@ function pendingBossQuestionFromContext(
   };
 }
 
-function questionExcerpt(question: string): string {
-  return question.replace(/[\r\n]+/g, ' ').slice(0, 80);
+// PBRT-3 / PBRT-14: on entry to `awaitBossReply` the runtime surfaces
+// the pending player question as a captain-speech act attributed to the
+// asking player (`<player> asks: <full question>`), emitted with no
+// glyph so the host renders it as captain speech. The question is
+// carried verbatim and in full — the judge JSON that produced it rides
+// a hidden callCaptain (PBRT-15), so this line is the Boss's only
+// legible view of what was asked.
+function formatAwaitBossReplyQuestion(
+  context: Record<string, unknown>,
+): string {
+  const pending = pendingBossQuestionFromContext(context);
+  const player = pending?.player ?? 'unknown';
+  const question = pending?.question ?? '';
+  return `${player} asks: ${question}`;
 }
 
-function formatAwaitBossReplyEntry(context: Record<string, unknown>): string {
+// The rider-less routing marker emitted right after the question line.
+// It carries only the resume target, asking player, and source item;
+// the former `q="<first 80 chars>"` excerpt rider is dropped now that
+// the full question rides the captain-speech line above.
+function formatAwaitBossReplyMarker(
+  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)}`;
+  return `◆ awaiting Boss reply · ${resumeStateId} · ${player} · ${sourceItem}`;
 }
 
-function formatStateEntry(
-  stateId: string,
-  context: Record<string, unknown> = {},
-): string | undefined {
-  if (stateId === 'awaitBossReply') return formatAwaitBossReplyEntry(context);
+function formatStateEntry(stateId: string): string | undefined {
   if (SUPPRESSED_ENTRY_STATES.has(stateId)) return undefined;
   if (stateId === 'failed') return '◆ failed';
   const meta = stateMetadata.get(stateId);
@@ -692,13 +920,23 @@ function stateTelemetryPayload(
   event: unknown,
   context: Record<string, unknown>,
 ): Record<string, unknown> {
-  const payload: Record<string, unknown> = { from, to, event };
+  const payload: Record<string, unknown> = {
+    from,
+    to,
+    event: normalizeEventForTelemetry(event),
+  };
   if (to === 'awaitBossReply') {
     const pendingBossQuestion = pendingBossQuestionFromContext(context);
     if (pendingBossQuestion !== undefined) {
       payload.pendingBossQuestion = pendingBossQuestion;
     }
   }
+  if (to === 'failed') {
+    const lastError = normalizeErrorFull(context.lastError);
+    if (lastError !== undefined) {
+      payload.lastError = lastError;
+    }
+  }
   return payload;
 }
 
@@ -715,11 +953,16 @@ export const _internal = {
   STATE_LABELS,
   stateMetadata,
   pendingBossQuestionFromContext,
-  formatAwaitBossReplyEntry,
+  formatAwaitBossReplyQuestion,
+  formatAwaitBossReplyMarker,
   formatStateEntry,
   formatTransition,
   formatClassification,
   stateTelemetryPayload,
+  normalizeErrorCompact,
+  normalizeErrorFull,
+  normalizeEventForTelemetry,
+  VERBATIM_PAYLOAD_FIELDS,
 };
 
 export default function createPlaybookRuntime(
@@ -809,12 +1052,24 @@ export default function createPlaybookRuntime(
           if (transitionLine !== undefined) {
             enqueueEmit(() => ports.emitStatus(transitionLine));
           }
-          const entryLine = formatStateEntry(to, context);
+          // awaitBossReply surfaces two lines per PBRT-3 / PBRT-14: the
+          // full player question as captain speech, then the rider-less
+          // routing marker. The full-question telemetry rides
+          // stateTelemetryPayload above.
+          if (to === 'awaitBossReply') {
+            const questionLine = formatAwaitBossReplyQuestion(context);
+            const markerLine = formatAwaitBossReplyMarker(context);
+            enqueueEmit(() => ports.emitStatus(questionLine));
+            enqueueEmit(() => ports.emitStatus(markerLine));
+            return;
+          }
+          const entryLine = formatStateEntry(to);
           if (entryLine === undefined) return;
           if (to === 'failed') {
             const lastError = (snap.context as { lastError?: unknown })
               ?.lastError;
-            enqueueEmit(() => ports.emitStatus(entryLine, { lastError }));
+            const data = { lastError: normalizeErrorCompact(lastError) };
+            enqueueEmit(() => ports.emitStatus(entryLine, data));
           } else {
             enqueueEmit(() => ports.emitStatus(entryLine));
           }

package/reference/sdlc/code.playbook/code.tmux-play.d.ts

@@ -1,2 +1,6 @@
 import type { Captain } from '@sublang/cligent/tmux-play';
+export interface CodeOptions {
+    committer?: 'coder' | 'reviewer';
+}
+export declare function validateCodeOptions(captainOptions: unknown): CodeOptions;
 export default function createCodeTmuxPlayCaptain(options: unknown): Captain;

package/reference/sdlc/code.playbook/code.tmux-play.js

@@ -1,15 +1,62 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 import createPlaybookRuntime from './code.playbook.js';
+// PBRT-29/30: CODE runtime options are carried under
+// `captain.options.code`, a namespaced object the host forwards
+// verbatim through `captain.options`. cligent neither reads nor
+// validates `options.code` (PBRT-30); this adapter is the sole
+// validator. The CODE options schema defines one key, `committer`: an
+// optional Committer-alias player id, one of the baked player ids
+// `coder` / `reviewer`. A valid `options.code` is absent, `{}`, or
+// `{ committer: 'coder' | 'reviewer' }`; every other key is unknown
+// and rejected with a path-named error, and an out-of-range
+// `committer` value is rejected naming `captain.options.code.committer`.
+// A further CODE option shall be introduced as its own higher-numbered
+// item that widens `CODE_OPTION_KEYS`; the validator still fails closed
+// on stray keys.
+const CODE_OPTION_KEYS = new Set(['committer']);
+const COMMITTER_PLAYER_IDS = new Set(['coder', 'reviewer']);
+export function validateCodeOptions(captainOptions) {
+    const code = readCodeNamespace(captainOptions);
+    if (code === undefined)
+        return {};
+    if (typeof code !== 'object' || code === null || Array.isArray(code)) {
+        throw new Error('captain.options.code must be an object');
+    }
+    for (const key of Object.keys(code)) {
+        if (!CODE_OPTION_KEYS.has(key)) {
+            throw new Error(`Unknown config field captain.options.code.${key}`);
+        }
+    }
+    const options = {};
+    const committer = code.committer;
+    if (committer !== undefined) {
+        if (typeof committer !== 'string' || !COMMITTER_PLAYER_IDS.has(committer)) {
+            throw new Error("captain.options.code.committer must be 'coder' or 'reviewer'");
+        }
+        options.committer = committer;
+    }
+    return options;
+}
+function readCodeNamespace(captainOptions) {
+    if (typeof captainOptions !== 'object' ||
+        captainOptions === null ||
+        Array.isArray(captainOptions)) {
+        return undefined;
+    }
+    return captainOptions.code;
+}
 // Captain factory per TMUX-014: `(options: unknown) => Captain`.
-// `options` is whatever `captain.options` carries in the YAML config.
-// The per-run player identity strings (`coderPlayer`, `reviewerPlayer`)
-// are derived from `session.players` at init time per PBRT-4 —
-// preferring each entry's `model` and falling back to `adapter` when
-// no model is pinned — so player prompts and commit-message trailers
-// carry the concrete model identity (e.g. `claude-opus-4-7`) rather
-// than the adapter family name (e.g. `claude`). Any same-named keys
-// in `options` are ignored.
+// `options` is whatever `captain.options` carries in the YAML config;
+// CODE reads only the namespaced `options.code` (PBRT-30). The per-run
+// player identity strings (`coderPlayer`, `reviewerPlayer`) are
+// derived from `session.players` at init time per PBRT-4 — preferring
+// each entry's `model` and falling back to `adapter` when no model is
+// pinned — so player prompts and commit-message trailers carry the
+// concrete model identity (e.g. `claude-opus-4-7`) rather than the
+// adapter family name (e.g. `claude`). They come from `session.players`
+// independent of `captain.options.code` and override any same-named
+// keys.
 export default function createCodeTmuxPlayCaptain(options) {
     // CaptainSession is bound at init time and persists across turns;
     // CaptainContext is rebuilt per turn and carries the call
@@ -21,17 +68,28 @@ export default function createCodeTmuxPlayCaptain(options) {
     let activeContext;
     return {
         async init(session) {
+            // PBRT-30: validate `captain.options.code` before constructing
+            // the runtime so a stray key fails `init` closed with a
+            // path-named error; the empty schema yields an empty options set.
+            const codeOptions = validateCodeOptions(options);
             const playerIdentity = (id) => {
                 const entry = session.players.find((p) => p.id === id);
                 return entry?.model ?? entry?.adapter;
             };
             const coderPlayer = playerIdentity('coder');
             const reviewerPlayer = playerIdentity('reviewer');
-            runtime = createPlaybookRuntime({
-                ...options,
+            // Identity strings from `session.players` override any same-named
+            // keys and are independent of `captain.options.code` (PBRT-30).
+            // The validated `committer` alias threads in as the runtime's
+            // Committer player id (`committerPlayer`, PBRT-8).
+            const runtimeOptions = {
                 coderPlayer,
                 reviewerPlayer,
-            });
+                ...(codeOptions.committer !== undefined
+                    ? { committerPlayer: codeOptions.committer }
+                    : {}),
+            };
+            runtime = createPlaybookRuntime(runtimeOptions);
             const ports = {
                 callPlayer: async (playerId, prompt, _signal) => {
                     if (!activeContext) {
@@ -54,7 +112,12 @@ export default function createCodeTmuxPlayCaptain(options) {
                     if (!activeContext) {
                         throw new Error('callJudge invoked outside a Boss turn');
                     }
-                    const r = await activeContext.callCaptain(prompt);
+                    // PBRT-15 / DR-007: run the judge call hidden so its JSON
+                    // reply never reaches the Boss pane; the runtime composes the
+                    // human-readable pane lines (PBRT-3) from the parsed result.
+                    const r = await activeContext.callCaptain(prompt, {
+                        visibility: 'hidden',
+                    });
                     if (r.status !== 'ok') {
                         throw new Error(r.error ?? `callCaptain status "${r.status}"`);
                     }