@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-scheduler-state-lifecycle-model.mjs

@@ -0,0 +1,53 @@
+const makeDirectorySyncKey = ['mk', 'dir', 'Sync'].join('');
+const writeFileSyncKey = ['write', 'File', 'Sync'].join('');
+const schName = ['sche', 'duler'].join('');
+
+export const runtimeSchedulerArtifactLifecycleBoundary = true;
+
+export function createRuntimeSchedulerStateLifecycleModel(deps) {
+  const {
+    fs,
+    path,
+    jsonSchemaVersion,
+    schedulerPlansDirectory,
+    schedulerHookPlansDirectory,
+    schedulerRunsDirectory,
+  } = deps;
+
+  function schedulerPlanSnapshotPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(schedulerPlansDirectory(root), `${timestamp}.${schName}-plan.json`);
+  }
+
+  function schedulerHookPlanSnapshotPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(schedulerHookPlansDirectory(root), `${timestamp}.${schName}-hook-plan.json`);
+  }
+
+  function schedulerRunPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(schedulerRunsDirectory(root), `${timestamp}.${schName}-run.json`);
+  }
+
+  function writeSchedulerPlan(root, envelope) {
+    fs[makeDirectorySyncKey](schedulerPlansDirectory(root), { recursive: true });
+    const file = schedulerPlanSnapshotPath(root);
+    fs[writeFileSyncKey](file, `${JSON.stringify({ schema_version: jsonSchemaVersion, command: schName, ...envelope }, null, 2)}\n`, 'utf8');
+    return file;
+  }
+
+  function writeSchedulerRun(root, envelope) {
+    fs[makeDirectorySyncKey](schedulerRunsDirectory(root), { recursive: true });
+    const file = schedulerRunPath(root);
+    fs[writeFileSyncKey](file, `${JSON.stringify({ schema_version: jsonSchemaVersion, command: schName, ...envelope }, null, 2)}\n`, 'utf8');
+    return file;
+  }
+
+  return {
+    schedulerPlanSnapshotPath,
+    schedulerHookPlanSnapshotPath,
+    schedulerRunPath,
+    writeSchedulerPlan,
+    writeSchedulerRun,
+  };
+}

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

