@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-sdd-plan-preflight-model.mjs

@@ -0,0 +1,121 @@
+export const sddPlanPreflightKind = 'superpowers-parity-sdd-plan-preflight';
+
+const pathPattern = /(?:[A-Za-z0-9_.-]+[\\/])+[A-Za-z0-9_.-]+(?:\.[A-Za-z0-9]{1,12})?/g;
+const quotedPathPattern = /`([^`]+\.[A-Za-z0-9]{1,12})`/g;
+
+export function sddPlanPreflightScan({ sourceText, tasks }) {
+  const text = String(sourceText || '');
+  const taskList = Array.isArray(tasks) ? tasks : [];
+  const findings = [
+    ...overlapFindings(taskList),
+    ...reviewGateFindings(text),
+    ...evidenceQuestions(text),
+    ...dependencyQuestions(taskList),
+  ];
+  const blockers = findings.filter((finding) => finding.severity === 'blocker');
+  const questions = findings.filter((finding) => finding.severity === 'question');
+  return {
+    version: 1,
+    scan_kind: sddPlanPreflightKind,
+    deterministic: true,
+    blocker_count: blockers.length,
+    question_count: questions.length,
+    blockers,
+    batched_questions: questions,
+    findings,
+  };
+}
+
+export function sddPlanPreflightMessages(scan) {
+  return asArray(scan?.findings).map((finding) => finding.message).filter(Boolean);
+}
+
+export function sddPlanPreflightBlockerMessages(scan) {
+  return asArray(scan?.blockers).map((finding) => finding.message).filter(Boolean);
+}
+
+function overlapFindings(tasks) {
+  const byPath = new Map();
+  for (const task of tasks) {
+    for (const filePath of extractTaskPaths(task.title)) {
+      const owners = byPath.get(filePath) || [];
+      if (!owners.find((owner) => owner.task_id === task.task_id)) owners.push({ task_id: task.task_id, title: task.title });
+      byPath.set(filePath, owners);
+    }
+  }
+  return [...byPath.entries()]
+    .filter(([, owners]) => owners.length > 1)
+    .map(([filePath, owners]) => ({
+      id: `file-overlap:${filePath}`,
+      severity: 'blocker',
+      category: 'task-file-overlap',
+      file: filePath,
+      task_ids: owners.map((owner) => owner.task_id),
+      message: `sdd preflight blocker: file scope overlap on ${filePath} across ${owners.map((owner) => owner.task_id).join(', ')}`,
+    }));
+}
+
+function reviewGateFindings(text) {
+  if (!/(skip|bypass|without|no)\s+(review|reviewer|gate)|跳过\s*review|跳过审查|无需审查|不需要审查/i.test(text)) return [];
+  return [{
+    id: 'review-gate-conflict',
+    severity: 'blocker',
+    category: 'review-gate-conflict',
+    message: 'sdd preflight blocker: plan conflicts with the required clean review gate before the next task',
+  }];
+}
+
+function evidenceQuestions(text) {
+  const findings = [];
+  if (!/(test|tests|testing|check|checks|acceptance|验收|测试|验证)/i.test(text)) findings.push({
+    id: 'missing-test-or-acceptance-marker',
+    severity: 'question',
+    category: 'missing-evidence-marker',
+    message: 'sdd preflight question: plan has no explicit test or acceptance marker',
+  });
+  if (!/(boundary|boundaries|read-only|confirm|review gate|安全边界|边界|确认)/i.test(text)) findings.push({
+    id: 'missing-boundary-marker',
+    severity: 'question',
+    category: 'missing-boundary-marker',
+    message: 'sdd preflight question: plan has no explicit boundary marker',
+  });
+  return findings;
+}
+
+function dependencyQuestions(tasks) {
+  return tasks
+    .filter((task) => /(depends on|after|before|blocked by|requires|依赖|之后|之前|等待)/i.test(task.title || ''))
+    .filter((task) => !/(task-\d{2}|#\d+|第\s*\d+)/i.test(task.title || ''))
+    .map((task) => ({
+      id: `dependency-order:${task.task_id}`,
+      severity: 'question',
+      category: 'dependency-order-unclear',
+      task_id: task.task_id,
+      message: `sdd preflight question: ${task.task_id} mentions dependency order without a concrete task reference`,
+    }));
+}
+
+function extractTaskPaths(title) {
+  const raw = String(title || '');
+  const values = [
+    ...matches(raw, quotedPathPattern).map((match) => match[1]),
+    ...matches(raw, pathPattern).map((match) => match[0]),
+  ];
+  return [...new Set(values.map(normalizePathToken).filter(Boolean))];
+}
+
+function normalizePathToken(value) {
+  const token = String(value || '').trim().replace(/[),.;:]+$/g, '').replaceAll('\\', '/');
+  if (!token.includes('/')) return '';
+  if (token.startsWith('http://') || token.startsWith('https://')) return '';
+  return token;
+}
+
+function matches(text, pattern) {
+  pattern.lastIndex = 0;
+  return [...String(text || '').matchAll(pattern)];
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}

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

@@ -0,0 +1,197 @@
+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 {
+  validateSddTaskBriefArtifact,
+} from './runtime-sdd-task-brief-model.mjs';
+import {
+  createSddReviewPackageArtifact,
+  sddReviewPackageDirectoryName,
+  sddReviewPackageKind,
+} from './runtime-sdd-review-package-model.mjs';
+
+export function sddReviewPackageEnvelope({ root, stage, sddDirectoryName, plan, task, progress, baseRef, headRef, spawnSync, persist = false }) {
+  const taskRecord = activeTaskRecordForReviewPackage(progress, plan, task.task_id);
+  const taskBrief = reviewPackageTaskBriefBinding(root, plan, task, taskRecord);
+  const report = reviewPackageReportBinding(root, plan, task, taskRecord, taskBrief);
+  const gitRead = captureReviewPackageGitRange(root, spawnSync, baseRef, headRef);
+  const createdAt = new Date().toISOString();
+  const baseName = `${safeStamp(createdAt)}.${task.task_id}.sdd-review-package`;
+  const { packageText, artifact } = createSddReviewPackageArtifact({
+    stage,
+    plan,
+    task,
+    createdAt,
+    base: gitRead.base,
+    head: gitRead.head,
+    commits: gitRead.commits,
+    diffStat: gitRead.diff_stat,
+    nameStatus: gitRead.name_status,
+    numStat: gitRead.numstat,
+    netDiff: gitRead.net_diff,
+    taskBrief,
+    report,
+    packageFile: stateRelative(sddDirectoryName, sddReviewPackageDirectoryName, `${baseName}.diff.md`),
+    sidecarFile: stateRelative(sddDirectoryName, sddReviewPackageDirectoryName, `${baseName}.json`),
+    writes: persist,
+  });
+  return {
+    schema_version: 1,
+    command: 'sdd',
+    mode: sddReviewPackageKind,
+    ok: true,
+    state_present: readonlyLocalStatePresent(root),
+    sdd_review_package: artifact,
+    files: { review_package: artifact.package_file, review_package_artifact: artifact.sidecar_file },
+    safety: { stage, ...artifact.boundary_assertions },
+    quality: [],
+    action: persist
+      ? 'sdd review-package wrote only local diff markdown and JSON sidecars for one active task. It used fixed git read commands only and did not modify source, run tests, invoke models, call platforms or subagents, create worktrees, commit, push, PR, merge, reset, or checkout.'
+      : 'sdd review-package previewed one active task review package with fixed git read commands only. No state write, source write, test execution, platform API, model invocation, subagent call, worktree, commit, push, PR, merge, reset, or checkout occurred.',
+    _package_text: packageText,
+  };
+}
+
+export function writeSddReviewPackageArtifacts(root, sddDirectoryName, envelope) {
+  const artifact = envelope.sdd_review_package;
+  const directory = path.join(root, '.vibecoding-state', sddDirectoryName, sddReviewPackageDirectoryName);
+  fs['mkdirSync'](directory, { recursive: true });
+  fs['writeFileSync'](path.join(root, '.vibecoding-state', artifact.package_file), envelope._package_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;
+}
+
+export function publicSddReviewPackageEnvelope(envelope) {
+  const { _package_text: _packageText, ...output } = envelope;
+  return output;
+}
+
+export function printSddReviewPackage(envelope) {
+  const review = envelope.sdd_review_package;
+  console.log('Vibecoding Runtime SDD Review Package');
+  console.log(`Stage: ${review.stage}; task=${review.task_id}; commits=${review.commit_count}; writes=${review.writes}`);
+  console.log(`Range: ${review.git_range.notation}`);
+  console.log(`Package: ${review.package_file}`);
+  console.log(`Package digest: ${review.review_package_digest}`);
+  console.log(`Action: ${envelope.action}`);
+}
+
+function activeTaskRecordForReviewPackage(progress, plan, taskId) {
+  if (!progress || Object.keys(progress).length === 0) throw new Error('sdd --review-package requires an existing progress ledger from sdd --run-loop');
+  if (progress.source_plan_digest && progress.source_plan_digest !== plan.source_plan_digest) throw new Error('sdd review package ledger digest drift: source plan changed since the active task dispatch');
+  if (progress.active_task_id !== taskId) throw new Error(`sdd review package task is not active: ${taskId}`);
+  if (asArray(progress.completed_task_ids).includes(taskId)) throw new Error(`sdd review package task is already completed: ${taskId}`);
+  const taskRecord = asArray(progress.task_records).find((record) => record?.task_id === taskId);
+  if (!taskRecord) throw new Error(`sdd review package missing active task record: ${taskId}`);
+  return taskRecord;
+}
+
+function reviewPackageTaskBriefBinding(root, plan, task, taskRecord) {
+  const artifactFile = taskRecord.task_brief_artifact;
+  if (!artifactFile) throw new Error('sdd review package requires task brief artifact binding');
+  const artifact = JSON.parse(readStateText(root, artifactFile, 'sdd task brief artifact'));
+  const briefText = readStateText(root, artifact.brief_file, 'sdd task brief markdown');
+  const validation = validateSddTaskBriefArtifact({ artifact, briefText, plan, task });
+  if (!validation.ok) throw new Error(validation.findings.join('; '));
+  if (taskRecord.task_brief_digest !== artifact.brief_digest) throw new Error('sdd review package task brief digest mismatch');
+  return {
+    file: artifact.brief_file,
+    digest: artifact.brief_digest,
+    artifact_file: artifact.sidecar_file,
+    artifact_digest: artifact.task_brief_digest,
+  };
+}
+
+function reviewPackageReportBinding(root, plan, task, taskRecord, taskBrief) {
+  const reportFile = taskRecord.report_artifact || taskRecord.implementer_report_file;
+  const expectedDigest = taskRecord.report_digest || taskRecord.implementer_report_digest;
+  if (!reportFile || !expectedDigest) throw new Error('sdd review package requires report artifact path and digest binding');
+  const text = readStateText(root, reportFile, 'sdd implementer report artifact');
+  const actualDigest = sddImplementerReportTextDigest(text);
+  if (actualDigest !== expectedDigest) throw new Error('sdd review package report digest mismatch');
+  const parsed = JSON.parse(text);
+  const validation = checkSddImplementerReportArtifact({ report: parsed, textDigest: actualDigest, plan, task, taskBriefDigest: taskBrief.digest, requireDone: true });
+  if (!validation.ok) throw new Error(validation.findings.join('; '));
+  return {
+    file: reportFile,
+    digest: actualDigest,
+    summary: sddImplementerReportSummary(validation),
+  };
+}
+
+function captureReviewPackageGitRange(root, spawnSync, baseRef, headRef) {
+  assertShaLikeRef(baseRef, 'base');
+  assertShaLikeRef(headRef, 'head');
+  const base = gitCommitSha(root, spawnSync, baseRef, 'base');
+  const head = gitCommitSha(root, spawnSync, headRef, 'head');
+  if (base === head) throw new Error('sdd review package requires distinct base and head commits');
+  const range = `${base}..${head}`;
+  const commitsText = gitReadText(root, spawnSync, ['git', 'log', '--format=%H%x09%s', range], 'commit list');
+  const diffStat = gitReadText(root, spawnSync, ['git', 'diff', '--stat', range], 'diff stat');
+  const nameStatus = gitReadText(root, spawnSync, ['git', 'diff', '--name-status', range], 'name status');
+  const numstat = gitReadText(root, spawnSync, ['git', 'diff', '--numstat', range], 'numstat');
+  const netDiff = gitReadText(root, spawnSync, ['git', 'diff', range], 'net diff');
+  return { base, head, commits: parseCommitList(commitsText), diff_stat: diffStat, name_status: nameStatus, numstat, net_diff: netDiff };
+}
+
+function assertShaLikeRef(value, label) {
+  if (!/^[0-9a-f]{7,40}$/i.test(String(value || ''))) throw new Error(`sdd --review-package requires ${label} sha; HEAD shortcuts are not accepted`);
+}
+
+function gitCommitSha(root, spawnSync, ref, label) {
+  return gitReadText(root, spawnSync, ['git', 'rev-parse', '--verify', `${ref}^{commit}`], `${label} commit`).trim();
+}
+
+function gitReadText(root, spawnSync, argv, label) {
+  const result = spawnSync(argv[0], argv.slice(1), {
+    cwd: root,
+    encoding: 'utf8',
+    windowsHide: true,
+    shell: false,
+    timeout: 15_000,
+    maxBuffer: 1024 * 1024 * 8,
+  });
+  if (result.status !== 0) throw new Error(`sdd review package git read failed for ${label}: ${result.stderr || result.error?.message || 'unknown error'}`);
+  return result.stdout || '';
+}
+
+function parseCommitList(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, ...subjectParts] = line.split('\t');
+      return { sha, subject: subjectParts.join('\t') };
+    });
+}
+
+function readStateText(root, stateFile, label) {
+  const relative = String(stateFile || '').replaceAll('\\', '/');
+  if (!relative || relative.startsWith('/') || relative.includes('..')) throw new Error(`${label} path must stay inside .vibecoding-state`);
+  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 stateRelative(...parts) {
+  return path.join(...parts).replaceAll(path.sep, '/');
+}
+
+function safeStamp(value) {
+  return value.replace(/[:.]/g, '-');
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}

package/tools/vibe-runtime/runtime-sdd-review-package-model.mjs

@@ -0,0 +1,183 @@
+import crypto from 'node:crypto';
+import { sddHandoffChainForTask } from './runtime-sdd-handoff-chain-model.mjs';
+
+export const sddReviewPackageKind = 'superpowers-parity-sdd-review-package';
+export const sddReviewPackageDirectoryName = 'review-packages';
+
+export function createSddReviewPackageArtifact({
+  stage,
+  plan,
+  task,
+  createdAt,
+  base,
+  head,
+  commits,
+  diffStat,
+  nameStatus,
+  numStat,
+  netDiff,
+  taskBrief,
+  report,
+  packageFile,
+  sidecarFile,
+  writes = false,
+}) {
+  const packageText = sddReviewPackageContent({ stage, plan, task, base, head, commits, diffStat, nameStatus, numStat, netDiff, taskBrief, report });
+  const handoffChain = sddHandoffChainForTask({
+    stage,
+    plan,
+    task,
+    taskBrief,
+    implementerReport: report,
+    reviewPackage: { package_file: packageFile, sidecar_file: sidecarFile, digest: digestText(packageText) },
+    writes,
+  });
+  const core = {
+    version: 1,
+    stage,
+    artifact_kind: sddReviewPackageKind,
+    automation_profile: 'superpowers-parity',
+    created_at: createdAt,
+    source_plan: plan.source_plan,
+    source_plan_digest: plan.source_plan_digest,
+    task_id: task.task_id,
+    title: task.title,
+    git_range: { base, head, notation: `${base}..${head}` },
+    commit_count: commits.length,
+    commits,
+    diff_stat: diffStat,
+    changed_files: changedFilesFromNameStatus(nameStatus),
+    numstat: parseNumStat(numStat),
+    net_diff_digest: digestText(netDiff),
+    net_diff_line_count: lineCount(netDiff),
+    package_file: packageFile,
+    sidecar_file: sidecarFile,
+    task_brief_file: taskBrief.file,
+    task_brief_digest: taskBrief.digest,
+    task_brief_artifact: taskBrief.artifact_file,
+    task_brief_artifact_digest: taskBrief.artifact_digest,
+    report_artifact: report.file,
+    report_digest: report.digest,
+    report_summary: report.summary || {},
+    review_required_before_next_task: true,
+    handoff_chain: handoffChain,
+    allowed_followup: ['manual-review-uses-package-before-adapter-consumption'],
+    forbidden_actions: ['git add/commit/push/merge/reset/checkout', 'source write', 'test execution', 'runtime subagent invocation', 'platform API call', 'model invocation', 'worktree creation', 'PR or merge'],
+    boundary_assertions: sddReviewPackageBoundaryAssertions(writes),
+    writes: Boolean(writes),
+    state_directory_created: Boolean(writes),
+    local_only: true,
+    deterministic: true,
+  };
+  return { packageText, artifact: { ...core, review_package_digest: digestObject(core) } };
+}
+
+export function sddReviewPackageBoundaryAssertions(writes = false) {
+  return {
+    sdd_review_package_artifact: Boolean(writes),
+    sdd_progress_ledger: false,
+    state_directory_created: Boolean(writes),
+    git_read: true,
+    git_write: false,
+    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,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    worktree: false,
+  };
+}
+
+export function digestText(text) {
+  return crypto.createHash('sha256').update(String(text || '')).digest('hex');
+}
+
+export function digestObject(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function sddReviewPackageContent({ stage, plan, task, base, head, commits, diffStat, nameStatus, numStat, netDiff, taskBrief, report }) {
+  return [
+    '# SDD Review Package',
+    '',
+    `stage: ${stage}`,
+    `task_id: ${task.task_id}`,
+    `source_plan: ${plan.source_plan}`,
+    `source_plan_digest: ${plan.source_plan_digest}`,
+    `base: ${base}`,
+    `head: ${head}`,
+    `task_brief_file: ${taskBrief.file}`,
+    `task_brief_digest: ${taskBrief.digest}`,
+    `report_artifact: ${report.file}`,
+    `report_digest: ${report.digest}`,
+    '',
+    '## Task',
+    task.title,
+    '',
+    '## Commits',
+    commits.length > 0 ? commits.map((commit) => `- ${commit.sha} ${commit.subject}`).join('\n') : '- none',
+    '',
+    '## Diff stat',
+    fence(diffStat || '(empty)'),
+    '',
+    '## Name status',
+    fence(nameStatus || '(empty)'),
+    '',
+    '## Numstat',
+    fence(numStat || '(empty)'),
+    '',
+    '## Net diff',
+    fence(netDiff || '(empty)'),
+    '',
+  ].join('\n');
+}
+
+function changedFilesFromNameStatus(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const parts = line.split(/\s+/);
+      return { status: parts[0] || '', path: parts.at(-1) || '' };
+    });
+}
+
+function parseNumStat(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [added, deleted, file] = line.split(/\s+/);
+      return { added, deleted, file };
+    });
+}
+
+function lineCount(text) {
+  const value = String(text || '');
+  if (!value) return 0;
+  return value.split(/\r?\n/).length;
+}
+
+function fence(text) {
+  return ['```', String(text || ''), '```'].join('\n');
+}
+
+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-task-brief-model.mjs

@@ -0,0 +1,144 @@
+import crypto from 'node:crypto';
+import { sddHandoffChainForTask } from './runtime-sdd-handoff-chain-model.mjs';
+
+export const sddTaskBriefKind = 'superpowers-parity-sdd-task-brief';
+export const sddTaskBriefDirectoryName = 'task-briefs';
+const sddTaskBriefContractSync = 'runtime-cli-usage tools/vibe-release-check';
+
+export function createSddTaskBriefArtifact({ stage, plan, task, createdAt, briefFile, sidecarFile, writes = false }) {
+  const briefText = sddTaskBriefContent({ stage, plan, task });
+  const handoffChain = sddHandoffChainForTask({
+    stage,
+    plan,
+    task,
+    taskBrief: { task_id: task.task_id, brief_file: briefFile, brief_digest: digestText(briefText), sidecar_file: sidecarFile },
+    writes,
+  });
+  const core = {
+    version: 1,
+    stage,
+    artifact_kind: sddTaskBriefKind,
+    automation_profile: 'superpowers-parity',
+    created_at: createdAt,
+    source_plan: plan.source_plan,
+    source_plan_digest: plan.source_plan_digest,
+    task_id: task.task_id,
+    title: task.title,
+    task_snapshot: {
+      task_id: task.task_id,
+      title: task.title,
+      role_sequence: task.role_sequence || [],
+      review_required: task.review_required === true,
+      evidence_required: task.evidence_required || [],
+    },
+    brief_file: briefFile,
+    sidecar_file: sidecarFile,
+    brief_digest: digestText(briefText),
+    implementer_source_of_truth: true,
+    review_required_before_next_task: true,
+    handoff_chain: handoffChain,
+    allowed_followup: ['adapter-dispatch-must-reference-brief-digest'],
+    forbidden_actions: ['runtime subagent invocation', 'platform API call', 'model invocation', 'source write', 'test execution', 'git add/commit/push', 'worktree creation', 'PR or merge'],
+    boundary_assertions: sddTaskBriefBoundaryAssertions(writes),
+    writes: Boolean(writes),
+    state_directory_created: Boolean(writes),
+    local_only: true,
+    deterministic: true,
+  };
+  return { briefText, artifact: { ...core, task_brief_digest: digestObject(core) } };
+}
+
+export function validateSddTaskBriefArtifact({ artifact, briefText, plan, task }) {
+  const findings = [];
+  if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) findings.push('sdd task brief sidecar must be an object');
+  if (findings.length > 0) return { ok: false, findings };
+  if (artifact.version !== 1) findings.push('sdd task brief version must be 1');
+  if (artifact.stage !== plan.stage) findings.push('sdd task brief stage mismatch');
+  if (artifact.artifact_kind !== sddTaskBriefKind) findings.push('sdd task brief artifact kind mismatch');
+  if (artifact.task_id !== task.task_id || artifact.task_snapshot?.task_id !== task.task_id) findings.push('sdd task brief task id mismatch');
+  if (artifact.source_plan_digest !== plan.source_plan_digest) findings.push('sdd task brief plan digest drift');
+  if (artifact.title !== task.title || artifact.task_snapshot?.title !== task.title) findings.push('sdd task brief task snapshot drift');
+  if (!String(artifact.brief_file || '').endsWith('.sdd-task-brief.md')) findings.push('sdd task brief markdown file marker missing');
+  if (!String(artifact.sidecar_file || '').endsWith('.sdd-task-brief.json')) findings.push('sdd task brief sidecar file marker missing');
+  if (artifact.brief_digest !== digestText(briefText)) findings.push('sdd task brief digest mismatch');
+  const digestPayload = { ...artifact };
+  delete digestPayload.task_brief_digest;
+  if (artifact.task_brief_digest !== digestObject(digestPayload)) findings.push('sdd task brief sidecar digest mismatch');
+  if (artifact.implementer_source_of_truth !== true) findings.push('sdd task brief must be implementer source of truth');
+  if (artifact.boundary_assertions?.platform_api !== false) findings.push('sdd task brief platform_api boundary must be false');
+  if (artifact.boundary_assertions?.model_invocation !== false) findings.push('sdd task brief model boundary must be false');
+  if (artifact.boundary_assertions?.subagent !== false) findings.push('sdd task brief subagent boundary must be false');
+  if (artifact.boundary_assertions?.git_write !== false) findings.push('sdd task brief git_write boundary must be false');
+  return { ok: findings.length === 0, findings };
+}
+
+export function sddTaskBriefBoundaryAssertions(writes = false) {
+  return {
+    sdd_task_brief_artifact: Boolean(writes),
+    sdd_progress_ledger: false,
+    adapter_dispatch_artifact: false,
+    state_directory_created: 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,
+  };
+}
+
+export function digestText(text) {
+  return crypto.createHash('sha256').update(String(text || '')).digest('hex');
+}
+
+export function digestObject(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function sddTaskBriefContent({ stage, plan, task }) {
+  const evidence = (task.evidence_required || []).map((item) => `- ${item}`).join('\n') || '- review-verdict';
+  const roles = (task.role_sequence || []).map((item) => `- ${item}`).join('\n') || '- implementer\n- reviewer';
+  return [
+    '# SDD Task Brief',
+    '',
+    `stage: ${stage}`,
+    `task_id: ${task.task_id}`,
+    `source_plan: ${plan.source_plan}`,
+    `source_plan_digest: ${plan.source_plan_digest}`,
+    '',
+    '## Task',
+    task.title,
+    '',
+    '## Required evidence',
+    evidence,
+    '',
+    '## Role sequence',
+    roles,
+    '',
+    '## Review gate',
+    '- Treat this brief as the implementer source of truth.',
+    '- Do not advance to the next task until a clean review is consumed.',
+    '- Runtime may only bind local sidecars; it must not call platforms, models, subagents, git, tests, or source writes from this brief.',
+    '',
+  ].join('\n');
+}
+
+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);
+}