@sublang/playbook 17.3.0 → 17.4.1

package/reference/sdlc/inspect.playbook/inspect.playbook.ts

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./inspect.fsm.js"; export: inspectMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { inspectMachine as machine } from "./inspect.fsm.js";
+import type { PlayerInput as SourcePlayerInput } from "./inspect.fsm.js";
+import {
+  createXStatePlaybookRuntime, snapshotJsonValue,
+  composePlayerContinuation, type XStatePromptIdentity,
+  type PlaybookPlayerInput,
+  type XStatePlaybookRuntimeConstruction,
+  type XStatePlaybookRuntimeFactory,
+  type XStatePlaybookRuntimeSpecV3,
+} from '@sublang/playbook/xstate-runtime';
+export type {
+  PlayerResult,
+  PlayerCallOptions,
+  PlayerSessionStore,
+  CaptainResult,
+  CaptainCallOptions,
+  JsonValue,
+  NormalizedError,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
+  PlaybookStateValue,
+  PlaybookState,
+  PlaybookPendingCall,
+  PlaybookRunResult,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
+  PlaybookRuntimeSnapshot,
+  PlaybookSession,
+  PlaybookPorts,
+  PlaybookTraceEvent,
+  PlaybookTraceType,
+  PlaybookControlReceipt,
+  PlaybookControlView,
+} from '@sublang/playbook/runtime';
+
+export interface PlaybookRuntimeOptions {
+  readonly "discussionContext"?: string;
+}
+export type PlaybookHostCapabilities = XStatePlaybookRuntimeConstruction<
+  PlaybookRuntimeOptions, { readonly authority: object }
+>['hostCapabilities'];
+
+const OPTION_SCHEMA = {
+  "discussionContext": {
+    "type": "string",
+    "required": false
+  }
+} as const;
+const INPUT_MAPPING = {
+  "discussionContext": "discussionContext"
+} as const;
+const RESUMABLE_STATE_IDS: ReadonlySet<string> = new Set([
+  "inspecting"
+]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
+  "unavailable"
+]);
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  "report"
+]);
+export function validateOptions(value: unknown): PlaybookRuntimeOptions {
+  const captured = snapshotJsonValue(value === undefined ? {} : value, "INSPECT runtime options");
+  if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
+    throw new TypeError("INSPECT runtime options must be an object");
+  }
+  const fields = captured as Readonly<Record<string, unknown>>;
+  for (const key of Object.keys(captured)) {
+    if (!Object.hasOwn(OPTION_SCHEMA, key)) throw new TypeError("INSPECT runtime options." + key + ' is not declared');
+  }
+  for (const [key, schema] of Object.entries(OPTION_SCHEMA) as [string, { type: string; required: boolean }][]) {
+    if (!Object.hasOwn(captured, key)) {
+      if (schema.required) throw new TypeError("INSPECT runtime options." + key + ' is required');
+    } else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+      throw new TypeError("INSPECT runtime options." + key + ' must be a ' + schema.type);
+    }
+  }
+  return captured as unknown as PlaybookRuntimeOptions;
+}
+function renderPlayerPrompt(input: SourcePlayerInput, promptIdentity: XStatePromptIdentity, resuming = false): string {
+  const fields = input as unknown as Readonly<Record<string, unknown>>;
+  const mapping: Readonly<Record<string, string>> = {};
+  const identities: Readonly<Record<string, string>> = {};
+  const omitted = new Set<string>(["> Discussion context: <discussion-context>"]);
+  const fieldFor = (token: string): string => Object.hasOwn(mapping, token) ? mapping[token]! : (token === '#' ? 'irNumber' : token.replace(/-([A-Za-z0-9_$])/g, (_match: string, next: string) => next.toUpperCase()));
+  const parts = input.prompt.split(/(\r?\n)/);
+  let body = '';
+  for (let index = 0; index < parts.length; index += 2) {
+    const line = parts[index]!;
+    if (omitted.has(line)) {
+      const token = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>$/.exec(line)![1]!;
+      if (fields[fieldFor(token)] === '') continue;
+    }
+    body += line.replace(/<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g, (match: string, token: string): string => {
+      const value = Object.hasOwn(identities, token) ? promptIdentity(identities[token]!) : fields[fieldFor(token)];
+      if (typeof value !== 'string') return match;
+      return line.startsWith('> ') ? value.replace(/\r?\n/g, (ending: string) => ending + '> ') : value;
+    }) + (parts[index + 1] ?? '');
+  }
+  return composePlayerContinuation(input, body, resuming);
+}
+const composePlayerPrompt = (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean): string =>
+  renderPlayerPrompt(input as SourcePlayerInput, promptIdentity, resuming);
+const runtimeSpec = {
+  composePlayerPrompt,
+  ...{
+  "label": "INSPECT",
+  "compat": {
+    "artifactSchema": 3,
+    "runtimeAbi": 1
+  },
+  "entryEvent": {
+    "type": "START",
+    "textField": "inspectionRequest",
+    "contextField": "inspectionRequest"
+  },
+  "bossEvents": [],
+  "roleStates": {
+    "inspecting": {
+      "role": "inspector",
+      "label": "Inspector investigates the requested material and gives an evidence-based explanation."
+    }
+  },
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "inspecting": {
+        "completed": {
+          "fields": {
+            "status": "semantic",
+            "report": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        },
+        "unavailable": {
+          "fields": {
+            "status": "semantic",
+            "report": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
+      }
+    }
+  },
+  "placeholderFields": {},
+  "transitionEventFields": [
+    "inspectionRequest",
+    "discussionContext",
+    "answer",
+    "questionId"
+  ],
+  "controlContextFields": [
+    "inspectionRequest"
+  ]
+},
+  snapshotOptions: validateOptions,
+  machineInput: (options: PlaybookRuntimeOptions) => Object.fromEntries(
+    Object.entries(INPUT_MAPPING).filter(([, key]) => options[key as keyof PlaybookRuntimeOptions] !== undefined)
+      .map(([field, key]) => [field, options[key as keyof PlaybookRuntimeOptions]]),
+  ),
+  verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+  resumableStateIds: RESUMABLE_STATE_IDS,
+  unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
+} satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
+
+export const _internal = {
+  composePlayerPrompt,
+  RESUMABLE_STATE_IDS,
+  UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
+};
+const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
+  XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
+> = createXStatePlaybookRuntime<PlaybookRuntimeOptions, PlaybookHostCapabilities>(machine, runtimeSpec);
+export default createPlaybookRuntime;

package/reference/sdlc/inspect.playbook/inspect.registry.d.ts

@@ -0,0 +1,41 @@
+import { type PlaybookRuntimeOptions, type PlaybookHostCapabilities, type PlaybookRuntime } from './inspect.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
+export interface PlaybookSummaryPolicy {
+    stateCountLabels: Readonly<Record<string, string>>;
+    copyPasteGuardNames: readonly string[];
+    savedCountsLine(counts: {
+        interruptions: number;
+        copyPastes: number;
+    }, rounds: number): string;
+}
+export type InspectOptions = PlaybookRuntimeOptions;
+export interface InspectPlaybookRegistryEntry {
+    id: 'inspect';
+    command: 'inspect';
+    intent: string;
+    artifactSchema: 3;
+    runtimeProfile: {
+        readonly kind: 'shared-factory';
+        readonly compat: {
+            readonly artifactSchema: 3;
+            readonly runtimeAbi: number;
+        };
+    };
+    requiredRoleIds: readonly ['inspector'];
+    concurrentRoleSets: readonly [];
+    summaryPolicy: PlaybookSummaryPolicy;
+    validateOptions(optionSlice: unknown): InspectOptions;
+    createRuntime(options: InspectOptions, hostCapabilities: PlaybookHostConstructionCapabilities & PlaybookHostCapabilities): PlaybookRuntime;
+}
+export declare const inspectStateCountLabels: {
+    readonly inspecting: "inspection round";
+};
+export declare const inspectCopyPasteGuardNames: readonly ["completed"];
+export declare function inspectSavedCountsLine(counts: {
+    interruptions: number;
+    copyPastes: number;
+}, rounds: number): string;
+export declare const inspectSummaryPolicy: PlaybookSummaryPolicy;
+export declare function validateInspectOptions(optionSlice: unknown): InspectOptions;
+export declare const inspectPlaybookRegistryEntry: InspectPlaybookRegistryEntry;
+export default inspectPlaybookRegistryEntry;

package/reference/sdlc/inspect.playbook/inspect.registry.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime, { validateOptions, } from './inspect.playbook.js';
+// INSPECT counts its delegated evidence-gathering calls as inspection rounds.
+export const inspectStateCountLabels = {
+    inspecting: 'inspection round',
+};
+export const inspectCopyPasteGuardNames = ['completed'];
+function countNoun(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+export function inspectSavedCountsLine(counts, rounds) {
+    return [
+        'Saved you',
+        countNoun(counts.interruptions, 'interruption'),
+        'and',
+        countNoun(counts.copyPastes, 'copy-paste'),
+        'across',
+        countNoun(rounds, 'round'),
+        'of inspection.',
+    ].join(' ');
+}
+export const inspectSummaryPolicy = {
+    stateCountLabels: inspectStateCountLabels,
+    copyPasteGuardNames: inspectCopyPasteGuardNames,
+    savedCountsLine: inspectSavedCountsLine,
+};
+export function validateInspectOptions(optionSlice) {
+    return validateOptions(optionSlice);
+}
+export const inspectPlaybookRegistryEntry = {
+    id: 'inspect',
+    command: 'inspect',
+    intent: 'inspect supplied material or a running web interface and explain observed evidence without changing the repository',
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'shared-factory',
+        compat: createPlaybookRuntime.compat,
+    }),
+    requiredRoleIds: ['inspector'],
+    concurrentRoleSets: [],
+    summaryPolicy: inspectSummaryPolicy,
+    validateOptions: validateInspectOptions,
+    createRuntime(options, hostCapabilities) {
+        return createPlaybookRuntime({
+            configuredOptions: options,
+            hostCapabilities,
+        });
+    },
+};
+export default inspectPlaybookRegistryEntry;

