chati-dev 4.5.28 → 4.5.29

package/src/orchestrator/planning-runtime.js

@@ -1,13 +1,20 @@
 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 { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { canonicalSerialize, sha256 } from '@chati/core';
+import { sealHandoff, validateTaskVerificationPlan, validateTaskBrowserVerificationPlan } from '@chati/planning';
 import { assertEligibleInvocation } from '@chati/provider-registry';
-import { assertV2PlanningPredecessors, loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { persistImmutableInstallationFile, readSafeInstallationStorageFile, replaceInstallationStorageFile } from '../installer-v2/catalog-client.js';
+import { assertV2PlanningPredecessors, loadRuntimeInstallationV2, resolveRuntimeTaskRouteV2 } from './runtime-installation-v2.js';
 import { loadSession } from './session-manager.js';
+import { openPinnedProviderExecutable } from '../installer-v2/provider-executable.js';
 
 export const PLANNING_V2_TASKS_PATH = '.chati/v2/planning/tasks.json';
+export const PLANNING_V2_TASKS_CANDIDATE_PATH = 'artifacts/6-Tasks/tasks.json';
+const PLANNING_RUNTIME_SECURITY_TEST_HOOKS = Symbol.for('chati.planning-runtime.security-test-hooks');
+const PLANNING_ARTIFACT_MAX_BYTES = 4 * 1024 * 1024;
+const STRICT_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 
 function fail(code, message, cause) {
   const error = new Error(message, cause ? { cause } : undefined);
@@ -25,16 +32,237 @@ function trustedGitEnvironment(source = process.env) {
   };
 }
 
-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 runPlanningSecurityTestHook(name, payload) {
+  const hook = globalThis[PLANNING_RUNTIME_SECURITY_TEST_HOOKS]?.[name];
+  if (typeof hook === 'function') hook(payload);
 }
 
-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 sameDirectory(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino && left?.isDirectory?.() && right?.isDirectory?.();
+}
+
+function openPinnedPlanningProjectRoot(projectDir) {
+  const path = resolve(projectDir);
+  let descriptor;
+  try {
+    const before = lstatSync(path, { bigint: true });
+    if (!before.isDirectory() || before.isSymbolicLink()) {
+      fail('UNSAFE_PLANNING_PROJECT_ROOT', 'planning requires a real project directory');
+    }
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+    const opened = fstatSync(descriptor, { bigint: true });
+    if (!sameDirectory(before, opened)) {
+      fail('UNSAFE_PLANNING_PROJECT_ROOT', 'planning project directory changed before it could be pinned');
+    }
+    return {
+      path,
+      descriptor,
+      identity: opened,
+      reference: process.platform === 'linux' ? `/proc/self/fd/${descriptor}` : path,
+      artifactSnapshots: [],
+    };
+  } catch (error) {
+    if (descriptor !== undefined) closeSync(descriptor);
+    if (error?.code?.startsWith?.('UNSAFE_PLANNING_')) throw error;
+    return fail('UNSAFE_PLANNING_PROJECT_ROOT', 'planning project directory cannot be opened safely', error);
+  }
+}
+
+function assertPinnedPlanningProjectRoot(project) {
+  const opened = fstatSync(project.descriptor, { bigint: true });
+  const current = lstatSync(project.path, { bigint: true });
+  if (!sameDirectory(project.identity, opened) || !sameDirectory(project.identity, current) || current.isSymbolicLink()) {
+    fail('UNSAFE_PLANNING_PROJECT_ROOT', 'planning project directory changed during compilation');
+  }
+}
+
+function samePlanningFileSnapshot(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino
+    && left?.size === right?.size && left?.mode === right?.mode
+    && left?.nlink === right?.nlink
+    && left?.mtimeNs === right?.mtimeNs && left?.ctimeNs === right?.ctimeNs;
+}
+
+function relativePlanningArtifact(project, relativePath, code) {
+  if (typeof relativePath !== 'string' || relativePath.trim() === '' || isAbsolute(relativePath)) {
+    fail(code, 'planning artifact path must be a non-empty relative path');
+  }
+  const absolute = resolve(project.path, relativePath);
+  const boundary = relative(project.path, absolute);
+  if (!boundary || boundary === '..' || boundary.startsWith(`..${sep}`) || isAbsolute(boundary)) {
+    fail(code, `planning artifact path escapes the project: ${relativePath}`);
+  }
+  return boundary;
+}
+
+function snapshotNamedPlanningArtifact(project, safeRelative, label) {
+  const segments = safeRelative.split(sep).filter(Boolean);
+  const snapshots = [];
+  let current = project.path;
+  for (let index = 0; index < segments.length; index += 1) {
+    current = join(current, segments[index]);
+    const final = index === segments.length - 1;
+    let stat;
+    try { stat = lstatSync(current, { bigint: true }); }
+    catch (error) {
+      return fail('UNSAFE_PLANNING_ARTIFACT', `cannot safely resolve ${label}`, error);
+    }
+    if (stat.isSymbolicLink() || (final ? !stat.isFile() || stat.nlink !== 1n : !stat.isDirectory())) {
+      fail('UNSAFE_PLANNING_ARTIFACT', `${label} path must contain only real directories and a single-link regular file`);
+    }
+    snapshots.push(Object.freeze({ path: current, final, stat }));
+  }
+  return Object.freeze(snapshots);
+}
+
+function samePlanningDirectorySnapshot(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino && left?.isDirectory?.() && right?.isDirectory?.();
+}
+
+function closePlanningArtifactDescriptors(artifact) {
+  for (const item of [...(artifact?.opened ?? [])].reverse()) {
+    try { closeSync(item.descriptor); } catch { /* preserve the original result */ }
+  }
+}
+
+function assertNamedPlanningArtifact(project, artifact) {
+  for (const snapshot of artifact.snapshots) {
+    let current;
+    try { current = lstatSync(snapshot.path, { bigint: true }); }
+    catch (error) {
+      return fail('UNSAFE_PLANNING_ARTIFACT', `${artifact.label} path changed during compilation`, error);
+    }
+    const valid = snapshot.final
+      ? !current.isSymbolicLink() && current.isFile() && current.nlink === 1n && samePlanningFileSnapshot(snapshot.stat, current)
+      : !current.isSymbolicLink() && current.isDirectory() && current.dev === snapshot.stat.dev && current.ino === snapshot.stat.ino;
+    if (!valid) fail('UNSAFE_PLANNING_ARTIFACT', `${artifact.label} path changed during compilation`);
+  }
+  for (const opened of artifact.opened) {
+    let current;
+    try { current = fstatSync(opened.descriptor, { bigint: true }); }
+    catch (error) {
+      return fail('UNSAFE_PLANNING_ARTIFACT', `${artifact.label} descriptor changed during compilation`, error);
+    }
+    const valid = opened.final
+      ? samePlanningFileSnapshot(opened.stat, current)
+      : samePlanningDirectorySnapshot(opened.stat, current);
+    if (!valid) fail('UNSAFE_PLANNING_ARTIFACT', `${artifact.label} descriptor changed during compilation`);
+  }
+  assertPinnedPlanningProjectRoot(project);
+  return undefined;
+}
+
+function assertAllNamedPlanningArtifacts(project) {
+  for (const artifact of project.artifactSnapshots) {
+    assertNamedPlanningArtifact(project, artifact);
+  }
+}
+
+function descriptorRelativePlanningPath(project, descriptor, segments, index) {
+  if (process.platform === 'linux') return join(`/proc/self/fd/${descriptor}`, segments[index]);
+  return join(project.path, ...segments.slice(0, index + 1));
+}
+
+function readPinnedPlanningArtifactDescriptor(descriptor, snapshot, label) {
+  const before = fstatSync(descriptor, { bigint: true });
+  if (!samePlanningFileSnapshot(snapshot, before) || !before.isFile() || before.nlink !== 1n) {
+    fail('UNSAFE_PLANNING_ARTIFACT', `${label} changed before it could be read`);
+  }
+  if (before.size > BigInt(PLANNING_ARTIFACT_MAX_BYTES)) {
+    fail('PLANNING_ARTIFACT_SIZE_LIMIT', `${label} exceeds the ${PLANNING_ARTIFACT_MAX_BYTES} byte safety limit`);
+  }
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, PLANNING_ARTIFACT_MAX_BYTES + 1 - total));
+    const count = readSync(descriptor, buffer, 0, buffer.length, null);
+    if (count === 0) break;
+    total += count;
+    if (total > PLANNING_ARTIFACT_MAX_BYTES) {
+      fail('PLANNING_ARTIFACT_SIZE_LIMIT', `${label} exceeds the ${PLANNING_ARTIFACT_MAX_BYTES} byte safety limit`);
+    }
+    chunks.push(buffer.subarray(0, count));
+  }
+  const after = fstatSync(descriptor, { bigint: true });
+  if (!samePlanningFileSnapshot(before, after)) {
+    fail('UNSAFE_PLANNING_ARTIFACT', `${label} changed while it was being read`);
+  }
+  try { return STRICT_UTF8.decode(Buffer.concat(chunks, total)); }
+  catch (error) { return fail('UNSAFE_PLANNING_ARTIFACT', `${label} must contain valid UTF-8 without lossy replacement`, error); }
+}
+
+function readPinnedPlanningArtifact(project, relativePath, code, label) {
+  const safeRelative = relativePlanningArtifact(project, relativePath, code);
+  const snapshots = snapshotNamedPlanningArtifact(project, safeRelative, label);
+  const segments = safeRelative.split(sep).filter(Boolean);
+  const opened = [];
+  try {
+    // Traverse once from the already pinned project root.  Every descriptor
+    // read below is compared to the pathname snapshot made immediately before
+    // opening it, so a swap between lstat and open cannot change the bytes
+    // that are later sealed into a handoff.
+    runPlanningSecurityTestHook('beforePinnedPlanningArtifactOpen', { relativePath: safeRelative, label });
+    let parent = openSync(project.reference, constants.O_RDONLY | (constants.O_DIRECTORY || 0)
+      | (process.platform === 'linux' ? 0 : (constants.O_NOFOLLOW || 0)));
+    let root;
+    try { root = fstatSync(parent, { bigint: true }); }
+    catch (error) {
+      closeSync(parent);
+      throw error;
+    }
+    if (!samePlanningDirectorySnapshot(project.identity, root)) {
+      closeSync(parent);
+      fail('UNSAFE_PLANNING_PROJECT_ROOT', 'planning project directory changed before an artifact could be opened');
+    }
+    opened.push(Object.freeze({ descriptor: parent, stat: root, final: false }));
+    for (let index = 0; index < segments.length; index += 1) {
+      const final = index === segments.length - 1;
+      let descriptor;
+      try {
+        descriptor = openSync(
+          descriptorRelativePlanningPath(project, parent, segments, index),
+          constants.O_RDONLY | (final ? 0 : (constants.O_DIRECTORY || 0)) | (constants.O_NOFOLLOW || 0) | (final ? (constants.O_NONBLOCK || 0) : 0),
+        );
+        const stat = fstatSync(descriptor, { bigint: true });
+        const expected = snapshots[index].stat;
+        const valid = final
+          ? samePlanningFileSnapshot(expected, stat) && stat.isFile() && stat.nlink === 1n
+          : samePlanningDirectorySnapshot(expected, stat);
+        if (!valid) {
+          fail('UNSAFE_PLANNING_ARTIFACT', `${label} changed before it could be opened`);
+        }
+        opened.push(Object.freeze({ descriptor, stat, final }));
+        parent = descriptor;
+        descriptor = undefined;
+      } finally {
+        if (descriptor !== undefined) closeSync(descriptor);
+      }
+    }
+    const artifact = Object.freeze({ snapshots, opened: Object.freeze(opened), label });
+    const content = readPinnedPlanningArtifactDescriptor(parent, snapshots.at(-1).stat, label);
+    runPlanningSecurityTestHook('afterPinnedPlanningArtifactRead', { relativePath: safeRelative, label });
+    assertNamedPlanningArtifact(project, artifact);
+    project.artifactSnapshots.push(Object.freeze({ ...artifact, content, relativePath: safeRelative }));
+    return content;
+  } catch (error) {
+    closePlanningArtifactDescriptors({ opened });
+    return fail(error.code || code, `cannot safely read ${label}: ${error.message}`, error);
+  }
+}
+
+function readJsonSnapshot(project, relativePath, code) {
+  const content = readPinnedPlanningArtifact(project, relativePath, code, 'planning task graph');
+  try {
+    const value = JSON.parse(content);
+    runPlanningSecurityTestHook('afterPlanningTaskGraphSnapshot', { path: relativePath, content });
+    return Object.freeze({ value, content });
+  } catch (error) {
+    return fail(code, `invalid JSON planning artifact: ${relativePath}`, error);
+  }
+}
+
+function immutableFileRef(project, relativePath, code) {
+  return `local-artifact://sha256/${sha256(readPinnedPlanningArtifact(project, relativePath, code, 'planning source artifact'))}`;
 }
 
 function criterionRef(taskId, criterion) {
@@ -78,28 +306,179 @@ function taskExecutionBinding(task, installation, clock) {
   return binding;
 }
 
+function planningUsesExecutionDesignV2(planning) {
+  const major = Number.parseInt(String(planning?.version || '1').split('.')[0], 10);
+  return Number.isInteger(major) && major >= 2;
+}
+
+function installationRequiresExecutionDesignV2(installation) {
+  return installation?.installation?.quality_council !== undefined;
+}
+
+function taskRoutingProfile(task) {
+  if (!task.routing_profile || typeof task.routing_profile !== 'object' || Array.isArray(task.routing_profile)) {
+    fail('TASK_ROUTING_PROFILE_REQUIRED', `task ${task.id} must declare a routing_profile for the signed catalog router`);
+  }
+  return task.routing_profile;
+}
+
+function durationRange(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('INVALID_TASK_EFFORT_PLAN', `${label} must be an object`);
+  const p50 = value.p50_minutes;
+  const p80 = value.p80_minutes;
+  if (!Number.isFinite(p50) || p50 < 0 || !Number.isFinite(p80) || p80 < p50) {
+    fail('INVALID_TASK_EFFORT_PLAN', `${label} must have non-negative p50_minutes and p80_minutes >= p50_minutes`);
+  }
+  return { p50_minutes: p50, p80_minutes: p80 };
+}
+
+function taskEffortPlan(task) {
+  const plan = task.effort_plan;
+  if (!plan || typeof plan !== 'object' || Array.isArray(plan)) {
+    fail('TASK_EFFORT_PLAN_REQUIRED', `task ${task.id} must declare a complete effort_plan`);
+  }
+  const parts = Object.fromEntries(['ai_build', 'ai_review', 'ai_rework_reserve', 'human_active', 'human_wait']
+    .map((part) => [part, durationRange(plan[part], `task ${task.id} effort_plan.${part}`)]));
+  if (!Number.isFinite(plan.rework_margin_pct) || plan.rework_margin_pct < 1 || plan.rework_margin_pct > 100) {
+    fail('INVALID_TASK_EFFORT_PLAN', `task ${task.id} effort_plan.rework_margin_pct must be between 1 and 100`);
+  }
+  if (parts.ai_rework_reserve.p80_minutes <= 0) {
+    fail('INVALID_TASK_EFFORT_PLAN', `task ${task.id} effort_plan.ai_rework_reserve must reserve rework time`);
+  }
+  const total = durationRange(plan.total, `task ${task.id} effort_plan.total`);
+  const expected = Object.values(parts).reduce((sum, value) => ({
+    p50_minutes: sum.p50_minutes + value.p50_minutes,
+    p80_minutes: sum.p80_minutes + value.p80_minutes,
+  }), { p50_minutes: 0, p80_minutes: 0 });
+  if (Math.abs(total.p50_minutes - expected.p50_minutes) > 0.001 || Math.abs(total.p80_minutes - expected.p80_minutes) > 0.001) {
+    fail('INVALID_TASK_EFFORT_PLAN', `task ${task.id} effort_plan.total must equal the sum of AI, rework, and human time`);
+  }
+  return { ...parts, rework_margin_pct: plan.rework_margin_pct, total };
+}
+
+function taskRequirementRefs(task) {
+  if (!Array.isArray(task.requirement_refs) || task.requirement_refs.length === 0
+    || !task.requirement_refs.every((ref) => typeof ref === 'string' && ref.trim())
+    || new Set(task.requirement_refs).size !== task.requirement_refs.length) {
+    fail('TASK_REQUIREMENT_TRACEABILITY_REQUIRED', `task ${task.id} must reference one or more unique discovery requirement IDs`);
+  }
+  return [...task.requirement_refs];
+}
+
+function validateDependencyGraph(tasks) {
+  const byId = new Map(tasks.map((task) => [task.task_id, task]));
+  for (const task of tasks) {
+    if (!Array.isArray(task.dependency_ids) || !task.dependency_ids.every((id) => typeof id === 'string' && id.trim())) {
+      fail('INVALID_TASK_DEPENDENCY', `task ${task.task_id} dependencies must be an array of task IDs`);
+    }
+    if (new Set(task.dependency_ids).size !== task.dependency_ids.length) {
+      fail('INVALID_TASK_DEPENDENCY', `task ${task.task_id} has duplicate dependencies`);
+    }
+    for (const dependency of task.dependency_ids) {
+      if (dependency === task.task_id || !byId.has(dependency)) {
+        fail('INVALID_TASK_DEPENDENCY', `task ${task.task_id} references an unknown or self dependency: ${dependency}`);
+      }
+    }
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (taskId) => {
+    if (visiting.has(taskId)) fail('TASK_DEPENDENCY_CYCLE', `planning task graph contains a dependency cycle at ${taskId}`);
+    if (visited.has(taskId)) return;
+    visiting.add(taskId);
+    for (const dependency of byId.get(taskId).dependency_ids) visit(dependency);
+    visiting.delete(taskId);
+    visited.add(taskId);
+  };
+  for (const task of tasks) visit(task.task_id);
+}
+
+function compileVerificationPlan(project, task) {
+  if (task.verification_checks === undefined) return {};
+  if (!Array.isArray(task.verification_checks) || task.verification_checks.length < 2 || task.verification_checks.length > 32) {
+    fail('VERIFICATION_PLAN_INVALID', 'verification_checks must contain 2 to 32 mandatory CI/acceptance checks');
+  }
+  const checks = task.verification_checks.map((check) => {
+    const fields = ['check_id', 'kind', 'criterion_indices', 'executable_binding', 'args', 'script_path', 'timeout_ms'];
+    if (!check || Object.keys(check).length !== fields.length || Object.keys(check).some((key) => !fields.includes(key))
+      || !Array.isArray(check.criterion_indices)
+      || check.criterion_indices.some((index) => !Number.isInteger(index) || index < 0 || index >= task.criteria.length)
+      || typeof check.script_path !== 'string' || !check.script_path.startsWith('artifacts/6-Tasks/verification/')
+      || check.script_path.includes('\0') || check.script_path.split('/').some((part) => !part || part === '.' || part === '..')) {
+      fail('VERIFICATION_PLAN_INVALID', 'verification check requires explicit fields, valid zero-based criterion indices and a Tasks verification script');
+    }
+    const stdin_ref = immutableFileRef(project, check.script_path, 'VERIFICATION_SCRIPT_REQUIRED');
+    return {
+      check_id: check.check_id, kind: check.kind,
+      criterion_refs: check.criterion_indices.map((index) => criterionRef(task.id, task.criteria[index])),
+      executable_binding: check.executable_binding, args: check.args, stdin_ref, timeout_ms: check.timeout_ms,
+    };
+  });
+  const verification_plan = { schema_version: 1, checks };
+  validateTaskVerificationPlan({ verification_plan, acceptance_criteria_refs: task.criteria.map((criterion) => criterionRef(task.id, criterion)) });
+  for (const check of checks) {
+    const pinned = openPinnedProviderExecutable(check.executable_binding, { projectDir: project.path, requireNativeImage: true });
+    closeSync(pinned.descriptor);
+  }
+  return { verification_plan };
+}
+
+function compileBrowserVerificationPlan(project, task) {
+  const source = task.browser_verification;
+  if (source === undefined) return {};
+  const fields = ['schema_version', 'tool_id', 'evidence_kind', 'criterion_indices', 'observation'];
+  const scriptPath = source?.observation?.application?.script_path;
+  if (!source || Object.keys(source).length !== fields.length || Object.keys(source).some((key) => !fields.includes(key))
+    || !Array.isArray(source.criterion_indices)
+    || source.criterion_indices.some((index) => !Number.isInteger(index) || index < 0 || index >= task.criteria.length)
+    || typeof scriptPath !== 'string' || !scriptPath.startsWith('artifacts/6-Tasks/verification/')
+    || scriptPath.includes('\0') || scriptPath.split('/').some((part) => !part || part === '.' || part === '..')) {
+    fail('BROWSER_VERIFICATION_PLAN_INVALID', 'browser verification requires explicit fields, criterion indices and a Tasks startup script');
+  }
+  const application = { ...source.observation.application }; delete application.script_path;
+  const stdin_ref = immutableFileRef(project, scriptPath, 'BROWSER_STARTUP_SCRIPT_REQUIRED');
+  const browser_verification_plan = { schema_version: source.schema_version, tool_id: source.tool_id,
+    evidence_kind: source.evidence_kind, criterion_refs: source.criterion_indices.map((index) => criterionRef(task.id, task.criteria[index])),
+    observation: { ...source.observation, application: { ...application, stdin_ref } } };
+  validateTaskBrowserVerificationPlan({ task_id: task.id, requires_browser: task.requires_browser,
+    browser_policy: task.browser_policy, acceptance_criteria_refs: task.criteria.map((criterion) => criterionRef(task.id, criterion)), browser_verification_plan });
+  for (const binding of [application.executable_binding, source.observation.browser.executable_binding]) {
+    const pinned = openPinnedProviderExecutable(binding, { projectDir: project.path, requireNativeImage: true });
+    closeSync(pinned.descriptor);
+  }
+  return { browser_verification_plan };
+}
+
 /**
  * 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.
+ * Only the trusted advance caller promotes an agent-owned candidate. The
+ * protected snapshot is council input, not permission to dispatch a task.
  */
-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 { loaded, session } = loadSession(projectDir);
-  if (!loaded || !session) fail('V2_SESSION_REQUIRED', 'planning-to-RAIL compilation requires a canonical project session');
-  assertV2PlanningPredecessors(session, 'tasks');
-  const inputPath = join(projectDir, PLANNING_V2_TASKS_PATH);
-  const planning = readJson(inputPath, 'PLANNING_TASK_GRAPH_REQUIRED');
+export function compilePlanningHandoff({ projectDir, clock = () => new Date(), promoteCandidate = false } = {}) {
+  const project = openPinnedPlanningProjectRoot(projectDir);
+  try {
+    const installation = loadRuntimeInstallationV2(project.path, { clock });
+    if (!installation) fail('V2_INSTALLATION_REQUIRED', 'planning-to-RAIL compilation requires a v2 installation');
+    const { loaded, session } = loadSession(project.path);
+    if (!loaded || !session) fail('V2_SESSION_REQUIRED', 'planning-to-RAIL compilation requires a canonical project session');
+    assertV2PlanningPredecessors(session, 'tasks');
+    const taskGraphPath = promoteCandidate ? PLANNING_V2_TASKS_CANDIDATE_PATH : PLANNING_V2_TASKS_PATH;
+    const { value: planning, content: planningSnapshot } = readJsonSnapshot(project, taskGraphPath, 'PLANNING_TASK_GRAPH_REQUIRED');
+    const strictExecutionDesign = installationRequiresExecutionDesignV2(installation);
+    if (strictExecutionDesign && !planningUsesExecutionDesignV2(planning)) {
+      fail('PLANNING_EXECUTION_DESIGN_VERSION_REQUIRED', 'current installations require a v2 planning task graph and do not permit a legacy routing downgrade');
+    }
   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'),
+    requirements_ref: immutableFileRef(project, sources.requirements_path, 'PLANNING_SOURCE_ARTIFACTS_REQUIRED'),
+    architecture_ref: immutableFileRef(project, sources.architecture_path, 'PLANNING_SOURCE_ARTIFACTS_REQUIRED'),
+    qa_plan_ref: immutableFileRef(project, 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');
+  if (sources.ux_path) source_artifacts.ux_ref = immutableFileRef(project, sources.ux_path, 'PLANNING_SOURCE_ARTIFACTS_REQUIRED');
   const ids = new Set();
   const clickupRequired = installation.installation.external_integrations?.clickup === 'required';
   const tasks = planning.tasks.map((task) => {
@@ -113,6 +492,21 @@ export function compilePlanningHandoff({ projectDir, clock = () => new Date() }
     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`);
+    const route = strictExecutionDesign
+      ? resolveRuntimeTaskRouteV2({
+        artifact: installation,
+        routing_profile: taskRoutingProfile(task),
+        required_independence_level: task.required_independence_level ?? 'A',
+        clock,
+      })
+      : null;
+    const execution_binding = route?.execution_binding ?? taskExecutionBinding(task, installation, clock);
+    const strictFields = strictExecutionDesign ? {
+      requirement_refs: taskRequirementRefs(task),
+      routing_profile: route.routing_profile,
+      review_binding: route.review_binding,
+      effort_plan: taskEffortPlan(task),
+    } : {};
     return {
       task_id: task.id,
       dependency_ids: task.dependencies ?? [],
@@ -120,25 +514,78 @@ export function compilePlanningHandoff({ projectDir, clock = () => new Date() }
       execution_scope_ref: task.execution_scope_ref,
       routing_constraints_ref: task.routing_constraints_ref || `policy://installation/${installation.installation.installation_id}/task/${task.id}`,
       required_independence_level: task.required_independence_level ?? 'A',
-      execution_binding: taskExecutionBinding(task, installation, clock),
+      execution_binding,
       estimate: task.estimate,
+      ...strictFields,
+      ...compileVerificationPlan(project, task),
+      ...compileBrowserVerificationPlan(project, task),
       ...(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'))}`;
+  validateDependencyGraph(tasks);
+  source_artifacts.task_details_ref = immutableFileRef(project, sources.task_details_path || 'artifacts/6-Tasks/tasks.md', 'PLANNING_TASK_DETAILS_REQUIRED');
+  const materialByRef = new Map(project.artifactSnapshots.map(({ content }) => [
+    `local-artifact://sha256/${sha256(content)}`, { ref: `local-artifact://sha256/${sha256(content)}`, sha256: sha256(content), content },
+  ]));
+  for (const task of planning.tasks) {
+    for (const criterion of task.criteria) {
+      const content = canonicalSerialize({ task_id: task.id, criterion });
+      const ref = criterionRef(task.id, criterion);
+      materialByRef.set(ref, { ref, sha256: sha256(content), content });
+    }
+  }
+  const planning_material = {
+    schema_version: 1,
+    artifacts: [...materialByRef.values()].sort((left, right) => left.ref.localeCompare(right.ref)),
+    scope_bindings: tasks.map((task) => ({
+      task_id: task.task_id, ref: task.execution_scope_ref, artifact_ref: source_artifacts.task_details_ref,
+    })),
+  };
+  assertAllNamedPlanningArtifacts(project);
+  const commit = gitCommit(project.path);
+  // The sealed executable task list and its council-visible artifact reference
+  // must derive from one immutable in-memory snapshot. A second path read here
+  // would let a concurrent writer bind different tasks to an approved digest.
+  const task_graph_ref = `local-artifact://sha256/${sha256(planningSnapshot)}`;
   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({
+  const handoff = sealHandoff({
     handoff_id,
     version: planning.version || '1.0.0',
     project_id: installation.project_id,
     source_artifacts,
     task_graph_ref,
     tasks,
+    planning_material,
     seal: { sealed_by: planning.sealed_by || 'actor://chati/qa-planning', sealed_at: sealedAt, git_commit_ref: commit },
   });
+  if (promoteCandidate) {
+    // Persist exactly the validated snapshot, never reread the mutable candidate.
+    // Invalid candidates leave the previous protected graph untouched. A new
+    // graph changes the council subject, so an old approval cannot authorize it.
+    assertAllNamedPlanningArtifacts(project);
+    const path = join(project.reference, PLANNING_V2_TASKS_PATH);
+    const previous = readSafeInstallationStorageFile(path, { allowMissing: true });
+    if (previous === null) {
+      persistImmutableInstallationFile(path, planningSnapshot, {
+        conflictCode: 'PLANNING_TASK_GRAPH_CONFLICT', label: 'validated planning task graph',
+      });
+    } else if (previous.content !== planningSnapshot) {
+      replaceInstallationStorageFile(path, planningSnapshot, previous);
+    }
+  }
+  return handoff;
+  } finally {
+    try {
+      assertPinnedPlanningProjectRoot(project);
+      assertAllNamedPlanningArtifacts(project);
+    }
+    finally {
+      for (const artifact of project.artifactSnapshots) closePlanningArtifactDescriptors(artifact);
+      closeSync(project.descriptor);
+    }
+  }
 }