@sublang/playbook 8.0.0 → 9.0.0

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

@@ -561,6 +561,31 @@ function stateDigestLine(
   ].join('; ');
 }
 
+// CAPTAIN-5's mirrored ledger member holds the runtime snapshot's
+// pending-question projection — entries of `{ questionId, asker, question,
+// sourceItem }` — never a raw telemetry payload: the linked runtime's state
+// telemetry carries the singular full-context question, whose extra
+// runtime-internal fields (`resumeStateId`) fail the durable snapshot's
+// leaf-projection equality (CAPTAIN-41) and with it headless settlement.
+function mirroredBossQuestions(value: unknown): unknown {
+  if (value === undefined || value === null) return undefined;
+  const entries = Array.isArray(value) ? value : [value];
+  return entries.map((entry) => {
+    if (typeof entry !== 'object' || entry === null) return entry;
+    const record = entry as Record<string, unknown>;
+    const projected: Record<string, unknown> = {};
+    if (record.questionId !== undefined) {
+      projected.questionId = record.questionId;
+    }
+    if (record.asker !== undefined) projected.asker = record.asker;
+    if (record.question !== undefined) projected.question = record.question;
+    if (record.sourceItem !== undefined) {
+      projected.sourceItem = record.sourceItem;
+    }
+    return projected;
+  });
+}
+
 function pendingQuestionLines(pending: unknown): string[] {
   const list = Array.isArray(pending)
     ? pending
@@ -2553,8 +2578,9 @@ export function createPlaybookCaptainShell(
     }
 
     if (leafFrame() === frame) {
-      pendingBossQuestions =
-        record.pendingBossQuestions ?? record.pendingBossQuestion;
+      pendingBossQuestions = mirroredBossQuestions(
+        record.pendingBossQuestions ?? record.pendingBossQuestion,
+      );
       lastError = normalizeErrorCompact(record.lastError);
       if (state.quiescent && state.tags.includes('playbook.parked')) {
         await setMode(
@@ -3518,7 +3544,7 @@ export function createPlaybookCaptainShell(
         // runtime publishes before disposal removes the frame. The opaque run
         // output remains runtime-to-runtime data and never becomes Captain
         // evidence (CAPPLAY-10).
-        activeTurn?.settlementFacts.push(rootCompletionFact(frame));
+        activeTurn?.settlementFacts.push(rootCompletionFact(frame, result));
         await runEffect(() => disposeStack('final'));
       }
       return;
@@ -4606,10 +4632,10 @@ export function createPlaybookCaptainShell(
   // The controller port (DR-029): host validation is the sole effector.
   // -------------------------------------------------------------------------
 
-  // The leaf's published state description, read from its control view the
-  // same way the digest reads it. A leaf without the pair — or one whose view
-  // cannot be read at this moment — publishes none, and the summary then says
-  // so instead of falling back to the state id.
+  // The legacy state-description channel, read from the live control view the
+  // same way the digest reads it. DR-037 makes the terminal result authoritative
+  // for completion; this remains only for an older runtime that omits the new
+  // optional member.
   const leafStateDescription = (
     frame: EngagementFrame,
   ): string | undefined => {
@@ -4621,10 +4647,21 @@ export function createPlaybookCaptainShell(
     }
   };
 
-  const rootCompletionFact = (frame: EngagementFrame): string => {
-    const published = leafStateDescription(frame);
+  const rootCompletionFact = (
+    frame: EngagementFrame,
+    result: Extract<PlaybookRunResult, { outcome: 'terminal' }>,
+  ): string => {
+    const returned =
+      result.stateDescription === undefined
+        ? ''
+        : compactEvidence(result.stateDescription);
+    const legacy = returned === '' ? leafStateDescription(frame) : undefined;
     const description =
-      published === undefined ? '' : compactEvidence(published);
+      returned !== ''
+        ? returned
+        : legacy === undefined
+          ? ''
+          : compactEvidence(legacy);
     return description === ''
       ? `${frameLabel(frame)} completed; its runtime published no result description.`
       : `${frameLabel(frame)} completed; its runtime-published result meaning was ${quoteEvidence(description)}.`;

package/reference/sdlc/decide.playbook/decide.fsm.d.ts

@@ -200,7 +200,7 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
 } | {
     type: "validReviewSuccess";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "commitCoderProposal" | "reviewCommit" | "reportedReviewFailure" | {
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "reportedReviewFailure" | "commitCoderProposal" | "reviewCommit" | {
     independentProposals: {
         coder: "complete" | "working" | "waiting";
         reviewer: "complete" | "working" | "waiting";

package/reference/sdlc/decide.playbook/decide.playbook.d.ts

@@ -27,6 +27,7 @@ declare function normalizeErrorFull(err: unknown): {
     stack?: string;
 } | undefined;
 declare function pendingQuestionsFromContext(context: Record<string, unknown>): PendingBossQuestion[];
+declare function pendingQuestionsForState(state: PlaybookState, context: Record<string, unknown>): PendingBossQuestion[];
 export declare const createPlaybookRuntime: PlaybookRuntimeFactory<PlaybookRuntimeOptions>;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
@@ -38,6 +39,7 @@ export declare const _internal: {
     parseAdjudication: typeof parseAdjudication;
     combineSignals: typeof combineSignals;
     pendingQuestionsFromContext: typeof pendingQuestionsFromContext;
+    pendingQuestionsForState: typeof pendingQuestionsForState;
     normalizeErrorCompact: typeof normalizeErrorCompact;
     normalizeErrorFull: typeof normalizeErrorFull;
     STATE_DESCRIPTIONS: Readonly<Record<string, string>>;