@sublang/playbook 15.0.0 → 16.0.0

package/README.md

@@ -107,7 +107,7 @@ SLC's `playbook` pipeline has three phases:
 2. **GEARS → FSM** ([slc/gears2fsm.md](slc/gears2fsm.md)) — maps each item to an XState state that invokes the Captain, a player, another playbook, or a local script.
 3. **FSM → runtime** ([slc/link.md](slc/link.md)) — links the machine to a host-independent interface for user input, agent calls, status, and telemetry.
 
-The default [optimization pass](slc/optimize.md) replaces eligible mechanical steps with local shell scripts; `--no-optimize` skips it.
+The default passes run between the first two phases: the [optimization pass](slc/optimize.md) replaces eligible mechanical steps with local shell scripts, and the [prompt-prefix pass](slc/prefix.md) moves each prompt's relayed runtime values after its instructions so repeated runs share a cacheable prompt prefix; `--no-optimize` skips both.
 Inspect the complete [Captain](reference/sdlc/captain.md), [CODE](reference/sdlc/code.md), [REVIEW](reference/sdlc/review.md), and [DECIDE](reference/sdlc/decide.md) examples.
 
 ## Contributing

package/docs/embedding.md

@@ -38,7 +38,7 @@ tree, which pnpm's strict linking will not allow.
 
 ```ts
 import createPlaybookRuntime, {
-  type ReviewPlaybookHostCapabilities,
+  type PlaybookHostCapabilities,
 } from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
@@ -156,7 +156,7 @@ const playbookSessionId = randomUUID();
 // machine input, or a persisted snapshot. A host outside the CLI constructs
 // the repository and effect-ledger members through the facade described in
 // "Constructing worktree host capabilities" below.
-declare const hostCapabilities: ReviewPlaybookHostCapabilities;
+declare const hostCapabilities: PlaybookHostCapabilities;
 
 const runtime = createPlaybookRuntime({
   configuredOptions: {},
@@ -445,21 +445,23 @@ const url = import.meta.resolve('@sublang/playbook/slc/link.md');
 const link = await readFile(fileURLToPath(url), 'utf8');
 ```
 
-The four specs are [`slc/text2gears.md`](../slc/text2gears.md),
+The five specs are [`slc/text2gears.md`](../slc/text2gears.md),
 [`slc/gears2fsm.md`](../slc/gears2fsm.md),
 [`slc/link.md`](../slc/link.md) — the FSM-to-runtime contract that
-`@sublang/playbook/runtime` projects into TypeScript — and
-[`slc/optimize.md`](../slc/optimize.md).
+`@sublang/playbook/runtime` projects into TypeScript —
+[`slc/optimize.md`](../slc/optimize.md), and
+[`slc/prefix.md`](../slc/prefix.md).
 
-Five supporting assets use the same resolution mechanism:
+Six supporting assets use the same resolution mechanism:
 
 | Asset | Purpose |
 | --- | --- |
 | [`slc/workflow-contracts.json`](../slc/workflow-contracts.json) | Public output schemas and default literal target bindings for the builtin REVIEW, DECIDE, CODE, BRANCH, and PR workflows; compilers and embedders can read them without importing workflow implementations. |
 | [`slc/materialize-link.mjs`](../slc/materialize-link.mjs) | Optional CLI that emits a thin linked module from a supported FSM and JSON descriptor; see the profiles and invocation in `slc/link.md`. |
 | [`slc/scaffold-fsm.mjs`](../slc/scaffold-fsm.mjs) | Optional CLI that initializes an incomplete typed FSM from supported GEARS source. |
+| [`slc/prefix-prompts.mjs`](../slc/prefix-prompts.mjs) | CLI that performs the prompt-prefix pass's rewrite of a GEARS package exactly; see the invocation in `slc/prefix.md`. |
 | [`slc/experiments/fsm-scaffold-guidance.md`](../slc/experiments/fsm-scaffold-guidance.md) | Opt-in compiler guidance for the initializer, outside ordinary phase discovery. |
-| [`slc/slc.pin-inputs.json`](../slc/slc.pin-inputs.json) | SLC semantic-input closures for `gears2fsm` and `link`, including the workflow catalog and, for `link`, the materializer. Other phases use SLC's inline-input discovery. |
+| [`slc/slc.pin-inputs.json`](../slc/slc.pin-inputs.json) | SLC semantic-input closures for `gears2fsm`, `prefix`, and `link`, including the workflow catalog, the prefix tool, and, for `link`, the materializer. Other phases use SLC's inline-input discovery. |
 
 For example, resolve `@sublang/playbook/slc/workflow-contracts.json`, read it
 with `readFile`, and parse the result as JSON to inspect the published workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "15.0.0",
+  "version": "16.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -46,6 +46,8 @@
     "slc/gears2fsm.md",
     "slc/text2gears.md",
     "slc/optimize.md",
+    "slc/prefix.md",
+    "slc/prefix-prompts.mjs",
     "reference/sdlc/captain.md",
     "reference/sdlc/code.md",
     "reference/sdlc/review.md",

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

@@ -1,34 +1,46 @@
 export type BranchStateId = 'createBranch';
 export type BranchSourceItem = 'BRANCH-1';
+/**
+ * Stable working-leaf ids that may suspend on a Boss question and be resumed
+ * by `BOSS_REPLY`. The machine has at most one active player task, so the
+ * scalar Boss-reply form applies.
+ */
+declare const RESUMABLE_STATE_IDS: readonly ["createBranch"];
+export type ResumableStateId = (typeof RESUMABLE_STATE_IDS)[number];
+/** JSON-safe normalization of a rejected invocation, retained for inspection. */
+export type NormalizedError = {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+};
+/** Question record raised by the suspended Coder working leaf. */
 export type PendingBossQuestion = {
-    readonly questionId: 'createBranch';
-    readonly resumeStateId: 'createBranch';
-    readonly sourceItem: 'BRANCH-1';
+    readonly questionId: ResumableStateId;
+    readonly resumeStateId: ResumableStateId;
+    readonly sourceItem: BranchSourceItem;
     readonly asker: {
         readonly kind: 'role';
         readonly roleId: 'coder';
     };
     readonly question: string;
 };
