thoth-agents 0.4.1 → 0.5.0

package/plugin/skills/thoth-sdd/scripts/validate.mjs

@@ -1,1389 +1,767 @@
 #!/usr/bin/env node
-
-import { existsSync, readFileSync } from 'node:fs';
-import { join, posix, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  parse,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
+import { pathToFileURL } from 'node:url';
 import {
-  CAPABILITY_PATTERN,
   parseCanonicalSpec,
   parseRequirementDelta,
   preflightRequirementDeltas,
 } from './durable-deltas.mjs';
 
-function parseArgs(argv) {
-  const values = { route: 'full', through: 'ready', json: false };
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index];
-    if (argument === '--json') values.json = true;
-    else if (argument === '--change') values.change = argv[++index];
-    else if (argument === '--route') values.route = argv[++index];
-    else if (argument === '--through') values.through = argv[++index];
-    else throw new Error(`Unknown argument: ${argument}`);
-  }
-  if (!values.change) throw new Error('--change is required');
-  if (!['direct', 'accelerated', 'full'].includes(values.route)) {
-    throw new Error('--route must be direct, accelerated, or full');
-  }
-  if (
-    !['specify', 'plan', 'tasks', 'checklist', 'ready', 'closeout'].includes(
-      values.through,
-    )
-  ) {
-    throw new Error(
-      '--through must be specify, plan, tasks, checklist, ready, or closeout',
-    );
-  }
-  return values;
-}
-
-function issue(code, artifact, message) {
-  return { code, artifact, message };
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const gates = [
+  'explore',
+  'specify',
+  'clarify',
+  'plan',
+  'tasks',
+  'checklist',
+  'ready',
+  'verify',
+  'closeout',
+];
+const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const reservedWindowsName = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+const issue = (code, message, recordName = 'record') => ({
+  code,
+  artifact: recordName,
+  message,
+});
+
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
 }
 
-function readArtifact(root, relativePath, errors, required = true) {
-  const path = join(root, relativePath);
-  if (!existsSync(path)) {
-    if (required) {
-      errors.push(
-        issue(
-          'SDD-ARTIFACT-MISSING',
-          relativePath,
-          `Required artifact is missing: ${relativePath}`,
-        ),
-      );
-    }
-    return undefined;
+function lstatMaybe(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return undefined;
+    throw error;
   }
-  return readFileSync(path, 'utf8');
 }
 
-function valuesFor(pattern, content) {
-  return [...content.matchAll(pattern)].map((match) => match[1]);
+export function isValidSddChangeId(id) {
+  return (
+    typeof id === 'string' &&
+    slugPattern.test(id) &&
+    !reservedWindowsName.test(id)
+  );
 }
 
-function sectionContent(content, heading) {
-  const expression = new RegExp(`^##\\s+${heading}\\s*$`, 'im');
-  const match = expression.exec(content);
-  if (!match || match.index === undefined) return undefined;
-  const start = match.index + match[0].length;
-  const remainder = content.slice(start);
-  const nextHeading = /^##\s+/m.exec(remainder);
-  return remainder.slice(0, nextHeading?.index ?? remainder.length).trim();
+function isIsoDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? '')) return false;
+  const date = new Date(`${value}T00:00:00.000Z`);
+  return (
+    !Number.isNaN(date.valueOf()) && date.toISOString().slice(0, 10) === value
+  );
 }
 
-function checkUniqueSequential(ids, prefix, artifact, errors) {
-  if (new Set(ids).size !== ids.length) {
-    errors.push(
-      issue(
-        `SDD-${prefix}-UNIQUE`,
-        artifact,
-        `${prefix} identifiers must be unique.`,
-      ),
-    );
-  }
-  const numbers = ids.map((id) => Number.parseInt(id, 10));
-  if (numbers.some((value, index) => value !== index + 1)) {
-    errors.push(
-      issue(
-        `SDD-${prefix}-SEQUENCE`,
-        artifact,
-        `${prefix} identifiers must start at 001 and remain sequential.`,
-      ),
-    );
+export function assertNoSymlinkAncestors(path) {
+  const absolute = resolve(path);
+  const { root } = parse(absolute);
+  let cursor = root;
+  for (const part of absolute.slice(root.length).split(sep).filter(Boolean)) {
+    cursor = join(cursor, part);
+    if (lstatMaybe(cursor)?.isSymbolicLink()) {
+      fail('SDD-SYMLINK', `Symlinked path component is not allowed: ${cursor}`);
+    }
   }
 }
 
-function parseAffectedCapabilities(intentSection) {
-  const match = /^\*\*Affected capabilities\*\*:\s*(.+)$/im.exec(
-    intentSection ?? '',
-  );
-  if (!match) return undefined;
-  const value = match[1].replace(/<br>\s*$/i, '').trim();
-  if (/^None\.?$/i.test(value)) return [];
-  const capabilities = valuesFor(/`([^`]+)`/g, value);
-  return capabilities.length > 0 &&
-    capabilities.every((item) => CAPABILITY_PATTERN.test(item))
-    ? capabilities
-    : undefined;
-}
-
-function contractCandidateLines(content, prefix) {
-  const pattern = new RegExp(`^\\s*-\\s+(?:\\*\\*)?${prefix}\\b`, 'i');
-  return content.split(/\r?\n/).filter((line) => pattern.test(line));
-}
+export function resolveSddChangeLocation(change) {
+  const changeRoot = resolve(change);
+  assertNoSymlinkAncestors(changeRoot);
+  const parent = dirname(changeRoot);
+  let projectRoot;
+  let id;
+  let archiveDate;
+  let archived = false;
 
-function validateSpec(content, errors) {
-  const artifact = 'spec.md';
-  const intentSection = sectionContent(content, 'Intent and scope');
-  const affectedCapabilities = parseAffectedCapabilities(intentSection);
   if (
-    intentSection === undefined ||
-    !/^\*\*Why\*\*:\s*\S.+$/im.test(intentSection) ||
-    !/^\*\*Impact\*\*:\s*\S.+$/im.test(intentSection) ||
-    affectedCapabilities === undefined
+    basename(parent) === 'changes' &&
+    basename(dirname(parent)) === '.thoth'
   ) {
-    errors.push(
-      issue(
-        'SDD-SPEC-INTENT',
-        artifact,
-        'Intent and scope must define Why, Impact, and valid affected capabilities or None.',
-      ),
+    projectRoot = dirname(dirname(parent));
+    id = basename(changeRoot);
+  } else if (
+    basename(parent) === 'archive' &&
+    basename(dirname(parent)) === 'changes' &&
+    basename(dirname(dirname(parent))) === '.thoth'
+  ) {
+    archived = true;
+    projectRoot = dirname(dirname(dirname(dirname(changeRoot))));
+    const match = /^(\d{4}-\d{2}-\d{2})-(.+)$/.exec(basename(changeRoot));
+    if (!match || !isIsoDate(match[1])) {
+      fail(
+        'SDD-CHANGE-PATH',
+        'Archived change directory must use YYYY-MM-DD-<id>',
+      );
+    }
+    archiveDate = match[1];
+    id = match[2];
+  } else {
+    fail(
+      'SDD-CHANGE-PATH',
+      'Change must be an immediate .thoth/changes/<id> or dated archive child',
     );
   }
 
-  const userStoriesSection = sectionContent(content, 'User stories');
-  const edgeCasesSection = sectionContent(content, 'Edge cases');
-  const functionalRequirementsSection = sectionContent(
-    content,
-    'Functional requirements',
-  );
-  const successCriteriaSection = sectionContent(content, 'Success criteria');
-  const dependenciesSection = sectionContent(content, 'Dependencies');
-  const missingSections = [
-    ['User stories', userStoriesSection],
-    ['Edge cases', edgeCasesSection],
-    ['Functional requirements', functionalRequirementsSection],
-    ['Success criteria', successCriteriaSection],
-    ['Dependencies', dependenciesSection],
-  ]
-    .filter(([, section]) => section === undefined)
-    .map(([heading]) => heading);
-  if (missingSections.length > 0) {
-    errors.push(
-      issue(
-        'SDD-SPEC-SECTIONS',
-        artifact,
-        `Canonical specification sections are missing: ${missingSections.join(', ')}.`,
-      ),
-    );
+  if (!isValidSddChangeId(id)) {
+    fail('SDD-CHANGE-ID', `Unsafe or reserved change ID: ${id}`);
   }
+  const recordPath = join(changeRoot, `${id}.md`);
+  assertNoSymlinkAncestors(recordPath);
+  return { projectRoot, changeRoot, id, recordPath, archived, archiveDate };
+}
 
-  const storyMatches = [
-    ...(userStoriesSection ?? '').matchAll(
-      /^###\s+US(\d+)\s+-.*\(Priority:\s*P\d+\)/gim,
-    ),
-  ];
-  const storyIds = storyMatches.map((match) => match[1]);
-  const storyCoverage = new Set();
-  if (storyIds.length === 0) {
-    errors.push(
-      issue(
-        'SDD-SPEC-STORIES',
-        artifact,
-        'Add prioritized US# stories with an independent test and acceptance scenarios.',
-      ),
-    );
-  } else {
-    checkUniqueSequential(storyIds, 'STORY', artifact, errors);
-    for (const [index, match] of storyMatches.entries()) {
-      const start = match.index ?? 0;
-      const next = storyMatches[index + 1]?.index;
-      const end = next ?? userStoriesSection.length;
-      const story = userStoriesSection.slice(start, end);
-      if (!/\*\*Independent test\*\*:\s*\S.+/i.test(story)) {
-        errors.push(
-          issue(
-            'SDD-SPEC-INDEPENDENCE',
-            artifact,
-            `US${match[1]} must describe an independent test.`,
-          ),
-        );
-      }
-      const covers = /^\*\*Covers\*\*:\s*(\S.+)$/im.exec(story);
-      const coveredIds = covers?.[1].match(/\b(?:FR|SC)-\d{3}\b/g) ?? [];
-      if (
-        !coveredIds.some((id) => id.startsWith('FR-')) ||
-        !coveredIds.some((id) => id.startsWith('SC-'))
-      ) {
-        errors.push(
-          issue(
-            'SDD-SPEC-STORY-COVERAGE',
-            artifact,
-            `US${match[1]} must map to its FR-### and SC-### contracts.`,
-          ),
-        );
-      }
-      for (const id of coveredIds) storyCoverage.add(id);
-      if (
-        !/\*\*Given\*\*[\s\S]+?\*\*When\*\*[\s\S]+?\*\*Then\*\*\s+\S/i.test(
-          story,
-        )
-      ) {
-        errors.push(
-          issue(
-            'SDD-SPEC-ACCEPTANCE',
-            artifact,
-            `US${match[1]} must include a Given/When/Then acceptance scenario.`,
-          ),
-        );
-      }
-    }
-  }
+function section(text, name, { trim = true } = {}) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`^## ${escaped}\\s*$`, 'im').exec(text);
+  if (!match) return undefined;
+  const tail = text.slice(match.index + match[0].length);
+  const content = tail.slice(0, /^## /m.exec(tail)?.index ?? tail.length);
+  return trim ? content.trim() : content;
+}
 
