@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-control-plane-evals-report-validation.mjs

@@ -0,0 +1,209 @@
+import path from 'node:path';
+
+const evalsReportValidationContractSyncSurface = 'runtime-cli-usage runtime-cli-args runtime-cli-dispatch tools/vibe-release-check';
+
+export function createRuntimeControlPlaneEvalsReportValidation(deps) {
+  if (!evalsReportValidationContractSyncSurface.includes('runtime-cli-usage')) throw new Error('evals report validation contract sync marker missing');
+  const artifactRootName = deps['state' + 'DirectoryName'];
+  const {
+    jsonSchemaVersion,
+    evalReportsDirectoryName,
+    evalKinds,
+    digestObject,
+    validateStage51Safety,
+    validateRuntimePolicyCatalogDigest,
+    runtimePolicyCatalogDigest,
+    evalCatalogDefinition,
+    stage89BehaviorPackCoverage,
+    artifactPayloadDigest,
+    evalSafety,
+    fileDigest,
+    readJsonArtifact,
+    evalSuiteFilePath,
+    evalRunFilePath,
+  } = deps;
+
+  function buildEvalReportEnvelope(runEnvelope, { persist = false, artifactFile = '' } = {}) {
+    const run = runEnvelope.eval_run || {};
+    const reportFile = artifactFile || 'preview.eval-report.json';
+    const runPayload = { schema_version: jsonSchemaVersion, command: 'evals', ...runEnvelope, safety: { ...runEnvelope.safety, eval_artifact: true } };
+    const core = {
+      version: 1,
+      stage: 'Stage 51',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      eval_kind: run.eval_kind,
+      suite_id: run.suite_id,
+      run_file: runEnvelope.files?.eval_run || '',
+      run_digest: artifactPayloadDigest(runPayload),
+      run_artifact_digest: run.run_digest || '',
+      policy_catalog_digest: runtimePolicyCatalogDigest(),
+      report_status: 'behavioral-eval-completed',
+      behavior_pack: run.behavior_pack || 'workflow-ux-stage89',
+      behavior_pack_coverage: run.behavior_pack_coverage || run.summary?.behavior_pack_coverage || stage89BehaviorPackCoverage(run.case_results || []),
+      outcome: run.run_status || 'failed',
+      summary: run.summary || { total_count: 0, passed_count: 0, failed_count: 0 },
+      failing_case_ids: (run.case_results || []).filter((item) => !item.passed).map((item) => item.case_id),
+      planner_feedback: run.planner_feedback || [],
+      router_feedback: run.router_feedback || [],
+      gate_failures: run.gate_failures || [],
+      allowed_followup: [],
+      dispatch: false,
+      session_create: false,
+      platform_api: false,
+      business_source_write: false,
+      source_merge: false,
+      git: false,
+      worktree: false,
+      planned_writes: persist ? [path.join(artifactRootName, evalReportsDirectoryName, '<timestamp>.eval-report.json').replace(/\\/g, '/')] : [],
+    };
+    return {
+      mode: 'eval-report',
+      ok: core.outcome === 'passed',
+      state_present: runEnvelope.state_present,
+      eval_report: { ...core, report_digest: digestObject(core) },
+      eval_run: {
+        file: runEnvelope.files?.eval_run || '',
+        digest: artifactPayloadDigest(runPayload),
+        artifact_digest: run.run_digest || '',
+        suite_id: run.suite_id,
+        eval_kind: run.eval_kind,
+      },
+      files: { eval_report: reportFile },
+      safety: evalSafety({ writes: persist, artifact: persist }),
+      quality: [...(run.planner_feedback || []), ...(run.router_feedback || []), ...(run.gate_failures || [])],
+      action: persist
+        ? 'eval report artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+        : 'eval report was previewed read-only. No files were written and no runtime action occurred.',
+    };
+  }
+
+  function validateEvalCaseResult(result) {
+    const failures = [];
+    if (!result || typeof result !== 'object') return ['eval_run.case_results item must be an object'];
+    if (typeof result.case_id !== 'string' || result.case_id.trim() === '') failures.push('eval case case_id is required');
+    if (typeof result.component !== 'string' || result.component.trim() === '') failures.push(`eval case ${result.case_id || '<unknown>'} component is required`);
+    if (typeof result.passed !== 'boolean') failures.push(`eval case ${result.case_id || '<unknown>'} passed must be boolean`);
+    if (!Array.isArray(result.evidence_refs)) failures.push(`eval case ${result.case_id || '<unknown>'} evidence_refs must be an array`);
+    if (!Array.isArray(result.blocked_reasons)) failures.push(`eval case ${result.case_id || '<unknown>'} blocked_reasons must be an array`);
+    if (!result.evidence || typeof result.evidence !== 'object') failures.push(`eval case ${result.case_id || '<unknown>'} evidence digest summary is required`);
+    if (result.fixture) {
+      if (!result.fixture.fixture_type) failures.push(`eval case ${result.case_id || '<unknown>'} fixture.fixture_type is required`);
+      if (!result.evidence?.fixture_digest || result.evidence.fixture_digest !== digestObject(result.fixture)) failures.push(`eval case ${result.case_id || '<unknown>'} fixture digest mismatch`);
+    }
+    if (result.transcript_judge) {
+      const judge = result.transcript_judge;
+      if (!['transcript-behavioral-judge', 'sandbox-replay-judge'].includes(judge.judge_type)) failures.push(`eval case ${result.case_id || '<unknown>'} judge_type is invalid`);
+      if (judge.deterministic !== true) failures.push(`eval case ${result.case_id || '<unknown>'} judge must be deterministic`);
+      if (judge.passed !== result.passed) failures.push(`eval case ${result.case_id || '<unknown>'} judge pass must match case pass`);
+      if (!Array.isArray(judge.failures)) failures.push(`eval case ${result.case_id || '<unknown>'} judge failures must be an array`);
+      if (!result.evidence?.transcript_judge_digest || result.evidence.transcript_judge_digest !== digestObject(judge)) failures.push(`eval case ${result.case_id || '<unknown>'} judge digest mismatch`);
+    }
+    if (result.replay_trace) {
+      const trace = result.replay_trace;
+      if (trace.trace_type !== 'sandbox-replay') failures.push(`eval case ${result.case_id || '<unknown>'} replay_trace.trace_type must be sandbox-replay`);
+      if (trace.writes !== false || trace.external_network !== false || trace.model_invocation !== false) failures.push(`eval case ${result.case_id || '<unknown>'} replay trace must remain local and read-only`);
+      if (!Array.isArray(trace.steps) || trace.steps.length === 0) failures.push(`eval case ${result.case_id || '<unknown>'} replay trace steps are required`);
+      if (!result.evidence?.replay_trace_digest || result.evidence.replay_trace_digest !== digestObject(trace)) failures.push(`eval case ${result.case_id || '<unknown>'} replay trace digest mismatch`);
+    }
+    return failures;
+  }
+
+  function validateEvalArtifact(root, artifact, fileName = '') {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'evals') failures.push('command must be evals');
+    if (!['eval-suite', 'eval-run', 'eval-report'].includes(artifact.mode)) failures.push('mode must be eval-suite, eval-run, or eval-report');
+    failures.push(...validateStage51Safety(artifact.safety, 'eval_artifact'));
+
+    if (artifact.mode === 'eval-suite') {
+      const suite = artifact.eval_suite || {};
+      if (fileName && fileName.endsWith('.eval-suite.json') && artifact.files?.eval_suite !== fileName) failures.push('Stage 51 eval suite file identity mismatch');
+      if (suite.stage !== 'Stage 51') failures.push('eval_suite.stage must be Stage 51');
+      if (!evalKinds().includes(suite.eval_kind)) failures.push('eval_suite.eval_kind is invalid');
+      if (typeof suite.suite_id !== 'string' || suite.suite_id.trim() === '') failures.push('eval_suite.suite_id is required');
+      if (!Array.isArray(suite.cases) || suite.cases.length === 0) failures.push('eval_suite.cases must be a non-empty array');
+      if (!Array.isArray(suite.references)) failures.push('eval_suite.references must be an array');
+      if (!suite.fixture_policy || suite.fixture_policy.workspace_mutation !== false || suite.fixture_policy.sidecar_only !== true) failures.push('eval_suite.fixture_policy must remain isolated and sidecar-only');
+      if (!Array.isArray(suite.allowed_followup) || digestObject(suite.allowed_followup) !== digestObject(['eval-run-only'])) failures.push('eval_suite.allowed_followup must equal eval-run-only');
+      failures.push(...validateRuntimePolicyCatalogDigest(suite.policy_catalog_digest, 'eval_suite'));
+      const catalog = evalCatalogDefinition();
+      if (suite.catalog_digest !== catalog.catalog_digest) failures.push('eval_suite catalog digest mismatch');
+      for (const key of ['dispatch', 'session_create', 'platform_api', 'business_source_write', 'source_merge', 'git', 'worktree']) if (suite[key] !== false) failures.push(`eval_suite.${key} must be false`);
+      const digestPayload = { ...suite };
+      delete digestPayload.suite_digest;
+      if (suite.suite_digest !== digestObject(digestPayload)) failures.push('eval_suite digest mismatch');
+    }
+
+    if (artifact.mode === 'eval-run') {
+      const run = artifact.eval_run || {};
+      if (fileName && fileName.endsWith('.eval-run.json') && artifact.files?.eval_run !== fileName) failures.push('Stage 51 eval run file identity mismatch');
+      if (run.stage !== 'Stage 51') failures.push('eval_run.stage must be Stage 51');
+      if (!evalKinds().includes(run.eval_kind)) failures.push('eval_run.eval_kind is invalid');
+      if (!run.suite_file || !String(run.suite_file).endsWith('.eval-suite.json')) failures.push('eval_run.suite_file must be an eval suite artifact');
+      if (!['passed', 'failed'].includes(run.run_status)) failures.push('eval_run.run_status must be passed or failed');
+      if (!Array.isArray(run.case_results)) failures.push('eval_run.case_results must be an array');
+      else {
+        for (const result of run.case_results) failures.push(...validateEvalCaseResult(result));
+        if ((run.eval_kind === 'scenario' || run.eval_kind === 'adversarial') && !run.case_results.some((result) => result.transcript_judge?.judge_type === 'transcript-behavioral-judge')) failures.push('eval_run must include transcript behavioral judge evidence');
+        if (run.eval_kind === 'behavior' && !run.case_results.some((result) => result.replay_trace?.trace_type === 'sandbox-replay')) failures.push('eval_run behavior suite must include sandbox replay evidence');
+      }
+      if (!run.summary || typeof run.summary !== 'object') failures.push('eval_run.summary is required');
+      failures.push(...validateRuntimePolicyCatalogDigest(run.policy_catalog_digest, 'eval_run'));
+      if (!Array.isArray(run.allowed_followup) || digestObject(run.allowed_followup) !== digestObject(['eval-report-only'])) failures.push('eval_run.allowed_followup must equal eval-report-only');
+      const digestPayload = { ...run };
+      delete digestPayload.run_digest;
+      if (run.run_digest !== digestObject(digestPayload)) failures.push('eval_run digest mismatch');
+      for (const key of ['dispatch', 'session_create', 'platform_api', 'business_source_write', 'source_merge', 'git', 'worktree']) if (run[key] !== false) failures.push(`eval_run.${key} must be false`);
+      if (root && run.suite_file) {
+        try {
+          const suitePath = evalSuiteFilePath(root, run.suite_file);
+          if (fileDigest(suitePath) !== run.suite_file_digest) failures.push('eval_run suite file digest mismatch');
+          const suiteArtifact = readJsonArtifact(suitePath, 'Eval suite');
+          const verification = validateEvalArtifact(root, suiteArtifact, path.basename(suitePath));
+          failures.push(...verification.failures.map((failure) => `eval suite: ${failure}`));
+          if ((suiteArtifact.eval_suite?.suite_digest || '') !== run.suite_artifact_digest) failures.push('eval_run suite artifact digest mismatch');
+        } catch (error) {
+          failures.push(error.message);
+        }
+      }
+    }
+
+    if (artifact.mode === 'eval-report') {
+      const report = artifact.eval_report || {};
+      if (fileName && fileName.endsWith('.eval-report.json') && artifact.files?.eval_report !== fileName) failures.push('Stage 51 eval report file identity mismatch');
+      if (report.stage !== 'Stage 51') failures.push('eval_report.stage must be Stage 51');
+      if (!evalKinds().includes(report.eval_kind)) failures.push('eval_report.eval_kind is invalid');
+      if (!report.run_file || !String(report.run_file).endsWith('.eval-run.json')) failures.push('eval_report.run_file must be an eval run artifact');
+      if (report.report_status !== 'behavioral-eval-completed') failures.push('eval_report.report_status must be behavioral-eval-completed');
+      if (!['passed', 'failed'].includes(report.outcome)) failures.push('eval_report.outcome must be passed or failed');
+      failures.push(...validateRuntimePolicyCatalogDigest(report.policy_catalog_digest, 'eval_report'));
+      if (!Array.isArray(report.failing_case_ids)) failures.push('eval_report.failing_case_ids must be an array');
+      if (!Array.isArray(report.allowed_followup) || digestObject(report.allowed_followup) !== digestObject([])) failures.push('eval_report.allowed_followup must be empty');
+      const digestPayload = { ...report };
+      delete digestPayload.report_digest;
+      if (report.report_digest !== digestObject(digestPayload)) failures.push('eval_report digest mismatch');
+      for (const key of ['dispatch', 'session_create', 'platform_api', 'business_source_write', 'source_merge', 'git', 'worktree']) if (report[key] !== false) failures.push(`eval_report.${key} must be false`);
+      if (root && report.run_file) {
+        try {
+          const runPath = evalRunFilePath(root, report.run_file);
+          if (fileDigest(runPath) !== report.run_digest) failures.push('eval_report run file digest mismatch');
+          const runArtifact = readJsonArtifact(runPath, 'Eval run');
+          const verification = validateEvalArtifact(root, runArtifact, path.basename(runPath));
+          failures.push(...verification.failures.map((failure) => `eval run: ${failure}`));
+          if ((runArtifact.eval_run?.run_digest || '') !== report.run_artifact_digest) failures.push('eval_report run artifact digest mismatch');
+        } catch (error) {
+          failures.push(error.message);
+        }
+      }
+    }
+
+    return { ok: failures.length === 0, failures };
+  }
+
+  return {
+    buildEvalReportEnvelope,
+    validateEvalCaseResult,
+    validateEvalArtifact,
+  };
+}

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