+/** Typed input for the delegated `player` actor. */
 export type PlayerInput = {
     readonly stateId: 'createBranch';
     readonly role: 'coder';
     readonly sourceItem: 'BRANCH-1';
     readonly prompt: string;
     readonly result: Readonly<Record<string, string>>;
+    /** Backs the prompt's `<caller-input>` placeholder with the exact caller input. */
     readonly callerInput: string;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
 };
+/** Discriminated result contract of the delegated `player` actor. */
 export type PlayerOutput = {
     readonly guard: 'branched';
     readonly branch: string;
-    /**
-     * Receipt-owned effect evidence (DR-045): the branching call's
-     * `unchanged` receipt observes the commit the branch was created from
-     * as HEAD, so the linked runtime injects it and never takes it from
-     * Coder's prose.
-     */
+    /** Exact base revision from repository authority, not from Coder's prose. */
     readonly baseRevision: string;
     readonly issueSummary: string;
 } | {
@@ -38,47 +50,55 @@ export type PlayerOutput = {
     readonly guard: 'needsBossReply';
     readonly question: string;
 };
+/**
+ * Terminal result: exactly the packaged `branch` workflow's public output
+ * interface (workflow-contracts.json), derived from typed context.
+ */
 export type BranchPlaybookOutput = {
     readonly status: 'branched';
-    /** Exact name of the new branch now checked out. */
+    /** Exact new branch name. */
     readonly branch: string;
-    /** Exact receipt-observed revision the branch was created from. */
+    /** Exact receipt-observed repository revision the branch was created from. */
     readonly baseRevision: string;
-    /** Coder's concise summary of the issue and its comments, or of the request. */
+    /** Concise issue-and-comments or request summary. */
     readonly issueSummary: string;
 } | {
     readonly status: 'refused';
-    /** Coder's complete report carrying the reason no branch was created. */
+    /** Complete refusal report. */
     readonly coderOutput: string;
 };
-export type BranchInput = Readonly<Record<string, never>>;
+/** The machine reads no input: the caller input arrives on `START_BRANCH`. */
+export type BranchInput = Readonly<Record<never, never>>;
+export type BranchCompletion = 'branched' | 'refused';
 export type BranchContext = {
     readonly callerInput?: string;
     readonly branch?: string;
-    /** Observed HEAD of the branching call's unchanged receipt (DR-045). */
     readonly baseRevision?: string;
     readonly issueSummary?: string;
     readonly coderOutput?: string;
-    readonly completion?: 'branched' | 'refused';
-    readonly lastError?: unknown;
+    readonly completion?: BranchCompletion;
+    readonly lastError?: NormalizedError;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
 };
+/** Typed Boss surfaces: the caller's entry event and the Boss reply. */
 export type BranchEvent = {
     readonly type: 'START_BRANCH';
     readonly callerInput: string;
 } | {
     readonly type: 'BOSS_REPLY';
     readonly answer: string;
-    readonly questionId?: 'createBranch';
+    readonly questionId?: ResumableStateId;
 };
+/** No parallel group in this playbook. */
+export declare const concurrentRoleSets: readonly (readonly string[])[];
 export declare const branchMachine: import("xstate").StateMachine<BranchContext, {
     readonly type: "START_BRANCH";
     readonly callerInput: string;
 } | {
     readonly type: "BOSS_REPLY";
     readonly answer: string;
-    readonly questionId?: "createBranch";
+    readonly questionId?: ResumableStateId;
 }, {
     [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
 }, {
@@ -96,16 +116,22 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberPendingQuestion";
+    type: "rememberMalformedPlayerOutput";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberBossReply";
+    type: "clearBossReplyContext";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberEmptyBossReplyError";
+    type: "setPendingBossQuestion";
+    params: {
+        readonly stateId: ResumableStateId;
+        readonly sourceItem: BranchSourceItem;
+    };
+} | {
+    type: "rememberMalformedBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberMalformedPlayerOutput";
+    type: "acceptBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "startBranch";
@@ -118,9 +144,16 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
     params: import("xstate").NonReducibleUnknown;
 }, {
     type: "needsBossReply";
-    params: unknown;
+    params: {
+        readonly stateId: ResumableStateId;
+    };
 } | {
-    type: "emptyBossReply";
+    type: "canResume";
+    params: {
+        readonly stateId: ResumableStateId;
+    };
+} | {
+    type: "givesRequest";
     params: unknown;
 } | {
     type: "isBranched";
@@ -128,20 +161,17 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
 } | {
     type: "isRefused";
     params: unknown;
-} | {
-    type: "resumesCreateBranch";
-    params: unknown;
-}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
+}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<never, never>>, {
     readonly status: "branched";
-    /** Exact name of the new branch now checked out. */
+    /** Exact new branch name. */
     readonly branch: string;
-    /** Exact receipt-observed revision the branch was created from. */
+    /** Exact receipt-observed repository revision the branch was created from. */
     readonly baseRevision: string;
-    /** Coder's concise summary of the issue and its comments, or of the request. */
+    /** Concise issue-and-comments or request summary. */
     readonly issueSummary: string;
 } | {
     readonly status: "refused";
-    /** Coder's complete report carrying the reason no branch was created. */
+    /** Complete refusal report. */
     readonly coderOutput: string;
 }, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "branch";