@sublang/playbook 1.3.0 → 3.0.0

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

@@ -191,29 +191,29 @@ const stateDescriptions = {
   summarizeSpecs:
     'CODE-4: Coder summarizes a completed IR into minimal spec items.',
   reviewBossCommitSpecs:
-    'CODE-5: Reviewer reviews a Boss-intent commit whose changes are only in @specs/{user,dev,test}/.',
+    'CODE-5: Reviewer reviews a Boss-intent commit whose changes are only in spec item files.',
   reviewBossCommitCode:
-    'CODE-6: Reviewer reviews a Boss-intent commit whose changes are only outside @specs/{user,dev,test}/.',
+    'CODE-6: Reviewer reviews a Boss-intent commit whose changes are only outside spec item files.',
   reviewBossCommitMixed:
-    'CODE-7: Reviewer reviews a Boss-intent commit whose changes span both @specs/{user,dev,test}/ and other files.',
+    'CODE-7: Reviewer reviews a Boss-intent commit whose changes span both spec item files and other files.',
   reviewIrTaskCommitSpecs:
-    'CODE-8: Reviewer reviews an IR-task commit whose changes are only in @specs/{user,dev,test}/.',
+    'CODE-8: Reviewer reviews an IR-task commit whose changes are only in spec item files.',
   reviewIrTaskCommitCode:
-    'CODE-9: Reviewer reviews an IR-task commit whose changes are only outside @specs/{user,dev,test}/.',
+    'CODE-9: Reviewer reviews an IR-task commit whose changes are only outside spec item files.',
   reviewIrTaskCommitMixed:
-    'CODE-10: Reviewer reviews an IR-task commit whose changes span both @specs/{user,dev,test}/ and other files.',
+    'CODE-10: Reviewer reviews an IR-task commit whose changes span both spec item files and other files.',
   reviewChangesSpecs:
-    'CODE-11: Reviewer reviews uncommitted Coder changes that touch only @specs/{user,dev,test}/ with no accompanying rebuttals.',
+    'CODE-11: Reviewer reviews uncommitted Coder changes that touch only spec item files with no accompanying rebuttals.',
   reviewChangesCode:
-    'CODE-12: Reviewer reviews uncommitted Coder changes that touch only files outside @specs/{user,dev,test}/ with no accompanying rebuttals.',
+    'CODE-12: Reviewer reviews uncommitted Coder changes that touch only files outside spec item files with no accompanying rebuttals.',
   reviewChangesMixed:
-    'CODE-13: Reviewer reviews uncommitted Coder changes that touch both @specs/{user,dev,test}/ and other files with no accompanying rebuttals.',
+    'CODE-13: Reviewer reviews uncommitted Coder changes that touch both spec item files and other files with no accompanying rebuttals.',
   reviewChangesAndChallengesSpecs:
-    'CODE-15: Reviewer reviews uncommitted Coder changes that touch only @specs/{user,dev,test}/ and adjudicates accompanying rebuttals in one round.',
+    'CODE-15: Reviewer reviews uncommitted Coder changes that touch only spec item files and adjudicates accompanying rebuttals in one round.',
   reviewChangesAndChallengesCode:
-    'CODE-16: Reviewer reviews uncommitted Coder changes that touch only files outside @specs/{user,dev,test}/ and adjudicates accompanying rebuttals in one round.',
+    'CODE-16: Reviewer reviews uncommitted Coder changes that touch only files outside spec item files and adjudicates accompanying rebuttals in one round.',
   reviewChangesAndChallengesMixed:
-    'CODE-17: Reviewer reviews uncommitted Coder changes that touch both @specs/{user,dev,test}/ and other files and adjudicates accompanying rebuttals in one round.',
+    'CODE-17: Reviewer reviews uncommitted Coder changes that touch both spec item files and other files and adjudicates accompanying rebuttals in one round.',
   adjudicateChallenges:
     'CODE-14: Reviewer adjudicates Coder rebuttals against the prior review when Coder produced no code edits this round.',
   commitCoderInitial:
@@ -354,7 +354,7 @@ const planAndImplementInput: PlayerInputFactory = (context) => ({
   ...bossReplyInputFields(context),
   prompt: [
     'Assess whether this can be completed in a single commit, following best practices.',
-    'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations and stop without implementing any IR task.',
+    'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/intents (or @specs/iterations in older scaffolds) and stop without implementing any IR task.',
     'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
     'Ensure @specs/map.md reflects the changes.',
     'Do not commit.',
@@ -396,9 +396,9 @@ const summarizeSpecsInput: PlayerInputFactory = (context) => ({
     'Read IR-<#> and corresponding commits.',
     'According to @specs/meta.md, add or update spec items to fully capture:',
     '',
-    '- the user requirements in @specs/user,',
-    '- the system behavior in @specs/dev, and',
-    '- the integration/system test cases in @specs/test.',
+    '- the external behavior users rely on,',
+    '- the internal system behavior, and',
+    '- the integration/system test cases.',
     '',
     'The spec items should be the *minimal* set needed to reimplement code without the IR.',
     'The set should be complete and coherent.',
@@ -408,7 +408,7 @@ const summarizeSpecsInput: PlayerInputFactory = (context) => ({
   ].join('\n'),
   result: withNeedsBossReply({
     specsReady: 'Coder produced uncommitted spec updates (Initial Changes).',
-    noSpecChanges: 'Existing specs already capture the iteration.',
+    noSpecChanges: 'Existing specs already capture the realized intent.',
   }),
 });
 
@@ -656,17 +656,17 @@ export const codingMachine = setup({
           ].join('\n'),
           result: {
             changesMadeSpecs:
-              'Coder accepted items and produced unstaged/untracked edits in @specs/{user,dev,test}/ only, without raising any rebuttals.',
+              'Coder accepted items and produced unstaged/untracked edits only in spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/), without raising any rebuttals.',
             changesMadeCode:
-              'Coder accepted items and produced unstaged/untracked edits outside @specs/{user,dev,test}/ only, without raising any rebuttals.',
+              'Coder accepted items and produced unstaged/untracked edits only outside spec item files (any other files, including @specs/ decision, intent, or legacy iteration records, @specs/map.md, and @specs/meta.md), without raising any rebuttals.',
             changesMadeMixed:
-              'Coder accepted items and produced unstaged/untracked edits spanning both @specs/{user,dev,test}/ and other files, without raising any rebuttals.',
+              'Coder accepted items and produced unstaged/untracked edits spanning both spec item files and other files, without raising any rebuttals.',
             changesMadeSpecsAndChallenged:
-              'Coder produced unstaged/untracked edits in @specs/{user,dev,test}/ only AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+              'Coder produced unstaged/untracked edits only in spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/) AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
             changesMadeCodeAndChallenged:
-              'Coder produced unstaged/untracked edits outside @specs/{user,dev,test}/ only AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+              'Coder produced unstaged/untracked edits only outside spec item files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
             changesMadeMixedAndChallenged:
-              'Coder produced unstaged/untracked edits spanning both @specs/{user,dev,test}/ and other files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+              'Coder produced unstaged/untracked edits spanning both spec item files and other files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
             challengesRaised:
               'Coder challenged one or more review items without producing any code edits. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
             accepted:
@@ -831,7 +831,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -957,7 +957,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -1023,7 +1023,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -1151,7 +1151,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -1215,7 +1215,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -1321,7 +1321,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -1377,7 +1377,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -1492,7 +1492,7 @@ export const codingMachine = setup({
             'Verify any affected spec items are:',
             '',
             '- Complete & coherent: sufficient for you to reimplement code.',
-            '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
             '- Minimal: essential and concise; every item earns its place; also check with other items.',
             '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
             '',
@@ -1621,18 +1621,19 @@ export const codingMachine = setup({
           coderPlayer: context.coderPlayer,
           committerPlayer: context.committerPlayer,
           prompt: [
-            'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
+            'Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).',
+            "If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.",
             'Write the commit message concisely.',
             'Coder is <coder-llm>.',
             'Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).',
           ].join('\n'),
           result: {
             committedSpecs:
-              'Committed changes that touch only @specs/{user,dev,test}/.',
+              'Committed changes that touch only spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/).',
             committedCode:
-              'Committed changes that touch only files outside @specs/{user,dev,test}/.',
+              'Committed changes that touch only files that are not spec item files (any other files, including @specs/ decision, intent, or legacy iteration records, @specs/map.md, and @specs/meta.md).',
             committedMixed:
-              'Committed changes that span both @specs/{user,dev,test}/ and other files.',
+              'Committed changes that span both spec item files and other files.',
             noRelevantChanges: 'There are no relevant changes to commit.',
             needsBossInput: 'Committing requires additional Boss input.',
             needsBossReply: needsBossReplyDescription,
@@ -1700,7 +1701,8 @@ export const codingMachine = setup({
           reviewerPlayer: context.reviewerPlayer,
           committerPlayer: context.committerPlayer,
           prompt: [
-            'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
+            'Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).',
+            "If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.",
             'Write the commit message concisely.',
             'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
             'Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).',

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

@@ -15,7 +15,7 @@ Players:
 
 When Boss gives a coding intent, Captain shall relay it to Coder along with the following prompt:
 > Assess whether this can be completed in a single commit, following best practices.
-> If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations and stop without implementing any IR task.
+> If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/intents (or @specs/iterations in older scaffolds) and stop without implementing any IR task.
 > For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
 > Ensure @specs/map.md reflects the changes.
 > Do not commit.
@@ -42,9 +42,9 @@ When an IR is done, Captain shall prompt Coder:
 > Read IR-<#> and corresponding commits.
 > According to @specs/meta.md, add or update spec items to fully capture:
 >
-> - the user requirements in @specs/user,
-> - the system behavior in @specs/dev, and
-> - the integration/system test cases in @specs/test.
+> - the external behavior users rely on,
+> - the internal system behavior, and
+> - the integration/system test cases.
 >
 > The spec items should be the *minimal* set needed to reimplement code without the IR.
 > The set should be complete and coherent.
@@ -58,15 +58,17 @@ For each finding in a review round, Coder either addresses it with changes or ch
 Any code change to address findings starts a new round of review, even if some findings are also rebutted.
 Rounds continue until Reviewer raises no findings.
 
+Spec item files are the files under @specs/ that hold spec items — @specs/packages/ and @specs/compositions/ in the current layout, or @specs/user/, @specs/dev/, and @specs/test/ in the legacy one; decision and intent records (iteration records in older scaffolds), @specs/map.md, and @specs/meta.md are not spec item files.
+
 ### CODE-5
 
-When Committer commits Initial Changes from a Boss coding intent involving changes only in @specs/user/, @specs/dev/, or @specs/test/, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
+When Committer commits Initial Changes from a Boss coding intent involving changes only in spec item files, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
 > Review the latest commit.
 > Refer to the commit message.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -78,7 +80,7 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 
 ### CODE-6
 
-When Committer commits Initial Changes from a Boss coding intent involving changes only outside @specs/user/, @specs/dev/, and @specs/test/, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
+When Committer commits Initial Changes from a Boss coding intent involving changes only outside spec item files, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
 > Review the latest commit.
 > Refer to the commit message.
 > Flag any issues or improvements (numbered; no duplication).
@@ -90,7 +92,7 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 
 ### CODE-7
 
-When Committer commits Initial Changes from a Boss coding intent involving changes both in and outside @specs/user/, @specs/dev/, and @specs/test/, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
+When Committer commits Initial Changes from a Boss coding intent involving changes both in and outside spec item files, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
 > Review the latest commit.
 > Refer to the commit message.
 > Flag any issues or improvements (numbered; no duplication).
@@ -98,7 +100,7 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -110,13 +112,13 @@ When Committer commits Initial Changes from a Boss coding intent involving chang
 
 ### CODE-8
 
-When Committer commits Initial Changes from an IR task involving changes only in @specs/user/, @specs/dev/, or @specs/test/, Captain shall relay the IR's task description to Reviewer along with the following prompt:
+When Committer commits Initial Changes from an IR task involving changes only in spec item files, Captain shall relay the IR's task description to Reviewer along with the following prompt:
 > Review the latest commit.
 > Refer to the commit message.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -128,7 +130,7 @@ When Committer commits Initial Changes from an IR task involving changes only in
 
 ### CODE-9
 
-When Committer commits Initial Changes from an IR task involving changes only outside @specs/user/, @specs/dev/, and @specs/test/, Captain shall relay the IR's task description to Reviewer along with the following prompt:
+When Committer commits Initial Changes from an IR task involving changes only outside spec item files, Captain shall relay the IR's task description to Reviewer along with the following prompt:
 > Review the latest commit.
 > Refer to the commit message.
 > Flag any issues or improvements (numbered; no duplication).
@@ -140,7 +142,7 @@ When Committer commits Initial Changes from an IR task involving changes only ou
 
 ### CODE-10
 
-When Committer commits Initial Changes from an IR task involving changes both in and outside @specs/user/, @specs/dev/, and @specs/test/, Captain shall relay the IR's task description to Reviewer along with the following prompt:
+When Committer commits Initial Changes from an IR task involving changes both in and outside spec item files, Captain shall relay the IR's task description to Reviewer along with the following prompt:
 > Review the latest commit.
 > Refer to the commit message.
 > Flag any issues or improvements (numbered; no duplication).
@@ -148,7 +150,7 @@ When Committer commits Initial Changes from an IR task involving changes both in
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -160,13 +162,13 @@ When Committer commits Initial Changes from an IR task involving changes both in
 
 ### CODE-11
 
-When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only in @specs/user/, @specs/dev/, or @specs/test/ without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
+When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only in spec item files without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
 > Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -178,7 +180,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 
 ### CODE-12
 
-When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside @specs/user/, @specs/dev/, and @specs/test/ without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
+When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside spec item files without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
 > Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
@@ -190,7 +192,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 
 ### CODE-13
 
-When Coder makes unreviewed changes (outside of any Initial Changes) involving changes both in and outside @specs/user/, @specs/dev/, and @specs/test/ without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
+When Coder makes unreviewed changes (outside of any Initial Changes) involving changes both in and outside spec item files without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
 > Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
@@ -198,7 +200,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -216,13 +218,13 @@ When Coder raises rebuttals without making code changes, Captain shall relay the
 
 ### CODE-15
 
-When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only in @specs/user/, @specs/dev/, or @specs/test/ and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
+When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only in spec item files and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
 > Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -235,7 +237,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 
 ### CODE-16
 
-When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside @specs/user/, @specs/dev/, and @specs/test/ and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
+When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside spec item files and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
 > Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
@@ -248,7 +250,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 
 ### CODE-17
 
-When Coder makes unreviewed changes (outside of any Initial Changes) involving changes both in and outside @specs/user/, @specs/dev/, and @specs/test/ and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
+When Coder makes unreviewed changes (outside of any Initial Changes) involving changes both in and outside spec item files and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
 > Review the unstaged and untracked changes in the context of the staged changes.
 > Understand the intent.
 > Flag any issues or improvements (numbered; no duplication).
@@ -256,7 +258,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
 > - Minimal: essential and concise; every item earns its place; also check with other items.
 > - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
 >
@@ -272,7 +274,8 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 ### CODE-18
 
 When Coder makes any Initial Changes and Reviewer has not played since the last commit, Captain shall prompt Committer:
-> Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
+> Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
+> If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
 > Write the commit message concisely.
 > Coder is <coder-llm>.
 > Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
@@ -282,7 +285,8 @@ Result guard: `needsBossInput` — Committing requires additional Boss input or
 ### CODE-19
 
 When Coder makes any Initial Changes and Reviewer has played since the last commit, or Reviewer raises no findings on uncommitted changes and Coder has played since the last commit, Captain shall prompt Committer:
-> Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
+> Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
+> If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
 > Write the commit message concisely.
 > Coder is <coder-llm>; Reviewer is <reviewer-llm>.
 > Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).

package/reference/sdlc/code.playbook/code.playbook.js

@@ -189,6 +189,10 @@ function extractRequiredFields(description) {
 }
 function buildJudgePrompt(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('');
     lines.push(`The ${input.player} just produced this output:`);
     lines.push('');
     lines.push('```');

package/reference/sdlc/code.playbook/code.playbook.ts

@@ -290,6 +290,12 @@ function extractRequiredFields(description: string): string[] {
 
 function buildJudgePrompt(input: PlayerInput, finalText: string): string {
   const lines: string[] = [];
+  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('');
   lines.push(`The ${input.player} just produced this output:`);
   lines.push('');
   lines.push('```');

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -2,7 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
-import { registerPlaybookAbortCleanup } from '../../../src/xstate-runtime.js';
+import { hiddenControlEnvelope, registerPlaybookAbortCleanup, } from '../../../src/xstate-runtime.js';
 import createDefaultCaptainRuntime from '../captain.playbook/captain.playbook.js';
 class VisibilityControlError extends Error {
     constructor(cause) {
@@ -27,6 +27,47 @@ function visibleChatEnvelope(message) {
         message,
     ].join('\n\n');
 }
+// DR-013 A1: adapters with no provider-enforced tool-restriction surface.
+// Cligent's Codex adapter rejects any `allowedTools` value — including the
+// empty list that expresses tool-free — because the supported Codex SDK
+// cannot enforce one, so requesting it fails every control call before the
+// model is reached. Omitting the option is the only way such an adapter can
+// run a control call at all; its isolation then rests on the authored
+// hidden-judge envelope below rather than on provider enforcement.
+const ADAPTERS_WITHOUT_TOOL_ENFORCEMENT = new Set([
+    'codex',
+]);
+// The tool half of a control call's options. An empty allowlist means "no
+// tools available" and is distinct from omission, which grants the adapter's
+// full native tool surface — so omit only where the empty list would be
+// refused, and keep requesting enforcement whenever the adapter is unknown.
+function controlCallToolOptions(captainAdapter) {
+    if (captainAdapter !== undefined &&
+        ADAPTERS_WITHOUT_TOOL_ENFORCEMENT.has(captainAdapter)) {
+        return {};
+    }
+    return { allowedTools: [] };
+}
+// A runtime-requested allowlist forwarded to the captain agent. The empty
+// list is the runtime's way of saying "tool-free", so it is the only value
+// the host substitutes; a non-empty list is a real restriction and stays
+// fail-closed on an adapter that cannot enforce it.
+function forwardedToolOptions(requested, captainAdapter) {
+    if (requested === undefined)
+        return {};
+    if (requested.length === 0)
+        return controlCallToolOptions(captainAdapter);
+    return { allowedTools: requested };
+}
+function readCaptainAdapter(options) {
+    if (typeof options !== 'object' || options === null)
+        return undefined;
+    const adapter = options.captainAdapter;
+    return typeof adapter === 'string' && adapter.length > 0
+        ? adapter
+        : undefined;
+}
+const hiddenJudgeEnvelope = hiddenControlEnvelope;
 function visibleTurnSummaryEnvelope(input) {
     return [
         'You are the Playbook Captain shell.',
@@ -176,6 +217,10 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const loadModule = deps.loadModule ?? ((specifier) => import(specifier));
     const createSessionId = deps.createSessionId ?? randomUUID;
     const createCaptainRuntime = deps.createCaptainRuntime ?? createDefaultCaptainRuntime;
+    // DR-013 A1: the launcher passes the resolved captain adapter through
+    // `captain.options`; a raw `--config` launch leaves it undefined, which
+    // keeps the enforced empty allowlist and its fail-closed behavior.
+    const captainAdapter = readCaptainAdapter(options);
     let entries = [];
     let byCommand = new Map();
     let byId = new Map();
@@ -382,9 +427,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             const result = await callCaptainQueued(frame, activeContext, prompt, {
                 visibility: options.visibility,
                 resume: options.resume,
-                ...(options.allowedTools === undefined
-                    ? {}
-                    : { allowedTools: options.allowedTools }),
+                ...forwardedToolOptions(options.allowedTools, captainAdapter),
             }, signal);
             return {
                 status: result.status,
@@ -398,7 +441,11 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             if (!activeContext) {
                 throw new Error('callJudge invoked outside a Boss turn');
             }
-            const result = await callCaptainQueued(frame, activeContext, prompt, { visibility: 'hidden', resume: false, allowedTools: [] }, signal);
+            const result = await callCaptainQueued(frame, activeContext, hiddenJudgeEnvelope(prompt), {
+                visibility: 'hidden',
+                resume: false,
+                ...controlCallToolOptions(captainAdapter),
+            }, signal);
             if (result.status !== 'ok') {
                 throw new Error(result.error ?? `callCaptain status "${result.status}"`);
             }
@@ -1101,13 +1148,21 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         }
     };
     const callVisibleChat = async (frame, context, message) => {
-        const result = await callCaptainQueued(frame, context, visibleChatEnvelope(message), { visibility: 'visible', resume: false, allowedTools: [] }, context.signal);
+        const result = await callCaptainQueued(frame, context, visibleChatEnvelope(message), {
+            visibility: 'visible',
+            resume: false,
+            ...controlCallToolOptions(captainAdapter),
+        }, context.signal);
         if (result.status !== 'ok') {
             throw new Error(result.error ?? `callCaptain status "${result.status}"`);
         }
     };
     const callVisibleTurnSummary = async (frame, context, input) => {
-        const result = await callCaptainQueued(frame, context, visibleTurnSummaryEnvelope(input), { visibility: 'visible', resume: false, allowedTools: [] }, context.signal);
+        const result = await callCaptainQueued(frame, context, visibleTurnSummaryEnvelope(input), {
+            visibility: 'visible',
+            resume: false,
+            ...controlCallToolOptions(captainAdapter),
+        }, context.signal);
         if (result.status !== 'ok') {
             throw new Error(result.error ?? `callCaptain status "${result.status}"`);
         }
@@ -1151,7 +1206,11 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         }
         let decision;
         try {
-            const result = await callCaptainQueued(leaf, context, hiddenLifecycleEnvelope(turn.prompt), { visibility: 'hidden', resume: false, allowedTools: [] }, context.signal);
+            const result = await callCaptainQueued(leaf, context, hiddenLifecycleEnvelope(turn.prompt), {
+                visibility: 'hidden',
+                resume: false,
+                ...controlCallToolOptions(captainAdapter),
+            }, context.signal);
             if (result.status === 'ok' && result.finalText !== undefined) {
                 decision = parseLifecycleDecision(result.finalText);
             }