-  const functionalRequirements = [
-    ...(functionalRequirementsSection ?? '').matchAll(
-      /^- \*\*FR-(\d{3})\s+—\s+(.+?)\*\*:\s*`\[(.+?)\]`\s+(\S.+)$/gim,
-    ),
-  ];
-  const successCriteria = [
-    ...(successCriteriaSection ?? '').matchAll(
-      /^- \*\*SC-(\d{3})\*\*\s+`\[(buildable|outcome)\]`:\s*(\S.+)$/gim,
-    ),
-  ];
-  const frIds = functionalRequirements.map((match) => match[1]);
-  const scIds = successCriteria.map((match) => match[1]);
-  const rawFrCandidates = contractCandidateLines(content, 'FR');
-  const rawScCandidates = contractCandidateLines(content, 'SC');
-  if (rawFrCandidates.length !== functionalRequirements.length) {
-    errors.push(
-      issue(
-        'SDD-SPEC-FR-FORMAT',
-        artifact,
-        'Every FR-### must use the canonical named requirement, delta metadata, and normative statement format.',
-      ),
-    );
-  }
-  const durableDeltas = [];
-  if (frIds.length === 0) {
-    errors.push(issue('SDD-SPEC-FR', artifact, 'Add FR-### requirements.'));
-  } else {
-    checkUniqueSequential(frIds, 'FR', artifact, errors);
-    for (const match of functionalRequirements) {
-      if (!/\b(?:MUST|SHALL)\b/.test(match[4])) {
-        errors.push(
-          issue(
-            'SDD-SPEC-FR-NORMATIVE',
-            artifact,
-            `FR-${match[1]} must contain an observable MUST or SHALL statement.`,
-          ),
-        );
-      }
-      const delta = parseRequirementDelta(match[3]);
-      if (!delta) {
-        errors.push(
-          issue(
-            'SDD-SPEC-FR-DELTA',
-            artifact,
-            `FR-${match[1]} must declare INTERNAL, ADDED, MODIFIED, REMOVED, or RENAMED metadata.`,
-          ),
-        );
-      } else if (
-        delta.capability &&
-        !affectedCapabilities?.includes(delta.capability)
-      ) {
-        errors.push(
-          issue(
-            'SDD-SPEC-CAPABILITY-COVERAGE',
-            artifact,
-            `FR-${match[1]} targets undeclared capability ${delta.capability}.`,
-          ),
-        );
-      } else if (delta.operation !== 'INTERNAL') {
-        durableDeltas.push({
-          title: match[2].trim(),
-          ...delta,
-        });
-      }
+function localFile(root, name) {
+  if (
+    !name ||
+    isAbsolute(name) ||
+    name.includes('\\') ||
+    !/^[a-zA-Z0-9_./-]+$/.test(name)
+  )
+    throw new Error('Invalid reviewed source path');
+  const target = resolve(root, name);
+  const rel = relative(root, target);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+    throw new Error('Reviewed source escapes project');
+  assertNoSymlinkAncestors(target);
+  const stat = lstatMaybe(target);
+  if (!stat?.isFile() || stat.isSymbolicLink())
+    throw new Error('Reviewed source must be a regular file');
+  return target;
+}
+
+function parseDeltas(text, errors, recordName) {
+  const lines = text.split(/\r?\n/).filter((line) => line.trim());
+  if (lines.length === 1 && lines[0] === '- None.') return [];
+  const deltas = [];
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const match = /^- `([^`]+)` \*\*(.+?)\*\* — (\S.+)$/.exec(line);
+    const metadata = match && parseRequirementDelta(match[1]);
+    if (
+      !metadata ||
+      metadata.operation === 'INTERNAL' ||
+      !match[2].trim() ||
+      !match[3].trim()
+    ) {
+      errors.push(
+        issue('SDD-DELTA-FORMAT', `Invalid durable delta: ${line}`, recordName),
+      );
+      continue;
     }
-  }
-  if (rawScCandidates.length !== successCriteria.length) {
-    errors.push(
-      issue(
-        'SDD-SPEC-SC-TYPE',
-        artifact,
-        'Every SC-### must be classified as buildable or outcome.',
-      ),
+    const scenario = /^ {2}- GIVEN (.+); WHEN (.+); THEN (.+)\.$/.exec(
+      lines[index + 1] ?? '',
     );
-  }
-  if (scIds.length === 0) {
-    errors.push(
-      issue('SDD-SPEC-SC', artifact, 'Add measurable SC-### criteria.'),
-    );
-  } else {
-    checkUniqueSequential(scIds, 'SC', artifact, errors);
-    const measurable =
-      /(?:\b\d+(?:\.\d+)?\b|%|\b(?:all|every|none|zero|under|over|within|at least|at most|no more|fewer|pass(?:es)?|fail(?:s)?|accept(?:s)?|reject(?:s)?|preserve(?:s)?)\b)/i;
-    if (successCriteria.some((match) => !measurable.test(match[3]))) {
+    if (scenario) index++;
+    if (
+      metadata.operation !== 'REMOVED' &&
+      (!scenario || scenario.slice(1).some((value) => !value.trim()))
+    ) {
       errors.push(
         issue(
-          'SDD-SPEC-SC-MEASURABLE',
-          artifact,
-          'Every SC-### definition must state a structurally measurable outcome.',
+          'SDD-DELTA-SCENARIO',
+          `Concrete GIVEN/WHEN/THEN scenario is required for ${match[2]}`,
+          recordName,
         ),
       );
     }
+    if (metadata.operation === 'REMOVED' && scenario) {
+      errors.push(
+        issue(
+          'SDD-DELTA-SCENARIO',
+          'Removed requirements do not define new scenarios',
+          recordName,
+        ),
+      );
+    }
+    deltas.push({
+      ...metadata,
+      title: match[2],
+      statement: match[3],
+      scenario: scenario?.slice(1),
+    });
   }
-  if (!/^##\s+Assumptions\s*$/im.test(content)) {
-    errors.push(
-      issue('SDD-SPEC-ASSUMPTIONS', artifact, 'Add an Assumptions section.'),
-    );
-  }
-  if (!/^##\s+Out of scope\s*$/im.test(content)) {
-    errors.push(
-      issue('SDD-SPEC-OUT-OF-SCOPE', artifact, 'Add an Out of scope section.'),
-    );
-  }
-
-  const knownContracts = new Set([
-    ...frIds.map((id) => `FR-${id}`),
-    ...scIds.map((id) => `SC-${id}`),
-  ]);
-  const unknownCoverage = [...storyCoverage].filter(
-    (id) => !knownContracts.has(id),
-  );
-  const uncoveredContracts = [...knownContracts].filter(
-    (id) => !storyCoverage.has(id),
-  );
-  if (unknownCoverage.length > 0 || uncoveredContracts.length > 0) {
+  if (!lines.length) {
     errors.push(
       issue(
-        'SDD-SPEC-STORY-COVERAGE',
-        artifact,
-        `Story traceability is incomplete. Unknown: ${unknownCoverage.join(', ') || 'none'}; uncovered: ${uncoveredContracts.join(', ') || 'none'}.`,
+        'SDD-DELTA-FORMAT',
+        'Declare deltas or explicitly use - None.',
+        recordName,
       ),
     );
   }
-
-  return {
-    storyIds,
-    frIds,
-    scIds,
-    buildableScIds: successCriteria
-      .filter((match) => match[2].toLowerCase() === 'buildable')
-      .map((match) => match[1]),
-    outcomeScIds: successCriteria
-      .filter((match) => match[2].toLowerCase() === 'outcome')
-      .map((match) => match[1]),
-    durableDeltas,
-  };
+  return deltas;
 }
 
-function validateDurableDeltaIntent(specRoot, deltas, errors, warnings) {
-  const byCapability = new Map();
-  for (const delta of deltas) {
-    const current = byCapability.get(delta.capability) ?? [];
-    current.push(delta);
-    byCapability.set(delta.capability, current);
-  }
-
-  for (const [capability, capabilityDeltas] of byCapability) {
-    const path = join(specRoot, capability, 'spec.md');
-    const present = existsSync(path);
-    let canonical;
+function preflightDeltas(root, deltas, errors, warnings, recordName) {
+  const groups = new Map();
+  for (const delta of deltas)
+    groups.set(delta.capability, [
+      ...(groups.get(delta.capability) ?? []),
+      delta,
+    ]);
+  for (const [capability, entries] of groups) {
+    const path = join(root, '.thoth', 'specs', capability, 'spec.md');
+    const present = Boolean(lstatMaybe(path));
     try {
-      canonical = present
-        ? parseCanonicalSpec(readFileSync(path, 'utf8'))
-        : { requirements: new Map() };
+      assertNoSymlinkAncestors(path);
+      const stat = present ? lstatSync(path) : undefined;
+      if (present && (!stat.isFile() || stat.isSymbolicLink()))
+        throw new Error('Not a regular canonical specification');
+      const requirements = present
+        ? parseCanonicalSpec(readFileSync(path, 'utf8')).requirements
+        : new Map();
+      const result = preflightRequirementDeltas({
+        capability,
+        present,
+        requirements,
+        deltas: entries,
+      });
+      errors.push(
+        ...result.errors.map((entry) =>
+          issue(entry.code, entry.message, recordName),
+        ),
+      );
+      warnings.push(...result.warnings);
     } catch (error) {
       errors.push(
         issue(
-          'SDD-SPEC-DELTA-BASELINE',
-          'spec.md',
-          `${capability} canonical baseline is invalid: ${error instanceof Error ? error.message : String(error)}`,
+          'SDD-DELTA-BASELINE',
+          `${capability}: ${error.message}`,
+          recordName,
         ),
       );
-      continue;
     }
-
-    const result = preflightRequirementDeltas({
-      capability,
-      present,
-      requirements: canonical.requirements,
-      deltas: capabilityDeltas,
-    });
-    errors.push(
-      ...result.errors.map((entry) =>
-        issue(entry.code, 'spec.md', entry.message),
-      ),
-    );
-    warnings.push(
-      ...result.warnings.map((entry) =>
-        issue(entry.code, 'spec.md', entry.message),
-      ),
-    );
   }
 }
 
-function constitutionEntries(content) {
-  if (content === undefined) return [];
-  return content
-    .split(/\r?\n/)
-    .filter((line) => /^- /.test(line))
-    .map((line) => {
-      const match =
-        /^- (?:\*\*)?(.+?)(?:\*\*)?:\s*(PASS|JUSTIFIED EXCEPTION|FAIL)\s+[—-]\s+(\S.+)$/i.exec(
-          line,
-        );
-      return match
-        ? {
-            name: match[1].trim(),
-            status: match[2].toUpperCase(),
-            evidence: match[3],
-          }
-        : undefined;
-    });
+function settled(text) {
+  return (
+    Boolean(text?.trim()) &&
+    !/\b(?:pending|unresolved|unknown|ask|tbd|todo)\b/i.test(text)
+  );
 }
 
-function validatePlan(content, errors, constitution) {
-  const pre = sectionContent(content, 'Constitution Check \\(pre-design\\)');
-  const post = sectionContent(content, 'Constitution Check \\(post-design\\)');
-  if (pre === undefined) {
-    errors.push(
-      issue(
-        'SDD-PLAN-CONSTITUTION-PRE',
-        'plan.md',
-        'Record the pre-design Constitution Check.',
-      ),
-    );
-  }
-  if (post === undefined) {
-    errors.push(
-      issue(
-        'SDD-PLAN-CONSTITUTION-POST',
-        'plan.md',
-        'Record the post-design Constitution Check.',
-      ),
-    );
-  }
-
-  const preEntries = constitutionEntries(pre);
-  const postEntries = constitutionEntries(post);
+function coverageErrors(text, ids, errors, recordName) {
+  const tasks = section(text, 'Tasks') ?? '';
+  const rows = tasks
+    .split(/\r?\n/)
+    .filter((line) => /^- \[[^\]]*\]/.test(line));
   if (
-    (pre !== undefined &&
-      (preEntries.length === 0 ||
-        preEntries.some(
-          (entry) => !entry || !isConcreteEvidence(entry.evidence),
-        ))) ||
-    (post !== undefined &&
-      (postEntries.length === 0 ||
-        postEntries.some(
-          (entry) => !entry || !isConcreteEvidence(entry.evidence),
-        )))
+    !rows.length ||
+    rows.some(
+      (line) =>
+        !/^- \[[ x]\] AC-\d+: \S.+/.test(line) ||
+        !settled(line.slice(line.indexOf(':') + 1)),
+    ) ||
+    ids.some((id) => !rows.some((line) => line.includes(` ${id}:`))) ||
+    rows.some((line) => !ids.some((id) => line.includes(` ${id}:`)))
   ) {
     errors.push(
       issue(
-        'SDD-PLAN-CONSTITUTION-EVIDENCE',
-        'plan.md',
-        'Every Constitution Check entry must include a status and concrete evidence.',
+        'SDD-TASK-COVERAGE',
+        'Tasks must cover only known acceptance with concrete work',
+        recordName,
       ),
     );
   }
+  return rows;
+}
 
-  const preNames = preEntries
-    .filter(Boolean)
-    .map(({ name }) => name.toLowerCase());
-  const postNames = postEntries
-    .filter(Boolean)
-    .map(({ name }) => name.toLowerCase());
-  const expectedNames = constitution
-    ? valuesFor(/^###\s+(?:\d+|[IVXLCDM]+)\.\s+(.+)$/gim, constitution).map(
-        (name) => name.trim().toLowerCase(),
-      )
-    : [];
-  const coverage = expectedNames.length > 0 ? expectedNames : preNames;
+export function validate({ change, through }) {
+  if (!gates.includes(through)) throw new Error('Invalid SDD validation gate');
+  const errors = [];
+  const warnings = [];
+  const specBaselines = [];
+  let location;
+  try {
+    location = resolveSddChangeLocation(change);
+    const rootStat = lstatMaybe(location.changeRoot);
+    if (!rootStat?.isDirectory() || rootStat.isSymbolicLink())
+      throw new Error('Change directory must be a regular directory');
+    const entries = readdirSync(location.changeRoot);
+    for (const entry of entries)
+      if (entry !== `${location.id}.md`)
+        errors.push(
+          issue(
+            'SDD-AUXILIARY-ARTIFACT',
+            `Only ${location.id}.md is allowed in a change directory; found ${entry}`,
+            `${location.id}.md`,
+          ),
+        );
+  } catch (error) {
+    const code = error.code?.startsWith('SDD-')
+      ? error.code
+      : 'SDD-CHANGE-PATH';
+    return {
+      valid: false,
+      through,
+      changeRoot: resolve(change),
+      errors: [issue(code, error.message)],
+      warnings,
+      deltas: [],
+    };
+  }
+
+  const { projectRoot, changeRoot, id, recordPath, archived, archiveDate } =
+    location;
+  let text;
+  try {
+    const stat = lstatMaybe(recordPath);
+    if (!stat?.isFile() || stat.isSymbolicLink())
+      throw new Error(`${id}.md must be a regular file`);
+    text = readFileSync(recordPath, 'utf8');
+  } catch (error) {
+    errors.push(issue('SDD-CHANGE-MISSING', error.message, `${id}.md`));
+    return {
+      valid: false,
+      through,
+      projectRoot,
+      changeRoot,
+      changeId: id,
+      recordPath,
+      archived,
+      archiveDate,
+      errors,
+      warnings,
+      deltas: [],
+    };
+  }
+
+  const recordName = `${id}.md`;
   if (
-    coverage.some(
-      (name) => !preNames.includes(name) || !postNames.includes(name),
-    ) ||
-    preNames.some((name) => !postNames.includes(name)) ||
-    postNames.some((name) => !preNames.includes(name))
+    !new RegExp(
+      `^# Change: ${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
+      'm',
+    ).test(text) ||
+    !/^\*\*Classification\*\*: substantial$/m.test(text) ||
+    !/^\*\*Scope\*\*: (?:local|coordinated|cross-cutting)$/m.test(text) ||
+    !/^\*\*Uncertainty\*\*: (?:low|medium|high)$/m.test(text) ||
+    !/^\*\*Risk\*\*: (?:low|medium|high)$/m.test(text)
   ) {
     errors.push(
       issue(
-        'SDD-PLAN-CONSTITUTION-COVERAGE',
-        'plan.md',
-        'Pre-design and post-design checks must cover the same active Constitution principles.',
+        'SDD-HEADER',
+        'Record identity, substantial classification, scope, uncertainty, and risk are required',
+        recordName,
       ),
     );
   }
