@sublang/playbook 0.5.0 → 0.6.0

package/README.md

@@ -36,7 +36,8 @@ The reference is the canonical worked example —
 [CODE source](reference/sdlc/code.md) →
 [gears](reference/sdlc/code.playbook/code.gears.md) →
 [FSM](reference/sdlc/code.playbook/code.fsm.ts) → runtime — with
-the runtime ported to cligent's `tmux-play` host out of the box.
+the runtime registered behind the built-in Playbook Captain shell for
+cligent's `tmux-play` host out of the box.
 The compiled artifacts live under
 [`reference/sdlc/code.playbook/`](reference/sdlc/code.playbook),
 the slc pipeline's `<basename>.<pipeline>/` output directory.
@@ -100,9 +101,10 @@ passed through to `tmux-play` with a warning because `playbook-code`
 does not know how to preflight their auth. The safe tuning points are
 `captain.adapter`, `captain.model`, and each role's `adapter` and
 `model` under `players.coder` / `players.reviewer`. The composer owns
-`captain.from` and the `coder` / `reviewer` role keys, so leave those
-keys as-is; the runtime binds to those host-configuration invariants
-per [PBRT-4](specs/user/playbook-runtime.md#pbrt-4) and derives the
+`captain.from` and points it at the Playbook Captain shell adapter, and
+it owns the `coder` / `reviewer` role keys, so leave those keys as-is;
+the runtime binds to those host-configuration invariants per
+[PBRT-4](specs/user/playbook-runtime.md#pbrt-4) and derives the
 `<coder-llm>` / `<reviewer-llm>` substitution strings from each role's
 `model` when pinned and `adapter` otherwise — so the Committer's
 commit-message trailers can name the concrete model
@@ -186,7 +188,7 @@ production install.
 
 Drive a Boss turn against the source tree (uses the developer
 [`tmux-play.config.yaml`](reference/sdlc/code.playbook/tmux-play.config.yaml)
-that imports the compiled adapter via relative path):
+that imports the compiled Playbook Captain shell via relative path):
 
 ```sh
 pnpm exec tmux-play --config reference/sdlc/code.playbook/tmux-play.config.yaml
@@ -198,7 +200,9 @@ installed globally.
 
 ### Running a Boss turn
 
-The Boss pane takes plain-language turns; the judge classifies each
+The Boss pane starts at the Playbook Captain shell. Use `/code <task>`
+to explicitly select the CODE playbook, or use ordinary text and let the
+shell route it. Once a turn reaches CODE, the CODE judge classifies it
 into an FSM event (start a coding turn, continue or summarize an IR,
 interrupt to a named state, or nothing) per
 [PBRT-1](specs/user/playbook-runtime.md#pbrt-1).
@@ -207,9 +211,16 @@ the FSM parks at `awaitBossReply` and the pane shows the question; your
 next turn is normally classified as the reply, or a fresh directive
 abandons it ([PBRT-2](specs/user/playbook-runtime.md#pbrt-2)).
 
-The Captain pane streams the state machine with a four-glyph vocabulary —
-`◆ ▸ ⮕ ⤷` per [PBRT-3](specs/user/playbook-runtime.md#pbrt-3) — while
-player prompts ride their own panes.
+The Captain pane shows `/code` start/stop/finished status with `◇` lines
+and streams the CODE state machine with the four-glyph vocabulary `◆ ▸ ⮕ ⤷` per
+[PBRT-3](specs/user/playbook-runtime.md#pbrt-3), while player prompts
+ride their own panes.
+
+Published configs should import the shell adapter from
+`@sublang/playbook/playbook-captain`. Existing explicit configs that
+still import `@sublang/playbook/code/tmux-play` keep resolving through
+a compatibility shim that delegates to the same shell with CODE
+registered.
 
 ### Embedding the runtime in your own host
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and tmux-play adapter for a coder/reviewer/committer loop driven by GEARS spec items.",
+  "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and Playbook Captain shell for a coder/reviewer/committer loop driven by GEARS spec items.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -34,6 +34,12 @@
     "reference/sdlc/code.playbook/code.playbook.ts",
     "reference/sdlc/code.playbook/code.playbook.js",
     "reference/sdlc/code.playbook/code.playbook.d.ts",
+    "reference/sdlc/code.playbook/code.registry.ts",
+    "reference/sdlc/code.playbook/code.registry.js",
+    "reference/sdlc/code.playbook/code.registry.d.ts",
+    "reference/sdlc/code.playbook/playbook-captain.ts",
+    "reference/sdlc/code.playbook/playbook-captain.js",
+    "reference/sdlc/code.playbook/playbook-captain.d.ts",
     "reference/sdlc/code.playbook/code.tmux-play.ts",
     "reference/sdlc/code.playbook/code.tmux-play.js",
     "reference/sdlc/code.playbook/code.tmux-play.d.ts",
@@ -51,6 +57,10 @@
       "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
       "default": "./reference/sdlc/code.playbook/code.playbook.js"
     },
+    "./playbook-captain": {
+      "types": "./reference/sdlc/code.playbook/playbook-captain.d.ts",
+      "default": "./reference/sdlc/code.playbook/playbook-captain.js"
+    },
     "./code/tmux-play": {
       "types": "./reference/sdlc/code.playbook/code.tmux-play.d.ts",
       "default": "./reference/sdlc/code.playbook/code.tmux-play.js"
@@ -67,7 +77,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
-    "@openai/codex-sdk": "^0.130.0",
+    "@openai/codex-sdk": "^0.139.0",
     "@sublang/cligent": "latest",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"

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

@@ -21,17 +21,30 @@ import {
   findTmuxPlayConfig,
   loadTmuxPlayConfig,
 } from '@sublang/cligent/tmux-play';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import {
+  parse as parseYaml,
+  parseDocument as parseYamlDocument,
+  stringify as stringifyYaml,
+} from 'yaml';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const templatePath = resolve(here, '..', 'playbook-code.config.template.yaml');
 const READINESS_FAILURE_EXIT_CODE = 2;
 const COMPOSITION_FAILURE_EXIT_CODE = 1;
-
-// PBCODE-16: the composer injects `captain.from` (the CODE adapter
-// module) and the `coder` / `reviewer` player ids, so the user-edited
-// overlay carries neither.
-export const CODE_ADAPTER_MODULE = '@sublang/playbook/code/tmux-play';
+const DEFAULT_NOTIFICATION_BLOCK = [
+  '',
+  '# tmux-play host notifications. Omitted turn_aborted resolves to off.',
+  'notifications:',
+  '  player_finished: bell',
+  '  turn_finished: desktop',
+  '',
+].join('\n');
+
+// PBCODE-16: the composer injects `captain.from` (the Playbook
+// Captain shell adapter module) and the `coder` / `reviewer` player
+// ids, so the user-edited overlay carries neither.
+export const PLAYBOOK_CAPTAIN_MODULE = '@sublang/playbook/playbook-captain';
+export const CODE_ADAPTER_MODULE = PLAYBOOK_CAPTAIN_MODULE;
 const CODE_ROLES = ['coder', 'reviewer'];
 // Accepted `players` keys: the two fixed CODE roles plus the optional
 // `committer` alias (a string naming one of the roles); PBCODE-17.
@@ -66,6 +79,7 @@ export async function runPlaybookCodeCli(options = {}) {
   }
 
   seedUserConfigIfMissing(userConfigPath, stderr);
+  migrateUserConfigNotificationsIfMissing(userConfigPath, stderr);
 
   // PBCODE-16/17: compose the launched config from the overlay plus an
   // optional base tmux-play config. Composition failures (missing role,
@@ -139,17 +153,6 @@ async function composeLaunchConfig({ overlayPath, cwd, configHome }) {
   let base;
   if (basePath) {
     base = (await loadTmuxPlayConfig({ configPath: basePath })).config;
-    // cligent's loader normalizes a discovered base to captain / players
-    // / theme and drops host fields it does not model yet — notably
-    // `layout`. Recover a base `layout` from the raw base YAML so base
-    // inheritance (PBCODE-16/17) holds; the `=== undefined` guard makes
-    // this inert once a future loader preserves `layout` itself.
-    if (base && base.layout === undefined) {
-      const rawBase = parseYaml(readFileSync(basePath, 'utf8'));
-      if (isObject(rawBase) && rawBase.layout !== undefined) {
-        base.layout = rawBase.layout;
-      }
-    }
   }
   return composeRuntimeConfig(overlay, base);
 }
@@ -163,7 +166,7 @@ async function composeLaunchConfig({ overlayPath, cwd, configHome }) {
 export function composeRuntimeConfig(
   overlay,
   base,
-  adapterModule = CODE_ADAPTER_MODULE,
+  adapterModule = PLAYBOOK_CAPTAIN_MODULE,
 ) {
   const overlayConfig = requireObject(overlay, 'config');
   const overlayPlayers = requireObject(overlayConfig.players, 'players');
@@ -256,13 +259,15 @@ export function composeRuntimeConfig(
     captain.options = { code };
   }
 
-  // Inherit `theme` and `layout` from the base when the overlay omits
-  // them; never the base `players[]` roster.
+  // Inherit host-owned top-level fields from the base when the overlay
+  // omits them; never the base `players[]` roster.
   const composed = {};
   const theme = overlayConfig.theme ?? base?.theme;
   if (theme !== undefined) composed.theme = theme;
   const layout = overlayConfig.layout ?? base?.layout;
   if (layout !== undefined) composed.layout = layout;
+  const notifications = overlayConfig.notifications ?? base?.notifications;
+  if (notifications !== undefined) composed.notifications = notifications;
   composed.captain = captain;
   composed.players = players;
   return composed;
@@ -317,6 +322,27 @@ function seedUserConfigIfMissing(userConfigPath, stderr) {
   stderr.write(`playbook-code: created config at ${userConfigPath}\n`);
 }
 
+function migrateUserConfigNotificationsIfMissing(userConfigPath, stderr) {
+  const source = readFileSync(userConfigPath, 'utf8');
+  let parsed;
+  try {
+    const document = parseYamlDocument(source);
+    if (document.errors.length > 0) return;
+    parsed = document.contents === null ? {} : document.toJS();
+  } catch {
+    return;
+  }
+  if (!isObject(parsed) || hasOwn(parsed, 'notifications')) return;
+  const separator = source.endsWith('\n') ? '' : '\n';
+  writeFileSync(
+    userConfigPath,
+    `${source}${separator}${DEFAULT_NOTIFICATION_BLOCK}`,
+  );
+  stderr.write(
+    `playbook-code: added notifications defaults to config at ${userConfigPath}\n`,
+  );
+}
+
 function hasExplicitConfig(argv) {
   return argv.some((arg) => arg === '--config' || arg.startsWith('--config='));
 }
@@ -393,6 +419,10 @@ function isObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
 function requireObject(value, path) {
   if (!isObject(value)) {
     throw new Error(`${path} must be an object`);

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

@@ -498,8 +498,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -581,8 +582,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',
@@ -628,8 +630,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -713,8 +716,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',
@@ -758,8 +762,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -843,8 +848,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',
@@ -892,8 +898,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -983,8 +990,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- 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.',
                         '- 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.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',

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

@@ -712,8 +712,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -801,8 +802,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'Flag any issues or improvements (numbered; no duplication).',
@@ -851,8 +853,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -942,8 +945,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'Flag any issues or improvements (numbered; no duplication).',
@@ -990,8 +994,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -1081,8 +1086,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'Flag any issues or improvements (numbered; no duplication).',
@@ -1133,8 +1139,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
@@ -1232,8 +1239,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+            '- 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.',
             '- 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.',
             '',
             'Flag anything missing, redundant, over-specified, or under-specified.',
             'Flag any issues or improvements (numbered; no duplication).',

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

@@ -65,8 +65,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
@@ -94,8 +95,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).
@@ -113,8 +115,9 @@ When Committer commits Initial Changes from an IR task involving changes only in
 > Verify any affected spec items are:
 >
 > - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: user requirements (in @specs/user) or behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
@@ -142,8 +145,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).
@@ -161,8 +165,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
@@ -190,8 +195,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).
@@ -215,8 +221,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
@@ -246,8 +253,9 @@ 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 behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.
+> - 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.
 > - 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.
 >
 > Flag anything missing, redundant, over-specified, or under-specified.
 > Flag any issues or improvements (numbered; no duplication).

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

@@ -0,0 +1,43 @@
+import { type CodePlaybookOptions, type PlaybookRuntime } from './code.playbook.js';
+export declare const codeCopyPasteGuardNames: readonly ["accepted", "approved", "challengeAccepted", "challengeRejected", "challengesRaised", "changesMadeCode", "changesMadeCodeAndChallenged", "changesMadeMixed", "changesMadeMixedAndChallenged", "changesMadeSpecs", "changesMadeSpecsAndChallenged", "hasFindings", "needsRevision", "noFindings", "noOpenItems"];
+export declare const codeStateCountLabels: {
+    readonly adjudicateChallenges: "rebuttal";
+    readonly reviewBossCommitSpecs: "review round";
+    readonly reviewBossCommitCode: "review round";
+    readonly reviewBossCommitMixed: "review round";
+    readonly reviewIrTaskCommitSpecs: "review round";
+    readonly reviewIrTaskCommitCode: "review round";
+    readonly reviewIrTaskCommitMixed: "review round";
+    readonly reviewChangesSpecs: "review round";
+    readonly reviewChangesCode: "review round";
+    readonly reviewChangesMixed: "review round";
+    readonly reviewChangesAndChallengesSpecs: "review round";
+    readonly reviewChangesAndChallengesCode: "review round";
+    readonly reviewChangesAndChallengesMixed: "review round";
+};
+export interface CodeOptions {
+    committer?: 'coder' | 'reviewer';
+}
+export interface RegistryPlayer {
+    id: string;
+    adapter?: string;
+    model?: string;
+}
+export interface CreateCodeRuntimeOptions {
+    captainOptions: unknown;
+    players: readonly RegistryPlayer[];
+}
+export interface CodePlaybookRegistryEntry {
+    id: 'code';
+    command: 'code';
+    intent: string;
+    idleStateId: 'ready';
+    finalStateId: 'done';
+    copyPasteGuardNames: readonly string[];
+    stateCountLabels: typeof codeStateCountLabels;
+    validateOptions(captainOptions: unknown): CodeOptions;
+    createRuntime(options: CreateCodeRuntimeOptions): PlaybookRuntime;
+}
+export declare function validateCodeOptions(captainOptions: unknown): CodeOptions;
+export declare function createCodeRuntimeOptions({ captainOptions, players, }: CreateCodeRuntimeOptions): CodePlaybookOptions;
+export declare const codePlaybookRegistryEntry: CodePlaybookRegistryEntry;