@sublang/playbook 11.0.0 → 12.1.0

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

@@ -43,7 +43,13 @@ type BossReplies = Partial<Record<ResumableStateId, string>>;
 type PendingBossQuestionParams = Omit<PendingBossQuestion, 'questionId'>;
 
 export interface ReviewSuccessOutput {
-  approvedCommit: 'latest';
+  evaluatedRevision: string;
+  noUnsettledFindings: true;
+}
+
+export interface DecideSuccessOutput {
+  decideCommit: string;
+  evaluatedRevision: string;
   noUnsettledFindings: true;
 }
 
@@ -57,7 +63,7 @@ export interface DecideFailureOutput {
   };
 }
 
-export type DecideOutput = ReviewSuccessOutput | DecideFailureOutput;
+export type DecideOutput = DecideSuccessOutput | DecideFailureOutput;
 
 interface ChildFailure {
   status: 'aborted' | 'error';
@@ -73,6 +79,7 @@ export interface DecideContext {
   coderProposal?: string;
   reviewerProposal?: string;
   latestCommit?: string;
+  coderOutput?: string;
   reviewResult?: ReviewSuccessOutput;
   reviewFailure?: ChildFailure;
   lastResult?: PlayerOutput;
@@ -105,6 +112,7 @@ export interface PlayerInput {
   result: Record<string, string>;
   role: Role;
   callerTopic?: string;
+  reviewerProposal?: string;
   pendingBossQuestion?: PendingBossQuestion;
   bossReply?: string;
 }
@@ -149,37 +157,48 @@ const INDEPENDENT_PROPOSAL_PROMPT = [
   'Do not change any files.',
 ].join('\n');
 
-const COMMIT_CODER_PROMPT = [
-  'Turn your proposal into the necessary spec items or DRs.',
+const SYNTHESIZE_COMMIT_PROMPT = [
+  "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>",
 ].join('\n');
 
 const REVIEW_INPUT_TEMPLATE = [
-  '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>',
 ].join('\n');
 
 function composeReviewInput(
   callerTopic: string | undefined,
-  coderProposal: string | undefined,
+  decideCommit: string | undefined,
+  coderOutput: string | undefined,
 ): string {
   const fields: Readonly<Record<string, string>> = {
     '<caller-topic>': callerTopic ?? '',
-    '<coder-proposal>': coderProposal ?? '',
+    '<decide-commit>': decideCommit ?? '',
+    '<coder-output>': coderOutput ?? '',
   };
   return REVIEW_INPUT_TEMPLATE.replace(
-    /<caller-topic>|<coder-proposal>/g,
-    (placeholder) => fields[placeholder],
+    /<caller-topic>|<decide-commit>|<coder-output>/g,
+    (placeholder, offset: number, source: string) => {
+      const value = fields[placeholder];
+      const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
+      return source.slice(lineStart, offset).startsWith('> ')
+        ? value.replaceAll('\n', '\n> ')
+        : value;
+    },
   );
 }
 
@@ -370,20 +389,24 @@ function isPlaybookState(value: unknown): boolean {
   );
 }
 
+// DECIDE supplied `review` a scope rooted at the `decide`-owned commit, so a
+// result applies to that scope only when it is the exact declared terminal
+// contract: the evaluated repository revision plus the affirmative
+// no-unsettled-findings fact. Any other shape does not establish those facts.
 function reviewSuccessFrom(event: unknown): ReviewSuccessOutput | undefined {
   const output = playbookOutputOf(event);
   if (!isPlainRecord(output)) return undefined;
-  if (!isExactKeys(output, ['approvedCommit', 'noUnsettledFindings'])) {
+  if (!isExactKeys(output, ['evaluatedRevision', 'noUnsettledFindings'])) {
     return undefined;
   }
   if (
-    output.approvedCommit !== 'latest' ||
+    !isNonEmptyString(output.evaluatedRevision) ||
     output.noUnsettledFindings !== true
   ) {
     return undefined;
   }
   return {
-    approvedCommit: 'latest',
+    evaluatedRevision: output.evaluatedRevision,
     noUnsettledFindings: true,
   };
 }
@@ -537,6 +560,7 @@ export const decideMachine = setup({
       coderProposal: undefined,
       reviewerProposal: undefined,
       latestCommit: undefined,
+      coderOutput: undefined,
       reviewResult: undefined,
       reviewFailure: undefined,
       lastResult: undefined,
@@ -552,6 +576,7 @@ export const decideMachine = setup({
       coderProposal: undefined,
       reviewerProposal: undefined,
       latestCommit: undefined,
+      coderOutput: undefined,
       reviewResult: undefined,
       reviewFailure: undefined,
       lastResult: undefined,
@@ -583,6 +608,7 @@ export const decideMachine = setup({
     }),
     rememberCommit: assign({
       latestCommit: ({ event }) => outputOf(event).latestCommit,
+      coderOutput: ({ event }) => outputOf(event).coderOutput,
       lastResult: ({ event }) => outputOf(event),
       lastError: undefined,
     }),
@@ -603,7 +629,7 @@ export const decideMachine = setup({
         error: {
           name: 'ReviewProtocolError',
           message:
-            'REVIEW returned without an approved latest commit and a no-findings result.',
+            'REVIEW returned without the evaluated repository revision and a no-unsettled-findings result for the supplied scope.',
         },
       },
       lastError: undefined,
@@ -678,7 +704,16 @@ export const decideMachine = setup({
   initial: 'ready',
   context: (): DecideContext => ({}),
   output: ({ context }): DecideOutput => {
-    if (context.reviewResult) return context.reviewResult;
+    if (context.reviewResult) {
+      if (!context.latestCommit) {
+        throw new Error('DECIDE completed without its decide-owned commit');
+      }
+      return {
+        decideCommit: context.latestCommit,
+        evaluatedRevision: context.reviewResult.evaluatedRevision,
+        noUnsettledFindings: true,
+      };
+    }
     if (!context.latestCommit || !context.reviewFailure) {
       throw new Error('DECIDE reached a final state without a result');
     }
@@ -747,7 +782,7 @@ export const decideMachine = setup({
                   prompt: INDEPENDENT_PROPOSAL_PROMPT,
                   result: withNeedsBossReply({
                     proposed:
-                      'Coder completed an independent proposal. Output shall include `coderProposal: <verbatim final text>`.',
+                      '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>`.',
                   }),
                   callerTopic: context.callerTopic,
                   ...bossReplyFields(context, 'askCoderProposal'),
@@ -887,7 +922,7 @@ export const decideMachine = setup({
                   prompt: INDEPENDENT_PROPOSAL_PROMPT,
                   result: withNeedsBossReply({
                     proposed:
-                      'Reviewer completed an independent proposal. Output shall include `reviewerProposal: <verbatim final text>`.',
+                      '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>`.',
                   }),
                   callerTopic: context.callerTopic,
                   ...bossReplyFields(context, 'askReviewerProposal'),
@@ -1014,11 +1049,12 @@ export const decideMachine = setup({
     commitCoderProposal: {
       id: 'commitCoderProposal',
       tags: 'playbook.busy',
-      description: 'Coder writes and commits Coder’s independent proposal.',
+      description: 'Coder synthesizes both proposals and commits the design.',
       meta: {
         playbook: {
           stateId: 'commitCoderProposal',
-          description: 'Coder writes and commits Coder’s independent proposal.',
+          description:
+            'Coder synthesizes both proposals and commits the design.',
           role: 'coder',
         },
       },
@@ -1028,11 +1064,13 @@ export const decideMachine = setup({
           stateId: 'commitCoderProposal',
           sourceItem: 'DECIDE-3',
           role: 'coder',
-          prompt: COMMIT_CODER_PROMPT,
+          prompt: SYNTHESIZE_COMMIT_PROMPT,
           result: withNeedsBossReply({
             committed:
-              "Coder committed Coder's proposal. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
+              'Coder synthesized both proposals and committed the resulting design as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
           }),
+          callerTopic: context.callerTopic,
+          reviewerProposal: context.reviewerProposal,
           ...bossReplyFields(context, 'commitCoderProposal'),
         }),
         onDone: [
@@ -1141,7 +1179,8 @@ export const decideMachine = setup({
           playbookId: 'review',
           text: composeReviewInput(
             context.callerTopic,
-            context.coderProposal,
+            context.latestCommit,
+            context.coderOutput,
           ),
         }),
         onDone: [

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.