@cleocode/playbooks 2026.6.13 → 2026.6.14

package/src/__tests__/pi-cantbook-e2e.test.ts

@@ -0,0 +1,294 @@
+/**
+ * T11945 (M4) — deterministic in-process e2e: a skill-only `.cantbook` executes
+ * THROUGH the PiAgentAdapter when the Pi runner is wired into the production
+ * dispatcher.
+ *
+ * ## What this proves (the M4 keystone)
+ *
+ * The two production cantbook dispatchers (`buildDefaultDispatcher` in
+ * `packages/cleo/src/dispatch/domains/playbook.ts` and `buildGoDispatcher` in
+ * `packages/cleo/src/cli/commands/go-ivtr-runner.ts`) now pass
+ * `runner: await maybeCreatePiRunner({ system, projectRoot })` into
+ * {@link runSkillNodeOrSpawn}. This test reconstructs that EXACT production
+ * dispatcher shape (`createToolGuard` + `runSkillNodeOrSpawn` + the
+ * `maybeCreatePiRunner` wiring helper) and drives a single skill-only node
+ * through the real {@link executePlaybook} runtime state machine.
+ *
+ * With `CLEO_PI_RUNNER_ENABLED=1` the in-process skill node routes THROUGH the
+ * PiAgentAdapter. There is no working LLM backend on this box, so we do NOT
+ * assert a live round-trip — we assert the DISPATCH PATH reached the Pi adapter,
+ * proven by the **cleo-owned no-credential failure string**
+ * (`no credential resolved for system "task-executor"`) emitted by the Cleo
+ * streamFn (`createPiStreamFn`, the E9 chokepoint). A pi-ai-internal failure
+ * shape would not carry that exact cleo string. The Pi adapter NEVER throws —
+ * it returns a contained `{ status: 'failure' }` (pi-agent-adapter.test.ts:197
+ * precedent), so the run terminates cleanly.
+ *
+ * ## Determinism + isolation contract (AC3 · AC4)
+ *
+ *  - IN-PROCESS only — vitest source, NO subprocess (tsx unresolvable in CI).
+ *  - daemon-OFF — the runtime is the in-memory `node:sqlite` DB, no daemon.
+ *  - `CLEO_SESSION_ID` is stamped so the Pi runner's ZERO-authority guard passes
+ *    (production relies on the daemon stamping it; here the test stamps it).
+ *  - A real `ct-*` skill is materialised under a temp project root's
+ *    `.agents/skills/` dir so `findSkill` resolves it and the in-process skill
+ *    path (not subprocess spawn) is taken. `CLEO_PROJECT_ROOT` pins resolution
+ *    to that temp dir.
+ *  - `maxIterationsDefault: 1` so the failing node runs exactly once → the run
+ *    terminates as `exceeded_iteration_cap` with the Pi error in `errorContext`.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11945
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } 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 AgentDispatcher,
+  type AgentDispatchInput,
+  type AgentDispatchResult,
+  createToolGuard,
+  maybeCreatePiRunner,
+  runSkillNodeOrSpawn,
+} from '@cleocode/core/internal';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { parsePlaybook } from '../parser.js';
+import { executePlaybook } from '../runtime.js';
+import { getPlaybookRun } from '../state.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_PATH = resolve(
+  __dirname,
+  '../../../core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/migration.sql',
+);
+
+/** The skill-only fixture cantbook materialised for this suite. */
+const FIXTURE_PATH = resolve(__dirname, 'fixtures/pi-skill-only.cantbook');
+
+/**
+ * Cleo-owned Pi failure markers that ONLY appear when a dispatch reached the
+ * PiAgentAdapter → Cleo streamFn (E9 chokepoint). A `defaultSkillRunner` would
+ * have SUCCEEDED (it does no LLM work), so seeing any of these proves the Pi
+ * route was taken:
+ *  - `no credential resolved for system` — the Cleo streamFn's no-credential
+ *    terminal error (`createPiStreamFn`), when NO key is reachable.
+ *  - `Pi loop failed:` — the Cleo `wrapPiCall` containment prefix
+ *    (`pi-errors.ts`), when a credential DID resolve and the real LLM transport
+ *    failed (e.g. an expired `sk-ant-oat` token → 401). Either way the call went
+ *    through the Pi adapter, never `defaultSkillRunner`.
+ *
+ * Mirrors the `pi-agent-adapter.test.ts:197` precedent
+ * (`/no credential resolved for system|pi loop error|error/i`).
+ */
+const PI_DISPATCH_MARKERS = /no credential resolved for system|Pi loop failed:/i;
+
+/**
+ * Apply a multi-statement Drizzle migration file (split on the
+ * `--> statement-breakpoint` token). Mirrors starter.e2e.test.ts.
+ */
+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);
+  }
+}
+
+/**
+ * Materialise a real `ct-task-executor` skill under `<projectRoot>/.agents/skills/`
+ * so {@link runSkillNodeOrSpawn}'s `findSkill(agentId, projectRoot)` resolves it
+ * via the `project-custom` search scope, taking the in-process skill path.
+ */
+function writeFixtureSkill(projectRoot: string): void {
+  const skillDir = join(projectRoot, '.agents', 'skills', 'ct-task-executor');
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(
+    join(skillDir, 'SKILL.md'),
+    [
+      '---',
+      'name: ct-task-executor',
+      'description: T11945 e2e fixture skill — drives the in-process Pi dispatch path.',
+      '---',
+      '',
+      'Execute the assigned task.',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+}
+
+/**
+ * Build the EXACT production dispatcher shape from `buildDefaultDispatcher`:
+ * in-process `ct-*` skill nodes run over a deny-first guarded tool surface via
+ * {@link runSkillNodeOrSpawn} with the Pi runner injected; isolation/agent nodes
+ * fall back to the (here-unused) subprocess spawn. The `runner` is obtained from
+ * the M4 wiring helper {@link maybeCreatePiRunner}, exactly as production does.
+ */
+async function buildProductionShapedDispatcher(projectRoot: string): Promise<AgentDispatcher> {
+  const tools = createToolGuard({ allowedRoots: [projectRoot] });
+  // The M4 keystone wiring under test — with CLEO_PI_RUNNER_ENABLED=1 this is
+  // the Pi `SkillRunner`; with the flag unset it is `undefined`.
+  const runner = await maybeCreatePiRunner({ system: 'task-executor', projectRoot });
+
+  /** Subprocess fallback — never exercised by the skill-only fixture. */
+  const spawn = async (input: AgentDispatchInput): Promise<AgentDispatchResult> => ({
+    status: 'failure',
+    output: {},
+    error: `unexpected subprocess spawn for ${input.agentId}`,
+  });
+
+  return {
+    async dispatch(input: AgentDispatchInput): Promise<AgentDispatchResult> {
+      return runSkillNodeOrSpawn(
+        { nodeId: input.nodeId, agentId: input.agentId, context: input.context },
+        {
+          tools,
+          cwd: projectRoot,
+          subprocessSpawn: () => spawn(input),
+          ...(runner !== undefined ? { runner } : {}),
+        },
+      );
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+describe('T11945 (M4): skill-only .cantbook routes through the PiAgentAdapter', () => {
+  let db: DatabaseSync;
+  let projectRoot: string;
+
+  const SAVED = {
+    session: process.env['CLEO_SESSION_ID'],
+    flag: process.env['CLEO_PI_RUNNER_ENABLED'],
+    projectRoot: process.env['CLEO_PROJECT_ROOT'],
+    cleoRoot: process.env['CLEO_ROOT'],
+    anthropic: process.env['ANTHROPIC_API_KEY'],
+    anthropicOauth: process.env['ANTHROPIC_OAUTH_TOKEN'],
+  };
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:');
+    db.exec('PRAGMA foreign_keys=ON');
+    applyMigration(db, readFileSync(MIGRATION_SQL_PATH, 'utf8'));
+
+    projectRoot = mkdtempSync(join(tmpdir(), 't11945-pi-e2e-'));
+    writeFixtureSkill(projectRoot);
+
+    // Pin skill + project resolution to the temp root (getProjectRoot honours
+    // CLEO_ROOT / CLEO_PROJECT_ROOT before any walk).
+    process.env['CLEO_PROJECT_ROOT'] = projectRoot;
+    process.env['CLEO_ROOT'] = projectRoot;
+    // Daemon-stamped identity — the Pi runner fails closed without it (ZERO authority).
+    process.env['CLEO_SESSION_ID'] = 'sess-t11945-e2e';
+    // No credential reachable → deterministic cleo-owned no-credential failure.
+    delete process.env['ANTHROPIC_API_KEY'];
+    delete process.env['ANTHROPIC_OAUTH_TOKEN'];
+  });
+
+  afterEach(() => {
+    db.close();
+    rmSync(projectRoot, { recursive: true, force: true });
+    restoreEnv('CLEO_SESSION_ID', SAVED.session);
+    restoreEnv('CLEO_PI_RUNNER_ENABLED', SAVED.flag);
+    restoreEnv('CLEO_PROJECT_ROOT', SAVED.projectRoot);
+    restoreEnv('CLEO_ROOT', SAVED.cleoRoot);
+    restoreEnv('ANTHROPIC_API_KEY', SAVED.anthropic);
+    restoreEnv('ANTHROPIC_OAUTH_TOKEN', SAVED.anthropicOauth);
+  });
+
+  it('routes the in-process skill node THROUGH the Pi adapter (proven by the cleo no-credential failure)', async () => {
+    process.env['CLEO_PI_RUNNER_ENABLED'] = '1';
+
+    const { definition, sourceHash } = parsePlaybook(readFileSync(FIXTURE_PATH, 'utf8'));
+    expect(definition.name).toBe('pi-skill-only');
+    expect(definition.nodes).toHaveLength(1);
+
+    const dispatcher = await buildProductionShapedDispatcher(projectRoot);
+
+    const result = await executePlaybook({
+      db,
+      playbook: definition,
+      playbookHash: sourceHash,
+      initialContext: { taskId: 'T11945' },
+      dispatcher,
+      projectRoot,
+      // One attempt → the node fails once (no credential) and terminates.
+      maxIterationsDefault: 1,
+    });
+
+    // The Pi loop never throws — the run reaches a clean terminal state with the
+    // node failure recorded (not an uncaught exception).
+    expect(result.terminalStatus).toBe('exceeded_iteration_cap');
+    expect(result.exceededNodeId).toBe('execute');
+
+    // THE PROOF: the failure carries a cleo-owned Pi marker (streamFn
+    // no-credential error OR the wrapPiCall containment prefix). These ONLY
+    // appear when the dispatch reached the PiAgentAdapter → Cleo streamFn (the
+    // E9 chokepoint). A `defaultSkillRunner` would have SUCCEEDED (it does no LLM
+    // work, terminalStatus 'completed'), so an `exceeded_iteration_cap` carrying
+    // this marker is dispositive that the Pi route ran.
+    const errorContext = result.errorContext ?? '';
+    expect(errorContext).toMatch(PI_DISPATCH_MARKERS);
+
+    const run = getPlaybookRun(db, result.runId);
+    expect(run?.status).toBe('failed');
+  });
+
+  it('with CLEO_PI_RUNNER_ENABLED unset the node stays on defaultSkillRunner (zero behaviour change)', async () => {
+    // Flag deliberately NOT set → maybeCreatePiRunner returns undefined →
+    // runSkillNodeOrSpawn uses defaultSkillRunner, which resolves the skill and
+    // returns success WITHOUT any LLM work. The run completes; no Pi string.
+    delete process.env['CLEO_PI_RUNNER_ENABLED'];
+
+    const { definition, sourceHash } = parsePlaybook(readFileSync(FIXTURE_PATH, 'utf8'));
+    const dispatcher = await buildProductionShapedDispatcher(projectRoot);
+
+    const result = await executePlaybook({
+      db,
+      playbook: definition,
+      playbookHash: sourceHash,
+      initialContext: { taskId: 'T11945' },
+      dispatcher,
+      projectRoot,
+      maxIterationsDefault: 1,
+    });
+
+    expect(result.terminalStatus).toBe('completed');
+    // defaultSkillRunner echoes resolution metadata — never a Pi failure marker.
+    expect(result.errorContext ?? '').not.toMatch(PI_DISPATCH_MARKERS);
+    expect(result.finalContext).toMatchObject({ skillId: 'ct-task-executor', resolved: true });
+  });
+
+  it('maybeCreatePiRunner is default-OFF: undefined unless CLEO_PI_RUNNER_ENABLED=1', async () => {
+    delete process.env['CLEO_PI_RUNNER_ENABLED'];
+    expect(await maybeCreatePiRunner({ system: 'task-executor', projectRoot })).toBeUndefined();
+
+    process.env['CLEO_PI_RUNNER_ENABLED'] = '1';
+    const runner = await maybeCreatePiRunner({ system: 'task-executor', projectRoot });
+    expect(typeof runner).toBe('function');
+  });
+});
+
+/** Restore an env var to its saved value (delete when it was unset). */
+function restoreEnv(key: string, value: string | undefined): void {
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+}

package/src/__tests__/rcasd-one-envelope.test.ts

@@ -0,0 +1,239 @@
+/**
+ * T11803 (M4 cantbook done-gate) — prove the vertical slice: `rcasd.cantbook`
+ * execution terminates with EXACTLY ONE LAFS `RenderableEnvelope`, and there is
+ * NO GenKit import anywhere in the execution call graph.
+ *
+ * ## What this proves
+ *
+ *  - **AC1** — the REAL starter `rcasd.cantbook` is parsed and driven end-to-end
+ *    through {@link executePlaybook} (parse → execute → terminal envelope). The
+ *    five agentic stages are stubbed by a DETERMINISTIC recording dispatcher (no
+ *    LLM backend authenticates on CI, and the point of this gate is the ENVELOPE
+ *    SHAPE + the import graph — NOT a live model round-trip).
+ *  - **AC2** — the terminal result is folded into exactly ONE LAFS envelope (the
+ *    ADR-077 `RenderableEnvelope<T>` `{ kind: 'single', data }` wrapped by the
+ *    canonical `createEnvelope` SSoT) and that envelope passes the
+ *    `@cleocode/lafs` `validateEnvelope` schema validator. Exactly one — the run
+ *    produces one `ExecutePlaybookResult`, which maps to one envelope.
+ *  - **AC3** — NO `@genkit-ai` / GenKit import in the execution call graph: a
+ *    static module-graph walk over every playbooks `src/` file reachable from
+ *    `runtime.ts` (the executePlaybook entry) via intra-package imports asserts
+ *    zero GenKit specifiers, and the runtime entry imports none directly.
+ *  - **AC5** — the test is NOT skipped (no `.skip`, no `it.skipIf`).
+ *
+ * ## Determinism + isolation
+ *
+ *  - IN-PROCESS only — vitest source, NO subprocess (tsx unresolvable in CI).
+ *  - daemon-OFF — an in-memory `node:sqlite` DB, no daemon, no live LLM.
+ *  - The dispatcher emits each stage's `ensures.schema`-satisfying output so the
+ *    rcasd contract gates pass and the run reaches `completed` — a faithful
+ *    full-pipeline traversal, deterministically.
+ *
+ * @epic T11391
+ * @task T11803
+ * @saga T11387
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import type { RenderableEnvelope } from '@cleocode/contracts';
+import { createEnvelope, validateEnvelope } from '@cleocode/lafs';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { parsePlaybook } from '../parser.js';
+import {
+  type AgentDispatcher,
+  type AgentDispatchInput,
+  type AgentDispatchResult,
+  type ExecutePlaybookResult,
+  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 PLAYBOOKS_SRC = resolve(__dirname, '..');
+
+const MIGRATION_SQL = resolve(
+  __dirname,
+  '../../../core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/migration.sql',
+);
+const RCASD_CANTBOOK = resolve(__dirname, '../../starter/rcasd.cantbook');
+
+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);
+  }
+}
+
+/**
+ * Deterministic recording dispatcher that emits each rcasd stage's
+ * `ensures.schema`-satisfying output + the `requires`/edge fields the next stage
+ * needs, so the full five-stage pipeline reaches `completed` with NO LLM. Keyed
+ * by `nodeId` (the rcasd stage names).
+ */
+function makeRcasdDispatcher(): AgentDispatcher & { nodes: string[] } {
+  const nodes: string[] = [];
+  // Per-stage outputs satisfying rcasd.cantbook ensures.schema + downstream
+  // requires/edge contracts. The first four stages' ensures.schema names
+  // (research_summary | consensus_decision | architecture_plan |
+  // specification_document) are registered passthrough; the terminal
+  // `decomposition` stage's `task_tree` is STRICT — it validates
+  // `context['task_tree']` as a non-empty array of { title, acceptance[] }
+  // entries — so we emit a conformant `task_tree` to clear the contract gate.
+  const STAGE_OUTPUT: Record<string, Record<string, unknown>> = {
+    research: {
+      summary: 'research summary for the epic',
+      risks: ['risk-a', 'risk-b'],
+    },
+    consensus: {
+      decision: 'proceed with approach X',
+    },
+    architecture: {
+      patterns: ['pattern-1', 'pattern-2'],
+      adrs: ['ADR-001'],
+    },
+    specification: {
+      acceptance: ['AC1', 'AC2'],
+      requirements: ['REQ-1'],
+    },
+    decomposition: {
+      // `children` satisfies the specification→decomposition edge.ensures.
+      children: ['T1001', 'T1002'],
+      acceptance: ['AC1'],
+      requirements: ['REQ-1'],
+      // `task_tree` satisfies the strict ensures.schema on the terminal stage.
+      task_tree: [
+        { id: 'T1001', title: 'Implement feature A', acceptance: ['AC1'] },
+        { id: 'T1002', title: 'Implement feature B', acceptance: ['AC2'] },
+      ],
+    },
+  };
+  return {
+    nodes,
+    async dispatch(input: AgentDispatchInput): Promise<AgentDispatchResult> {
+      nodes.push(input.nodeId);
+      return { status: 'success', output: STAGE_OUTPUT[input.nodeId] ?? {} };
+    },
+  };
+}
+
+/**
+ * Recursively collect every `*.ts` source file under `dir` (excluding tests),
+ * so the no-GenKit assertion covers the WHOLE playbooks runtime package surface
+ * reachable by the execution path — not just the entry file.
+ */
+function collectSourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__') continue;
+      out.push(...collectSourceFiles(full));
+    } else if (entry.name.endsWith('.ts')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+describe('T11803 (M4): rcasd.cantbook → exactly ONE LAFS envelope, no GenKit', () => {
+  let db: DatabaseSync;
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:');
+    db.exec('PRAGMA foreign_keys=ON');
+    applyMigration(db, readFileSync(MIGRATION_SQL, 'utf8'));
+  });
+  afterEach(() => db.close());
+
+  it('AC1+AC2: parse→execute→envelope yields exactly ONE valid LAFS RenderableEnvelope', async () => {
+    const { definition, sourceHash } = parsePlaybook(readFileSync(RCASD_CANTBOOK, 'utf8'));
+    expect(definition.name).toBe('rcasd');
+    expect(definition.nodes.map((n) => n.id)).toEqual([
+      'research',
+      'consensus',
+      'architecture',
+      'specification',
+      'decomposition',
+    ]);
+
+    const dispatcher = makeRcasdDispatcher();
+    const result: ExecutePlaybookResult = await executePlaybook({
+      db,
+      playbook: definition,
+      playbookHash: sourceHash,
+      initialContext: { taskId: 'T999', epicId: 'T999', scope: 'global' },
+      dispatcher,
+    });
+
+    // The full five-stage pipeline ran deterministically to completion.
+    expect(dispatcher.nodes).toEqual([
+      'research',
+      'consensus',
+      'architecture',
+      'specification',
+      'decomposition',
+    ]);
+    expect(result.terminalStatus).toBe('completed');
+    // No silent contract violation hid behind the completion.
+    expect(result.finalContext['__ensuresSchemaViolation']).toBeUndefined();
+    expect(result.finalContext['__contractViolation']).toBeUndefined();
+
+    // Fold the single terminal result into ONE ADR-077 RenderableEnvelope, then
+    // into ONE canonical LAFS envelope (the SSoT `createEnvelope`).
+    const renderable: RenderableEnvelope<ExecutePlaybookResult> = {
+      kind: 'single',
+      data: result,
+    };
+    const lafsEnvelope = createEnvelope({
+      success: true,
+      result: renderable as unknown as Record<string, unknown>,
+      meta: { operation: 'playbook.run', requestId: `rcasd-${result.runId}` },
+    });
+
+    // EXACTLY ONE — a single object, not an array of envelopes.
+    expect(Array.isArray(lafsEnvelope)).toBe(false);
+    expect(lafsEnvelope.success).toBe(true);
+    expect(lafsEnvelope.result).toMatchObject({ kind: 'single' });
+
+    // Validated by the @cleocode/lafs schema validator.
+    const validation = validateEnvelope(lafsEnvelope);
+    expect(validation.errors).toEqual([]);
+    expect(validation.valid).toBe(true);
+  });
+
+  it('AC3: NO @genkit-ai / GenKit import in the execution call graph', () => {
+    // The execution call graph for executePlaybook (runtime → state, approval,
+    // parser, schema) lives entirely under packages/playbooks/src. Walk every
+    // non-test source file and assert zero GenKit specifiers.
+    const files = collectSourceFiles(PLAYBOOKS_SRC);
+    expect(files.length).toBeGreaterThan(0);
+
+    const offenders: string[] = [];
+    const GENKIT_IMPORT =
+      /(?:import|from|require)\s*(?:\(\s*)?['"]@?genkit(?:-ai)?(?:\/[^'"]*)?['"]/;
+    for (const file of files) {
+      const src = readFileSync(file, 'utf8');
+      if (GENKIT_IMPORT.test(src)) offenders.push(file);
+    }
+    expect(offenders).toEqual([]);
+
+    // And the runtime entry — the executePlaybook module itself — imports no
+    // GenKit specifier directly (belt-and-suspenders against a future edit).
+    const runtimeSrc = readFileSync(resolve(PLAYBOOKS_SRC, 'runtime.ts'), 'utf8');
+    expect(runtimeSrc).not.toMatch(/@?genkit/i);
+  });
+});

package/src/index.ts

@@ -79,6 +79,8 @@ export {
   executePlaybook,
   type PlaybookTerminalStatus,
   type ResumePlaybookOptions,
+  // T1944 (M4): per-step `node.inputs` → dispatch-boundary binding resolver.
+  resolveStepBindings,
   resumePlaybook,
 } from './runtime.js';
 // W4-8: state layer CRUD for playbook_runs + playbook_approvals

package/src/parser.ts

@@ -337,6 +337,19 @@ function parseAgenticNode(
 
   const context_files = parseStringArray(raw.context_files, `nodes[${index}].context_files`);
 
+  // T11759 (M4): per-stage LLM pin. Each is an optional non-empty string — the
+  // dispatcher resolves them through the E9 chokepoint at dispatch time. Absent
+  // fields leave resolution unchanged (additive).
+  const profile = parseOptionalNonEmptyString(raw.profile, `nodes[${index}].profile`);
+  const model = parseOptionalNonEmptyString(raw.model, `nodes[${index}].model`);
+  const provider = parseOptionalNonEmptyString(raw.provider, `nodes[${index}].provider`);
+
+  // T1947 (M4): per-step skill/tool allowlists. Each is an optional string[] —
+  // enforced at spawn time by composeSpawnPayload as an INTERSECTION against the
+  // Tier-0/1/2 baseline (restrict-only, never expand). Absent → no restriction.
+  const allowed_skills = parseStringArray(raw.allowed_skills, `nodes[${index}].allowed_skills`);
+  const allowed_tools = parseStringArray(raw.allowed_tools, `nodes[${index}].allowed_tools`);
+
   return {
     ...base,
     type: 'agentic',
@@ -345,6 +358,11 @@ function parseAgenticNode(
     role,
     inputs,
     ...(context_files !== undefined ? { context_files } : {}),
+    ...(profile !== undefined ? { profile } : {}),
+    ...(model !== undefined ? { model } : {}),
+    ...(provider !== undefined ? { provider } : {}),
+    ...(allowed_skills !== undefined ? { allowed_skills } : {}),
+    ...(allowed_tools !== undefined ? { allowed_tools } : {}),
   };
 }
 
@@ -768,6 +786,23 @@ function parseStringArray(raw: unknown, field: string): string[] | undefined {
   });
 }
 
+/**
+ * Parse an optional scalar string field that, when present, MUST be a non-empty
+ * string (T11759 — the per-stage LLM pins `profile` / `model` / `provider`).
+ *
+ * @param raw - Raw YAML value.
+ * @param field - Field path for diagnostics.
+ * @returns The trimmed-as-authored string, or `undefined` when absent.
+ * @throws {PlaybookParseError} When present but not a non-empty string.
+ */
+function parseOptionalNonEmptyString(raw: unknown, field: string): string | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string' || raw.length === 0) {
+    throw new PlaybookParseError(`${field} must be a non-empty string`, field, raw);
+  }
+  return raw;
+}
+
 /**
  * Detect cycles across the combined edge-set (explicit `edges[]` plus
  * `depends[]` back-references). Uses 3-color DFS.