package/reference/sdlc/inspect.playbook/inspect.registry.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import createPlaybookRuntime, {
+  validateOptions,
+  type PlaybookRuntimeOptions,
+  type PlaybookHostCapabilities,
+  type PlaybookRuntime,
+} from './inspect.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
+
+export interface PlaybookSummaryPolicy {
+  stateCountLabels: Readonly<Record<string, string>>;
+  copyPasteGuardNames: readonly string[];
+  savedCountsLine(
+    counts: { interruptions: number; copyPastes: number },
+    rounds: number,
+  ): string;
+}
+
+export type InspectOptions = PlaybookRuntimeOptions;
+
+export interface InspectPlaybookRegistryEntry {
+  id: 'inspect';
+  command: 'inspect';
+  intent: string;
+  artifactSchema: 3;
+  runtimeProfile: {
+    readonly kind: 'shared-factory';
+    readonly compat: {
+      readonly artifactSchema: 3;
+      readonly runtimeAbi: number;
+    };
+  };
+  requiredRoleIds: readonly ['inspector'];
+  concurrentRoleSets: readonly [];
+  summaryPolicy: PlaybookSummaryPolicy;
+  validateOptions(optionSlice: unknown): InspectOptions;
+  // The linked module types live authority as opaque (link-materialization);
+  // the Captain entry binds its own construction capabilities here.
+  createRuntime(
+    options: InspectOptions,
+    hostCapabilities: PlaybookHostConstructionCapabilities &
+      PlaybookHostCapabilities,
+  ): PlaybookRuntime;
+}
+
+// INSPECT counts its delegated evidence-gathering calls as inspection rounds.
+export const inspectStateCountLabels = {
+  inspecting: 'inspection round',
+} as const;
+
+export const inspectCopyPasteGuardNames = ['completed'] as const;
+
+function countNoun(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+export function inspectSavedCountsLine(
+  counts: { interruptions: number; copyPastes: number },
+  rounds: number,
+): string {
+  return [
+    'Saved you',
+    countNoun(counts.interruptions, 'interruption'),
+    'and',
+    countNoun(counts.copyPastes, 'copy-paste'),
+    'across',
+    countNoun(rounds, 'round'),
+    'of inspection.',
+  ].join(' ');
+}
+
+export const inspectSummaryPolicy: PlaybookSummaryPolicy = {
+  stateCountLabels: inspectStateCountLabels,
+  copyPasteGuardNames: inspectCopyPasteGuardNames,
+  savedCountsLine: inspectSavedCountsLine,
+};
+
+export function validateInspectOptions(optionSlice: unknown): InspectOptions {
+  return validateOptions(optionSlice);
+}
+
+export const inspectPlaybookRegistryEntry: InspectPlaybookRegistryEntry = {
+  id: 'inspect',
+  command: 'inspect',
+  intent:
+    'inspect supplied material or a running web interface and explain observed evidence without changing the repository',
+  artifactSchema: 3,
+  runtimeProfile: Object.freeze({
+    kind: 'shared-factory',
+    compat: createPlaybookRuntime.compat,
+  }),
+  requiredRoleIds: ['inspector'],
+  concurrentRoleSets: [],
+  summaryPolicy: inspectSummaryPolicy,
+  validateOptions: validateInspectOptions,
+  createRuntime(options, hostCapabilities) {
+    return createPlaybookRuntime({
+      configuredOptions: options,
+      hostCapabilities,
+    });
+  },
+};
+
+export default inspectPlaybookRegistryEntry;

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/slc/workflow-contracts.json

@@ -359,6 +359,47 @@
           }
         ]
       }
+    },
+    "inspect": {
+      "callInput": "text",
+      "output": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "complete"
+              },
+              "report": {
+                "type": "string",
+                "description": "Inspector's complete explanation; presentation evidence, not independent effect authority."
+              }
+            },
+            "required": [
+              "status",
+              "report"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "unavailable"
+              },
+              "report": {
+                "type": "string",
+                "description": "Inspector's complete explanation; presentation evidence, not independent effect authority."
+              }
+            },
+            "required": [
+              "status",
+              "report"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      }
     }
   },
   "literalTargetBindings": {
@@ -366,6 +407,7 @@
     "decide": "decide",
     "code": "code",
     "branch": "branch",
-    "pr": "pr"
+    "pr": "pr",
+    "inspect": "inspect"
   }
 }

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:`,