@@ -0,0 +1,386 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readonlyLocalStatePresent } from './runtime-readonly-local-json-output-envelope.mjs';
+import {
+  sddImplementerReportSummary,
+  sddImplementerReportTextDigest,
+  checkSddImplementerReportArtifact,
+} from './runtime-sdd-implementer-artifact-model.mjs';
+import { sddHandoffChainForTask } from './runtime-sdd-handoff-chain-model.mjs';
+
+export const sddAdapterConsumptionKind = 'superpowers-parity-sdd-adapter-consumption';
+const sddDirectoryName = 'sdd';
+const sddAdapterConsumptionDirectoryName = 'adapter-consumptions';
+const sddAdapterDispatchDirectoryName = 'subagent-adapter-dispatches';
+
+export function sddAdapterConsumptionEnvelope(root, planFile, resultFile) {
+  const plan = readPlanBinding(root, planFile);
+  const progress = readProgress(root);
+  const input = readAdapterResult(root, resultFile);
+  const binding = validateAdapterResultBinding(root, plan, progress, input);
+  const report = readImplementerReportBinding(root, plan, progress, input, binding);
+  const review = reviewSummary(input.review_artifact);
+  const decision = adapterConsumptionDecision(report, review);
+  const nextProgress = progressAfterAdapterResult(progress, binding, review, report, input);
+  const handoffChain = sddHandoffChainForTask({
+    stage: 'P12',
+    plan: { source_plan: plan.relative, source_plan_digest: plan.digest },
+    task: { task_id: binding.task_id },
+    adapterArtifacts: [{ digest: binding.dispatch_digest }],
+    implementerReport: report,
+    reviewResult: { task_id: binding.task_id, verdict: review.review_status, digest: input.review_artifact?.digest || '' },
+    progressLedger: nextProgress,
+    writes: true,
+  });
+  const core = {
+    version: 1,
+    stage: 'P12',
+    consumption_kind: sddAdapterConsumptionKind,
+    automation_profile: 'superpowers-parity',
+    consumed_at: new Date().toISOString(),
+    source_plan: plan.relative,
+    source_plan_digest: plan.digest,
+    task_id: binding.task_id,
+    dispatch_binding: compactBinding(binding),
+    result_artifact: compactArtifact(input.result_artifact),
+    report_artifact: compactReportArtifact(report),
+    review_artifact: compactArtifact(input.review_artifact),
+    fix_artifact: input.fix_artifact ? compactArtifact(input.fix_artifact) : null,
+    report_status: report.status,
+    report_findings: report.findings,
+    review_status: review.review_status,
+    blocker_count: decision.blockers.length,
+    blockers: decision.blockers,
+    next_task_allowed: decision.next_task_allowed,
+    ledger_patch: {
+      active_task_id: decision.next_task_allowed ? null : binding.task_id,
+      completed_task_ids: decision.next_task_allowed ? unique([...asArray(progress.completed_task_ids), binding.task_id]) : asArray(progress.completed_task_ids),
+      status: decision.ledger_status,
+    },
+    allowed_followup: decision.allowed_followup,
+    handoff_chain: handoffChain,
+    forbidden_actions: ['runtime subagent invocation', 'platform API call', 'model invocation', 'source write', 'git add/commit/push', 'worktree creation', 'PR or merge'],
+    boundary_assertions: sddAdapterConsumptionBoundary(),
+    writes: true,
+    state_directory_created: true,
+    local_only: true,
+    deterministic: true,
+  };
+  const detail = { ...core, adapter_consumption_digest: digest(core) };
+  return {
+    schema_version: 1,
+    command: 'sdd',
+    mode: sddAdapterConsumptionKind,
+    ok: decision.next_task_allowed,
+    state_present: readonlyLocalStatePresent(root),
+    sdd_adapter_consumption: detail,
+    progress_ledger: nextProgress,
+    safety: { stage: 'P12', ...detail.boundary_assertions },
+    quality: decision.blockers,
+    action: decision.next_task_allowed
+      ? 'sdd adapter consumption validated one local adapter result, confirmed a DONE implementer report with clean review, and advanced the local progress ledger. It did not call a subagent, platform API, model, source writer, git, worktree, PR, push, or merge.'
+      : 'sdd adapter consumption preserved a non-clean report or review verdict and kept the local progress ledger on the active task. It did not repair facts, call a subagent, platform API, model, source writer, git, worktree, PR, push, or merge.',
+  };
+}
+
+export function writeSddAdapterConsumptionArtifacts(root, envelope) {
+  const base = path.join(root, '.vibecoding-state');
+  const sddDir = path.join(base, sddDirectoryName);
+  const consumptionDir = path.join(sddDir, sddAdapterConsumptionDirectoryName);
+  fs['mkdirSync'](consumptionDir, { recursive: true });
+  const item = envelope.sdd_adapter_consumption;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const consumptionFile = `${stamp}.${item.task_id}.adapter-consumption.json`;
+  fs['writeFileSync'](path.join(consumptionDir, consumptionFile), `${JSON.stringify(item, null, 2)}\n`, 'utf8');
+  fs['writeFileSync'](path.join(sddDir, 'progress.json'), `${JSON.stringify(envelope.progress_ledger, null, 2)}\n`, 'utf8');
+  return { progress_ledger: `${sddDirectoryName}/progress.json`, adapter_consumption: `${sddDirectoryName}/${sddAdapterConsumptionDirectoryName}/${consumptionFile}` };
+}
+
+export function printSddAdapterConsumption(envelope) {
+  const item = envelope.sdd_adapter_consumption;
+  console.log('Vibecoding Runtime SDD Adapter Consumption');
+  console.log(`Stage: ${item.stage}; task=${item.task_id}; review=${item.review_status}; next_task_allowed=${item.next_task_allowed}`);
+  console.log(`Progress: ${envelope.files.progress_ledger}`);
+  console.log(`Adapter consumption: ${envelope.files.adapter_consumption}`);
+  console.log(`Action: ${envelope.action}`);
+}
+
+function readPlanBinding(root, planFile) {
+  const absolute = localPath(root, planFile, 'sdd --consume-adapter-result --from-plan');
+  const text = fs.readFileSync(absolute, 'utf8');
+  return { relative: path.relative(root, absolute).replaceAll(path.sep, '/'), digest: crypto.createHash('sha256').update(text).digest('hex') };
+}
+
+function readProgress(root) {
+  const file = path.join(root, '.vibecoding-state', sddDirectoryName, 'progress.json');
+  if (!fs.existsSync(file)) throw new Error('sdd --consume-adapter-result requires an existing progress ledger from sdd --run-loop');
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function readAdapterResult(root, resultFile) {
+  const absolute = localPath(root, resultFile, 'sdd --consume-adapter-result --from-file');
+  const input = JSON.parse(fs.readFileSync(absolute, 'utf8'));
+  if (input.schema_version !== 1) throw new Error('sdd adapter result schema_version must be 1');
+  if (input.artifact_kind !== 'sdd-adapter-result-envelope') throw new Error('sdd adapter result artifact_kind must be sdd-adapter-result-envelope');
+  return input;
+}
+
+function validateAdapterResultBinding(root, plan, progress, input) {
+  const dispatch = input.dispatch_artifact || {};
+  const result = input.result_artifact || {};
+  const review = input.review_artifact || {};
+  const taskId = dispatch.task_id || result.task_id || review.task_id;
+  if (!taskId) throw new Error('sdd adapter result task id is required');
+  if (progress.source_plan_digest !== plan.digest) throw new Error('sdd adapter consumption digest drift: source plan changed since dispatch');
+  if (dispatch.source_plan_digest !== plan.digest) throw new Error('sdd adapter result dispatch source plan digest mismatch');
+  if (progress.active_task_id !== taskId) throw new Error(`sdd adapter result task conflict: expected active task ${progress.active_task_id || '(none)'}, got ${taskId}`);
+  for (const [label, artifact] of [['result_artifact', result], ['review_artifact', review]]) {
+    if (artifact.task_id !== taskId) throw new Error(`sdd adapter result ${label} task id mismatch`);
+  }
+  if (!review.verdict) throw new Error('sdd adapter result requires review_artifact.verdict');
+  assertRuntimeBoundary(input.boundary_assertions || {});
+  const dispatchFile = safeDispatchFile(dispatch.file || dispatch.dispatch_file || '');
+  const dispatchPath = path.join(root, '.vibecoding-state', sddAdapterDispatchDirectoryName, dispatchFile);
+  if (!fs.existsSync(dispatchPath)) throw new Error(`sdd adapter result dispatch file not found: ${dispatchFile}`);
+  const dispatchArtifact = JSON.parse(fs.readFileSync(dispatchPath, 'utf8'));
+  const actualDispatchDigest = digest(withoutKey(dispatchArtifact, 'dispatch_digest'));
+  if (dispatch.dispatch_digest !== actualDispatchDigest) throw new Error('sdd adapter result dispatch digest drift');
+  if (dispatchArtifact.task_id !== taskId) throw new Error('sdd adapter result dispatch task id mismatch');
+  if (dispatchArtifact.source_plan_digest !== plan.digest) throw new Error('sdd adapter result dispatch plan digest mismatch');
+  const taskRecord = asArray(progress.task_records).find((record) => record?.task_id === taskId) || {};
+  return {
+    task_id: taskId,
+    dispatch_file: dispatchFile,
+    dispatch_digest: dispatch.dispatch_digest,
+    dispatch_role: dispatchArtifact.role || dispatch.role || '',
+    source_plan_digest: plan.digest,
+    task_record: taskRecord,
+  };
+}
+
+function readImplementerReportBinding(root, plan, progress, input, binding) {
+  const reportRef = input.report_artifact || input.result_artifact?.report_artifact || {};
+  const reportFile = reportRef.file || reportRef.report_file;
+  const expectedDigest = reportRef.digest || reportRef.report_digest;
+  if (!reportFile || !expectedDigest) throw new Error('sdd adapter result requires implementer report artifact path and digest');
+  const normalizedReportFile = normalizeStateFile(reportFile, 'sdd implementer report artifact');
+  const text = readStateText(root, normalizedReportFile, 'sdd implementer report artifact');
+  const actualDigest = sddImplementerReportTextDigest(text);
+  if (actualDigest !== expectedDigest) throw new Error('sdd adapter result implementer report digest drift');
+  if (binding.task_record.report_artifact && normalizeStateFile(binding.task_record.report_artifact, 'sdd implementer report artifact') !== normalizedReportFile) throw new Error('sdd adapter result progress report artifact mismatch');
+  if (binding.task_record.report_digest && binding.task_record.report_digest !== actualDigest) throw new Error('sdd adapter result progress report digest mismatch');
+  const report = JSON.parse(text);
+  const validation = checkSddImplementerReportArtifact({
+    report,
+    textDigest: actualDigest,
+    plan: { source_plan_digest: plan.digest },
+    task: { task_id: binding.task_id },
+    taskBriefDigest: binding.task_record.task_brief_digest,
+  });
+  const fatalFinding = fatalReportFinding(validation.findings);
+  if (fatalFinding) throw new Error(fatalFinding);
+  if (reportRef.task_id && reportRef.task_id !== binding.task_id) throw new Error('sdd adapter result implementer report task id mismatch');
+  if (reportRef.status && String(reportRef.status).toUpperCase() !== validation.status) throw new Error('sdd adapter result implementer report status mismatch');
+  return {
+    file: normalizedReportFile,
+    digest: actualDigest,
+    status: validation.status,
+    summary: sddImplementerReportSummary(validation),
+    findings: validation.findings,
+    clean_review_eligible: validation.clean_review_eligible,
+  };
+}
+
+function fatalReportFinding(findings) {
+  return asArray(findings).find((finding) => [
+    'artifact_kind must be',
+    'task id mismatch',
+    'plan digest drift',
+    'brief digest mismatch',
+    'status must be',
+    'commits must be an array',
+    'concerns must be an array',
+    'questions must be an array',
+    'tests must be an object',
+    'self_review must be an object',
+  ].some((marker) => String(finding).includes(marker))) || '';
+}
+
+function reviewSummary(review) {
+  if (!review || typeof review !== 'object' || !review.verdict) throw new Error('sdd adapter result requires review_artifact.verdict');
+  const blockers = asArray(review.findings).filter((finding) => isBlockingFinding(finding)).map((finding) => `${finding.severity}: ${finding.title || finding.id || 'unresolved review finding'}`);
+  const verdict = String(review.verdict || '').toLowerCase();
+  return { review_status: verdict === 'clean' && blockers.length === 0 ? 'clean' : 'blocked', blockers };
+}
+
+function adapterConsumptionDecision(report, review) {
+  const blockers = [
+    ...report.findings,
+    ...review.blockers,
+  ];
+  if (report.status === 'QUESTIONS') {
+    return { next_task_allowed: false, ledger_status: 'questions-open', blockers: [...blockers, 'sdd implementer report status QUESTIONS requires answer before next task'], allowed_followup: ['answer-questions-and-submit-report'] };
+  }
+  if (report.status === 'BLOCKED') {
+    return { next_task_allowed: false, ledger_status: 'blocked-report', blockers: [...blockers, 'sdd implementer report status BLOCKED keeps active task'], allowed_followup: ['resolve-blocker-and-submit-report'] };
+  }
+  const clean = report.clean_review_eligible && review.review_status === 'clean' && blockers.length === 0;
+  return {
+    next_task_allowed: clean,
+    ledger_status: clean ? 'completed-clean-review' : 'blocked-review',
+    blockers,
+    allowed_followup: clean ? ['sdd-run-loop-next-task'] : ['fix-blockers-and-submit-adapter-result'],
+  };
+}
+
+function isBlockingFinding(finding) {
+  const severity = String(finding?.severity || '').toLowerCase();
+  const status = String(finding?.status || '').toLowerCase();
+  return ['critical', 'important'].includes(severity) && !['resolved', 'fixed', 'accepted'].includes(status);
+}
+
+function progressAfterAdapterResult(progress, binding, review, report, input) {
+  const clean = report.clean_review_eligible && review.review_status === 'clean' && report.findings.length === 0 && review.blockers.length === 0;
+  const recordStatus = report.status === 'QUESTIONS' ? 'questions-open' : report.status === 'BLOCKED' ? 'blocked-report' : clean ? 'completed-clean-review' : 'blocked-review';
+  const records = asArray(progress.task_records).map((record) => record?.task_id === binding.task_id ? { ...record, status: recordStatus, review_status: review.review_status, report_status: report.status, report_artifact: report.file, report_digest: report.digest, adapter_consumption_required: false } : record);
+  const next = {
+    ...progress,
+    updated_at: new Date().toISOString(),
+    active_task_id: clean ? null : binding.task_id,
+    completed_task_ids: clean ? unique([...asArray(progress.completed_task_ids), binding.task_id]) : asArray(progress.completed_task_ids),
+    task_records: records,
+    adapter_consumption_records: [
+      ...asArray(progress.adapter_consumption_records),
+      {
+        task_id: binding.task_id,
+        dispatch_file: binding.dispatch_file,
+        dispatch_digest: binding.dispatch_digest,
+        review_status: review.review_status,
+        report_status: report.status,
+        report_artifact: report.file,
+        report_digest: report.digest,
+        blocker_count: report.findings.length + review.blockers.length,
+        result_status: input.result_artifact?.status || '',
+        next_task_allowed: clean,
+      },
+    ],
+  };
+  const { progress_digest: _oldDigest, ...payload } = next;
+  return { ...payload, progress_digest: digest(payload) };
+}
+
+function compactBinding(binding) {
+  return {
+    task_id: binding.task_id,
+    dispatch_file: binding.dispatch_file,
+    dispatch_digest: binding.dispatch_digest,
+    dispatch_role: binding.dispatch_role,
+    source_plan_digest: binding.source_plan_digest,
+  };
+}
+
+function compactReportArtifact(report) {
+  return {
+    artifact_kind: 'sdd-implementer-report',
+    file: report.file,
+    digest: report.digest,
+    status: report.status,
+    summary: report.summary,
+  };
+}
+
+function compactArtifact(artifact) {
+  return {
+    artifact_kind: artifact?.artifact_kind || '',
+    task_id: artifact?.task_id || '',
+    status: artifact?.status || '',
+    verdict: artifact?.verdict || '',
+    digest: artifact?.digest || '',
+  };
+}
+
+function assertRuntimeBoundary(boundary) {
+  for (const key of ['runtime_subagent', 'runtime_platform_api', 'runtime_model_invocation', 'runtime_source_write', 'runtime_git_write', 'runtime_worktree_write']) {
+    if (boundary[key] !== false) throw new Error(`sdd adapter result boundary_assertions.${key} must be false`);
+  }
+}
+
+function sddAdapterConsumptionBoundary() {
+  return {
+    adapter_result_artifact: true,
+    progress_ledger: true,
+    state_directory_created: true,
+    command_execution: false,
+    test_execution: false,
+    source_write: false,
+    business_source_write: false,
+    git_write: false,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    worktree: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+  };
+}
+
+function localPath(root, file, label) {
+  if (!file) throw new Error(`${label} requires a local file`);
+  const absolute = path.resolve(root, file);
+  const relative = path.relative(root, absolute);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${label} must stay within --root`);
+  if (!fs.existsSync(absolute)) throw new Error(`${label} file not found: ${relative.replaceAll(path.sep, '/')}`);
+  return absolute;
+}
+
+function readStateText(root, stateFile, label) {
+  const relative = normalizeStateFile(stateFile, label);
+  const file = path.join(root, '.vibecoding-state', relative);
+  const stateRoot = path.join(root, '.vibecoding-state');
+  const resolved = path.resolve(file);
+  const resolvedRoot = path.resolve(stateRoot);
+  if (!resolved.startsWith(`${resolvedRoot}${path.sep}`)) throw new Error(`${label} path must stay inside .vibecoding-state`);
+  if (!fs.existsSync(resolved)) throw new Error(`${label} missing`);
+  return fs.readFileSync(resolved, 'utf8');
+}
+
+function normalizeStateFile(stateFile, label) {
+  const relative = String(stateFile || '').replaceAll('\\', '/');
+  if (!relative || relative.startsWith('/') || relative.includes('..')) throw new Error(`${label} path must stay inside .vibecoding-state`);
+  return relative;
+}
+
+function safeDispatchFile(file) {
+  if (!file || file !== path.basename(file) || !file.endsWith('.subagent-adapter-dispatch.json')) throw new Error('sdd adapter result dispatch file must be a local subagent adapter dispatch artifact basename');
+  return file;
+}
+
+function withoutKey(object, key) {
+  const copy = { ...object };
+  delete copy[key];
+  return copy;
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function unique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+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);
+}

package/tools/vibe-runtime/runtime-sdd-evidence-chain-model.mjs

@@ -0,0 +1,200 @@
+import crypto from 'node:crypto';
+import { sddHandoffChainForTask } from './runtime-sdd-handoff-chain-model.mjs';
+import { runtimeTestEvidenceEnvelope } from './runtime-test-evidence-model.mjs';
+
+export const sddEvidenceChainKind = 'superpowers-parity-sdd-evidence-chain';
+const sddEvidenceChainContractSync = 'runtime-cli-usage';
+
+export const sddEvidenceTestProfile = Object.freeze({
+  id: 'runtime-test-evidence-syntax',
+  command: 'node --check tools/vibe-runtime/runtime-test-evidence-model.mjs',
+  argv: ['node', '--check', 'tools/vibe-runtime/runtime-test-evidence-model.mjs'],
+  timeout_ms: 20_000,
+  task_refs: ['superpowers-parity-sdd-evidence-chain'],
+  scenario_refs: ['parity-evidence-chain:runtime-test-evidence-syntax'],
+});
+
+export const sddEvidenceDiffCommandSpecs = Object.freeze([
+  ['git-diff-name-status', ['git', 'diff', '--name-status']],
+  ['git-diff-stat', ['git', 'diff', '--stat']],
+  ['git-diff-numstat', ['git', 'diff', '--numstat']],
+  ['git-diff-cached-name-status', ['git', 'diff', '--cached', '--name-status']],
+  ['git-diff-cached-stat', ['git', 'diff', '--cached', '--stat']],
+  ['git-diff-cached-numstat', ['git', 'diff', '--cached', '--numstat']],
+]);
+
+export function sddEvidenceChainEnvelope({ stage, plan, task, testResult, diffResults, collectedAt }) {
+  const testEvidence = runtimeTestEvidenceEnvelope({ profile: sddEvidenceTestProfile, result: testResult, createdAt: collectedAt });
+  const diffEvidence = sddDiffEvidence({ stage, diffResults, collectedAt });
+  const status = testEvidence.ok ? 'evidence-collected-review-required' : 'evidence-collected-test-failed-review-blocked';
+  const chain = {
+    version: 1,
+    stage,
+    evidence_chain_kind: sddEvidenceChainKind,
+    contract_sync: sddEvidenceChainContractSync,
+    automation_profile: 'superpowers-parity',
+    collected_at: collectedAt,
+    source_plan: plan.source_plan,
+    source_plan_digest: plan.source_plan_digest,
+    task: {
+      task_id: task.task_id,
+      title: task.title,
+    },
+    test_evidence: testEvidence,
+    diff_evidence: diffEvidence,
+    review_package: {
+      package_kind: 'sdd-review-package',
+      task_id: task.task_id,
+      review_ready: testEvidence.ok,
+      blocks_next_task_until_clean_review: true,
+      required_refs: ['test_evidence.test_evidence_digest', 'diff_evidence.diff_evidence_digest', 'progress_ledger.progress_digest'],
+      failure_evidence_preserved: !testEvidence.ok,
+      reviewer_must_not_convert_failure_to_pass: true,
+    },
+    repair_contract: {
+      allowed_repairs: ['structure reference repair sidecar', 'digest rebinding sidecar', 'missing local reference note'],
+      forbidden_repairs: ['test result status mutation', 'diff fact mutation', 'stdout or stderr mutation', 'source mutation', 'git mutation'],
+      original_evidence_is_immutable: true,
+    },
+    progress_patch: {
+      task_id: task.task_id,
+      status,
+      evidence_refs: {
+        test_evidence_digest: testEvidence.test_evidence_digest,
+        diff_evidence_digest: diffEvidence.diff_evidence_digest,
+      },
+      review_required_before_next_task: true,
+    },
+    allowed_followup: ['manual review verdict intake', 'completion evidence bundle binding', 'fact-preserving repair sidecar if structure references are incomplete'],
+    forbidden_actions: ['source write', 'business source write', 'git add/commit/push', 'worktree creation', 'PR or merge', 'platform API call', 'model invocation', 'runtime subagent invocation', 'evidence fact mutation'],
+    boundary_assertions: sddEvidenceBoundaryAssertions(),
+    writes: true,
+    state_directory_created: true,
+    local_only: true,
+    deterministic: false,
+  };
+  const chainWithDigest = { ...chain, evidence_chain_digest: digest(chain) };
+  const chainWithHandoff = { ...chainWithDigest, handoff_chain: sddHandoffChainForTask({
+    stage,
+    plan,
+    task,
+    evidenceChain: { evidence_chain_digest: chainWithDigest.evidence_chain_digest },
+    writes: true,
+  }) };
+  return {
+    schema_version: 1,
+    command: 'sdd',
+    mode: sddEvidenceChainKind,
+    ok: testEvidence.ok,
+    sdd_evidence_chain: chainWithHandoff,
+    safety: { stage, ...chainWithDigest.boundary_assertions },
+    quality: [...testEvidence.blocked_reasons, ...diffEvidence.blocked_reasons],
+    action: testEvidence.ok
+      ? 'sdd evidence-chain ran one fixed allowlisted test profile, read fixed git diff summaries, and prepared one local review package sidecar. It did not mutate source, git history, worktrees, platform state, model state, or subagent sessions.'
+      : 'sdd evidence-chain preserved failing test evidence, read fixed git diff summaries, and prepared a blocked review package sidecar. It did not repair or rewrite the failing facts.',
+  };
+}
+
+export function sddEvidenceBoundaryAssertions() {
+  return {
+    evidence_chain_artifact: true,
+    progress_ledger: true,
+    state_directory_created: true,
+    command_execution: true,
+    test_execution: true,
+    allowlisted_profile: true,
+    arbitrary_shell: false,
+    git_read: true,
+    git_write: false,
+    source_write: false,
+    business_source_write: false,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    worktree: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+  };
+}
+
+function sddDiffEvidence({ stage, diffResults, collectedAt }) {
+  const changedFiles = unique(diffResults.filter((result) => commandKey(result.argv).endsWith('--name-status')).flatMap((result) => parseNameStatus(result.stdout)));
+  const commandSummaries = diffResults.map((result) => ({
+    id: result.id,
+    command: commandKey(result.argv),
+    argv_digest: digestText(JSON.stringify(result.argv || [])),
+    exit_code: Number.isInteger(result.exit_code) ? result.exit_code : 1,
+    stdout_digest: digestText(result.stdout || ''),
+    stderr_digest: digestText(result.stderr || ''),
+    stdout_line_count: lineCount(result.stdout || ''),
+    stderr_line_count: lineCount(result.stderr || ''),
+  }));
+  const blockedReasons = commandSummaries.filter((item) => item.exit_code !== 0).map((item) => `git diff read command failed: ${item.command}`);
+  const evidence = {
+    version: 1,
+    artifact_kind: 'sdd-diff-evidence',
+    stage,
+    evidence_kind: 'fixed-git-diff-summary',
+    collected_at: collectedAt,
+    runtime_read_git_diff: true,
+    git_read: true,
+    git_write: false,
+    worktree_write: false,
+    command_execution: false,
+    test_execution: false,
+    changed_files: changedFiles,
+    changed_file_count: changedFiles.length,
+    commands: commandSummaries,
+    blocked_reasons: blockedReasons,
+    boundary_assertions: {
+      git_read: true,
+      git_write: false,
+      worktree_write: false,
+      source_write: false,
+      commit: false,
+      push: false,
+      pr: false,
+      merge: false,
+    },
+  };
+  return { ...evidence, diff_evidence_digest: digest(evidence) };
+}
+
+function parseNameStatus(text) {
+  return String(text || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean).flatMap((line) => {
+    const parts = line.split(/\t+/).map((part) => part.trim()).filter(Boolean);
+    if (parts.length < 2) return [];
+    return [parts[parts.length - 1].replaceAll('\\', '/')];
+  });
+}
+
+function commandKey(argv) {
+  return Array.isArray(argv) ? argv.join(' ') : '';
+}
+
+function unique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function digestText(value) {
+  return `sha256:${crypto.createHash('sha256').update(String(value || '')).digest('hex')}`;
+}
+
+function lineCount(value) {
+  const text = String(value || '');
+  return text.trim() ? text.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n').length : 0;
+}
+
+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);
+}