chati-dev 4.4.1 → 4.5.2

package/src/orchestrator/cli.js

@@ -45,7 +45,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from
 import { join, resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import {
   initTaskList, readTaskList, getTeamProgress,
 } from '../terminal/team-task-list.js';
@@ -53,6 +53,9 @@ import {
   recordEvent, EventType, clearTimeline,
 } from '../intelligence/timeline.js';
 import { updateClaudeMd } from '../memory/magic-docs.js';
+import { loadRuntimeInstallationV2, resolveRuntimeInvocationV2 } from './runtime-installation-v2.js';
+import { compilePlanningHandoff, PLANNING_V2_TASKS_PATH } from './planning-runtime.js';
+import { persistRailHandoff } from './rail-runtime.js';
 
 // Spawn commands must reference the terminal runners with an absolute,
 // layout-independent path: the old monorepo-relative
@@ -545,7 +548,7 @@ function sessionToPipelineState(session, projectDir) {
  * Build the spawn command string for an autonomous agent.
  * Exported for testing (path resolution must hold in every install layout).
  */
-export function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout) {
+export function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout, model = null, strictProvider = false) {
   const parts = [
     'node', RUNNER('run-agent.js'),
     '--agent', agent,
@@ -553,6 +556,8 @@ export function buildSpawnCommand(agent, projectDir, previousAgent, provider, ti
     '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent || 'none',
     '--provider', provider || 'claude',
+    ...(model ? ['--model', model] : []),
+    ...(strictProvider ? ['--strict-provider'] : []),
     '--timeout', String(timeout || 600000),
   ];
   return parts.join(' ');
@@ -562,7 +567,7 @@ export function buildSpawnCommand(agent, projectDir, previousAgent, provider, ti
  * Build the parallel spawn command string.
  * Exported for testing.
  */
-export function buildParallelSpawnCommand(agents, projectDir, previousAgent, provider, timeout) {
+export function buildParallelSpawnCommand(agents, projectDir, previousAgent, provider, timeout, model = null, strictProvider = false) {
   const taskIds = agents.map(a => `${a}-task`).join(',');
   const parts = [
     'node', RUNNER('run-parallel.js'),
@@ -571,6 +576,8 @@ export function buildParallelSpawnCommand(agents, projectDir, previousAgent, pro
     '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent || 'none',
     '--provider', provider || 'claude',
+    ...(model ? ['--model', model] : []),
+    ...(strictProvider ? ['--strict-provider'] : []),
     '--timeout', String(timeout || 900000),
   ];
   return parts.join(' ');
@@ -600,7 +607,19 @@ const AGENT_MODEL_MAP = {
  * Resolve provider and model for an agent.
  * Checks config.yaml for agent_overrides, falls back to AGENT_MODEL_MAP defaults.
  */
-function resolveAgentModel(agent, projectDir) {
+export function resolveAgentModel(agent, projectDir) {
+  const v2Artifact = loadRuntimeInstallationV2(projectDir);
+  if (v2Artifact) {
+    const invocation = resolveRuntimeInvocationV2({ artifact: v2Artifact, agent });
+    return {
+      provider: invocation.harness_id,
+      provider_id: invocation.provider_id,
+      model: invocation.model_pin.model_id,
+      reasoning_configuration: invocation.model_pin.reasoning_configuration,
+      catalog_snapshot_ref: invocation.model_pin.catalog_snapshot_ref,
+      source: 'installation-v2',
+    };
+  }
   const defaults = AGENT_MODEL_MAP[agent] || { provider: 'claude', model: 'sonnet', upgrade: '' };
 
   // Check config.yaml for agent_overrides
@@ -816,7 +835,10 @@ async function _handleNextInner(projectDir) {
         agent,
         agent_file: agentFile,
         phase: agentDef?.phase || session.mode,
-        spawn_command: isInteractive ? null : buildSpawnCommand(agent, projectDir, session.last_handoff || 'none', resolveAgentModel(agent, projectDir).provider, 600000),
+        spawn_command: isInteractive ? null : (() => {
+          const modelInfo = resolveAgentModel(agent, projectDir);
+          return buildSpawnCommand(agent, projectDir, session.last_handoff || 'none', modelInfo.provider, 600000, modelInfo.model, modelInfo.source === 'installation-v2');
+        })(),
         parallel_spawn_command: null,
         parallel_agents: [],
         handoff_status: { valid: true, missing: [], warnings: ['Resuming in-progress agent'] },
@@ -926,7 +948,7 @@ async function _handleNextInner(projectDir) {
     } else {
       action = 'spawn_parallel';
       parallelAgents = nextInfo.group;
-      parallelSpawnCommand = buildParallelSpawnCommand(nextInfo.group, projectDir, lastAgent, modelInfo.provider, 900000);
+      parallelSpawnCommand = buildParallelSpawnCommand(nextInfo.group, projectDir, lastAgent, modelInfo.provider, 900000, modelInfo.model, modelInfo.source === 'installation-v2');
     }
   } else if (nextAgent === 'dev' && teamsEnabled) {
     // Build Team auto-spawn: dev + qa-implementation are NOT parallel in the
@@ -943,7 +965,7 @@ async function _handleNextInner(projectDir) {
     action = 'activate_interactive';
   } else {
     action = 'spawn_autonomous';
-    spawnCommand = buildSpawnCommand(nextAgent, projectDir, lastAgent, modelInfo.provider, 600000);
+    spawnCommand = buildSpawnCommand(nextAgent, projectDir, lastAgent, modelInfo.provider, 600000, modelInfo.model, modelInfo.source === 'installation-v2');
   }
 
   // Surface criteria (Article XVII): even in autonomous mode, a high-stakes
@@ -1346,6 +1368,35 @@ async function handleAdvance(projectDir, args) {
 
   // Deterministic gates: block advance if required artifacts are missing.
 
+  // V2 replaces the legacy Build/Deploy entry with a sealed, project-local
+  // RAIL handoff. QA Planning validates planning quality, but the Tasks agent
+  // is the first stage that produces the structured task graph required by
+  // the compiler. Sealing at qa-planning therefore races the normal pipeline
+  // and can only produce a false missing-artifact block.
+  //
+  // The compiler is deliberately strict: prose planning cannot become
+  // executable work without task-level scope, criteria, estimates,
+  // dependencies and ClickUp references.
+  if (agent === 'tasks' && status === 'completed' && score >= 95 && loadRuntimeInstallationV2(projectDir)) {
+    try {
+      const handoff = compilePlanningHandoff({ projectDir });
+      handoffData.rail_handoff = persistRailHandoff({ projectDir, handoff });
+    } catch (error) {
+      return {
+        advanced: false,
+        blocked: true,
+        reason: error.code || 'RAIL_HANDOFF_COMPILATION_FAILED',
+        message: error.message,
+        expected_artifact: PLANNING_V2_TASKS_PATH,
+        action_required: {
+          owner: 'Tasks and QA Planning agents',
+          artifact: PLANNING_V2_TASKS_PATH,
+          requirements: ['source artifacts', 'task IDs and dependencies', 'Given-When-Then criteria', 'execution scopes', 'AI and human estimates', 'ClickUp references'],
+        },
+      };
+    }
+  }
+
   // BRIEF gate: reference frames captured → Visualizer MUST run for ALL sites before Brief advances.
   if (agent === 'brief') {
     const refsDir = join(projectDir, 'artifacts', '4-UX', 'references');
@@ -1773,6 +1824,35 @@ async function handleAdvance(projectDir, args) {
   await recordAgentCompletion(projectDir, { agent, status, score, handoffData });
   recordEvent(projectDir, EventType.AGENT_COMPLETED, agent, { score, status });
 
+  // A v2 task graph has become an immutable RAIL handoff. Do not silently
+  // continue into the legacy BUILD/DEPLOY agent chain: that would create two
+  // competing execution authorities for the same plan. The caller receives
+  // the handoff identifier and must enter the project-local RAIL lifecycle.
+  if (handoffData.rail_handoff) {
+    const railState = {
+      current_agent: 'rail',
+      last_handoff: agent,
+      pipeline_position: (session.completed_agents || []).length + 1,
+      rail_handoff_id: handoffData.rail_handoff.handoff.handoff_id,
+      rail_handoff_path: handoffData.rail_handoff.path,
+      rail_state: 'ready',
+    };
+    const saved = await updateSession(projectDir, railState);
+    if (saved && saved.saved === false) return errorResult(`Session update failed: ${saved.error}`, 'SESSION_WRITE_FAILED');
+    return {
+      advanced: true,
+      agent_completed: agent,
+      score,
+      rail_ready: true,
+      rail_handoff: handoffData.rail_handoff,
+      next: {
+        action: 'rail_execute',
+        handoff_id: handoffData.rail_handoff.handoff.handoff_id,
+        reason: 'v2 planning is sealed; RAIL is now the sole execution authority',
+      },
+    };
+  }
+
   // Fase 10 — Scaffold auto-gate. After qa-planning completes, check whether
   // a scaffold preset has cleared the confidence threshold and is still
   // unapplied. If so, return an action_required response with the 3-option
@@ -2551,7 +2631,12 @@ function generateTeamId(slug) {
  * providers would fail. We always fall back silently to spawn_parallel
  * (Gemini) or spawn_autonomous (Codex) when the active provider is not claude.
  */
-function isAgentTeamsEnabled(projectDir) {
+export function isAgentTeamsEnabled(projectDir) {
+  // The v1 Agent Teams runner is Claude-specific. Provider-neutral v2 routes
+  // parallel work through the regular strict-provider runner until its own
+  // team coordinator exists. It must never silently use Claude's native team
+  // semantics for a Codex- or Grok-selected installation.
+  if (loadRuntimeInstallationV2(projectDir)) return false;
   const configPath = join(projectDir, resolveFrameworkDir(projectDir), 'config.yaml');
   if (!existsSync(configPath)) return false;
   const raw = readFileSync(configPath, 'utf-8');

package/src/orchestrator/clickup-projection.js

@@ -0,0 +1,84 @@
+import { join } from 'node:path';
+import { sha256 } from '@chati/core';
+import { TrackingClickUp } from '@chati/tracking-clickup';
+
+function handoffAttemptIds(records, handoffId) {
+  return new Set(records.filter((record) => record.type === 'attempt_claimed' && record.payload?.attempt?.handoff_id === handoffId).map((record) => record.payload.attempt.attempt_id));
+}
+
+function taskState(records, handoffId, taskId) {
+  const attempts = handoffAttemptIds(records, handoffId);
+  const attempt = records.filter((record) => (record.payload?.attempt?.task_id === taskId && record.payload.attempt.handoff_id === handoffId)
+    || (record.payload?.completion?.task_id === taskId && attempts.has(record.payload.completion.attempt_id))).at(-1);
+  if (!attempt) return 'pending';
+  if (attempt.type === 'attempt_completed') return attempt.payload.completion.state;
+  return 'active';
+}
+
+function completionIsCanonical(records, completion) {
+  if (!completion || typeof completion !== 'object' || typeof completion.completion_id !== 'string') return false;
+  const material = { ...completion };
+  delete material.event_id;
+  delete material.immutable_ref;
+  return records.some((record) => record.type === 'attempt_completed'
+    && record.payload?.completion?.completion_id === completion.completion_id
+    && sha256(record.payload.completion) === sha256(material));
+}
+
+function journalBlockers(records, handoffId, taskId) {
+  const attempts = handoffAttemptIds(records, handoffId);
+  return records
+    .filter((record) => (record.type === 'attempt_blocked' || record.type === 'attempt_cancelled') && record.payload?.attempt_id)
+    .filter((record) => attempts.has(record.payload.attempt_id)
+      && records.some((claim) => claim.type === 'attempt_claimed' && claim.payload?.attempt?.attempt_id === record.payload.attempt_id && claim.payload.attempt.task_id === taskId))
+    .map((record) => `${record.type}:${record.payload.attempt_id}`);
+}
+
+function journalDecisions(records, handoffId, taskId) {
+  const attempts = handoffAttemptIds(records, handoffId);
+  return records
+    .filter((record) => record.type === 'review_decided' && record.payload?.task_id === taskId && attempts.has(record.payload.attempt_id))
+    .map((record) => ({
+      decision_ref: `rail-review-decision://${handoffId}/${record.event_id}`,
+      decision: record.payload.decision.decision,
+      review_ref: record.payload.review_ref,
+    }));
+}
+
+export function enqueueClickUpProjectionFromState({ projectDir, handoff, records, task_id, attempt_id, operation = 'update', payload, completion, decisions, clock = () => new Date() } = {}) {
+  const task = handoff.tasks.find((item) => item.task_id === task_id);
+  if (!task) throw Object.assign(new Error(`task ${task_id} is absent from handoff`), { code: 'TASK_NOT_FOUND' });
+  const handoff_ref = `rail-handoff://${handoff.handoff_id}/${handoff.seal.manifest_digest}`;
+  const journal_ref = `rail-journal://sha256/${sha256(records)}`;
+  const derivedDecisions = journalDecisions(records, handoff.handoff_id, task_id);
+  // Canonical journal decisions always win over caller-supplied annotations
+  // sharing the same identity.
+  const normalizedDecisions = [...new Map([...(decisions || []), ...derivedDecisions].map((item) => [item.decision_ref, item])).values()];
+  const refs = new Set([
+    handoff_ref,
+    journal_ref,
+    ...derivedDecisions.flatMap((item) => [item.decision_ref, item.review_ref]),
+    ...(completion?.reviews || []),
+    ...(completion?.acceptance_evidence_refs || []),
+  ]);
+  const tracking = new TrackingClickUp({
+    outbox_path: join(projectDir, '.chati/v2/tracking/clickup-outbox.json'),
+    project_evolution_dir: join(projectDir, '.chati/v2/project-evolution'),
+    clock, verify_completion: (candidate) => completionIsCanonical(records, candidate),
+    verify_reference: (ref) => refs.has(ref),
+    resolve_reference: (ref, type) => type === 'handoff'
+      ? { phase: 'rail-execution', handoff_id: handoff.handoff_id }
+      : { task_state: taskState(records, handoff.handoff_id, task_id), blockers: journalBlockers(records, handoff.handoff_id, task_id) },
+  });
+  const projection = tracking.enqueue({
+    projection_id: `clickup-${sha256({ handoff_id: handoff.handoff_id, task_id, attempt_id, operation, payload }).slice(0, 24)}`,
+    idempotency_key: `clickup:${handoff.handoff_id}:${task_id}:${attempt_id}:${operation}:${completion?.state || payload?.status || 'active'}`,
+    canonical_event_id: `rail:${sha256(records).slice(0, 24)}`,
+    task_id, attempt_id, clickup_ref: task.clickup_ref, operation, payload, completion, decisions: normalizedDecisions,
+    project_id: handoff.project_id, handoff_ref, journal_ref,
+  });
+  if (operation === 'close' && completion?.metrics) {
+    return tracking.recordMetrics({ projection_id: projection.projection_id, completion, ...completion.metrics });
+  }
+  return projection;
+}

package/src/orchestrator/clickup-runtime.js

@@ -0,0 +1,13 @@
+import { createProjectRailEngine, loadRailHandoff } from './rail-runtime.js';
+import { enqueueClickUpProjectionFromState } from './clickup-projection.js';
+
+/** Enqueues a durable local ClickUp projection. It never sends to ClickUp. */
+export function enqueueClickUpProjection({ projectDir, handoff_id, task_id, attempt_id, operation = 'update', payload, completion, decisions, clock = () => new Date() } = {}) {
+  const { handoff } = loadRailHandoff({ projectDir, handoff_id });
+  const records = createProjectRailEngine({ projectDir, clock }).records;
+  return enqueueClickUpProjectionFromState({
+    projectDir, handoff, records, task_id, attempt_id, operation, payload, completion, decisions, clock,
+  });
+}
+
+export { enqueueClickUpProjectionFromState } from './clickup-projection.js';

package/src/orchestrator/knowledge-runtime.js

@@ -0,0 +1,64 @@
+import { emitLocalLearningCandidate, validateKnowledgeRetrievalRequest } from '@chati/knowledge-context';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { createProjectRailEngine, loadRailHandoff } from './rail-runtime.js';
+
+function fail(code, message) {
+  throw Object.assign(new Error(message), { code });
+}
+
+function railCandidateWithVerifiedLineage({ projectDir, candidate, handoff_id, task_id, attempt_id, clock }) {
+  if (candidate?.origin !== 'rail-evidence') return candidate;
+  for (const [name, value] of Object.entries({ handoff_id, task_id, attempt_id })) {
+    if (typeof value !== 'string' || value.trim() === '') fail('RAIL_CANDIDATE_LINEAGE_REQUIRED', `${name} is required for rail-evidence candidates`);
+  }
+  const { handoff } = loadRailHandoff({ projectDir, handoff_id });
+  if (!handoff.tasks.some((task) => task.task_id === task_id)) fail('RAIL_CANDIDATE_TASK_NOT_FOUND', 'candidate task is absent from the sealed handoff');
+  const engine = createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) });
+  const claim = engine.records.find((record) => record.type === 'attempt_claimed'
+    && record.payload?.attempt?.attempt_id === attempt_id
+    && record.payload.attempt.handoff_id === handoff_id
+    && record.payload.attempt.task_id === task_id);
+  if (!claim) fail('RAIL_CANDIDATE_ATTEMPT_NOT_FOUND', 'candidate attempt has no matching project-local RAIL claim');
+  const lineage_refs = [...new Set([
+    ...(candidate.lineage_refs || []),
+    `rail-handoff://${handoff_id}/${handoff.seal.manifest_digest}`,
+    `rail-task://${handoff_id}/${task_id}`,
+    `rail-attempt://${handoff_id}/${attempt_id}/${claim.event_id}`,
+  ])];
+  return { ...candidate, lineage_refs };
+}
+
+/**
+ * CHATI's knowledge boundary. Retrieval is delegated to an injected read-only
+ * adapter. Candidate emission is project-local and never promotes to a Brain.
+ */
+export function retrieveProjectKnowledge({ projectDir, request, adapter, clock = () => new Date() } = {}) {
+  const installation = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!installation) throw Object.assign(new Error('knowledge retrieval requires a v2 installation'), { code: 'V2_INSTALLATION_REQUIRED' });
+  const capability = installation.brain_read_capability;
+  if (capability?.status !== 'configured') return Object.freeze({ state: 'not-configured', returned_learning_refs: [] });
+  if (capability.mode !== 'read-only') fail('BRAIN_WRITE_FORBIDDEN', 'knowledge capability must remain read-only at retrieval time');
+  if (!adapter || adapter.mode !== 'read-only' || typeof adapter.retrieve !== 'function') fail('KNOWLEDGE_ADAPTER_UNAVAILABLE', 'an explicitly read-only knowledge adapter is required');
+  const callableCapabilities = new Set();
+  for (let cursor = adapter; cursor && cursor !== Object.prototype; cursor = Object.getPrototypeOf(cursor)) {
+    for (const key of Reflect.ownKeys(cursor)) {
+      if (key !== 'constructor' && typeof adapter[key] === 'function') callableCapabilities.add(key);
+    }
+  }
+  const mutatingCapabilities = [...callableCapabilities].filter((key) => key !== 'retrieve');
+  if (mutatingCapabilities.length > 0) fail('BRAIN_WRITE_FORBIDDEN', 'knowledge adapter may expose only the retrieve capability');
+  const validated = validateKnowledgeRetrievalRequest(request);
+  if (validated.policy_ref !== capability.policy_ref) fail('KNOWLEDGE_POLICY_MISMATCH', 'retrieval policy_ref must match the installed Brain read capability');
+  const receipt = adapter.retrieve(validated);
+  if (!receipt || typeof receipt !== 'object' || receipt.policy_ref !== capability.policy_ref || receipt.retrieval_id !== validated.retrieval_id) {
+    fail('INVALID_KNOWLEDGE_RECEIPT', 'knowledge receipt must remain bound to the installed policy and retrieval request');
+  }
+  return Object.freeze(receipt);
+}
+
+export function emitProjectKnowledgeCandidate({ projectDir, candidate, handoff_id, task_id, attempt_id, clock } = {}) {
+  const installation = loadRuntimeInstallationV2(projectDir, { ...(clock === undefined ? {} : { clock }) });
+  if (!installation) throw Object.assign(new Error('knowledge candidate emission requires a v2 installation'), { code: 'V2_INSTALLATION_REQUIRED' });
+  const verified = railCandidateWithVerifiedLineage({ projectDir, candidate, handoff_id, task_id, attempt_id, clock });
+  return emitLocalLearningCandidate({ project_dir: projectDir, candidate: verified });
+}

package/src/orchestrator/planning-runtime.js

@@ -0,0 +1,127 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sha256 } from '@chati/core';
+import { sealHandoff } from '@chati/planning';
+import { assertEligibleInvocation } from '@chati/provider-registry';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+
+export const PLANNING_V2_TASKS_PATH = '.chati/v2/planning/tasks.json';
+
+function fail(code, message, cause) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  throw error;
+}
+
+function readJson(path, code) {
+  if (!existsSync(path)) fail(code, `missing required planning artifact: ${path}`);
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch (error) { return fail(code, `invalid JSON planning artifact: ${path}`, error); }
+}
+
+function immutableFileRef(projectDir, relativePath, code) {
+  if (typeof relativePath !== 'string' || relativePath.trim() === '') fail(code, 'planning source path is required');
+  const path = join(projectDir, relativePath);
+  if (!existsSync(path)) fail(code, `planning source file does not exist: ${relativePath}`);
+  return `local-artifact://sha256/${sha256(readFileSync(path, 'utf8'))}`;
+}
+
+function criterionRef(taskId, criterion) {
+  if (typeof criterion === 'string' && criterion.trim()) return `local-artifact://sha256/${sha256({ task_id: taskId, criterion })}`;
+  if (criterion && typeof criterion === 'object' && ['given', 'when', 'then'].every((field) => typeof criterion[field] === 'string' && criterion[field].trim())) {
+    return `local-artifact://sha256/${sha256({ task_id: taskId, criterion })}`;
+  }
+  return fail('INVALID_PLANNING_TASK', `task ${taskId} has an invalid acceptance criterion`);
+}
+
+function gitCommit(projectDir) {
+  try { return execFileSync('git', ['-C', projectDir, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch (error) { return fail('MISSING_GIT_COMMIT', 'Planning-to-RAIL handoff requires a local Git commit', error); }
+}
+
+function taskExecutionBinding(task, installation, clock) {
+  const binding = task.execution_binding;
+  if (!binding || typeof binding !== 'object' || Array.isArray(binding)) {
+    fail('TASK_EXECUTION_BINDING_REQUIRED', `task ${task.id} must select an execution binding`);
+  }
+  for (const field of ['provider_id', 'harness_id', 'model_id', 'reasoning_configuration']) {
+    if (typeof binding[field] !== 'string' || !binding[field].trim()) {
+      fail('TASK_EXECUTION_BINDING_REQUIRED', `task ${task.id} execution_binding.${field} is required`);
+    }
+  }
+  const invocation = {
+    provider_id: binding.provider_id,
+    harness_id: binding.harness_id,
+    action: 'build',
+    model_pin: {
+      model_id: binding.model_id,
+      catalog_snapshot_ref: installation.capability_snapshot.snapshot_id,
+      reasoning_configuration: binding.reasoning_configuration,
+    },
+  };
+  try {
+    assertEligibleInvocation({ installation: installation.installation, snapshot: installation.capability_snapshot, invocation, clock });
+  } catch (error) {
+    fail(error.code || 'TASK_EXECUTION_BINDING_INVALID', `task ${task.id} has an ineligible execution binding: ${error.message}`, error);
+  }
+  return binding;
+}
+
+/**
+ * Compiles the structured output of the Tasks agent into the only artifact the
+ * RAIL runtime accepts. It does not infer scope, criteria, estimates, ClickUp
+ * mapping, or dependencies from prose.
+ */
+export function compilePlanningHandoff({ projectDir, clock = () => new Date() } = {}) {
+  const installation = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!installation) fail('V2_INSTALLATION_REQUIRED', 'planning-to-RAIL compilation requires a v2 installation');
+  const inputPath = join(projectDir, PLANNING_V2_TASKS_PATH);
+  const planning = readJson(inputPath, 'PLANNING_TASK_GRAPH_REQUIRED');
+  if (!Array.isArray(planning.tasks) || planning.tasks.length === 0) fail('PLANNING_TASK_GRAPH_REQUIRED', 'planning tasks must be a non-empty array');
+  if (!planning.source_artifacts || typeof planning.source_artifacts !== 'object') fail('PLANNING_SOURCE_ARTIFACTS_REQUIRED', 'planning source_artifacts are required');
+  const sources = planning.source_artifacts;
+  const source_artifacts = {
+    requirements_ref: immutableFileRef(projectDir, sources.requirements_path, 'PLANNING_SOURCE_ARTIFACTS_REQUIRED'),
+    architecture_ref: immutableFileRef(projectDir, sources.architecture_path, 'PLANNING_SOURCE_ARTIFACTS_REQUIRED'),
+    qa_plan_ref: immutableFileRef(projectDir, sources.qa_plan_path, 'PLANNING_SOURCE_ARTIFACTS_REQUIRED'),
+  };
+  if (sources.ux_path) source_artifacts.ux_ref = immutableFileRef(projectDir, sources.ux_path, 'PLANNING_SOURCE_ARTIFACTS_REQUIRED');
+  const ids = new Set();
+  const clickupRequired = installation.installation.profile === 'focus-ai-internal'
+    && installation.installation.external_integrations?.clickup === 'required';
+  const tasks = planning.tasks.map((task) => {
+    if (!task || typeof task !== 'object' || typeof task.id !== 'string' || !task.id.trim() || ids.has(task.id)) fail('INVALID_PLANNING_TASK', 'each planning task needs a unique id');
+    ids.add(task.id);
+    if (!Array.isArray(task.criteria) || task.criteria.length === 0) fail('INVALID_PLANNING_TASK', `task ${task.id} must have acceptance criteria`);
+    if (typeof task.execution_scope_ref !== 'string' || !task.execution_scope_ref.trim()) fail('INVALID_PLANNING_TASK', `task ${task.id} must have execution_scope_ref`);
+    if (clickupRequired && (typeof task.clickup_ref !== 'string' || !task.clickup_ref.trim())) fail('MISSING_CLICKUP_REFERENCE', `internal task ${task.id} must have clickup_ref`);
+    if (task.clickup_ref !== undefined && (typeof task.clickup_ref !== 'string' || !task.clickup_ref.trim())) fail('INVALID_CLICKUP_REFERENCE', `task ${task.id} clickup_ref must be a non-empty string when provided`);
+    if (!task.estimate || task.estimate.ai_processing == null || task.estimate.human_effort == null || task.estimate.uncertainty == null) fail('INVALID_PLANNING_TASK', `task ${task.id} must have ai_processing, human_effort and uncertainty estimates`);
+    return {
+      task_id: task.id,
+      dependency_ids: task.dependencies ?? [],
+      acceptance_criteria_refs: task.criteria.map((criterion) => criterionRef(task.id, criterion)),
+      execution_scope_ref: task.execution_scope_ref,
+      routing_constraints_ref: task.routing_constraints_ref || `policy://installation/${installation.installation.installation_id}/task/${task.id}`,
+      execution_binding: taskExecutionBinding(task, installation, clock),
+      estimate: task.estimate,
+      ...(task.clickup_ref === undefined ? {} : { clickup_ref: task.clickup_ref }),
+      ...(task.requires_browser === undefined ? {} : { requires_browser: task.requires_browser }),
+      ...(task.browser_policy === undefined ? {} : { browser_policy: task.browser_policy }),
+    };
+  });
+  const commit = gitCommit(projectDir);
+  const task_graph_ref = `local-artifact://sha256/${sha256(readFileSync(inputPath, 'utf8'))}`;
+  const handoff_id = planning.handoff_id || `handoff-${sha256({ project_id: installation.project_id, task_graph_ref, git_commit_ref: commit }).slice(0, 24)}`;
+  const now = clock();
+  const sealedAt = (now instanceof Date ? now : new Date(now)).toISOString();
+  return sealHandoff({
+    handoff_id,
+    version: planning.version || '1.0.0',
+    project_id: installation.project_id,
+    source_artifacts,
+    task_graph_ref,
+    tasks,
+    seal: { sealed_by: planning.sealed_by || 'actor://chati/qa-planning', sealed_at: sealedAt, git_commit_ref: commit },
+  });
+}