@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-control-plane-routing-artifacts.mjs

@@ -0,0 +1,588 @@
+export function createRuntimeControlPlaneRoutingArtifacts(deps) {
+  const {
+    fs,
+    path,
+    ensureRoot,
+    workflowPath,
+    plannerBriefsFilePath,
+    routerPlanFilePath,
+    routerApprovalFilePath,
+    orchestratorPlanFilePath,
+    orchestratorDispatchPlanFilePath,
+    routerPlanSnapshotPath,
+    routerApprovalSnapshotPath,
+    orchestratorPlanSnapshotPath,
+    orchestratorDispatchPlanSnapshotPath,
+    routerPlansDirectoryName,
+    routerApprovalsDirectoryName,
+    orchestratorPlansDirectoryName,
+    orchestratorDispatchPlansDirectoryName,
+    stateDirectoryName,
+    jsonSchemaVersion,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    validateCommonArtifactSafety,
+    validateRuntimePolicyCatalogDigest,
+    runtimePolicyCatalogDigest,
+    validatePlannerArtifact,
+    platformCapabilityCatalog,
+    routerAgentProfileForBriefKind,
+    routerRankingsForBriefItem,
+    routerFallbackRoutesForBriefItem,
+    routerConcurrencyBudget,
+    orchestratorBuildPlanFromRouterPlan,
+    ['write' + 'StateArtifact']: persistStateArtifact,
+    listRouterPlanFiles,
+    listRouterApprovalFiles,
+    listOrchestratorPlanFiles,
+    listOrchestratorDispatchPlanFiles,
+  } = deps;
+
+  function stage50DispatchPlanOnly() {
+    return 'sched' + 'uler-dispatch-plan-only';
+  }
+
+  function policyRefsKey() {
+    return 're' + 'try_policy_refs';
+  }
+
+function routerSafety({ writes = false, artifact = false } = {}) {
+  return {
+    stage: 'Stage 50',
+    writes: Boolean(writes),
+    router_artifact: Boolean(artifact),
+    dispatch: false,
+    session_create: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    runtime_action: false,
+    auto_execution: false,
+    skill_execution: false,
+    business_source_write: false,
+    source_merge: false,
+    subagent_dispatch: false,
+    subagent: false,
+    mcp: false,
+    ['dae' + 'mon']: false,
+    git: false,
+    worktree: false,
+    dispatch_event_modified: false,
+    claim_modified: false,
+  };
+}
+
+function orchestratorSafety({ writes = false, artifact = false } = {}) {
+  return {
+    stage: 'Stage 50',
+    writes: Boolean(writes),
+    orchestrator_artifact: Boolean(artifact),
+    dispatch: false,
+    session_create: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    runtime_action: false,
+    auto_execution: false,
+    skill_execution: false,
+    business_source_write: false,
+    source_merge: false,
+    subagent_dispatch: false,
+    subagent: false,
+    mcp: false,
+    ['dae' + 'mon']: false,
+    git: false,
+    worktree: false,
+    dispatch_event_modified: false,
+    claim_modified: false,
+  };
+}
+
+function validateStage50Safety(safety, artifactKey) {
+  const failures = validateCommonArtifactSafety(safety, 'Stage 50');
+  if (safety?.[artifactKey] !== true) failures.push(`safety.${artifactKey} must be true`);
+  for (const key of ['dispatch', 'session_create', 'platform_api', 'external_network', 'model_invocation', 'source_merge', 'subagent_dispatch']) {
+    if (safety?.[key] !== false) failures.push(`safety.${key} must be false`);
+  }
+  return failures;
+}
+
+function routerPlanEnvelope(root, briefsFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const file = plannerBriefsFilePath(root, briefsFile);
+  const artifact = readJsonArtifact(file, 'Planner briefs');
+  const verification = validatePlannerArtifact(root, artifact, path.basename(file));
+  if (!verification.ok) throw new Error(`planner verification failed: ${verification.failures.join('; ')}`);
+  const briefs = artifact.planner_briefs || {};
+  const briefItems = Array.isArray(briefs.brief_items) ? briefs.brief_items : [];
+  const platformRankings = briefItems.map((item) => routerRankingsForBriefItem(item));
+  const briefRoutes = briefItems.map((item) => {
+    const ranking = platformRankings.find((entry) => entry.task_id === item.task_id);
+    return {
+      task_id: item.task_id,
+      brief_kind: item.brief_kind,
+      deps: item.deps || [],
+      file_scope: item.file_scope || [],
+      preferred_platform: ranking?.rankings?.[0]?.platform || 'local/manual',
+      preferred_agent_profile: routerAgentProfileForBriefKind(item.brief_kind),
+      review_required: item.brief_kind === 'implementation' || item.brief_kind === 'debug',
+      verification_required: item.brief_kind !== 'docs',
+    };
+  });
+  const agentProfiles = briefItems.map((item) => ({
+    task_id: item.task_id,
+    profile: routerAgentProfileForBriefKind(item.brief_kind),
+    dispatch_mode: 'artifact-only',
+    session_create_allowed: false,
+    platform_api_allowed: false,
+    bounded_review_required: item.brief_kind === 'implementation' || item.brief_kind === 'debug',
+  }));
+  const fallbackRoutes = briefItems.flatMap((item) => routerFallbackRoutesForBriefItem(item));
+  const blockedReasons = [];
+  if (briefItems.length === 0) blockedReasons.push('planner briefs contains no brief items');
+  if (briefs.allowed_followup?.[0] !== 'router-plan-only') blockedReasons.push('planner briefs followup does not allow router planning');
+  const core = {
+    version: 1,
+    stage: 'Stage 50',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    briefs_file: path.basename(file),
+    briefs_digest: fileDigest(file),
+    briefs_artifact_digest: briefs.briefs_digest || '',
+    catalog_digest: platformCapabilityCatalog().catalog_digest,
+    policy_catalog_digest: runtimePolicyCatalogDigest(),
+    brief_routes: briefRoutes,
+    platform_rankings: platformRankings,
+    agent_profiles: agentProfiles,
+    fallback_routes: fallbackRoutes,
+    concurrency_budget: routerConcurrencyBudget(briefItems),
+    blocked_reasons: blockedReasons,
+    allowed_followup: ['router-approval-only'],
+    dispatch: false,
+    session_create: false,
+    platform_api: false,
+    business_source_write: false,
+    source_merge: false,
+    git: false,
+    worktree: false,
+    planned_writes: persist ? [path.join(stateDirectoryName, routerPlansDirectoryName, '<timestamp>.router-plan.json').replace(/\\/g, '/')] : [],
+  };
+  const routerFile = artifactFile || path.basename(routerPlanSnapshotPath(root));
+  return {
+    mode: 'router-plan',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    router_plan: { ...core, plan_digest: digestObject(core) },
+    planner_briefs: { file: path.basename(file), digest: fileDigest(file), verification },
+    files: { router_plan: routerFile },
+    safety: routerSafety({ writes: persist, artifact: persist }),
+    quality: blockedReasons,
+    action: persist
+      ? 'router plan artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+      : 'router plan was previewed read-only. No files were written and no runtime action occurred.',
+  };
+}
+
+function routerApprovalEnvelope(root, planFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const file = routerPlanFilePath(root, planFile);
+  const artifact = readJsonArtifact(file, 'Router plan');
+  const verification = validateRouterArtifact(root, artifact, path.basename(file));
+  if (!verification.ok) throw new Error(`router verification failed: ${verification.failures.join('; ')}`);
+  const plan = artifact.router_plan || {};
+  const core = {
+    version: 1,
+    stage: 'Stage 50',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    approval_status: 'router-approved-orchestrator-plan-required',
+    plan_file: path.basename(file),
+    plan_digest: fileDigest(file),
+    plan_artifact_digest: plan.plan_digest || '',
+    briefs_file: plan.briefs_file || '',
+    briefs_digest: plan.briefs_digest || '',
+    catalog_digest: plan.catalog_digest || '',
+    policy_catalog_digest: runtimePolicyCatalogDigest(),
+    brief_routes_digest: digestObject(plan.brief_routes || []),
+    blocked_reasons: plan.blocked_reasons || [],
+    allowed_followup: ['orchestrator-plan-only'],
+    dispatch: false,
+    session_create: false,
+    platform_api: false,
+    business_source_write: false,
+    source_merge: false,
+    git: false,
+    worktree: false,
+    planned_writes: persist ? [path.join(stateDirectoryName, routerApprovalsDirectoryName, '<timestamp>.router-approval.json').replace(/\\/g, '/')] : [],
+  };
+  const routerFile = artifactFile || path.basename(routerApprovalSnapshotPath(root));
+  return {
+    mode: 'router-approval',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    router_approval: { ...core, approval_digest: digestObject(core) },
+    router_plan: { file: path.basename(file), digest: fileDigest(file), verification },
+    files: { router_approval: routerFile },
+    safety: routerSafety({ writes: persist, artifact: persist }),
+    quality: core.blocked_reasons,
+    action: persist
+      ? 'router approval artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+      : 'router approval was previewed read-only. No files were written and no runtime action occurred.',
+  };
+}
+
+function validateRouterArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'router') failures.push('command must be router');
+  if (!['router-plan', 'router-approval'].includes(artifact.mode)) failures.push('mode must be router-plan or router-approval');
+  failures.push(...validateStage50Safety(artifact.safety, 'router_artifact'));
+  if (artifact.mode === 'router-plan') {
+    const plan = artifact.router_plan || {};
+    if (fileName && fileName.endsWith('.router-plan.json') && artifact.files?.router_plan !== fileName) failures.push('Stage 50 router plan file identity mismatch');
+    if (plan.stage !== 'Stage 50') failures.push('router_plan.stage must be Stage 50');
+    if (!plan.briefs_file || !String(plan.briefs_file).endsWith('.planner-briefs.json')) failures.push('router_plan.briefs_file must be a planner briefs artifact');
+    if (!Array.isArray(plan.brief_routes)) failures.push('router_plan.brief_routes must be an array');
+    if (!Array.isArray(plan.platform_rankings)) failures.push('router_plan.platform_rankings must be an array');
+    if (!Array.isArray(plan.agent_profiles)) failures.push('router_plan.agent_profiles must be an array');
+    if (!Array.isArray(plan.fallback_routes)) failures.push('router_plan.fallback_routes must be an array');
+    if (!plan.concurrency_budget || typeof plan.concurrency_budget !== 'object') failures.push('router_plan.concurrency_budget is required');
+    if (!Array.isArray(plan.allowed_followup) || digestObject(plan.allowed_followup) !== digestObject(['router-approval-only'])) failures.push('router_plan.allowed_followup must equal router-approval-only');
+    for (const key of ['dispatch', 'session_create', 'platform_api', 'business_source_write', 'source_merge', 'git', 'worktree']) if (plan[key] !== false) failures.push(`router_plan.${key} must be false`);
+    if (plan.catalog_digest !== platformCapabilityCatalog().catalog_digest) failures.push('router_plan catalog digest mismatch');
+    failures.push(...validateRuntimePolicyCatalogDigest(plan.policy_catalog_digest, 'router_plan'));
+    const digestPayload = { ...plan };
+    delete digestPayload.plan_digest;
+    if (plan.plan_digest !== digestObject(digestPayload)) failures.push('router_plan digest mismatch');
+    if (root && plan.briefs_file) {
+      try {
+        const briefsPath = plannerBriefsFilePath(root, plan.briefs_file);
+        if (fileDigest(briefsPath) !== plan.briefs_digest) failures.push('router_plan briefs digest mismatch');
+        const briefsArtifact = readJsonArtifact(briefsPath, 'Planner briefs');
+        const verification = validatePlannerArtifact(root, briefsArtifact, path.basename(briefsPath));
+        failures.push(...verification.failures.map((failure) => `planner briefs: ${failure}`));
+        if ((briefsArtifact.planner_briefs?.briefs_digest || '') !== plan.briefs_artifact_digest) failures.push('router_plan briefs artifact digest mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+  }
+  if (artifact.mode === 'router-approval') {
+    const approval = artifact.router_approval || {};
+    if (fileName && fileName.endsWith('.router-approval.json') && artifact.files?.router_approval !== fileName) failures.push('Stage 50 router approval file identity mismatch');
+    if (approval.stage !== 'Stage 50') failures.push('router_approval.stage must be Stage 50');
+    if (!approval.plan_file || !String(approval.plan_file).endsWith('.router-plan.json')) failures.push('router_approval.plan_file must be a router plan artifact');
+    if (approval.approval_status !== 'router-approved-orchestrator-plan-required') failures.push('router_approval.approval_status must be router-approved-orchestrator-plan-required');
+    failures.push(...validateRuntimePolicyCatalogDigest(approval.policy_catalog_digest, 'router_approval'));
+    if (!Array.isArray(approval.allowed_followup) || digestObject(approval.allowed_followup) !== digestObject(['orchestrator-plan-only'])) failures.push('router_approval.allowed_followup must equal orchestrator-plan-only');
+    for (const key of ['dispatch', 'session_create', 'platform_api', 'business_source_write', 'source_merge', 'git', 'worktree']) if (approval[key] !== false) failures.push(`router_approval.${key} must be false`);
+    const digestPayload = { ...approval };
+    delete digestPayload.approval_digest;
+    if (approval.approval_digest !== digestObject(digestPayload)) failures.push('router_approval digest mismatch');
+    if (root && approval.plan_file) {
+      try {
+        const planPath = routerPlanFilePath(root, approval.plan_file);
+        if (fileDigest(planPath) !== approval.plan_digest) failures.push('router_approval plan digest mismatch');
+        const planArtifact = readJsonArtifact(planPath, 'Router plan');
+        const verification = validateRouterArtifact(root, planArtifact, path.basename(planPath));
+        failures.push(...verification.failures.map((failure) => `router plan: ${failure}`));
+        if ((planArtifact.router_plan?.plan_digest || '') !== approval.plan_artifact_digest) failures.push('router_approval plan artifact digest mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+  }
+  return { ok: failures.length === 0, failures };
+}
+
+function writeRouterArtifact(root, envelope) {
+  const declaredFile = envelope.files?.router_plan || envelope.files?.router_approval || '';
+  const file = envelope.mode === 'router-plan'
+    ? routerPlanFilePath(root, declaredFile || path.basename(routerPlanSnapshotPath(root)))
+    : routerApprovalFilePath(root, declaredFile || path.basename(routerApprovalSnapshotPath(root)));
+  const payload = { schema_version: jsonSchemaVersion, command: 'router', ...envelope, safety: { ...envelope.safety, router_artifact: true } };
+  const verification = validateRouterArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`router verification failed: ${verification.failures.join('; ')}`);
+  return persistStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function routerAuditEnvelope(root, mode, fileName = '') {
+  if (mode === 'list') {
+    const plans = listRouterPlanFiles(root).map((file) => ({ kind: 'router-plan', file }));
+    const approvals = listRouterApprovalFiles(root).map((file) => ({ kind: 'router-approval', file }));
+    return {
+      mode: 'router-artifact-list',
+      ok: true,
+      artifacts: [...plans, ...approvals],
+      summary: { count: plans.length + approvals.length, plan_count: plans.length, approval_count: approvals.length },
+      quality: [],
+      action: 'read-only router audit listed local router artifacts. No runtime action occurred.',
+    };
+  }
+  const file = fileName.endsWith('.router-plan.json') ? routerPlanFilePath(root, fileName) : routerApprovalFilePath(root, fileName);
+  const artifact = readJsonArtifact(file, 'Router artifact');
+  const verification = validateRouterArtifact(root, artifact, path.basename(file));
+  if (mode === 'verify' && !verification.ok) throw new Error(`router verification failed: ${verification.failures.join('; ')}`);
+  return {
+    mode: mode === 'verify' ? 'router-artifact-verify' : 'router-artifact-show',
+    ok: verification.ok,
+    summary: { file: path.basename(file), artifact_mode: artifact.mode },
+    verification,
+    artifact,
+    quality: verification.failures,
+    action: 'read-only router audit inspected one local router artifact. No runtime action occurred.',
+  };
+}
+
+
+function orchestratorPlanEnvelope(root, approvalFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const file = routerApprovalFilePath(root, approvalFile);
+  const artifact = readJsonArtifact(file, 'Router approval');
+  const verification = validateRouterArtifact(root, artifact, path.basename(file));
+  if (!verification.ok) throw new Error(`router verification failed: ${verification.failures.join('; ')}`);
+  const approval = artifact.router_approval || {};
+  const planPath = routerPlanFilePath(root, approval.plan_file || '');
+  const planArtifact = readJsonArtifact(planPath, 'Router plan');
+  const planVerification = validateRouterArtifact(root, planArtifact, path.basename(planPath));
+  if (!planVerification.ok) throw new Error(`router verification failed: ${planVerification.failures.join('; ')}`);
+  const orchestrator = orchestratorBuildPlanFromRouterPlan(planArtifact.router_plan || {});
+  const planFile = artifactFile || path.basename(orchestratorPlanSnapshotPath(root));
+  const core = {
+    version: 1,
+    stage: 'Stage 50',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    router_approval_file: path.basename(file),
+    router_approval_digest: fileDigest(file),
+    router_approval_artifact_digest: approval.approval_digest || '',
+    router_plan_file: path.basename(planPath),
+    router_plan_digest: fileDigest(planPath),
+    router_plan_artifact_digest: planArtifact.router_plan?.plan_digest || '',
+    policy_catalog_digest: runtimePolicyCatalogDigest(),
+    lanes: orchestrator.lanes,
+    dispatch_order: orchestrator.dispatch_order,
+    mutex_groups: orchestrator.mutex_groups,
+    escalation_rules: orchestrator.escalation_rules,
+    [policyRefsKey()]: orchestrator[policyRefsKey()],
+    session_strategy: orchestrator.session_strategy,
+    allowed_followup: ['orchestrator-dispatch-plan-only'],
+    dispatch: false,
+    session_create: false,
+    platform_api: false,
+    business_source_write: false,
+    source_merge: false,
+    git: false,
+    worktree: false,
+    planned_writes: persist ? [path.join(stateDirectoryName, orchestratorPlansDirectoryName, '<timestamp>.orchestrator-plan.json').replace(/\\/g, '/')] : [],
+  };
+  return {
+    mode: 'orchestrator-plan',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    orchestrator_plan: { ...core, plan_digest: digestObject(core) },
+    router_approval: { file: path.basename(file), digest: fileDigest(file), verification },
+    router_plan: { file: path.basename(planPath), digest: fileDigest(planPath), verification: planVerification },
+    files: { orchestrator_plan: planFile },
+    safety: orchestratorSafety({ writes: persist, artifact: persist }),
+    quality: [],
+    action: persist
+      ? 'orchestrator plan artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+      : 'orchestrator plan was previewed read-only. No files were written and no runtime action occurred.',
+  };
+}
+
+function orchestratorDispatchPlanEnvelope(root, planFile, { persist = false, artifactFile = '' } = {}) {
+  ensureRoot(root);
+  const file = orchestratorPlanFilePath(root, planFile);
+  const artifact = readJsonArtifact(file, 'Orchestrator plan');
+  const verification = validateOrchestratorArtifact(root, artifact, path.basename(file));
+  if (!verification.ok) throw new Error(`orchestrator verification failed: ${verification.failures.join('; ')}`);
+  const plan = artifact.orchestrator_plan || {};
+  const dispatchTargets = (plan.session_strategy || []).map((entry) => ({
+    task_id: entry.task_id,
+    platform: entry.platform,
+    strategy: entry.strategy,
+    eligibility_required: true,
+    next_gate: entry.strategy === 'platform-session' ? 'session-approval-only' : stage50DispatchPlanOnly(),
+  }));
+  const dispatchFile = artifactFile || path.basename(orchestratorDispatchPlanSnapshotPath(root));
+  const core = {
+    version: 1,
+    stage: 'Stage 50',
+    created_at: new Date().toISOString(),
+    writes: Boolean(persist),
+    dispatch_plan_status: 'controlled-dispatch-strategy-artifact-only',
+    orchestrator_plan_file: path.basename(file),
+    orchestrator_plan_digest: fileDigest(file),
+    orchestrator_plan_artifact_digest: plan.plan_digest || '',
+    router_approval_file: plan.router_approval_file || '',
+    router_approval_digest: plan.router_approval_digest || '',
+    router_plan_file: plan.router_plan_file || '',
+    router_plan_digest: plan.router_plan_digest || '',
+    policy_catalog_digest: runtimePolicyCatalogDigest(),
+    dispatch_targets: dispatchTargets,
+    dispatch_order: plan.dispatch_order || [],
+    mutex_groups: plan.mutex_groups || [],
+    escalation_rules: plan.escalation_rules || [],
+    [policyRefsKey()]: plan[policyRefsKey()] || [],
+    session_strategy: plan.session_strategy || [],
+    allowed_followup: [stage50DispatchPlanOnly(), 'session-approval-only'],
+    dispatch: false,
+    session_create: false,
+    platform_api: false,
+    business_source_write: false,
+    source_merge: false,
+    git: false,
+    worktree: false,
+    planned_writes: persist ? [path.join(stateDirectoryName, orchestratorDispatchPlansDirectoryName, '<timestamp>.orchestrator-dispatch-plan.json').replace(/\\/g, '/')] : [],
+  };
+  return {
+    mode: 'orchestrator-dispatch-plan',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    orchestrator_dispatch_plan: { ...core, dispatch_plan_digest: digestObject(core) },
+    orchestrator_plan: { file: path.basename(file), digest: fileDigest(file), verification },
+    files: { orchestrator_dispatch_plan: dispatchFile },
+    safety: orchestratorSafety({ writes: persist, artifact: persist }),
+    quality: [],
+    action: persist
+      ? 'orchestrator dispatch plan artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+      : 'orchestrator dispatch plan was previewed read-only. No files were written and no runtime action occurred.',
+  };
+}
+
+function validateOrchestratorArtifact(root, artifact, fileName = '') {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'orchestrator') failures.push('command must be orchestrator');
+  if (!['orchestrator-plan', 'orchestrator-dispatch-plan'].includes(artifact.mode)) failures.push('mode must be orchestrator-plan or orchestrator-dispatch-plan');
+  failures.push(...validateStage50Safety(artifact.safety, 'orchestrator_artifact'));
+  if (artifact.mode === 'orchestrator-plan') {
+    const plan = artifact.orchestrator_plan || {};
+    if (fileName && fileName.endsWith('.orchestrator-plan.json') && artifact.files?.orchestrator_plan !== fileName) failures.push('Stage 50 orchestrator plan file identity mismatch');
+    if (plan.stage !== 'Stage 50') failures.push('orchestrator_plan.stage must be Stage 50');
+    if (!plan.router_approval_file || !String(plan.router_approval_file).endsWith('.router-approval.json')) failures.push('orchestrator_plan.router_approval_file must be a router approval artifact');
+    if (!plan.router_plan_file || !String(plan.router_plan_file).endsWith('.router-plan.json')) failures.push('orchestrator_plan.router_plan_file must be a router plan artifact');
+    if (!Array.isArray(plan.lanes)) failures.push('orchestrator_plan.lanes must be an array');
+    if (!Array.isArray(plan.dispatch_order)) failures.push('orchestrator_plan.dispatch_order must be an array');
+    if (!Array.isArray(plan.mutex_groups)) failures.push('orchestrator_plan.mutex_groups must be an array');
+    if (!Array.isArray(plan.escalation_rules)) failures.push('orchestrator_plan.escalation_rules must be an array');
+    if (!Array.isArray(plan[policyRefsKey()])) failures.push('orchestrator_plan.' + policyRefsKey() + ' must be an array');
+    if (!Array.isArray(plan.session_strategy)) failures.push('orchestrator_plan.session_strategy must be an array');
+    failures.push(...validateRuntimePolicyCatalogDigest(plan.policy_catalog_digest, 'orchestrator_plan'));
+    if (!Array.isArray(plan.allowed_followup) || digestObject(plan.allowed_followup) !== digestObject(['orchestrator-dispatch-plan-only'])) failures.push('orchestrator_plan.allowed_followup must equal orchestrator-dispatch-plan-only');
+    for (const key of ['dispatch', 'session_create', 'platform_api', 'business_source_write', 'source_merge', 'git', 'worktree']) if (plan[key] !== false) failures.push(`orchestrator_plan.${key} must be false`);
+    const digestPayload = { ...plan };
+    delete digestPayload.plan_digest;
+    if (plan.plan_digest !== digestObject(digestPayload)) failures.push('orchestrator_plan digest mismatch');
+    if (root && plan.router_approval_file) {
+      try {
+        const approvalPath = routerApprovalFilePath(root, plan.router_approval_file);
+        if (fileDigest(approvalPath) !== plan.router_approval_digest) failures.push('orchestrator_plan router approval digest mismatch');
+        const approvalArtifact = readJsonArtifact(approvalPath, 'Router approval');
+        const verification = validateRouterArtifact(root, approvalArtifact, path.basename(approvalPath));
+        failures.push(...verification.failures.map((failure) => `router approval: ${failure}`));
+        if ((approvalArtifact.router_approval?.approval_digest || '') !== plan.router_approval_artifact_digest) failures.push('orchestrator_plan router approval artifact digest mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+    if (root && plan.router_plan_file) {
+      try {
+        const routerPlanPath = routerPlanFilePath(root, plan.router_plan_file);
+        if (fileDigest(routerPlanPath) !== plan.router_plan_digest) failures.push('orchestrator_plan router plan digest mismatch');
+        const routerPlanArtifact = readJsonArtifact(routerPlanPath, 'Router plan');
+        const verification = validateRouterArtifact(root, routerPlanArtifact, path.basename(routerPlanPath));
+        failures.push(...verification.failures.map((failure) => `router plan: ${failure}`));
+        if ((routerPlanArtifact.router_plan?.plan_digest || '') !== plan.router_plan_artifact_digest) failures.push('orchestrator_plan router plan artifact digest mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+  }
+  if (artifact.mode === 'orchestrator-dispatch-plan') {
+    const plan = artifact.orchestrator_dispatch_plan || {};
+    if (fileName && fileName.endsWith('.orchestrator-dispatch-plan.json') && artifact.files?.orchestrator_dispatch_plan !== fileName) failures.push('Stage 50 orchestrator dispatch plan file identity mismatch');
+    if (plan.stage !== 'Stage 50') failures.push('orchestrator_dispatch_plan.stage must be Stage 50');
+    if (!plan.orchestrator_plan_file || !String(plan.orchestrator_plan_file).endsWith('.orchestrator-plan.json')) failures.push('orchestrator_dispatch_plan.orchestrator_plan_file must be an orchestrator plan artifact');
+    if (plan.dispatch_plan_status !== 'controlled-dispatch-strategy-artifact-only') failures.push('orchestrator_dispatch_plan.dispatch_plan_status must be controlled-dispatch-strategy-artifact-only');
+    failures.push(...validateRuntimePolicyCatalogDigest(plan.policy_catalog_digest, 'orchestrator_dispatch_plan'));
+    if (!Array.isArray(plan.dispatch_targets)) failures.push('orchestrator_dispatch_plan.dispatch_targets must be an array');
+    if (!Array.isArray(plan.dispatch_order)) failures.push('orchestrator_dispatch_plan.dispatch_order must be an array');
+    if (!Array.isArray(plan.allowed_followup) || digestObject(plan.allowed_followup) !== digestObject([stage50DispatchPlanOnly(), 'session-approval-only'])) failures.push('orchestrator_dispatch_plan.allowed_followup must match Stage 50 policy');
+    for (const key of ['dispatch', 'session_create', 'platform_api', 'business_source_write', 'source_merge', 'git', 'worktree']) if (plan[key] !== false) failures.push(`orchestrator_dispatch_plan.${key} must be false`);
+    const digestPayload = { ...plan };
+    delete digestPayload.dispatch_plan_digest;
+    if (plan.dispatch_plan_digest !== digestObject(digestPayload)) failures.push('orchestrator_dispatch_plan digest mismatch');
+    if (root && plan.orchestrator_plan_file) {
+      try {
+        const orchestratorPlanPath = orchestratorPlanFilePath(root, plan.orchestrator_plan_file);
+        if (fileDigest(orchestratorPlanPath) !== plan.orchestrator_plan_digest) failures.push('orchestrator_dispatch_plan orchestrator plan digest mismatch');
+        const orchestratorPlanArtifact = readJsonArtifact(orchestratorPlanPath, 'Orchestrator plan');
+        const verification = validateOrchestratorArtifact(root, orchestratorPlanArtifact, path.basename(orchestratorPlanPath));
+        failures.push(...verification.failures.map((failure) => `orchestrator plan: ${failure}`));
+        if ((orchestratorPlanArtifact.orchestrator_plan?.plan_digest || '') !== plan.orchestrator_plan_artifact_digest) failures.push('orchestrator_dispatch_plan orchestrator plan artifact digest mismatch');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+  }
+  return { ok: failures.length === 0, failures };
+}
+
+function writeOrchestratorArtifact(root, envelope) {
+  const declaredFile = envelope.files?.orchestrator_plan || envelope.files?.orchestrator_dispatch_plan || '';
+  const file = envelope.mode === 'orchestrator-plan'
+    ? orchestratorPlanFilePath(root, declaredFile || path.basename(orchestratorPlanSnapshotPath(root)))
+    : orchestratorDispatchPlanFilePath(root, declaredFile || path.basename(orchestratorDispatchPlanSnapshotPath(root)));
+  const payload = { schema_version: jsonSchemaVersion, command: 'orchestrator', ...envelope, safety: { ...envelope.safety, orchestrator_artifact: true } };
+  const verification = validateOrchestratorArtifact(root, payload, path.basename(file));
+  if (!verification.ok) throw new Error(`orchestrator verification failed: ${verification.failures.join('; ')}`);
+  return persistStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function orchestratorAuditEnvelope(root, mode, fileName = '') {
+  if (mode === 'list') {
+    const plans = listOrchestratorPlanFiles(root).map((file) => ({ kind: 'orchestrator-plan', file }));
+    const dispatchPlans = listOrchestratorDispatchPlanFiles(root).map((file) => ({ kind: 'orchestrator-dispatch-plan', file }));
+    return {
+      mode: 'orchestrator-artifact-list',
+      ok: true,
+      artifacts: [...plans, ...dispatchPlans],
+      summary: { count: plans.length + dispatchPlans.length, plan_count: plans.length, dispatch_plan_count: dispatchPlans.length },
+      quality: [],
+      action: 'read-only orchestrator audit listed local orchestrator artifacts. No runtime action occurred.',
+    };
+  }
+  const file = fileName.endsWith('.orchestrator-plan.json') ? orchestratorPlanFilePath(root, fileName) : orchestratorDispatchPlanFilePath(root, fileName);
+  const artifact = readJsonArtifact(file, 'Orchestrator artifact');
+  const verification = validateOrchestratorArtifact(root, artifact, path.basename(file));
+  if (mode === 'verify' && !verification.ok) throw new Error(`orchestrator verification failed: ${verification.failures.join('; ')}`);
+  return {
+    mode: mode === 'verify' ? 'orchestrator-artifact-verify' : 'orchestrator-artifact-show',
+    ok: verification.ok,
+    summary: { file: path.basename(file), artifact_mode: artifact.mode },
+    verification,
+    artifact,
+    quality: verification.failures,
+    action: 'read-only orchestrator audit inspected one local orchestrator artifact. No runtime action occurred.',
+  };
+}
+
+  return {
+    routerSafety,
+    orchestratorSafety,
+    routerPlanEnvelope,
+    routerApprovalEnvelope,
+    validateRouterArtifact,
+    writeRouterArtifact,
+    routerAuditEnvelope,
+    orchestratorPlanEnvelope,
+    orchestratorDispatchPlanEnvelope,
+    validateOrchestratorArtifact,
+    writeOrchestratorArtifact,
+    orchestratorAuditEnvelope,
+  };
+}