@cleocode/playbooks 2026.6.12 → 2026.6.14

package/src/__tests__/guarded-deterministic-dispatch.test.ts

@@ -0,0 +1,225 @@
+/**
+ * T11802 (M4 cantbook done-gate) — every `deterministic` (shell) node dispatch in
+ * `executePlaybook` routes through the `guard.ts` deny-first chokepoint.
+ *
+ * ## What this proves
+ *
+ *  - **AC1 / AC2** — a minimal `.cantbook` with a `deterministic` shell step,
+ *    executed through the REAL {@link executePlaybook} runtime with the
+ *    production-shaped {@link createGuardedDeterministicRunner} wired to a real
+ *    {@link createToolGuard}, reaches the guard: the spawned command actually runs
+ *    THROUGH `guard.executeShell` (proven by captured stdout in the merged run
+ *    context). There is NO `child_process` import in the runtime call graph — the
+ *    guard owns the spawn.
+ *  - **AC3** — when the SAME runtime dispatches a `deterministic` node whose
+ *    command is on the guard's denylist (`enforce` mode), the guard REJECTS it
+ *    BEFORE any process is spawned; the node terminates as a contained failure
+ *    (the runtime contract is non-throwing) carrying the guard's
+ *    `E_TOOL_GUARD_DENIED` message.
+ *  - **AC5** — no new state machine: the runtime is unchanged; only the injected
+ *    `deterministicRunner` is the guard-routed one.
+ *
+ * ## Determinism + isolation
+ *
+ *  - IN-PROCESS only — vitest source, NO subprocess driver (tsx unresolvable in CI).
+ *  - daemon-OFF — an in-memory `node:sqlite` DB, no daemon.
+ *  - The allowed command is `node -e <print>` (always present on the test box, no
+ *    network, no filesystem mutation) so the "guard actually spawned" assertion is
+ *    portable and side-effect-free.
+ *  - A temp project root scopes the guard's `allowedRoots`; `cwd` is pinned to it.
+ *
+ * @epic T11391
+ * @task T11802
+ * @saga T11387
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import type { PlaybookDefinition, PlaybookDeterministicNode } from '@cleocode/contracts';
+import {
+  createGuardedDeterministicRunner,
+  createToolGuard,
+  DEFAULT_DETERMINISTIC_DENIED_COMMANDS,
+} from '@cleocode/core/internal';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { type DeterministicRunner, executePlaybook } from '../runtime.js';
+
+const _require = createRequire(import.meta.url);
+type DatabaseSync = _DatabaseSyncType;
+const { DatabaseSync } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof _DatabaseSyncType>) => DatabaseSync;
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the T889 playbook-tables migration SQL. */
+const MIGRATION_SQL = resolve(
+  __dirname,
+  '../../../core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/migration.sql',
+);
+
+/** Apply a multi-statement Drizzle migration (split on the breakpoint token). */
+function applyMigration(db: DatabaseSync, sql: string): void {
+  const statements = sql
+    .split(/--> statement-breakpoint/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  for (const stmt of statements) {
+    const lines = stmt.split('\n');
+    const hasSql = lines.some((l) => l.trim().length > 0 && !l.trim().startsWith('--'));
+    if (hasSql) db.exec(stmt);
+  }
+}
+
+/** Build a single-node `deterministic` playbook (the entry node is terminal). */
+function singleDeterministicPlaybook(node: PlaybookDeterministicNode): PlaybookDefinition {
+  return { version: '1.0', name: 'guarded-shell', nodes: [node], edges: [] };
+}
+
+describe('T11802 (M4): deterministic node dispatch routes through guard.ts', () => {
+  let db: DatabaseSync;
+  let projectRoot: string;
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:');
+    db.exec('PRAGMA foreign_keys=ON');
+    applyMigration(db, readFileSync(MIGRATION_SQL, 'utf8'));
+    projectRoot = mkdtempSync(join(tmpdir(), 't11802-guarded-shell-'));
+  });
+
+  afterEach(() => {
+    db.close();
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  /**
+   * Build the production-shaped deterministic runner: the SAME guard the CLI's
+   * `buildDefaultDeterministicRunner` constructs (allowedRoots + denylist +
+   * enforce), wrapped by `createGuardedDeterministicRunner`.
+   */
+  function buildGuardedRunner(): DeterministicRunner {
+    const tools = createToolGuard({
+      allowedRoots: [projectRoot],
+      deniedCommands: DEFAULT_DETERMINISTIC_DENIED_COMMANDS,
+      mode: 'enforce',
+    });
+    // Structurally assignable to the runtime's DeterministicRunner.
+    return createGuardedDeterministicRunner({ tools });
+  }
+
+  it('AC2: a shell step is intercepted by the guard — the command runs THROUGH guard.executeShell', async () => {
+    // `node -e` prints a sentinel; capturing it proves the guard actually
+    // spawned the process (not a mock).
+    const SENTINEL = 'guard-intercepted-T11802';
+    const node: PlaybookDeterministicNode = {
+      id: 'shell',
+      type: 'deterministic',
+      command: process.execPath, // node — always present, never on the denylist
+      args: ['-e', `process.stdout.write(${JSON.stringify(SENTINEL)})`],
+      cwd: projectRoot,
+    };
+
+    const result = await executePlaybook({
+      db,
+      playbook: singleDeterministicPlaybook(node),
+      playbookHash: 'hash-allowed',
+      initialContext: { taskId: 'T11802' },
+      dispatcher: {
+        // The agentic dispatcher must NEVER be reached for a deterministic node.
+        async dispatch() {
+          return {
+            status: 'failure',
+            output: {},
+            error: 'agentic dispatcher reached for a deterministic node — guard bypassed!',
+          };
+        },
+      },
+      deterministicRunner: buildGuardedRunner(),
+    });
+
+    expect(result.terminalStatus).toBe('completed');
+    // The guard's executeShell captured the child's stdout into the merged
+    // context — dispositive that the command was spawned THROUGH the guard.
+    expect(result.finalContext['shell_stdout']).toBe(SENTINEL);
+    expect(result.finalContext['shell_exitCode']).toBe(0);
+  });
+
+  it('AC3: a denied command is rejected by the guard denylist when dispatched from executePlaybook', async () => {
+    // `rm` is on DEFAULT_DETERMINISTIC_DENIED_COMMANDS — the guard rejects it
+    // BEFORE any process is spawned (enforce mode).
+    expect(DEFAULT_DETERMINISTIC_DENIED_COMMANDS).toContain('rm');
+
+    const node: PlaybookDeterministicNode = {
+      id: 'danger',
+      type: 'deterministic',
+      command: 'rm',
+      args: ['-rf', join(projectRoot, 'anything')],
+      cwd: projectRoot,
+      // One attempt → first denial is terminal (no retry storms).
+      on_failure: { max_iterations: 1 },
+    };
+
+    const result = await executePlaybook({
+      db,
+      playbook: singleDeterministicPlaybook(node),
+      playbookHash: 'hash-denied',
+      initialContext: { taskId: 'T11802' },
+      dispatcher: {
+        async dispatch() {
+          return {
+            status: 'failure',
+            output: {},
+            error: 'agentic dispatcher reached for a deterministic node — guard bypassed!',
+          };
+        },
+      },
+      deterministicRunner: buildGuardedRunner(),
+      maxIterationsDefault: 1,
+    });
+
+    // The denial is a contained node failure (the runtime never throws).
+    expect(result.terminalStatus).toBe('exceeded_iteration_cap');
+    expect(result.exceededNodeId).toBe('danger');
+    // The guard's enforce-mode rejection message reached the runtime.
+    expect(result.errorContext ?? '').toMatch(/denylist|E_TOOL_GUARD_DENIED|"rm"/);
+  });
+
+  it('AC1: the guard is the ONLY spawn path — a denied command never spawns rm', async () => {
+    // Targeting a path INSIDE the project root so, IF the guard were bypassed,
+    // rm would actually delete it. The guard must stop it first. We assert the
+    // failure shape (no rm executed) rather than filesystem side effects so the
+    // test is hermetic even on a box without `rm`.
+    const node: PlaybookDeterministicNode = {
+      id: 'danger',
+      type: 'deterministic',
+      command: '/bin/rm', // absolute path — basename `rm` is still denied
+      args: ['-f', join(projectRoot, 'sentinel')],
+      cwd: projectRoot,
+      on_failure: { max_iterations: 1 },
+    };
+
+    let agenticReached = false;
+    const result = await executePlaybook({
+      db,
+      playbook: singleDeterministicPlaybook(node),
+      playbookHash: 'hash-abs-denied',
+      initialContext: { taskId: 'T11802' },
+      dispatcher: {
+        async dispatch() {
+          agenticReached = true;
+          return { status: 'success', output: { bypassed: true } };
+        },
+      },
+      deterministicRunner: buildGuardedRunner(),
+      maxIterationsDefault: 1,
+    });
+
+    expect(agenticReached).toBe(false); // never fell back to the agentic path
+    expect(result.terminalStatus).toBe('exceeded_iteration_cap');
+    expect(result.errorContext ?? '').toMatch(/denylist|E_TOOL_GUARD_DENIED|"rm"/);
+  });
+});

package/src/__tests__/inputs-bindings.test.ts

@@ -0,0 +1,250 @@
+/**
+ * T1944 (M4 cantbook done-gate) — `PlaybookAgenticNode.inputs` →
+ * `AgentDispatchInput.bindings` wiring + mustache resolution at the dispatch
+ * boundary.
+ *
+ * Two layers of coverage:
+ *
+ *  1. Pure-unit tests of {@link resolveStepBindings} — precedence, shadowing,
+ *     dot-path resolution, and the lenient missing-key rule, exercised in
+ *     isolation with no DB.
+ *  2. In-process `executePlaybook` end-to-end — a `.cantbook`-equivalent node
+ *     with `inputs: { topic: '{{inputs.epicId}}' }` resolves and the bound
+ *     value reaches {@link AgentDispatchInput.bindings} at dispatch time.
+ *
+ * No `@cleocode/*` module is mocked — the resolver is the real canonical
+ * T1238 engine and the runtime runs against an in-memory `node:sqlite` DB.
+ *
+ * @task T1944 — wire PlaybookAgenticNode.inputs → AgentDispatchInput.bindings
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import type { PlaybookAgenticNode, PlaybookDefinition } from '@cleocode/contracts';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  type AgentDispatcher,
+  type AgentDispatchInput,
+  type AgentDispatchResult,
+  executePlaybook,
+  resolveStepBindings,
+} from '../runtime.js';
+
+const _require = createRequire(import.meta.url);
+type DatabaseSync = _DatabaseSyncType;
+const { DatabaseSync } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof _DatabaseSyncType>) => DatabaseSync;
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIGRATION_SQL = resolve(
+  __dirname,
+  '../../../core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/migration.sql',
+);
+
+function applyMigration(db: DatabaseSync, sql: string): void {
+  const statements = sql
+    .split(/--> statement-breakpoint/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  for (const stmt of statements) {
+    const lines = stmt.split('\n');
+    const hasSql = lines.some((l) => l.trim().length > 0 && !l.trim().startsWith('--'));
+    if (hasSql) db.exec(stmt);
+  }
+}
+
+function agenticNode(
+  id: string,
+  overrides: Partial<PlaybookAgenticNode> = {},
+): PlaybookAgenticNode {
+  return { id, type: 'agentic', skill: `skill-${id}`, ...overrides };
+}
+
+/** Dispatcher that records the full {@link AgentDispatchInput} per call. */
+function makeBindingRecorder(
+  handler: (input: AgentDispatchInput) => AgentDispatchResult,
+): AgentDispatcher & { calls: AgentDispatchInput[] } {
+  const calls: AgentDispatchInput[] = [];
+  return {
+    calls,
+    async dispatch(input: AgentDispatchInput): Promise<AgentDispatchResult> {
+      // Snapshot bindings/context so later mutation cannot taint the assertion.
+      calls.push({
+        ...input,
+        context: { ...input.context },
+        bindings: input.bindings === undefined ? undefined : { ...input.bindings },
+      });
+      return handler(input);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resolveStepBindings — pure unit
+// ---------------------------------------------------------------------------
+
+describe('T1944: resolveStepBindings (pure)', () => {
+  it('AC5: resolves a {{inputs.epicId}} template from the run context', () => {
+    const node = agenticNode('research', { inputs: { topic: '{{inputs.epicId}}' } });
+    const context = { inputs: { epicId: 'T1942' } };
+
+    const bound = resolveStepBindings(node, context);
+
+    expect(bound['topic']).toBe('T1942');
+    // Original context keys remain present.
+    expect(bound['inputs']).toEqual({ epicId: 'T1942' });
+  });
+
+  it('AC5: resolves a flat {{epicId}} single-segment template', () => {
+    const node = agenticNode('research', { inputs: { topic: '{{epicId}}' } });
+    const bound = resolveStepBindings(node, { epicId: 'T1942' });
+    expect(bound['topic']).toBe('T1942');
+  });
+
+  it('AC6: step bindings shadow playbook bindings for the same key', () => {
+    // The run context already carries `topic`; the step input MUST win.
+    const node = agenticNode('research', { inputs: { topic: '{{inputs.epicId}}' } });
+    const context = { topic: 'stale-context-value', inputs: { epicId: 'T1942' } };
+
+    const bound = resolveStepBindings(node, context);
+
+    expect(bound['topic']).toBe('T1942');
+    expect(bound['topic']).not.toBe('stale-context-value');
+  });
+
+  it('missing-key rule: unresolved {{path}} is left as a literal placeholder', () => {
+    const node = agenticNode('research', { inputs: { topic: '{{inputs.nope}}' } });
+    const bound = resolveStepBindings(node, { inputs: { epicId: 'T1942' } });
+    expect(bound['topic']).toBe('{{inputs.nope}}');
+  });
+
+  it('resolves dot-path nesting deeper than one level', () => {
+    const node = agenticNode('research', { inputs: { fw: '{{project.testing.framework}}' } });
+    const bound = resolveStepBindings(node, {
+      project: { testing: { framework: 'vitest' } },
+    });
+    expect(bound['fw']).toBe('vitest');
+  });
+
+  it('passes literal (non-template) input values through unchanged', () => {
+    const node = agenticNode('research', { inputs: { mode: 'fast' } });
+    const bound = resolveStepBindings(node, { x: 1 });
+    expect(bound['mode']).toBe('fast');
+  });
+
+  it('returns a shallow copy of context when the node declares no inputs', () => {
+    const node = agenticNode('research');
+    const context = { taskId: 'T123', a: 1 };
+    const bound = resolveStepBindings(node, context);
+    expect(bound).toEqual(context);
+    expect(bound).not.toBe(context);
+  });
+
+  it('returns a shallow copy of context for an empty inputs map', () => {
+    const node = agenticNode('research', { inputs: {} });
+    const context = { taskId: 'T123' };
+    expect(resolveStepBindings(node, context)).toEqual(context);
+  });
+
+  it('does not mutate the source context', () => {
+    const node = agenticNode('research', { inputs: { topic: '{{epicId}}' } });
+    const context = { epicId: 'T1942' };
+    resolveStepBindings(node, context);
+    expect(context).toEqual({ epicId: 'T1942' });
+    expect(context).not.toHaveProperty('topic');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// executePlaybook — bindings reach the dispatch boundary (in-process e2e)
+// ---------------------------------------------------------------------------
+
+describe('T1944: AgentDispatchInput.bindings (in-process)', () => {
+  let db: DatabaseSync;
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:');
+    db.exec('PRAGMA foreign_keys=ON');
+    applyMigration(db, readFileSync(MIGRATION_SQL, 'utf8'));
+  });
+  afterEach(() => db.close());
+
+  it('AC2: resolved step input reaches AgentDispatchInput.bindings at dispatch', async () => {
+    const playbook: PlaybookDefinition = {
+      version: '1.0',
+      name: 'inputs-bindings',
+      nodes: [agenticNode('research', { inputs: { topic: '{{inputs.epicId}}' } })],
+      edges: [],
+    };
+    const dispatcher = makeBindingRecorder(() => ({ status: 'success', output: {} }));
+
+    const result = await executePlaybook({
+      db,
+      playbook,
+      playbookHash: 'hash-t1944',
+      initialContext: { inputs: { epicId: 'T1942' } },
+      dispatcher,
+    });
+
+    expect(result.terminalStatus).toBe('completed');
+    expect(dispatcher.calls).toHaveLength(1);
+    // The resolved binding (NOT the raw template) reaches the dispatcher.
+    expect(dispatcher.calls[0]?.bindings?.['topic']).toBe('T1942');
+    // The raw accumulated context still carries the source object.
+    expect(dispatcher.calls[0]?.context['inputs']).toEqual({ epicId: 'T1942' });
+  });
+
+  it('AC2: bindings is always populated even when the node declares no inputs', async () => {
+    const playbook: PlaybookDefinition = {
+      version: '1.0',
+      name: 'no-inputs',
+      nodes: [agenticNode('plain')],
+      edges: [],
+    };
+    const dispatcher = makeBindingRecorder(() => ({ status: 'success', output: {} }));
+
+    await executePlaybook({
+      db,
+      playbook,
+      playbookHash: 'hash-t1944-b',
+      initialContext: { taskId: 'T123' },
+      dispatcher,
+    });
+
+    expect(dispatcher.calls[0]?.bindings).toMatchObject({ taskId: 'T123' });
+  });
+
+  it('AC6: step binding shadows a same-named accumulated context key end-to-end', async () => {
+    // Node `a` emits `topic`; node `b` declares an `inputs.topic` template that
+    // MUST shadow the inherited context value when dispatched.
+    const playbook: PlaybookDefinition = {
+      version: '1.0',
+      name: 'shadowing',
+      nodes: [agenticNode('a'), agenticNode('b', { inputs: { topic: '{{inputs.epicId}}' } })],
+      edges: [{ from: 'a', to: 'b' }],
+    };
+    const dispatcher = makeBindingRecorder((input) =>
+      input.nodeId === 'a'
+        ? { status: 'success', output: { topic: 'from-node-a' } }
+        : { status: 'success', output: {} },
+    );
+
+    await executePlaybook({
+      db,
+      playbook,
+      playbookHash: 'hash-t1944-c',
+      initialContext: { inputs: { epicId: 'T1942' } },
+      dispatcher,
+    });
+
+    const callB = dispatcher.calls.find((c) => c.nodeId === 'b');
+    // Accumulated context still has node-a's value...
+    expect(callB?.context['topic']).toBe('from-node-a');
+    // ...but the step binding shadows it.
+    expect(callB?.bindings?.['topic']).toBe('T1942');
+  });
+});

package/src/__tests__/node-allowlist.test.ts

@@ -0,0 +1,186 @@
+/**
+ * T1947 (M4 cantbook done-gate, Gap E/F) — `PlaybookAgenticNode.allowed_skills`
+ * / `.allowed_tools` are parsed (AC1) and reach the dispatch boundary as
+ * `AgentDispatchInput.allowedSkills` / `.allowedTools` (AC5) so the dispatcher
+ * can intersect them against the Tier-0/1/2 baseline at spawn time.
+ *
+ * Two layers:
+ *  1. Parser → runtime forwarding: a `.cantbook` node with `allowed_skills:` /
+ *     `allowed_tools:` is parsed and the lists reach {@link AgentDispatchInput}
+ *     at dispatch time — asserted with a recorder dispatcher (no live backend).
+ *  2. Default (un-restricted) nodes carry NO allowlist — the dispatch path is
+ *     unchanged (additive).
+ *
+ * The intersection enforcement itself lives in `@cleocode/core`'s
+ * `composeSpawnPayload` and is covered by `spawn.test.ts`; this suite proves the
+ * runtime hands the allowlists to the dispatcher so that enforcement can occur.
+ * No `@cleocode/*` module is mocked.
+ *
+ * @task T1947
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { parsePlaybook } from '../parser.js';
+import {
+  type AgentDispatcher,
+  type AgentDispatchInput,
+  type AgentDispatchResult,
+  executePlaybook,
+} from '../runtime.js';
+
+const _require = createRequire(import.meta.url);
+type DatabaseSync = _DatabaseSyncType;
+const { DatabaseSync } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof _DatabaseSyncType>) => DatabaseSync;
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIGRATION_SQL = resolve(
+  __dirname,
+  '../../../core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/migration.sql',
+);
+
+function applyMigration(db: DatabaseSync, sql: string): void {
+  const statements = sql
+    .split(/--> statement-breakpoint/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  for (const stmt of statements) {
+    const lines = stmt.split('\n');
+    const hasSql = lines.some((l) => l.trim().length > 0 && !l.trim().startsWith('--'));
+    if (hasSql) db.exec(stmt);
+  }
+}
+
+/** Records the full {@link AgentDispatchInput} per call. */
+function makeRecorder(): AgentDispatcher & { calls: AgentDispatchInput[] } {
+  const calls: AgentDispatchInput[] = [];
+  return {
+    calls,
+    async dispatch(input: AgentDispatchInput): Promise<AgentDispatchResult> {
+      calls.push({ ...input, context: { ...input.context } });
+      return { status: 'success', output: {} };
+    },
+  };
+}
+
+describe('T1947: AC1 — parser accepts allowed_skills / allowed_tools', () => {
+  it('parses string[] allowlists onto the agentic node', () => {
+    const yaml = `
+version: "1.0"
+name: gated-flow
+nodes:
+  - id: review
+    type: agentic
+    skill: ct-validator
+    allowed_skills: [ct-validator, ct-cleo]
+    allowed_tools: [Read, Grep]
+`;
+    const { definition } = parsePlaybook(yaml);
+    const node = definition.nodes[0];
+    expect(node?.type).toBe('agentic');
+    if (node?.type !== 'agentic') throw new Error('expected agentic node');
+    expect(node.allowed_skills).toEqual(['ct-validator', 'ct-cleo']);
+    expect(node.allowed_tools).toEqual(['Read', 'Grep']);
+  });
+
+  it('omits both fields when the node declares neither (additive)', () => {
+    const yaml = `
+version: "1.0"
+name: plain-flow
+nodes:
+  - id: research
+    type: agentic
+    skill: ct-research-agent
+`;
+    const { definition } = parsePlaybook(yaml);
+    const node = definition.nodes[0];
+    if (node?.type !== 'agentic') throw new Error('expected agentic node');
+    expect(node.allowed_skills).toBeUndefined();
+    expect(node.allowed_tools).toBeUndefined();
+  });
+
+  it('rejects a non-string entry in allowed_skills', () => {
+    const yaml = `
+version: "1.0"
+name: bad-flow
+nodes:
+  - id: review
+    type: agentic
+    skill: ct-validator
+    allowed_skills: [ct-validator, 42]
+`;
+    expect(() => parsePlaybook(yaml)).toThrow(/allowed_skills/);
+  });
+});
+
+describe('T1947: AC5 — allowlists reach the dispatch boundary', () => {
+  let db: DatabaseSync;
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:');
+    db.exec('PRAGMA foreign_keys=ON');
+    applyMigration(db, readFileSync(MIGRATION_SQL, 'utf8'));
+  });
+  afterEach(() => db.close());
+
+  it('forwards allowed_skills/allowed_tools as allowedSkills/allowedTools', async () => {
+    const yaml = `
+version: "1.0"
+name: gated-flow
+nodes:
+  - id: review
+    type: agentic
+    skill: ct-validator
+    allowed_skills: [ct-validator]
+    allowed_tools: [Read, Grep]
+`;
+    const { definition } = parsePlaybook(yaml);
+    const dispatcher = makeRecorder();
+
+    const result = await executePlaybook({
+      db,
+      playbook: definition,
+      playbookHash: 'hash-t1947',
+      initialContext: { taskId: 'T1947' },
+      dispatcher,
+    });
+
+    expect(result.terminalStatus).toBe('completed');
+    expect(dispatcher.calls).toHaveLength(1);
+    const call = dispatcher.calls[0];
+    expect(call?.nodeId).toBe('review');
+    expect(call?.allowedSkills).toEqual(['ct-validator']);
+    expect(call?.allowedTools).toEqual(['Read', 'Grep']);
+  });
+
+  it('an un-restricted stage carries NO allowedSkills/allowedTools (additive)', async () => {
+    const yaml = `
+version: "1.0"
+name: plain-flow
+nodes:
+  - id: research
+    type: agentic
+    skill: ct-research-agent
+`;
+    const { definition } = parsePlaybook(yaml);
+    const dispatcher = makeRecorder();
+
+    await executePlaybook({
+      db,
+      playbook: definition,
+      playbookHash: 'hash-t1947-b',
+      initialContext: { taskId: 'T123' },
+      dispatcher,
+    });
+
+    const call = dispatcher.calls[0];
+    expect(call?.allowedSkills).toBeUndefined();
+    expect(call?.allowedTools).toBeUndefined();
+  });
+});