@sublang/playbook 11.0.0 → 12.0.0

package/reference/sdlc/decide.playbook/decide.gears.md

@@ -12,7 +12,8 @@
 
 The caller supplies a topic as `callerTopic`.
 Coder and Reviewer receive the complete topic concurrently and independently.
-Neither role's player receives the other role's proposal before both proposals finish and Coder commits Coder's own proposal.
+Neither role's player receives the other role's proposal before both proposals are complete.
+A proposal is complete only when its player affirmatively provides a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome.
 A Boss interrupt during the parallel proposal pair restarts the complete pair with the new `callerTopic`.
 
 ### DECIDE-1
@@ -30,7 +31,7 @@ When the caller gives a topic, Captain shall relay the complete topic to Coder i
 > Do not change any files.
 
 Results:
-- `proposed`: Coder completed an independent proposal. Output shall include `coderProposal: <verbatim final text>`.
+- `proposed`: Coder affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `coderProposal: <verbatim final text>`.
 
 ### DECIDE-2
 
@@ -47,39 +48,44 @@ When the caller gives a topic, Captain shall relay the complete topic to Reviewe
 > Do not change any files.
 
 Results:
-- `proposed`: Reviewer completed an independent proposal. Output shall include `reviewerProposal: <verbatim final text>`.
+- `proposed`: Reviewer affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `reviewerProposal: <verbatim final text>`.
 
-## Commit Coder's proposal
+## Synthesize and commit
 
 ### DECIDE-3
 
-When both independent proposals are complete, Captain shall prompt Coder:
+When both independent proposals are complete, Captain shall relay the complete topic and Reviewer's complete proposal to Coder under their own labels in quotes and prompt Coder:
 
-> Turn your proposal into the necessary spec items or DRs.
+> Synthesize your independent proposal with Reviewer's proposal below.
+> Keep to the original topic below and follow what it asks.
+> Keep the best, essential parts of either proposal and reject any point that is unsound, unnecessary, or outside the topic.
+> Turn the resulting design into the necessary DRs and/or spec items.
 > Follow @specs/meta.md and update @specs/map.md when needed.
-> Do not inspect or incorporate Reviewer's proposal before this commit.
-> Do not change code or implement the proposal.
+> Do not change code or implement the design.
 >
 > Commit the result as one new commit, following @specs/packages/git.md.
 > Make the commit message explain concisely what changed and why.
-> Coder is <coder-llm>; format the model token in conventional human form.
+> Identify every new commit you make.
+> Coder is <coder-llm> and Reviewer is <reviewer-llm>.
+>
+> > Original topic: <caller-topic>
+> > Reviewer's independent proposal: <reviewer-proposal>
 
 Results:
-- `committed`: Coder committed Coder's proposal. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+- `committed`: Coder synthesized both proposals and committed the resulting design as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+
+No transition depends on a fixed presentation format of either player's reply; the repository-effect receipt is the authoritative identity of Coder's new `decide`-owned commit.
 
 ## Review
 
 ### DECIDE-4
 
-When Coder commits, Captain shall call playbook `review`:
+When Coder commits, Captain shall call playbook `review` with the following input in quotes:
 
-> Review the latest commit as a spec-design change against the initial intent.
-> Compare it with your independent proposal and take the best of both.
-> Make your suggestions.
->
-> Initial intent: <caller-topic>.
-> Coder's independent proposal: <coder-proposal>.
+> > Original intent: <caller-topic>
+> > Review scope: the `decide`-owned commit <decide-commit> and its resulting repository state.
+> > Coder output: <coder-output>
 
-The successful child output is DECIDE's terminal output.
-An authored child abort, failure, or invalid approval terminates with the failure and `latestCommit` reported to the caller.
+`decide` is complete only when `review` returns a result that applies to the supplied review scope, gives the exact evaluated repository revision, and affirmatively establishes that no unsettled findings remain; `decide` then returns the `decide`-owned commit and that evaluated revision to the caller.
+An authored `review` abort or failure, or a terminal result that does not establish those facts, terminates with the failure and the last `decide`-owned commit reported to the caller.
 Any other nested-call error parks `decide` as failed and retains the control-plane error.

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

@@ -123,7 +123,10 @@ const TRACE_TOPIC = 'playbook.trace';
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
 const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
