@sublang/playbook 14.1.0 → 15.1.0

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

@@ -28,18 +28,27 @@ import {
 } from '../../../src/accepted-outcome.js';
 
 import {
+  ABORTED_FAILURE_CAUSE,
   assertJsonSafe,
   assertPlaybookEffectLedger,
   assertPlaybookRuntimeSnapshot,
+  attachPlaybookFailureCause,
   combineAbortSignals,
   composePlayerContinuation,
+  createFailureCauseRetention,
   createNestedPlaybookBridge,
   detachPersistedMachineSnapshot,
+  effectAuthorizedPreExistingBlock,
+  governedSettlementCause,
   normalizeError,
+  normalizeErrorCompact,
+  normalizeErrorFull,
   normalizePlaybookSnapshot,
   PlaybookSemanticCandidateStructureError,
+  playerFailureCause,
   reconcilePlaybookSemanticEvidence,
   renderGovernedOutcomeContract,
+  runtimeDefectCause,
   snapshotJsonValue,
   snapshotPlaybookSession,
   terminalOutcomesFromMachine,
@@ -80,6 +89,7 @@ import type {
   PlaybookEffectBoundaryStart,
   PlaybookEffectLedger,
   PlaybookEffectLedgerCapability,
+  PlaybookFailureCause,
   PlaybookPendingBossQuestion,
   PlaybookPendingCall,
   PlaybookPorts,
@@ -699,20 +709,6 @@ function combineSignals(
   return combineAbortSignals(a, b);
 }
 
-function normalizeErrorCompact(
-  err: unknown,
-): { name: string; message: string } | undefined {
-  if (err === undefined || err === null) return undefined;
-  const normalized = normalizeError(err);
-  return { name: normalized.name, message: normalized.message };
-}
-
-function normalizeErrorFull(
-  err: unknown,
-): { name: string; message: string; stack?: string } | undefined {
-  return err === undefined || err === null ? undefined : normalizeError(err);
-}
-
 // DR-028's unified empty predicate: a missing, empty, or whitespace-only
 // `finalText` on an `ok` player result is the one shape that earns exactly
 // one corrective re-ask before the existing failure path applies. Mirrors
@@ -1240,6 +1236,7 @@ function telemetryPayload(
   event: unknown,
   context: Record<string, unknown>,
   hiddenQuestionId?: string,
+  failedError?: NormalizedError,
 ): JsonValue {
   const pendingBossQuestions = pendingQuestionsForState(
     state,
@@ -1254,7 +1251,7 @@ function telemetryPayload(
     state,
     ...(pendingBossQuestions.length > 0 ? { pendingBossQuestions } : {}),
     ...(state.activeStateIds.includes('failed')
-      ? { lastError: normalizeErrorFull(context.lastError) ?? null }
+      ? { lastError: failedError ?? normalizeErrorFull(context.lastError) ?? null }
       : {}),
   } satisfies Record<string, unknown>;
   assertJsonSafe(payload);
@@ -1278,6 +1275,7 @@ interface ActiveDeferredContinuation {
   readonly result: DeferredValue<PlayerResult>;
   readonly acknowledged: DeferredValue<PlayerResult>;
   playerContinuation?: string | false;
+  baseline?: PlaybookRepositoryReceipt['baseline'];
   input?: PlayerInput;
   playerId?: string;
 }
@@ -1350,6 +1348,85 @@ function createDecidePlaybookRuntime(
   const semanticCompletionQueue = new PQueue({ concurrency: 1 });
   const governedOutputsByBoundaryId = new Map<string, PlayerOutput>();
   const governedFailuresByBoundaryId = new Map<string, Error>();
+  // DR-063 §2: the causes decided for thrown values that cannot carry the
+  // marker — a string, a frozen error — kept by identity for as long as the
+  // failure stands, so every surface that reads the FSM's own `lastError`
+  // publishes the cause decided for exactly that value (mirrors the shared
+  // factory).
+  const failureCauses = createFailureCauseRetention();
+  // DR-063 §2: each decided failure is one occurrence in decision order, kept
+  // by the player call or governed boundary it was decided for, so a cohort
+  // names the member that failed first whatever value its siblings threw.
+  type FailureOccurrence = {
+    readonly cause: PlaybookFailureCause;
+    readonly sequence: number;
+  };
+  let failureSequence = 0;
+  const playerCallFailures = new Map<string, FailureOccurrence>();
+  const governedFailureOccurrences = new Map<string, FailureOccurrence>();
+  const recordFailure = (
+    occurrences: Map<string, FailureOccurrence>,
+    key: string,
+    cause: PlaybookFailureCause,
+  ): void => {
+    occurrences.set(key, { cause, sequence: ++failureSequence });
+  };
+  const failedStateError = (
+    context: Record<string, unknown>,
+  ): NormalizedError | undefined => {
+    const normalized = normalizeErrorFull(context.lastError);
+    if (normalized === undefined || normalized.cause !== undefined) {
+      return normalized;
+    }
+    return {
+      ...normalized,
+      cause:
+        failureCauses.causeOf(context.lastError) ??
+        runtimeDefectCause(normalized.message),
+    };
+  };
+  const playerResultFailureCause = (
+    roleId: RoleId,
+    playerId: string | undefined,
+    result: PlayerResult,
+  ): PlaybookFailureCause =>
+    result.status === 'aborted'
+      ? ABORTED_FAILURE_CAUSE
+      : playerFailureCause({
+          roleId,
+          ...(playerId === undefined ? {} : { playerId }),
+          error:
+            result.error ??
+            `callPlayer status ${JSON.stringify(result.status)}`,
+        });
+  // A rejected player port or a result the runtime cannot read is a
+  // `player-failed` failure named by role; the turn's own abort is `aborted`.
+  // A cancellation the runtime itself issued — a proposal cancelled because
+  // its sibling failed — is not this player's failure and decides nothing, so
+  // the originator's cause stands; every other failure is decided afresh and
+  // recorded as this call's occurrence, whatever an earlier failure threw.
+  const decidePlayerCallFailure = (
+    error: unknown,
+    roleId: RoleId,
+    playerId: string | undefined,
+    signal: AbortSignal,
+    callId: string,
+  ): void => {
+    const turn = currentSignal;
+    const turnAborted = turn !== undefined && turn.aborted;
+    if (!turnAborted && signal.aborted) return;
+    const cause =
+      turn !== undefined && turn.aborted && Object.is(error, turn.reason)
+        ? ABORTED_FAILURE_CAUSE
+        : playerFailureCause({
+            roleId,
+            ...(playerId === undefined ? {} : { playerId }),
+            error,
+          });
+    attachPlaybookFailureCause(error, cause);
+    failureCauses.retain(error, cause);
+    recordFailure(playerCallFailures, callId, cause);
+  };
   const governedEvidenceByBoundaryId = new Map<
     string,
     { readonly finalText: string; readonly semanticCandidate?: JsonValue }
@@ -2154,6 +2231,7 @@ function createDecidePlaybookRuntime(
     continuation?: {
       readonly resume?: string | false;
       readonly callId: string;
+      readonly preExistingBlock?: string;
     },
   ): Promise<DeferredContinuationEnvelope> => {
     const aborts = abortReasonClassifier(signal);
@@ -2165,7 +2243,13 @@ function createDecidePlaybookRuntime(
     const roleId = input.role;
     const playerId = resolvedPlayerId(roleId);
     const playerKey = continuationKey(roleId, playerId);
-    const freshPrompt = composeInvocationPrompt(input);
+    // DR-062 §4: composed from this call's own baseline observation, so the
+    // prompt the trace records is the prompt the player is sent.
+    const withPreExisting = (text: string): string =>
+      continuation?.preExistingBlock === undefined
+        ? text
+        : `${text}\n\n${continuation.preExistingBlock}`;
+    const freshPrompt = withPreExisting(composeInvocationPrompt(input));
     let resume: PlayerCallOptions['resume'];
     try {
       signal.throwIfAborted();
@@ -2178,7 +2262,10 @@ function createDecidePlaybookRuntime(
       latchControlPlaneError(error, signal);
       throw error;
     }
-    const prompt = resume === false ? freshPrompt : composeInvocationPrompt(input, true);
+    const prompt =
+      resume === false
+        ? freshPrompt
+        : withPreExisting(composeInvocationPrompt(input, true));
     const callId =
       continuation?.callId ?? `player-${++playerCallSequence}`;
     const identity = {
@@ -2244,6 +2331,7 @@ function createDecidePlaybookRuntime(
         // A rejected call produced no authoritative result, so the previous
         // token remains untouched. This also covers a coder promise that
         // resolves after its invocation signal was cancelled.
+        decidePlayerCallFailure(error, roleId, playerId, signal, callId);
         latchControlPlaneError(error, signal);
         try {
           await emitFailure(error);
@@ -2257,6 +2345,7 @@ function createDecidePlaybookRuntime(
       try {
         result = validatePlayerResult(rawResult);
       } catch (error) {
+        decidePlayerCallFailure(error, roleId, playerId, signal, callId);
         latchControlPlaneError(error, signal);
         try {
           await emitFailure(error);
@@ -2348,17 +2437,29 @@ function createDecidePlaybookRuntime(
     };
   };
 
+  // DR-063 §1/§2: the cause of an unresolved governed settlement is decided
+  // here — a reconciled mismatch supplies its receipt-read cause, an abort or
+  // a refused adjudication its own code, anything else a runtime defect — and
+  // rides the failure the boundary throws.
   const unresolvedGovernedEvidence = (
     boundaryId: string,
     reason: string,
     error?: unknown,
+    cause?: PlaybookFailureCause,
   ): void => {
-    governedFailuresByBoundaryId.set(
-      boundaryId,
+    const aborted =
+      error !== undefined &&
+      currentSignal?.aborted === true &&
+      Object.is(error, currentSignal.reason);
+    const decided = governedSettlementCause(reason, error, aborted, cause);
+    const failure =
       error instanceof Error
         ? error
-        : new Error(`DECIDE governed outcome remains unresolved: ${reason}`),
-    );
+        : new Error(`DECIDE governed outcome remains unresolved: ${reason}`);
+    attachPlaybookFailureCause(failure, decided);
+    failureCauses.retain(failure, decided);
+    recordFailure(governedFailureOccurrences, boundaryId, decided);
+    governedFailuresByBoundaryId.set(boundaryId, failure);
   };
 
   const spendSemanticCorrectionBudget = async (
@@ -2706,6 +2807,8 @@ function createDecidePlaybookRuntime(
           unresolvedGovernedEvidence(
             boundary.boundaryId,
             reconciliation.reason,
+            undefined,
+            reconciliation.cause,
           );
           return { finalText, semanticCandidate, unresolved: true as const };
         }
@@ -2952,11 +3055,23 @@ function createDecidePlaybookRuntime(
                 envelope.result.status !== 'ok' &&
                 !cohortOperations.signal.aborted
               ) {
-                cohortOperations.abort(
+                // DR-063 §2: the cancellation carries the cause of the result
+                // that caused it, recorded as this member's occurrence, so the
+                // cohort fails for this member.
+                const cause = playerResultFailureCause(
+                  roleId,
+                  resolvedPlayerId(roleId),
+                  envelope.result,
+                );
+                const cancellation = attachPlaybookFailureCause(
                   new Error(
                     `DECIDE proposal cohort ${roleId} returned status ${JSON.stringify(envelope.result.status)}`,
                   ),
+                  cause,
                 );
+                failureCauses.retain(cancellation, cause);
+                recordFailure(playerCallFailures, member.callId, cause);
+                cohortOperations.abort(cancellation);
               }
               return envelope.result;
             } catch (error) {
@@ -3037,12 +3152,43 @@ function createDecidePlaybookRuntime(
         for (const result of acknowledgedResults.values()) {
           governedPlayerOutputs.delete(result);
         }
-        throw acknowledgementFailures.length === 1
-          ? acknowledgementFailures[0]
-          : new AggregateError(
-              acknowledgementFailures,
-              'DECIDE proposal cohort reconciliation failed',
-            );
+        const failure =
+          acknowledgementFailures.length === 1
+            ? acknowledgementFailures[0]
+            : new AggregateError(
+                acknowledgementFailures,
+                'DECIDE proposal cohort reconciliation failed',
+              );
+        // DR-063 §2: a cohort fails for the member whose failure was decided
+        // first — a rejected or non-`ok` player call, a refused adjudication,
+        // a mismatched receipt — in decision order, not in the order the
+        // players finished or the values they threw. That cause rides every
+        // error the failure can surface as: the cancellation, each member's
+        // own rejection, and the aggregate of both, never an abort.
+        const origin = cohortOperations.signal.aborted
+          ? cohortOperations.signal.reason
+          : undefined;
+        const first = ROLE_IDS.flatMap((roleId) => {
+          const member = members[roleId];
+          const occurrence =
+            member === undefined
+              ? undefined
+              : (playerCallFailures.get(member.callId) ??
+                governedFailureOccurrences.get(member.effectBoundary.boundaryId));
+          return occurrence === undefined ? [] : [occurrence];
+        }).sort((left, right) => left.sequence - right.sequence)[0];
+        const originCause =
+          first?.cause ??
+          failureCauses.causeOf(failure) ??
+          (origin === undefined ? undefined : failureCauses.causeOf(origin));
+        if (originCause !== undefined) {
+          for (const candidate of [failure, origin, ...acknowledgementFailures]) {
+            if (candidate === undefined) continue;
+            attachPlaybookFailureCause(candidate, originCause);
+            failureCauses.retain(candidate, originCause);
+          }
+        }
+        throw failure;
       }
       for (const roleId of releaseOrder) {
         const member = members[roleId]!;
@@ -3120,6 +3266,10 @@ function createDecidePlaybookRuntime(
           const envelope = await runPlayerCall(input, signal, {
             callId: active.effectBoundary.callId,
             resume: active.playerContinuation,
+            preExistingBlock: effectAuthorizedPreExistingBlock(
+              active.effectBoundary,
+              active.baseline,
+            ),
           });
           active.result.resolve(envelope.result);
           const acknowledgedResult = await active.acknowledged.promise;
@@ -3145,8 +3295,16 @@ function createDecidePlaybookRuntime(
       const settled = await deferredEffects.repository.runExclusive({
         signal,
         effectBoundary,
-        operation: async () => {
-          envelope = await runPlayerCall(input, signal, { callId });
+        // DR-062 §4: the call's own baseline, supplied by the host that
+        // captured it under this exclusive claim.
+        operation: async (context) => {
+          envelope = await runPlayerCall(input, signal, {
+            callId,
+            preExistingBlock: effectAuthorizedPreExistingBlock(
+              effectBoundary,
+              context?.baseline,
+            ),
+          });
           return envelope.result;
         },
         completeEffectBoundary: completionEvidenceFor(
@@ -3214,12 +3372,18 @@ function createDecidePlaybookRuntime(
           ));
         }
         if (result.status !== 'ok') {
-          throw new Error(
-            `${roleLabel(roleId)}${
-              playerId === undefined ? '' : ` (${playerId})`
-            } returned status "${result.status}"${
-              result.error ? `: ${result.error}` : ''
-            }`,
+          // DR-063 §2: the failure Error built for a non-`ok` result carries
+          // the cause decided for that exact result.
+          const cause = playerResultFailureCause(roleId, playerId, result);
+          throw attachPlaybookFailureCause(
+            new Error(
+              `${roleLabel(roleId)}${
+                playerId === undefined ? '' : ` (${playerId})`
+              } returned status "${result.status}"${
+                result.error ? `: ${result.error}` : ''
+              }`,
+            ),
+            cause,
           );
         }
         const finalText = result.finalText ?? '';
@@ -3365,6 +3529,9 @@ function createDecidePlaybookRuntime(
         hiddenDeferredOperationId === undefined
           ? undefined
           : 'commitCoderProposal',
+        state.activeStateIds.includes('failed')
+          ? failedStateError(context)
+          : undefined,
       );
       const describedFsmPayload = snapshotJsonValue(
         fsmPayload,
@@ -3444,7 +3611,7 @@ function createDecidePlaybookRuntime(
         }
         const lastError =
           activeStateId === 'failed'
-            ? normalizeErrorCompact(context.lastError)
+            ? normalizeErrorCompact(failedStateError(context))
             : undefined;
         const description = STATE_DESCRIPTIONS[activeStateId];
         if (description === undefined) continue;
@@ -3456,7 +3623,9 @@ function createDecidePlaybookRuntime(
             ? '◆ workflow failed; awaiting Boss recovery.'
             : `⤷ ${roleLabel(roleState.role)}: ${description}`,
           activeStateId,
-          lastError === undefined ? undefined : { lastError },
+          lastError === undefined
+            ? undefined
+            : snapshotJsonValue({ lastError }, 'DECIDE failed status data'),
         );
       }
     } catch (error) {
@@ -3640,7 +3809,7 @@ function createDecidePlaybookRuntime(
       signal,
       operationId,
       effectBoundary,
-      operation: async ({ playerContinuation }) => {
+      operation: async ({ playerContinuation, baseline }) => {
         if (
           playerContinuation !== false &&
           (typeof playerContinuation !== 'string' ||
@@ -3651,6 +3820,8 @@ function createDecidePlaybookRuntime(
           );
         }
         active.playerContinuation = playerContinuation;
+        // DR-062 §4: the continuation's own baseline.
+        active.baseline = baseline;
         readiness.resolve({ status: 'ready' });
         return active.result.promise;
       },
@@ -3957,7 +4128,10 @@ function createDecidePlaybookRuntime(
     const actions = deriveControlCandidates().map(({ action }) => ({
       ...action,
     }));
-    const lastError = normalizeErrorFull(context.lastError);
+    const lastError =
+      state.stateId === 'failed'
+        ? failedStateError(context)
+        : normalizeErrorFull(context.lastError);
     const stateDescription =
       unresolved || state.stateId === undefined
         ? undefined
@@ -4035,6 +4209,8 @@ function createDecidePlaybookRuntime(
     const turnId = ++turnSequence;
     const callId = `apply-${++applyCallSequence}`;
     currentTurnId = turnId;
+    playerCallFailures.clear();
+    governedFailureOccurrences.clear();
     currentSignal = signal;
     currentAborts = abortReasonClassifier(signal);
     controlPlaneError = undefined;
@@ -4306,7 +4482,7 @@ function createDecidePlaybookRuntime(
       return abortedResult(signal);
     }
     if (state.activeStateIds.includes('failed')) {
-      const error = normalizeErrorFull(context.lastError);
+      const error = failedStateError(context);
       return {
         outcome: 'failed',
         state,
@@ -4504,12 +4680,17 @@ function createDecidePlaybookRuntime(
       }
       const state = currentState();
       if (state.status !== 'active' || !state.quiescent) return undefined;
-      const machine = detachPersistedMachineSnapshot(
-        actor.getPersistedSnapshot(),
-      );
       const context = (
         actor.getSnapshot() as SnapshotFrom<typeof decideMachine>
       ).context as unknown as Record<string, unknown>;
+      // DR-063 §2: the failed state's `lastError` is persisted as every live
+      // surface publishes it, completed from the runtime's own cause slot.
+      const machine = detachPersistedMachineSnapshot(
+        actor.getPersistedSnapshot(),
+        state.stateId === 'failed'
+          ? { lastError: failedStateError(context) }
+          : {},
+      );
       if (deferredEffects !== undefined) {
         synchronizeDeferredProjection(readEffectLedger());
       }
@@ -4678,6 +4859,8 @@ function createDecidePlaybookRuntime(
 
       const turnId = ++turnSequence;
       currentTurnId = turnId;
+      playerCallFailures.clear();
+      governedFailureOccurrences.clear();
       currentSignal = turn.signal;
       currentAborts = abortReasonClassifier(turn.signal);
       controlPlaneError = undefined;
@@ -4806,7 +4989,7 @@ function createDecidePlaybookRuntime(
             : {
                 outcome: 'failed',
                 state,
-                error: normalizeErrorFull(effectiveError) ?? {
+                error: failedStateError({ lastError: effectiveError }) ?? {
                   name: 'Error',
                   message: String(effectiveError),
                 },
@@ -4830,7 +5013,7 @@ function createDecidePlaybookRuntime(
         result = {
           outcome: drainAborted ? 'aborted' : 'failed',
           state,
-          error: normalizeErrorFull(effectiveError) ?? {
+          error: failedStateError({ lastError: effectiveError }) ?? {
             name: 'Error',
             message: String(effectiveError),
           },

package/reference/sdlc/review.md

@@ -101,7 +101,7 @@ If you accept any item, make minimal changes and add one new review-fix commit;
 Follow @specs/packages/git.md.
 Make the commit message explain concisely what changed and why, including relevant verification.
 Identify every new commit you make.
-Coder is <coder-llm>; Reviewer is <reviewer-llm>.
+Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.
 
 If you reject every item, change nothing and make no commit.
 Report every disposition, all relevant run results, and every rebuttal.

package/reference/sdlc/review.playbook/review.fsm.js

@@ -67,7 +67,7 @@ const CODER_DISPOSITION_PROMPT = [
     'Follow @specs/packages/git.md.',
     'Make the commit message explain concisely what changed and why, including relevant verification.',
     'Identify every new commit you make.',
-    'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
+    'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.',
     '',
     'If you reject every item, change nothing and make no commit.',
     'Report every disposition, all relevant run results, and every rebuttal.',

package/reference/sdlc/review.playbook/review.fsm.ts

@@ -156,7 +156,7 @@ const CODER_DISPOSITION_PROMPT = [
   'Follow @specs/packages/git.md.',
   'Make the commit message explain concisely what changed and why, including relevant verification.',
   'Identify every new commit you make.',
-  'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
+  'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.',
   '',
   'If you reject every item, change nothing and make no commit.',
   'Report every disposition, all relevant run results, and every rebuttal.',

package/reference/sdlc/review.playbook/review.gears.md

@@ -65,7 +65,7 @@ When Reviewer raises or keeps any finding, Captain shall relay the caller input
 > Follow @specs/packages/git.md.
 > Make the commit message explain concisely what changed and why, including relevant verification.
 > Identify every new commit you make.
-> Coder is <coder-llm>; Reviewer is <reviewer-llm>.
+> Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.
 >
 > If you reject every item, change nothing and make no commit.
 > Report every disposition, all relevant run results, and every rebuttal.