@sublang/playbook 17.4.0 → 17.5.0

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

@@ -446,12 +446,27 @@ export interface PlaybookCaptainShell extends Captain {
 // normalized `captain.options.playbooks.<id>` role map.
 interface Enablement {
   entry: PlaybookCaptainRegistryEntry;
+  readonly configuredFrom: string;
   artifactSchema: 3;
   command: string;
   options: JsonValue;
   roleBindings: ReadonlyMap<string, EffectivePlayerBinding>;
 }
 
+function missingPackagedReview(
+  enablementById: ReadonlyMap<string, Enablement>,
+  playbookId: string,
+): string | undefined {
+  const selected = enablementById.get(playbookId);
+  if (
+    selected === undefined ||
+    enablementById.has('review') ||
+    !['code', 'decide'].includes(playbookId) ||
+    selected.configuredFrom !== `@sublang/playbook/${playbookId}/registry`
+  ) return undefined;
+  return `/${selected.command} requires enabled playbook "review"; enable REVIEW before starting this packaged workflow`;
+}
+
 function createRuntimeForEnablement(
   enablement: Enablement,
   hostCapabilitiesById: ReadonlyMap<
@@ -4181,6 +4196,7 @@ async function buildEnablements(
     hostCapabilitiesById.set(entry.id, hostCapability);
     enablementById.set(entry.id, {
       entry,
+      configuredFrom: from,
       artifactSchema,
       command,
       options: validatedOptions,
@@ -6142,13 +6158,16 @@ export function createPlaybookCaptainShell(
       enablement,
       hostCapabilitiesById,
     );
+    // A nested child inherits only its parent's selection, never the turn's
+    // unselected references; only a root reads the turn's selection.
+    const inherited = parent ? parent.frame.attachments : (activeTurn?.selectedAttachments ?? activeTurn?.attachments);
     return {
       entry,
       enablement,
       runtime,
       sessionId,
       rootSessionId: parent?.frame.rootSessionId ?? sessionId,
-      ...((parent?.frame.attachments ?? activeTurn?.selectedAttachments ?? activeTurn?.attachments)?.length ? { attachments: [...(parent?.frame.attachments ?? activeTurn?.selectedAttachments ?? activeTurn!.attachments)] } : {}),
+      ...(inherited?.length ? { attachments: [...inherited] } : {}),
       depth: parent ? parent.frame.depth + 1 : 0,
       playerBindings,
       ...(parent ? { parent } : {}),
@@ -6486,7 +6505,6 @@ export function createPlaybookCaptainShell(
       } finally {
         if (leafFrame() === frame) {
           frames.pop();
-          if (!frame.parent) pendingAttachments = [];
           if (frame.parent) {
             pendingChildParents.delete(frame.parent.frame);
           }
@@ -6930,6 +6948,23 @@ export function createPlaybookCaptainShell(
       return;
     }
     assertRetainableResult(frame, result);
+    // A deferred checkpoint refusal changes the runtime's control overlay
+    // without publishing an FSM transition. Refresh its derived question
+    // mirror from an exact safe snapshot before reporting or saving the stop.
+    if (leafFrame() === frame && !frame.disposing &&
+        retainedEffectReconciliation === undefined) {
+      try {
+        const exported = frame.runtime.exportSnapshot?.();
+        if (exported !== undefined) {
+          const snapshot = assertPlaybookRuntimeSnapshot(exported, frame.entry.id);
+          if (isDeepStrictEqual(snapshot.state, result.state) &&
+              isDeepStrictEqual(snapshot.effectLedger, currentEffectLedger())) {
+            pendingBossQuestions = snapshot.pendingBossQuestions.length === 0 && pendingBossQuestions === undefined
+              ? undefined : mirroredBossQuestions(snapshot.pendingBossQuestions);
+          }
+        }
+      } catch { /* An inconsistent runtime must still fail exact capture. */ }
+    }
     if (result.outcome === 'aborted' && runFailureFacts) {
       runFailureFacts.push(
         `${frameLabel(frame)} was aborted before its outcome could be confirmed; it was not repeated automatically.`,
@@ -7011,6 +7046,9 @@ export function createPlaybookCaptainShell(
       );
     }
 
+    const reviewRefusal = missingPackagedReview(enablementById, entry.id);
+    if (reviewRefusal !== undefined) throw new Error(reviewRefusal);
+
     pendingChildParents.add(parent);
     let child: EngagementFrame;
     try {
@@ -9004,7 +9042,13 @@ export function createPlaybookCaptainShell(
       // its decision-call prose crosses the presentation boundary. Acting
       // selections freeze after their work and before reporting begins.
       if (selection.action === 'respond') freezeControllerEvidence();
-      let settlement = await executeSelection(selection, signal, automaticRecovery);
+      signal.throwIfAborted();
+      const reviewRefusal = selection.action === 'start' || selection.action === 'switch'
+        ? missingPackagedReview(enablementById, selection.playbookId)
+        : undefined;
+      let settlement = reviewRefusal === undefined
+        ? await executeSelection(selection, signal, automaticRecovery)
+        : await rejectSelection(selection, reviewRefusal);
       // One controller action can include bounded prerequisite recovery.
       // Neither the model nor a retry manufactures an unadvertised transition.
       if (turn && abortPreparation && settlement.status !== 'rejected' && !['respond', 'dismiss', 'recover'].includes(selection.action)) {
@@ -9548,6 +9592,9 @@ export function createPlaybookCaptainShell(
       const selected = selection.attachmentIds === undefined ? turn.attachments : selection.attachmentIds.map((id) => available.get(id as SessionAssetRef['assetId'])!);
       const nextAttachments = mergeAttachments(leaf.attachments ?? [], selected);
       if (nextAttachments.length) leaf.attachments = nextAttachments;
+      // Delivered references now belong to the leaf; the rest stay pending.
+      const delivered = new Set(selected.map((reference) => reference.assetId));
+      pendingAttachments = pendingAttachments.filter((reference) => !delivered.has(reference.assetId));
       // CAPTAIN-8: delivery carries text only, and the shell is authoritative
       // for that text — any text carried on the selection is ignored.
       turn.settled = true;

package/reference/sdlc/code.playbook/session-assets.js

@@ -102,9 +102,11 @@ export function createAssetStore(options) {
     try {
       const opened = await directoryHandle.stat();
       if (opened.dev !== before.dev || opened.ino !== before.ino) throw new Error('asset owner directory changed during preparation');
-      if (process.platform !== 'win32') await directoryHandle.chmod(0o700);
+      // fchmod always moves ctime, which verified readers pin: change only modes that differ.
+      if (process.platform !== 'win32' && (opened.mode & 0o777) !== 0o700) await directoryHandle.chmod(0o700);
       for (const name of await readdir(directory)) {
-        if (!/^(?:[0-9a-f]{64}(?:\.json)?|\.import-[0-9a-f-]+\.tmp)$/.test(name)) throw new Error('unknown asset owner entry');
+        // Foreign names (Finder or editor files) are neither assets nor ours to modify.
+        if (!/^(?:[0-9a-f]{64}(?:\.json)?|\.import-[0-9a-f-]+\.tmp)$/.test(name)) continue;
         const path = join(directory, name);
         const stat = await lstat(path);
         if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error('asset entry must be a single-link regular file');
@@ -114,7 +116,7 @@ export function createAssetStore(options) {
         try {
           const pinned = await handle.stat();
           if (!sameFile(stat, pinned)) throw new Error('asset entry changed during preparation');
-          if (process.platform !== 'win32') await handle.chmod(0o600);
+          if (process.platform !== 'win32' && (pinned.mode & 0o777) !== 0o600) await handle.chmod(0o600);
           assertFile(await handle.stat(), 'asset entry');
           const final = await lstat(path);
           if (final.dev !== pinned.dev || final.ino !== pinned.ino || final.nlink !== 1) throw new Error('asset entry changed during preparation');
@@ -286,9 +288,8 @@ export function createAssetStore(options) {
       const entries = await readdir(directory);
       const result = [];
       for (const name of entries.sort()) {
-        if (/^\.import-[0-9a-f-]+\.tmp$/.test(name)) continue;
-        if (/^[0-9a-f]{64}\.json$/.test(name)) continue;
-        if (!/^[0-9a-f]{64}$/.test(name)) throw new Error(`unknown asset owner entry ${JSON.stringify(basename(name))}`);
+        // Descriptors, import temporaries and foreign files are not enumerated.
+        if (!/^[0-9a-f]{64}$/.test(name)) continue;
         if (!entries.includes(`${name}.json`)) { const orphan = await checkedOpen(name, 'unreferenced asset content'); await orphan.handle.close(); continue; }
         const reader = await openAsset(`sha256:${name}`); await reader.close();
         result.push(Object.freeze({ assetId: reader.reference.assetId, path: name, metadataPath: `${name}.json`, byteLength: reader.reference.byteLength }));

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

@@ -43,8 +43,15 @@ export declare function installRetainedGenerationsForLaunch(options: {
 export declare function executionConfigFromPlan(plan: any): SessionExecutionProjection;
 export declare function validateFrozenExecutionConfig(structural: SessionStructuralProjection, execution: SessionExecutionProjection, dependencies: { loadModule: (specifier: string) => Promise<any>; prepareRegistryModule?: (request: {id: string; from: string; authoredFrom: string}) => Promise<string | void> }): Promise<SessionExecutionProjection>;
 export declare function driveHeadlessCaptainTurn(options: any): Promise<any>;
-export declare function normalizeLaunchPlan(top: any, options?: any): Promise<any>;
-export declare function loadLaunchPlan(options: any): Promise<any>;
+/** Playbook id to registry module specifier, supplied at launch ahead of `playbooks.<id>.from` (DR-083). */
+export type PlaybookModuleLocations = Readonly<Record<string, string>>;
+export interface LaunchPlanModuleOptions {
+  /** Absolute paths become file URLs; file URLs and package specifiers are kept; relative paths are refused. */
+  readonly modules?: PlaybookModuleLocations;
+  readonly [key: string]: any;
+}
+export declare function normalizeLaunchPlan(top: any, options?: LaunchPlanModuleOptions): Promise<any>;
+export declare function loadLaunchPlan(options: LaunchPlanModuleOptions): Promise<any>;
 export declare function composeGenericConfig(top: any, loadModule: (specifier: string) => Promise<any>, configPath?: string): Promise<any>;
 export declare function projectTmuxConfig(plan: any): any;
 export declare function resolveLaunchSessionsDir(options: any): string;

package/slc/gears2fsm.md

@@ -602,6 +602,9 @@ safety beyond the guarded direct transition.
 ## Context and prompts
 
 Context fields used to drive guards or compose prompts shall be **typed and named**.
+Where Source owns array-valued retained discussion whose initial state is no history, initialize that context field to `[]` and reset it to `[]` only at its Source lifecycle boundaries.
+Carry its declared array shape through ordinary and continuation `invoke.input`; do not leave the empty structural history absent so a prompt-contract probe mistakes it for a scalar.
+This empty history is not a default caller intent, prerequisite report, domain evidence, approval, or prior-stage result; those remain unavailable until actually established.
 The compiler shall not branch on untyped properties of `lastResult`; persistent routing decisions belong in typed context fields. (`lastResult` is for inspection only.)
 Where Source declares a finite ordered plan, represent it as a typed readonly
 JSON-safe array and validate that shape on the actor-output transition; an
@@ -835,8 +838,8 @@ Only
 The canonical storage paths are `context.pendingBossQuestion` and `context.bossReply` for the scalar form, or `context.pendingBossQuestions[stateId]` and `context.bossReplies[stateId]` for the keyed form.
 A private wrapper such as `context.continuation` shall not replace these fields directly on machine context.
 
-A machine with at most one active Captain or player task may use the scalar
-form:
+A machine that declares no root parallel group shall use the scalar form;
+keyed storage alone is not visible to the flat shared factory:
 
 - An `awaitBossReply` state with stable `id: 'awaitBossReply'`, tag
   `playbook.parked`, and description
@@ -847,7 +850,9 @@ form:
 - `resumableStates(ids)`, `setPendingBossQuestion`, and
   `clearBossReplyContext` helpers with the existing single-question behavior.
 
-A machine with parallel delegated-player tasks shall use the keyed form:
+A machine that declares a root parallel group shall use the keyed form
+throughout the machine, including any sequential working leaves and their
+root reply wait:
 
 - One local waiting leaf per branch, tagged `playbook.parked`.
 - A `BOSS_REPLY` event carrying `{ questionId: string; answer: string }`.
@@ -884,6 +889,15 @@ pending question and reply selected for that working leaf as singular
 `pendingBossQuestion` and `bossReply` fields, regardless of the scalar or keyed
 context representation, so prompt composition has one stable contract.
 When Source requires earlier discussion or constraints on a later invocation, the compiler shall persist that source-owned history in serializable machine context before replacing or clearing the pending Q/A fields.
+Where that Source-owned value is the complete received Boss reply, retain it
+directly from the current working leaf's canonical reply context at the
+Source-authored accepted-outcome boundary, before clearing that leaf's Q/A.
+Preserve its exact string, including surrounding whitespace, CRLF/LF separators,
+blank lines and trailing separators; do not require a model-produced echo or
+replace it with one. Acceptance remains the acting agent's semantic judgment,
+guarded by the current matching question's state, Source-item and asker binding
+and actual receipt of a nonempty reply. Neither stale question/reply context
+nor a different actor-supplied value establishes that binding or approval.
 The later `invoke.input` shall relay that persisted context on both resumed and fresh calls that Source says need it, preserving Source-owned relevance and format without imposing all-history semantics on sources that do not require it.
 Shared Boss-reply continuation carries only the latest Q/A pair, and a backend continuation token is not durable Source history.
 When both fields are present, the linked runtime shall compose the continuation preamble and labelled Q&A blocks per [link.md "Player prompt composition"](link.md#player-prompt-composition).

package/slc/text2gears.md

@@ -189,6 +189,13 @@ between the Source and the catalog: leave the Target unwritten and report it
 as an incompatible compiler input rather than rename or invent.
 A Source outside those ids is named from its own words as above.
 
+A value Source assigns to the received Boss input or reply is already runtime
+input, not a value the acting agent produces. Where Source requires that
+complete value retained for later calls, preserve the exact input's retention
+and the Source's acceptance condition in non-acting GEARS prose; do not declare
+a Judge-extracted echo property for it. The semantic approval or refusal stays
+in the acting result contract.
+
 A produced value consumed later shall have a declared producer: where any
 later item's blockquote reads a value through a `<placeholder>`, the item
 whose behavior produces that value shall declare the `Results:` contract

package/src/xstate-playbook-runtime.js

@@ -866,12 +866,16 @@ export function defaultExtractRequiredFields(description) {
         fields.push(m[1]);
     return fields;
 }
+const CURRENT_CALL_ADJUDICATION_GUIDANCE = "Classify the invoked role's current call by the result it reports at call end, using the full output and declared outcome meanings. " +
+    'An earlier interim question is not outstanding when later prose explicitly resolves or supersedes it for this call; a prerequisite only for a later workflow stage does not block an affirmatively completed current call. ' +
+    'A genuinely unanswered question needed to finish the current call remains outstanding. A commit statement alone does not establish semantic completion; do not force contradictory or insufficient evidence into a completed outcome.';
 /** Default delegated-player adjudicator prompt. */
 export function defaultBuildJudgePrompt(input, finalText) {
     const lines = [];
     lines.push('This is hidden control work. Do not call tools, inspect files, or ' +
         'seek external evidence. Decide only from the supplied player output ' +
         'and outcome descriptions. Reply with exactly one JSON object and no prose.');
+    lines.push(CURRENT_CALL_ADJUDICATION_GUIDANCE);
     lines.push('');
     lines.push(`The ${input.role} role just produced this output:`);
     lines.push('');
@@ -957,6 +961,7 @@ function buildGovernedJudgePrompt(input, finalText, outcomes, correction) {
     const lines = [
         'This is hidden control work. Do not call tools, inspect files, or seek external evidence.',
         'Decide only from the supplied player output and declared outcomes.',
+        CURRENT_CALL_ADJUDICATION_GUIDANCE,
         'Reply with exactly one JSON object and no prose.',
         '',
         `The ${input.role} role just produced this output:`,

package/src/xstate-playbook-runtime.ts

@@ -1706,6 +1706,11 @@ export function defaultExtractRequiredFields(description: string): string[] {
   return fields;
 }
 
+const CURRENT_CALL_ADJUDICATION_GUIDANCE =
+  "Classify the invoked role's current call by the result it reports at call end, using the full output and declared outcome meanings. " +
+  'An earlier interim question is not outstanding when later prose explicitly resolves or supersedes it for this call; a prerequisite only for a later workflow stage does not block an affirmatively completed current call. ' +
+  'A genuinely unanswered question needed to finish the current call remains outstanding. A commit statement alone does not establish semantic completion; do not force contradictory or insufficient evidence into a completed outcome.';
+
 /** Default delegated-player adjudicator prompt. */
 export function defaultBuildJudgePrompt(
   input: PlaybookPlayerInput,
@@ -1717,6 +1722,7 @@ export function defaultBuildJudgePrompt(
       'seek external evidence. Decide only from the supplied player output ' +
       'and outcome descriptions. Reply with exactly one JSON object and no prose.',
   );
+  lines.push(CURRENT_CALL_ADJUDICATION_GUIDANCE);
   lines.push('');
   lines.push(`The ${input.role} role just produced this output:`);
   lines.push('');
@@ -1822,6 +1828,7 @@ function buildGovernedJudgePrompt(
   const lines = [
     'This is hidden control work. Do not call tools, inspect files, or seek external evidence.',
     'Decide only from the supplied player output and declared outcomes.',
+    CURRENT_CALL_ADJUDICATION_GUIDANCE,
     'Reply with exactly one JSON object and no prose.',
     '',
     `The ${input.role} role just produced this output:`,