@haposoft/cafekit 0.16.0-rc.2 → 0.16.0-rc.4

package/src/claude/scripts/spec-scaffold.cjs

@@ -12,41 +12,230 @@
  * for the model to fill. It NEVER overwrites an existing spec directory.
  *
  * Usage:
- *   node spec-scaffold.cjs <feature> --tasks "R0-01-slug,R1-01-slug,..." \
- *        [--lang en] [--title "..."] [--specs-root specs]
+ *   node spec-scaffold.cjs <feature> [--tasks "R0-01-slug,R1-01-slug,..."] \
+ *        [--boundaries '[{"id":"B-OWN","type":"ownership",...}]'] \
+ *        [--lane Standard|Critical] [--planning-depth None|Compact|Full] \
+ *        [--assurance-level Routine|Elevated|Strict] [--research] [--risks auth,privacy] \
+ *        [--lang en] [--title "..."] [--specs-root specs] \
+ *        [--artifacts '{"R1-01-slug":["dist/output.js"]}'] \
+ *        [--dependencies '{"R1-02-consumer":["R1-01-owner"]}']
  *
  * Exit: 0 = scaffolded, 2 = usage/precondition error.
  */
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
+const POLICY = require('./workflow-policy.cjs');
+const SEMANTIC = require('./spec-semantic-model.cjs');
+const PATH_SAFETY = require('../hooks/lib/runtime-path-safety.cjs');
 
 const TEMPLATES = path.join(__dirname, '..', 'skills', 'specs', 'templates');
-const TASK_ID_RE = /^R(\d+)-(\d+)-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+function resolveTemplatePath(name) {
+  const adapterRoot = path.resolve(__dirname, '..');
+  const projectRoot = path.resolve(adapterRoot, '..');
+  const candidates = [
+    { file: path.join(TEMPLATES, name), root: adapterRoot },
+    // Packed Codex: <project>/.codex/scripts/spec-scaffold.cjs -> <project>/.agents/skills/specs/templates
+    {
+      file: path.resolve(__dirname, '..', '..', '.agents', 'skills', 'specs', 'templates', name),
+      root: projectRoot,
+    },
+  ];
+  for (const candidate of candidates) {
+    try {
+      return PATH_SAFETY.canonicalRegularFile(candidate.root, candidate.file, 'spec template');
+    } catch (e) {
+      if (e.code !== 'ENOENT' && !/cannot be inspected \(ENOENT\)/.test(e.message)) {
+        throw new Error(`template check failed: ${e.message} (${candidate.file})`);
+      }
+      continue;
+    }
+  }
+  throw new Error(`template not found: ${name} (checked ${candidates.map((item) => item.file).join(', ')})`);
+}
+const TASK_ID_RE = /^R(\d+)-(\d{2})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const TASK_PATH_RE = /^tasks\/task-(R\d+-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*)\.md$/;
+const FEATURE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const EXECUTION_CLOSURE_BLOCK_RE = /<!-- EXECUTION_CLOSURE_START -->[\s\S]*?<!-- EXECUTION_CLOSURE_END -->\n?/g;
+const REGISTRY_KEYS = [
+  'id',
+  'title',
+  'status',
+  'dependencies',
+  'blocker',
+  'started_at',
+  'completed_at',
+  'last_updated_at',
+];
+const AUTHORING_FIELDS = ['requirements', 'design', 'research', 'tasks'];
+const AUTHORING_STATES = new Set(['draft', 'validated', 'absent']);
+const SPEC_STATUS_VALUES = new Set(['in_progress', 'paused', 'blocked', 'done']);
+const TASK_STATUS_VALUES = new Set(['pending', 'in_progress', 'blocked', 'done']);
+const VALIDATION_STATUS_VALUES = new Set(['not-run', 'in_progress', 'completed']);
+const CANONICAL_SPEC_FIELDS = new Set([
+  'schema_version', 'feature_name', 'created_at', 'updated_at', 'language', 'status',
+  'scope_lock', 'authoring', 'coordination', 'validation', 'semantic_model', 'ready_for_implementation',
+  'workflow_policy', 'research', 'task_files', 'task_registry', 'decisions',
+]);
+const SCOPE_LOCK_FIELDS = ['source', 'in_scope', 'out_of_scope', 'expansion_policy'];
+const COORDINATION_FIELDS = new Set(['boundaries', 'phases']);
+const VALIDATION_FIELDS = ['status', 'semantic_review'];
+const SEMANTIC_REVIEW_FIELDS = ['status', 'semantic_digest', 'reviewed_criteria', 'counterexamples'];
+const LEGACY_SEMANTIC_REVIEW_FIELDS = [...SEMANTIC_REVIEW_FIELDS, 'reviewed_artifact_digest'];
+const LEGACY_SPEC_FIELDS = [
+  ...CANONICAL_SPEC_FIELDS,
+  'approvals', 'current_phase', 'override_receipt', 'timestamps',
+];
+const LEGACY_COORDINATION_FIELDS = [
+  ...COORDINATION_FIELDS,
+  'tasks_required', 'phases_required', 'reason', 'task_triggers',
+];
+const LEGACY_TIMESTAMP_FIELDS = [
+  'init', 'requirements_done', 'research_done', 'design_done', 'tasks_done',
+  'code_done', 'test_done', 'review_done', 'validation_done',
+];
+const LEGACY_APPROVAL_FIELDS = ['requirements', 'design', 'research', 'tasks'];
+const LEGACY_APPROVAL_STATE_FIELDS = ['generated', 'agent_validated', 'user_approved'];
+const LEGACY_POLICY_FIELDS = [
+  'version', 'planning_depth', 'automatic_planning_depth', 'assurance_level',
+  'automatic_assurance_level', 'lane', 'automatic_lane', 'risks', 'artifact_profile',
+  'planning_obligations', 'proof_obligations', 'actor_needs', 'classified_minimum', 'override_receipt',
+];
+const TRANSACTION_PREFIX = '.cafekit-scaffold-tx-';
+const TRANSACTION_FORMAT = 'cafekit-spec-scaffold-transaction/1';
+
+class ScaffoldPreconditionError extends Error {}
 
 function usage() {
-  console.error('Usage: node spec-scaffold.cjs <feature> --tasks "R0-01-slug,R1-01-slug" [--lang en] [--title "..."] [--specs-root specs]');
+  console.error('Usage: node spec-scaffold.cjs <feature> [--sync-semantic-model] [--tasks "R0-01-slug,R1-01-slug" --boundaries \'[{"id":"B-OWN","type":"ownership",...}]\'] [--lane Standard|Critical] [--planning-depth Compact|Full] [--assurance-level Routine|Elevated|Strict] [--research --uncertainty "..."] [--phases \'[{"id":"phase-1","task_ids":["R1-01"],"entry_condition":"...","exit_condition":"...","owner_boundary":"B-OWN"}]\'] [--risks auth,privacy] [--lang en] [--title "..."] [--specs-root specs]');
+}
+
+function failPrecondition(message) {
+  throw new ScaffoldPreconditionError(message);
+}
+
+function observeInstalledPolicyBaseline({ args, specDir, spec }) {
+  const adapterDir = path.dirname(__dirname);
+  const adapterName = path.basename(adapterDir);
+  if (path.basename(__dirname) !== 'scripts' || (adapterName !== '.claude' && adapterName !== '.codex')) return;
+  const statePath = path.join(adapterDir, 'hooks', 'completion-authority-state.cjs');
+  const checkPath = path.join(adapterDir, 'hooks', 'completion-authority-check.cjs');
+  if (![statePath, checkPath].every((filePath) => {
+    try {
+      const stat = fs.lstatSync(filePath);
+      if (!stat.isFile() || stat.isSymbolicLink()) return false;
+      const real = fs.realpathSync(filePath);
+      const realDir = fs.realpathSync(path.dirname(filePath));
+      const rel = path.relative(realDir, real);
+      if (rel.startsWith('..') || path.isAbsolute(rel)) return false;
+      return true;
+    } catch { return false; }
+  })) return;
+  let installedRoot;
+  let scaffoldCwd;
+  let specFile;
+  try {
+    installedRoot = fs.realpathSync(path.resolve(adapterDir, '..'));
+    scaffoldCwd = fs.realpathSync(path.resolve(process.cwd()));
+    specFile = path.join(specDir, 'spec.json');
+    const canonicalSpecFile = fs.realpathSync(specFile);
+    if (!isWithin(installedRoot, scaffoldCwd) || !isWithin(installedRoot, canonicalSpecFile)) {
+      throw new Error(`scaffold cwd and spec path must stay inside installed project root ${installedRoot}`);
+    }
+  } catch (error) {
+    throw new Error(`installed ${adapterName} scaffold authority baseline could not be verified: ${error.message}`);
+  }
+  let STATE;
+  let check;
+  let runtime = {};
+  try {
+    const realStatePath = fs.realpathSync(statePath);
+    const realCheckPath = fs.realpathSync(checkPath);
+    // Ensure real paths are still inside adapterDir's realpath (no symlink escape)
+    const realAdapterDir = fs.realpathSync(adapterDir);
+    const relState = path.relative(realAdapterDir, realStatePath);
+    const relCheck = path.relative(realAdapterDir, realCheckPath);
+    if (relState.startsWith('..') || path.isAbsolute(relState) || relCheck.startsWith('..') || path.isAbsolute(relCheck)) {
+      throw new Error('scaffold authority path escapes adapter');
+    }
+    STATE = require(realStatePath);
+    check = require(realCheckPath);
+    const runtimePath = path.join(installedRoot, adapterName, 'runtime.json');
+    if (fs.existsSync(runtimePath)) runtime = JSON.parse(fs.readFileSync(runtimePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`installed ${adapterName} scaffold authority hooks are unavailable: ${error.message}`);
+  }
+  if (typeof check.observePolicyBaseline !== 'function') throw new Error(`installed ${adapterName} scaffold authority check does not expose observePolicyBaseline`);
+  let result;
+  try {
+    result = check.observePolicyBaseline({ STATE, policy: POLICY, projectRoot: installedRoot, candidate: { spec, specFile, featureName: args.feature }, runtime });
+  } catch (error) {
+    throw new Error(`installed ${adapterName} scaffold authority baseline failed: ${error.message}`);
+  }
+  if (!result || result.ok !== true) throw new Error(`installed ${adapterName} scaffold authority baseline rejected the spec: ${result?.reason || 'unknown reason'}`);
 }
 
 function parseArgs(argv) {
-  const a = { feature: null, tasks: null, lang: 'en', title: null, specsRoot: 'specs', tasksOnly: false };
+  const a = {
+    feature: null,
+    tasks: null,
+    lane: null,
+    risks: null,
+    lang: 'en',
+    title: null,
+    specsRoot: 'specs',
+    tasksOnly: false,
+    artifacts: null,
+    dependencies: null,
+    planningDepth: null,
+    assuranceLevel: null,
+    coordination: false,
+    taskTriggers: null,
+    boundaries: null,
+    phases: null,
+    research: false,
+    uncertainty: null,
+    syncSemanticModel: false,
+  };
+  let dependenciesSeen = false;
   for (let i = 2; i < argv.length; i++) {
     const v = argv[i];
     if (v === '--tasks') a.tasks = argv[++i];
+    else if (v === '--lane') a.lane = argv[++i];
+    else if (v === '--planning-depth') a.planningDepth = argv[++i];
+    else if (v === '--assurance-level') a.assuranceLevel = argv[++i];
+    else if (v === '--coordination') a.coordination = true;
+    else if (v === '--task-triggers') a.taskTriggers = argv[++i];
+    else if (v === '--boundaries') a.boundaries = argv[++i];
+    else if (v === '--phases') a.phases = argv[++i];
+    else if (v === '--research') a.research = true;
+    else if (v === '--uncertainty') a.uncertainty = argv[++i];
+    else if (v === '--risks') a.risks = argv[++i];
     else if (v === '--lang') a.lang = argv[++i];
     else if (v === '--title') a.title = argv[++i];
     else if (v === '--specs-root') a.specsRoot = argv[++i];
     else if (v === '--tasks-only') a.tasksOnly = true;
+    else if (v === '--sync-semantic-model') a.syncSemanticModel = true;
+    else if (v === '--artifacts') a.artifacts = argv[++i];
+    else if (v === '--dependencies') {
+      if (dependenciesSeen) failPrecondition('--dependencies may be provided only once');
+      dependenciesSeen = true;
+      if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) {
+        failPrecondition('--dependencies requires one JSON object value');
+      }
+      a.dependencies = argv[++i];
+    }
     else if (!a.feature) a.feature = v;
   }
   return a;
 }
 
 function readTemplate(name) {
-  const p = path.join(TEMPLATES, name);
+  const p = resolveTemplatePath(name);
   if (!fs.existsSync(p)) {
-    console.error(`precondition: template not found: ${p}`);
-    process.exit(2);
+    failPrecondition(`template not found: ${p}`);
   }
   return fs.readFileSync(p, 'utf8');
 }
