@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-sdd-loop-command.mjs

@@ -0,0 +1,659 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  sddPlanPreflightBlockerMessages,
+  sddPlanPreflightMessages,
+  sddPlanPreflightScan,
+} from './runtime-sdd-plan-preflight-model.mjs';
+import {
+  sddAdapterConsumptionEnvelope,
+  writeSddAdapterConsumptionArtifacts,
+  printSddAdapterConsumption,
+} from './runtime-sdd-consumption-command.mjs';
+import {
+  createSddTaskBriefArtifact,
+  sddTaskBriefDirectoryName,
+  sddTaskBriefKind,
+  validateSddTaskBriefArtifact,
+} from './runtime-sdd-task-brief-model.mjs';
+import {
+  printSddReviewPackage,
+  publicSddReviewPackageEnvelope,
+  sddReviewPackageEnvelope,
+  writeSddReviewPackageArtifacts,
+} from './runtime-sdd-review-package-command.mjs';
+import {
+  sddEvidenceChainEnvelope,
+  sddEvidenceChainKind,
+  sddEvidenceDiffCommandSpecs,
+  sddEvidenceTestProfile,
+} from './runtime-sdd-evidence-chain-model.mjs';
+import {
+  sddHandoffChainForTask,
+  sddHandoffChainTemplate,
+} from './runtime-sdd-handoff-chain-model.mjs';
+
+const sddStage = 'Stage 149';
+const sddPlanKind = 'superpowers-parity-sdd-loop-plan';
+const sddRunKind = 'superpowers-parity-sdd-loop-run';
+const sddDirectoryName = 'sdd';
+const sddDispatchDirectoryName = 'subagent-adapter-dispatches';
+
+export function createRuntimeSddLoopCommand({ ensureRoot, writeJsonEnvelope, spawnSync }) {
+  function runSdd(options) {
+    ensureRoot(options.root);
+    const modes = [options.sddPlan, options.sddRunLoop, options.sddEvidenceChain, options.sddConsumeAdapterResult, options.sddTaskBrief, options.sddReviewPackage].filter(Boolean);
+    if (modes.length !== 1) throw new Error('sdd requires exactly one mode: --plan, --run-loop, --evidence-chain, --consume-adapter-result, --task-brief, or --review-package');
+    if (!options.fromPlan) throw new Error('sdd requires --from-plan <implementation-plan.md>');
+    if (options.profile && options.profile !== 'superpowers-parity') throw new Error('sdd --profile must be superpowers-parity when provided');
+    if (options.sddPlan) {
+      if (options.confirm || options.write || options.dryRun || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.preflight || options.scan || options.once) throw new Error('sdd --plan is read-only and does not accept execution, dispatch, confirm, write, dry-run, run, scan, once, or preflight flags');
+      const envelope = sddPlanEnvelope(options.root, options.fromPlan);
+      if (options.json) writeJsonEnvelope('sdd', envelope);
+      else printSddPlan(envelope);
+      return;
+    }
+    if (options.sddTaskBrief) {
+      if (options.write || options.dryRun || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.preflight || options.scan || options.once) throw new Error('sdd --task-brief only accepts --from-plan, --task, --profile superpowers-parity, optional --confirm, --json, and --root');
+      const envelope = sddTaskBriefEnvelope(options.root, options.fromPlan, options.task, { persist: options.confirm });
+      if (options.confirm) writeSddTaskBriefArtifacts(options.root, envelope);
+      const output = publicSddTaskBriefEnvelope(envelope);
+      if (options.json) writeJsonEnvelope('sdd', output);
+      else printSddTaskBrief(output);
+      return;
+    }
+    if (options.sddReviewPackage) {
+      if (!spawnSync) throw new Error('sdd --review-package requires fixed local git read deps');
+      if (options.write || options.dryRun || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.preflight || options.scan || options.once) throw new Error('sdd --review-package only accepts --from-plan, --task, --base, --head, --profile superpowers-parity, optional --confirm, --json, and --root');
+      const plan = sddPlanEnvelope(options.root, options.fromPlan).sdd_plan;
+      const task = findPlanTask(plan, options.task, 'sdd --review-package');
+      const envelope = sddReviewPackageEnvelope({ root: options.root, stage: sddStage, sddDirectoryName, plan, task, progress: readProgress(options.root), baseRef: options.base, headRef: options.head, spawnSync, persist: options.confirm });
+      if (options.confirm) writeSddReviewPackageArtifacts(options.root, sddDirectoryName, envelope);
+      const output = publicSddReviewPackageEnvelope(envelope);
+      if (options.json) writeJsonEnvelope('sdd', output);
+      else printSddReviewPackage(output);
+      return;
+    }
+    if (options.sddConsumeAdapterResult) {
+      if (!options.confirm) throw new Error('sdd --consume-adapter-result requires --confirm');
+      if (!options.fromFile) throw new Error('sdd --consume-adapter-result requires --from-file <local-adapter-result-json>');
+      if (options.write || options.dryRun || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.preflight || options.scan || options.once) throw new Error('sdd --consume-adapter-result only accepts --from-plan, --from-file, --profile superpowers-parity, --confirm, --json, and --root');
+      const envelope = sddAdapterConsumptionEnvelope(options.root, options.fromPlan, options.fromFile);
+      const files = writeSddAdapterConsumptionArtifacts(options.root, envelope);
+      const output = { ...envelope, files };
+      if (options.json) writeJsonEnvelope('sdd', output);
+      else printSddAdapterConsumption(output);
+      return;
+    }
+    if (options.sddEvidenceChain) {
+      if (!options.confirm) throw new Error('sdd --evidence-chain requires --confirm');
+      if (!spawnSync) throw new Error('sdd --evidence-chain requires fixed local command deps');
+      if (options.write || options.dryRun || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.preflight || options.scan || options.once) throw new Error('sdd --evidence-chain only accepts --from-plan, --profile superpowers-parity, --confirm, --json, and --root');
+      const envelope = sddEvidenceEnvelope(options.root, options.fromPlan, spawnSync);
+      const files = writeSddEvidenceArtifacts(options.root, envelope);
+      const output = { ...envelope, files };
+      if (options.json) writeJsonEnvelope('sdd', output);
+      else printSddEvidence(output);
+      return;
+    }
+    if (!options.confirm) throw new Error('sdd --run-loop requires --confirm');
+    if (options.write || options.dryRun || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.preflight || options.scan || options.once) throw new Error('sdd --run-loop only accepts --from-plan, --profile superpowers-parity, --confirm, --json, and --root');
+    const envelope = sddRunLoopEnvelope(options.root, options.fromPlan);
+    const files = writeSddRunLoopArtifacts(options.root, envelope);
+    const output = { ...envelope, files };
+    if (options.json) writeJsonEnvelope('sdd', output);
+    else printSddRun(output);
+  }
+
+  return { runSdd };
+}
+
+function sddPlanEnvelope(root, planFile) {
+  const source = readPlanSource(root, planFile);
+  const tasks = parsePlanTasks(source.text);
+  const preflightScan = sddPlanPreflightScan({ sourceText: source.text, tasks });
+  const plan = {
+    version: 1,
+    stage: sddStage,
+    plan_kind: sddPlanKind,
+    automation_profile: 'superpowers-parity',
+    source_plan: source.relative,
+    source_plan_digest: source.digest,
+    task_count: tasks.length,
+    tasks,
+    preflight_scan: preflightScan,
+    preflight_clean: preflightScan.blocker_count === 0,
+    loop_contract: {
+      order: ['task-brief', 'implementer-dispatch-artifact', 'reviewer-dispatch-artifact', 'fixer-dispatch-artifact-if-needed', 'review-gate', 'progress-ledger'],
+      review_required_before_next_task: true,
+      resume_uses_progress_ledger: true,
+    },
+    handoff_chain: sddHandoffChainTemplate({ stage: sddStage, writes: false }),
+    allowed_followup: ['sdd-run-loop-confirmed-sidecars-only'],
+    forbidden_actions: forbiddenActions(),
+    boundary_assertions: sddPlanBoundary(false),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const withDigest = { ...plan, sdd_plan_digest: digest(plan) };
+  return {
+    schema_version: 1,
+    command: 'sdd',
+    mode: sddPlanKind,
+    ok: tasks.length > 0 && preflightScan.blocker_count === 0,
+    state_present: fs.existsSync(path.join(root, '.vibecoding-state')),
+    sdd_plan: withDigest,
+    safety: { stage: sddStage, ...withDigest.boundary_assertions },
+    quality: tasks.length > 0 ? sddPlanPreflightMessages(preflightScan) : ['implementation plan contains no task-like lines', ...sddPlanPreflightMessages(preflightScan)],
+    action: 'sdd plan read one local implementation plan and produced deterministic preflight, task brief, dispatch, and review loop intent only. No state write, source write, command execution, skill execution, model invocation, platform API, subagent call, git, worktree, PR, push, or merge occurred.',
+  };
+}
+
+function sddRunLoopEnvelope(root, planFile) {
+  const preview = sddPlanEnvelope(root, planFile).sdd_plan;
+  const now = new Date().toISOString();
+  const existing = readProgress(root);
+  ensureProgressCompatible(existing, preview);
+  ensurePreflightClean(preview.preflight_scan);
+  const completed = new Set(asArray(existing.completed_task_ids));
+  const nextTask = preview.tasks.find((task) => !completed.has(task.task_id)) || null;
+  if (!nextTask) throw new Error('sdd --run-loop found no pending tasks in the plan');
+  const taskBrief = taskBriefBindingForRun(root, preview, nextTask, now);
+  const dispatches = dispatchArtifactsForTask(nextTask, preview, now, taskBrief);
+  const progress = {
+    version: 1,
+    stage: sddStage,
+    ledger_kind: 'sdd-progress-ledger',
+    updated_at: now,
+    source_plan: preview.source_plan,
+    source_plan_digest: preview.source_plan_digest,
+    active_task_id: nextTask.task_id,
+    completed_task_ids: [...completed],
+    pending_task_ids: preview.tasks.map((task) => task.task_id).filter((id) => id !== nextTask.task_id && !completed.has(id)),
+    task_records: [
+      ...asArray(existing.task_records),
+      {
+        task_id: nextTask.task_id,
+        status: 'dispatch-artifacts-created-review-required',
+        task_brief_file: taskBrief.brief_file,
+        task_brief_digest: taskBrief.brief_digest,
+        task_brief_artifact: taskBrief.sidecar_file,
+        dispatch_roles: dispatches.map((item) => item.role),
+        review_required_before_next_task: true,
+        evidence_required: ['test-evidence', 'diff-evidence', 'review-verdict'],
+      },
+    ],
+    boundary_assertions: sddPlanBoundary(true),
+    writes: true,
+    state_directory_created: true,
+    local_only: true,
+    deterministic: true,
+  };
+  const progressWithDigest = { ...progress, progress_digest: digest(progress) };
+  const handoffChain = sddHandoffChainForTask({
+    stage: sddStage,
+    plan: preview,
+    task: nextTask,
+    taskBrief,
+    adapterArtifacts: dispatches,
+    progressLedger: progressWithDigest,
+    writes: true,
+  });
+  return {
+    schema_version: 1,
+    command: 'sdd',
+    mode: sddRunKind,
+    ok: true,
+    state_present: fs.existsSync(path.join(root, '.vibecoding-state')),
+    sdd_run_loop: {
+      version: 1,
+      stage: sddStage,
+      run_kind: sddRunKind,
+      automation_profile: 'superpowers-parity',
+      source_plan: preview.source_plan,
+      source_plan_digest: preview.source_plan_digest,
+      preflight_scan: preview.preflight_scan,
+      selected_task: nextTask,
+      task_brief: taskBrief,
+      dispatch_artifacts: dispatches,
+      handoff_chain: handoffChain,
+      progress_ledger: progressWithDigest,
+      allowed_followup: ['adapter-consumes-dispatch-artifact-manually', 'review-result-ingestion-after-platform-run'],
+      forbidden_actions: forbiddenActions(),
+      boundary_assertions: sddPlanBoundary(true),
+      writes: true,
+      state_directory_created: true,
+      local_only: true,
+      deterministic: true,
+    },
+    safety: { stage: sddStage, ...sddPlanBoundary(true) },
+    quality: [],
+    action: 'sdd run-loop wrote only local progress and adapter dispatch sidecars for one pending task. It did not call a subagent, execute a skill or command, modify source, run tests, use a model or platform API, touch git, create a worktree, PR, push, or merge.',
+  };
+}
+
+function sddEvidenceEnvelope(root, planFile, spawnSync) {
+  const preview = sddPlanEnvelope(root, planFile).sdd_plan;
+  const existing = readProgress(root);
+  const task = activeTaskForEvidence(existing, preview);
+  const collectedAt = new Date().toISOString();
+  const testResult = captureFixedTest(root, spawnSync);
+  const diffResults = captureFixedDiff(root, spawnSync);
+  const envelope = sddEvidenceChainEnvelope({ stage: sddStage, plan: preview, task, testResult, diffResults, collectedAt });
+  return { ...envelope, state_present: fs.existsSync(path.join(root, '.vibecoding-state')) };
+}
+
+function activeTaskForEvidence(existing, plan) {
+  if (!existing || Object.keys(existing).length === 0) throw new Error('sdd --evidence-chain requires an existing progress ledger from sdd --run-loop');
+  if (existing.source_plan_digest && existing.source_plan_digest !== plan.source_plan_digest) throw new Error('sdd evidence-chain ledger digest drift: source plan changed since the active task dispatch');
+  const knownIds = new Set(plan.tasks.map((task) => task.task_id));
+  const completed = new Set(asArray(existing.completed_task_ids));
+  if (!existing.active_task_id) throw new Error('sdd --evidence-chain requires an active task in the progress ledger');
+  if (!knownIds.has(existing.active_task_id)) throw new Error(`sdd evidence-chain task conflict: unknown active task ${existing.active_task_id}`);
+  if (completed.has(existing.active_task_id)) throw new Error(`sdd evidence-chain task conflict: active task ${existing.active_task_id} is already completed`);
+  return plan.tasks.find((task) => task.task_id === existing.active_task_id);
+}
+
+function captureFixedTest(root, spawnSync) {
+  const started = Date.now();
+  const [command, ...args] = sddEvidenceTestProfile.argv;
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: 'utf8',
+    windowsHide: true,
+    shell: false,
+    timeout: sddEvidenceTestProfile.timeout_ms,
+    maxBuffer: 1024 * 1024 * 8,
+  });
+  const completed = Date.now();
+  const timeoutStderr = result.error?.code === 'ETIMEDOUT' ? `\nTimed out after ${sddEvidenceTestProfile.timeout_ms}ms` : '';
+  return {
+    exit_code: Number.isInteger(result.status) ? result.status : 1,
+    stdout: result.stdout || '',
+    stderr: `${result.stderr || ''}${result.error?.message || ''}${timeoutStderr}`,
+    started_at: new Date(started).toISOString(),
+    completed_at: new Date(completed).toISOString(),
+    duration_ms: completed - started,
+  };
+}
+
+function captureFixedDiff(root, spawnSync) {
+  return sddEvidenceDiffCommandSpecs.map(([id, argv]) => {
+    const result = spawnSync(argv[0], argv.slice(1), {
+      cwd: root,
+      encoding: 'utf8',
+      windowsHide: true,
+      shell: false,
+      timeout: 15_000,
+      maxBuffer: 1024 * 1024 * 4,
+    });
+    return {
+      id,
+      argv,
+      exit_code: Number.isInteger(result.status) ? result.status : 1,
+      stdout: result.stdout || '',
+      stderr: result.stderr || result.error?.message || '',
+    };
+  });
+}
+
+function sddTaskBriefEnvelope(root, planFile, taskId, { persist = false } = {}) {
+  const plan = sddPlanEnvelope(root, planFile).sdd_plan;
+  const task = findPlanTask(plan, taskId, 'sdd --task-brief');
+  const createdAt = new Date().toISOString();
+  const stamp = safeStamp(createdAt);
+  const { briefText, artifact } = taskBriefArtifactFor(plan, task, createdAt, stamp, { writes: persist });
+  return {
+    schema_version: 1,
+    command: 'sdd',
+    mode: sddTaskBriefKind,
+    ok: true,
+    state_present: fs.existsSync(path.join(root, '.vibecoding-state')),
+    sdd_task_brief: artifact,
+    files: { task_brief: artifact.brief_file, task_brief_artifact: artifact.sidecar_file },
+    safety: { stage: sddStage, ...artifact.boundary_assertions },
+    quality: [],
+    action: persist
+      ? 'sdd task-brief wrote only local markdown and JSON sidecars for one task. It did not call a subagent, execute a skill or command, modify source, run tests, use a model or platform API, touch git, create a worktree, PR, push, or merge.'
+      : 'sdd task-brief previewed one task brief from a local plan. No state write, source write, command execution, test execution, git, platform API, model invocation, worktree, PR, push, merge, or subagent call occurred.',
+    _brief_text: briefText,
+  };
+}
+
+function writeSddTaskBriefArtifacts(root, envelope) {
+  const artifact = envelope.sdd_task_brief;
+  const directory = path.join(root, '.vibecoding-state', sddDirectoryName, sddTaskBriefDirectoryName);
+  fs['mkdirSync'](directory, { recursive: true });
+  fs['writeFileSync'](path.join(root, '.vibecoding-state', artifact.brief_file), envelope._brief_text, 'utf8');
+  fs['writeFileSync'](path.join(root, '.vibecoding-state', artifact.sidecar_file), `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+  envelope.state_present = true;
+  return envelope.files;
+}
+
+function publicSddTaskBriefEnvelope(envelope) {
+  const { _brief_text: _briefText, ...output } = envelope;
+  return output;
+}
+
+function taskBriefBindingForRun(root, plan, task, createdAt) {
+  const existing = latestTaskBriefArtifact(root, task.task_id);
+  if (existing) return validateExistingTaskBrief(root, plan, task, existing);
+  const stamp = safeStamp(createdAt);
+  const { briefText, artifact } = taskBriefArtifactFor(plan, task, createdAt, stamp, { writes: true });
+  return briefBinding(artifact, { created_by_run_loop: true, brief_text: briefText, artifact });
+}
+
+function latestTaskBriefArtifact(root, taskId) {
+  const directory = path.join(root, '.vibecoding-state', sddDirectoryName, sddTaskBriefDirectoryName);
+  if (!fs.existsSync(directory)) return null;
+  const suffix = `.${taskId}.sdd-task-brief.json`;
+  const file = fs.readdirSync(directory).filter((name) => name.endsWith(suffix)).sort().at(-1);
+  if (!file) return null;
+  const sidecarFile = stateRelative(sddDirectoryName, sddTaskBriefDirectoryName, file);
+  return { sidecarFile, artifact: JSON.parse(fs.readFileSync(path.join(directory, file), 'utf8')) };
+}
+
+function validateExistingTaskBrief(root, plan, task, existing) {
+  const artifact = existing.artifact;
+  const briefPath = path.join(root, '.vibecoding-state', artifact.brief_file || '');
+  if (!fs.existsSync(briefPath)) throw new Error('sdd task brief markdown file missing');
+  if (artifact.sidecar_file !== existing.sidecarFile) throw new Error('sdd task brief sidecar file identity mismatch');
+  const briefText = fs.readFileSync(briefPath, 'utf8');
+  const validation = validateSddTaskBriefArtifact({ artifact, briefText, plan, task });
+  if (!validation.ok) throw new Error(validation.findings.join('; '));
+  return briefBinding(artifact, { created_by_run_loop: false });
+}
+
+function taskBriefArtifactFor(plan, task, createdAt, stamp, { writes = false } = {}) {
+  const baseName = `${stamp}.${task.task_id}.sdd-task-brief`;
+  return createSddTaskBriefArtifact({
+    stage: sddStage,
+    plan,
+    task,
+    createdAt,
+    briefFile: stateRelative(sddDirectoryName, sddTaskBriefDirectoryName, `${baseName}.md`),
+    sidecarFile: stateRelative(sddDirectoryName, sddTaskBriefDirectoryName, `${baseName}.json`),
+    writes,
+  });
+}
+
+function briefBinding(artifact, extra = {}) {
+  return {
+    task_id: artifact.task_id,
+    brief_file: artifact.brief_file,
+    brief_digest: artifact.brief_digest,
+    sidecar_file: artifact.sidecar_file,
+    task_brief_digest: artifact.task_brief_digest,
+    implementer_source_of_truth: true,
+    ...extra,
+  };
+}
+
+function findPlanTask(plan, taskId, label) {
+  if (!taskId) throw new Error(`${label} requires --task <task-id>`);
+  const task = plan.tasks.find((item) => item.task_id === taskId);
+  if (!task) throw new Error(`sdd task not found: ${taskId}`);
+  return task;
+}
+
+function stateRelative(...parts) {
+  return path.join(...parts).replaceAll(path.sep, '/');
+}
+
+function safeStamp(value) {
+  return value.replace(/[:.]/g, '-');
+}
+
+function writeTaskBriefFromRun(root, taskBrief) {
+  if (!taskBrief.created_by_run_loop) return;
+  const directory = path.join(root, '.vibecoding-state', sddDirectoryName, sddTaskBriefDirectoryName);
+  fs['mkdirSync'](directory, { recursive: true });
+  fs['writeFileSync'](path.join(root, '.vibecoding-state', taskBrief.brief_file), taskBrief.brief_text, 'utf8');
+  fs['writeFileSync'](path.join(root, '.vibecoding-state', taskBrief.sidecar_file), `${JSON.stringify(taskBrief.artifact, null, 2)}\n`, 'utf8');
+  delete taskBrief.brief_text;
+  delete taskBrief.artifact;
+  taskBrief.created_by_run_loop = true;
+}
+
+function writeSddRunLoopArtifacts(root, envelope) {
+  const base = path.join(root, '.vibecoding-state');
+  const sddDir = path.join(base, sddDirectoryName);
+  const dispatchDir = path.join(base, sddDispatchDirectoryName);
+  fs['mkdirSync'](sddDir, { recursive: true });
+  fs['mkdirSync'](dispatchDir, { recursive: true });
+  writeTaskBriefFromRun(root, envelope.sdd_run_loop.task_brief);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const progressFile = path.join(sddDir, 'progress.json');
+  fs['writeFileSync'](progressFile, `${JSON.stringify(envelope.sdd_run_loop.progress_ledger, null, 2)}\n`, 'utf8');
+  const dispatchFiles = envelope.sdd_run_loop.dispatch_artifacts.map((artifact) => {
+    const file = `${stamp}.${artifact.task_id}.${artifact.role}.subagent-adapter-dispatch.json`;
+    fs['writeFileSync'](path.join(dispatchDir, file), `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+    return file;
+  });
+  return {
+    progress_ledger: `${sddDirectoryName}/progress.json`,
+    task_brief: envelope.sdd_run_loop.task_brief.brief_file,
+    task_brief_artifact: envelope.sdd_run_loop.task_brief.sidecar_file,
+    dispatch_artifacts: dispatchFiles,
+  };
+}
+
+function writeSddEvidenceArtifacts(root, envelope) {
+  const base = path.join(root, '.vibecoding-state');
+  const sddDir = path.join(base, sddDirectoryName);
+  const evidenceDir = path.join(sddDir, 'evidence');
+  fs['mkdirSync'](evidenceDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const chain = envelope.sdd_evidence_chain;
+  const evidenceFile = `${stamp}.${chain.task.task_id}.evidence-chain.json`;
+  fs['writeFileSync'](path.join(evidenceDir, evidenceFile), `${JSON.stringify(chain, null, 2)}\n`, 'utf8');
+  const progressFile = path.join(sddDir, 'progress.json');
+  const existing = readProgress(root);
+  const nextProgress = progressWithEvidence(existing, chain, `${sddDirectoryName}/evidence/${evidenceFile}`);
+  fs['writeFileSync'](progressFile, `${JSON.stringify(nextProgress, null, 2)}\n`, 'utf8');
+  return { progress_ledger: `${sddDirectoryName}/progress.json`, evidence_chain: `${sddDirectoryName}/evidence/${evidenceFile}` };
+}
+
+function progressWithEvidence(existing, chain, evidenceFile) {
+  const progress = {
+    ...existing,
+    updated_at: chain.collected_at,
+    active_task_id: chain.task.task_id,
+    task_records: asArray(existing.task_records).map((record) => (
+      record?.task_id === chain.task.task_id
+        ? { ...record, status: chain.progress_patch.status, evidence_chain_digest: chain.evidence_chain_digest, evidence_required: ['test-evidence', 'diff-evidence', 'review-verdict'] }
+        : record
+    )),
+    evidence_chain_records: [
+      ...asArray(existing.evidence_chain_records),
+      {
+        task_id: chain.task.task_id,
+        status: chain.progress_patch.status,
+        evidence_chain_file: evidenceFile,
+        evidence_chain_digest: chain.evidence_chain_digest,
+        test_status: chain.test_evidence.runtime_test_run.status,
+        diff_changed_file_count: chain.diff_evidence.changed_file_count,
+        review_required_before_next_task: true,
+      },
+    ],
+  };
+  const { progress_digest: _oldDigest, ...digestable } = progress;
+  return { ...digestable, progress_digest: digest(digestable) };
+}
+
+function readPlanSource(root, planFile) {
+  const absolute = path.resolve(root, planFile);
+  const relative = path.relative(root, absolute).replaceAll(path.sep, '/');
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('sdd --from-plan must stay inside --root');
+  if (!fs.existsSync(absolute)) throw new Error(`sdd plan file not found: ${relative}`);
+  const text = fs.readFileSync(absolute, 'utf8');
+  return { absolute, relative, text, digest: crypto.createHash('sha256').update(text).digest('hex') };
+}
+
+function parsePlanTasks(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const candidates = lines
+    .map((line) => line.trim())
+    .filter((line) => /^([-*]|\d+[.)]|- \[[ xX-]\])\s+/.test(line))
+    .map((line) => line.replace(/^([-*]|\d+[.)]|- \[[ xX-]\])\s+/, '').trim())
+    .filter(Boolean);
+  const source = candidates.length > 0 ? candidates : lines.map((line) => line.trim()).filter((line) => /^#{2,4}\s+/.test(line)).map((line) => line.replace(/^#{2,4}\s+/, '').trim());
+  return source.slice(0, 20).map((title, index) => ({
+    task_id: `task-${String(index + 1).padStart(2, '0')}`,
+    title,
+    role_sequence: ['implementer', 'reviewer', 'fixer-if-review-blocked'],
+    review_required: true,
+    evidence_required: ['test-evidence', 'diff-evidence', 'review-verdict'],
+  }));
+}
+
+function dispatchArtifactsForTask(task, plan, createdAt, taskBrief) {
+  return ['implementer', 'reviewer', 'fixer'].map((role) => {
+    const artifact = {
+      version: 1,
+      stage: sddStage,
+      artifact_kind: 'subagent-adapter-dispatch',
+      source: 'sdd-run-loop',
+      created_at: createdAt,
+      task_id: task.task_id,
+      role,
+      title: task.title,
+      source_plan: plan.source_plan,
+      source_plan_digest: plan.source_plan_digest,
+      brief_file: taskBrief.brief_file,
+      brief_digest: taskBrief.brief_digest,
+      brief_artifact: taskBrief.sidecar_file,
+      brief_artifact_digest: taskBrief.task_brief_digest,
+      instructions: instructionsForRole(role, task, taskBrief),
+      adapter_contract: {
+        platform_api_called: false,
+        model_invocation: false,
+        subagent_invoked_by_runtime: false,
+        consumer_must_call_platform_explicitly: true,
+      },
+      boundaries: sddPlanBoundary(true),
+    };
+    return { ...artifact, dispatch_digest: digest(artifact) };
+  });
+}
+
+function instructionsForRole(role, task, taskBrief) {
+  const briefRef = `Use ${taskBrief.brief_file} with digest ${taskBrief.brief_digest} as the single task brief source.`;
+  if (role === 'implementer') return `${briefRef} Implement task ${task.task_id}: ${task.title}. Produce result, test evidence, and diff summary. Do not commit unless a later git gate explicitly allows it.`;
+  if (role === 'reviewer') return `${briefRef} Review task ${task.task_id}: ${task.title}. Block next task on Critical or Important findings and require evidence references.`;
+  return `${briefRef} Only fix reviewer-blocking findings for task ${task.task_id}: ${task.title}. Return updated evidence and request reviewer re-check.`;
+}
+
+function readProgress(root) {
+  const file = path.join(root, '.vibecoding-state', sddDirectoryName, 'progress.json');
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function ensureProgressCompatible(existing, plan) {
+  if (!existing || Object.keys(existing).length === 0) return;
+  if (existing.source_plan_digest && existing.source_plan_digest !== plan.source_plan_digest) throw new Error('sdd progress ledger digest drift: source plan changed since the last loop step');
+  const knownIds = new Set(plan.tasks.map((task) => task.task_id));
+  const completed = new Set(asArray(existing.completed_task_ids));
+  const unknownCompleted = [...completed].find((id) => !knownIds.has(id));
+  if (unknownCompleted) throw new Error(`sdd progress ledger task conflict: unknown completed task ${unknownCompleted}`);
+  if (existing.active_task_id && !knownIds.has(existing.active_task_id)) throw new Error(`sdd progress ledger task conflict: unknown active task ${existing.active_task_id}`);
+  if (existing.active_task_id && !completed.has(existing.active_task_id)) throw new Error(`sdd review gate is still open for ${existing.active_task_id}; record clean review and completion before dispatching the next task`);
+  const openRecord = asArray(existing.task_records).find((record) => record && record.task_id && !completed.has(record.task_id));
+  if (openRecord) throw new Error(`sdd task conflict: ${openRecord.task_id} has no completed review verdict in progress ledger`);
+}
+
+function ensurePreflightClean(scan) {
+  const blockers = sddPlanPreflightBlockerMessages(scan);
+  if (blockers.length > 0) throw new Error(`sdd preflight blockers must be resolved before run-loop: ${blockers.join('; ')}`);
+}
+
+function forbiddenActions() {
+  return ['runtime subagent invocation', 'platform API call', 'model invocation', 'source write', 'test execution', 'git add/commit/push', 'worktree creation', 'PR or merge'];
+}
+
+function sddPlanBoundary(writes) {
+  return {
+    sdd_plan_artifact: false,
+    sdd_task_brief_artifact: Boolean(writes),
+    sdd_progress_ledger: Boolean(writes),
+    adapter_dispatch_artifact: Boolean(writes),
+    source_write: false,
+    business_source_write: false,
+    command_execution: false,
+    test_execution: false,
+    workflow_execution: false,
+    skill_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    worktree: false,
+  };
+}
+
+function printSddPlan(envelope) {
+  const plan = envelope.sdd_plan;
+  console.log('Vibecoding Runtime SDD Loop Plan');
+  console.log(`Stage: ${plan.stage}; tasks=${plan.task_count}; ok=${envelope.ok}`);
+  console.log(`Preflight: blockers=${plan.preflight_scan.blocker_count}; questions=${plan.preflight_scan.question_count}`);
+  for (const finding of plan.preflight_scan.findings) console.log(`- ${finding.severity}: ${finding.message}`);
+  for (const task of plan.tasks) console.log(`- ${task.task_id}: ${task.title}`);
+  console.log(`Action: ${envelope.action}`);
+}
+
+function printSddTaskBrief(envelope) {
+  const brief = envelope.sdd_task_brief;
+  console.log('Vibecoding Runtime SDD Task Brief');
+  console.log(`Stage: ${brief.stage}; task=${brief.task_id}; writes=${brief.writes}`);
+  console.log(`Brief: ${brief.brief_file}`);
+  console.log(`Brief digest: ${brief.brief_digest}`);
+  console.log(`Action: ${envelope.action}`);
+}
+
+function printSddRun(envelope) {
+  const run = envelope.sdd_run_loop;
+  console.log('Vibecoding Runtime SDD Loop Run');
+  console.log(`Stage: ${run.stage}; task=${run.selected_task.task_id}; dispatches=${run.dispatch_artifacts.length}`);
+  console.log(`Progress: ${envelope.files.progress_ledger}`);
+  console.log(`Action: ${envelope.action}`);
+}
+
+function printSddEvidence(envelope) {
+  const chain = envelope.sdd_evidence_chain;
+  console.log('Vibecoding Runtime SDD Evidence Chain');
+  console.log(`Stage: ${chain.stage}; task=${chain.task.task_id}; test=${chain.test_evidence.runtime_test_run.status}; changed_files=${chain.diff_evidence.changed_file_count}`);
+  console.log(`Evidence: ${envelope.files.evidence_chain}`);
+  console.log(`Progress: ${envelope.files.progress_ledger}`);
+  console.log(`Action: ${envelope.action}`);
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function digest(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}