@sublang/playbook 1.3.0 → 3.0.0

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

@@ -20,7 +20,10 @@ import type {
   PlaybookRuntime,
   PlaybookState,
 } from '@sublang/playbook/runtime';
-import { registerPlaybookAbortCleanup } from '../../../src/xstate-runtime.js';
+import {
+  hiddenControlEnvelope,
+  registerPlaybookAbortCleanup,
+} from '../../../src/xstate-runtime.js';
 import createDefaultCaptainRuntime from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy, RegistryPlayer } from './code.registry.js';
 
@@ -154,6 +157,56 @@ function visibleChatEnvelope(message: string): string {
   ].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: ReadonlySet<string> = 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: string | undefined,
+): { allowedTools?: readonly string[] } {
+  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: readonly string[] | undefined,
+  captainAdapter: string | undefined,
+): { allowedTools?: readonly string[] } {
+  if (requested === undefined) return {};
+  if (requested.length === 0) return controlCallToolOptions(captainAdapter);
+  return { allowedTools: requested };
+}
+
+function readCaptainAdapter(options: unknown): string | undefined {
+  if (typeof options !== 'object' || options === null) return undefined;
+  const adapter = (options as Record<string, unknown>).captainAdapter;
+  return typeof adapter === 'string' && adapter.length > 0
+    ? adapter
+    : undefined;
+}
+
+const hiddenJudgeEnvelope = hiddenControlEnvelope;
+
 function visibleTurnSummaryEnvelope(input: {
   playbookId: string;
   submittedText: string;
@@ -368,6 +421,10 @@ export function createPlaybookCaptainShell(
   const createCaptainRuntime: NonNullable<
     PlaybookCaptainDeps['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: readonly PlaybookCaptainRegistryEntry[] = [];
   let byCommand = new Map<string, PlaybookCaptainRegistryEntry>();
   let byId = new Map<string, PlaybookCaptainRegistryEntry>();
@@ -650,9 +707,7 @@ export function createPlaybookCaptainShell(
         {
           visibility: options.visibility,
           resume: options.resume,
-          ...(options.allowedTools === undefined
-            ? {}
-            : { allowedTools: options.allowedTools }),
+          ...forwardedToolOptions(options.allowedTools, captainAdapter),
         },
         signal,
       );
@@ -671,8 +726,12 @@ export function createPlaybookCaptainShell(
       const result = await callCaptainQueued(
         frame,
         activeContext,
-        prompt,
-        { visibility: 'hidden', resume: false, allowedTools: [] },
+        hiddenJudgeEnvelope(prompt),
+        {
+          visibility: 'hidden',
+          resume: false,
+          ...controlCallToolOptions(captainAdapter),
+        },
         signal,
       );
       if (result.status !== 'ok') {
@@ -1495,7 +1554,11 @@ export function createPlaybookCaptainShell(
       frame,
       context,
       visibleChatEnvelope(message),
-      { visibility: 'visible', resume: false, allowedTools: [] },
+      {
+        visibility: 'visible',
+        resume: false,
+        ...controlCallToolOptions(captainAdapter),
+      },
       context.signal,
     );
     if (result.status !== 'ok') {
@@ -1519,7 +1582,11 @@ export function createPlaybookCaptainShell(
       frame,
       context,
       visibleTurnSummaryEnvelope(input),
-      { visibility: 'visible', resume: false, allowedTools: [] },
+      {
+        visibility: 'visible',
+        resume: false,
+        ...controlCallToolOptions(captainAdapter),
+      },
       context.signal,
     );
     if (result.status !== 'ok') {
@@ -1577,7 +1644,11 @@ export function createPlaybookCaptainShell(
         leaf,
         context,
         hiddenLifecycleEnvelope(turn.prompt),
-        { visibility: 'hidden', resume: false, allowedTools: [] },
+        {
+          visibility: 'hidden',
+          resume: false,
+          ...controlCallToolOptions(captainAdapter),
+        },
         context.signal,
       );
       if (result.status === 'ok' && result.finalText !== undefined) {

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -6,39 +6,25 @@
 # The launcher injects captain.from and the namespaced <id>-<role> host
 # players, then launches cligent's tmux-play under the Playbook Captain shell.
 
-# Reusable agent settings. A profile id must not be an adapter shorthand
-# (claude, codex). Reference a profile by id from captain / players below.
-# Profile ids name the underlying agent/model (e.g. claude-opus,
-# codex-gpt) so they read distinctly from the captain / coder / reviewer
-# player roles that reference them.
+# Every agent — the Captain and each playbook role — carries its own
+# settings inline: an adapter shorthand (claude, codex) or a block with
+# adapter/model/effort/permissions. Retuning one agent never changes
+# another.
 # Every seeded agent runs in cligent's protected auto mode
 # (permissions.mode: auto): claude maps it to permissionMode auto, codex to
 # on-request + auto_review. Codex roles also grant writablePaths: ['.git']
 # so commit turns can write git metadata under the codex sandbox.
-profiles:
-  claude-opus:
-    adapter: claude
-    model: claude-opus-4-8
-    reasoningEffort: high
-    permissions:
-      mode: auto
-  claude-opus-1m:
-    adapter: claude
-    model: claude-opus-4-8[1m]
-    reasoningEffort: xhigh
-    permissions:
-      mode: auto
-  codex-gpt:
-    adapter: codex
-    model: gpt-5.5
-    reasoningEffort: xhigh
-    permissions:
-      mode: auto
-      writablePaths: ['.git']
 
-# The Captain/Judge agent: a profile id, an adapter shorthand, or a full
-# tmux-play agent block (which may carry a `profile:` key).
-captain: claude-opus
+# The Captain/Judge agent.
+# Captain routing/adjudication calls run tool-free. Claude enforces that at
+# the provider level; the codex adapter cannot enforce a tool list, so a
+# codex captain degrades to a prompt-level restriction (DR-013 A1).
+captain:
+  adapter: claude
+  model: claude-opus-4-8
+  effort: high
+  permissions:
+    mode: auto
 
 # Host notifications. Omitting turn_aborted resolves it to off.
 notifications:
@@ -53,8 +39,19 @@ playbooks:
   code:
     from: "@sublang/playbook/code/registry"
     players:
-      coder: claude-opus-1m
-      reviewer: codex-gpt
+      coder:
+        adapter: claude
+        model: claude-opus-4-8[1m]
+        effort: xhigh
+        permissions:
+          mode: auto
+      reviewer:
+        adapter: codex
+        model: gpt-5.5
+        effort: xhigh
+        permissions:
+          mode: auto
+          writablePaths: ['.git']
     committer: coder
 
 # The DISCUSS playbook: two agents converge on spec items or decision
@@ -63,8 +60,17 @@ playbooks:
 #  discuss:
 #    from: "@sublang/playbook/discuss/registry"
 #    players:
-#      host: claude-opus
-#      participant: codex-gpt
+#      host:
+#        adapter: claude
+#        model: claude-opus-4-8
+#        permissions:
+#          mode: auto
+#      participant:
+#        adapter: codex
+#        model: gpt-5.5
+#        permissions:
+#          mode: auto
+#          writablePaths: ['.git']
 #    committer: host
 
 # Non-interactive `playbook run` defaults (optional). Each value is an

package/reference/sdlc/discuss.md

@@ -0,0 +1,93 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Discuss
+
+Players:
+
+- Host
+- Participant
+- Committer = Host | Participant
+
+When Boss gives a topic, Captain shall relay it to both players concurrently and independently, without waiting for either proposal before asking the other, along with the following prompt:
+
+> Assess whether Boss's topic above is better expressed as a few spec items (per @specs/meta.md) or requires one or more DRs added to @specs/decisions/.
+> Consult @specs/map.md, if necessary, to find relevant context.
+> Each DR should be coherent and focused.
+> Propose your design in reply.
+> DRs, if any, need not include full detail here — describe the key points at a high level.
+> Don't change any code.
+
+The initial discussion shall go round by round.
+In each round, Captain shall prompt both players concurrently.
+Both players each shall make a new proposal using only the completed proposals from the previous round; neither shall see the other's current-round result before replying.
+Captain shall join both results before beginning the next round, using the following prompt:
+
+> Consider the other agent's proposal below.
+> (1) If there are essentially different points (including creation or division of DRs), list them, accept any reasonable ones, and challenge the rest with strong reasoning, solid evidence, and comprehensive thinking — make your argument.
+> (2) Only if your proposal of the previous round is equivalent to the other's, with nothing to reconcile, state the end of initial discussion.
+> Don't change any code.
+
+A Boss interrupt into parallel discussion shall restart the whole initial-proposal or reconciliation round so both independent branches receive one coherent prior-round input. An individual branch that asks Boss a question may still resume on its own; branch working states are not Boss-interrupt destinations.
+
+When both players state the end of initial discussion, Captain shall ask Host to write spec items or DRs according to the agreement, along with the following prompt:
+
+> Update @specs/map.md to reflect your changes (if any) when done.
+
+When Committer commits at the end of the initial discussion, or when Host addresses findings with changes, Captain shall ask Participant to review the spec changes in a round, without waiting for Boss.
+In the first step of each round, Participant shall review the latest changes, address any rebuttals, and raise any findings.
+In the second step of each round, Host shall address any findings.
+Rounds continue until Participant 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.
+
+While any new or updated spec item (in spec item files) is under review, Captain shall include the following prompt for Participant:
+
+> Verify any new or updated spec items are:
+>
+> - Complete & coherent: sufficient for you to reimplement code.
+> - 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.
+>
+> Flag anything missing, redundant, over-specified, or under-specified.
+
+While any new or updated DR is under review, Captain shall include the following prompt for Participant:
+
+> Review any new/updated decision following @specs/meta.md (reread if necessary).
+> Flag any issues or propose any design suggestions (numbered; no duplication), with strong reasoning and evidence.
+> Key statements must be backed by references unless they are common sense or widely acknowledged best practices.
+>
+> If the decision is well-thought-out and well-written, don't raise nitpicks.
+> Remember to keep the DR simple and minimal.
+
+When Participant begins any review, Captain shall include the following prompt:
+
+> Think thoroughly — don't just approve or reject.
+> For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
+> If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
+
+When Participant raises any findings, Captain shall relay them to Host along with the following prompt:
+
+> For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
+> Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.
+
+When Host raises any rebuttals, Captain shall relay them to Participant along with the following prompt:
+
+> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
+
+When the spec items or DRs are written at the end of the initial discussion, or Participant raises no findings on uncommitted changes, Captain shall ask Committer to commit with the following prompt:
+
+> Then 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.
+> Host is \<host-llm\>.
+> Participant is \<participant-llm\>.
+
+`<*-llm>` shall be the conventional human form of the substituted ID (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
+
+For the initial-discussion commit outcome, any adjudicated `reviewScope`
+payload shall be exactly `specItems`, `decisionRecords`, or `mixed`; a prose
+summary is not a review scope.

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

@@ -51,7 +51,7 @@ const DISCUSS_6_PROMPT = [
     'Review the latest spec changes, address any rebuttals, and raise any findings.',
     'Verify any new or updated 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.',
     'Flag anything missing, redundant, over-specified, or under-specified.',
@@ -84,7 +84,7 @@ const DISCUSS_10_PROMPT = [
     'Review the latest spec changes, address any rebuttals, and raise any findings.',
     'Verify any new or updated 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.',
     'Flag anything missing, redundant, over-specified, or under-specified.',
@@ -110,7 +110,8 @@ const DISCUSS_13_PROMPT = [
     'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
 ].join('\n');
 const DISCUSS_14_PROMPT = [
-    'Then make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
+    'Then 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.',
     'Host is <host-llm>.',
     'Participant is <participant-llm>.',
@@ -1250,7 +1251,7 @@ export const discussMachine = setup({
                     sourceItem: 'DISCUSS-14',
                     prompt: DISCUSS_14_PROMPT,
                     result: withNeedsBossReply({
-                        committed: 'Committer made the initial-discussion commit. Output may include `latestChanges` and `reviewScope`.',
+                        committed: 'Committer made the initial-discussion commit. Output may include `latestChanges: <summary>` and `reviewScope: "specItems" | "decisionRecords" | "mixed"`.',
                     }),
                     latestChanges: context.latestChanges,
                     reviewScope: context.reviewScope,

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

@@ -220,7 +220,7 @@ const DISCUSS_6_PROMPT = [
   'Review the latest spec changes, address any rebuttals, and raise any findings.',
   'Verify any new or updated 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.',
   'Flag anything missing, redundant, over-specified, or under-specified.',
@@ -257,7 +257,7 @@ const DISCUSS_10_PROMPT = [
   'Review the latest spec changes, address any rebuttals, and raise any findings.',
   'Verify any new or updated 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.',
   'Flag anything missing, redundant, over-specified, or under-specified.',
@@ -287,7 +287,8 @@ const DISCUSS_13_PROMPT = [
 ].join('\n');
 
 const DISCUSS_14_PROMPT = [
-  'Then make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
+  'Then 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.',
   'Host is <host-llm>.',
   'Participant is <participant-llm>.',
@@ -1611,7 +1612,7 @@ export const discussMachine = setup({
           prompt: DISCUSS_14_PROMPT,
           result: withNeedsBossReply({
             committed:
-              'Committer made the initial-discussion commit. Output may include `latestChanges` and `reviewScope`.',
+              'Committer made the initial-discussion commit. Output may include `latestChanges: <summary>` and `reviewScope: "specItems" | "decisionRecords" | "mixed"`.',
           }),
           latestChanges: context.latestChanges,
           reviewScope: context.reviewScope,

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

@@ -89,16 +89,18 @@ In the first step of each review round, Participant reviews the latest changes,
 In the second step of each review round, Host addresses any findings.
 Rounds continue until Participant 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.
+
 ### DISCUSS-6
 
-While new or updated spec items under @specs/user, @specs/dev, or @specs/test are under review and no new or updated DR is under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
+While new or updated spec items (in spec item files) are under review and no new or updated DR is under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
 
 > Latest changes: <changes>
 > Rebuttals to address, if any: <rebuttals>
 > Review the latest spec changes, address any rebuttals, and raise any findings.
 > Verify any new or updated 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.
 > Flag anything missing, redundant, over-specified, or under-specified.
@@ -110,14 +112,14 @@ While new or updated spec items under @specs/user, @specs/dev, or @specs/test ar
 
 ### DISCUSS-7
 
-While new or updated spec items under @specs/user, @specs/dev, or @specs/test are under review and no new or updated DR is under review, when Host addresses findings with changes, Captain shall prompt Participant:
+While new or updated spec items (in spec item files) are under review and no new or updated DR is under review, when Host addresses findings with changes, Captain shall prompt Participant:
 
 > Latest changes: <changes>
 > Rebuttals to address, if any: <rebuttals>
 > Review the latest spec changes, address any rebuttals, and raise any findings.
 > Verify any new or updated 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.
 > Flag anything missing, redundant, over-specified, or under-specified.
@@ -129,7 +131,7 @@ While new or updated spec items under @specs/user, @specs/dev, or @specs/test ar
 
 ### DISCUSS-8
 
-While new or updated DRs are under review and no new or updated spec item under @specs/user, @specs/dev, or @specs/test is under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
+While new or updated DRs are under review and no new or updated spec item (in spec item files) is under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
 
 > Latest changes: <changes>
 > Rebuttals to address, if any: <rebuttals>
@@ -147,7 +149,7 @@ While new or updated DRs are under review and no new or updated spec item under
 
 ### DISCUSS-9
 
-While new or updated DRs are under review and no new or updated spec item under @specs/user, @specs/dev, or @specs/test is under review, when Host addresses findings with changes, Captain shall prompt Participant:
+While new or updated DRs are under review and no new or updated spec item (in spec item files) is under review, when Host addresses findings with changes, Captain shall prompt Participant:
 
 > Latest changes: <changes>
 > Rebuttals to address, if any: <rebuttals>
@@ -165,14 +167,14 @@ While new or updated DRs are under review and no new or updated spec item under
 
 ### DISCUSS-10
 
-While new or updated spec items under @specs/user, @specs/dev, or @specs/test are under review and new or updated DRs are under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
+While new or updated spec items (in spec item files) are under review and new or updated DRs are under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
 
 > Latest changes: <changes>
 > Rebuttals to address, if any: <rebuttals>
 > Review the latest spec changes, address any rebuttals, and raise any findings.
 > Verify any new or updated 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.
 > Flag anything missing, redundant, over-specified, or under-specified.
@@ -189,14 +191,14 @@ While new or updated spec items under @specs/user, @specs/dev, or @specs/test ar
 
 ### DISCUSS-11
 
-While new or updated spec items under @specs/user, @specs/dev, or @specs/test are under review and new or updated DRs are under review, when Host addresses findings with changes, Captain shall prompt Participant:
+While new or updated spec items (in spec item files) are under review and new or updated DRs are under review, when Host addresses findings with changes, Captain shall prompt Participant:
 
 > Latest changes: <changes>
 > Rebuttals to address, if any: <rebuttals>
 > Review the latest spec changes, address any rebuttals, and raise any findings.
 > Verify any new or updated 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.
 > Flag anything missing, redundant, over-specified, or under-specified.
@@ -234,17 +236,22 @@ Model ID formatting examples: `claude-opus-4-7` becomes `Claude-Opus-4.7`; `gpt-
 
 When the spec items or DRs are written at the end of the initial discussion, Captain shall prompt Committer:
 
-> Then make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
+> Then 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.
 > Host is <host-llm>.
 > Participant is <participant-llm>.
 > Format the Host and Participant model IDs as conventional human forms.
 
+Results:
+- `committed`: Committer made the initial-discussion commit. Output may include `latestChanges: <summary>` and `reviewScope: "specItems" | "decisionRecords" | "mixed"`.
+
 ### DISCUSS-15
 
 When Participant raises no findings on uncommitted changes, Captain shall prompt Committer:
 
-> Then make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
+> Then 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.
 > Host is <host-llm>.
 > Participant is <participant-llm>.

package/reference/sdlc/discuss.playbook/discuss.playbook.js

@@ -458,6 +458,9 @@ function parseClassification(raw, pendingQuestionIds = []) {
 function buildAdjudicatorPrompt(input, playerOutput) {
     const lines = [];
     lines.push('You are the guard adjudicator for a playbook state machine.');
+    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 guard descriptions. Reply with exactly one JSON object and no prose.');
     lines.push(`The player "${input.player}" produced the output below for source item ${input.sourceItem}.`);
     lines.push('Choose exactly one guard whose description matches that output.');
     lines.push('');

package/reference/sdlc/discuss.playbook/discuss.playbook.ts

@@ -618,6 +618,11 @@ function buildAdjudicatorPrompt(
 ): string {
   const lines: string[] = [];
   lines.push('You are the guard adjudicator for a playbook state machine.');
+  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 guard descriptions. Reply with exactly one JSON object and no prose.',
+  );
   lines.push(
     `The player "${input.player}" produced the output below for source item ${input.sourceItem}.`,
   );

package/slc/link.md

@@ -257,15 +257,21 @@ array requests a tool-free call, while omission preserves the host Captain's
 configured tools.
 `CaptainResult` carries no resume token or player-continuation selection.
 A non-`ok`
-result, or an `ok` result without `finalText`, shall reject the actor through
-the FSM's error path.
-Outside a signal-driven abort, those invalid direct-Captain results are
-latched control-plane failures. The runtime shall let the actor take `onError`,
-drive it to quiescence, and drain ordered emissions before the public method
-rejects with the original failure. It shall never translate either case into
-a recoverable workflow `{ outcome: 'failed' }` result. If the combined signal
-has aborted, an aborted host result follows the ordinary abort settlement
-instead of being promoted to a control-plane failure.
+result, or an `ok` result without non-empty `finalText`, shall record that
+failure on the call's single finish trace and reject the actor through the
+FSM's error path. These structured host-result failures are recoverable
+workflow failures, not control-plane failures: the runtime shall let the actor
+take `onError`, drive it to quiescence, drain ordered emissions, and resolve
+the public method with `{ outcome: 'failed' }` carrying the failure state's
+error. This matches the delegated-player result boundary.
+A non-abort thrown `callCaptain` port, a malformed host result, and a rejecting
+trace sink remain control-plane failures that reject the public method. If the
+required finish sink rejects after a structured host-result failure, the
+actor's error and failure-state evidence shall remain the host-result failure,
+while the public method rejects with the sink failure surfaced by the turn's
+emission drain. Absent such a control-plane failure, if the combined signal
+has aborted, ordinary abort settlement remains authoritative after the actor
+reaches its error path.
 
 Every linked runtime owns a map from resolved player id to its latest non-empty `resumeToken`.
 Before reading a resolved direct-Captain or delegated-player result, the
@@ -716,9 +722,12 @@ Two default adjudication strategies, in selection order:
   lists the `result` keys with their descriptions, and demands a JSON
   `{ guard, …structuralPayloadFields }` answer keyed to exactly one of the
   declared guards, excluding the runtime-owned direct-Captain `question` and
-  `response` fields above. The judge prompt shall not interpret the player's
-  output, paraphrase it, or alter the FSM's `result` text — it carries
-  the description verbatim.
+  `response` fields above. The prompt shall identify hidden control work,
+  prohibit tool use, file inspection, and external evidence, direct the judge
+  to decide only from the supplied actor output and declared outcomes, and
+  require exactly one JSON object with no prose. The judge prompt shall not
+  interpret the player's output, paraphrase it, or alter the FSM's `result`
+  text — it carries the description verbatim.
 - **Marker-parse** (delegated-player alternative): a deterministic parser that
   scans the player output for a terminal control line such as
   `FSM-RESULT: { "guard": "...", ... }`. Useful when player adapters can
@@ -753,8 +762,11 @@ Adjudicator failures are control-plane errors.
 The runtime shall propagate them by throwing out of `handleBossInput` after attempting cleanup.
 The host adapter surfaces the throw on its control-plane channel (cligent surfaces such throws as `runtime_error` per [TMUX-025](https://github.com/sublang-ai/cligent/blob/main/specs/user/tmux-play.md#tmux-025)).
 The host's player-result channels (`player_finished` and equivalents) are reserved for failures the player itself produced; the host emits them when `callPlayer` resolves with `status !== 'ok'`.
-Captain call failures stay on the Captain/control boundary and shall not be
-reported as player failures.
+Direct-Captain host-result failures stay on the Captain actor boundary and
+shall not be reported as player failures; they follow the recoverable FSM
+failure path specified above. Captain transport, result-shape, trace-sink, and
+adjudication failures remain control-plane errors unless the transport failure
+is causally identical to the active abort signal.
 Because XState still needs the invoked promise to settle, the linked runtime
 shall latch an adjudicator, actor-output JSON-validation, or nested-boundary
 control error outside machine context, allow the invocation's `onError` path to
@@ -1316,6 +1328,13 @@ The emitted module:
   weaken, runtime-derived entry text ownership or closed interrupt targets.
   A conflicting duplicate field contract is a linker/runtime construction
   error.
+  `NO_ACTION` and `BOSS_REPLY` are runtime-owned event types the factory
+  supplies itself — `NO_ACTION` as exactly `{ type: 'NO_ACTION' }`, and
+  `BOSS_REPLY` as an optional judge-selected `questionId` plus the exact-text
+  `answer` the runtime attaches. `bossEvents` shall carry no entry for either
+  type; supplying one is a construction error, so a linker that judges a
+  runtime-owned arm to have lost payload detail under erasure shall report
+  that gap rather than emit the entry.
 - Default-exports the factory call as `createPlaybookRuntime`, typed
   `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`.
 - Exposes, under an `_internal` export, the pure helpers verification