@sublang/playbook 12.0.0 → 12.2.0

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -4080,7 +4080,10 @@ function validateEffectLedgerAuthority(value, record, owner) {
   return authority;
 }
 
-function applyEffectLedgerCommands(
+// Exported for the private worktree host-capability constructor in
+// repository-effects.js, so an external host's in-memory ledger applies the
+// exact command semantics the durable Captain record applies.
+export function applyEffectLedgerCommands(
   ledgerValue,
   authority,
   uncertain,

package/reference/sdlc/code.playbook/host-capabilities.d.ts

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type PlaybookRepositoryDisposition =
+  | 'unchanged'
+  | 'one-descendant-commit'
+  | 'deferred';
+export type RepositoryReceiptClassification =
+  | 'unchanged'
+  | 'one-descendant-commit'
+  | 'multiple-commits'
+  | 'rewritten-or-non-descendant'
+  | 'worktree-only-change'
+  | 'concurrent-or-foreign-change'
+  | 'observation-ambiguous';
+export declare const REPOSITORY_RECEIPT_CLASSIFICATIONS: readonly RepositoryReceiptClassification[];
+
+export interface RepositoryIdentity {
+  readonly worktree: string;
+  readonly gitDir: string;
+}
+export interface PlaybookRepositoryObservation extends RepositoryIdentity {
+  readonly head: string;
+  readonly projection: Readonly<Record<string, JsonValue>>;
+  readonly projectionDigest: string;
+}
+export interface PlaybookRepositoryReceipt {
+  readonly classification: RepositoryReceiptClassification;
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly commitOid?: string;
+}
+export interface RepositoryReceiptOptions {
+  readonly allowedDispositions: readonly PlaybookRepositoryDisposition[];
+}
+
+export declare function observeGitRepository(
+  cwd: string,
+): Promise<PlaybookRepositoryObservation>;
+export declare function classifyRepositoryReceipt(
+  baseline: PlaybookRepositoryObservation,
+  after: PlaybookRepositoryObservation,
+  options: RepositoryReceiptOptions,
+): Promise<PlaybookRepositoryReceipt>;
+export declare function captureRepositoryReceipt(
+  baseline: PlaybookRepositoryObservation,
+  options: RepositoryReceiptOptions,
+): Promise<PlaybookRepositoryReceipt>;
+
+export interface PlaybookPendingBossQuestion {
+  readonly questionId: string;
+  readonly asker:
+    | { readonly kind: 'captain' }
+    | { readonly kind: 'role'; readonly roleId: string };
+  readonly question: string;
+  readonly sourceItem?: string;
+}
+export interface PlaybookEffectBoundary {
+  readonly sequence: number;
+  readonly boundaryId: string;
+  readonly attemptId: string;
+  readonly attemptNumber: number;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly turnId: number;
+  readonly callId: string;
+  readonly roleId: string;
+  readonly sourceStateId: string;
+  readonly sourceOutcomeSchema: JsonValue;
+  readonly dispositions: readonly PlaybookRepositoryDisposition[];
+  readonly canonicalWorktree: RepositoryIdentity;
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly physicalReceipt?: PlaybookRepositoryReceipt;
+  readonly finalText?: string;
+  readonly semanticCandidate?: JsonValue;
+  readonly initialSemanticCandidate?: JsonValue;
+  readonly correctionBudget: {
+    readonly limit: 1;
+    readonly spent: boolean;
+  };
+  readonly cohortId?: string;
+  readonly logicalOperationId?: string;
+}
+export type PlaybookEffectBoundaryStart = Omit<
+  PlaybookEffectBoundary,
+  | 'sequence'
+  | 'attemptId'
+  | 'attemptNumber'
+  | 'after'
+  | 'physicalReceipt'
+  | 'finalText'
+  | 'semanticCandidate'
+  | 'initialSemanticCandidate'
+>;
+export type EffectBoundarySeed = Omit<
+  PlaybookEffectBoundaryStart,
+  'playbookId' | 'canonicalWorktree' | 'baseline' | 'cohortId'
+>;
+export interface PlaybookEffectLogicalOperation {
+  readonly sequence: number;
+  readonly operationId: string;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly boundaryIds: readonly string[];
+  readonly originalBaseline: PlaybookRepositoryObservation;
+  readonly checkpoint?: PlaybookRepositoryObservation;
+  readonly pendingQuestion?: PlaybookPendingBossQuestion;
+  readonly playerContinuation?: JsonValue;
+  readonly checkpointRestorationEligible: boolean;
+  readonly logicalReceipt?: PlaybookRepositoryReceipt;
+}
+export interface PlaybookEffectLedger {
+  readonly schemaVersion: 1;
+  readonly revision: number;
+  readonly boundaries: readonly PlaybookEffectBoundary[];
+  readonly logicalOperations: readonly PlaybookEffectLogicalOperation[];
+}
+export type PlaybookEffectLedgerCommand =
+  | {
+      readonly kind: 'start-boundaries';
+      readonly boundaries: readonly [
+        PlaybookEffectBoundaryStart,
+        ...PlaybookEffectBoundaryStart[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-boundaries';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        },
+        ...{
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        }[],
+      ];
+    }
+  | {
+      readonly kind: 'append-logical-operations';
+      readonly operations: readonly [
+        Omit<PlaybookEffectLogicalOperation, 'sequence'>,
+        ...Omit<PlaybookEffectLogicalOperation, 'sequence'>[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-logical-operations';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        },
+        ...{
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        }[],
+      ];
+    };
+export type PlaybookEffectLedgerCommandBatch = readonly [
+  PlaybookEffectLedgerCommand,
+  ...PlaybookEffectLedgerCommand[],
+];
+export interface PlaybookEffectLedgerCapability {
+  snapshot(): PlaybookEffectLedger;
+  writeAhead(
+    commands: PlaybookEffectLedgerCommandBatch,
+  ): Promise<PlaybookEffectLedger>;
+}
+
+interface RepositoryOperationSettlement<T> {
+  readonly status: 'fulfilled';
+  readonly value: T;
+}
+interface RepositoryOperationRejection {
+  readonly status: 'rejected';
+  readonly reason: unknown;
+}
+export interface RepositoryExclusiveCompletion<T> {
+  readonly boundary: PlaybookEffectBoundary;
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly outcomeReceipt: PlaybookRepositoryReceipt;
+}
+interface RepositoryDeferredBinding {
+  readonly operationId: string;
+  readonly pendingQuestion: PlaybookPendingBossQuestion;
+  readonly playerContinuation: JsonValue;
+}
+export interface RepositoryCompletionEvidence {
+  readonly finalText?: string;
+  readonly semanticCandidate?: JsonValue;
+  readonly deferred?: RepositoryDeferredBinding;
+  readonly unresolved?: true;
+}
+export interface RepositoryExclusiveResult<T> {
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly effectLedger: PlaybookEffectLedger;
+  readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface RepositoryDeferredContinuationResult<T> {
+  readonly status: 'continued';
+  readonly operation:
+    | RepositoryOperationSettlement<T>
+    | RepositoryOperationRejection;
+  readonly receipt: PlaybookRepositoryReceipt;
+  readonly logicalReceipt?: PlaybookRepositoryReceipt;
+  readonly effectLedger: PlaybookEffectLedger;
+  readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface RepositoryDeferredCheckpointMismatch {
+  readonly status: 'checkpoint-mismatch' | 'ineligible';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+interface RepositoryDeferredParked {
+  readonly status: 'parked';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+interface RepositoryDeferredRestoreResult {
+  readonly status: 'restored' | 'checkpoint-mismatch' | 'ineligible';
+  readonly effectLedger: PlaybookEffectLedger;
+}
+export interface RepositoryCapability {
+  runExclusive<T>(options: {
+    readonly signal?: AbortSignal;
+    readonly effectBoundary: EffectBoundarySeed;
+    readonly operation: (context: {
+      readonly baseline: PlaybookRepositoryObservation;
+      readonly identity: RepositoryIdentity;
+    }) => Promise<T>;
+    readonly completeEffectBoundary: (
+      completion: RepositoryExclusiveCompletion<T>,
+    ) => RepositoryCompletionEvidence | Promise<RepositoryCompletionEvidence>;
+  }): Promise<RepositoryExclusiveResult<T>>;
+  runDeferred<T>(options: {
+    readonly mode: 'continue';
+    readonly signal?: AbortSignal;
+    readonly operationId: string;
+    readonly effectBoundary: EffectBoundarySeed;
+    readonly operation: (context: {
+      readonly baseline: PlaybookRepositoryObservation;
+      readonly identity: RepositoryIdentity;
+      readonly playerContinuation: JsonValue;
+    }) => Promise<T>;
+    readonly completeEffectBoundary: (
+      completion: RepositoryExclusiveCompletion<T>,
+    ) => RepositoryCompletionEvidence | Promise<RepositoryCompletionEvidence>;
+  }): Promise<
+    RepositoryDeferredContinuationResult<T> | RepositoryDeferredCheckpointMismatch
+  >;
+  runDeferred(options: {
+    readonly mode: 'park' | 'restore';
+    readonly signal?: AbortSignal;
+    readonly operationId: string;
+  }): Promise<RepositoryDeferredParked | RepositoryDeferredRestoreResult>;
+}
+export interface HostCapabilities {
+  readonly repository: RepositoryCapability;
+  readonly effectLedger: PlaybookEffectLedgerCapability;
+}
+export interface WorktreeRepositoryCapability extends RepositoryCapability {
+  readonly identity: RepositoryIdentity;
+  observe(): Promise<PlaybookRepositoryObservation>;
+}
+export interface WorktreeHostCapabilities extends HostCapabilities {
+  readonly repository: WorktreeRepositoryCapability;
+}
+export interface WorktreeHostCapabilitiesOptions {
+  readonly cwd: string;
+  readonly playbookId: string;
+  readonly requiredRoleIds: readonly string[];
+  readonly concurrentRoleSets?: readonly (readonly string[])[];
+  readonly effectLedger?: PlaybookEffectLedger;
+}
+export declare function createWorktreeHostCapabilities(
+  options: WorktreeHostCapabilitiesOptions,
+): Promise<WorktreeHostCapabilities>;
+export declare function createFailClosedHostCapabilities(): HostCapabilities;

package/reference/sdlc/code.playbook/host-capabilities.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// DR-046: the public `@sublang/playbook/host-capabilities` facade. Every
+// member is the CLI host's own repository-effect implementation; this module
+// only narrows the accepted arguments to the declared surface.
+
+import {
+  REPOSITORY_RECEIPT_CLASSIFICATIONS,
+  captureRepositoryReceipt as capture,
+  classifyRepositoryReceipt as classify,
+  createFailClosedHostCapabilities,
+  createWorktreeHostCapabilities,
+  observeGitRepository as observe,
+} from './bin/repository-effects.js';
+
+export {
+  REPOSITORY_RECEIPT_CLASSIFICATIONS,
+  createFailClosedHostCapabilities,
+  createWorktreeHostCapabilities,
+};
+
+export async function observeGitRepository(cwd) {
+  return observe(cwd);
+}
+
+export async function classifyRepositoryReceipt(baseline, after, options) {
+  return classify(baseline, after, receiptOptions(options));
+}
+
+export async function captureRepositoryReceipt(baseline, options) {
+  return capture(baseline, receiptOptions(options));
+}
+
+function receiptOptions(options) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('repository receipt options must be an object');
+  }
+  return { allowedDispositions: options.allowedDispositions };
+}

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

@@ -64,6 +64,10 @@ const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
 const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
+// The fixed machine-syntax guard of a player's Boss-question suspension
+// (slc/link.md §Boss-reply suspension): the accepted outcome that parks on
+// Boss rather than sparing Boss a relay.
+const BOSS_QUESTION_OUTCOME = 'needsBossReply';
 const RESUMPTION_DUPLICATE_EFFECT_WARNING = 'Warning: resumption may duplicate external effects attempted after the retained boundary; verify the current world before continuing.';
 function parseRegisteredCommand(prompt) {
     const match = /^\/([A-Za-z][A-Za-z0-9_-]*)(?:\s+([\s\S]*))?$/.exec(prompt.trim());
@@ -2550,6 +2554,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (summary.acceptedOutcomeTraceKeys.has(traceKey))
             return;
         summary.acceptedOutcomeTraceKeys.add(traceKey);
+        // CAPTAIN-19/20: a saved interruption is a player reply Boss did not
+        // have to relay. A Boss-question suspension is the one accepted outcome
+        // that parks on Boss instead, so it saves nothing and counts nothing —
+        // a turn that only parked must not claim it saved an interruption.
+        if (receipt.acceptedOutcome === BOSS_QUESTION_OUTCOME)
+            return;
         summary.counts.interruptions++;
         if (frame.entry.summaryPolicy?.copyPasteGuardNames.includes(receipt.acceptedOutcome)) {
             summary.counts.copyPastes++;

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

@@ -554,6 +554,10 @@ const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID =
   'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
+// The fixed machine-syntax guard of a player's Boss-question suspension
+// (slc/link.md §Boss-reply suspension): the accepted outcome that parks on
+// Boss rather than sparing Boss a relay.
+const BOSS_QUESTION_OUTCOME = 'needsBossReply';
 const RESUMPTION_DUPLICATE_EFFECT_WARNING =
   'Warning: resumption may duplicate external effects attempted after the retained boundary; verify the current world before continuing.';
 
@@ -4293,6 +4297,11 @@ export function createPlaybookCaptainShell(
     const traceKey = `${frame.sessionId}:${trace.sequence}`;
     if (summary.acceptedOutcomeTraceKeys.has(traceKey)) return;
     summary.acceptedOutcomeTraceKeys.add(traceKey);
+    // CAPTAIN-19/20: a saved interruption is a player reply Boss did not
+    // have to relay. A Boss-question suspension is the one accepted outcome
+    // that parks on Boss instead, so it saves nothing and counts nothing —
+    // a turn that only parked must not claim it saved an interruption.
+    if (receipt.acceptedOutcome === BOSS_QUESTION_OUTCOME) return;
     summary.counts.interruptions++;
     if (
       frame.entry.summaryPolicy?.copyPasteGuardNames.includes(

package/reference/sdlc/decide.playbook/decide.playbook.js

@@ -19,7 +19,7 @@ import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
 import { createAcceptedOutcomeConsumer, } from '../../../src/accepted-outcome.js';
-import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, snapshotJsonValue, snapshotPlaybookSession, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
+import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
 import decideMachine from './decide.fsm.js';
 function snapshotDecideRuntimeOptions(value) {
     const captured = snapshotJsonValue(value, 'DECIDE runtime options');
@@ -429,15 +429,19 @@ function buildAdjudicatorPrompt(input, playerOutput, correction) {
     lines.push('"""');
     lines.push('');
     lines.push('Guards (choose exactly one; the descriptions are authoritative and must be applied as written):');
+    // The shared engine's renderer (slc/link.md §Captain adjudication): each
+    // arm's meaning verbatim, with its `Output shall include` clause — authored
+    // for the complete actor output — replaced by the reply contract the
+    // outcome authority gives the judge. Rendering the clause verbatim asked
+    // the judge for presentation-owned `coderProposal` or `question`, which the
+    // reconciler rejects, spending the single correction on a self-inflicted
+    // defect.
     for (const [guard, description] of Object.entries(input.result)) {
-        const semanticFields = Object.entries(outcomes[guard]?.fields ?? {})
-            .filter(([, authority]) => authority === 'semantic')
-            .map(([field]) => field);
-        lines.push(`- ${guard}: semantic fields: ${semanticFields.length === 0 ? '(none)' : semanticFields.join(', ')}; ${description}`);
+        lines.push(...renderGovernedOutcomeContract(guard, description, outcomes[guard]));
     }
     lines.push('');
-    lines.push('Reply with exactly the chosen `guard` and every semantic-owned field for that guard, and no other field.');
-    lines.push('Do not include presentation-, effect-, or runtime-owned fields; the runtime supplies those from authoritative evidence.');
+    lines.push("Pick exactly one declared `guard` and reply with exactly that outcome's reply shape above: `guard` plus its semantic-owned fields and nothing else.");
+    lines.push('A field listed as runtime-supplied is owned by presentation, effect, or runtime evidence; the runtime fills it itself, and a reply that includes one is structurally invalid.');
     if (correction !== undefined) {
         lines.push('');
         lines.push('Your first reply was structurally invalid:');

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

@@ -38,6 +38,7 @@ import {
   normalizePlaybookSnapshot,
   PlaybookSemanticCandidateStructureError,
   reconcilePlaybookSemanticEvidence,
+  renderGovernedOutcomeContract,
   snapshotJsonValue,
   snapshotPlaybookSession,
   validatePlayerResult,
@@ -660,22 +661,24 @@ function buildAdjudicatorPrompt(
   lines.push(
     'Guards (choose exactly one; the descriptions are authoritative and must be applied as written):',
   );
+  // The shared engine's renderer (slc/link.md §Captain adjudication): each
+  // arm's meaning verbatim, with its `Output shall include` clause — authored
+  // for the complete actor output — replaced by the reply contract the
+  // outcome authority gives the judge. Rendering the clause verbatim asked
+  // the judge for presentation-owned `coderProposal` or `question`, which the
+  // reconciler rejects, spending the single correction on a self-inflicted
+  // defect.
   for (const [guard, description] of Object.entries(input.result)) {
-    const semanticFields = Object.entries(outcomes[guard]?.fields ?? {})
-      .filter(([, authority]) => authority === 'semantic')
-      .map(([field]) => field);
     lines.push(
-      `- ${guard}: semantic fields: ${
-        semanticFields.length === 0 ? '(none)' : semanticFields.join(', ')
-      }; ${description}`,
+      ...renderGovernedOutcomeContract(guard, description, outcomes[guard]),
     );
   }
   lines.push('');
   lines.push(
-    'Reply with exactly the chosen `guard` and every semantic-owned field for that guard, and no other field.',
+    "Pick exactly one declared `guard` and reply with exactly that outcome's reply shape above: `guard` plus its semantic-owned fields and nothing else.",
   );
   lines.push(
-    'Do not include presentation-, effect-, or runtime-owned fields; the runtime supplies those from authoritative evidence.',
+    'A field listed as runtime-supplied is owned by presentation, effect, or runtime evidence; the runtime fills it itself, and a reply that includes one is structurally invalid.',
   );
   if (correction !== undefined) {
     lines.push('');

package/slc/gears2fsm.md

@@ -540,6 +540,10 @@ The artifact shall not bake them into machine input, options, or context; model
 Host-owned configuration such as an enabled-playbook catalog shall remain
 immutable machine input/context for the session. Boss events and actor outputs
 shall not carry, replace, append to, or otherwise overwrite that catalog.
+A placeholder whose value Source assigns to the host — for example the
+`<definition>` a phase host supplies to a compiled phase — is such host-owned
+configuration: a required machine `input` field carried into typed context and
+the acting actor's input, never a Boss-event or actor-output payload.
 Every machine with a dynamic call shall receive its own registered or authored
 playbook id as immutable machine input/context named `selfPlaybookId`, and its
 dynamic-call guard shall reject that target. The leaf-level `stateId` name is
@@ -776,6 +780,22 @@ compile as `{ response: string }`, not `{ response?: string }`; reaching the
 final state without a non-empty response shall be guarded out before the
 machine output is constructed.
 
+## Compiled execution
+
+This section governs compiled execution of this phase; the rules above remain the transformation's normative content for both execution paths.
+
+Where the phase host supplies `<definition>` as the exact bytes of the definition file the request names, when a transformation request names a `gears` Source (`.md`) and an `fsm` Target (`.ts`), Captain shall carry out the GEARS-to-FSM transformation as specified:
+
+> Follow the definition relayed between the `--- DEFINITION ---` and `--- END DEFINITION ---` lines exactly, adding no rules of your own: read the named Source and write the named Target as the definition specifies.
+> If the Source cannot be transformed under the definition, do not guess: leave the Target unwritten and report the concrete reason.
+> --- DEFINITION ---
+> \<definition\>
+> --- END DEFINITION ---
+
+Results:
+- `compiled`: Captain wrote the named Target as the relayed definition specifies.
+- `rejected`: Captain reported that the Source cannot be transformed under the relayed definition and left the Target unwritten.
+
 ## References
 
 [1]: https://stately.ai/docs/xstate 'XState Official Documentation'

package/slc/link.md

@@ -1079,6 +1079,15 @@ runtime-owned payload field; `guard` shall name exactly one outcome declared
 by both the live result map and `outcomeAuthority`; and every semantic-owned
 field shall satisfy the result map's required-field type before any actor
 output is delivered.
+The judge prompt shall render each governed outcome's description with its
+meaning verbatim and its `Output shall include` clause replaced by that reply
+contract — exactly `guard` plus the semantic-owned fields, each keeping its
+authored placeholder or guidance, with every presentation-, effect-, or
+runtime-owned field named as runtime-supplied to omit — so the judge is never asked for a
+field it does not own; the artifact's description text stays unchanged.
+The shared engine shall export that rendering as `renderGovernedOutcomeContract`
+on `@sublang/playbook/xstate-runtime`, and a bespoke linked runtime shall
+render its judge prompt through it rather than restate the contract.
 The reconciler shall construct the complete actor output rather than accept a
 cross-authority object from the judge: every presentation-owned payload field
 shall receive the canonical `finalText.trim()` value; every effect-owned
@@ -1170,7 +1179,9 @@ Two default adjudication strategies, in selection order:
   to decide only from the supplied actor output and declared outcomes, and
   require exactly one JSON object with no prose. The judge prompt shall not
   interpret the player's output, paraphrase it, or alter the FSM's `result`
-  text — it carries the description verbatim.
+  text — it carries the description verbatim, except that a governed
+  schema-3 outcome's `Output shall include` clause is rendered as the
+  authority-derived reply contract of §Captain adjudication.
 - **Marker-parse** (delegated-player alternative): a deterministic parser that
   scans the player output for a terminal control line such as
   `FSM-RESULT: { "guard": "...", ... }`. Useful when player adapters can
@@ -2451,6 +2462,22 @@ This spec is silent on the choice; the contract is the same in any location.
 
 New behavior in any of these areas requires a separate slc spec.
 
+## Compiled execution
+
+This section governs compiled execution of this phase; the rules above remain the transformation's normative content for both execution paths.
+
+Where the phase host supplies `<definition>` as the exact bytes of the definition file the request names, when a transformation request names an `fsm` Source (`.ts`) and a `playbook` Target (`.ts`), Captain shall carry out the FSM-to-runtime linking as specified:
+
+> Follow the definition relayed between the `--- DEFINITION ---` and `--- END DEFINITION ---` lines exactly, adding no rules of your own: read the named Source and write the named Target as the definition specifies.
+> If the Source cannot be transformed under the definition, do not guess: leave the Target unwritten and report the concrete reason.
+> --- DEFINITION ---
+> \<definition\>
+> --- END DEFINITION ---
+
+Results:
+- `compiled`: Captain wrote the named Target as the relayed definition specifies.
+- `rejected`: Captain reported that the Source cannot be transformed under the relayed definition and left the Target unwritten.
+
 ## References
 
 [1]: text2gears.md "First phase: text → GEARS spec items."

package/slc/text2gears.md

@@ -321,7 +321,9 @@ exact English form regardless of Source language.
 ## Transformation-spec sources
 
 A Source may itself be the normative specification of a transformation — e.g., a compiler phase definition, as when a meta pipeline compiles this file.
-Such a Source declares no roles and prompts none; its implied procedure is that Captain performs the specified transformation on request.
+Such a Source declares no roles and prompts none; Captain performs the specified transformation on request.
+Where such a Source carries a `## Compiled execution` section, text2gears shall compile it from that section alone: the section is the Source's complete behavior — its acting item, prompt, and `Results:` contract — and the remaining definition text is relayed content, not behaviors to transcribe, so the composition below applies only to a Source without that section.
+That section's blockquote is complete as authored: text2gears shall emit it verbatim and shall append no relay line to it — the `<definition>` placeholder is its only runtime value, and the undelivered-value rule above does not add `<boss-intent>` or any other placeholder to it.
 Compose Captain-acting spec items for it: when a transformation request names the specification's source and target, Captain shall carry out the transformation as specified.
 Prompts shall carry the specification's normative requirements as instructions to Captain — deduplicated, one point per line — without inventing roles, triggers, or requirements the specification does not state.
 
@@ -352,6 +354,22 @@ Partition items by every variable that determines prompt content — including a
 Drop disjunctive branches incompatible with the rest of an item's condition or prompt.
 Dead branches mislead readers and downstream phases.
 
+## Compiled execution
+
+This section governs compiled execution of this phase; the rules above remain the transformation's normative content for both execution paths.
+
+Where the phase host supplies `<definition>` as the exact bytes of the definition file the request names, when a transformation request names a `text` Source (`.md`) and a `gears` Target (`.md`), Captain shall carry out the text-to-GEARS transformation as specified:
+
+> Follow the definition relayed between the `--- DEFINITION ---` and `--- END DEFINITION ---` lines exactly, adding no rules of your own: read the named Source and write the named Target as the definition specifies.
+> If the Source cannot be transformed under the definition, do not guess: leave the Target unwritten and report the concrete reason.
+> --- DEFINITION ---
+> \<definition\>
+> --- END DEFINITION ---
+
+Results:
+- `compiled`: Captain wrote the named Target as the relayed definition specifies.
+- `rejected`: Captain reported that the Source cannot be transformed under the relayed definition and left the Target unwritten.
+
 ## References
 
 [1]: GEARS definition shipped by the installed `@sublang/spex` package: `@sublang/spex/scaffold/specs/meta.md` (English) and `@sublang/spex/scaffold/i18n/zh/specs/meta.md` (Chinese); canonical renditions [GEARS: AI-Ready Spec Syntax](https://sublang.ai/ref/gears-ai-ready-spec-syntax) (en) and [GEARS：面向 AI 的规约语法](https://sublang.ai/zh/ref/gears-ai-ready-spec-syntax) (zh)

package/src/xstate-playbook-runtime.d.ts

@@ -412,6 +412,21 @@ export declare function defaultComposeCaptainPrompt(input: PlaybookCaptainInput,
 export declare function defaultExtractRequiredFields(description: string): string[];
 /** Default delegated-player adjudicator prompt. */
 export declare function defaultBuildJudgePrompt(input: PlaybookPlayerInput, finalText: string): string;
+/**
+ * Judge-facing rendering of one governed outcome (DR-040 §1). The artifact's
+ * description is not altered: its meaning is carried through verbatim, while
+ * its `Output shall include` clause — authored for the complete actor output
+ * — is replaced by the reply contract `outcomeAuthority` gives the judge:
+ * exactly `guard` plus the outcome's semantic-owned fields, each keeping the
+ * placeholder or guidance the clause authors for it, and every
+ * presentation-, effect-, or runtime-owned field named as runtime-supplied
+ * so the judge omits it. Rendering the clause verbatim asked the judge for
+ * `question`, `planningResult`, or `evaluatedRevision`, which the reconciler
+ * rejects as a structural error, spending the single correction on a
+ * self-inflicted defect. Exported so a bespoke linked runtime (DECIDE's
+ * parallel machinery) renders the identical contract instead of restating it.
+ */
+export declare function renderGovernedOutcomeContract(guard: string, description: string, outcome: XStateGovernedOutcomeSpec | undefined): string[];
 export interface PlayerAdjudicationSpec {
     buildJudgePrompt?: (input: PlaybookPlayerInput, finalText: string) => string;
     extractRequiredFields?: (description: string) => string[];