@@ -56,28 +245,435 @@ function titleFromSlug(slug) {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
 
-function registryEntry(t) {
-  return {
+function concreteUncertainty(value) {
+  return typeof value === 'string'
+    && value === value.trim()
+    && value.length >= 12
+    && !/^(?:tbd|todo|unknown|n\/a|none|placeholder)$/i.test(value);
+}
+
+function renderResearchTemplate(feature, uncertainty) {
+  return readTemplate('research.md')
+    .replace(/\{\{FEATURE_NAME\}\}/g, feature)
+    .replace(/\{\{UNCERTAINTY\}\}/g, uncertainty);
+}
+
+function registryEntry(t, artifactDeclarations, dependencies = []) {
+  const entry = {
     id: `R${t.req}-${t.seq}`,
     title: titleFromSlug(t.slug),
     status: 'pending',
-    dependencies: [],
+    dependencies: [...dependencies],
     blocker: null,
     started_at: null,
     completed_at: null,
     last_updated_at: null,
   };
+  const artifacts = artifactDeclarations.get(t.file);
+  if (artifacts) entry.artifacts = artifacts;
+  return entry;
+}
+
+function pendingApproval() {
+  return 'draft';
+}
+
+function semanticReviewNotRun() {
+  return {
+    status: 'not-run',
+    semantic_digest: null,
+    reviewed_criteria: [],
+    counterexamples: [],
+  };
+}
+
+function parseArtifactDeclarations(raw, parsedTasks) {
+  if (raw === null || raw === undefined) return new Map();
+  let declarations;
+  try {
+    declarations = JSON.parse(raw);
+  } catch (error) {
+    failPrecondition(`--artifacts must be valid JSON (${error.message})`);
+  }
+  if (!declarations || typeof declarations !== 'object' || Array.isArray(declarations)) {
+    failPrecondition('--artifacts must be an object keyed by task id or task path');
+  }
+
+  const result = new Map();
+  for (const [key, artifacts] of Object.entries(declarations)) {
+    const task = parsedTasks.find((candidate) => key === candidate.raw || key === candidate.file);
+    if (!task) {
+      failPrecondition(`--artifacts references unknown task "${key}"`);
+    }
+    if (!Array.isArray(artifacts) || artifacts.length === 0 || artifacts.some((artifact) => (
+      typeof artifact !== 'string'
+      || artifact.trim() === ''
+      || artifact !== artifact.trim()
+      || /^(?:[A-Za-z]:[\\/]|[\\/]|https?:\/\/)/.test(artifact)
+      || artifact.split(/[\\/]+/).includes('..')
+    ))) {
+      failPrecondition(`--artifacts for "${key}" must be a non-empty array of safe relative paths`);
+    }
+    if (new Set(artifacts).size !== artifacts.length) {
+      failPrecondition(`--artifacts for "${key}" must not contain duplicate paths`);
+    }
+    result.set(task.file, artifacts);
+  }
+  return result;
+}
+
+function parseDependencyDeclarations(raw, parsedTasks, knownTaskFiles, existingRegistry = {}) {
+  if (raw === null || raw === undefined) return new Map();
+  let declarations;
+  try {
+    declarations = JSON.parse(raw);
+  } catch (error) {
+    failPrecondition(`--dependencies must be valid JSON (${error.message})`);
+  }
+  if (!isPlainObject(declarations)) {
+    failPrecondition('--dependencies must be an object keyed by requested task id or task path');
+  }
+
+  const requested = new Map();
+  for (const task of parsedTasks) {
+    requested.set(task.raw, task);
+    requested.set(task.file, task);
+  }
+  const known = new Map();
+  for (const taskPath of knownTaskFiles) {
+    const identity = parseTaskPath(taskPath, `known task ${taskPath}`);
+    known.set(taskPath, taskPath);
+    known.set(identity.rawId, taskPath);
+  }
+
+  const result = new Map();
+  const declaredTargets = new Map();
+  for (const [key, dependencyRefs] of Object.entries(declarations)) {
+    const task = requested.get(key);
+    if (!task) failPrecondition(`--dependencies references unknown requested task "${key}"`);
+    const previousKey = declaredTargets.get(task.file);
+    if (previousKey) {
+      failPrecondition(
+        `--dependencies declares task "${task.file}" more than once after canonical resolution ` +
+        `("${previousKey}" and "${key}")`,
+      );
+    }
+    declaredTargets.set(task.file, key);
+    if (!Array.isArray(dependencyRefs)) {
+      failPrecondition(`--dependencies for "${key}" must be an array`);
+    }
+    const dependencies = [];
+    const seen = new Set();
+    for (const dependencyRef of dependencyRefs) {
+      if (typeof dependencyRef !== 'string') {
+        failPrecondition(`--dependencies for "${key}" must contain only task ids or task paths`);
+      }
+      const dependency = known.get(dependencyRef);
+      if (!dependency) {
+        failPrecondition(`--dependencies for "${key}" references unknown task "${dependencyRef}"`);
+      }
+      if (dependency === task.file) {
+        failPrecondition(`--dependencies for "${key}" cannot contain itself`);
+      }
+      if (seen.has(dependency)) {
+        failPrecondition(`--dependencies for "${key}" must not contain duplicate edges`);
+      }
+      seen.add(dependency);
+      dependencies.push(dependency);
+    }
+    result.set(task.file, dependencies);
+  }
+
+  const candidateRegistry = {};
+  for (const taskPath of knownTaskFiles) {
+    candidateRegistry[taskPath] = {
+      dependencies: [...(existingRegistry[taskPath]?.dependencies || [])],
+    };
+  }
+  for (const task of parsedTasks) {
+    if (!candidateRegistry[task.file]) candidateRegistry[task.file] = { dependencies: [] };
+  }
+  for (const [taskPath, dependencies] of result) {
+    candidateRegistry[taskPath].dependencies = dependencies;
+  }
+  validateDependencyCycles(knownTaskFiles, candidateRegistry);
+  return result;
+}
+
+function parsePhaseDeclarations(raw, knownTaskFiles) {
+  if (raw === null) return [];
+  let phases;
+  try {
+    phases = JSON.parse(raw);
+  } catch (error) {
+    failPrecondition(`--phases must be valid JSON (${error.message})`);
+  }
+  if (!Array.isArray(phases) || phases.length === 0) {
+    failPrecondition('--phases must be a non-empty JSON array');
+  }
+  const requiredKeys = ['entry_condition', 'exit_condition', 'id', 'owner_boundary', 'task_ids'];
+  const knownTaskIds = new Set(knownTaskFiles.map((taskPath) => parseTaskPath(taskPath, `known task ${taskPath}`).id));
+  const phaseIds = new Set();
+  return phases.map((phase, index) => {
+    const label = `--phases[${index}]`;
+    if (!isPlainObject(phase) || JSON.stringify(Object.keys(phase).sort()) !== JSON.stringify(requiredKeys)) {
+      failPrecondition(`${label} must contain exactly ${requiredKeys.join(', ')}`);
+    }
+    for (const key of ['id', 'entry_condition', 'exit_condition', 'owner_boundary']) {
+      if (typeof phase[key] !== 'string' || phase[key].trim() === '' || phase[key] !== phase[key].trim()) {
+        failPrecondition(`${label}.${key} must be a non-empty trimmed string`);
+      }
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(phase.id)) {
+      failPrecondition(`${label}.id must be one safe identifier`);
+    }
+    if (phaseIds.has(phase.id)) failPrecondition(`--phases contains duplicate id ${phase.id}`);
+    phaseIds.add(phase.id);
+    if (!Array.isArray(phase.task_ids) || phase.task_ids.length === 0) {
+      failPrecondition(`${label}.task_ids must be a non-empty array`);
+    }
+    const taskIds = new Set();
+    for (const taskId of phase.task_ids) {
+      if (typeof taskId !== 'string' || !knownTaskIds.has(taskId)) {
+        failPrecondition(`${label}.task_ids references unknown task ${String(taskId)}`);
+      }
+      if (taskIds.has(taskId)) failPrecondition(`${label}.task_ids must not contain duplicate task ids`);
+      taskIds.add(taskId);
+    }
+    return cloneJson(phase);
+  });
+}
+
+const BOUNDARY_FIELDS = Object.freeze({
+  ownership: ['id', 'type', 'tasks', 'write_sets'],
+  dependency: ['id', 'type', 'producer', 'consumer', 'deliverable'],
+  transition: ['id', 'type', 'design_ref', 'owner', 'consumers', 'precondition', 'postcondition', 'failure', 'recovery'],
+  proof: ['id', 'type', 'subject', 'verifier', 'verification_ref', 'artifact_anchor'],
+  parallel: ['id', 'type', 'tasks', 'resources'],
+});
+
+function exactTarget(value, label) {
+  safeRelativePath(value, label);
+  if (/[*?{}[\]]/.test(value) || /[\\/]$/.test(value)) {
+    failPrecondition(`${label} must be one exact grounded target, not a glob or parent directory`);
+  }
+  return value;
+}
+
+function targetsContend(left, right) {
+  const a = left.replace(/\\/g, '/').replace(/\/+$/, '');
+  const b = right.replace(/\\/g, '/').replace(/\/+$/, '');
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+function boundaryTaskList(value, label, knownTaskIds, minimum = 1) {
+  if (!Array.isArray(value) || value.length < minimum) {
+    failPrecondition(`${label} must contain at least ${minimum} task id(s)`);
+  }
+  const seen = new Set();
+  for (const taskId of value) {
+    if (!knownTaskIds.has(taskId)) failPrecondition(`${label} references unknown task ${String(taskId)}`);
+    if (seen.has(taskId)) failPrecondition(`${label} must not contain duplicate task ids`);
+    seen.add(taskId);
+  }
+  return [...value];
+}
+
+function boundaryTargetMap(value, tasks, label) {
+  if (!isPlainObject(value) || JSON.stringify(Object.keys(value).sort()) !== JSON.stringify([...tasks].sort())) {
+    failPrecondition(`${label} must be an object keyed exactly by its task ids`);
+  }
+  const result = {};
+  for (const taskId of tasks) {
+    if (!Array.isArray(value[taskId]) || value[taskId].length === 0) {
+      failPrecondition(`${label}.${taskId} must be a non-empty exact target array`);
+    }
+    result[taskId] = value[taskId].map((target, index) => exactTarget(target, `${label}.${taskId}[${index}]`));
+    if (new Set(result[taskId]).size !== result[taskId].length) {
+      failPrecondition(`${label}.${taskId} must not contain duplicate targets`);
+    }
+  }
+  for (let left = 0; left < tasks.length; left += 1) {
+    for (let right = left + 1; right < tasks.length; right += 1) {
+      for (const a of result[tasks[left]]) {
+        for (const b of result[tasks[right]]) {
+          if (targetsContend(a, b)) {
+            failPrecondition(`${label} has resource contention between ${tasks[left]}:${a} and ${tasks[right]}:${b}`);
+          }
+        }
+      }
+    }
+  }
+  return result;
+}
+
+function parseBoundaryDeclarations(raw, knownTaskFiles) {
+  if (raw === null || raw === undefined) return [];
+  let boundaries;
+  try { boundaries = JSON.parse(raw); } catch (error) {
+    failPrecondition(`--boundaries must be valid JSON (${error.message})`);
+  }
+  if (!Array.isArray(boundaries) || boundaries.length === 0) {
+    failPrecondition('--boundaries must be a non-empty JSON array');
+  }
+  const taskPathById = new Map(knownTaskFiles.map((taskPath) => {
+    const identity = parseTaskPath(taskPath, `known task ${taskPath}`);
+    return [identity.id, taskPath];
+  }));
+  const knownTaskIds = new Set(taskPathById.keys());
+  const ids = new Set();
+  const result = boundaries.map((boundary, index) => {
+    const label = `--boundaries[${index}]`;
+    if (!isPlainObject(boundary) || !Object.prototype.hasOwnProperty.call(BOUNDARY_FIELDS, boundary.type)) {
+      failPrecondition(`${label}.type must be ownership, dependency, transition, proof, or parallel`);
+    }
+    if (JSON.stringify(Object.keys(boundary).sort()) !== JSON.stringify([...BOUNDARY_FIELDS[boundary.type]].sort())) {
+      failPrecondition(`${label} ${boundary.type} fields must be exactly ${BOUNDARY_FIELDS[boundary.type].join(', ')}`);
+    }
+    if (typeof boundary.id !== 'string' || !/^B-[A-Z0-9][A-Z0-9._-]*$/i.test(boundary.id)) {
+      failPrecondition(`${label}.id must be a safe B-* identifier`);
+    }
+    if (ids.has(boundary.id)) failPrecondition(`--boundaries contains duplicate id ${boundary.id}`);
+    ids.add(boundary.id);
+    if (boundary.type === 'ownership') {
+      const tasks = boundaryTaskList(boundary.tasks, `${label}.tasks`, knownTaskIds, 2);
+      boundaryTargetMap(boundary.write_sets, tasks, `${label}.write_sets`);
+    } else if (boundary.type === 'dependency') {
+      boundaryTaskList([boundary.producer, boundary.consumer], label, knownTaskIds, 2);
+      if (boundary.producer === boundary.consumer) failPrecondition(`${label} producer and consumer must differ`);
+      exactTarget(boundary.deliverable, `${label}.deliverable`);
+    } else if (boundary.type === 'transition') {
+      boundaryTaskList([boundary.owner], `${label}.owner`, knownTaskIds);
+      boundaryTaskList(boundary.consumers, `${label}.consumers`, knownTaskIds);
+      if (boundary.consumers.includes(boundary.owner)) failPrecondition(`${label}.consumers cannot include transition owner`);
+      if (!/^T\d+(?:\.\d+)?$/i.test(boundary.design_ref)) failPrecondition(`${label}.design_ref must be a T id`);
+      for (const field of ['precondition', 'postcondition', 'failure', 'recovery']) {
+        if (typeof boundary[field] !== 'string' || boundary[field].trim().length < 8) {
+          failPrecondition(`${label}.${field} must be a concrete definition`);
+        }
+      }
+    } else if (boundary.type === 'proof') {
+      boundaryTaskList([boundary.subject, boundary.verifier], label, knownTaskIds, 2);
+      if (boundary.subject === boundary.verifier) failPrecondition(`${label} subject and verifier must differ`);
+      if (!/^V\d+(?:\.\d+)?$/i.test(boundary.verification_ref)) failPrecondition(`${label}.verification_ref must be a V id`);
+      if (!new RegExp(`^A-${boundary.verifier}-\\d{2}$`).test(boundary.artifact_anchor)) {
+        failPrecondition(`${label}.artifact_anchor must be owned by verifier ${boundary.verifier}`);
+      }
+    } else if (boundary.type === 'parallel') {
+      const tasks = boundaryTaskList(boundary.tasks, `${label}.tasks`, knownTaskIds, 2);
+      boundaryTargetMap(boundary.resources, tasks, `${label}.resources`);
+    }
+    return cloneJson(boundary);
+  });
+
+  const dependencies = result.filter((boundary) => boundary.type === 'dependency');
+  const graph = new Map([...knownTaskIds].map((taskId) => [taskId, []]));
+  for (const boundary of dependencies) graph.get(boundary.producer).push(boundary.consumer);
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (taskId, stack = []) => {
+    if (visiting.has(taskId)) {
+      const start = stack.indexOf(taskId);
+      failPrecondition(`coordination.boundaries dependency cycle: ${stack.slice(start).concat(taskId).join(' -> ')}`);
+    }
+    if (visited.has(taskId)) return;
+    visiting.add(taskId);
+    for (const consumer of graph.get(taskId)) visit(consumer, [...stack, taskId]);
+    visiting.delete(taskId);
+    visited.add(taskId);
+  };
+  for (const taskId of knownTaskIds) visit(taskId);
+  const pathExists = (from, to, seen = new Set()) => {
+    if (from === to) return true;
+    if (seen.has(from)) return false;
+    seen.add(from);
+    return graph.get(from).some((next) => pathExists(next, to, seen));
+  };
+  for (const boundary of result.filter((candidate) => candidate.type === 'parallel')) {
+    for (let left = 0; left < boundary.tasks.length; left += 1) {
+      for (let right = left + 1; right < boundary.tasks.length; right += 1) {
+        if (pathExists(boundary.tasks[left], boundary.tasks[right])
+          || pathExists(boundary.tasks[right], boundary.tasks[left])) {
+          failPrecondition(`${boundary.id}: parallel tasks must have no dependency path`);
+        }
+      }
+    }
+    const authorities = result.filter((candidate) => ['transition', 'proof'].includes(candidate.type));
+    for (const authority of authorities) {
+      const owners = authority.type === 'transition'
+        ? [authority.owner, ...authority.consumers]
+        : [authority.subject, authority.verifier];
+      if (boundary.tasks.filter((taskId) => owners.includes(taskId)).length > 1) {
+        failPrecondition(`${boundary.id}: parallel tasks cannot share ${authority.type} authority ${authority.id}`);
+      }
+    }
+  }
+  return result;
 }
 
-function fillTask(taskTpl, t, feature) {
-  return taskTpl
+function dependenciesFromBoundaries(boundaries, knownTaskFiles) {
+  const pathById = new Map(knownTaskFiles.map((taskPath) => [parseTaskPath(taskPath, taskPath).id, taskPath]));
+  const result = new Map(knownTaskFiles.map((taskPath) => [taskPath, []]));
+  for (const boundary of boundaries) {
+    if (boundary.type !== 'dependency') continue;
+    result.get(pathById.get(boundary.consumer)).push(pathById.get(boundary.producer));
+  }
+  for (const [taskPath, dependencies] of result) result.set(taskPath, [...new Set(dependencies)].sort());
+  return result;
+}
+
+function validatePhaseBoundaryRefs(phases, boundaries) {
+  const boundaryIds = new Set(boundaries.map((boundary) => boundary.id));
+  for (const phase of phases) {
+    if (!boundaryIds.has(phase.owner_boundary)) {
+      failPrecondition(`phase ${phase.id}.owner_boundary references unknown boundary ${phase.owner_boundary}`);
+    }
+  }
+}
+
+function applyExecutionClosureProfile(content, includeExecutionClosure) {
+  if (!includeExecutionClosure) return content.replace(EXECUTION_CLOSURE_BLOCK_RE, '');
+  return content
+    .replace('<!-- EXECUTION_CLOSURE_START -->\n', '')
+    .replace('<!-- EXECUTION_CLOSURE_END -->\n', '');
+}
+
+function declaredImplementationObligations(spec) {
+  return Array.isArray(spec?.implementation_obligations)
+    ? spec.implementation_obligations.filter(isPlainObject)
+    : [];
+}
+
+function taskHasDeclaredImplementationObligation(spec, taskPath) {
+  return declaredImplementationObligations(spec).some((obligation) => (
+    obligation.owner_task === taskPath
+    || (Array.isArray(obligation.consumer_tasks) && obligation.consumer_tasks.includes(taskPath))
+  ));
+}
+
+function fillTask(taskTpl, t, feature, dependencies = [], includeExecutionClosure = false) {
+  return applyExecutionClosureProfile(taskTpl, includeExecutionClosure)
     .replace(/\{\{REQ_NUMBER\}\}/g, t.req)
     .replace(/\{\{SEQ\}\}/g, t.seq)
     .replace(/\{\{TITLE\}\}/g, titleFromSlug(t.slug))
     .replace(/\{\{FEATURE_NAME\}\}/g, feature)
     .replace(/\{\{PRIORITY\}\}/g, 'P2')
     .replace(/\{\{EFFORT\}\}/g, 'TBD')
-    .replace(/\{\{DEPENDENCIES\}\}/g, 'none');
+    .replace(/\{\{DEPENDENCIES\}\}/g, dependencies.length > 0 ? dependencies.join(', ') : 'none');
+}
+
+function parseRiskNames(raw) {
+  if (!raw) return [];
+  const aliases = new Map([
+    ['auth', 'auth'],
+    ['authentication', 'auth'],
+    ['authorization', 'auth'],
+  ]);
+  return [...new Set(raw
+    .split(',')
+    .map((risk) => risk.trim().toLowerCase())
+    .filter(Boolean)
+    .map((risk) => aliases.get(risk) || risk))];
 }
 
 function nowIso() {
@@ -91,22 +687,1221 @@ function nowIso() {
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${sign}${oh}:${om}`;
 }
 
+function hasOwn(value, key) {
+  return value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function assertExactKeys(value, expected, label) {
+  if (!isPlainObject(value)) failPrecondition(`${label} must be an object`);
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (JSON.stringify(actual) !== JSON.stringify(wanted)) {
+    const unknown = actual.filter((key) => !wanted.includes(key));
+    const missing = wanted.filter((key) => !actual.includes(key));
+    failPrecondition(
+      `${label} must be closed-world; unknown=[${unknown.join(', ')}], missing=[${missing.join(', ')}]`,
+    );
+  }
+}
+
+function canonicalRegistryFields(entry) {
+  return hasOwn(entry, 'artifacts') ? [...REGISTRY_KEYS, 'artifacts'] : REGISTRY_KEYS;
+}
+
+function assertCanonicalSpecInputClosedWorld(spec) {
+  if (!isPlainObject(spec) || spec.schema_version !== '2.1') return;
+  const topLevel = [...CANONICAL_SPEC_FIELDS].filter((field) => {
+    if (field === 'research') return hasOwn(spec, 'research');
+    if (field === 'task_files' || field === 'task_registry') return hasOwn(spec, field);
+    if (field === 'decisions') return hasOwn(spec, 'decisions');
+    return true;
+  });
+  assertExactKeys(spec, topLevel, 'canonical schema 2.1 spec.json');
+  assertExactKeys(spec.scope_lock, SCOPE_LOCK_FIELDS, 'canonical schema 2.1 scope_lock');
+  assertExactKeys(spec.authoring, AUTHORING_FIELDS, 'canonical schema 2.1 authoring');
+  const coordinationFields = hasOwn(spec.coordination, 'phases')
+    ? [...COORDINATION_FIELDS] : ['boundaries'];
+  assertExactKeys(spec.coordination, coordinationFields, 'canonical schema 2.1 coordination');
+  assertExactKeys(spec.validation, VALIDATION_FIELDS, 'canonical schema 2.1 validation');
+  assertExactKeys(
+    spec.validation.semantic_review,
+    SEMANTIC_REVIEW_FIELDS,
+    'canonical schema 2.1 validation.semantic_review',
+  );
+  if (Array.isArray(spec.validation.semantic_review?.counterexamples)) {
+    const fields = ['criterion', 'case_kind', 'scenario', 'expected', 'decision_refs', 'verification_ref'];
+    for (const [index, counterexample] of spec.validation.semantic_review.counterexamples.entries()) {
+      assertExactKeys(
+        counterexample,
+        fields,
+        `canonical schema 2.1 validation.semantic_review.counterexamples[${index}]`,
+      );
+    }
+  }
+  if (hasOwn(spec, 'decisions')) {
+    if (!Array.isArray(spec.decisions) || spec.decisions.length === 0) failPrecondition('canonical schema 2.1 decisions must be omitted or a non-empty array');
+    for (const [index, decision] of spec.decisions.entries()) {
+      assertExactKeys(decision, ['id', 'classification', 'statement', 'status', 'evidence'], `canonical schema 2.1 decisions[${index}]`);
+    }
+  }
+  if (Array.isArray(spec.coordination?.boundaries)) {
+    for (const [index, boundary] of spec.coordination.boundaries.entries()) {
+      if (!isPlainObject(boundary) || !Object.prototype.hasOwnProperty.call(BOUNDARY_FIELDS, boundary.type)) {
+        failPrecondition(`canonical schema 2.1 coordination.boundaries[${index}] has an unknown type`);
+      }
+      assertExactKeys(
+        boundary,
+        BOUNDARY_FIELDS[boundary.type],
+        `canonical schema 2.1 coordination.boundaries[${index}]`,
+      );
+    }
+  }
+  if (Array.isArray(spec.coordination?.phases)) {
+    const fields = ['entry_condition', 'exit_condition', 'id', 'owner_boundary', 'task_ids'];
+    for (const [index, phase] of spec.coordination.phases.entries()) {
+      assertExactKeys(phase, fields, `canonical schema 2.1 coordination.phases[${index}]`);
+    }
+  }
+  if (hasOwn(spec, 'task_registry') && isPlainObject(spec.task_registry)) {
+    for (const [taskPath, entry] of Object.entries(spec.task_registry)) {
+      assertExactKeys(entry, canonicalRegistryFields(entry), `canonical schema 2.1 task_registry.${taskPath}`);
+    }
+  }
+}
+
+function rejectUnknownKeys(value, allowed, label) {
+  if (!isPlainObject(value)) return;
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) {
+    failPrecondition(`${label} contains unsupported legacy authority field(s): ${unknown.join(', ')}; remove or explicitly migrate them before schema 2.1 promotion`);
+  }
+}
+
+function assertLegacyMigrationClosedWorld(spec) {
+  rejectUnknownKeys(spec, LEGACY_SPEC_FIELDS, 'schema 2.0 spec.json');
+  rejectUnknownKeys(spec.scope_lock, SCOPE_LOCK_FIELDS, 'schema 2.0 scope_lock');
+  rejectUnknownKeys(spec.authoring, AUTHORING_FIELDS, 'schema 2.0 authoring');
+  rejectUnknownKeys(spec.coordination, LEGACY_COORDINATION_FIELDS, 'schema 2.0 coordination');
+  rejectUnknownKeys(spec.validation, VALIDATION_FIELDS, 'schema 2.0 validation');
+  rejectUnknownKeys(spec.validation?.semantic_review, LEGACY_SEMANTIC_REVIEW_FIELDS, 'schema 2.0 validation.semantic_review');
+  for (const [index, counterexample] of (spec.validation?.semantic_review?.counterexamples || []).entries()) {
+    rejectUnknownKeys(counterexample, ['criterion', 'case_kind', 'scenario', 'expected', 'decision_refs', 'verification_ref'], `schema 2.0 semantic_review.counterexamples[${index}]`);
+  }
+  for (const [index, boundary] of (spec.coordination?.boundaries || []).entries()) {
+    if (!isPlainObject(boundary) || !hasOwn(BOUNDARY_FIELDS, boundary.type)) {
+      failPrecondition(`schema 2.0 coordination.boundaries[${index}] has an unknown authority type`);
+    }
+    rejectUnknownKeys(boundary, BOUNDARY_FIELDS[boundary.type], `schema 2.0 coordination.boundaries[${index}]`);
+  }
+  if (isPlainObject(spec.workflow_policy)) {
+    rejectUnknownKeys(spec.workflow_policy, LEGACY_POLICY_FIELDS, 'schema 2.0 workflow_policy');
+  }
+  if (hasOwn(spec, 'current_phase')
+    && (typeof spec.current_phase !== 'string' || spec.current_phase.trim() === '')) {
+    failPrecondition('schema 2.0 current_phase must be a non-empty string when present');
+  }
+  if (hasOwn(spec, 'timestamps')) {
+    if (!isPlainObject(spec.timestamps)) failPrecondition('schema 2.0 timestamps must be an object');
+    rejectUnknownKeys(spec.timestamps, LEGACY_TIMESTAMP_FIELDS, 'schema 2.0 timestamps');
+    for (const [field, value] of Object.entries(spec.timestamps)) {
+      if (value !== null && !isIsoTimestamp(value)) {
+        failPrecondition(`schema 2.0 timestamps.${field} must be null or a valid ISO 8601 timestamp`);
+      }
+    }
+  }
+  if (hasOwn(spec, 'approvals')) {
+    if (!isPlainObject(spec.approvals)) failPrecondition('schema 2.0 approvals must be an object');
+    rejectUnknownKeys(spec.approvals, LEGACY_APPROVAL_FIELDS, 'schema 2.0 approvals');
+    for (const [section, state] of Object.entries(spec.approvals)) {
+      if (!isPlainObject(state)) failPrecondition(`schema 2.0 approvals.${section} must be an object`);
+      rejectUnknownKeys(state, LEGACY_APPROVAL_STATE_FIELDS, `schema 2.0 approvals.${section}`);
+      for (const [field, value] of Object.entries(state)) {
+        if (typeof value !== 'boolean') {
+          failPrecondition(`schema 2.0 approvals.${section}.${field} must be boolean`);
+        }
+      }
+    }
+  }
+  if (isPlainObject(spec.task_registry)) for (const [taskPath, entry] of Object.entries(spec.task_registry)) {
+    rejectUnknownKeys(entry, canonicalRegistryFields(entry), `schema 2.0 task_registry.${taskPath}`);
+  }
+}
+
+function isIsoTimestamp(value) {
+  return typeof value === 'string'
+    && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
+    && Number.isFinite(Date.parse(value));
+}
+
+function isWithin(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function assertNoSymlinkPath(root, target, label) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(target);
+  if (!isWithin(resolvedRoot, resolvedTarget)) {
+    failPrecondition(`${label} escapes the work root: ${target}`);
+  }
+
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  let current = resolvedRoot;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch (error) {
+      if (error.code === 'ENOENT') break;
+      failPrecondition(`${label} cannot be inspected (${error.message})`);
+    }
+    if (stat.isSymbolicLink()) failPrecondition(`${label} cannot traverse a symlink: ${current}`);
+  }
+}
+
+function assertExistingDirectory(root, directory, label) {
+  assertNoSymlinkPath(root, directory, label);
+  let stat;
+  try {
+    stat = fs.lstatSync(directory);
+  } catch (error) {
+    failPrecondition(`${label} is missing (${error.message})`);
+  }
+  if (!stat.isDirectory()) failPrecondition(`${label} must be a directory`);
+}
+
+function assertRegularFileOrMissing(root, filePath, label) {
+  assertNoSymlinkPath(root, filePath, label);
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile()) failPrecondition(`${label} must be a regular file`);
+  } catch (error) {
+    if (error instanceof ScaffoldPreconditionError) throw error;
+    if (error.code !== 'ENOENT') failPrecondition(`${label} cannot be inspected (${error.message})`);
+  }
+}
+
+function safeRelativePath(value, label) {
+  if (
+    typeof value !== 'string'
+    || value.trim() === ''
+    || value !== value.trim()
+    || path.isAbsolute(value)
+    || /^[A-Za-z]:[\\/]/.test(value)
+    || value.split(/[\\/]+/).includes('..')
+  ) {
+    failPrecondition(`${label} must be a safe relative path`);
+  }
+  return value;
+}
+
+function validateArtifactList(artifacts, label) {
+  if (!Array.isArray(artifacts) || artifacts.length === 0) {
+    failPrecondition(`${label} must be a non-empty array of safe relative paths`);
+  }
+  const seen = new Set();
+  for (const artifact of artifacts) {
+    safeRelativePath(artifact, `${label} entry`);
+    if (seen.has(artifact)) failPrecondition(`${label} must not contain duplicate paths`);
+    seen.add(artifact);
+  }
+}
+
+function parseTaskPath(taskPath, label) {
+  const match = typeof taskPath === 'string' && taskPath.match(TASK_PATH_RE);
+  if (!match) failPrecondition(`${label} must match tasks/task-R{N}-{SEQ}-<slug>.md`);
+  const rawId = match[1];
+  const idParts = rawId.match(TASK_ID_RE);
+  if (!idParts) failPrecondition(`${label} contains an invalid task id`);
+  return { id: `R${idParts[1]}-${idParts[2]}`, rawId, req: idParts[1], seq: idParts[2], slug: idParts[3] };
+}
+
+function validateTaskPathList(taskFiles, label) {
+  if (!Array.isArray(taskFiles)) failPrecondition(`${label} must be an array`);
+  const seen = new Set();
+  for (const taskPath of taskFiles) {
+    parseTaskPath(taskPath, `${label} entry`);
+    if (seen.has(taskPath)) failPrecondition(`${label} contains duplicate path ${taskPath}`);
+    seen.add(taskPath);
+  }
+  return [...taskFiles].sort();
+}
+
+function validateRegistryEntry(taskPath, entry, declaredSet) {
+  if (!isPlainObject(entry)) failPrecondition(`task_registry.${taskPath} must be an object`);
+  for (const key of REGISTRY_KEYS) {
+    if (!hasOwn(entry, key)) failPrecondition(`task_registry.${taskPath} is missing ${key}`);
+  }
+  const identity = parseTaskPath(taskPath, `task_registry.${taskPath}`);
+  if (entry.id !== identity.id) failPrecondition(`task_registry.${taskPath}.id conflicts with its task path`);
+  if (typeof entry.title !== 'string' || entry.title.trim() === '') failPrecondition(`task_registry.${taskPath}.title must be a non-empty string`);
+  if (!TASK_STATUS_VALUES.has(entry.status)) {
+    failPrecondition(`task_registry.${taskPath}.status must be one of ${[...TASK_STATUS_VALUES].join(', ')}`);
+  }
+  if (!Array.isArray(entry.dependencies)) failPrecondition(`task_registry.${taskPath}.dependencies must be an array`);
+  const dependencies = new Set();
+  for (const dependency of entry.dependencies) {
+    parseTaskPath(dependency, `task_registry.${taskPath}.dependencies entry`);
+    if (dependencies.has(dependency)) failPrecondition(`task_registry.${taskPath}.dependencies contains a duplicate`);
+    if (dependency === taskPath) failPrecondition(`task_registry.${taskPath}.dependencies cannot contain itself`);
+    if (!declaredSet.has(dependency)) failPrecondition(`task_registry.${taskPath}.dependencies references unknown task ${dependency}`);
+    dependencies.add(dependency);
+  }
+  if (hasOwn(entry, 'artifacts')) validateArtifactList(entry.artifacts, `task_registry.${taskPath}.artifacts`);
+  const label = `task_registry.${taskPath}`;
+  if (entry.blocker !== null && (typeof entry.blocker !== 'string' || entry.blocker.trim() === '')) {
+    failPrecondition(`${label}.blocker must be null or a non-empty string`);
+  }
+  for (const field of ['started_at', 'completed_at', 'last_updated_at']) {
+    if (entry[field] !== null && !isIsoTimestamp(entry[field])) {
+      failPrecondition(`${label}.${field} must be null or an ISO 8601 timestamp`);
+    }
+  }
+  if (entry.status === 'pending') {
+    if (entry.blocker !== null || entry.started_at !== null || entry.completed_at !== null) {
+      failPrecondition(`${label} pending lifecycle is inconsistent`);
+    }
+  } else if (entry.status === 'in_progress') {
+    if (entry.blocker !== null || !isIsoTimestamp(entry.started_at)
+      || entry.completed_at !== null || !isIsoTimestamp(entry.last_updated_at)
+      || Date.parse(entry.last_updated_at) < Date.parse(entry.started_at)) {
+      failPrecondition(`${label} in_progress lifecycle is inconsistent`);
+    }
+  } else if (entry.status === 'blocked') {
+    if (typeof entry.blocker !== 'string' || entry.blocker.trim() === ''
+      || entry.completed_at !== null || !isIsoTimestamp(entry.last_updated_at)
+      || (isIsoTimestamp(entry.started_at) && Date.parse(entry.last_updated_at) < Date.parse(entry.started_at))) {
+      failPrecondition(`${label} blocked lifecycle is inconsistent`);
+    }
+  } else if (entry.status === 'done') {
+    if (entry.blocker !== null
+      || ![entry.started_at, entry.completed_at, entry.last_updated_at].every(isIsoTimestamp)
+      || Date.parse(entry.completed_at) < Date.parse(entry.started_at)
+      || Date.parse(entry.last_updated_at) < Date.parse(entry.completed_at)) {
+      failPrecondition(`${label} done lifecycle is inconsistent`);
+    }
+  }
+}
+
+function semanticReviewShapeValid(review) {
+  return isPlainObject(review)
+    && ['not-run', 'completed'].includes(review.status)
+    && (review.semantic_digest === null || typeof review.semantic_digest === 'string')
+    && Array.isArray(review.reviewed_criteria)
+    && Array.isArray(review.counterexamples);
+}
+
+function preflightSpec21Candidate(spec, evidence) {
+  if (!isPlainObject(spec)) failPrecondition('schema 2.1 candidate must be an object');
+  assertCanonicalSpecInputClosedWorld(spec);
+  if (hasOwn(spec, 'override_receipt')) {
+    failPrecondition('schema 2.1 candidate override_receipt is unsupported; omit the field');
+  }
+  const required = [
+    'schema_version', 'feature_name', 'created_at', 'updated_at', 'language', 'status',
+    'scope_lock', 'authoring', 'coordination', 'validation', 'semantic_model', 'ready_for_implementation',
+    'workflow_policy',
+  ];
+  for (const field of required) if (!hasOwn(spec, field)) {
+    failPrecondition(`schema 2.1 candidate is missing required machine field ${field}`);
+  }
+  if (spec.schema_version !== '2.1') failPrecondition('schema 2.1 candidate has an unsupported schema_version');
+  if (spec.feature_name !== evidence.featureName) failPrecondition('feature_name conflicts with the scaffold feature identity');
+  if (!isIsoTimestamp(spec.created_at) || !isIsoTimestamp(spec.updated_at)
+    || Date.parse(spec.updated_at) < Date.parse(spec.created_at)) {
+    failPrecondition('schema 2.1 candidate lifecycle timestamps are invalid');
+  }
+  if (typeof spec.language !== 'string' || spec.language.trim() === '') failPrecondition('schema 2.1 candidate language must be non-empty');
+  if (!SPEC_STATUS_VALUES.has(spec.status)) failPrecondition('schema 2.1 candidate status is invalid');
+  if (!isPlainObject(spec.scope_lock)) failPrecondition('schema 2.1 candidate scope_lock must be an object');
+  if (!isPlainObject(spec.authoring)
+    || Object.keys(spec.authoring).sort().join(',') !== [...AUTHORING_FIELDS].sort().join(',')) {
+    failPrecondition('schema 2.1 candidate authoring must contain exactly requirements, design, research, and tasks');
+  }
+  for (const field of AUTHORING_FIELDS) if (!AUTHORING_STATES.has(spec.authoring[field])) {
+    failPrecondition(`schema 2.1 candidate authoring.${field} is invalid`);
+  }
+  if (!evidence.requirementsExists || !evidence.designExists) {
+    failPrecondition('schema 2.1 migration requires physical requirements.md and design.md files');
+  }
+  if (spec.authoring.requirements === 'absent' || spec.authoring.design === 'absent') {
+    failPrecondition('physical requirements.md and design.md cannot be marked absent');
+  }
+  if (evidence.researchExists) {
+    if (spec.research !== 'research.md' || spec.authoring.research === 'absent') {
+      failPrecondition('research pointer, authoring state, and physical research.md must agree');
+    }
+  } else if (hasOwn(spec, 'research') || spec.authoring.research !== 'absent') {
+    failPrecondition('absent physical research.md requires no pointer and authoring.research absent');
+  }
+  if (!isPlainObject(spec.coordination) || !Array.isArray(spec.coordination.boundaries)) {
+    failPrecondition('schema 2.1 candidate coordination.boundaries must be an array');
+  }
+  if (!isPlainObject(spec.validation) || !VALIDATION_STATUS_VALUES.has(spec.validation.status)
+    || !semanticReviewShapeValid(spec.validation.semantic_review)) {
+    failPrecondition('schema 2.1 candidate validation state is invalid');
+  }
+  if (typeof spec.ready_for_implementation !== 'boolean') failPrecondition('schema 2.1 candidate readiness must be boolean');
+  if (spec.semantic_model !== null) {
+    const semanticErrors = SEMANTIC.validateSemanticModel(spec.semantic_model, spec);
+    if (semanticErrors.length) failPrecondition(`schema 2.1 candidate semantic_model is invalid (${semanticErrors.join('; ')})`);
+  } else if (spec.ready_for_implementation === true) {
+    failPrecondition('schema 2.1 readiness requires a promoted semantic_model');
+  }
+  if (isPlainObject(spec.workflow_policy) && hasOwn(spec.workflow_policy, 'override_receipt')) {
+    failPrecondition('schema 2.1 candidate workflow_policy.override_receipt is unsupported; omit the field');
+  }
+  const policyValidation = POLICY.validateWorkflowPolicySnapshot(spec.workflow_policy);
+  if (!policyValidation.valid || spec.workflow_policy.version !== '2.1') {
+    failPrecondition(`schema 2.1 candidate workflow_policy is invalid (${policyValidation.errors.join('; ')})`);
+  }
+  const taskFiles = validateTaskPathList(spec.task_files || [], 'task_files');
+  if (JSON.stringify(taskFiles) !== JSON.stringify([...evidence.taskFiles].sort())) {
+    failPrecondition('schema 2.1 candidate task_files do not match the resulting physical topology');
+  }
+  if (taskFiles.length === 0) {
+    if (hasOwn(spec, 'task_files') || hasOwn(spec, 'task_registry') || spec.authoring.tasks !== 'absent') {
+      failPrecondition('taskless schema 2.1 candidate must omit task topology and mark tasks absent');
+    }
+  } else {
+    if (!isPlainObject(spec.task_registry)
+      || Object.keys(spec.task_registry).sort().join(',') !== taskFiles.join(',')) {
+      failPrecondition('schema 2.1 candidate task_registry must exactly match task_files');
+    }
+    if (!['draft', 'validated'].includes(spec.authoring.tasks)) {
+      failPrecondition('physical tasks require draft or validated authoring state');
+    }
+    const declared = new Set(taskFiles);
+    for (const taskPath of taskFiles) validateRegistryEntry(taskPath, spec.task_registry[taskPath], declared);
+    validateDependencyCycles(taskFiles, spec.task_registry);
+  }
+}
+
+function normalizeSpec21Candidate(candidate, evidence) {
+  try {
+    if (!isPlainObject(candidate)) failPrecondition('migration candidate must be an object');
+    if (!['2.0', '2.1'].includes(candidate.schema_version)) {
+      failPrecondition('migration candidate schema_version must be exactly 2.0 or 2.1');
+    }
+    const isLegacy = candidate.schema_version === '2.0';
+    if (isLegacy) assertLegacyMigrationClosedWorld(candidate);
+    if (!isLegacy) assertCanonicalSpecInputClosedWorld(candidate);
+    const featureName = !hasOwn(candidate, 'feature_name') && isLegacy
+      ? evidence.featureName : candidate.feature_name;
+    if (typeof featureName !== 'string' || featureName.trim() === ''
+      || featureName !== evidence.featureName) {
+      failPrecondition('existing feature_name conflicts with the scaffold feature identity');
+    }
+    if (!isIsoTimestamp(candidate.created_at) || !isIsoTimestamp(candidate.updated_at)) {
+      failPrecondition('existing created_at and updated_at must be valid ISO 8601 timestamps');
+    }
+    if (typeof candidate.language !== 'string' || candidate.language.trim() === '') {
+      failPrecondition('existing language must be a non-empty string');
+    }
+    const status = isLegacy && candidate.status === 'in-progress' ? 'in_progress' : candidate.status;
+    if (!SPEC_STATUS_VALUES.has(status)) failPrecondition('existing spec status is invalid');
+    if (!isPlainObject(candidate.scope_lock)) failPrecondition('existing scope_lock must be an object');
+    const scopeLock = {
+      source: candidate.scope_lock.source,
+      in_scope: candidate.scope_lock.in_scope,
+      out_of_scope: candidate.scope_lock.out_of_scope,
+      expansion_policy: candidate.scope_lock.expansion_policy,
+    };
+    if (typeof scopeLock.source !== 'string' || scopeLock.source.trim() === ''
+      || !Array.isArray(scopeLock.in_scope) || !Array.isArray(scopeLock.out_of_scope)
+      || typeof scopeLock.expansion_policy !== 'string' || scopeLock.expansion_policy.trim() === '') {
+      failPrecondition('existing scope_lock canonical fields are invalid');
+    }
+
+    const previousAuthoring = isPlainObject(candidate.authoring) ? candidate.authoring : {};
+    const authoring = {};
+    for (const field of ['requirements', 'design']) {
+      if (!evidence[`${field}Exists`]) failPrecondition(`physical ${field}.md is required for schema 2.1 migration`);
+      authoring[field] = previousAuthoring[field] === 'validated' ? 'validated' : 'draft';
+    }
+    if (evidence.researchExists) {
+      const pointer = isPlainObject(candidate.research) ? candidate.research.path : candidate.research;
+      if (pointer !== undefined && pointer !== null && pointer !== 'research.md') {
+        failPrecondition('legacy research pointer is ambiguous; expected canonical research.md');
+      }
+      authoring.research = previousAuthoring.research === 'validated' && !evidence.researchChanged
+        ? 'validated' : 'draft';
+    } else {
+      if (hasOwn(candidate, 'research') && candidate.research !== null) {
+        failPrecondition('research pointer exists without a physical research.md artifact');
+      }
+      authoring.research = 'absent';
+    }
+    if (evidence.taskFiles.length > 0) {
+      authoring.tasks = previousAuthoring.tasks === 'validated' && !evidence.tasksChanged
+        ? 'validated' : 'draft';
+    } else {
+      authoring.tasks = 'absent';
+    }
+    const projectedRegistry = {};
+    for (const taskPath of evidence.taskFiles) {
+      const entry = candidate.task_registry?.[taskPath];
+      if (!isPlainObject(entry)) failPrecondition(`task_registry.${taskPath} must be an object`);
+      projectedRegistry[taskPath] = {};
+      for (const key of canonicalRegistryFields(entry)) {
+        if (hasOwn(entry, key)) projectedRegistry[taskPath][key] = cloneJson(entry[key]);
+      }
+    }
+    const validationValid = isPlainObject(candidate.validation)
+      && VALIDATION_STATUS_VALUES.has(candidate.validation.status)
+      && semanticReviewShapeValid(candidate.validation.semantic_review);
+    const readinessValid = typeof candidate.ready_for_implementation === 'boolean';
+    const next = {
+      schema_version: '2.1',
+      feature_name: featureName,
+      created_at: candidate.created_at,
+      updated_at: candidate.updated_at,
+      language: candidate.language,
+      status,
+      scope_lock: scopeLock,
+      authoring,
+      coordination: cloneJson(evidence.coordination),
+      validation: validationValid ? cloneJson(candidate.validation) : {
+        status: 'not-run', semantic_review: semanticReviewNotRun(),
+      },
+      semantic_model: isLegacy ? null : cloneJson(candidate.semantic_model),
+      ready_for_implementation: readinessValid ? candidate.ready_for_implementation : false,
+      workflow_policy: cloneJson(evidence.workflowPolicy),
+      ...(evidence.researchExists ? { research: 'research.md' } : {}),
+      ...(evidence.taskFiles.length > 0 ? {
+        task_files: [...evidence.taskFiles].sort(), task_registry: projectedRegistry,
+      } : {}),
+    };
+    const semanticChanged = evidence.tasksChanged || evidence.researchChanged
+      || isLegacy || JSON.stringify(next) !== JSON.stringify(candidate);
+    if (semanticChanged || !validationValid || !readinessValid) {
+      next.ready_for_implementation = false;
+      next.validation = { status: 'not-run', semantic_review: semanticReviewNotRun() };
+      next.semantic_model = null;
+    }
+    const changed = JSON.stringify(next) !== JSON.stringify(candidate);
+    if (changed) next.updated_at = evidence.timestamp;
+    preflightSpec21Candidate(next, evidence);
+    return { ok: true, spec: next, changed };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function validateDependencyCycles(taskFiles, registry) {
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(taskPath, stack = []) {
+    if (visiting.has(taskPath)) {
+      const start = stack.indexOf(taskPath);
+      failPrecondition(`task_registry.dependencies contains a cycle: ${stack.slice(start).concat(taskPath).join(' -> ')}`);
+    }
+    if (visited.has(taskPath)) return;
+    visiting.add(taskPath);
+    for (const dependency of registry[taskPath].dependencies) visit(dependency, [...stack, taskPath]);
+    visiting.delete(taskPath);
+    visited.add(taskPath);
+  }
+  for (const taskPath of taskFiles) visit(taskPath);
+}
+
+function listExistingTaskFiles(workRoot, specDir) {
+  const tasksDir = path.join(specDir, 'tasks');
+  assertNoSymlinkPath(workRoot, tasksDir, 'tasks directory');
+  if (!fs.existsSync(tasksDir)) return [];
+  assertExistingDirectory(workRoot, tasksDir, 'tasks directory');
+  const files = [];
+  for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+    const fullPath = path.join(tasksDir, entry.name);
+    if (entry.isSymbolicLink()) failPrecondition(`tasks entry cannot be a symlink: ${fullPath}`);
+    if (!entry.isFile()) failPrecondition(`tasks entry must be a regular file: ${fullPath}`);
+    const relative = `tasks/${entry.name}`;
+    parseTaskPath(relative, `tasks entry ${relative}`);
+    files.push(relative);
+  }
+  return files.sort();
+}
+
+function readPersistedPolicy(spec) {
+  if (hasOwn(spec, 'override_receipt')) {
+    if (spec.override_receipt !== null) {
+      failPrecondition('existing top-level override_receipt is unsupported; omit the field');
+    }
+    if (spec.schema_version !== '2.0') {
+      failPrecondition('top-level override_receipt is only readable as inert null during schema 2.0 migration; omit the field');
+    }
+  }
+  if (!hasOwn(spec, 'workflow_policy')) {
+    const legacy = spec.design_context?.execution_tier;
+    failPrecondition(
+      legacy
+        ? 'existing spec has no persisted workflow_policy; design_context.execution_tier is read-only and cannot create policy'
+        : 'existing spec must contain a persisted workflow_policy snapshot',
+    );
+  }
+  if (isPlainObject(spec.workflow_policy)
+    && hasOwn(spec.workflow_policy, 'override_receipt')
+    && spec.workflow_policy.override_receipt !== null) {
+    failPrecondition('existing workflow_policy.override_receipt is unsupported; omit the field');
+  }
+  try {
+    return POLICY.readWorkflowPolicySnapshot(spec);
+  } catch (error) {
+    failPrecondition(`existing workflow_policy is invalid (${error.message})`);
+  }
+}
+
+function validateResearchTopology(workRoot, specDir, spec, needsResearch) {
+  const canonical = 'research.md';
+  if (hasOwn(spec, 'research') && spec.research !== null) {
+    const pointer = isPlainObject(spec.research) ? spec.research.path : spec.research;
+    if (typeof pointer !== 'string') failPrecondition('spec.research must be null, a safe relative path, or an object with a path');
+    const safePointer = safeRelativePath(pointer, 'spec.research');
+    const pointerPath = path.resolve(specDir, safePointer);
+    assertNoSymlinkPath(workRoot, pointerPath, 'spec.research path');
+    if (!isWithin(specDir, pointerPath)) failPrecondition('spec.research path must stay inside the spec directory');
+    if (needsResearch && safePointer !== canonical) {
+      failPrecondition('spec.research path must be research.md for an explicit --research request');
+    }
+    assertRegularFileOrMissing(workRoot, pointerPath, 'spec.research path');
+  }
+  const researchPath = path.join(specDir, canonical);
+  assertRegularFileOrMissing(workRoot, researchPath, 'research.md');
+  return researchPath;
+}
+
+function inspectTaskTopology(workRoot, specDir, spec, parsed, artifactDeclarations) {
+  const hasTaskFiles = hasOwn(spec, 'task_files');
+  const hasRegistry = hasOwn(spec, 'task_registry');
+  if (hasTaskFiles !== hasRegistry) failPrecondition('task_files and task_registry must be present together');
+
+  const declared = hasTaskFiles ? validateTaskPathList(spec.task_files, 'task_files') : [];
+  const registry = hasRegistry ? spec.task_registry : {};
+  if (hasRegistry && !isPlainObject(registry)) failPrecondition('task_registry must be an object keyed by task file path');
+  const declaredSet = new Set(declared);
+  if (hasRegistry) {
+    const registryIds = new Set();
+    for (const taskPath of Object.keys(registry)) {
+      parseTaskPath(taskPath, `task_registry key ${taskPath}`);
+      if (!declaredSet.has(taskPath)) failPrecondition(`task_registry has an unregistered entry ${taskPath}`);
+      validateRegistryEntry(taskPath, registry[taskPath], declaredSet);
+      if (registryIds.has(registry[taskPath].id)) failPrecondition(`task_registry contains duplicate task id ${registry[taskPath].id}`);
+      registryIds.add(registry[taskPath].id);
+    }
+    for (const taskPath of declared) {
+      if (!hasOwn(registry, taskPath)) failPrecondition(`task_registry is missing entry ${taskPath}`);
+    }
+    validateDependencyCycles(declared, registry);
+  }
+
+  const existing = listExistingTaskFiles(workRoot, specDir);
+  const existingSet = new Set(existing);
+  if (!hasTaskFiles && existing.length > 0) failPrecondition('tasks directory contains files but task_files/task_registry are absent');
+  for (const taskPath of existing) {
+    if (!declaredSet.has(taskPath)) failPrecondition(`task_files is missing existing task file ${taskPath}`);
+  }
+  const requested = new Set(parsed.map((task) => task.file));
+  for (const taskPath of declared) {
+    if (!existingSet.has(taskPath)) failPrecondition(`task_files declares missing task file ${taskPath}`);
+  }
+
+  for (const task of parsed) {
+    if (!existingSet.has(task.file)) continue;
+    const entry = registry[task.file];
+    const expected = registryEntry(task, artifactDeclarations);
+    if (entry.id !== expected.id || entry.title !== expected.title) {
+      failPrecondition(`conflicting duplicate task ${task.raw}: existing registry entry differs`);
+    }
+    if (artifactDeclarations.has(task.file)) {
+      if (!hasOwn(entry, 'artifacts') || JSON.stringify(entry.artifacts) !== JSON.stringify(expected.artifacts)) {
+        failPrecondition(`conflicting duplicate task ${task.raw}: existing registry artifacts differ`);
+      }
+    }
+  }
+
+  return {
+    declared,
+    registry,
+    existing,
+    existingSet,
+    requested,
+    hasTaskTopology: hasTaskFiles,
+  };
+}
+
+function captureTarget(workRoot, specDir, relativePath) {
+  const target = path.join(specDir, relativePath);
+  assertNoSymlinkPath(workRoot, target, `target ${relativePath}`);
+  try {
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile()) failPrecondition(`target ${relativePath} must be a regular file`);
+    return { exists: true, bytes: fs.readFileSync(target) };
+  } catch (error) {
+    if (error instanceof ScaffoldPreconditionError) throw error;
+    if (error.code !== 'ENOENT') failPrecondition(`target ${relativePath} cannot be inspected (${error.message})`);
+    return { exists: false, bytes: null };
+  }
+}
+
+function parseFailureInjection() {
+  const raw = process.env.CAFEKIT_SCAFFOLD_FAIL_AFTER_WRITES;
+  if (raw === undefined) return null;
+  if (!/^[1-9]\d*$/.test(raw)) failPrecondition('CAFEKIT_SCAFFOLD_FAIL_AFTER_WRITES must be a positive integer');
+  return Number(raw);
+}
+
+function parseCrashInjection() {
+  const raw = process.env.CAFEKIT_SCAFFOLD_KILL_AFTER_RENAMES;
+  if (raw === undefined) return null;
+  if (!/^[1-9]\d*$/.test(raw)) {
+    failPrecondition('CAFEKIT_SCAFFOLD_KILL_AFTER_RENAMES must be a positive integer');
+  }
+  return Number(raw);
+}
+
+function digest(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function fsyncPath(filePath) {
+  const fd = fs.openSync(filePath, 'r');
+  try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+
+function fsyncDirectory(directory) {
+  try { fsyncPath(directory); } catch (error) {
+    if (!['EINVAL', 'ENOTSUP', 'EISDIR'].includes(error.code)) throw error;
+  }
+}
+
+function fileDigestOrNull(filePath) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile()) throw new Error(`transaction path is not a regular file: ${filePath}`);
+    return digest(fs.readFileSync(filePath));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function processIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid) return pid === process.pid;
+  try { process.kill(pid, 0); return true; } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+function validateTransactionManifest(workRoot, transactionDir, manifest) {
+  if (!isPlainObject(manifest) || manifest.format !== TRANSACTION_FORMAT) {
+    throw new Error(`unrecognized scaffold transaction manifest: ${transactionDir}`);
+  }
+  const transactionId = path.basename(transactionDir).slice(TRANSACTION_PREFIX.length);
+  if (manifest.transaction_id !== transactionId || !/^[a-f0-9-]{20,}$/i.test(transactionId)) {
+    throw new Error(`scaffold transaction identity mismatch: ${transactionDir}`);
+  }
+  if (path.resolve(manifest.work_root || '') !== workRoot) {
+    throw new Error(`scaffold transaction work root mismatch: ${transactionDir}`);
+  }
+  const specRelative = safeRelativePath(manifest.spec_dir, 'transaction spec_dir');
+  const specDir = path.resolve(workRoot, specRelative);
+  if (!isWithin(workRoot, specDir) || !Array.isArray(manifest.entries) || manifest.entries.length === 0) {
+    throw new Error(`invalid scaffold transaction topology: ${transactionDir}`);
+  }
+  const seen = new Set();
+  for (const entry of manifest.entries) {
+    if (!isPlainObject(entry)) throw new Error(`invalid scaffold transaction entry: ${transactionDir}`);
+    const relativePath = safeRelativePath(entry.path, 'transaction entry path');
+    if (seen.has(relativePath)) throw new Error(`duplicate scaffold transaction path: ${relativePath}`);
+    seen.add(relativePath);
+    if (!isPlainObject(entry.before) || typeof entry.before.exists !== 'boolean'
+      || (entry.before.exists && !/^[a-f0-9]{64}$/.test(entry.before.digest || ''))
+      || !/^[a-f0-9]{64}$/.test(entry.after_digest || '')) {
+      throw new Error(`invalid scaffold transaction digest evidence: ${relativePath}`);
+    }
+  }
+  return { ...manifest, specDir };
+}
+
+function removeEmptyTransactionParents(specDir, target) {
+  let current = path.dirname(target);
+  while (isWithin(specDir, current) && current !== path.dirname(specDir)) {
+    try { fs.rmdirSync(current); } catch (error) {
+      if (error.code === 'ENOENT') break;
+      if (['ENOTEMPTY', 'EEXIST'].includes(error.code)) break;
+      throw error;
+    }
+    if (current === specDir) break;
+    current = path.dirname(current);
+  }
+}
+
+function recoverTransaction(workRoot, transactionDir, rawManifest) {
+  const manifest = validateTransactionManifest(workRoot, transactionDir, rawManifest);
+  if (processIsAlive(manifest.pid)) return false;
+  for (let index = manifest.entries.length - 1; index >= 0; index -= 1) {
+    const entry = manifest.entries[index];
+    const target = path.join(manifest.specDir, entry.path);
+    const backup = path.join(transactionDir, 'backup', entry.path);
+    const targetDigest = fileDigestOrNull(target);
+    const backupDigest = fileDigestOrNull(backup);
+    if (entry.before.exists) {
+      if (backupDigest !== null && backupDigest !== entry.before.digest) {
+        throw new Error(`recovery cannot prove backup ownership for ${entry.path}`);
+      }
+      if (targetDigest === entry.after_digest) {
+        removeTarget(target);
+      } else if (targetDigest !== null && targetDigest !== entry.before.digest) {
+        throw new Error(`recovery refuses to overwrite unowned target ${entry.path}`);
+      }
+      if (fileDigestOrNull(target) === null) {
+        if (backupDigest !== entry.before.digest) {
+          throw new Error(`recovery is missing the owned backup for ${entry.path}`);
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.renameSync(backup, target);
+      }
+    } else if (targetDigest === entry.after_digest) {
+      removeTarget(target);
+    } else if (targetDigest !== null) {
+      throw new Error(`recovery refuses to delete unowned target ${entry.path}`);
+    }
+    removeEmptyTransactionParents(manifest.specDir, target);
+  }
+  fs.rmSync(transactionDir, { recursive: true, force: true });
+  fsyncDirectory(workRoot);
+  return true;
+}
+
+function recoverTransactions(workRoot) {
+  let recovered = 0;
+  for (const entry of fs.readdirSync(workRoot, { withFileTypes: true })) {
+    if (!entry.name.startsWith(TRANSACTION_PREFIX)) continue;
+    const transactionDir = path.join(workRoot, entry.name);
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      failPrecondition(`scaffold transaction identity is not a directory: ${transactionDir}`);
+    }
+    const manifestPath = path.join(transactionDir, 'manifest.json');
+    let manifest;
+    try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); } catch (error) {
+      failPrecondition(`scaffold transaction cannot be recovered (${error.message}): ${transactionDir}`);
+    }
+    try {
+      if (recoverTransaction(workRoot, transactionDir, manifest)) recovered += 1;
+    } catch (error) {
+      failPrecondition(`scaffold transaction recovery stopped safely (${error.message})`);
+    }
+  }
+  return recovered;
+}
+
+function prepareTransaction(workRoot, specDir, changes, snapshots, transactionRoot, createSpecDir) {
+  assertExistingDirectory(workRoot, transactionRoot, 'scaffold transaction directory');
+  const transactionId = crypto.randomUUID();
+  const transactionDir = path.join(transactionRoot, `${TRANSACTION_PREFIX}${transactionId}`);
+  const stageDir = path.join(transactionDir, 'stage');
+  const backupDir = path.join(transactionDir, 'backup');
+  fs.mkdirSync(stageDir, { recursive: true });
+  fs.mkdirSync(backupDir);
+  const entries = [];
+  try {
+    for (const change of changes) {
+      safeRelativePath(change.path, `staged path ${change.path}`);
+      const staged = path.join(stageDir, change.path);
+      fs.mkdirSync(path.dirname(staged), { recursive: true });
+      fs.writeFileSync(staged, change.body, { encoding: 'utf8', flag: 'wx' });
+      fsyncPath(staged);
+      const before = snapshots.get(change.path);
+      entries.push({
+        path: change.path,
+        before: { exists: before.exists, ...(before.exists ? { digest: digest(before.bytes) } : {}) },
+        after_digest: digest(Buffer.from(change.body, 'utf8')),
+      });
+    }
+    const manifest = {
+      format: TRANSACTION_FORMAT,
+      transaction_id: transactionId,
+      pid: process.pid,
+      work_root: workRoot,
+      spec_dir: path.relative(workRoot, specDir),
+      create_spec_dir: createSpecDir,
+      entries,
+    };
+    const manifestPath = path.join(transactionDir, 'manifest.json');
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+    fsyncPath(manifestPath);
+    fsyncDirectory(transactionDir);
+    fsyncDirectory(transactionRoot);
+    return { transactionDir, stageDir, backupDir, manifest };
+  } catch (error) {
+    fs.rmSync(transactionDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function ensureTargetParent(workRoot, specDir, relativePath, createdDirs) {
+  const parent = path.dirname(relativePath);
+  if (parent === '.') return;
+  let current = specDir;
+  for (const segment of parent.split(path.sep)) {
+    current = path.join(current, segment);
+    assertNoSymlinkPath(workRoot, current, `target parent ${current}`);
+    if (fs.existsSync(current)) {
+      assertExistingDirectory(workRoot, current, `target parent ${current}`);
+    } else {
+      fs.mkdirSync(current);
+      createdDirs.push(current);
+    }
+  }
+}
+
+function ensureDirectoryTree(workRoot, directory, createdDirs, label) {
+  assertNoSymlinkPath(workRoot, directory, label);
+  const relative = path.relative(path.resolve(workRoot), path.resolve(directory));
+  let current = path.resolve(workRoot);
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (fs.existsSync(current)) {
+      assertExistingDirectory(workRoot, current, label);
+    } else {
+      fs.mkdirSync(current);
+      createdDirs.push(current);
+    }
+  }
+}
+
+function removeTarget(target) {
+  try {
+    const stat = fs.lstatSync(target);
+    if (stat.isDirectory()) throw new Error(`rollback target is a directory: ${target}`);
+    fs.unlinkSync(target);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
+function commitChanges(
+  workRoot,
+  specDir,
+  changes,
+  snapshots,
+  failureAfter,
+  { createSpecDir = false, afterApply = null, transactionRoot = path.dirname(specDir) } = {},
+) {
+  const transaction = prepareTransaction(
+    workRoot, specDir, changes, snapshots, transactionRoot, createSpecDir,
+  );
+  const createdDirs = [];
+  let writes = 0;
+  let renames = 0;
+  const crashAfter = parseCrashInjection();
+  const renameBoundary = (from, to) => {
+    fs.renameSync(from, to);
+    renames += 1;
+    fsyncDirectory(path.dirname(to));
+    if (crashAfter !== null && renames >= crashAfter) process.kill(process.pid, 'SIGKILL');
+  };
+  try {
+    if (createSpecDir) {
+      if (fs.existsSync(specDir)) failPrecondition(`spec dir already exists: ${specDir}`);
+      ensureDirectoryTree(workRoot, specDir, createdDirs, 'spec directory');
+    }
+    for (const change of changes) {
+      const target = path.join(specDir, change.path);
+      const before = captureTarget(workRoot, specDir, change.path);
+      const expected = snapshots.get(change.path);
+      if (before.exists !== expected.exists || (before.exists && !before.bytes.equals(expected.bytes))) {
+        failPrecondition(`target changed during preflight: ${change.path}`);
+      }
+      ensureTargetParent(workRoot, specDir, change.path, createdDirs);
+      const backup = path.join(transaction.backupDir, change.path);
+      if (before.exists) {
+        fs.mkdirSync(path.dirname(backup), { recursive: true });
+        renameBoundary(target, backup);
+      }
+      renameBoundary(path.join(transaction.stageDir, change.path), target);
+      writes += 1;
+      if (failureAfter !== null && writes >= failureAfter) {
+        throw new Error(`injected failure after ${writes} staged write(s)`);
+      }
+    }
+    if (typeof afterApply === 'function') afterApply();
+  } catch (error) {
+    let rollbackError = null;
+    try {
+      const manifest = { ...transaction.manifest, pid: -1 };
+      recoverTransaction(workRoot, transaction.transactionDir, manifest);
+    } catch (rollbackFailure) {
+      rollbackError = rollbackFailure;
+    }
+    if (rollbackError) throw new Error(`${error.message}; rollback failed: ${rollbackError.message}`);
+    throw new Error(`${error.message}; transaction rolled back`);
+  }
+  fs.rmSync(transaction.transactionDir, { recursive: true, force: true });
+  fsyncDirectory(transactionRoot);
+}
+
+function scaffoldTasksOnly({ args, specDir, specPath, spec, persistedPolicy, parsed, artifactDeclarations, taskTpl, ts }) {
+  const workRoot = path.resolve(process.cwd());
+  assertExistingDirectory(workRoot, specDir, 'spec directory');
+  assertRegularFileOrMissing(workRoot, specPath, 'spec.json');
+  const requirementsPath = path.join(specDir, 'requirements.md');
+  const designPath = path.join(specDir, 'design.md');
+  assertRegularFileOrMissing(workRoot, requirementsPath, 'requirements.md');
+  assertRegularFileOrMissing(workRoot, designPath, 'design.md');
+  const topology = inspectTaskTopology(workRoot, specDir, spec, parsed, artifactDeclarations);
+  const allTaskFiles = [...new Set([...topology.declared, ...parsed.map((task) => task.file)])].sort();
+  if (args.taskTriggers !== null || args.coordination || args.dependencies !== null || args.artifacts !== null) {
+    failPrecondition('schema 2.1 mutation uses --boundaries as the only topology authority');
+  }
+  const boundaries = parseBoundaryDeclarations(args.boundaries, allTaskFiles);
+  if (boundaries.length === 0) {
+    failPrecondition('--tasks-only requires a complete non-empty --boundaries array for the resulting task bundle');
+  }
+  const dependencyDeclarations = dependenciesFromBoundaries(boundaries, allTaskFiles);
+  const phases = args.phases === null && Array.isArray(spec.coordination?.phases)
+    ? cloneJson(spec.coordination.phases)
+    : parsePhaseDeclarations(args.phases, allTaskFiles);
+  validatePhaseBoundaryRefs(phases, boundaries);
+  for (const task of parsed) {
+    if (!topology.existingSet.has(task.file) || !dependencyDeclarations.has(task.file)) continue;
+    const existing = topology.registry[task.file].dependencies;
+    const requested = dependencyDeclarations.get(task.file);
+    if (JSON.stringify(existing) !== JSON.stringify(requested)) {
+      failPrecondition(`conflicting duplicate task ${task.raw}: existing registry dependencies differ`);
+    }
+  }
+
+  let nextPolicy = POLICY.canonicalWorkflowPolicySnapshot(spec);
+  if (args.risks && args.risks.length > 0) {
+    try {
+      nextPolicy = POLICY.escalateWorkflowPolicy(nextPolicy, { risks: args.risks });
+    } catch (error) {
+      failPrecondition(`--tasks-only cannot escalate workflow policy (${error.message})`);
+    }
+    const validation = POLICY.validateWorkflowPolicySnapshot(nextPolicy);
+    if (!validation.valid) failPrecondition(`--tasks-only escalation produced an invalid workflow_policy (${validation.errors.join('; ')})`);
+  }
+
+  const needsResearch = args.research === true;
+  const researchPath = validateResearchTopology(workRoot, specDir, spec, needsResearch);
+  const researchExists = fs.existsSync(researchPath);
+  const researchTemplate = needsResearch && !researchExists
+    ? renderResearchTemplate(args.feature, args.uncertainty)
+    : null;
+  const newTasks = parsed.filter((task) => !topology.existingSet.has(task.file));
+  const nextSpec = cloneJson(spec);
+  if (!topology.hasTaskTopology && newTasks.length > 0) {
+    nextSpec.task_files = [];
+    nextSpec.task_registry = {};
+  }
+  for (const task of newTasks) {
+    nextSpec.task_files.push(task.file);
+    nextSpec.task_registry[task.file] = registryEntry(
+      task,
+      artifactDeclarations,
+      dependencyDeclarations.get(task.file) || [],
+    );
+  }
+  if (needsResearch && nextSpec.research !== 'research.md') {
+    nextSpec.research = 'research.md';
+  }
+  nextSpec.task_files.sort();
+  const normalized = normalizeSpec21Candidate(nextSpec, {
+    featureName: args.feature,
+    timestamp: ts,
+    requirementsExists: fs.existsSync(requirementsPath),
+    designExists: fs.existsSync(designPath),
+    researchExists: researchExists || researchTemplate !== null,
+    researchChanged: researchTemplate !== null,
+    taskFiles: allTaskFiles,
+    tasksChanged: newTasks.length > 0,
+    coordination: { boundaries, ...(phases.length > 0 ? { phases } : {}) },
+    workflowPolicy: nextPolicy,
+  });
+  if (!normalized.ok) failPrecondition(`schema 2.1 migration rejected candidate (${normalized.error})`);
+  const normalizedSpec = normalized.spec;
+  const specChanged = JSON.stringify(normalizedSpec) !== JSON.stringify(spec);
+  if (specChanged && normalizedSpec.updated_at === spec.created_at && ts !== spec.created_at) {
+    failPrecondition('schema 2.1 migration produced a stale updated_at timestamp');
+  }
+
+  const changes = newTasks.map((task) => ({
+    path: task.file,
+    body: fillTask(
+      taskTpl,
+      task,
+      args.feature,
+      dependencyDeclarations.get(task.file) || [],
+      taskHasDeclaredImplementationObligation(normalizedSpec, task.file),
+    ),
+  }));
+  if (researchTemplate !== null) changes.push({ path: 'research.md', body: researchTemplate });
+  if (specChanged) changes.push({ path: 'spec.json', body: `${JSON.stringify(normalizedSpec, null, 2)}\n` });
+  if (changes.length === 0) return { createdTasks: [], researchCreated: false };
+
+  const expectedAbsent = new Set(newTasks.map((task) => task.file));
+  if (researchTemplate !== null) expectedAbsent.add('research.md');
+  const snapshots = new Map();
+  for (const change of changes) {
+    const snapshot = captureTarget(workRoot, specDir, change.path);
+    if (expectedAbsent.has(change.path) && snapshot.exists) {
+      failPrecondition(`target appeared after preflight: ${change.path}`);
+    }
+    snapshots.set(change.path, snapshot);
+  }
+  commitChanges(workRoot, specDir, changes, snapshots, parseFailureInjection(), {
+    transactionRoot: workRoot,
+    afterApply: () => observeInstalledPolicyBaseline({ args, specDir, spec: normalizedSpec }),
+  });
+  return { createdTasks: newTasks.map((task) => task.file), researchCreated: researchTemplate !== null };
+}
+
+function syncSemanticModel({ workRoot, args, specDir, ts }) {
+  assertExistingDirectory(workRoot, specDir, 'spec directory');
+  const specPath = path.join(specDir, 'spec.json');
+  assertRegularFileOrMissing(workRoot, specPath, 'spec.json');
+  if (!fs.existsSync(specPath)) failPrecondition('--sync-semantic-model requires an existing spec.json');
+  let spec;
+  try { spec = JSON.parse(fs.readFileSync(specPath, 'utf8')); }
+  catch (error) { failPrecondition(`--sync-semantic-model spec.json is invalid JSON (${error.message})`); }
+  if (!isPlainObject(spec) || spec.schema_version !== '2.1') failPrecondition('--sync-semantic-model accepts canonical schema 2.1 only');
+  assertCanonicalSpecInputClosedWorld(spec);
+  const projection = SEMANTIC.modelFromMarkdown(specDir, spec);
+  if (projection.errors.length) failPrecondition(`semantic projection is invalid (${projection.errors.join('; ')})`);
+  const modelUnchanged = SEMANTIC.stableJson(spec.semantic_model) === SEMANTIC.stableJson(projection.model);
+  if (modelUnchanged) {
+    console.log(`SEMANTIC_MODEL_UNCHANGED ${path.relative(process.cwd(), specDir) || specDir}`);
+    return;
+  }
+  const next = cloneJson(spec);
+  next.semantic_model = projection.model;
+  next.updated_at = ts;
+  next.ready_for_implementation = false;
+  next.validation = { status: 'not-run', semantic_review: semanticReviewNotRun() };
+  preflightSpec21Candidate(next, {
+    featureName: args.feature,
+    requirementsExists: fs.existsSync(path.join(specDir, 'requirements.md')),
+    designExists: fs.existsSync(path.join(specDir, 'design.md')),
+    researchExists: fs.existsSync(path.join(specDir, 'research.md')),
+    taskFiles: listExistingTaskFiles(workRoot, specDir),
+  });
+  const snapshot = captureTarget(workRoot, specDir, 'spec.json');
+  commitChanges(
+    workRoot,
+    specDir,
+    [{ path: 'spec.json', body: `${JSON.stringify(next, null, 2)}\n` }],
+    new Map([['spec.json', snapshot]]),
+    parseFailureInjection(),
+    { transactionRoot: workRoot },
+  );
+  console.log(`SEMANTIC_MODEL_SYNCED ${path.relative(process.cwd(), specDir) || specDir}`);
+}
+
 function main() {
+  const workRoot = path.resolve(process.cwd());
+  const recoveredTransactions = recoverTransactions(workRoot);
+  if (recoveredTransactions > 0) {
+    console.error(`recovered ${recoveredTransactions} interrupted scaffold transaction(s)`);
+  }
   const args = parseArgs(process.argv);
-  if (!args.feature || !args.tasks) { usage(); process.exit(2); }
+  if (args.syncSemanticModel) {
+    if (!args.feature || args.tasks !== null || args.tasksOnly || args.boundaries !== null || args.research
+      || args.planningDepth || args.assuranceLevel || args.lane) {
+      failPrecondition('--sync-semantic-model is an isolated explicit promotion mode and cannot be combined with authoring mutations');
+    }
+    safeRelativePath(args.specsRoot, '--specs-root');
+    safeRelativePath(args.feature, 'feature');
+    const specDir = path.resolve(workRoot, args.specsRoot, args.feature);
+    if (!isWithin(workRoot, specDir)) failPrecondition(`spec directory escapes the work root: ${specDir}`);
+    syncSemanticModel({ workRoot, args, specDir, ts: nowIso() });
+    return;
+  }
+  if (!args.feature || (args.tasks === null && args.tasksOnly) || (args.coordination && !args.tasks)) {
+    usage();
+    failPrecondition('missing feature or required task arguments');
+  }
+  if (args.research && !concreteUncertainty(args.uncertainty)) {
+    failPrecondition('--research requires --uncertainty with one concrete unresolved question (at least 12 trimmed characters)');
+  }
+  if (!args.research && args.uncertainty !== null) {
+    failPrecondition('--uncertainty is only valid with --research');
+  }
+  if (typeof args.lane === 'string' && args.lane.toLowerCase() === 'direct') {
+    failPrecondition('Direct lane does not create a spec; run targeted verification from the Direct workflow instead');
+  }
+  if (args.lane && !POLICY.LANES.includes(args.lane)) {
+    failPrecondition(`--lane must be one of ${POLICY.LANES.join(', ')}`);
+  }
+  if (args.planningDepth && !POLICY.PLANNING_DEPTHS.includes(args.planningDepth)) {
+    failPrecondition(`--planning-depth must be one of ${POLICY.PLANNING_DEPTHS.join(', ')}`);
+  }
+  if (args.planningDepth === 'None') {
+    failPrecondition('None planning depth does not create a durable spec; use the Direct workflow instead');
+  }
+  if (args.assuranceLevel && !POLICY.ASSURANCE_LEVELS.includes(args.assuranceLevel)) {
+    failPrecondition(`--assurance-level must be one of ${POLICY.ASSURANCE_LEVELS.join(', ')}`);
+  }
+  if (args.lane && (args.planningDepth || args.assuranceLevel)) {
+    failPrecondition('--lane is a compatibility adapter and cannot be combined with Specs v2 axis flags');
+  }
 
-  const ids = args.tasks.split(',').map((s) => s.trim()).filter(Boolean);
+  const ids = (args.tasks || '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (args.tasksOnly && ids.length === 0) {
+    failPrecondition('--tasks-only requires at least one task id');
+  }
   const parsed = [];
+  const seenIds = new Set();
   for (const id of ids) {
     const m = id.match(TASK_ID_RE);
     if (!m) {
-      console.error(`precondition: invalid task id "${id}" (want R{N}-{SEQ}-<slug>, SEQ 2 digits)`);
-      process.exit(2);
+      failPrecondition(`invalid task id "${id}" (want R{N}-{SEQ}-<slug>, SEQ 2 digits)`);
     }
+    const logicalId = `R${m[1]}-${m[2]}`;
+    if (seenIds.has(logicalId)) failPrecondition(`duplicate task id "${logicalId}"`);
+    seenIds.add(logicalId);
     parsed.push({ raw: id, req: m[1], seq: m[2], slug: m[3], file: `tasks/task-${id}.md` });
   }
+  if (args.phases !== null && parsed.length === 0) {
+    failPrecondition('--phases requires --tasks because phase grouping needs a task graph');
+  }
+  if (args.phases !== null && args.planningDepth !== 'Full') {
+    failPrecondition('--phases requires explicit --planning-depth Full before any scaffold writes');
+  }
+  const artifactDeclarations = parseArtifactDeclarations(args.artifacts, parsed);
+  if (args.taskTriggers !== null || args.coordination || args.dependencies !== null || args.artifacts !== null) {
+    failPrecondition('schema 2.1 authoring uses --boundaries as the only topology authority; task triggers, coordination markers, dependencies, and artifact maps are read compatibility only');
+  }
+  const boundaries = args.tasksOnly ? null : parseBoundaryDeclarations(
+    args.boundaries,
+    parsed.map((task) => task.file).sort(),
+  );
+  const dependencyDeclarations = args.tasksOnly
+    ? null
+    : dependenciesFromBoundaries(boundaries, parsed.map((task) => task.file).sort());
+  const riskNames = parseRiskNames(args.risks);
+  const phases = args.tasksOnly
+    ? []
+    : parsePhaseDeclarations(args.phases, parsed.map((task) => task.file));
+  if (!args.tasksOnly) validatePhaseBoundaryRefs(phases, boundaries);
 
+  safeRelativePath(args.specsRoot, '--specs-root');
+  safeRelativePath(args.feature, 'feature');
+  if (!FEATURE_NAME_RE.test(args.feature)) {
+    failPrecondition('feature must be one safe path segment starting with an alphanumeric character');
+  }
   const specDir = path.resolve(process.cwd(), args.specsRoot, args.feature);
+  if (!isWithin(workRoot, specDir)) failPrecondition(`spec directory escapes the work root: ${specDir}`);
+  assertNoSymlinkPath(workRoot, specDir, 'spec directory');
   const taskTpl = readTemplate('task.md');
   const ts = nowIso();
   const created = [];
@@ -114,74 +1909,169 @@ function main() {
   // --- --tasks-only: add task stubs + merge registry into an existing spec ---
   if (args.tasksOnly) {
     const specPath = path.join(specDir, 'spec.json');
-    if (!fs.existsSync(specPath)) {
-      console.error(`precondition: --tasks-only needs an existing spec.json at ${specPath}`);
-      process.exit(2);
-    }
-    const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
-    spec.task_files = spec.task_files || [];
-    spec.task_registry = spec.task_registry || {};
-    fs.mkdirSync(path.join(specDir, 'tasks'), { recursive: true });
-    for (const t of parsed) {
-      const abs = path.join(specDir, t.file);
-      if (fs.existsSync(abs)) continue; // never overwrite an already-filled task
-      fs.writeFileSync(abs, fillTask(taskTpl, t, args.feature));
-      if (!spec.task_files.includes(t.file)) spec.task_files.push(t.file);
-      spec.task_registry[t.file] = registryEntry(t);
-      created.push(t.file);
-    }
-    spec.task_files.sort();
-    spec.updated_at = ts;
-    fs.writeFileSync(specPath, JSON.stringify(spec, null, 2) + '\n');
+    assertNoSymlinkPath(workRoot, specPath, 'spec.json');
+    if (!fs.existsSync(specPath)) failPrecondition(`--tasks-only needs an existing spec.json at ${specPath}`);
+    let spec;
+    try {
+      spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+    } catch (error) {
+      failPrecondition(`--tasks-only existing spec.json is invalid JSON (${error.message})`);
+    }
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+      failPrecondition('--tasks-only existing spec.json must contain a JSON object');
+    }
+    assertCanonicalSpecInputClosedWorld(spec);
+    if (spec.schema_version === '2.0') assertLegacyMigrationClosedWorld(spec);
+    const persistedPolicy = readPersistedPolicy(spec);
+    if (args.planningDepth && args.planningDepth !== persistedPolicy.planning_depth) {
+      failPrecondition(`--tasks-only --planning-depth ${args.planningDepth} does not match persisted workflow_policy.planning_depth ${persistedPolicy.planning_depth}`);
+    }
+    if (args.lane && args.lane !== persistedPolicy.lane) {
+      failPrecondition(`--tasks-only --lane ${args.lane} does not match persisted workflow_policy.lane ${persistedPolicy.lane}; omit --lane or use the persisted lane (downgrade is not allowed)`);
+    }
+    const result = scaffoldTasksOnly({
+      args: { ...args, risks: riskNames },
+      specDir,
+      specPath,
+      spec,
+      persistedPolicy,
+      parsed,
+      artifactDeclarations,
+      taskTpl,
+      ts,
+    });
+    const createdTasks = result.createdTasks;
     const relTo = path.relative(process.cwd(), specDir) || specDir;
     console.log(`SCAFFOLDED (tasks-only) ${relTo}`);
-    console.log(`- ${created.length} new task stub(s); task_files + task_registry merged.`);
+    console.log(`- ${createdTasks.length} new task stub(s); task_files + task_registry merged.`);
+    if (result.researchCreated) console.log('- research.md created by explicit --research request.');
     console.log(`- NEXT: Edit-fill {{...}} in each stub; set dependencies; run validator + spec-ground.`);
     return;
   }
 
+  const policyInput = args.lane
+    ? { risks: riskNames, override: args.lane }
+    : {
+      risks: riskNames,
+      ...(args.planningDepth ? { planning_depth: args.planningDepth } : {}),
+      ...(args.assuranceLevel ? { assurance_level: args.assuranceLevel } : {}),
+    };
+  let selectedPolicy;
+  try {
+    selectedPolicy = POLICY.workflowPolicySnapshot(policyInput);
+  } catch (error) {
+    failPrecondition(error.message);
+  }
+  if (parsed.length > 0 && boundaries.length === 0) {
+    failPrecondition('physical task bundle requires at least one typed coordination.boundaries entry with semantic evidence');
+  }
+  if (parsed.length === 0 && args.boundaries !== null) {
+    failPrecondition('--boundaries requires --tasks');
+  }
   if (fs.existsSync(specDir)) {
     console.error(`precondition: spec dir already exists, refusing to overwrite: ${specDir}`);
     process.exit(2);
   }
 
-  fs.mkdirSync(path.join(specDir, 'tasks'), { recursive: true });
-  fs.mkdirSync(path.join(specDir, 'reports'), { recursive: true });
-
   // --- spec.json (from spec-state.json template) ---
   const spec = JSON.parse(readTemplate('spec-state.json'));
   spec.feature_name = args.feature;
   spec.created_at = ts;
   spec.updated_at = ts;
   spec.language = args.lang;
-  spec.timestamps = spec.timestamps || {};
-  spec.timestamps.init = ts;
   spec.scope_lock = spec.scope_lock || {};
   spec.scope_lock.source = args.title || `{{PROJECT_DESCRIPTION}}`;
-  spec.task_files = parsed.map((t) => t.file);
-  spec.task_registry = {};
-  for (const t of parsed) spec.task_registry[t.file] = registryEntry(t);
-  fs.writeFileSync(path.join(specDir, 'spec.json'), JSON.stringify(spec, null, 2) + '\n');
+  delete spec.workflow_policy;
+  delete spec.override_receipt;
+  Object.assign(spec, POLICY.persistWorkflowPolicySnapshot(spec, policyInput));
+  spec.validation = isPlainObject(spec.validation) ? spec.validation : {};
+  spec.validation.semantic_review = semanticReviewNotRun();
+  if (args.research) {
+    spec.research = 'research.md';
+    spec.authoring.research = 'draft';
+  }
+  spec.coordination = {
+    boundaries,
+    ...(phases.length > 0 ? { phases } : {}),
+  };
+  if (parsed.length > 0) {
+    spec.authoring.tasks = 'draft';
+    spec.task_files = parsed.map((t) => t.file);
+    spec.task_registry = {};
+    for (const t of parsed) {
+      spec.task_registry[t.file] = registryEntry(
+        t,
+        artifactDeclarations,
+        dependencyDeclarations.get(t.file) || [],
+      );
+    }
+  } else {
+    delete spec.task_files;
+    delete spec.task_registry;
+  }
+  if (args.research) spec.authoring.research = 'draft';
+  preflightSpec21Candidate(spec, {
+    featureName: args.feature,
+    requirementsExists: true,
+    designExists: true,
+    researchExists: args.research,
+    taskFiles: parsed.map((task) => task.file),
+  });
+  const changes = [{ path: 'spec.json', body: `${JSON.stringify(spec, null, 2)}\n` }];
   created.push('spec.json');
 
   // --- doc templates (placeholders left for the model to fill) ---
-  for (const [tpl, out] of [['requirements.md', 'requirements.md'], ['research.md', 'research.md'], ['design.md', 'design.md']]) {
-    const body = readTemplate(tpl).replace(/\{\{FEATURE_NAME\}\}/g, args.feature);
-    fs.writeFileSync(path.join(specDir, out), body);
+  const docs = [
+    ['requirements.md', 'requirements.md'],
+    ...(args.research ? [['research.md', 'research.md']] : []),
+    ['design.md', 'design.md'],
+  ];
+  for (const [tpl, out] of docs) {
+    const source = tpl === 'research.md'
+      ? renderResearchTemplate(args.feature, args.uncertainty)
+      : readTemplate(tpl);
+    const body = applyExecutionClosureProfile(
+      source,
+      tpl === 'design.md'
+        && (selectedPolicy.lane === 'Critical' || declaredImplementationObligations(spec).length > 0),
+    ).replace(/\{\{FEATURE_NAME\}\}/g, args.feature);
+    changes.push({ path: out, body });
     created.push(out);
   }
 
   // --- task stubs (fill the cheap placeholders; leave the rest) ---
   for (const t of parsed) {
-    fs.writeFileSync(path.join(specDir, t.file), fillTask(taskTpl, t, args.feature));
+    changes.push({
+      path: t.file,
+      body: fillTask(
+        taskTpl,
+        t,
+        args.feature,
+        dependencyDeclarations.get(t.file) || [],
+        taskHasDeclaredImplementationObligation(spec, t.file),
+      ),
+    });
     created.push(t.file);
   }
 
+  const snapshots = new Map();
+  for (const change of changes) snapshots.set(change.path, captureTarget(workRoot, specDir, change.path));
+  commitChanges(workRoot, specDir, changes, snapshots, parseFailureInjection(), {
+    createSpecDir: true,
+    transactionRoot: workRoot,
+    afterApply: () => observeInstalledPolicyBaseline({ args, specDir, spec }),
+  });
+
   const rel = path.relative(process.cwd(), specDir) || specDir;
   console.log(`SCAFFOLDED ${rel}`);
-  console.log(`- ${created.length} files created: spec.json + 3 docs + ${parsed.length} task stub(s)`);
-  console.log(`- task_files + task_registry pre-populated (${parsed.length} entries, all pending)`);
-  console.log(`- NEXT: Edit-fill the {{...}} placeholders (do NOT leave any); set dependencies in task_registry; run validator + spec-ground before ready.`);
+  console.log(`- ${created.length} files created: spec.json + ${docs.length} docs + ${parsed.length} task stub(s)`);
+  if (parsed.length > 0) console.log(`- task_files + task_registry pre-populated (${parsed.length} entries, all pending)`);
+  console.log('- NEXT: Fill all spec placeholders (do NOT leave any); run validator + spec-ground before ready.');
 }
 
-main();
+try {
+  main();
+} catch (error) {
+  console.error(`precondition: ${error.message}`);
+  process.exitCode = 2;
+}