-const PLACEHOLDER_FIELDS = [['<caller-topic>', 'callerTopic']];
+const PLACEHOLDER_FIELDS = [
+    ['<caller-topic>', 'callerTopic'],
+    ['<reviewer-proposal>', 'reviewerProposal'],
+];
 const VERBATIM_PAYLOAD_FIELDS = new Set([
     'coderProposal',
     'reviewerProposal',
@@ -151,12 +154,17 @@ function composePlayerPrompt(input, promptIdentity) {
     if (input.prompt.includes('<coder-llm>')) {
         replacements.set('<coder-llm>', promptIdentity('coder'));
     }
-    const body = input.prompt.replace(/<caller-topic>|<coder-llm>/g, (placeholder, offset, source) => {
+    if (input.prompt.includes('<reviewer-llm>')) {
+        replacements.set('<reviewer-llm>', promptIdentity('reviewer'));
+    }
+    const body = input.prompt.replace(/<caller-topic>|<reviewer-proposal>|<coder-llm>|<reviewer-llm>/g, (placeholder, offset, source) => {
         const value = replacements.get(placeholder);
         if (value === undefined)
             return placeholder;
+        // A labelled quoted relay keeps a multiline value inside its authored
+        // blockquote, so continuation lines re-enter the quote marker.
         const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
-        return source.slice(lineStart, offset) === '> '
+        return source.slice(lineStart, offset).startsWith('> ')
             ? value.replaceAll('\n', '\n> ')
             : value;
     });

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

@@ -284,7 +284,10 @@ const CONTINUATION_PREAMBLE =
   'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 
 const PLACEHOLDER_FIELDS: ReadonlyArray<readonly [string, keyof PlayerInput]> =
-  [['<caller-topic>', 'callerTopic']];
+  [
+    ['<caller-topic>', 'callerTopic'],
+    ['<reviewer-proposal>', 'reviewerProposal'],
+  ];
 
 const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   'coderProposal',
@@ -322,13 +325,18 @@ function composePlayerPrompt(
   if (input.prompt.includes('<coder-llm>')) {
     replacements.set('<coder-llm>', promptIdentity('coder'));
   }
+  if (input.prompt.includes('<reviewer-llm>')) {
+    replacements.set('<reviewer-llm>', promptIdentity('reviewer'));
+  }
   const body = input.prompt.replace(
-    /<caller-topic>|<coder-llm>/g,
+    /<caller-topic>|<reviewer-proposal>|<coder-llm>|<reviewer-llm>/g,
     (placeholder, offset: number, source: string) => {
       const value = replacements.get(placeholder);
       if (value === undefined) return placeholder;
+      // A labelled quoted relay keeps a multiline value inside its authored
+      // blockquote, so continuation lines re-enter the quote marker.
       const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
-      return source.slice(lineStart, offset) === '> '
+      return source.slice(lineStart, offset).startsWith('> ')
         ? value.replaceAll('\n', '\n> ')
         : value;
     },

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

@@ -41,7 +41,7 @@ export function validateDecideOptions(optionSlice) {
 export const decidePlaybookRegistryEntry = {
     id: 'decide',
     command: 'decide',
-    intent: 'turn independent Coder and Reviewer proposals into an approved spec-design commit',
+    intent: 'synthesize independent Coder and Reviewer proposals into an approved spec-design commit',
     artifactSchema: 3,
     runtimeProfile: Object.freeze({
         kind: 'bespoke',

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

@@ -95,7 +95,7 @@ export const decidePlaybookRegistryEntry: DecidePlaybookRegistryEntry = {
   id: 'decide',
   command: 'decide',
   intent:
-    'turn independent Coder and Reviewer proposals into an approved spec-design commit',
+    'synthesize independent Coder and Reviewer proposals into an approved spec-design commit',
   artifactSchema: 3,
   runtimeProfile: Object.freeze({
     kind: 'bespoke',

package/reference/sdlc/dev.md

@@ -0,0 +1,52 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
+
+# Dev
+
+Roles:
+
+- Analyst
+
+The caller supplies a development request including any desired outcome, scope, and context.
+
+`dev` is an optional repository-aware planner for a development request that needs more analysis before choosing a development path.
+It coordinates existing playbooks and owns no repository commit itself.
+
+At the start of `dev` and after each Boss reply, Captain shall relay the development request, relevant discussion context, and any relevant run results to Analyst in quotes (`>`), along with the following instruction:
+
+```markdown
+Inspect the request and the relevant repository and specs only as needed to determine the smallest sound next step.
+Do not change files or commit while planning or discussing the request.
+
+- If useful analysis or clarification should be discussed before any repository work, give Boss the useful response and ask one material question that advances the decision.
+- If the discussion has concluded after a Boss reply and no repository work should follow, choose `discussion complete`.
+- If implementation can proceed under the existing decisions, choose `code`.
+- If implementation first requires a new or amended durable decision that the existing specs do not settle, choose `decide then code`.
+
+A question or exploratory discussion is not by itself authorization to create a durable decision or implement changes.
+Do not choose `decide then code` merely because the work is large.
+Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
+```
+
+The planning result has four semantic outcomes: needs Boss reply, discussion complete, code, and decide then code.
+Each outcome requires affirmative support in Analyst's result; absence of a reason to choose another outcome is not support.
+No outcome depends on a fixed presentation format of Analyst's reply.
+`dev` shall act on the accepted outcome itself and shall not return to the session Captain for another routing decision.
+
+For needs Boss reply, `dev` shall use the standard Boss-question suspension with Analyst's complete response.
+The session Captain shall present that response to Boss and, after Boss replies, resume `dev` with the question and answer in the same Analyst conversation.
+
+Discussion complete is available only after a Boss reply, when any useful analysis has already been presented through needs Boss reply.
+It completes `dev` without a child call or repository change.
+
+For code, `dev` shall directly call playbook `code` with the development request, relevant discussion context, and planning result in quotes (`>`).
+
+For decide then code, `dev` shall call playbook `decide` with the development request, relevant discussion context, and planning result in quotes (`>`).
+Only after `decide` succeeds shall `dev` call playbook `code` with the development request, relevant discussion context, planning result, `decide`-owned commit, and exact evaluated repository revision in quotes (`>`).
+`dev` shall not separately call `review` for the design scope already reviewed by `decide`.
+
+`dev` completes with the successful result of its final child call.
+If a child returns an authored abort or failure, or a terminal result that does not prove the success required for the selected path, `dev` shall start no later child and shall relay that canonical result.
+If a child call fails outside its authored result contract, `dev` shall park as failed and retain the control-plane error.
+`dev` shall consume commit identities only from each child's canonical structured result, never from player prose.

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

@@ -0,0 +1,261 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type DevStateId = 'planAnalysis' | 'callCode' | 'callDecide' | 'callCodeAfterDecide';
+export type DevSourceItem = 'DEV-1' | 'DEV-2' | 'DEV-3' | 'DEV-4';
+export type DevChildPlaybookId = 'code' | 'decide';
+export type PendingBossQuestion = {
+    readonly questionId: 'planAnalysis';
+    readonly resumeStateId: 'planAnalysis';
+    readonly sourceItem: 'DEV-1';
+    readonly asker: {
+        readonly kind: 'role';
+        readonly roleId: 'analyst';
+    };
+    readonly question: string;
+};
+export type DiscussionExchange = {
+    readonly question: string;
+    readonly answer: string;
+};
+export type PlayerInput = {
+    readonly stateId: 'planAnalysis';
+    readonly role: 'analyst';
+    readonly sourceItem: 'DEV-1';
+    readonly prompt: string;
+    readonly result: Readonly<Record<string, string>>;
+    readonly developmentRequest: string;
+    readonly discussionContext: string;
+    readonly runResults: string;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+};
+export type PlayerOutput = {
+    readonly guard: 'discussionComplete';
+} | {
+    readonly guard: 'code';
+    readonly planningResult: string;
+} | {
+    readonly guard: 'decideThenCode';
+    readonly planningResult: string;
+} | {
+    readonly guard: 'needsBossReply';
+    readonly question: string;
+};
+export type PlaybookInput = {
+    readonly stateId: 'callCode' | 'callDecide' | 'callCodeAfterDecide';
+    readonly sourceItem: 'DEV-2' | 'DEV-3' | 'DEV-4';
+    readonly playbookId: DevChildPlaybookId;
+    readonly text: string;
+};
+/**
+ * The affirmative success proof DEV requires from `decide`'s canonical
+ * structured terminal output before starting the dependent `code` call:
+ * the `decide`-owned commit, the exact evaluated repository revision, and
+ * the affirmative no-unsettled-findings fact. Additional members belong to
+ * DECIDE's own contract and do not disprove success.
+ */
+export type DecideSuccessOutput = {
+    readonly decideCommit: string;
+    readonly evaluatedRevision: string;
+    readonly noUnsettledFindings: true;
+};
+export type CompactError = {
+    readonly name: string;
+    readonly message: string;
+};
+/** Sanitized canonical child result relayed as DEV's own failure outcome. */
+export type CompletedChildResult = {
+    readonly playbookId: DevChildPlaybookId;
+    readonly status: 'ok';
+    readonly output?: JsonValue;
+} | {
+    readonly playbookId: DevChildPlaybookId;
+    readonly status: 'aborted' | 'error';
+    readonly error: CompactError;
+};
+export type DevPlaybookOutput = {
+    readonly status: 'discussion-complete';
+} | {
+    readonly status: 'complete';
+    readonly childPlaybookId: 'code';
+    /** The successful result of DEV's final child call, when it has one. */
+    readonly childOutput?: JsonValue;
+} | {
+    readonly status: 'child-failed';
+    /** The relayed canonical child result that ended the selected path. */
+    readonly childResult: CompletedChildResult;
+};
+export type DevInput = {
+    readonly runResults?: string;
+};
+export type DevContext = {
+    readonly runResults: string;
+    readonly developmentRequest?: string;
+    readonly discussionExchanges: readonly DiscussionExchange[];
+    readonly planningResult?: string;
+    readonly decideCommit?: string;
+    readonly evaluatedRevision?: string;
+    readonly completion?: 'discussion-complete' | 'complete' | 'child-failed';
+    readonly childOutput?: JsonValue;
+    readonly childFailure?: CompletedChildResult;
+    readonly lastError?: unknown;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+};
+export type DevEvent = {
+    readonly type: 'START_DEV';
+    readonly developmentRequest: string;
+} | {
+    readonly type: 'BOSS_REPLY';
+    readonly answer: string;
+    readonly questionId?: 'planAnalysis';
+};
+/** Consumed planning Q&A rendered for later relayed discussion context. */
+export declare function renderDiscussionContext(exchanges: readonly DiscussionExchange[]): string;
+export declare const devMachine: import("xstate").StateMachine<DevContext, {
+    readonly type: "START_DEV";
+    readonly developmentRequest: string;
+} | {
+    readonly type: "BOSS_REPLY";
+    readonly answer: string;
+    readonly questionId?: "planAnalysis";
+}, {
+    [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>> | 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;
+}, {
+    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: "startDev";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeDiscussion";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCodePath";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberDecidePath";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberDecideResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithChildSuccess";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithInsufficientCodeResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithInsufficientDecideResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithCodeFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithDecideFailure";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "needsBossReply";
+    params: unknown;
+} | {
+    type: "emptyBossReply";
+    params: unknown;
+} | {
+    type: "isDiscussionComplete";
+    params: unknown;
+} | {
+    type: "isCodePath";
+    params: unknown;
+} | {
+    type: "isDecideThenCode";
+    params: unknown;
+} | {
+    type: "isCodeSuccess";
+    params: unknown;
+} | {
+    type: "isDecideSuccess";
+    params: unknown;
+} | {
+    type: "authoredCodeFailure";
+    params: unknown;
+} | {
+    type: "authoredDecideFailure";
+    params: unknown;
+} | {
+    type: "resumesPlanAnalysis";
+    params: unknown;
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "planAnalysis" | "callCode" | "callDecide" | "callCodeAfterDecide" | "discussionComplete" | "reportedChildFailure", string, DevInput, {
+    readonly status: "discussion-complete";
+} | {
+    readonly status: "complete";
+    readonly childPlaybookId: "code";
+    /** The successful result of DEV's final child call, when it has one. */
+    readonly childOutput?: JsonValue;
+} | {
+    readonly status: "child-failed";
+    /** The relayed canonical child result that ended the selected path. */
+    readonly childResult: CompletedChildResult;
+}, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "dev";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly planAnalysis: {
+            id: "planAnalysis";
+        };
+        readonly callCode: {
+            id: "callCode";
+        };
+        readonly callDecide: {
+            id: "callDecide";
+        };
+        readonly callCodeAfterDecide: {
+            id: "callCodeAfterDecide";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly discussionComplete: {
+            id: "discussionComplete";
+        };
+        readonly done: {
+            id: "done";
+        };
+        readonly reportedChildFailure: {
+            id: "reportedChildFailure";
+        };
+    };
+}>;
+export default devMachine;