enterprise-delivery 0.1.0

package/src/rules.mjs

@@ -0,0 +1,814 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSection, listIds, sectionHasContent } from './markdown.mjs';
+import { loadChange, loadStory } from './repository.mjs';
+
+export const REQUIRED_REPO_FILES = [
+  'docs/enterprise/project-charter.md',
+  'docs/enterprise/roadmap.md',
+  'docs/enterprise/architecture-overview.md',
+  'docs/enterprise/test-strategy.md',
+  'docs/enterprise/stakeholder-register.md',
+  'docs/enterprise/risk-register.md',
+  'docs/enterprise/decision-log.md',
+  'docs/enterprise/product-backlog.md',
+  'docs/enterprise/change-log.md',
+  'docs/enterprise/project-vision.md',
+  'docs/enterprise/current-state.md',
+  'docs/enterprise/task-graph.json'
+];
+
+const REQUIRED_STORY_SECTIONS = [
+  'Requirement',
+  'Business Value',
+  'Acceptance Criteria',
+  'Non-Functional Criteria',
+  'Dependencies',
+  'Risk Impact',
+  'Docs Impact',
+  'Test Evidence',
+  'Implementation Links',
+  'Change History'
+];
+
+const REQUIRED_CHANGE_SECTIONS = [
+  'Reason',
+  'Impact',
+  'Approval',
+  'Evidence',
+  'Rollout Notes'
+];
+
+const DEDICATED_STORY_SECTION_ERRORS = new Set([
+  'Acceptance Criteria',
+  'Docs Impact',
+  'Implementation Links',
+  'Test Evidence'
+]);
+
+const CHANGE_ID_PATTERN = /^CHG-[0-9]{4}$/;
+const STORY_ID_PATTERN = /^STORY-[0-9]{4}$/;
+const FEATURE_COMPLETION_CHANGE_STATUSES = new Set(['implemented', 'verified', 'released']);
+const RELEASE_CHANGE_STATUSES = new Set(['verified', 'released']);
+const TASK_STATUSES = new Set(['planned', 'in_progress', 'blocked', 'review', 'done']);
+const REQUIRED_PROJECT_VISION_SECTIONS = [
+  'Product Goals',
+  'Non-Goals',
+  'Target Users',
+  'Spec Principles',
+  'Architecture Principles',
+  'Forbidden Patterns',
+  'Coding Philosophy',
+  'Quality Bar',
+  'AI Collaboration Rules'
+];
+const REQUIRED_CURRENT_STATE_SECTIONS = [
+  'Active Stories',
+  'Active Changes',
+  'Failing Tests',
+  'TODOs',
+  'Coverage',
+  'Unresolved Bugs',
+  'Recent Commits',
+  'Active Risks',
+  'Active Decisions',
+  'Current Task Graph',
+  'Next Verification Commands'
+];
+
+export function validateRepo(rootDir) {
+  const errors = [];
+
+  for (const relativePath of REQUIRED_REPO_FILES) {
+    const absolutePath = path.join(rootDir, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      errors.push(error(
+        'missing_repo_artifact',
+        `Missing required artifact: ${relativePath}`,
+        `Create ${relativePath} from the enterprise-delivery template.`
+      ));
+    }
+  }
+
+  const taskGraphPath = path.join(rootDir, 'docs/enterprise/task-graph.json');
+  if (fs.existsSync(taskGraphPath)) {
+    try {
+      const taskGraph = JSON.parse(fs.readFileSync(taskGraphPath, 'utf8'));
+      errors.push(...validateTaskGraph(taskGraph));
+    } catch (parseError) {
+      errors.push(error(
+        'invalid_task_graph_json',
+        `docs/enterprise/task-graph.json contains invalid JSON: ${parseError.message}`,
+        'Fix docs/enterprise/task-graph.json so it can be parsed as JSON.'
+      ));
+    }
+  }
+
+  errors.push(...validateMarkdownSections(
+    rootDir,
+    'docs/enterprise/project-vision.md',
+    REQUIRED_PROJECT_VISION_SECTIONS
+  ));
+  errors.push(...validateMarkdownSections(
+    rootDir,
+    'docs/enterprise/current-state.md',
+    REQUIRED_CURRENT_STATE_SECTIONS
+  ));
+
+  return result('repo', 'repo', errors);
+}
+
+function validateMarkdownSections(rootDir, relativePath, sections) {
+  const errors = [];
+  const absolutePath = path.join(rootDir, relativePath);
+  if (!fs.existsSync(absolutePath)) {
+    return errors;
+  }
+
+  const content = fs.readFileSync(absolutePath, 'utf8');
+  for (const section of sections) {
+    if (!sectionHasContent(content, section)) {
+      errors.push(error(
+        'missing_repo_section',
+        `${relativePath} section "${section}" is empty or missing.`,
+        `Fill ${section} in ${relativePath}, using "unknown" when the fact is not known yet.`
+      ));
+    }
+  }
+
+  return errors;
+}
+
+function validateTaskGraph(taskGraph) {
+  const errors = [];
+  if (!isPlainObject(taskGraph)) {
+    return [
+      error(
+        'invalid_task_graph_shape',
+        'docs/enterprise/task-graph.json must contain a JSON object.',
+        'Replace docs/enterprise/task-graph.json with the enterprise-delivery task graph template.'
+      )
+    ];
+  }
+
+  if (!Number.isInteger(taskGraph.schema_version)) {
+    errors.push(error(
+      'invalid_task_graph_schema_version',
+      'docs/enterprise/task-graph.json schema_version must be an integer.',
+      'Set schema_version to the current integer schema version.'
+    ));
+  }
+
+  if (typeof taskGraph.updated_at !== 'string' || taskGraph.updated_at.trim() === '') {
+    errors.push(error(
+      'invalid_task_graph_updated_at',
+      'docs/enterprise/task-graph.json updated_at must be a non-empty string.',
+      'Set updated_at to an ISO date or "unknown".'
+    ));
+  }
+
+  if (!isPlainObject(taskGraph.tasks)) {
+    errors.push(error(
+      'invalid_task_graph_tasks',
+      'docs/enterprise/task-graph.json tasks must be an object.',
+      'Define tasks as an object keyed by task IDs.'
+    ));
+    return errors;
+  }
+
+  const taskIds = new Set(Object.keys(taskGraph.tasks));
+  for (const [taskId, task] of Object.entries(taskGraph.tasks)) {
+    if (!/^task_[A-Za-z0-9_-]+$/.test(taskId)) {
+      errors.push(error(
+        'invalid_task_id',
+        `${taskId} must use a task_* ID.`,
+        `Rename ${taskId} in docs/enterprise/task-graph.json to a task_* ID.`
+      ));
+    }
+
+    if (!isPlainObject(task)) {
+      errors.push(error(
+        'invalid_task_shape',
+        `${taskId} must be a JSON object.`,
+        `Replace ${taskId} with a task object in docs/enterprise/task-graph.json.`
+      ));
+      continue;
+    }
+
+    if (typeof task.title !== 'string' || task.title.trim() === '') {
+      errors.push(error(
+        'missing_task_title',
+        `${taskId} title is empty or missing.`,
+        `Add a title to ${taskId} in docs/enterprise/task-graph.json.`
+      ));
+    }
+
+    if (!TASK_STATUSES.has(task.status)) {
+      errors.push(error(
+        'invalid_task_status',
+        `${taskId} has invalid status ${task.status}.`,
+        `Use one of ${Array.from(TASK_STATUSES).join(', ')} for ${taskId}.`
+      ));
+    }
+
+    if (!Array.isArray(task.depends_on)) {
+      errors.push(error(
+        'invalid_task_dependencies',
+        `${taskId} depends_on must be an array.`,
+        `Set depends_on to an array in ${taskId}.`
+      ));
+    } else {
+      for (const dependencyId of task.depends_on) {
+        if (!taskIds.has(dependencyId)) {
+          errors.push(error(
+            'missing_task_dependency',
+            `${taskId} depends on missing task ${dependencyId}.`,
+            `Add ${dependencyId} to tasks or remove it from ${taskId}.depends_on.`
+          ));
+        }
+      }
+    }
+
+    if (typeof task.story_id !== 'string' || !STORY_ID_PATTERN.test(task.story_id)) {
+      errors.push(error(
+        'invalid_task_story_id',
+        `${taskId} story_id must be a STORY-* ID.`,
+        `Set ${taskId}.story_id to a STORY-0000 style ID.`
+      ));
+    }
+
+    if (typeof task.change_id !== 'string' || !CHANGE_ID_PATTERN.test(task.change_id)) {
+      errors.push(error(
+        'invalid_task_change_id',
+        `${taskId} change_id must be a CHG-* ID.`,
+        `Set ${taskId}.change_id to a CHG-0000 style ID.`
+      ));
+    }
+
+    if (!Array.isArray(task.evidence)) {
+      errors.push(error(
+        'invalid_task_evidence',
+        `${taskId} evidence must be an array.`,
+        `Set ${taskId}.evidence to an array.`
+      ));
+    }
+
+    if (task.status === 'blocked' && (typeof task.blocked_reason !== 'string' || task.blocked_reason.trim() === '')) {
+      errors.push(error(
+        'missing_blocked_reason',
+        `${taskId} is blocked but has no blocked_reason.`,
+        `Add blocked_reason to ${taskId} or move it out of blocked status.`
+      ));
+    }
+  }
+
+  return errors;
+}
+
+export function validateFeature(rootDir, storyId) {
+  const errors = [];
+  const story = loadStory(rootDir, storyId);
+
+  if (!story) {
+    return result('feature', storyId, [
+      error('missing_story', `Story ${storyId} does not exist.`, `Create docs/enterprise/stories/${storyId}-<slug>.md.`)
+    ]);
+  }
+
+  if (story.parseError) {
+    return result('feature', storyId, [
+      error(
+        'unparseable_story',
+        `Story ${storyId} could not be parsed: ${story.parseError.message}`,
+        `Fix frontmatter syntax in ${story.relativePath}.`
+      )
+    ]);
+  }
+
+  if (!['review', 'done'].includes(story.data.status)) {
+    errors.push(error(
+      'invalid_story_status',
+      `${storyId} status must be review or done for completion validation.`,
+      `Move ${storyId} to review only after implementation evidence is ready.`
+    ));
+  }
+
+  for (const section of REQUIRED_STORY_SECTIONS) {
+    if (!DEDICATED_STORY_SECTION_ERRORS.has(section) && !sectionHasContent(story.body, section)) {
+      errors.push(error(
+        'missing_story_section',
+        `${storyId} section "${section}" is empty or missing.`,
+        `Fill ${section} in ${story.relativePath}.`
+      ));
+    }
+  }
+
+  const linkedChanges = Array.isArray(story.data.linked_changes) ? story.data.linked_changes : [];
+  if (linkedChanges.length === 0) {
+    errors.push(error(
+      'missing_linked_change',
+      `${storyId} has no linked CHG-* record.`,
+      `Create docs/enterprise/changes/CHG-<next>-<slug>.md and add it to linked_changes.`
+    ));
+  }
+
+  for (const changeId of linkedChanges) {
+    if (!CHANGE_ID_PATTERN.test(changeId)) {
+      errors.push(error(
+        'invalid_linked_change',
+        `Linked change ${changeId} must be a CHG-* ID.`,
+        `Replace ${changeId} in ${story.relativePath} with a CHG-0000 style change ID.`
+      ));
+    }
+  }
+
+  if (!sectionHasContent(story.body, 'Acceptance Criteria')) {
+    errors.push(error(
+      'missing_acceptance_criteria',
+      `${storyId} has no acceptance criteria.`,
+      `Add acceptance criteria to ${story.relativePath}.`
+    ));
+  }
+
+  if (!sectionHasContent(story.body, 'Test Evidence')) {
+    errors.push(error(
+      'missing_test_evidence',
+      `${storyId} has no test evidence.`,
+      `Add command and result evidence to ${story.relativePath}.`
+    ));
+  }
+
+  const docsImpact = getSection(story.body, 'Docs Impact').trim();
+  if (!docsImpact) {
+    errors.push(error(
+      'missing_docs_impact',
+      `${storyId} Docs Impact section is empty.`,
+      `Fill Docs Impact or state "No impact" with a reason.`
+    ));
+  }
+
+  if (isBareNoImpact(docsImpact)) {
+    errors.push(error(
+      'missing_docs_impact_reason',
+      `${storyId} Docs Impact must include a reason when stating no impact.`,
+      `Change Docs Impact to "No impact: <reason>" or describe the documentation changes.`
+    ));
+  }
+
+  if (!sectionHasContent(story.body, 'Implementation Links')) {
+    errors.push(error(
+      'missing_implementation_links',
+      `${storyId} has no implementation links.`,
+      `Add linked files, commit, pull request, or external implementation reference.`
+    ));
+  }
+
+  for (const changeId of linkedChanges) {
+    if (!CHANGE_ID_PATTERN.test(changeId)) {
+      continue;
+    }
+
+    const change = loadChange(rootDir, changeId);
+    if (!change) {
+      errors.push(error(
+        'missing_change',
+        `Linked change ${changeId} does not exist.`,
+        `Create docs/enterprise/changes/${changeId}-<slug>.md.`
+      ));
+      continue;
+    }
+
+    if (change.parseError) {
+      errors.push(error(
+        'unparseable_change',
+        `Change ${changeId} could not be parsed: ${change.parseError.message}`,
+        `Fix frontmatter syntax in ${change.relativePath}.`
+      ));
+      continue;
+    }
+
+    if (!FEATURE_COMPLETION_CHANGE_STATUSES.has(change.data.status)) {
+      errors.push(error(
+        'invalid_change_status',
+        `${changeId} status must be implemented, verified, or released for feature validation.`,
+        `Move ${changeId} to implemented after implementation is complete, or link a completed change.`
+      ));
+    }
+
+    const relatedStories = Array.isArray(change.data.related_stories) ? change.data.related_stories : [];
+    if (!relatedStories.includes(storyId)) {
+      errors.push(error(
+        'missing_reverse_story_link',
+        `${changeId} must list ${storyId} in related_stories.`,
+        `Add ${storyId} to related_stories in ${change.relativePath}.`
+      ));
+    }
+
+    const hasDedicatedEvidenceError = ['verified', 'released'].includes(change.data.status);
+    for (const section of REQUIRED_CHANGE_SECTIONS) {
+      if (!(hasDedicatedEvidenceError && section === 'Evidence') && !sectionHasContent(change.body, section)) {
+        errors.push(error(
+          'missing_change_section',
+          `${changeId} section "${section}" is empty or missing.`,
+          `Fill ${section} in ${change.relativePath}.`
+        ));
+      }
+    }
+
+    if (['verified', 'released'].includes(change.data.status) && !sectionHasContent(change.body, 'Evidence')) {
+      errors.push(error(
+        'missing_change_evidence',
+        `${changeId} is ${change.data.status} but has no evidence.`,
+        `Add verification evidence to ${change.relativePath}.`
+      ));
+    }
+  }
+
+  return result('feature', storyId, errors);
+}
+
+export function validateSprint(rootDir, sprintId) {
+  const errors = [];
+  const sprintDir = path.join(rootDir, 'docs/enterprise/sprints', sprintId);
+  const sprintPlanPath = path.join(sprintDir, 'sprint-plan.md');
+  const statusReportPath = path.join(sprintDir, 'status-report.md');
+
+  let sprintPlan = '';
+  if (!fs.existsSync(sprintPlanPath)) {
+    errors.push(error(
+      'missing_sprint_plan',
+      `Sprint ${sprintId} is missing sprint-plan.md.`,
+      `Create docs/enterprise/sprints/${sprintId}/sprint-plan.md.`
+    ));
+  } else {
+    sprintPlan = fs.readFileSync(sprintPlanPath, 'utf8');
+  }
+
+  let statusReport = '';
+  if (!fs.existsSync(statusReportPath)) {
+    errors.push(error(
+      'missing_status_report',
+      `Sprint ${sprintId} is missing status-report.md.`,
+      `Create docs/enterprise/sprints/${sprintId}/status-report.md.`
+    ));
+  } else {
+    statusReport = fs.readFileSync(statusReportPath, 'utf8');
+  }
+
+  const committedStoriesSection = getSection(sprintPlan, 'Committed Stories');
+  const committedStories = listIds(committedStoriesSection, 'STORY');
+  for (const storyId of listInvalidIdReferences(committedStoriesSection, 'STORY', STORY_ID_PATTERN)) {
+    errors.push(error(
+      'invalid_committed_story',
+      `Committed story reference ${storyId} is not a valid STORY-* ID.`,
+      `Replace ${storyId} in docs/enterprise/sprints/${sprintId}/sprint-plan.md with a STORY-0000 style story ID.`
+    ));
+  }
+
+  if (committedStories.length === 0) {
+    errors.push(error(
+      'missing_committed_stories',
+      `Sprint ${sprintId} has no committed stories.`,
+      `Add committed STORY-* IDs to docs/enterprise/sprints/${sprintId}/sprint-plan.md.`
+    ));
+  }
+
+  for (const storyId of committedStories) {
+    const story = loadStory(rootDir, storyId);
+    if (!story) {
+      errors.push(error(
+        'missing_committed_story',
+        `Committed story ${storyId} does not exist.`,
+        `Create docs/enterprise/stories/${storyId}-<slug>.md or remove it from the sprint plan.`
+      ));
+      continue;
+    }
+
+    if (story.parseError) {
+      errors.push(error(
+        'unparseable_story',
+        `Story ${storyId} could not be parsed: ${story.parseError.message}`,
+        `Fix frontmatter syntax in ${story.relativePath}.`
+      ));
+      continue;
+    }
+
+    const linkedChanges = Array.isArray(story.data.linked_changes) ? story.data.linked_changes : [];
+    const hasLinkedChange = linkedChanges.some((changeId) => CHANGE_ID_PATTERN.test(changeId));
+    const featureGateReportsMissingChange = story.data.status === 'done' && linkedChanges.length === 0;
+    if (!hasLinkedChange && !featureGateReportsMissingChange) {
+      errors.push(error(
+        'missing_linked_change',
+        `${storyId} has no linked CHG-* record.`,
+        `Create docs/enterprise/changes/CHG-<next>-<slug>.md and add it to linked_changes.`
+      ));
+    }
+
+    if (story.data.status === 'done') {
+      errors.push(...validateFeature(rootDir, storyId).errors);
+    } else {
+      errors.push(...validateSprintLinkedChanges(rootDir, storyId, linkedChanges));
+    }
+
+    if (story.data.status === 'blocked' && !story.body.toLowerCase().includes('next action')) {
+      errors.push(error(
+        'missing_blocked_next_action',
+        `${storyId} is blocked but has no next action.`,
+        `Add a next action to ${story.relativePath}.`
+      ));
+    }
+  }
+
+  const risks = getSection(statusReport, 'Risks').toLowerCase();
+  if (!risks.includes('no new risks') && !risks.includes('risk-register')) {
+    errors.push(error(
+      'missing_risk_status',
+      `Sprint ${sprintId} status report must state risk status.`,
+      `Update Risks in docs/enterprise/sprints/${sprintId}/status-report.md with "No new risks" or a risk-register reference.`
+    ));
+  }
+
+  const decisions = getSection(statusReport, 'Decisions').toLowerCase();
+  if (!decisions.includes('no new decisions') && !decisions.includes('decision-log')) {
+    errors.push(error(
+      'missing_decision_status',
+      `Sprint ${sprintId} status report must state decision status.`,
+      `Update Decisions in docs/enterprise/sprints/${sprintId}/status-report.md with "No new decisions" or a decision-log reference.`
+    ));
+  }
+
+  return result('sprint', sprintId, errors);
+}
+
+function validateSprintLinkedChanges(rootDir, storyId, linkedChanges) {
+  const errors = [];
+
+  for (const changeId of linkedChanges) {
+    if (!CHANGE_ID_PATTERN.test(changeId)) {
+      errors.push(error(
+        'invalid_linked_change',
+        `Linked change ${changeId} must be a CHG-* ID.`,
+        `Replace ${changeId} in the story frontmatter with a CHG-0000 style change ID.`
+      ));
+      continue;
+    }
+
+    const change = loadChange(rootDir, changeId);
+    if (!change) {
+      errors.push(error(
+        'missing_change',
+        `Linked change ${changeId} does not exist.`,
+        `Create docs/enterprise/changes/${changeId}-<slug>.md.`
+      ));
+      continue;
+    }
+
+    if (change.parseError) {
+      errors.push(error(
+        'unparseable_change',
+        `Change ${changeId} could not be parsed: ${change.parseError.message}`,
+        `Fix frontmatter syntax in ${change.relativePath}.`
+      ));
+      continue;
+    }
+
+    const relatedStories = Array.isArray(change.data.related_stories) ? change.data.related_stories : [];
+    if (!relatedStories.includes(storyId)) {
+      errors.push(error(
+        'missing_reverse_story_link',
+        `${changeId} must list ${storyId} in related_stories.`,
+        `Add ${storyId} to related_stories in ${change.relativePath}.`
+      ));
+    }
+  }
+
+  return errors;
+}
+
+export function validateRelease(rootDir, releaseId) {
+  const errors = [];
+  const releaseDir = path.join(rootDir, 'docs/enterprise/releases', releaseId);
+  const requiredArtifacts = [
+    'release-plan.md',
+    'release-notes.md',
+    'traceability-matrix.md'
+  ];
+  const contents = [];
+  let traceabilityMatrix = null;
+
+  for (const artifact of requiredArtifacts) {
+    const absolutePath = path.join(releaseDir, artifact);
+    const relativePath = path.join('docs/enterprise/releases', releaseId, artifact);
+    if (!fs.existsSync(absolutePath)) {
+      errors.push(error(
+        'missing_release_artifact',
+        `Release ${releaseId} is missing ${artifact}.`,
+        `Create ${relativePath}.`
+      ));
+      continue;
+    }
+
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    contents.push(content);
+    if (artifact === 'traceability-matrix.md') {
+      traceabilityMatrix = content;
+    }
+  }
+
+  const releaseContent = contents.join('\n');
+  const traceabilityPairs = traceabilityMatrix === null ? [] : listReleaseTraceabilityPairs(traceabilityMatrix);
+  const storyIds = listIds(releaseContent, 'STORY');
+  const changeIds = listIds(releaseContent, 'CHG');
+  for (const storyId of listInvalidIdReferences(releaseContent, 'STORY', STORY_ID_PATTERN)) {
+    errors.push(error(
+      'invalid_release_story',
+      `Release story reference ${storyId} is not a valid STORY-* ID.`,
+      `Replace ${storyId} in docs/enterprise/releases/${releaseId} with a STORY-0000 style story ID.`
+    ));
+  }
+
+  for (const changeId of listInvalidIdReferences(releaseContent, 'CHG', CHANGE_ID_PATTERN)) {
+    errors.push(error(
+      'invalid_release_change',
+      `Release change reference ${changeId} is not a valid CHG-* ID.`,
+      `Replace ${changeId} in docs/enterprise/releases/${releaseId} with a CHG-0000 style change ID.`
+    ));
+  }
+
+  if (storyIds.length === 0) {
+    errors.push(error(
+      'missing_release_stories',
+      `Release ${releaseId} has no story references.`,
+      `Add included STORY-* IDs to docs/enterprise/releases/${releaseId}/release-plan.md or traceability-matrix.md.`
+    ));
+  }
+
+  if (changeIds.length === 0) {
+    errors.push(error(
+      'missing_release_changes',
+      `Release ${releaseId} has no change references.`,
+      `Add included CHG-* IDs to docs/enterprise/releases/${releaseId}/release-plan.md, release-notes.md, or traceability-matrix.md.`
+    ));
+  }
+
+  if (traceabilityMatrix !== null && traceabilityPairs.length === 0) {
+    errors.push(error(
+      'missing_release_traceability_pairs',
+      `Release ${releaseId} has no traceability story/change pairs.`,
+      `Add at least one same-line STORY-0000 and CHG-0000 pair to docs/enterprise/releases/${releaseId}/traceability-matrix.md.`
+    ));
+  }
+
+  if (traceabilityMatrix !== null) {
+    const tracedStoryIds = new Set(traceabilityPairs.map((pair) => pair.storyId));
+    const tracedChangeIds = new Set(traceabilityPairs.map((pair) => pair.changeId));
+
+    for (const storyId of storyIds) {
+      if (!tracedStoryIds.has(storyId)) {
+        errors.push(error(
+          'missing_release_story_traceability',
+          `Release story ${storyId} is missing from traceability-matrix.md.`,
+          `Add ${storyId} to a same-line STORY/CHG pair in docs/enterprise/releases/${releaseId}/traceability-matrix.md.`
+        ));
+      }
+    }
+
+    for (const changeId of changeIds) {
+      if (!tracedChangeIds.has(changeId)) {
+        errors.push(error(
+          'missing_release_change_traceability',
+          `Release change ${changeId} is missing from traceability-matrix.md.`,
+          `Add ${changeId} to a same-line STORY/CHG pair in docs/enterprise/releases/${releaseId}/traceability-matrix.md.`
+        ));
+      }
+    }
+  }
+
+  for (const pair of traceabilityPairs) {
+    const story = loadStory(rootDir, pair.storyId);
+    const change = loadChange(rootDir, pair.changeId);
+    if (!story || story.parseError || !change || change.parseError) {
+      continue;
+    }
+
+    const linkedChanges = Array.isArray(story.data.linked_changes) ? story.data.linked_changes : [];
+    const relatedStories = Array.isArray(change.data.related_stories) ? change.data.related_stories : [];
+    if (!linkedChanges.includes(pair.changeId) || !relatedStories.includes(pair.storyId)) {
+      errors.push(error(
+        'mismatched_release_traceability',
+        `Release traceability pairs ${pair.storyId} with ${pair.changeId}, but they are not linked.`,
+        `Update ${story.relativePath} linked_changes and ${change.relativePath} related_stories so the release matrix pair is bidirectional.`
+      ));
+    }
+  }
+
+  for (const storyId of storyIds) {
+    const story = loadStory(rootDir, storyId);
+    if (!story) {
+      errors.push(error(
+        'missing_release_story',
+        `Release story ${storyId} does not exist.`,
+        `Create docs/enterprise/stories/${storyId}-<slug>.md or remove it from release ${releaseId}.`
+      ));
+      continue;
+    }
+
+    if (story.parseError) {
+      errors.push(error(
+        'unparseable_story',
+        `Story ${storyId} could not be parsed: ${story.parseError.message}`,
+        `Fix frontmatter syntax in ${story.relativePath}.`
+      ));
+      continue;
+    }
+
+    errors.push(...validateFeature(rootDir, storyId).errors);
+  }
+
+  for (const changeId of changeIds) {
+    const change = loadChange(rootDir, changeId);
+    if (!change) {
+      errors.push(error(
+        'missing_release_change',
+        `Release change ${changeId} does not exist.`,
+        `Create docs/enterprise/changes/${changeId}-<slug>.md or remove it from release ${releaseId}.`
+      ));
+      continue;
+    }
+
+    if (change.parseError) {
+      errors.push(error(
+        'unparseable_change',
+        `Change ${changeId} could not be parsed: ${change.parseError.message}`,
+        `Fix frontmatter syntax in ${change.relativePath}.`
+      ));
+      continue;
+    }
+
+    if (!RELEASE_CHANGE_STATUSES.has(change.data.status)) {
+      errors.push(error(
+        'unverified_release_change',
+        `${changeId} must be verified before release.`,
+        `Move ${changeId} to verified after verification evidence is complete, or remove it from release ${releaseId}.`
+      ));
+    }
+  }
+
+  return result('release', releaseId, errors);
+}
+
+function listInvalidIdReferences(markdown, prefix, idPattern) {
+  const expression = new RegExp(`\\b${prefix}-[A-Za-z0-9]+\\b`, 'g');
+  const matches = markdown.match(expression) ?? [];
+  return Array.from(new Set(matches.filter((value) => !idPattern.test(value))));
+}
+
+function listReleaseTraceabilityPairs(markdown) {
+  const pairs = new Map();
+  for (const line of markdown.split(/\r?\n/u)) {
+    const storyIds = line.match(/\bSTORY-[0-9]{4}\b/g) ?? [];
+    const changeIds = line.match(/\bCHG-[0-9]{4}\b/g) ?? [];
+    for (const storyId of storyIds) {
+      for (const changeId of changeIds) {
+        pairs.set(`${storyId}:${changeId}`, { storyId, changeId });
+      }
+    }
+  }
+
+  return Array.from(pairs.values());
+}
+
+function isBareNoImpact(value) {
+  const candidates = [
+    value,
+    ...value.split(/\r?\n/u).filter((line) => line.trim())
+  ];
+
+  return candidates.some((candidate) => {
+    const normalized = candidate
+      .toLowerCase()
+      .replace(/^\s*(?:[-*+]|\d+[.)])\s+/u, '')
+      .replace(/[:.。]+$/u, '')
+      .trim();
+    return normalized === 'no impact' || normalized === 'not applicable';
+  });
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function result(gate, target, errors, warnings = []) {
+  return {
+    gate,
+    target,
+    status: errors.length === 0 ? 'pass' : 'fail',
+    errors,
+    warnings,
+    nextActions: errors.map((item) => item.nextAction).filter(Boolean)
+  };
+}
+
+function error(code, message, nextAction) {
+  return { code, message, nextAction };
+}