-  if (
-    [...preEntries, ...postEntries]
-      .filter(Boolean)
-      .some(({ status }) => status === 'FAIL')
-  ) {
+  const headingList = [...text.matchAll(/^## ([^\r\n]+)$/gm)].map((match) =>
+    match[1].trim().toLowerCase(),
+  );
+  if (new Set(headingList).size !== headingList.length) {
     errors.push(
       issue(
-        'SDD-PLAN-CONSTITUTION-FAIL',
-        'plan.md',
-        'A FAIL Constitution status blocks downstream task generation.',
+        'SDD-DUPLICATE-SECTION',
+        'Canonical record sections must be unique',
+        recordName,
       ),
     );
   }
-}
 
-function exactTaskPath(line) {
-  const description = line.split(' | Verify:', 1)[0];
-  const spans = [...description.matchAll(/`([^`\r\n]+)`/g)];
-  if (spans.length !== 1) return undefined;
-
-  const rawPath = spans[0][1].trim().replaceAll('\\', '/');
+  const needed = [];
+  if (through === 'explore') needed.push('Exploration');
+  else needed.push('Exploration', 'Intent', 'Non-goals', 'Acceptance');
   if (
-    rawPath.length === 0 ||
-    /^\[.*\]$/.test(rawPath) ||
-    /[*?[\]{}]/.test(rawPath) ||
-    rawPath.startsWith('!') ||
-    rawPath === '~' ||
-    rawPath.startsWith('~/') ||
-    rawPath.startsWith('/') ||
-    /^[a-z][a-z0-9+.-]*:/i.test(rawPath)
-  ) {
-    return undefined;
-  }
-
-  const normalized = posix.normalize(rawPath);
-  if (
-    normalized === '.' ||
-    normalized === '..' ||
-    normalized.startsWith('../')
-  ) {
-    return undefined;
-  }
-  return normalized.toLowerCase();
-}
-
-function taskDependencyEdges(content) {
-  return [...content.matchAll(/\bT\d{3}(?:\s*->\s*T\d{3})+\b/g)].flatMap(
-    ([chain]) => {
-      const ids = chain.match(/\bT\d{3}\b/g) ?? [];
-      return ids.slice(1).map((target, index) => ({
-        source: ids[index],
-        target,
-      }));
-    },
-  );
-}
-
-function parseParallelGroups(content) {
-  const lines = content.split(/\r?\n/);
-  const headingIndexes = lines
-    .map((line, index) => (/^###\s+Group\s+P\d+\s*$/.test(line) ? index : -1))
-    .filter((index) => index >= 0);
-  const groups = [];
-  let valid = headingIndexes.length > 0;
-
+    [
+      'clarify',
+      'plan',
+      'tasks',
+      'checklist',
+      'ready',
+      'verify',
+      'closeout',
+    ].includes(through)
+  )
+    needed.push('Clarifications', 'Decisions');
   if (
-    lines
-      .slice(0, headingIndexes[0] ?? lines.length)
-      .some((line) => line.trim())
-  ) {
-    valid = false;
-  }
-
-  for (const [groupIndex, start] of headingIndexes.entries()) {
-    const end = headingIndexes[groupIndex + 1] ?? lines.length;
-    const groupId = /^###\s+Group\s+P(\d+)\s*$/.exec(lines[start])?.[1];
-    const body = lines.slice(start + 1, end).filter((line) => line.trim());
-    const lanes = [];
-    let prerequisites;
-    let barrier;
-    let rationale;
-    for (const line of body) {
-      const lane =
-        /^- Lane L(\d+): (T\d{3}(?: -> T\d{3})*)(?: \| Owner: (\S+))?\s*$/.exec(
-          line,
-        );
-      if (lane) {
-        lanes.push({
-          number: Number.parseInt(lane[1], 10),
-          taskIds: lane[2].split(' -> '),
-          owner: lane[3],
-        });
-        continue;
-      }
-      const prerequisiteLine =
-        /^- Prerequisites: (None|T\d{3}(?:, T\d{3})*)\s*$/.exec(line);
-      if (prerequisiteLine && prerequisites === undefined) {
-        prerequisites =
-          prerequisiteLine[1] === 'None' ? [] : prerequisiteLine[1].split(', ');
-        continue;
-      }
-      const barrierLine = /^- Barrier: (Final verification|T\d{3})\s*$/.exec(
-        line,
+    ['plan', 'tasks', 'checklist', 'ready', 'verify', 'closeout'].includes(
+      through,
+    )
+  )
+    needed.push('Durable deltas', 'Plan');
+  if (['tasks', 'ready', 'verify', 'closeout'].includes(through))
+    needed.push('Tasks');
+  for (const name of needed) {
+    const content = section(text, name);
+    if (!settled(content)) {
+      errors.push(
+        issue(
+          'SDD-SECTION',
+          `${name} is missing, incomplete, or unresolved`,
+          recordName,
+        ),
       );
-      if (barrierLine && barrier === undefined) {
-        barrier = barrierLine[1];
-        continue;
-      }
-      const rationaleLine = /^- Rationale: (\S.*)$/.exec(line);
-      if (rationaleLine && rationale === undefined) {
-        rationale = rationaleLine[1];
-        continue;
-      }
-      valid = false;
-    }
-    if (
-      groupId === undefined ||
-      lanes.length < 2 ||
-      rationale === undefined ||
-      !isConcreteEvidence(rationale) ||
-      lanes.some((lane, index) => lane.number !== index + 1)
-    ) {
-      valid = false;
     }
-    groups.push({
-      number: Number.parseInt(groupId ?? '0', 10),
-      lanes,
-      prerequisites,
-      barrier,
-      rationale,
-    });
   }
-  if (groups.some((group, index) => group.number !== index + 1)) valid = false;
-  return { groups, valid };
-}
 
-function validateTasks(content, errors, spec) {
-  const artifact = 'tasks.md';
-  const taskLines = content
+  const acceptance = section(text, 'Acceptance') ?? '';
+  const candidates = acceptance
     .split(/\r?\n/)
-    .filter((line) => /^- \[[ x~]\]/.test(line));
-  const taskShape =
-    /^- \[[ x~]\] T(\d{3})(?: \[P\])?(?: \[US(\d+)\])? .+`[^`\r\n]+`(?: \| Verify: \S.+)?\s*$/;
+    .filter((line) => /^- AC-/.test(line));
+  const clauses = candidates.map((line) => /^- (AC-\d+): (\S.+)$/.exec(line));
   if (
-    taskLines.length === 0 ||
-    taskLines.some((line) => !taskShape.test(line) || !exactTaskPath(line))
+    !clauses.length ||
+    clauses.some((match) => !match || !settled(match[2])) ||
+    new Set(clauses.map((match) => match?.[1])).size !== clauses.length
   ) {
     errors.push(
       issue(
-        'SDD-TASK-FORMAT',
-        artifact,
-        'Every task must use T### [P?] [US#?], a description, and exactly one literal repository-relative path.',
+        'SDD-ACCEPTANCE',
+        'Acceptance requires unique, concrete AC identifiers',
+        recordName,
       ),
     );
   }
-  const parsedTasks = taskLines
-    .map((line) => ({ line, match: taskShape.exec(line) }))
-    .filter(({ match }) => match !== null);
-  if (parsedTasks.length > 0) {
-    const taskIds = parsedTasks.map(({ match }) => match[1]);
-    checkUniqueSequential(taskIds, 'TASK', artifact, errors);
+  const ids = clauses.filter(Boolean).map((match) => match[1]);
+  if (['tasks', 'ready', 'verify', 'closeout'].includes(through)) {
+    const rows = coverageErrors(text, ids, errors, recordName);
+    if (
+      ['verify', 'closeout'].includes(through) &&
+      rows.some((line) => !line.startsWith('- [x]'))
+    )
+      errors.push(
+        issue('SDD-TASK-INCOMPLETE', 'All tasks must be complete', recordName),
+      );
   }
   if (
-    taskLines.length > 0 &&
-    taskLines.some((line) => !/ \| Verify: \S.+\s*$/.test(line))
+    [
+      'clarify',
+      'plan',
+      'tasks',
+      'checklist',
+      'ready',
+      'verify',
+      'closeout',
+    ].includes(through)
   ) {
-    errors.push(
-      issue(
-        'SDD-TASK-VERIFICATION',
-        artifact,
-        'Every task must state an observable Verify outcome.',
-      ),
-    );
-  }
-
-  if (spec) {
-    const storyTags = new Set(
-      parsedTasks
-        .map(({ match }) => match[2])
-        .filter((value) => value !== undefined),
-    );
-    const missing = [
-      ...spec.storyIds
-        .filter((id) => !storyTags.has(String(Number.parseInt(id, 10))))
-        .map((id) => `US${Number.parseInt(id, 10)}`),
-      ...spec.frIds
-        .filter(
-          (id) => !new RegExp(`\\bFR-${id}\\b`).test(taskLines.join('\n')),
-        )
-        .map((id) => `FR-${id}`),
-      ...spec.buildableScIds
-        .filter(
-          (id) => !new RegExp(`\\bSC-${id}\\b`).test(taskLines.join('\n')),
-        )
-        .map((id) => `SC-${id}`),
-    ];
-    const unknownStories = [...storyTags]
-      .filter(
-        (id) =>
-          !spec.storyIds.some(
-            (storyId) =>
-              Number.parseInt(storyId, 10) === Number.parseInt(id, 10),
+    for (const name of ['Clarifications', 'Decisions']) {
+      if (!settled(section(text, name))) {
+        errors.push(
+          issue(
+            'SDD-DECISION',
+            'Material choices must be settled before classification proceeds',
+            recordName,
           ),
-      )
-      .map((id) => `US${id}`);
-    if (missing.length > 0 || unknownStories.length > 0) {
-      errors.push(
-        issue(
-          'SDD-TASK-COVERAGE',
-          artifact,
-          `Task coverage is incomplete. Missing: ${missing.join(', ') || 'none'}; unknown stories: ${unknownStories.join(', ') || 'none'}.`,
-        ),
-      );
+        );
+      }
     }
   }
-  if (!/^##\s+MVP scope\s*$/im.test(content)) {
-    errors.push(
-      issue(
-        'SDD-TASK-MVP',
-        artifact,
-        'Identify the independently testable MVP.',
-      ),
-    );
-  }
-  if (!/^##\s+Dependencies\s*$/im.test(content)) {
-    errors.push(
-      issue('SDD-TASK-DEPENDENCIES', artifact, 'Document task dependencies.'),
-    );
-  }
-  const parallelSection = sectionContent(
-    content,
-    'Parallel execution(?: examples)?',
-  );
-  const taskRecords = parsedTasks.map(({ line, match }) => ({
-    id: `T${match[1]}`,
-    parallel: /\[P\]/.test(line),
-    path: exactTaskPath(line),
-  }));
-  const tasksById = new Map(taskRecords.map((task) => [task.id, task]));
-  const hasParallelTask = taskRecords.some((task) => task.parallel);
-  const noParallelMatch = /^-\s+None:\s*(\S.*)$/im.exec(parallelSection ?? '');
-  const explainsNoParallelWork =
-    noParallelMatch !== null && isConcreteEvidence(noParallelMatch[1]);
-  const pathsOverlap = (left, right) =>
-    left === right ||
-    left.startsWith(`${right}/`) ||
-    right.startsWith(`${left}/`);
-  const noneOnly =
-    explainsNoParallelWork &&
-    parallelSection?.trim() === noParallelMatch?.[0].trim();
-  const { groups, valid: validGroupGrammar } = parseParallelGroups(
-    parallelSection ?? '',
-  );
-  const declaredDependencies = taskDependencyEdges(
-    sectionContent(content, 'Dependencies') ?? '',
-  );
-  const hasGroups = groups.length > 0;
+
+  const deltaSection = section(text, 'Durable deltas');
+  const deltas = deltaSection
+    ? parseDeltas(deltaSection, errors, recordName)
+    : [];
   if (
-    parallelSection === undefined ||
-    (hasParallelTask && (!hasGroups || explainsNoParallelWork)) ||
-    (!hasParallelTask && !noneOnly) ||
-    (explainsNoParallelWork && !noneOnly)
+    deltaSection &&
+    ['plan', 'tasks', 'checklist', 'ready', 'verify', 'closeout'].includes(
+      through,
+    )
   ) {
-    errors.push(
-      issue(
-        'SDD-TASK-PARALLEL',
-        artifact,
-        'Declare strict parallel groups for [P] tasks, or provide one exclusive evidence-backed None reason.',
-      ),
-    );
-  }
-  if (hasGroups && !validGroupGrammar) {
-    errors.push(
-      issue(
-        'SDD-TASK-LANE-GRAMMAR',
-        artifact,
-        'Groups and lanes must use unique sequential IDs, at least two lanes, and every required field.',
-      ),
-    );
-  }
-
-  if (hasGroups && validGroupGrammar) {
-    const memberships = groups.flatMap((group) =>
-      group.lanes.flatMap((lane) =>
-        lane.taskIds.map((taskId) => ({ group, lane, taskId })),
-      ),
-    );
-    const membershipCounts = new Map();
-    for (const { taskId } of memberships) {
-      membershipCounts.set(taskId, (membershipCounts.get(taskId) ?? 0) + 1);
-    }
-    const invalidMembership =
-      memberships.some(({ taskId }) => !tasksById.get(taskId)?.parallel) ||
-      taskRecords.some(
-        (task) => task.parallel && membershipCounts.get(task.id) !== 1,
-      );
-    if (invalidMembership) {
+    preflightDeltas(projectRoot, deltas, errors, warnings, recordName);
+  }
+
+  if (['verify', 'closeout'].includes(through)) {
+    const authorizationHeading = /^## Authorization\s*$/m.exec(text);
+    const auth = section(text, 'Authorization') ?? '';
+    const reviewDisposition = /^\*\*Plan review\*\*: (SKIPPED|OKAY)$/m.exec(
+      auth,
+    )?.[1];
+    const selectionLines =
+      auth.match(/^\*\*Plan review selection\*\*:.*$/gm) ?? [];
+    const reviewSelection =
+      selectionLines.length === 1
+        ? /^\*\*Plan review selection\*\*: (EXPLICIT_REVIEW|EXPLICIT_SKIP|DEFAULT_REVIEW_AFTER_3)$/.exec(
+            selectionLines[0],
+          )?.[1]
+        : undefined;
+    if (
+      !authorizationHeading ||
+      !reviewDisposition ||
+      !/^\*\*Implementation\*\*: AUTHORIZED$/m.test(auth)
+    ) {
       errors.push(
         issue(
-          'SDD-TASK-LANE-MEMBERSHIP',
-          artifact,
-          'Every [P] task must belong to exactly one lane, and lane members must be known [P] tasks.',
+          'SDD-AUTHORIZATION',
+          'Plan-review disposition and separate implementation authorization are required',
+          recordName,
         ),
       );
     }
-
     if (
-      groups.some((group) =>
-        group.lanes.some(
-          (lane) => !['designer', 'quick', 'deep'].includes(lane.owner),
-        ),
+      !(
+        (reviewDisposition === 'SKIPPED' &&
+          reviewSelection === 'EXPLICIT_SKIP') ||
+        (reviewDisposition === 'OKAY' &&
+          ['EXPLICIT_REVIEW', 'DEFAULT_REVIEW_AFTER_3'].includes(
+            reviewSelection,
+          ))
       )
     ) {
       errors.push(
         issue(
-          'SDD-TASK-LANE-OWNER',
-          artifact,
-          'Every lane owner must be designer, quick, or deep.',
+          'SDD-REVIEW-SELECTION',
+          'Plan-review selection must support the recorded disposition',
+          recordName,
         ),
       );
     }
-
-    for (const group of groups) {
-      const rationale = group.rationale ?? '';
-      const hasPathIndependenceEvidence =
-        /\b(?:path|file|surface)s?\b/i.test(rationale) &&
-        /\b(?:disjoint|non[- ]?overlap(?:ping)?)\b/i.test(rationale);
-      const hasDependencyIndependenceEvidence =
-        /\b(?:dependenc(?:y|ies)|consum(?:e|es|ing)|peer output|data flow)\b/i.test(
-          rationale,
-        );
-      if (!hasPathIndependenceEvidence || !hasDependencyIndependenceEvidence) {
+    const verificationText =
+      section(text, 'Verification', { trim: false }) ?? '';
+    const verified = verificationText.trim();
+    if (through === 'closeout') {
+      const prefix = text.slice(0, authorizationHeading?.index ?? text.length);
+      if (
+        !/^\*\*Reviewer\*\*: oracle$/m.test(verified) ||
+        !/^\*\*Independent from implementer\*\*: Yes$/m.test(verified) ||
+        !/^\*\*Verdict\*\*: PASS$/m.test(verified)
+      ) {
         errors.push(
           issue(
-            'SDD-TASK-LANE-RATIONALE',
-            artifact,
-            'Parallel rationale must state concrete path-disjointness and cross-lane dependency evidence for Oracle review.',
+            'SDD-VERIFICATION',
+            'Fresh independent Oracle PASS is required',
+            recordName,
           ),
         );
       }
-
-      const memberIds = new Set(group.lanes.flatMap((lane) => lane.taskIds));
-      const prerequisites = group.prerequisites ?? [];
-      if (
-        group.prerequisites === undefined ||
-        new Set(prerequisites).size !== prerequisites.length ||
-        prerequisites.some(
-          (taskId) => !tasksById.has(taskId) || memberIds.has(taskId),
-        )
-      ) {
+      const digestLines =
+        verificationText.match(/^\*\*Reviewed record SHA-256\*\*:.*$/gm) ?? [];
+      const reviewedDigest =
+        digestLines.length === 1
+          ? /^\*\*Reviewed record SHA-256\*\*: ([a-f0-9]{64})$/.exec(
+              digestLines[0],
+            )?.[1]
+          : undefined;
+      if (reviewedDigest !== sha(prefix)) {
         errors.push(
           issue(
-            'SDD-TASK-LANE-PREREQUISITE',
-            artifact,
-            'Prerequisites must be unique known tasks outside the group.',
+            'SDD-VERIFICATION-STALE',
+            'Reviewed record does not match the content before Authorization',
+            recordName,
           ),
         );
       }
-
-      const memberNumbers = [...memberIds].map((id) =>
-        Number.parseInt(id.slice(1), 10),
-      );
-      const barrierNumber = /^T\d{3}$/.test(group.barrier ?? '')
-        ? Number.parseInt(group.barrier.slice(1), 10)
-        : undefined;
+      const rows = verified
+        .split(/\r?\n/)
+        .filter((line) => /^- AC-/.test(line));
       if (
-        group.barrier !== 'Final verification' &&
-        (barrierNumber === undefined ||
-          !tasksById.has(group.barrier) ||
-          memberIds.has(group.barrier) ||
-          prerequisites.includes(group.barrier) ||
-          memberNumbers.some((number) => barrierNumber <= number))
+        rows.length !== ids.length ||
+        ids.some(
+          (id) =>
+            !rows.some((row) =>
+              new RegExp(
+                `^- ${id}: PASS \\| (?!none|TBD)\\S.+ \\| (?!none|TBD)\\S.+$`,
+                'i',
+              ).test(row),
+            ),
+        )
       ) {
         errors.push(
           issue(
-            'SDD-TASK-LANE-BARRIER',
-            artifact,
-            'A task barrier must be a known downstream non-member task, or use exact Final verification.',
+            'SDD-VERIFICATION-COVERAGE',
+            'Every accepted outcome needs concrete PASS check and evidence',
+            recordName,
           ),
         );
       }
-
-      const laneByTask = new Map(
-        group.lanes.flatMap((lane) =>
-          lane.taskIds.map((taskId) => [taskId, lane.number]),
+    }
+    const sources = verified
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith('- Source:'));
+    if (!sources.length) {
+      errors.push(
+        issue(
+          'SDD-VERIFICATION-SOURCE',
+          'Reviewed source digests are required',
+          recordName,
         ),
       );
-      if (
-        declaredDependencies.some(
-          ({ source, target }) =>
-            laneByTask.has(source) &&
-            laneByTask.has(target) &&
-            laneByTask.get(source) !== laneByTask.get(target),
-        )
-      ) {
+    }
+    const affectedSpecs = new Map(
+      [...new Set(deltas.map((delta) => delta.capability))].map(
+        (capability) => [`.thoth/specs/${capability}/spec.md`, capability],
+      ),
+    );
+    const reviewedSources = [];
+    for (const line of sources) {
+      const match = /^- Source: ([^ |]+) \| sha256:([a-f0-9]{64})$/.exec(line);
+      const absent = /^- Source: ([^ |]+) \| absent$/.exec(line);
+      if (match) {
+        const source = {
+          line,
+          path: match[1],
+          state: 'present',
+          sha256: match[2],
+          valid: false,
+        };
+        reviewedSources.push(source);
+        try {
+          if (
+            sha(readFileSync(localFile(projectRoot, source.path))) !==
+            source.sha256
+          )
+            throw new Error('Missing, invalid or stale source');
+          source.valid = true;
+        } catch (error) {
+          errors.push(
+            issue(
+              affectedSpecs.has(source.path)
+                ? 'SDD-VERIFICATION-SPEC-BASELINE'
+                : 'SDD-VERIFICATION-SOURCE',
+              `${line}: ${error.message}`,
+              recordName,
+            ),
+          );
+        }
+      } else if (absent && affectedSpecs.has(absent[1])) {
+        reviewedSources.push({
+          line,
+          path: absent[1],
+          state: 'absent',
+          valid: true,
+        });
+      } else {
         errors.push(
           issue(
-            'SDD-TASK-LANE-DEPENDENCY',
-            artifact,
-            'Declared dependencies cannot connect different lanes in one group.',
+            'SDD-VERIFICATION-SOURCE',
+            `${line}: Missing, invalid or stale source`,
+            recordName,
           ),
         );
       }
-
-      const lanePaths = group.lanes.map((lane) =>
-        lane.taskIds.map((taskId) => tasksById.get(taskId)?.path),
+    }
+    for (const [specPath, capability] of affectedSpecs) {
+      const entries = reviewedSources.filter(
+        (source) => source.path === specPath,
       );
-      const overlaps = lanePaths.some((paths, index) =>
-        lanePaths
-          .slice(index + 1)
-          .some((otherPaths) =>
-            paths.some(
-              (path) =>
-                path !== undefined &&
-                otherPaths.some(
-                  (other) => other !== undefined && pathsOverlap(path, other),
-                ),
-            ),
+      if (entries.length !== 1) {
+        errors.push(
+          issue(
+            'SDD-VERIFICATION-SPEC-BASELINE',
+            `${specPath}: exactly one reviewed canonical baseline is required`,
+            recordName,
           ),
-      );
-      if (overlaps) {
+        );
+        continue;
+      }
+      const [baseline] = entries;
+      const target = resolve(projectRoot, specPath);
+      try {
+        assertNoSymlinkAncestors(target);
+        if (baseline.state === 'absent') {
+          if (lstatMaybe(target))
+            throw new Error(
+              'Reviewed-absent canonical specification now exists',
+            );
+          let parent = dirname(target);
+          while (
+            parent !== projectRoot &&
+            parent.startsWith(`${projectRoot}${sep}`)
+          ) {
+            const stat = lstatMaybe(parent);
+            if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+              throw new Error(
+                'Canonical specification parent is not a directory',
+              );
+            parent = dirname(parent);
+          }
+          specBaselines.push({ capability, path: specPath, state: 'absent' });
+        } else if (baseline.valid) {
+          specBaselines.push({
+            capability,
+            path: specPath,
+            state: 'present',
+            sha256: baseline.sha256,
+          });
+        }
+      } catch (error) {
         errors.push(
           issue(
-            'SDD-TASK-LANE-OVERLAP',
-            artifact,
-            'Mutable task paths cannot overlap across lanes in one group.',
+            'SDD-VERIFICATION-SPEC-BASELINE',
+            `${specPath}: ${error.message}`,
+            recordName,
           ),
         );
       }
     }
-  }
-}
-
-function validateChecklist(content, errors, spec, requireComplete) {
-  const artifact = 'checklists/requirements.md';
-  const activationMatch = /^\*\*Activation reason\*\*:\s*(\S.*)$/im.exec(
-    content,
-  );
-  if (activationMatch === null || !isConcreteEvidence(activationMatch[1])) {
-    errors.push(
-      issue(
-        'SDD-CHECKLIST-ACTIVATION',
-        artifact,
-        'Record the concrete risk or ambiguity that activated the checklist.',
-      ),
-    );
-  }
-  const checklistLines = content
-    .split(/\r?\n/)
-    .filter((line) => /^- \[[ x~]\]/.test(line));
-  const checklistShape = /^- \[([ x~])\] CHK(\d{3})\b.+$/i;
-  const parsed = checklistLines
-    .map((line) => checklistShape.exec(line))
-    .filter((match) => match !== null);
-  if (
-    checklistLines.length === 0 ||
-    checklistLines.some((line) => !checklistShape.test(line))
-  ) {
-    errors.push(
-      issue(
-        'SDD-CHECKLIST-ID',
-        artifact,
-        'Checklist items must use CHK### IDs.',
-      ),
-    );
-  }
-  if (parsed.length > 0) {
-    checkUniqueSequential(
-      parsed.map((match) => match[2]),
-      'CHECKLIST',
-      artifact,
-      errors,
-    );
-  }
-  if (requireComplete && parsed.some((match) => match[1] !== 'x')) {
-    errors.push(
-      issue(
-        'SDD-CHECKLIST-INCOMPLETE',
-        artifact,
-        'Final validation requires every checklist item to be complete.',
-      ),
-    );
-  }
-  const initial = sectionContent(content, 'Initial validation');
-  const domainLenses = sectionContent(content, 'Domain lenses');
-  const revalidation = sectionContent(content, 'Revalidation');
-  const noopRevalidationMatch =
-    revalidation === undefined
-      ? null
-      : /^-\s+Not required:\s*(\S.*)$/im.exec(revalidation);
-  const explicitNoopRevalidation =
-    noopRevalidationMatch !== null &&
-    isConcreteEvidence(noopRevalidationMatch[1]);
-  const hasRevalidationItems =
-    revalidation !== undefined &&
-    /^- \[[ x~]\] CHK\d{3}\b/im.test(revalidation);
-  const hasDomainItems =
-    domainLenses !== undefined &&
-    /^- \[[ x~]\] CHK\d{3}\b/im.test(domainLenses);
-  const noDomainLensesMatch =
-    domainLenses === undefined
-      ? null
-      : /^-\s+None:\s*(\S.*)$/im.exec(domainLenses);
-  const explicitNoDomainLenses =
-    noDomainLensesMatch !== null && isConcreteEvidence(noDomainLensesMatch[1]);
-  const missingDimensions = [
-    'Completeness',
-    'Clarity',
-    'Consistency',
-    'Measurability',
-    'Coverage',
-  ].filter(
-    (dimension) => !new RegExp(`\\[${dimension}\\]`, 'i').test(initial ?? ''),
-  );
-  if (missingDimensions.length > 0) {
-    errors.push(
-      issue(
-        'SDD-CHECKLIST-TAXONOMY',
-        artifact,
-        `Missing requirement-quality dimensions: ${missingDimensions.join(', ')}.`,
-      ),
-    );
-  }
-  if (
-    domainLenses === undefined ||
-    (!hasDomainItems && !explicitNoDomainLenses) ||
-    (hasDomainItems && explicitNoDomainLenses)
-  ) {
-    errors.push(
-      issue(
-        'SDD-CHECKLIST-DOMAIN-LENSES',
-        artifact,
-        'Add applicable domain-lens checks or an evidence-backed None decision.',
-      ),
-    );
-  }
-  if (
-    initial === undefined ||
-    revalidation === undefined ||
-    (!hasRevalidationItems && !explicitNoopRevalidation) ||
-    (hasRevalidationItems && explicitNoopRevalidation)
-  ) {
-    errors.push(
-      issue(
-        'SDD-CHECKLIST-REVALIDATION',
-        artifact,
-        'Record initial validation plus checked revalidation or an evidence-backed no-op.',
-      ),
-    );
-  }
-  if (spec) {
-    const missing = [
-      ...spec.storyIds
-        .filter(
-          (id) =>
-            !new RegExp(`\\bUS${Number.parseInt(id, 10)}\\b`).test(content),
-        )
-        .map((id) => `US${Number.parseInt(id, 10)}`),
-      ...spec.frIds
-        .filter((id) => !new RegExp(`\\bFR-${id}\\b`).test(content))
-        .map((id) => `FR-${id}`),
-      ...spec.scIds
-        .filter((id) => !new RegExp(`\\bSC-${id}\\b`).test(content))
-        .map((id) => `SC-${id}`),
-    ];
-    if (missing.length > 0) {
+    if (
+      through === 'closeout' &&
+      !/^\*\*Archive\*\*: READY$/m.test(section(text, 'Closeout') ?? '')
+    ) {
       errors.push(
-        issue(
-          'SDD-CHECKLIST-COVERAGE',
-          artifact,
-          `Checklist coverage is missing: ${missing.join(', ')}.`,
-        ),
+        issue('SDD-ARCHIVE-READINESS', 'Archive must be READY', recordName),
       );
     }
   }
-}
-
-function validateCloseoutTasks(content, errors) {
-  if (/^- \[(?: |~)\] T\d{3}\b/m.test(content)) {
-    errors.push(
-      issue(
-        'SDD-CLOSEOUT-TASKS',
-        'tasks.md',
-        'Closeout requires every task to be complete.',
-      ),
-    );
-  }
-}
-
-function parseComplianceMatrix(content) {
-  const matrix = sectionContent(content, 'Compliance matrix') ?? '';
-  const candidates = matrix
-    .split(/\r?\n/)
-    .filter((line) => /^\s*\|\s*(?:FR|SC)-/i.test(line));
-  const entries = [
-    ...matrix.matchAll(
-      /^\|\s*((?:FR|SC)-\d{3})(?:\s+`?\[(?:buildable|outcome)\]`?)?\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*(PASS|RISK|FAIL)\s*\|\s*$/gim,
-    ),
-  ].map((match) => ({
-    id: match[1].toUpperCase(),
-    evidence: match[2],
-    check: match[3],
-    result: match[4].toUpperCase(),
-  }));
-  return { entries, malformed: candidates.length !== entries.length };
-}
-
-function isConcreteEvidence(value) {
-  const normalized = value.replaceAll('`', '').trim();
-  return (
-    normalized.length > 0 &&
-    !/^\[.*\]$/.test(normalized) &&
-    !/^(?:N\/?A|NONE|PENDING|TBD|NOT YET|-)[.!]?$/i.test(normalized)
-  );
-}
-
-function hasExplicitResidualRisk(content, id) {
-  const residualRisks = sectionContent(content, 'Residual risks') ?? '';
-  const match = new RegExp(`^-\\s+${id}\\s*:\\s*(\\S.*)$`, 'im').exec(
-    residualRisks,
-  );
-  return match !== null && isConcreteEvidence(match[1]);
-}
-
-function hasBlockingCriticalFinding(content) {
-  const findings = sectionContent(content, 'Findings') ?? '';
-  return findings.split(/\r?\n/).some((line) => {
-    if (!/\bCRITICAL\b/i.test(line)) return false;
-    if (/\bRESOLVED\b/i.test(line)) return false;
-    return !/\b(?:NO|ZERO)\s+(?:OPEN\s+)?CRITICAL\b/i.test(line);
-  });
-}
-
-function hasConcreteReviewDimensions(content) {
-  const dimensions = sectionContent(content, 'Review dimensions') ?? '';
-  return ['Completeness', 'Correctness', 'Coherence'].every((dimension) => {
-    const match = new RegExp(
-      `^-\\s*\\*\\*${dimension}\\*\\*:\\s*(\\S.*)$`,
-      'im',
-    ).exec(dimensions);
-    return match !== null && isConcreteEvidence(match[1]);
-  });
-}
-
-function validateVerifyReport(content, errors, spec) {
-  const artifact = 'verify-report.md';
-  if (
-    !/^\*\*Reviewer\*\*:\s*oracle(?:<br>)?\s*$/im.test(content) ||
-    !/^\*\*Independent from implementer\*\*:\s*Yes(?:<br>)?\s*$/im.test(content)
-  ) {
-    errors.push(
-      issue(
-        'SDD-VERIFY-INDEPENDENCE',
-        artifact,
-        'Closeout requires an oracle reviewer independent from the implementer.',
-      ),
-    );
-  }
-  if (!/^\*\*Verdict\*\*:\s*PASS\s*$/im.test(content)) {
-    errors.push(
-      issue(
-        'SDD-VERIFY-VERDICT',
-        artifact,
-        'Closeout requires an explicit PASS verdict.',
-      ),
-    );
-  }
-  if (hasBlockingCriticalFinding(content)) {
-    errors.push(
-      issue(
-        'SDD-VERIFY-CRITICAL',
-        artifact,
-        'Unresolved CRITICAL verification findings block closeout.',
-      ),
-    );
-  }
-
-  if (!hasConcreteReviewDimensions(content)) {
-    errors.push(
-      issue(
-        'SDD-VERIFY-DIMENSIONS',
-        artifact,
-        'Oracle must judge completeness, correctness, and coherence separately.',
-      ),
-    );
-  }
-
-  const matrix = parseComplianceMatrix(content);
-  const knownIds = new Set([
-    ...spec.frIds.map((id) => `FR-${id}`),
-    ...spec.scIds.map((id) => `SC-${id}`),
-  ]);
-  const rowIds = matrix.entries.map(({ id }) => id);
-  const duplicateIds = rowIds.filter(
-    (id, index) => rowIds.indexOf(id) !== index,
-  );
-  const unknownIds = rowIds.filter((id) => !knownIds.has(id));
-  const failedIds = matrix.entries
-    .filter(({ result }) => result === 'FAIL')
-    .map(({ id }) => id);
-  if (
-    matrix.malformed ||
-    duplicateIds.length > 0 ||
-    unknownIds.length > 0 ||
-    failedIds.length > 0
-  ) {
-    errors.push(
-      issue(
-        'SDD-VERIFY-MATRIX',
-        artifact,
-        `Compliance matrix rows must be canonical, unique, known, and non-FAIL. Duplicates: ${[...new Set(duplicateIds)].join(', ') || 'none'}; unknown: ${[...new Set(unknownIds)].join(', ') || 'none'}; failed: ${[...new Set(failedIds)].join(', ') || 'none'}.`,
-      ),
-    );
-  }
-  const rows = new Map(matrix.entries.map((entry) => [entry.id, entry]));
-  const required = [
-    ...spec.frIds.map((id) => `FR-${id}`),
-    ...spec.buildableScIds.map((id) => `SC-${id}`),
-  ];
-  const missing = required.filter((id) => {
-    const row = rows.get(id);
-    return (
-      row?.result !== 'PASS' ||
-      !isConcreteEvidence(row.evidence) ||
-      !isConcreteEvidence(row.check)
-    );
-  });
-  if (missing.length > 0) {
-    errors.push(
-      issue(
-        'SDD-VERIFY-COVERAGE',
-        artifact,
-        `Verification evidence is missing for: ${missing.join(', ')}.`,
-      ),
-    );
-  }
-
-  const unresolvedOutcomes = spec.outcomeScIds
-    .map((id) => `SC-${id}`)
-    .filter((id) => {
-      const row = rows.get(id);
-      if (!row) return true;
-      if (row.result === 'PASS') {
-        return (
-          !isConcreteEvidence(row.evidence) || !isConcreteEvidence(row.check)
-        );
-      }
-      return row.result !== 'RISK' || !hasExplicitResidualRisk(content, id);
-    });
-  if (unresolvedOutcomes.length > 0) {
-    errors.push(
-      issue(
-        'SDD-VERIFY-OUTCOME',
-        artifact,
-        `Outcome criteria require observed PASS evidence or an explicit residual RISK: ${unresolvedOutcomes.join(', ')}.`,
-      ),
-    );
-  }
-}
-
-function validateArchiveReport(content, errors) {
-  const artifact = 'archive-report.md';
-  const valid =
-    /^\*\*Status\*\*:\s*READY(?:<br>)?\s*$/im.test(content) &&
-    /^\*\*Oracle verdict\*\*:\s*PASS(?:<br>)?\s*$/im.test(content) &&
-    /^\*\*Archive path\*\*:\s*`openspec\/changes\/archive\/YYYY-MM-DD-\[feature\]\/`(?:<br>)?\s*$/im.test(
-      content,
-    ) &&
-    /verify-report\.md/i.test(
-      sectionContent(content, 'Verification lineage') ?? '',
-    ) &&
-    /^- Pending: archive applies declared durable deltas transactionally\.\s*$/im.test(
-      sectionContent(content, 'Canonical specification sync') ?? '',
-    );
-  if (!valid) {
-    errors.push(
-      issue(
-        'SDD-ARCHIVE-REPORT',
-        artifact,
-        'Archive report must be READY with oracle PASS, lineage, sync status, and the dated target placeholder.',
-      ),
-    );
-  }
-}
-
-function validate({ change, route, through }) {
-  const root = resolve(change);
-  const errors = [];
-  const warnings = [];
-
-  if (route === 'direct') {
-    return { valid: true, route, through, changeRoot: root, errors, warnings };
-  }
-
-  const spec = readArtifact(root, 'spec.md', errors);
-  const requiresPlan = [
-    'plan',
-    'checklist',
-    'tasks',
-    'ready',
-    'closeout',
-  ].includes(through);
-  const requiresTasks = ['tasks', 'ready', 'closeout'].includes(through);
-  const plan = requiresPlan ? readArtifact(root, 'plan.md', errors) : undefined;
-  const tasks = requiresTasks
-    ? readArtifact(root, 'tasks.md', errors)
-    : undefined;
-  const checklist = readArtifact(
-    root,
-    'checklists/requirements.md',
-    errors,
-    through === 'checklist',
-  );
-
-  const specContract =
-    spec === undefined ? undefined : validateSpec(spec, errors);
-  if (specContract !== undefined) {
-    validateDurableDeltaIntent(
-      join(root, '..', '..', 'specs'),
-      specContract.durableDeltas,
-      errors,
-      warnings,
-    );
-  }
-  const constitution = readArtifact(
-    join(root, '..', '..'),
-    'memory/constitution.md',
-    errors,
-    requiresPlan,
-  );
-  if (plan !== undefined) validatePlan(plan, errors, constitution);
-  if (tasks !== undefined) validateTasks(tasks, errors, specContract);
-  if (checklist !== undefined) {
-    validateChecklist(
-      checklist,
-      errors,
-      specContract,
-      ['checklist', 'ready', 'closeout'].includes(through),
-    );
-  } else if (route === 'full' && ['ready', 'closeout'].includes(through)) {
-    warnings.push({
-      code: 'SDD-CHECKLIST-CONDITIONAL',
-      artifact: 'checklists/requirements.md',
-      message:
-        'No requirements checklist exists; confirm that risk did not activate the conditional checklist gate.',
-    });
-  }
-
-  if (
-    through === 'closeout' &&
-    tasks !== undefined &&
-    specContract !== undefined
-  ) {
-    validateCloseoutTasks(tasks, errors);
-    const verifyReport = readArtifact(root, 'verify-report.md', errors);
-    const archiveReport = readArtifact(root, 'archive-report.md', errors);
-    if (verifyReport !== undefined) {
-      validateVerifyReport(verifyReport, errors, specContract);
-    }
-    if (archiveReport !== undefined) {
-      validateArchiveReport(archiveReport, errors);
-    }
-  }
 
   return {
     valid: errors.length === 0,
-    route,
     through,
-    changeRoot: root,
+    projectRoot,
+    changeRoot,
+    changeId: id,
+    recordPath,
+    archived,
+    archiveDate,
     errors,
     warnings,
+    deltas,
+    specBaselines,
   };
 }
 
-try {
-  const options = parseArgs(process.argv.slice(2));
-  const report = validate(options);
-  const output = options.json
-    ? JSON.stringify(report)
-    : report.valid
-      ? 'SDD artifacts are structurally valid.'
-      : report.errors
-          .map((error) => `${error.code} (${error.artifact}): ${error.message}`)
-          .join('\n');
-  process.stdout.write(`${output}\n`);
-  process.exitCode = report.valid ? 0 : 1;
-} catch (error) {
-  process.stderr.write(
-    `${error instanceof Error ? error.message : String(error)}\n`,
-  );
-  process.exitCode = 2;
+function args(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--json') options.json = true;
+    else if (['--change', '--through'].includes(argv[i]))
+      options[argv[i].slice(2)] = argv[++i];
+    else throw new Error(`Unknown argument: ${argv[i]}`);
+  }
+  if (!options.change || !options.through)
+    throw new Error('--change and --through are required');
+  return options;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  try {
+    const options = args(process.argv.slice(2));
+    const result = validate(options);
+    process.stdout.write(
+      `${options.json ? JSON.stringify(result) : result.valid ? 'Substantial SDD record is structurally valid.' : result.errors.map((entry) => `${entry.code}: ${entry.message}`).join('\n')}\n`,
+    );
+    process.exitCode = result.valid ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  }
 }