@sublang/playbook 13.1.0 → 13.3.0

package/reference/sdlc/dev.playbook/dev.playbook.js

@@ -9,7 +9,9 @@
 //                BOSS_REPLY
 // Adjudication:  LLM judge for the one Analyst state; planningResult is
 //                carried verbatim
-// Nested calls:  literal code and decide targets through the shared bridge
+// Nested calls:  literal code, decide, branch, and pr targets through the
+//                shared bridge; branch, revision, commit, and pull-request
+//                identities enter only from canonical child results
 // Compat:        artifact schema 3 / runtime ABI 1
 import { createXStatePlaybookRuntime, composePlayerContinuation, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { devMachine, } from './dev.fsm.js';
@@ -116,6 +118,16 @@ const runtimeSpec = {
                     fields: { planningResult: 'presentation' },
                     repositoryDisposition: 'unchanged',
                 },
+                // DR-050: reading a GitHub issue during planning is not an effect, so
+                // the two pull-request outcomes stay `unchanged` like the plain ones.
+                codeViaPullRequest: {
+                    fields: { planningResult: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                decideThenCodeViaPullRequest: {
+                    fields: { planningResult: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
                 needsBossReply: {
                     fields: { question: 'presentation' },
                     repositoryDisposition: 'unchanged',

package/reference/sdlc/dev.playbook/dev.playbook.ts

@@ -9,7 +9,9 @@
 //                BOSS_REPLY
 // Adjudication:  LLM judge for the one Analyst state; planningResult is
 //                carried verbatim
-// Nested calls:  literal code and decide targets through the shared bridge
+// Nested calls:  literal code, decide, branch, and pr targets through the
+//                shared bridge; branch, revision, commit, and pull-request
+//                identities enter only from canonical child results
 // Compat:        artifact schema 3 / runtime ABI 1
 
 import {
@@ -205,6 +207,16 @@ const runtimeSpec = {
           fields: { planningResult: 'presentation' },
           repositoryDisposition: 'unchanged',
         },
+        // DR-050: reading a GitHub issue during planning is not an effect, so
+        // the two pull-request outcomes stay `unchanged` like the plain ones.
+        codeViaPullRequest: {
+          fields: { planningResult: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+        decideThenCodeViaPullRequest: {
+          fields: { planningResult: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
         needsBossReply: {
           fields: { question: 'presentation' },
           repositoryDisposition: 'unchanged',

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

@@ -29,7 +29,7 @@ export interface DevPlaybookRegistryEntry {
 export declare const devStateCountLabels: {
     readonly planAnalysis: "planning round";
 };
-export declare const devCopyPasteGuardNames: readonly ["code", "decideThenCode"];
+export declare const devCopyPasteGuardNames: readonly ["code", "decideThenCode", "codeViaPullRequest", "decideThenCodeViaPullRequest"];
 export declare function devSavedCountsLine(counts: {
     interruptions: number;
     copyPastes: number;

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

@@ -7,7 +7,12 @@ import createPlaybookRuntime from './dev.playbook.js';
 export const devStateCountLabels = {
     planAnalysis: 'planning round',
 };
-export const devCopyPasteGuardNames = ['code', 'decideThenCode'];
+export const devCopyPasteGuardNames = [
+    'code',
+    'decideThenCode',
+    'codeViaPullRequest',
+    'decideThenCodeViaPullRequest',
+];
 function countNoun(count, singular, plural = `${singular}s`) {
     return `${count} ${count === 1 ? singular : plural}`;
 }
@@ -44,7 +49,7 @@ export function validateDevOptions(optionSlice) {
 export const devPlaybookRegistryEntry = {
     id: 'dev',
     command: 'dev',
-    intent: 'analyze a development request that needs planning before choosing direct implementation or a durable decision first',
+    intent: 'analyze a development request that needs planning before choosing direct implementation or a durable decision first, delivered through a pull request when the request names a GitHub issue or asks for one',
     artifactSchema: 3,
     runtimeProfile: Object.freeze({
         kind: 'shared-factory',

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

@@ -46,7 +46,12 @@ export const devStateCountLabels = {
   planAnalysis: 'planning round',
 } as const;
 
-export const devCopyPasteGuardNames = ['code', 'decideThenCode'] as const;
+export const devCopyPasteGuardNames = [
+  'code',
+  'decideThenCode',
+  'codeViaPullRequest',
+  'decideThenCodeViaPullRequest',
+] as const;
 
 function countNoun(
   count: number,
@@ -99,7 +104,7 @@ export const devPlaybookRegistryEntry: DevPlaybookRegistryEntry = {
   id: 'dev',
   command: 'dev',
   intent:
-    'analyze a development request that needs planning before choosing direct implementation or a durable decision first',
+    'analyze a development request that needs planning before choosing direct implementation or a durable decision first, delivered through a pull request when the request names a GitHub issue or asks for one',
   artifactSchema: 3,
   runtimeProfile: Object.freeze({
     kind: 'shared-factory',

package/reference/sdlc/pr.md

@@ -0,0 +1,108 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
+
+# PR
+
+Roles:
+
+- Coder
+
+The caller supplies:
+
+- the original request, including the issue it names, if any;
+- the issue summary;
+- the branch to deliver and the base revision it was created from;
+- the last `code`-owned commit and the exact evaluated repository revision;
+- optional relevant context.
+
+`pr` delivers a reviewed branch into the repository default branch through a GitHub pull request: it publishes the branch, waits for the pull request's checks, fixes red checks through playbook `code` no more than once, and merges.
+It changes no files and owns no repository commit; the one fix it may request is owned by `code`.
+The check waits, the fix publication, the merge, and the local update are mechanical steps: each runs one fixed command whose exit status alone decides its two outcomes, reads no conversation, and produces no prose.
+`gh` infers the pull request from the checked-out branch, so no mechanical step needs a runtime value.
+
+When the caller gives its input, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the following instruction:
+
+> Original request: <caller-input>
+
+```markdown
+Publish the branch and open its pull request without changing any file or making any commit.
+Confirm that the working tree is clean and that the checked-out branch is the branch to deliver, not the repository default branch.
+Push the branch to the repository's GitHub remote with its upstream set; never force-push.
+If an open pull request for this branch already exists, use it; otherwise open one against the repository default branch with `gh pr create`.
+Give the pull request a title naming the change and a body with a summary of what changed and why from the base revision to the last commit, the verification the commits report, and a `Closes #N` line for issue number N when the request names one.
+Report the pull request number and URL exactly.
+If the working tree is not clean, the checked-out branch is wrong, the push is rejected, or the pull request cannot be opened, open nothing further and report the failure with its reason.
+```
+
+The result has two semantic outcomes: opened and not published.
+Each outcome requires affirmative support in Coder's result, and no outcome depends on a fixed presentation format of Coder's reply.
+Every outcome keeps the repository exact: pushing a branch and opening a pull request change neither HEAD's commit nor the working tree.
+For not published, `pr` fails and reports Coder's complete result with its reason to its caller.
+
+When the pull request is open and no fix has been attempted, Captain shall wait for the pull request's checks by running exactly the following command in the repository, with no other action and without reading its output:
+
+> n=0
+> while gh pr checks 2>&1 | grep -q 'no checks reported'; do
+> n=$((n + 1))
+> [ "$n" -ge 6 ] && exit 0
+> sleep 10
+> done
+> gh pr checks --watch --fail-fast >/dev/null 2>&1
+
+The wait has exactly two outcomes decided by the command's exit status alone: checks passed on status zero and checks failed otherwise.
+A pull request whose repository still reports no checks after a brief wait for them to register counts as passed.
+
+When the checks fail before any fix attempt, Captain shall call playbook `code` with the original request, the pull request, and the coding request in quotes (`>`):
+
+> Original request: <caller-input>
+> Pull request: <pull-request-url>
+> Coding request: The pull request's checks are red on the checked-out branch. Inspect the failing checks with `gh pr checks` and `gh run view --log-failed`, fix their cause on this branch with a minimal change, and make the checks pass.
+
+`pr` makes no more than one fix attempt.
+Only after `code` succeeds shall `pr` publish the fix and wait for the checks again.
+When `code` returns an authored abort or failure, or a terminal result that does not prove its success, `pr` shall fail relaying that canonical result and shall leave the pull request open.
+When the nested `code` call fails outside that authored result contract, `pr` shall park as failed and retain the control-plane error instead of reporting an authored outcome.
+
+When `code` succeeds, Captain shall publish the fix to the pull request by running exactly the following command in the repository, with no other action and without reading its output:
+
+> git push || exit 1
+> n=0
+> until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do
+> n=$((n + 1))
+> [ "$n" -ge 12 ] && exit 1
+> sleep 5
+> done
+
+The publication has exactly two outcomes decided by the exit status alone: fix published on status zero, once the pull request's head is the pushed commit, and fix not published otherwise.
+Fix not published is an authored failure that leaves the pull request open.
+
+When the fix is published, Captain shall wait for the pull request's checks again by running exactly the same command as the first wait in the repository, with no other action and without reading its output:
+
+> n=0
+> while gh pr checks 2>&1 | grep -q 'no checks reported'; do
+> n=$((n + 1))
+> [ "$n" -ge 6 ] && exit 0
+> sleep 10
+> done
+> gh pr checks --watch --fail-fast >/dev/null 2>&1
+
+This wait has exactly two outcomes decided by the exit status alone: checks passed on status zero and checks still failing otherwise.
+Checks still failing is an authored failure that leaves the pull request open; there is no second fix attempt.
+
+When the checks pass, before or after the one fix attempt, Captain shall merge the pull request by running exactly the following command in the repository, with no other action and without reading its output:
+
+> gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"
+
+The merge creates a merge commit on the repository default branch, deletes the remote and local branch, and checks out the local default branch; GitHub closes the linked issue on merge.
+The merge has exactly two outcomes decided by the exit status alone: merged on status zero and merge refused otherwise.
+Merge refused is an authored failure that leaves the pull request in the state GitHub reports: GitHub refused the merge for a conflict, a branch protection, a forbidden merge method, or a head that moved, or the merge landed but the local switch to the default branch or the branch deletion failed.
+
+When the pull request is merged, Captain shall bring the local default branch to the merged head by running exactly the following command in the repository, with no other action and without reading its output:
+
+> git pull --ff-only
+
+The update has exactly two outcomes decided by the exit status alone: local default updated on status zero and local default not updated otherwise.
+Both complete `pr`: the pull request is merged either way, and the result states whether the local default branch was fast-forwarded to the merged head.
+
+On completion, `pr` returns the pull request number and URL, the fact that the pull request is merged, and whether the local default branch was fast-forwarded to the merged head.

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

@@ -0,0 +1,352 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type PrStateId = 'openPullRequest' | 'waitForChecks' | 'fixChecks' | 'publishFix' | 'waitForChecksAfterFix' | 'mergePullRequest' | 'updateLocalDefault';
+export type PrSourceItem = 'PR-1' | 'PR-2' | 'PR-3' | 'PR-4' | 'PR-5' | 'PR-6' | 'PR-7';
+export type PrScriptStateId = 'waitForChecks' | 'publishFix' | 'waitForChecksAfterFix' | 'mergePullRequest' | 'updateLocalDefault';
+export type PrScriptSourceItem = 'PR-2' | 'PR-4' | 'PR-5' | 'PR-6' | 'PR-7';
+export type PrChildPlaybookId = 'code';
+export type PendingBossQuestion = {
+    readonly questionId: 'openPullRequest';
+    readonly resumeStateId: 'openPullRequest';
+    readonly sourceItem: 'PR-1';
+    readonly asker: {
+        readonly kind: 'role';
+        readonly roleId: 'coder';
+    };
+    readonly question: string;
+};
+export type PlayerInput = {
+    readonly stateId: 'openPullRequest';
+    readonly role: 'coder';
+    readonly sourceItem: 'PR-1';
+    readonly prompt: string;
+    readonly result: Readonly<Record<string, string>>;
+    readonly callerInput: string;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+};
+export type PlayerOutput = {
+    readonly guard: 'opened';
+    readonly pullRequest: string;
+    readonly pullRequestUrl: string;
+} | {
+    readonly guard: 'notPublished';
+    readonly coderOutput: string;
+} | {
+    readonly guard: 'needsBossReply';
+    readonly question: string;
+};
+export type PlaybookInput = {
+    readonly stateId: 'fixChecks';
+    readonly sourceItem: 'PR-3';
+    readonly playbookId: PrChildPlaybookId;
+    readonly text: string;
+};
+export type ScriptInput = {
+    readonly stateId: PrScriptStateId;
+    readonly sourceItem: PrScriptSourceItem;
+    readonly command: string;
+    readonly result: Readonly<Record<string, string>>;
+};
+export type ScriptOutput = {
+    readonly guard: 'checksPassed';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'checksFailed';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'fixPublished';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'fixNotPublished';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'checksStillFailing';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'merged';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'mergeRefused';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'localDefaultUpdated';
+    readonly exitStatus: number;
+} | {
+    readonly guard: 'localDefaultNotUpdated';
+    readonly exitStatus: number;
+};
+export type CompactError = {
+    readonly name: string;
+    readonly message: string;
+};
+/** Sanitized canonical child result relayed as PR's own failure outcome. */
+export type CompletedChildResult = {
+    readonly playbookId: PrChildPlaybookId;
+    readonly status: 'ok';
+    readonly output?: JsonValue;
+} | {
+    readonly playbookId: PrChildPlaybookId;
+    readonly status: 'aborted' | 'error';
+    readonly error: CompactError;
+};
+export type PrPlaybookOutput = {
+    readonly status: 'merged';
+    /** The pull request number, exactly as Coder reported it. */
+    readonly pullRequest: string;
+    /** The pull request URL, exactly as Coder reported it. */
+    readonly pullRequestUrl: string;
+    /** Whether the local default branch was fast-forwarded to the merged head. */
+    readonly localDefaultUpdated: boolean;
+} | {
+    readonly status: 'not-merged';
+    readonly reason: 'not-published';
+    /** Coder's complete result carrying the reason. */
+    readonly coderOutput: string;
+} | {
+    readonly status: 'not-merged';
+    readonly reason: 'fix-failed';
+    readonly pullRequest: string;
+    readonly pullRequestUrl: string;
+    /** The relayed canonical `code` result that ended the one fix attempt. */
+    readonly childResult: CompletedChildResult;
+} | {
+    readonly status: 'not-merged';
+    readonly reason: 'fix-not-published' | 'checks-failed' | 'merge-refused';
+    readonly pullRequest: string;
+    readonly pullRequestUrl: string;
+};
+export type PrCompletion = 'merged' | 'not-published' | 'fix-failed' | 'fix-not-published' | 'checks-failed' | 'merge-refused';
+/** The machine reads no input: the caller input arrives on `START_PR`. */
+export type PrInput = Readonly<Record<never, never>>;
+export type PrContext = {
+    readonly callerInput?: string;
+    readonly pullRequest?: string;
+    readonly pullRequestUrl?: string;
+    readonly completion?: PrCompletion;
+    readonly localDefaultUpdated?: boolean;
+    readonly coderOutput?: string;
+    readonly childFailure?: CompletedChildResult;
+    readonly lastError?: unknown;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+};
+export type PrEvent = {
+    readonly type: 'START_PR';
+    readonly callerInput: string;
+} | {
+    readonly type: 'BOSS_REPLY';
+    readonly answer: string;
+    readonly questionId?: 'openPullRequest';
+};
+/** PR-3's composed child input: the caller input, the pull request, and the static coding request. */
+export declare function fixChecksCallText(context: PrContext): string;
+export declare const prMachine: import("xstate").StateMachine<PrContext, {
+    readonly type: "START_PR";
+    readonly callerInput: string;
+} | {
+    readonly type: "BOSS_REPLY";
+    readonly answer: string;
+    readonly questionId?: "openPullRequest";
+}, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<ScriptOutput, ScriptInput, import("xstate").EventObject>> | undefined;
+}, {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "player";
+    logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "script";
+    logic: import("xstate").PromiseActorLogic<ScriptOutput, ScriptInput, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "playbook.acceptedOutcome";
+    params: {
+        readonly source: string;
+        readonly target: string;
+        readonly acceptedOutcome: string;
+    };
+} | {
+    type: "rememberActorError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberPendingQuestion";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberEmptyBossReplyError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedPlayerOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithInsufficientCodeResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithCodeFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "startPr";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberPullRequest";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeNotPublished";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeFixNotPublished";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeChecksStillFailing";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeMergeRefused";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeMerged";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeMergedLocalBehind";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedScriptOutput";
+    params: {
+        readonly sourceItem: PrScriptSourceItem;
+    };
+}, {
+    type: "needsBossReply";
+    params: unknown;
+} | {
+    type: "emptyBossReply";
+    params: unknown;
+} | {
+    type: "authoredCodeFailure";
+    params: unknown;
+} | {
+    type: "checksPassed";
+    params: unknown;
+} | {
+    type: "checksFailed";
+    params: unknown;
+} | {
+    type: "fixPublished";
+    params: unknown;
+} | {
+    type: "fixNotPublished";
+    params: unknown;
+} | {
+    type: "checksStillFailing";
+    params: unknown;
+} | {
+    type: "merged";
+    params: unknown;
+} | {
+    type: "mergeRefused";
+    params: unknown;
+} | {
+    type: "localDefaultUpdated";
+    params: unknown;
+} | {
+    type: "localDefaultNotUpdated";
+    params: unknown;
+} | {
+    type: "isOpened";
+    params: unknown;
+} | {
+    type: "isNotPublished";
+    params: unknown;
+} | {
+    type: "isCodeSuccess";
+    params: unknown;
+} | {
+    type: "resumesOpenPullRequest";
+    params: unknown;
+}, never, "failed" | "awaitBossReply" | "ready" | "openPullRequest" | "waitForChecks" | "fixChecks" | "publishFix" | "waitForChecksAfterFix" | "mergePullRequest" | "updateLocalDefault" | "notPublished" | "fixNotPublished" | "checksStillFailing" | "merged" | "mergeRefused" | "mergedLocalBehind" | "fixFailed", string, Readonly<Record<never, never>>, {
+    readonly status: "merged";
+    /** The pull request number, exactly as Coder reported it. */
+    readonly pullRequest: string;
+    /** The pull request URL, exactly as Coder reported it. */
+    readonly pullRequestUrl: string;
+    /** Whether the local default branch was fast-forwarded to the merged head. */
+    readonly localDefaultUpdated: boolean;
+} | {
+    readonly status: "not-merged";
+    readonly reason: "not-published";
+    /** Coder's complete result carrying the reason. */
+    readonly coderOutput: string;
+} | {
+    readonly status: "not-merged";
+    readonly reason: "fix-failed";
+    readonly pullRequest: string;
+    readonly pullRequestUrl: string;
+    /** The relayed canonical `code` result that ended the one fix attempt. */
+    readonly childResult: CompletedChildResult;
+} | {
+    readonly status: "not-merged";
+    readonly reason: "fix-not-published" | "checks-failed" | "merge-refused";
+    readonly pullRequest: string;
+    readonly pullRequestUrl: string;
+}, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "pr";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly openPullRequest: {
+            id: "openPullRequest";
+        };
+        readonly waitForChecks: {
+            id: "waitForChecks";
+        };
+        readonly fixChecks: {
+            id: "fixChecks";
+        };
+        readonly publishFix: {
+            id: "publishFix";
+        };
+        readonly waitForChecksAfterFix: {
+            id: "waitForChecksAfterFix";
+        };
+        readonly mergePullRequest: {
+            id: "mergePullRequest";
+        };
+        readonly updateLocalDefault: {
+            id: "updateLocalDefault";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly merged: {
+            id: "merged";
+        };
+        readonly mergedLocalBehind: {
+            id: "mergedLocalBehind";
+        };
+        readonly notPublished: {
+            id: "notPublished";
+        };
+        readonly fixFailed: {
+            id: "fixFailed";
+        };
+        readonly fixNotPublished: {
+            id: "fixNotPublished";
+        };
+        readonly checksStillFailing: {
+            id: "checksStillFailing";
+        };
+        readonly mergeRefused: {
+            id: "mergeRefused";
+        };
+    };
+}>;
+export default prMachine;