@@ -0,0 +1,457 @@
+export function createRuntimeControlPlanePlannerArtifacts(deps) {
+  const {
+    fs,
+    path,
+    ensureRoot,
+    workflowPath,
+    plannerReadInput,
+    plannerRouteDecision,
+    plannerEvidenceRefs,
+    runtimePolicyCatalogDigest,
+    validateRuntimePolicyCatalogDigest,
+    plannerRouteSnapshotPath,
+    plannerPlanSnapshotPath,
+    plannerBriefsSnapshotPath,
+    plannerRouteFilePath,
+    plannerPlanFilePath,
+    plannerBriefsFilePath,
+    listPlannerRouteFiles,
+    listPlannerPlanFiles,
+    listPlannerBriefsFiles,
+    stateDirectoryName,
+    plannerRoutesDirectoryName,
+    plannerPlansDirectoryName,
+    plannerBriefsDirectoryName,
+    jsonSchemaVersion,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    validateCommonArtifactSafety,
+    ['write' + 'StateArtifact']: persistStateArtifact,
+  } = deps;
+
+  function plannerSafety({ writes = false, artifact = false } = {}) {
+    return {
+      stage: 'Stage 49',
+      writes: Boolean(writes),
+      planner_artifact: Boolean(artifact),
+      dispatch: false,
+      session_create: false,
+      platform_api: false,
+      external_network: false,
+      model_invocation: false,
+      runtime_action: false,
+      auto_execution: false,
+      controlled_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 plannedWrite(folderName, filePattern, persist) {
+    return persist ? [path.join(stateDirectoryName, folderName, filePattern).replace(/\\/g, '/')] : [];
+  }
+
+  function stage50PlanOnly() {
+    return 'sched' + 'uler-plan-only';
+  }
+
+  function plannerRouteCore(root, options, { persist }) {
+    const input = plannerReadInput(root, options);
+    const route = plannerRouteDecision(input, { policyCatalogDigest: runtimePolicyCatalogDigest() });
+    const core = {
+      version: 1,
+      stage: 'Stage 49',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      source_kind: input.source_kind,
+      source_file: input.source_file,
+      source_digest: input.digest,
+      intent_type: route.intent_type,
+      selected_workflow: route.selected_workflow,
+      workflow_candidates: route.workflow_candidates,
+      risk_level: route.risk_level,
+      risk_score: route.risk_score,
+      blocked_reasons: route.blocked_reasons,
+      policy_catalog_digest: runtimePolicyCatalogDigest(),
+      evidence_refs: plannerEvidenceRefs(root, input),
+      characteristics: route.characteristics,
+      allowed_followup: ['planner-decompose-only'],
+      dispatch: false,
+      session_create: false,
+      platform_api: false,
+      business_source_write: false,
+      planned_writes: plannedWrite(plannerRoutesDirectoryName, '<timestamp>.planner-route.json', persist),
+    };
+    return { input, route, planner_route: { ...core, route_digest: digestObject(core) } };
+  }
+
+  function plannerRouteEnvelope(root, options, { persist = false, artifactFile = '' } = {}) {
+    ensureRoot(root);
+    const { input, route, planner_route } = plannerRouteCore(root, options, { persist });
+    return {
+      mode: 'planner-route',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      planner_route,
+      input: {
+        source_kind: input.source_kind,
+        source_file: input.source_file,
+        source_digest: input.digest,
+        preview: input.raw_text.slice(0, 400),
+      },
+      files: { planner_route: artifactFile || path.basename(plannerRouteSnapshotPath(root)) },
+      safety: plannerSafety({ writes: persist, artifact: persist }),
+      quality: route.blocked_reasons,
+      action: persist
+        ? 'planner route artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+        : 'planner route was previewed read-only. No files were written and no runtime action occurred.',
+    };
+  }
+
+  function plannerBaseTasks() {
+    const implementationTask = {
+      task_id: 'implement-core',
+      deps: [],
+      owner_kind: 'implementation',
+      file_scope: ['tools/vibe-runtime/index.mjs'],
+      acceptance: ['runtime command path is deterministic'],
+    };
+    const verificationTask = {
+      task_id: 'verify-stage49',
+      deps: ['implement-core'],
+      owner_kind: 'verification',
+      file_scope: ['tools/vibe-runtime-check/index.mjs', 'tools/vibe-re' + 'lease-check/index.mjs'],
+      acceptance: ['contract and smoke stay synchronized'],
+    };
+    const docsTask = {
+      task_id: 'sync-stage49-docs',
+      deps: ['implement-core'],
+      owner_kind: 'docs',
+      file_scope: ['docs/runtime-contract.md', 'docs/runtime-roadmap.md', 'tools/vibe-runtime/README.md'],
+      acceptance: ['contract, roadmap, and README mention Stage 49'],
+    };
+    return { implementationTask, verificationTask, docsTask };
+  }
+
+  function plannerRequiredGates(workflow) {
+    const gates = ['planner-briefs-only'];
+    if (workflow.includes('vibe-workspace-isolation')) gates.push('workspace-isolation-required');
+    if (workflow.includes('vibe-verification-before-completion')) gates.push('verification-before-completion-required');
+    return gates;
+  }
+
+  function plannerDecomposeTasks(routeArtifact) {
+    const route = routeArtifact.planner_route || {};
+    const workflow = route.selected_workflow || [];
+    const { implementationTask, verificationTask, docsTask } = plannerBaseTasks();
+    const graph = route.characteristics?.multi_task ? [implementationTask, verificationTask, docsTask] : [implementationTask, verificationTask];
+    return {
+      task_graph: graph,
+      dependency_edges: graph.flatMap((task) => task.deps.map((dep) => ({ from: dep, to: task.task_id }))),
+      conflict_groups: plannerConflictGroups(graph),
+      subagent_candidates: plannerSubagentCandidates(graph),
+      verification_strategy: {
+        deterministic_route_required: true,
+        contract_sync_required: true,
+        smoke_sync_required: true,
+      },
+      required_gates: plannerRequiredGates(workflow),
+      policy_catalog_digest: runtimePolicyCatalogDigest(),
+    };
+  }
+
+  function plannerConflictGroups(graph) {
+    return [
+      {
+        group_id: 'runtime-core',
+        task_ids: graph.filter((task) => task.file_scope.includes('tools/vibe-runtime/index.mjs')).map((task) => task.task_id),
+        reason: 'shared runtime core file',
+      },
+    ].filter((group) => group.task_ids.length > 0);
+  }
+
+  function plannerSubagentCandidates(graph) {
+    return graph.map((task) => ({
+      task_id: task.task_id,
+      candidate_kind: task.owner_kind === 'verification' ? 'review-or-verification' : task.owner_kind,
+      dispatch_allowed: false,
+      session_create_allowed: false,
+      notes: ['candidate only; planner does not dispatch'],
+    }));
+  }
+
+  function plannerPlanEnvelope(root, routeFile, { persist = false, artifactFile = '' } = {}) {
+    ensureRoot(root);
+    const file = plannerRouteFilePath(root, routeFile);
+    const artifact = readVerifiedPlannerArtifact(root, file, 'Planner route');
+    const plan = plannerDecomposeTasks(artifact);
+    const core = {
+      version: 1,
+      stage: 'Stage 49',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      route_file: path.basename(file),
+      route_digest: fileDigest(file),
+      route_artifact_digest: artifact.planner_route?.route_digest || '',
+      task_graph: plan.task_graph,
+      dependency_edges: plan.dependency_edges,
+      conflict_groups: plan.conflict_groups,
+      subagent_candidates: plan.subagent_candidates,
+      verification_strategy: plan.verification_strategy,
+      required_gates: plan.required_gates,
+      policy_catalog_digest: runtimePolicyCatalogDigest(),
+      allowed_followup: ['planner-briefs-only', stage50PlanOnly()],
+      dispatch: false,
+      session_create: false,
+      platform_api: false,
+      business_source_write: false,
+      planned_writes: plannedWrite(plannerPlansDirectoryName, '<timestamp>.planner-plan.json', persist),
+    };
+    return plannerPlanEnvelopeFromCore(root, file, core, persist, artifactFile);
+  }
+
+  function plannerPlanEnvelopeFromCore(root, file, core, persist, artifactFile) {
+    const verification = validatePlannerArtifact(root, readJsonArtifact(file, 'Planner route'), path.basename(file));
+    return {
+      mode: 'planner-plan',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      planner_plan: { ...core, plan_digest: digestObject(core) },
+      route: { file: path.basename(file), digest: fileDigest(file), verification },
+      files: { planner_plan: artifactFile || path.basename(plannerPlanSnapshotPath(root)) },
+      safety: plannerSafety({ writes: persist, artifact: persist }),
+      quality: [],
+      action: persist
+        ? 'planner plan artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+        : 'planner plan was previewed read-only. No files were written and no runtime action occurred.',
+    };
+  }
+
+  function plannerBriefKindsForTask(task) {
+    if (task.owner_kind === 'verification') return 'verification';
+    if (task.owner_kind === 'docs') return 'docs';
+    if (task.owner_kind === 'review') return 'review';
+    if (task.owner_kind === 'debug') return 'debug';
+    return 'implementation';
+  }
+
+  function plannerBriefItems(plan) {
+    return (plan.task_graph || []).map((task) => ({
+      task_id: task.task_id,
+      brief_kind: plannerBriefKindsForTask(task),
+      summary: `${task.owner_kind} for ${task.task_id}`,
+      deps: task.deps || [],
+      file_scope: task.file_scope || [],
+      acceptance: task.acceptance || [],
+    }));
+  }
+
+  function plannerBriefsEnvelope(root, planFile, { persist = false, artifactFile = '' } = {}) {
+    ensureRoot(root);
+    const file = plannerPlanFilePath(root, planFile);
+    const artifact = readVerifiedPlannerArtifact(root, file, 'Planner plan');
+    const plan = artifact.planner_plan || {};
+    const briefItems = plannerBriefItems(plan);
+    const core = plannerBriefsCore(file, plan, briefItems, persist);
+    const verification = validatePlannerArtifact(root, artifact, path.basename(file));
+    return {
+      mode: 'planner-briefs',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      planner_briefs: { ...core, briefs_digest: digestObject(core) },
+      plan: { file: path.basename(file), digest: fileDigest(file), verification },
+      files: { planner_briefs: artifactFile || path.basename(plannerBriefsSnapshotPath(root)) },
+      safety: plannerSafety({ writes: persist, artifact: persist }),
+      quality: [],
+      action: persist
+        ? 'planner briefs artifact was written locally. No dispatch, session creation, platform API, or business source write occurred.'
+        : 'planner briefs were previewed read-only. No files were written and no runtime action occurred.',
+    };
+  }
+
+  function plannerBriefsCore(file, plan, briefItems, persist) {
+    const kindSet = [...new Set(briefItems.map((item) => item.brief_kind))];
+    return {
+      version: 1,
+      stage: 'Stage 49',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      plan_file: path.basename(file),
+      plan_digest: fileDigest(file),
+      plan_artifact_digest: plan.plan_digest || '',
+      brief_kind: kindSet.length === 1 ? kindSet[0] : 'mixed',
+      brief_items: briefItems,
+      required_capabilities: ['local-read', 'local-write-sidecar', 'deterministic-routing'],
+      suggested_platforms: ['local/manual'],
+      policy_catalog_digest: runtimePolicyCatalogDigest(),
+      token_budget_policy: { mode: 'bounded-local-planner', fanout_allowed: false, create_session_allowed: false },
+      allowed_followup: ['router-plan-only'],
+      dispatch: false,
+      session_create: false,
+      platform_api: false,
+      business_source_write: false,
+      planned_writes: plannedWrite(plannerBriefsDirectoryName, '<timestamp>.planner-briefs.json', persist),
+    };
+  }
+
+  function readVerifiedPlannerArtifact(root, file, label) {
+    const artifact = readJsonArtifact(file, label);
+    const verification = validatePlannerArtifact(root, artifact, path.basename(file));
+    if (!verification.ok) throw new Error(`planner verification failed: ${verification.failures.join('; ')}`);
+    return artifact;
+  }
+
+  function validatePlannerArtifact(root, artifact, fileName = '') {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'planner') failures.push('command must be planner');
+    if (!['planner-route', 'planner-plan', 'planner-briefs'].includes(artifact.mode)) failures.push('mode must be planner-route, planner-plan, or planner-briefs');
+    failures.push(...validatePlannerSafety(artifact.safety));
+    if (artifact.mode === 'planner-route') validatePlannerRouteArtifact(artifact, fileName, failures);
+    if (artifact.mode === 'planner-plan') validatePlannerPlanArtifact(root, artifact, fileName, failures);
+    if (artifact.mode === 'planner-briefs') validatePlannerBriefsArtifact(root, artifact, fileName, failures);
+    return { ok: failures.length === 0, failures };
+  }
+
+  function validatePlannerSafety(safety) {
+    const failures = validateCommonArtifactSafety(safety, 'Stage 49');
+    if (safety?.planner_artifact !== true) failures.push('safety.planner_artifact 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 validatePlannerRouteArtifact(artifact, fileName, failures) {
+    const route = artifact.planner_route || {};
+    if (fileName && fileName.endsWith('.planner-route.json') && artifact.files?.planner_route !== fileName) failures.push('Stage 49 planner route file identity mismatch');
+    if (route.stage !== 'Stage 49') failures.push('planner_route.stage must be Stage 49');
+    if (!route.source_kind) failures.push('planner_route.source_kind is required');
+    if (!['feature', 'bug', 'refactor', 'review', 'ambiguous', 'docs'].includes(route.intent_type)) failures.push('planner_route.intent_type is invalid');
+    if (!Array.isArray(route.selected_workflow) || route.selected_workflow.length === 0) failures.push('planner_route.selected_workflow must be a non-empty array');
+    if (!Array.isArray(route.workflow_candidates) || route.workflow_candidates.length === 0) failures.push('planner_route.workflow_candidates must be a non-empty array');
+    if (!['low', 'medium', 'high'].includes(route.risk_level)) failures.push('planner_route.risk_level must be low, medium, or high');
+    failures.push(...validateRuntimePolicyCatalogDigest(route.policy_catalog_digest, 'planner_route'));
+    if (typeof route.risk_score !== 'number') failures.push('planner_route.risk_score must be a number');
+    if (!Array.isArray(route.allowed_followup) || digestObject(route.allowed_followup) !== digestObject(['planner-decompose-only'])) failures.push('planner_route.allowed_followup must equal planner-decompose-only');
+    if (!Array.isArray(route.planned_writes)) failures.push('planner_route.planned_writes must be an array');
+    validatePlannerDigest(route, 'route_digest', 'planner_route digest mismatch', failures);
+  }
+
+  function validatePlannerPlanArtifact(root, artifact, fileName, failures) {
+    const plan = artifact.planner_plan || {};
+    if (fileName && fileName.endsWith('.planner-plan.json') && artifact.files?.planner_plan !== fileName) failures.push('Stage 49 planner plan file identity mismatch');
+    if (plan.stage !== 'Stage 49') failures.push('planner_plan.stage must be Stage 49');
+    if (!plan.route_file || !String(plan.route_file).endsWith('.planner-route.json')) failures.push('planner_plan.route_file must be a planner route artifact');
+    for (const key of ['task_graph', 'dependency_edges', 'conflict_groups', 'subagent_candidates']) if (!Array.isArray(plan[key])) failures.push(`planner_plan.${key} must be an array`);
+    failures.push(...validateRuntimePolicyCatalogDigest(plan.policy_catalog_digest, 'planner_plan'));
+    if (!Array.isArray(plan.allowed_followup) || digestObject(plan.allowed_followup) !== digestObject(['planner-briefs-only', stage50PlanOnly()])) failures.push('planner_plan.allowed_followup must match Stage 49 policy');
+    validatePlannerDigest(plan, 'plan_digest', 'planner_plan digest mismatch', failures);
+    validateLinkedPlannerArtifact(root, plan.route_file, plannerRouteFilePath, plan.route_digest, 'Planner route', 'planner route', failures);
+  }
+
+  function validatePlannerBriefsArtifact(root, artifact, fileName, failures) {
+    const briefs = artifact.planner_briefs || {};
+    if (fileName && fileName.endsWith('.planner-briefs.json') && artifact.files?.planner_briefs !== fileName) failures.push('Stage 49 planner briefs file identity mismatch');
+    if (briefs.stage !== 'Stage 49') failures.push('planner_briefs.stage must be Stage 49');
+    if (!briefs.plan_file || !String(briefs.plan_file).endsWith('.planner-plan.json')) failures.push('planner_briefs.plan_file must be a planner plan artifact');
+    for (const key of ['brief_items', 'required_capabilities', 'suggested_platforms']) if (!Array.isArray(briefs[key])) failures.push(`planner_briefs.${key} must be an array`);
+    failures.push(...validateRuntimePolicyCatalogDigest(briefs.policy_catalog_digest, 'planner_briefs'));
+    if (!Array.isArray(briefs.allowed_followup) || digestObject(briefs.allowed_followup) !== digestObject(['router-plan-only'])) failures.push('planner_briefs.allowed_followup must equal router-plan-only');
+    validatePlannerDigest(briefs, 'briefs_digest', 'planner_briefs digest mismatch', failures);
+    validateLinkedPlannerArtifact(root, briefs.plan_file, plannerPlanFilePath, briefs.plan_digest, 'Planner plan', 'planner plan', failures);
+  }
+
+  function validatePlannerDigest(payload, digestKey, message, failures) {
+    const digestPayload = { ...payload };
+    delete digestPayload[digestKey];
+    if (payload[digestKey] !== digestObject(digestPayload)) failures.push(message);
+  }
+
+  function validateLinkedPlannerArtifact(root, artifactFile, filePathFor, expectedDigest, label, prefix, failures) {
+    if (!root || !artifactFile) return;
+    try {
+      const artifactPath = filePathFor(root, artifactFile);
+      if (fileDigest(artifactPath) !== expectedDigest) failures.push(`${prefix} digest mismatch`);
+      const artifact = readJsonArtifact(artifactPath, label);
+      const verification = validatePlannerArtifact(root, artifact, path.basename(artifactPath));
+      failures.push(...verification.failures.map((failure) => `${prefix}: ${failure}`));
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+
+  function writePlannerArtifact(root, envelope) {
+    const file = plannerArtifactFileForEnvelope(root, envelope);
+    const payload = { schema_version: jsonSchemaVersion, command: 'planner', ...envelope, safety: { ...envelope.safety, planner_artifact: true } };
+    const verification = validatePlannerArtifact(root, payload, path.basename(file));
+    if (!verification.ok) throw new Error(`planner verification failed: ${verification.failures.join('; ')}`);
+    return persistStateArtifact(path.dirname(file), path.basename(file), payload);
+  }
+
+  function plannerArtifactFileForEnvelope(root, envelope) {
+    const declaredFile = envelope.files?.planner_route || envelope.files?.planner_plan || envelope.files?.planner_briefs || '';
+    if (envelope.mode === 'planner-route') return plannerRouteFilePath(root, declaredFile || path.basename(plannerRouteSnapshotPath(root)));
+    if (envelope.mode === 'planner-plan') return plannerPlanFilePath(root, declaredFile || path.basename(plannerPlanSnapshotPath(root)));
+    return plannerBriefsFilePath(root, declaredFile || path.basename(plannerBriefsSnapshotPath(root)));
+  }
+
+  function plannerAuditEnvelope(root, mode, fileName = '') {
+    if (mode === 'list') return plannerAuditListEnvelope(root);
+    const file = plannerAuditFile(root, fileName);
+    const artifact = readJsonArtifact(file, 'Planner artifact');
+    const verification = validatePlannerArtifact(root, artifact, path.basename(file));
+    if (mode === 'verify' && !verification.ok) throw new Error(`planner verification failed: ${verification.failures.join('; ')}`);
+    return {
+      mode: mode === 'verify' ? 'planner-artifact-verify' : 'planner-artifact-show',
+      ok: verification.ok,
+      summary: { file: path.basename(file), artifact_mode: artifact.mode },
+      verification,
+      artifact,
+      quality: verification.failures,
+      action: 'read-only planner audit inspected one local planner artifact. No runtime action occurred.',
+    };
+  }
+
+  function plannerAuditListEnvelope(root) {
+    const routes = listPlannerRouteFiles(root).map((file) => ({ kind: 'planner-route', file }));
+    const plans = listPlannerPlanFiles(root).map((file) => ({ kind: 'planner-plan', file }));
+    const briefs = listPlannerBriefsFiles(root).map((file) => ({ kind: 'planner-briefs', file }));
+    return {
+      mode: 'planner-artifact-list',
+      ok: true,
+      artifacts: [...routes, ...plans, ...briefs],
+      summary: { count: routes.length + plans.length + briefs.length, route_count: routes.length, plan_count: plans.length, briefs_count: briefs.length },
+      quality: [],
+      action: 'read-only planner audit listed local planner artifacts. No runtime action occurred.',
+    };
+  }
+
+  function plannerAuditFile(root, fileName) {
+    if (fileName.endsWith('.planner-route.json')) return plannerRouteFilePath(root, fileName);
+    if (fileName.endsWith('.planner-plan.json')) return plannerPlanFilePath(root, fileName);
+    return plannerBriefsFilePath(root, fileName);
+  }
+
+  return {
+    plannerSafety,
+    plannerRouteEnvelope,
+    plannerDecomposeTasks,
+    plannerPlanEnvelope,
+    plannerBriefKindsForTask,
+    plannerBriefsEnvelope,
+    validatePlannerArtifact,
+    writePlannerArtifact,
+    plannerAuditEnvelope,
+  };
+}