sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/task-parser.ts

@@ -1,709 +1,738 @@
-import { hashDocumentContent, hashNormalizedMarkdownContent, hashSemanticDocument, hashTasksContract } from './document-hashes.js';
-import { readdir, readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { assertSafePathSegment } from '../path-safety.js';
-import { exists } from '../storage/json-io.js';
-
-export type SddTaskStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'deferred' | 'unknown';
-export type SddChangeSurface = 'frontend_only' | 'backend_only' | 'full_stack' | 'docs_only' | 'config_only' | 'unknown';
-export type SddValidationTiming = 'task_end' | 'batch_end' | 'wave_end';
-export type SddGapSeverity = 'blocking' | 'warning';
-export type SddGapType = 'Document Gap' | 'Task Gap' | 'Dependency Gap';
-
-export interface SddTaskSourceLocation {
-  filePath: string;
-  heading: string | null;
-  lineStart: number;
-  lineEnd: number;
-}
-
-export interface SddValidationCommand {
-  command: string;
-  acceptanceRefs: string[];
-  raw: string;
-}
-
-export interface SddTask {
-  id: string;
-  contractHash: string;
-  title: string | null;
-  status: SddTaskStatus;
-  wave: number | null;
-  implementationWave: string | null;
-  validationBatch: string | null;
-  validationTiming: SddValidationTiming;
-  requiresVerifyBeforeNext: boolean;
-  changeSurface: SddChangeSurface;
-  dependsOn: string[];
-  affectedFiles: string[];
-  validation: string[];
-  validationCommands: SddValidationCommand[];
-  risk: string[];
-  acceptanceRefs: string[];
-  planRefs: string[];
-  fileOwnership: string[];
-  agentFit: string[];
-  verificationAvailability: string[];
-  autonomy: string | null;
-  allowedAgents: string[];
-  requiredArtifacts: string[];
-  gapState: string | null;
-  boundary: string | null;
-  acceptance: string[];
-  implementationNotes: string | null;
-  rawMetadata: Record<string, string | string[]>;
-  source: SddTaskSourceLocation;
-}
-
-export interface SddTaskGap {
-  type: SddGapType;
-  severity: SddGapSeverity;
-  taskId: string | null;
-  field: string;
-  message: string;
-  recommendation: string;
-}
-
-export interface SddTaskModel {
-  branch: string;
-  specPath: string;
-  planPath: string;
-  tasksPath: string;
-  verifyPath: string;
-  documents: {
-    specExists: boolean;
-    planExists: boolean;
-    tasksExists: boolean;
-    verifyExists: boolean;
-    specHash?: string | null;
-    planHash?: string | null;
-    tasksHash?: string | null;
-    verifyHash?: string | null;
-    specDocHash?: string | null;
-    planDocHash?: string | null;
-    tasksDocHash?: string | null;
-    verifyDocHash?: string | null;
-    specContractHash?: string | null;
-    planContractHash?: string | null;
-    tasksContractHash?: string | null;
-    verifyContractHash?: string | null;
-    planBasedOnSpecHash?: string | null;
-    tasksBasedOnPlanHash?: string | null;
-    verifyBasedOnTasksHash?: string | null;
-    planBasedOnSpecContractHash?: string | null;
-    tasksBasedOnPlanContractHash?: string | null;
-    verifyBasedOnTasksContractHash?: string | null;
-    planStale?: boolean;
-    tasksStale?: boolean;
-    verifyStale?: boolean;
-  };
-  tasks: SddTask[];
-  gaps: SddTaskGap[];
-}
-
-export async function parseSddBranch(projectRoot: string, branch = 'master'): Promise<SddTaskModel> {
-  assertSafePathSegment(branch, 'branch');
-  const specPath = path.join(projectRoot, 'specs', branch, 'spec.md');
-  const planPath = path.join(projectRoot, 'specs', branch, 'plan.md');
-  const tasksPath = path.join(projectRoot, 'specs', branch, 'tasks.md');
-  const verifyPath = path.join(projectRoot, 'specs', branch, 'verify.md');
-  const [specExists, planExists, tasksExists, verifyExists] = await Promise.all([exists(specPath), exists(planPath), exists(tasksPath), exists(verifyPath)]);
-  const [rawSpec, rawPlan, rawTasks, rawVerify] = await Promise.all([
-    specExists ? readFile(specPath, 'utf8') : Promise.resolve(null),
-    planExists ? readFile(planPath, 'utf8') : Promise.resolve(null),
-    tasksExists ? readFile(tasksPath, 'utf8') : Promise.resolve(null),
-    verifyExists ? readFile(verifyPath, 'utf8') : Promise.resolve(null)
-  ]);
-  const documents = buildDocumentChainState({ specExists, planExists, tasksExists, verifyExists, rawSpec, rawPlan, rawTasks, rawVerify });
-  const gaps: SddTaskGap[] = [];
-
-  if (!specExists) {
-    gaps.push(documentGap('spec.md', 'Spec document is missing.', 'Create or restore specs/<branch>/spec.md before full SDD execution.'));
-  }
-  if (!planExists) {
-    gaps.push(documentGap('plan.md', 'Plan document is missing.', 'Create or restore specs/<branch>/plan.md before task execution.'));
-  }
-  if (!tasksExists || rawTasks === null) {
-    gaps.push(documentGap('tasks.md', 'Tasks document is missing.', 'Create specs/<branch>/tasks.md with sdd-task fenced blocks.'));
-    return {
-      branch,
-      specPath,
-      planPath,
-      tasksPath,
-      verifyPath,
-      documents,
-      tasks: [],
-      gaps
-    };
-  }
-
-  const taskModel = parseSddTasksMarkdown(rawTasks, { tasksPath });
-  if (taskModel.tasks.length === 0 && !path.basename(tasksPath).startsWith('phase')) {
-    const retainedModel = await parseRetainedPhaseTasks(path.dirname(tasksPath));
-    if (retainedModel.tasks.length > 0) {
-      return {
-        branch,
-        specPath,
-        planPath,
-        tasksPath,
-        verifyPath,
-        documents,
-        tasks: retainedModel.tasks,
-        gaps: [...gaps, ...retainedModel.gaps]
-      };
-    }
-  }
-  return {
-    branch,
-    specPath,
-    planPath,
-    tasksPath,
-    verifyPath,
-    documents,
-    tasks: taskModel.tasks,
-    gaps: [...gaps, ...taskModel.gaps]
-  };
-}
-
-export function parseSddTasksMarkdown(raw: string, options: { branch?: string; tasksPath?: string; validateDependencies?: boolean } = {}): Pick<SddTaskModel, 'tasks' | 'gaps'> {
-  const tasksPath = options.tasksPath ?? 'tasks.md';
-  const fencedBlocks = Array.from(raw.matchAll(/^\s*```sdd-task\s*\r?\n([\s\S]*?)\r?^\s*```\s*$/gm));
-  const tasks: SddTask[] = [];
-  const gaps: SddTaskGap[] = [];
-
-  if (fencedBlocks.length === 0) {
-    gaps.push({
-      type: 'Task Gap',
-      severity: 'blocking',
-      taskId: null,
-      field: 'sdd-task',
-      message: 'No sdd-task fenced blocks found in tasks.md.',
-      recommendation: 'Add one sdd-task fenced block per executable task.'
-    });
-    return { tasks, gaps };
-  }
-
-  const seenIds = new Map<string, SddTaskSourceLocation>();
-  for (let blockIndex = 0; blockIndex < fencedBlocks.length; blockIndex += 1) {
-    const blockMatch = fencedBlocks[blockIndex];
-    const block = blockMatch[1] ?? '';
-    const blockStart = blockMatch.index ?? 0;
-    const blockEnd = blockStart + blockMatch[0].length;
-    const nextBlockStart = fencedBlocks[blockIndex + 1]?.index ?? raw.length;
-    const lineStart = lineNumberAt(raw, blockStart);
-    const lineEnd = lineNumberAt(raw, blockEnd);
-    const heading = nearestTaskHeading(raw.slice(0, blockStart));
-    const metadata = parseSimpleYamlBlock(block);
-    const id = scalarValue(metadata.id);
-    const taskId = id || heading?.id || null;
-    const section = raw.slice(blockEnd, nextTaskStart(raw, blockEnd, nextBlockStart));
-    const parsedSections = parseTaskCompanionSections(section);
-    if (!taskId) {
-      gaps.push({
-        type: 'Task Gap',
-        severity: 'blocking',
-        taskId: null,
-        field: 'id',
-        message: `sdd-task block starting at line ${lineStart} is missing id.`,
-        recommendation: 'Add a stable id field such as id: T1.'
-      });
-      continue;
-    }
-
-    const source: SddTaskSourceLocation = {
-      filePath: tasksPath,
-      heading: heading?.raw ?? null,
-      lineStart,
-      lineEnd
-    };
-    const priorSource = seenIds.get(taskId);
-    if (priorSource) {
-      gaps.push({
-        type: 'Task Gap',
-        severity: 'blocking',
-        taskId,
-        field: 'id',
-        message: `Duplicate task id ${taskId} in ${taskSourceEvidence({ id: taskId, source })} and ${sourceLocationEvidence(priorSource)}.`,
-        recommendation: 'Keep task ids unique within a spec branch.'
-      });
-    }
-    seenIds.set(taskId, source);
-
-    const contractHash = hashTaskContract({ taskId, headingTitle: heading?.title ?? null, metadata, parsedSections });
-    const task: SddTask = {
-      id: taskId,
-      contractHash,
-      title: heading?.title ?? null,
-      status: parseTaskStatus(scalarValue(metadata.status)),
-      wave: parseWave(scalarValue(metadata.wave)),
-      implementationWave: scalarValue(metadata.implementation_wave),
-      validationBatch: scalarValue(metadata.validation_batch),
-      validationTiming: parseValidationTiming(scalarValue(metadata.validation_timing)),
-      requiresVerifyBeforeNext: parseRequiresVerifyBeforeNext(scalarValue(metadata.requires_verify_before_next)),
-      changeSurface: parseChangeSurface(scalarValue(metadata.change_surface)),
-      dependsOn: listValue(metadata.depends_on),
-      affectedFiles: listValue(metadata.affected_files),
-      validation: parseValidationCommands(metadata.validation).map((command) => command.command),
-      validationCommands: parseValidationCommands(metadata.validation),
-      risk: listValue(metadata.risk),
-      acceptanceRefs: listValue(metadata.acceptance_refs),
-      planRefs: listValue(metadata.plan_refs),
-      fileOwnership: listValue(metadata.file_ownership),
-      agentFit: listValue(metadata.agent_fit),
-      verificationAvailability: listValue(metadata.verification_availability),
-      autonomy: scalarValue(metadata.autonomy),
-      allowedAgents: listValue(metadata.allowed_agents),
-      requiredArtifacts: listValue(metadata.required_artifacts),
-      gapState: scalarValue(metadata.gap_state),
-      boundary: parsedSections.boundary,
-      acceptance: parsedSections.acceptance,
-      implementationNotes: parsedSections.implementationNotes,
-      rawMetadata: metadata,
-      source
-    };
-    tasks.push(task);
-    gaps.push(...validateTask(task));
-  }
-
-  if (options.validateDependencies !== false) {
-    gaps.push(...validateAggregateTaskSet(tasks));
-  }
-
-  return { tasks, gaps };
-}
-
-function buildDocumentChainState(input: { specExists: boolean; planExists: boolean; tasksExists: boolean; verifyExists: boolean; rawSpec: string | null; rawPlan: string | null; rawTasks: string | null; rawVerify: string | null }): SddTaskModel['documents'] {
-  const specDocHash = input.rawSpec === null ? null : hashDocumentContent(input.rawSpec);
-  const planDocHash = input.rawPlan === null ? null : hashDocumentContent(input.rawPlan);
-  const tasksDocHash = input.rawTasks === null ? null : hashDocumentContent(input.rawTasks);
-  const verifyDocHash = input.rawVerify === null ? null : hashDocumentContent(input.rawVerify);
-  const specContractHash = hashNormalizedMarkdownContent(input.rawSpec);
-  const planContractHash = hashNormalizedMarkdownContent(input.rawPlan);
-  const tasksContractHash = hashTasksContract(input.rawTasks);
-  const verifyContractHash = hashSemanticDocument(input.rawVerify);
-  const planBasedOnSpecHash = null;
-  const tasksBasedOnPlanHash = null;
-  const verifyBasedOnTasksHash = null;
-  const planBasedOnSpecContractHash = null;
-  const tasksBasedOnPlanContractHash = null;
-  const verifyBasedOnTasksContractHash = null;
-  const planStale = false;
-  const tasksHashMismatch = false;
-  const verifyHashMismatch = false;
-
-  return {
-    specExists: input.specExists,
-    planExists: input.planExists,
-    tasksExists: input.tasksExists,
-    verifyExists: input.verifyExists,
-    specHash: specDocHash,
-    planHash: planDocHash,
-    tasksHash: tasksDocHash,
-    verifyHash: verifyDocHash,
-    specDocHash,
-    planDocHash,
-    tasksDocHash,
-    verifyDocHash,
-    specContractHash,
-    planContractHash,
-    tasksContractHash,
-    verifyContractHash,
-    planBasedOnSpecHash,
-    tasksBasedOnPlanHash,
-    verifyBasedOnTasksHash,
-    planBasedOnSpecContractHash,
-    tasksBasedOnPlanContractHash,
-    verifyBasedOnTasksContractHash,
-    planStale,
-    tasksStale: planStale || tasksHashMismatch,
-    verifyStale: planStale || tasksHashMismatch || verifyHashMismatch
-  };
-}
-
-
-async function parseRetainedPhaseTasks(specBranchDir: string): Promise<Pick<SddTaskModel, 'tasks' | 'gaps'>> {
-  const entries = await readdir(specBranchDir, { withFileTypes: true });
-  const taskFiles = entries
-    .filter((entry) => entry.isFile() && /^phase\d+\.\d+-tasks\.md$/.test(entry.name))
-    .map((entry) => path.join(specBranchDir, entry.name))
-    .sort();
-  const tasks: SddTask[] = [];
-  const gaps: SddTaskGap[] = [];
-  for (const taskFile of taskFiles) {
-    const raw = await readFile(taskFile, 'utf8');
-    const parsed = parseSddTasksMarkdown(raw, { tasksPath: taskFile, validateDependencies: false });
-    tasks.push(...parsed.tasks);
-    gaps.push(...parsed.gaps);
-  }
-  gaps.push(...validateAggregateTaskSet(tasks));
-  return { tasks, gaps };
-}
-
-function documentGap(field: string, message: string, recommendation: string): SddTaskGap {
-  return {
-    type: 'Document Gap',
-    severity: 'blocking',
-    taskId: null,
-    field,
-    message,
-    recommendation
-  };
-}
-
-function parseTaskStatus(value: string | null): SddTaskStatus {
-  if (value === 'pending' || value === 'in_progress' || value === 'completed' || value === 'blocked' || value === 'deferred') {
-    return value;
-  }
-  return 'unknown';
-}
-
-function parseWave(value: string | null): number | null {
-  if (!value) {
-    return null;
-  }
-  const parsed = Number(value);
-  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
-}
-
-function parseChangeSurface(value: string | null): SddChangeSurface {
-  if (value === 'frontend_only' || value === 'backend_only' || value === 'full_stack' || value === 'docs_only' || value === 'config_only' || value === 'unknown') {
-    return value;
-  }
-  return 'unknown';
-}
-
-function parseValidationTiming(value: string | null): SddValidationTiming {
-  if (value === 'batch_end' || value === 'wave_end') {
-    return value;
-  }
-  return 'task_end';
-}
-
-function parseRequiresVerifyBeforeNext(value: string | null): boolean {
-  return value === 'false' ? false : true;
-}
-
-function isValidChangeSurface(value: string | null): boolean {
-  return value === null || value === 'frontend_only' || value === 'backend_only' || value === 'full_stack' || value === 'docs_only' || value === 'config_only' || value === 'unknown';
-}
-
-function isValidValidationTiming(value: string | null): boolean {
-  return value === null || value === 'task_end' || value === 'batch_end' || value === 'wave_end';
-}
-
-function isValidBooleanScalar(value: string | null): boolean {
-  return value === null || value === 'true' || value === 'false';
-}
-
-function parseSimpleYamlBlock(raw: string): Record<string, string | string[]> {
-  const result: Record<string, string | string[]> = {};
-  const lines = raw.split(/\r?\n/);
-  let currentListKey: string | null = null;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) {
-      continue;
-    }
-    if (currentListKey && /^-\s+/.test(trimmed)) {
-      const current = result[currentListKey];
-      const items = Array.isArray(current) ? current : [];
-      items.push(unquoteSimpleYamlValue(trimmed.slice(2).trim()));
-      result[currentListKey] = items;
-      continue;
-    }
-
-    const scalarMatch = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (!scalarMatch) {
-      currentListKey = null;
-      continue;
-    }
-    const key = scalarMatch[1];
-    const value = scalarMatch[2].trim();
-    if (value === '') {
-      result[key] = [];
-      currentListKey = key;
-    } else if (value === '[]') {
-      result[key] = [];
-      currentListKey = null;
-    } else if (value.startsWith('[') && value.endsWith(']')) {
-      result[key] = value.slice(1, -1).split(',').map((item) => unquoteSimpleYamlValue(item.trim())).filter(Boolean);
-      currentListKey = null;
-    } else {
-      result[key] = unquoteSimpleYamlValue(value);
-      currentListKey = null;
-    }
-  }
-
-  return result;
-}
-
-function unquoteSimpleYamlValue(value: string): string {
-  if (value.length >= 2) {
-    const first = value[0];
-    const last = value[value.length - 1];
-    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
-      return value.slice(1, -1);
-    }
-  }
-  return value;
-}
-
-function scalarValue(value: string | string[] | undefined): string | null {
-  return typeof value === 'string' && value.length > 0 ? value : null;
-}
-
-function listValue(value: string | string[] | undefined): string[] {
-  if (Array.isArray(value)) {
-    return value.filter(Boolean);
-  }
-  if (!value || value === '[]') {
-    return [];
-  }
-  return [value];
-}
-
-function parseValidationCommands(value: string | string[] | undefined): SddValidationCommand[] {
-  return listValue(value).map(parseValidationCommand);
-}
-
-function parseValidationCommand(raw: string): SddValidationCommand {
-  const separator = raw.match(/\s=>\s/);
-  if (!separator || separator.index === undefined) {
-    return { command: raw, acceptanceRefs: [], raw };
-  }
-  const command = raw.slice(0, separator.index).trim();
-  const refsRaw = raw.slice(separator.index + separator[0].length).trim();
-  return {
-    command: command || raw,
-    acceptanceRefs: parseAcceptanceRefList(refsRaw),
-    raw
-  };
-}
-
-function parseAcceptanceRefList(raw: string): string[] {
-  const trimmed = raw.replace(/^\[/, '').replace(/\]$/, '').trim();
-  if (!trimmed) {
-    return [];
-  }
-  return trimmed.split(',').map((item) => unquoteSimpleYamlValue(item.trim())).filter(Boolean);
-}
-
-function lineNumberAt(raw: string, offset: number): number {
-  return raw.slice(0, offset).split(/\r?\n/).length;
-}
-
-function nearestTaskHeading(prefix: string): { raw: string; id: string | null; title: string | null } | null {
-  const matches = Array.from(prefix.matchAll(/^\s*#{2,3}\s+(.+)$/gm));
-  const last = matches.at(-1);
-  if (!last) {
-    return null;
-  }
-  const raw = last[1].trim();
-  const parsed = raw.match(/^([^:：\s]+)\s*[:：]\s*(.+)$/);
-  return {
-    raw,
-    id: parsed?.[1]?.trim() ?? null,
-    title: parsed?.[2]?.trim() ?? raw
-  };
-}
-
-function nextTaskStart(raw: string, offset: number, limit = raw.length): number {
-  const next = raw.slice(offset, limit).search(/^\s*#{2,3}\s+/m);
-  return next < 0 ? limit : offset + next;
-}
-
-function parseTaskCompanionSections(raw: string): { boundary: string | null; acceptance: string[]; implementationNotes: string | null } {
-  return {
-    boundary: sectionText(raw, 'Boundary'),
-    acceptance: sectionBullets(raw, 'Acceptance'),
-    implementationNotes: sectionText(raw, 'Implementation Notes')
-  };
-}
-
-function hashTaskContract(input: { taskId: string; headingTitle: string | null; metadata: Record<string, string | string[]>; parsedSections: { boundary: string | null; acceptance: string[]; implementationNotes: string | null } }): string {
-  return hashDocumentContent(JSON.stringify({
-    id: input.taskId,
-    title: input.headingTitle,
-    metadata: {
-      id: normalizedTaskContractValue(input.metadata.id),
-      wave: normalizedTaskContractValue(input.metadata.wave),
-      depends_on: normalizedTaskContractValue(input.metadata.depends_on),
-      acceptance_refs: normalizedTaskContractValue(input.metadata.acceptance_refs),
-      plan_refs: normalizedTaskContractValue(input.metadata.plan_refs),
-      affected_files: normalizedTaskContractValue(input.metadata.affected_files),
-      change_surface: normalizedTaskContractValue(input.metadata.change_surface),
-      implementation_wave: normalizedTaskContractValue(input.metadata.implementation_wave),
-      validation_batch: normalizedTaskContractValue(input.metadata.validation_batch),
-      validation_timing: normalizedTaskContractValue(input.metadata.validation_timing),
-      requires_verify_before_next: normalizedTaskContractValue(input.metadata.requires_verify_before_next),
-      validation: normalizedTaskContractValue(input.metadata.validation),
-      risk: normalizedTaskContractValue(input.metadata.risk),
-      required_artifacts: normalizedTaskContractValue(input.metadata.required_artifacts),
-      allowed_agents: normalizedTaskContractValue(input.metadata.allowed_agents),
-      verification_availability: normalizedTaskContractValue(input.metadata.verification_availability),
-      autonomy: normalizedTaskContractValue(input.metadata.autonomy),
-      validation_wave: normalizedTaskContractValue(input.metadata.validation_wave),
-      review_gate: normalizedTaskContractValue(input.metadata.review_gate)
-    },
-    sections: input.parsedSections
-  }));
-}
-
-function normalizedTaskContractValue(value: string | string[] | undefined): string | string[] | null {
-  if (Array.isArray(value)) {
-    return value.map((item) => item.trim()).filter(Boolean);
-  }
-  if (typeof value === 'string') {
-    const trimmed = value.trim();
-    return trimmed ? trimmed : null;
-  }
-  return null;
-}
-
-function sectionText(raw: string, title: string): string | null {
-  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const sectionPattern = `^\\s*####\\s+${escaped}\\s*$([\\s\\S]*?)(?=^\\s*####\\s+|^\\s*#{2,3}\\s+|$(?![\\s\\S]))`;
-  const match = raw.match(new RegExp(sectionPattern, 'im'));
-  const text = match?.[1]?.trim() ?? '';
-  return text.length > 0 ? text : null;
-}
-
-function sectionBullets(raw: string, title: string): string[] {
-  const text = sectionText(raw, title);
-  if (!text) {
-    return [];
-  }
-  return text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith('- ')).map((line) => line.slice(2).trim()).filter(Boolean);
-}
-
-function validateTask(task: SddTask): SddTaskGap[] {
-  const gaps: SddTaskGap[] = [];
-  const requiredLists: Array<[keyof SddTask, string]> = [
-    ['affectedFiles', 'affected_files'],
-    ['validation', 'validation']
-  ];
-
-  if (task.status === 'unknown') {
-    gaps.push(taskGap(task.id, 'status', 'Task status is missing or unsupported.', 'Use one of pending, in_progress, completed, blocked, deferred.'));
-  }
-  if (task.wave === null) {
-    gaps.push(taskGap(task.id, 'wave', 'Task wave is missing or invalid.', 'Add a positive integer wave value.'));
-  }
-  if (!isValidChangeSurface(scalarValue(task.rawMetadata.change_surface))) {
-    gaps.push(taskGap(task.id, 'change_surface', `Task ${task.id} has invalid change_surface.`, 'Use one of frontend_only, backend_only, full_stack, docs_only, config_only, unknown.'));
-  }
-  if (!isValidValidationTiming(scalarValue(task.rawMetadata.validation_timing))) {
-    gaps.push(taskGap(task.id, 'validation_timing', `Task ${task.id} has invalid validation_timing.`, 'Use one of task_end, batch_end, wave_end.'));
-  }
-  if (!isValidBooleanScalar(scalarValue(task.rawMetadata.requires_verify_before_next))) {
-    gaps.push(taskGap(task.id, 'requires_verify_before_next', `Task ${task.id} has invalid requires_verify_before_next.`, 'Use true or false.'));
-  }
-  if ((task.validationTiming === 'batch_end' || task.validationTiming === 'wave_end') && !task.validationBatch) {
-    gaps.push(taskGap(task.id, 'validation_batch', `Task ${task.id} uses ${task.validationTiming} but has no validation_batch.`, 'Declare validation_batch so batch/wave validation can group implementation evidence before /sdd:test.'));
-  }
-  if ((task.validationTiming === 'batch_end' || task.validationTiming === 'wave_end') && task.requiresVerifyBeforeNext) {
-    gaps.push(taskGap(task.id, 'requires_verify_before_next', `Task ${task.id} uses ${task.validationTiming} but requires verify before next.`, 'Set requires_verify_before_next: false for batch/wave validation, or use validation_timing: task_end for strict validation.'));
-  }
-  for (const [property, field] of requiredLists) {
-    if ((task[property] as unknown[]).length === 0) {
-      gaps.push(taskGap(task.id, field, `Task ${task.id} has no ${field}.`, `Declare ${field} in the sdd-task block before implementation.`));
-    }
-  }
-  if ((task.changeSurface === 'frontend_only' || isFrontendOnlyTask(task)) && task.validation.some(isBackendBuildValidationCommand)) {
-    gaps.push(taskGap(task.id, 'validation', `Task ${task.id} is frontend-only but declares backend build validation.`, 'For JSP/static frontend-only changes, replace Maven/Gradle validation with frontend-appropriate checks, dev-server/manual page evidence, lint/typecheck, or an explicit unavailable reason.'));
-  }
-  if (!task.boundary) {
-    gaps.push(taskGap(task.id, 'Boundary', `Task ${task.id} has no Boundary section.`, 'Add a #### Boundary section describing allowed and forbidden scope.'));
-  }
-  if (task.acceptance.length === 0) {
-    gaps.push(taskGap(task.id, 'Acceptance', `Task ${task.id} has no acceptance items.`, 'Add verifiable bullets under #### Acceptance.'));
-  }
-  return gaps;
-}
-
-export function isFrontendOnlyTask(task: SddTask): boolean {
-  return task.affectedFiles.length > 0 && task.affectedFiles.every(isFrontendOnlyPath);
-}
-
-function isFrontendOnlyPath(filePath: string): boolean {
-  const normalized = filePath.toLowerCase().replace(/\\/g, '/');
-  return /\.(jsp|html|htm|css|scss|sass|less|js|jsx|ts|tsx|vue|svelte|png|jpg|jpeg|gif|svg|webp|ico)$/.test(normalized)
-    && !normalized.includes('/src/main/java/')
-    && !normalized.includes('/src/test/java/')
-    && !normalized.includes('/pom.xml')
-    && !normalized.endsWith('pom.xml')
-    && !normalized.endsWith('build.gradle')
-    && !normalized.endsWith('build.gradle.kts');
-}
-
-export function isBackendBuildValidationCommand(command: string): boolean {
-  return /(^|\s)(mvn|maven|mvnw|\.\/mvnw|gradle|gradlew|\.\/gradlew)(\s|$)|\b(maven_compile|gradle_build)\b/i.test(command);
-}
-
-function taskGap(taskId: string, field: string, message: string, recommendation: string): SddTaskGap {
-  return {
-    type: 'Task Gap',
-    severity: 'blocking',
-    taskId,
-    field,
-    message,
-    recommendation
-  };
-}
-
-function validateAggregateTaskSet(tasks: SddTask[]): SddTaskGap[] {
-  const gaps: SddTaskGap[] = [];
-  const tasksById = new Map<string, SddTask[]>();
-  for (const task of tasks) {
-    const matchingTasks = tasksById.get(task.id) ?? [];
-    matchingTasks.push(task);
-    tasksById.set(task.id, matchingTasks);
-  }
-
-  for (const [taskId, matchingTasks] of tasksById) {
-    if (matchingTasks.length > 1) {
-      gaps.push(taskGap(
-        taskId,
-        'id',
-        `Duplicate task id ${taskId} across parsed task files: ${matchingTasks.map(taskSourceEvidence).join('; ')}.`,
-        'Rename duplicate task ids or add deterministic source disambiguation before implementation.'
-      ));
-    }
-  }
-
-  for (const task of tasks) {
-    for (const dependency of task.dependsOn) {
-      const matchingDependencies = tasksById.get(dependency) ?? [];
-      if (matchingDependencies.length === 0) {
-        gaps.push({
-          type: 'Dependency Gap',
-          severity: 'blocking',
-          taskId: task.id,
-          field: 'depends_on',
-          message: `Task ${task.id} depends on unknown task ${dependency}.`,
-          recommendation: 'Fix depends_on to reference an existing task id, or add the missing task.'
-        });
-      } else if (matchingDependencies.length > 1) {
-        gaps.push({
-          type: 'Dependency Gap',
-          severity: 'blocking',
-          taskId: task.id,
-          field: 'depends_on',
-          message: `Task ${task.id} depends on ambiguous duplicate task id ${dependency}: ${matchingDependencies.map(taskSourceEvidence).join('; ')}.`,
-          recommendation: 'Rename duplicate task ids so dependencies resolve to one task.'
-        });
-      }
-    }
-  }
-
-  return gaps;
-}
-
-function taskSourceEvidence(task: Pick<SddTask, 'id' | 'source'>): string {
-  return `${task.id} at ${sourceLocationEvidence(task.source)}`;
-}
-
-function sourceLocationEvidence(source: SddTaskSourceLocation): string {
-  return `${source.filePath}:${source.lineStart}-${source.lineEnd}`;
-}
+import { hashDocumentContent, hashSemanticDocument, hashTasksContract, documentHashMatches } from './document-hashes.js';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { assertSafePathSegment } from '../path-safety.js';
+import { exists } from '../storage/json-io.js';
+
+export type SddTaskStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'deferred' | 'unknown';
+export type SddChangeSurface = 'frontend_only' | 'backend_only' | 'full_stack' | 'docs_only' | 'config_only' | 'cli_only' | 'unknown';
+export type SddValidationTiming = 'task_end' | 'batch_end' | 'wave_end';
+export type SddGapSeverity = 'blocking' | 'warning';
+export type SddGapType = 'Document Gap' | 'Task Gap' | 'Dependency Gap';
+
+export type SddTaskClass = 'implementation' | 'validation';
+export interface SddTaskSourceLocation {
+  filePath: string;
+  heading: string | null;
+  lineStart: number;
+  lineEnd: number;
+}
+
+export interface SddValidationCommand {
+  command: string;
+  acceptanceRefs: string[];
+  raw: string;
+}
+
+export interface SddTask {
+  id: string;
+  title: string | null;
+  status: SddTaskStatus;
+  wave: number | null;
+  taskClass: SddTaskClass | null;
+  unitType: string | null;
+  implementationWave: string | null;
+  validationBatch: string | null;
+  validationTiming: SddValidationTiming;
+  requiresVerifyBeforeNext: boolean;
+  changeSurface: SddChangeSurface;
+  dependsOn: string[];
+  validationHandoff: string[];
+  affectedFiles: string[];
+  validation: string[];
+  validationCommands: SddValidationCommand[];
+  risk: string[];
+  acceptanceRefs: string[];
+  planRefs: string[];
+  fileOwnership: string[];
+  agentFit: string[];
+  verificationAvailability: string[];
+  autonomy: string | null;
+  allowedAgents: string[];
+  requiredArtifacts: string[];
+  gapState: string | null;
+  boundary: string | null;
+  acceptance: string[];
+  implementationNotes: string | null;
+  rawMetadata: Record<string, string | string[]>;
+  source: SddTaskSourceLocation;
+}
+
+export interface SddTaskGap {
+  type: SddGapType;
+  severity: SddGapSeverity;
+  taskId: string | null;
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface SddTaskModel {
+  branch: string;
+  specPath: string;
+  planPath: string;
+  tasksPath: string;
+  verifyPath: string;
+  documents: {
+    specExists: boolean;
+    planExists: boolean;
+    tasksExists: boolean;
+    verifyExists: boolean;
+    specHash?: string | null;
+    planHash?: string | null;
+    tasksHash?: string | null;
+    verifyHash?: string | null;
+    specDocHash?: string | null;
+    planDocHash?: string | null;
+    tasksDocHash?: string | null;
+    verifyDocHash?: string | null;
+    specContractHash?: string | null;
+    planContractHash?: string | null;
+    tasksContractHash?: string | null;
+    verifyContractHash?: string | null;
+    planBasedOnSpecHash?: string | null;
+    tasksBasedOnPlanHash?: string | null;
+    verifyBasedOnTasksHash?: string | null;
+    planBasedOnSpecContractHash?: string | null;
+    tasksBasedOnPlanContractHash?: string | null;
+    verifyBasedOnTasksContractHash?: string | null;
+    planStale?: boolean;
+    tasksStale?: boolean;
+    verifyStale?: boolean;
+  };
+  tasks: SddTask[];
+  gaps: SddTaskGap[];
+}
+
+export async function parseSddBranch(projectRoot: string, branch = 'master'): Promise<SddTaskModel> {
+  assertSafePathSegment(branch, 'branch');
+  const specPath = path.join(projectRoot, 'specs', branch, 'spec.md');
+  const planPath = path.join(projectRoot, 'specs', branch, 'plan.md');
+  const tasksPath = path.join(projectRoot, 'specs', branch, 'tasks.md');
+  const verifyPath = path.join(projectRoot, 'specs', branch, 'verify.md');
+  const [specExists, planExists, tasksExists, verifyExists] = await Promise.all([exists(specPath), exists(planPath), exists(tasksPath), exists(verifyPath)]);
+  const [rawSpec, rawPlan, rawTasks, rawVerify] = await Promise.all([
+    specExists ? readFile(specPath, 'utf8') : Promise.resolve(null),
+    planExists ? readFile(planPath, 'utf8') : Promise.resolve(null),
+    tasksExists ? readFile(tasksPath, 'utf8') : Promise.resolve(null),
+    verifyExists ? readFile(verifyPath, 'utf8') : Promise.resolve(null)
+  ]);
+  const documents = buildDocumentChainState({ specExists, planExists, tasksExists, verifyExists, rawSpec, rawPlan, rawTasks, rawVerify });
+  const gaps: SddTaskGap[] = [];
+
+  if (documents.planStale) {
+    gaps.push(documentGap('plan.md', `Plan document is stale because based_on_spec_hash ${documents.planBasedOnSpecHash} no longer matches current spec hash ${documents.specHash}.`, 'Refresh the plan stage for this partition before updating tasks or executing implementation.'));
+  }
+  if (documents.tasksStale) {
+    gaps.push(documentGap('tasks.md', `Tasks document is stale because based_on_plan_hash ${documents.tasksBasedOnPlanHash} no longer matches current plan hash ${documents.planHash}.`, 'Refresh the tasks stage for this partition before executing implementation.'));
+  }
+
+  if (!specExists) {
+    gaps.push(documentGap('spec.md', 'Spec document is missing.', 'Create or restore specs/<branch>/spec.md before full SDD execution.'));
+  }
+  if (!planExists) {
+    gaps.push(documentGap('plan.md', 'Plan document is missing.', 'Create or restore specs/<branch>/plan.md before task execution.'));
+  }
+  if (!tasksExists || rawTasks === null) {
+    gaps.push(documentGap('tasks.md', 'Tasks document is missing.', 'Create specs/<branch>/tasks.md with sdd-task fenced blocks.'));
+    return {
+      branch,
+      specPath,
+      planPath,
+      tasksPath,
+      verifyPath,
+      documents,
+      tasks: [],
+      gaps
+    };
+  }
+
+  const taskModel = parseSddTasksMarkdown(rawTasks, { tasksPath });
+  if (taskModel.tasks.length === 0 && !path.basename(tasksPath).startsWith('phase')) {
+    const retainedModel = await parseRetainedPhaseTasks(path.dirname(tasksPath));
+    if (retainedModel.tasks.length > 0) {
+      return {
+        branch,
+        specPath,
+        planPath,
+        tasksPath,
+        verifyPath,
+        documents,
+        tasks: retainedModel.tasks,
+        gaps: [...gaps, ...retainedModel.gaps]
+      };
+    }
+  }
+  return {
+    branch,
+    specPath,
+    planPath,
+    tasksPath,
+    verifyPath,
+    documents,
+    tasks: taskModel.tasks,
+    gaps: [...gaps, ...taskModel.gaps]
+  };
+}
+
+export function parseSddTasksMarkdown(raw: string, options: { branch?: string; tasksPath?: string; validateDependencies?: boolean } = {}): Pick<SddTaskModel, 'tasks' | 'gaps'> {
+  const tasksPath = options.tasksPath ?? 'tasks.md';
+  const fencedBlocks = Array.from(raw.matchAll(/^\s*```sdd-task\s*\r?\n([\s\S]*?)\r?^\s*```\s*$/gm));
+  const tasks: SddTask[] = [];
+  const gaps: SddTaskGap[] = [];
+
+  if (fencedBlocks.length === 0) {
+    gaps.push({
+      type: 'Task Gap',
+      severity: 'blocking',
+      taskId: null,
+      field: 'sdd-task',
+      message: 'No sdd-task fenced blocks found in tasks.md.',
+      recommendation: 'Add one sdd-task fenced block per executable task.'
+    });
+    return { tasks, gaps };
+  }
+
+  const seenIds = new Map<string, SddTaskSourceLocation>();
+  for (let blockIndex = 0; blockIndex < fencedBlocks.length; blockIndex += 1) {
+    const blockMatch = fencedBlocks[blockIndex];
+    const block = blockMatch[1] ?? '';
+    const blockStart = blockMatch.index ?? 0;
+    const blockEnd = blockStart + blockMatch[0].length;
+    const nextBlockStart = fencedBlocks[blockIndex + 1]?.index ?? raw.length;
+    const lineStart = lineNumberAt(raw, blockStart);
+    const lineEnd = lineNumberAt(raw, blockEnd);
+    const heading = nearestTaskHeading(raw.slice(0, blockStart));
+    const metadata = parseSimpleYamlBlock(block);
+    const id = scalarValue(metadata.id);
+    const taskId = id || heading?.id || null;
+    const section = raw.slice(blockEnd, nextTaskStart(raw, blockEnd, nextBlockStart));
+    const parsedSections = parseTaskCompanionSections(section);
+    if (!taskId) {
+      gaps.push({
+        type: 'Task Gap',
+        severity: 'blocking',
+        taskId: null,
+        field: 'id',
+        message: `sdd-task block starting at line ${lineStart} is missing id.`,
+        recommendation: 'Add a stable id field such as id: T1.'
+      });
+      continue;
+    }
+
+    const source: SddTaskSourceLocation = {
+      filePath: tasksPath,
+      heading: heading?.raw ?? null,
+      lineStart,
+      lineEnd
+    };
+    const priorSource = seenIds.get(taskId);
+    if (priorSource) {
+      gaps.push({
+        type: 'Task Gap',
+        severity: 'blocking',
+        taskId,
+        field: 'id',
+        message: `Duplicate task id ${taskId} in ${taskSourceEvidence({ id: taskId, source })} and ${sourceLocationEvidence(priorSource)}.`,
+        recommendation: 'Keep task ids unique within a spec branch.'
+      });
+    }
+    seenIds.set(taskId, source);
+
+    const task: SddTask = {
+      id: taskId,
+      title: heading?.title ?? null,
+      status: parseTaskStatus(scalarValue(metadata.status)),
+      wave: parseWave(scalarValue(metadata.wave)),
+      taskClass: parseTaskClass(scalarByNames(metadata, ['taskClass', 'task_class'])),
+      unitType: scalarByNames(metadata, ['unitType', 'unit_type']),
+      implementationWave: scalarValue(metadata.implementation_wave),
+      validationBatch: scalarValue(metadata.validation_batch),
+      validationTiming: parseValidationTiming(scalarValue(metadata.validation_timing)),
+      requiresVerifyBeforeNext: parseRequiresVerifyBeforeNext(scalarValue(metadata.requires_verify_before_next)),
+      changeSurface: parseChangeSurface(scalarValue(metadata.change_surface)),
+      dependsOn: listByNames(metadata, ['depends_on', 'dependencies', 'dependsOn']),
+      validationHandoff: listByNames(metadata, ['validationHandoff', 'validation_handoff', 'validationTasks', 'validation_tasks']),
+      affectedFiles: listByNames(metadata, ['affected_files', 'touches', 'affectedFiles']),
+      validation: parseValidationCommands(metadata.validation ?? metadata.completionEvidence ?? metadata.completion_evidence).map((command) => command.command),
+      validationCommands: parseValidationCommands(metadata.validation ?? metadata.completionEvidence ?? metadata.completion_evidence),
+      risk: listValue(metadata.risk),
+      acceptanceRefs: listByNames(metadata, ['acceptance_refs', 'sourceAcceptanceCriteria', 'source_acceptance_criteria']),
+      planRefs: listByNames(metadata, ['plan_refs', 'planRefs']),
+      fileOwnership: listByNames(metadata, ['file_ownership', 'primaryWritableOwnership', 'primary_writable_ownership']),
+      agentFit: listValue(metadata.agent_fit),
+      verificationAvailability: listValue(metadata.verification_availability),
+      autonomy: scalarValue(metadata.autonomy),
+      allowedAgents: listValue(metadata.allowed_agents),
+      requiredArtifacts: listValue(metadata.required_artifacts),
+      gapState: scalarValue(metadata.gap_state),
+      boundary: parsedSections.boundary,
+      acceptance: parsedSections.acceptance,
+      implementationNotes: parsedSections.implementationNotes,
+      rawMetadata: metadata,
+      source
+    };
+    tasks.push(task);
+    gaps.push(...validateTask(task));
+  }
+
+  if (options.validateDependencies !== false) {
+    gaps.push(...validateAggregateTaskSet(tasks));
+  }
+
+  return { tasks, gaps };
+}
+
+function buildDocumentChainState(input: { specExists: boolean; planExists: boolean; tasksExists: boolean; verifyExists: boolean; rawSpec: string | null; rawPlan: string | null; rawTasks: string | null; rawVerify: string | null }): SddTaskModel['documents'] {
+  const specDocHash = input.rawSpec === null ? null : hashDocumentContent(input.rawSpec);
+  const planDocHash = input.rawPlan === null ? null : hashDocumentContent(input.rawPlan);
+  const tasksDocHash = input.rawTasks === null ? null : hashDocumentContent(input.rawTasks);
+  const verifyDocHash = input.rawVerify === null ? null : hashDocumentContent(input.rawVerify);
+  const specContractHash = hashSemanticDocument(input.rawSpec);
+  const planContractHash = hashSemanticDocument(input.rawPlan);
+  const tasksContractHash = hashTasksContract(input.rawTasks);
+  const verifyContractHash = hashSemanticDocument(input.rawVerify);
+  const planBasedOnSpecHash = input.rawPlan === null ? null : readDocumentScalar(input.rawPlan, 'based_on_spec_hash');
+  const tasksBasedOnPlanHash = input.rawTasks === null ? null : readDocumentScalar(input.rawTasks, 'based_on_plan_hash');
+  const verifyBasedOnTasksHash = input.rawVerify === null ? null : readDocumentScalar(input.rawVerify, 'based_on_tasks_hash');
+  const planBasedOnSpecContractHash = input.rawPlan === null ? null : readDocumentScalar(input.rawPlan, 'based_on_spec_contract_hash');
+  const tasksBasedOnPlanContractHash = input.rawTasks === null ? null : readDocumentScalar(input.rawTasks, 'based_on_plan_contract_hash');
+  const verifyBasedOnTasksContractHash = input.rawVerify === null ? null : readDocumentScalar(input.rawVerify, 'based_on_tasks_contract_hash');
+
+  const planStale = Boolean(
+    (planBasedOnSpecContractHash && specContractHash && !documentHashMatches(planBasedOnSpecContractHash, specContractHash))
+    || (!planBasedOnSpecContractHash && planBasedOnSpecHash && specDocHash && !documentHashMatches(planBasedOnSpecHash, specDocHash))
+  );
+  const tasksHashMismatch = Boolean(
+    (tasksBasedOnPlanContractHash && planContractHash && !documentHashMatches(tasksBasedOnPlanContractHash, planContractHash))
+    || (!tasksBasedOnPlanContractHash && tasksBasedOnPlanHash && planDocHash && !documentHashMatches(tasksBasedOnPlanHash, planDocHash))
+  );
+  const verifyHashMismatch = false;
+
+  return {
+    specExists: input.specExists,
+    planExists: input.planExists,
+    tasksExists: input.tasksExists,
+    verifyExists: input.verifyExists,
+    specHash: specDocHash,
+    planHash: planDocHash,
+    tasksHash: tasksDocHash,
+    verifyHash: verifyDocHash,
+    specDocHash,
+    planDocHash,
+    tasksDocHash,
+    verifyDocHash,
+    specContractHash,
+    planContractHash,
+    tasksContractHash,
+    verifyContractHash,
+    planBasedOnSpecHash,
+    tasksBasedOnPlanHash,
+    verifyBasedOnTasksHash,
+    planBasedOnSpecContractHash,
+    tasksBasedOnPlanContractHash,
+    verifyBasedOnTasksContractHash,
+    planStale,
+    tasksStale: planStale || tasksHashMismatch,
+    verifyStale: planStale || tasksHashMismatch || verifyHashMismatch
+  };
+}
+
+function readDocumentScalar(raw: string, key: string): string | null {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = raw.match(new RegExp(`^\\s*(?:-\\s*)?${escapedKey}:\\s*(.+?)\\s*$`, 'm'));
+  return match?.[1]?.trim().replace(/^["'`]|["'`]$/g, '') ?? null;
+}
+
+async function parseRetainedPhaseTasks(specBranchDir: string): Promise<Pick<SddTaskModel, 'tasks' | 'gaps'>> {
+  const entries = await readdir(specBranchDir, { withFileTypes: true });
+  const taskFiles = entries
+    .filter((entry) => entry.isFile() && /^phase\d+\.\d+-tasks\.md$/.test(entry.name))
+    .map((entry) => path.join(specBranchDir, entry.name))
+    .sort();
+  const tasks: SddTask[] = [];
+  const gaps: SddTaskGap[] = [];
+  for (const taskFile of taskFiles) {
+    const raw = await readFile(taskFile, 'utf8');
+    const parsed = parseSddTasksMarkdown(raw, { tasksPath: taskFile, validateDependencies: false });
+    tasks.push(...parsed.tasks);
+    gaps.push(...parsed.gaps);
+  }
+  gaps.push(...validateAggregateTaskSet(tasks));
+  return { tasks, gaps };
+}
+
+function documentGap(field: string, message: string, recommendation: string): SddTaskGap {
+  return {
+    type: 'Document Gap',
+    severity: 'blocking',
+    taskId: null,
+    field,
+    message,
+    recommendation
+  };
+}
+
+function parseTaskStatus(value: string | null): SddTaskStatus {
+  if (value === 'pending' || value === 'in_progress' || value === 'completed' || value === 'blocked' || value === 'deferred') {
+    return value;
+  }
+  return 'unknown';
+}
+
+function parseWave(value: string | null): number | null {
+  if (!value) {
+    return null;
+  }
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parseChangeSurface(value: string | null): SddChangeSurface {
+  if (value === 'frontend_only' || value === 'backend_only' || value === 'full_stack' || value === 'docs_only' || value === 'config_only' || value === 'cli_only' || value === 'unknown') {
+    return value;
+  }
+  return 'unknown';
+}
+function parseTaskClass(value: string | null): SddTaskClass | null {
+  return value === 'implementation' || value === 'validation' ? value : null;
+}
+
+function parseValidationTiming(value: string | null): SddValidationTiming {
+  if (value === 'batch_end' || value === 'wave_end') {
+    return value;
+  }
+  return 'task_end';
+}
+
+function parseRequiresVerifyBeforeNext(value: string | null): boolean {
+  return value === 'false' ? false : true;
+}
+
+function isValidChangeSurface(value: string | null): boolean {
+  return value === null || value === 'frontend_only' || value === 'backend_only' || value === 'full_stack' || value === 'docs_only' || value === 'config_only' || value === 'cli_only' || value === 'unknown';
+}
+
+function isValidValidationTiming(value: string | null): boolean {
+  return value === null || value === 'task_end' || value === 'batch_end' || value === 'wave_end';
+}
+
+function isValidBooleanScalar(value: string | null): boolean {
+  return value === null || value === 'true' || value === 'false';
+}
+
+function parseSimpleYamlBlock(raw: string): Record<string, string | string[]> {
+  const result: Record<string, string | string[]> = {};
+  const lines = raw.split(/\r?\n/);
+  let currentListKey: string | null = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    if (currentListKey && /^-\s+/.test(trimmed)) {
+      const current = result[currentListKey];
+      const items = Array.isArray(current) ? current : [];
+      items.push(unquoteSimpleYamlValue(trimmed.slice(2).trim()));
+      result[currentListKey] = items;
+      continue;
+    }
+
+    const scalarMatch = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!scalarMatch) {
+      currentListKey = null;
+      continue;
+    }
+    const key = scalarMatch[1];
+    const value = scalarMatch[2].trim();
+    if (value === '') {
+      result[key] = [];
+      currentListKey = key;
+    } else if (value === '[]') {
+      result[key] = [];
+      currentListKey = null;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      result[key] = value.slice(1, -1).split(',').map((item) => unquoteSimpleYamlValue(item.trim())).filter(Boolean);
+      currentListKey = null;
+    } else {
+      result[key] = unquoteSimpleYamlValue(value);
+      currentListKey = null;
+    }
+  }
+
+  return result;
+}
+
+function unquoteSimpleYamlValue(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function scalarValue(value: string | string[] | undefined): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function listValue(value: string | string[] | undefined): string[] {
+  if (Array.isArray(value)) {
+    return value.filter(Boolean);
+  }
+  if (!value || value === '[]') {
+    return [];
+  }
+  return [value];
+}
+
+function scalarByNames(metadata: Record<string, string | string[]>, names: string[]): string | null {
+  for (const name of names) {
+    const value = scalarValue(metadata[name]);
+    if (value) {
+      return value;
+    }
+  }
+  return null;
+}
+
+function listByNames(metadata: Record<string, string | string[]>, names: string[]): string[] {
+  for (const name of names) {
+    const value = listValue(metadata[name]);
+    if (value.length > 0) {
+      return value;
+    }
+  }
+  return [];
+}
+
+function parseValidationCommands(value: string | string[] | undefined): SddValidationCommand[] {
+  return listValue(value).map(parseValidationCommand);
+}
+
+function parseValidationCommand(raw: string): SddValidationCommand {
+  const separator = raw.match(/\s=>\s/);
+  if (!separator || separator.index === undefined) {
+    return { command: raw, acceptanceRefs: [], raw };
+  }
+  const command = raw.slice(0, separator.index).trim();
+  const refsRaw = raw.slice(separator.index + separator[0].length).trim();
+  return {
+    command: command || raw,
+    acceptanceRefs: parseAcceptanceRefList(refsRaw),
+    raw
+  };
+}
+
+function parseAcceptanceRefList(raw: string): string[] {
+  const trimmed = raw.replace(/^\[/, '').replace(/\]$/, '').trim();
+  if (!trimmed) {
+    return [];
+  }
+  return trimmed.split(',').map((item) => unquoteSimpleYamlValue(item.trim())).filter(Boolean);
+}
+
+function lineNumberAt(raw: string, offset: number): number {
+  return raw.slice(0, offset).split(/\r?\n/).length;
+}
+
+function nearestTaskHeading(prefix: string): { raw: string; id: string | null; title: string | null } | null {
+  const matches = Array.from(prefix.matchAll(/^\s*###\s+(.+)$/gm));
+  const last = matches.at(-1);
+  if (!last) {
+    return null;
+  }
+  const raw = last[1].trim();
+  const parsed = raw.match(/^([^:：\s]+)\s*[:：]\s*(.+)$/);
+  return {
+    raw,
+    id: parsed?.[1]?.trim() ?? null,
+    title: parsed?.[2]?.trim() ?? raw
+  };
+}
+
+function nextTaskStart(raw: string, offset: number, limit = raw.length): number {
+  const next = raw.slice(offset, limit).search(/^\s*###\s+/m);
+  return next < 0 ? limit : offset + next;
+}
+
+function parseTaskCompanionSections(raw: string): { boundary: string | null; acceptance: string[]; implementationNotes: string | null } {
+  return {
+    boundary: sectionText(raw, 'Boundary'),
+    acceptance: sectionBullets(raw, 'Acceptance'),
+    implementationNotes: sectionText(raw, 'Implementation Notes')
+  };
+}
+
+function sectionText(raw: string, title: string): string | null {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const sectionPattern = `^\\s*####\\s+${escaped}\\s*$([\\s\\S]*?)(?=^\\s*####\\s+|^\\s*###\\s+|^\\s*##\\s+|$(?![\\s\\S]))`;
+  const match = raw.match(new RegExp(sectionPattern, 'im'));
+  const text = match?.[1]?.trim() ?? '';
+  return text.length > 0 ? text : null;
+}
+
+function sectionBullets(raw: string, title: string): string[] {
+  const text = sectionText(raw, title);
+  if (!text) {
+    return [];
+  }
+  return text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith('- ')).map((line) => line.slice(2).trim()).filter(Boolean);
+}
+
+function validateTask(task: SddTask): SddTaskGap[] {
+  const gaps: SddTaskGap[] = [];
+  const isV3Task = Boolean(scalarValue(task.rawMetadata.workType) || scalarValue(task.rawMetadata.work_type));
+
+  if (task.status === 'unknown') {
+    gaps.push(taskGap(task.id, 'status', 'Task status is missing or unsupported.', 'Use one of pending, in_progress, completed, blocked, deferred.'));
+  }
+  if (task.wave === null) {
+    gaps.push(taskGap(task.id, 'wave', 'Task wave is missing or invalid.', 'Add a positive integer wave value.'));
+  }
+
+  if (isV3Task) {
+    const requiredV3Lists: Array<[string[], string]> = [
+      [['primaryWritableOwnership', 'primary_writable_ownership'], 'primaryWritableOwnership'],
+      [['touches', 'affectedFiles', 'affected_files'], 'touches'],
+      [['completionEvidence', 'completion_evidence'], 'completionEvidence']
+    ];
+    for (const [names, field] of requiredV3Lists) {
+      if (listByNames(task.rawMetadata, names).length === 0) {
+        gaps.push(taskGap(task.id, field, `Task ${task.id} has no ${field}.`, `Declare ${field} in the sdd-task block before execute.`));
+      }
+    }
+    if (!scalarByNames(task.rawMetadata, ['executionLane', 'execution_lane'])) {
+      gaps.push(taskGap(task.id, 'executionLane', `Task ${task.id} has no executionLane.`, 'Declare executionLane in the sdd-task block before execute.'));
+    }
+    if (!scalarByNames(task.rawMetadata, ['failureRoute', 'failure_route'])) {
+      gaps.push(taskGap(task.id, 'failureRoute', `Task ${task.id} has no failureRoute.`, 'Declare failureRoute in the sdd-task block before execute.'));
+    }
+    return gaps;
+  }
+
+  const requiredLists: Array<[keyof SddTask, string]> = [
+    ['affectedFiles', 'affected_files'],
+    ['validation', 'validation']
+  ];
+
+  if (!isValidChangeSurface(scalarValue(task.rawMetadata.change_surface))) {
+    gaps.push(taskGap(task.id, 'change_surface', `Task ${task.id} has invalid change_surface.`, 'Use one of frontend_only, backend_only, full_stack, docs_only, config_only, cli_only, unknown.'));
+  }
+  if (!isValidValidationTiming(scalarValue(task.rawMetadata.validation_timing))) {
+    gaps.push(taskGap(task.id, 'validation_timing', `Task ${task.id} has invalid validation_timing.`, 'Use one of task_end, batch_end, wave_end.'));
+  }
+  if (!isValidBooleanScalar(scalarValue(task.rawMetadata.requires_verify_before_next))) {
+    gaps.push(taskGap(task.id, 'requires_verify_before_next', `Task ${task.id} has invalid requires_verify_before_next.`, 'Use true or false.'));
+  }
+  if ((task.validationTiming === 'batch_end' || task.validationTiming === 'wave_end') && !task.validationBatch) {
+    gaps.push(taskGap(task.id, 'validation_batch', `Task ${task.id} uses ${task.validationTiming} but has no validation_batch.`, 'Declare validation_batch so batch/wave validation can group implementation evidence before /sdd:test.'));
+  }
+  if ((task.validationTiming === 'batch_end' || task.validationTiming === 'wave_end') && task.requiresVerifyBeforeNext) {
+    gaps.push(taskGap(task.id, 'requires_verify_before_next', `Task ${task.id} uses ${task.validationTiming} but requires verify before next.`, 'Set requires_verify_before_next: false for batch/wave validation, or use validation_timing: task_end for strict validation.'));
+  }
+  for (const [property, field] of requiredLists) {
+    if ((task[property] as unknown[]).length === 0) {
+      gaps.push(taskGap(task.id, field, `Task ${task.id} has no ${field}.`, `Declare ${field} in the sdd-task block before implementation.`));
+    }
+  }
+  if ((task.changeSurface === 'frontend_only' || isFrontendOnlyTask(task)) && task.validation.some(isBackendBuildValidationCommand)) {
+    gaps.push(taskGap(task.id, 'validation', `Task ${task.id} is frontend-only but declares backend build validation.`, 'For JSP/static frontend-only changes, replace Maven/Gradle validation with frontend-appropriate checks, dev-server/manual page evidence, lint/typecheck, or an explicit unavailable reason.'));
+  }
+  if (!task.boundary) {
+    gaps.push(taskGap(task.id, 'Boundary', `Task ${task.id} has no Boundary section.`, 'Add a #### Boundary section describing allowed and forbidden scope.'));
+  }
+  if (task.acceptance.length === 0) {
+    gaps.push(taskGap(task.id, 'Acceptance', `Task ${task.id} has no acceptance items.`, 'Add verifiable bullets under #### Acceptance.'));
+  }
+  return gaps;
+}
+
+export function isFrontendOnlyTask(task: SddTask): boolean {
+  return task.affectedFiles.length > 0 && task.affectedFiles.every(isFrontendOnlyPath);
+}
+
+function isFrontendOnlyPath(filePath: string): boolean {
+  const normalized = filePath.toLowerCase().replace(/\\/g, '/');
+  return /\.(jsp|html|htm|css|scss|sass|less|js|jsx|ts|tsx|vue|svelte|png|jpg|jpeg|gif|svg|webp|ico)$/.test(normalized)
+    && !normalized.includes('/src/main/java/')
+    && !normalized.includes('/src/test/java/')
+    && !normalized.includes('/pom.xml')
+    && !normalized.endsWith('pom.xml')
+    && !normalized.endsWith('build.gradle')
+    && !normalized.endsWith('build.gradle.kts');
+}
+
+export function isBackendBuildValidationCommand(command: string): boolean {
+  return /(^|\s)(mvn|maven|mvnw|\.\/mvnw|gradle|gradlew|\.\/gradlew)(\s|$)|\b(maven_compile|gradle_build)\b/i.test(command);
+}
+
+function taskGap(taskId: string, field: string, message: string, recommendation: string): SddTaskGap {
+  return {
+    type: 'Task Gap',
+    severity: 'blocking',
+    taskId,
+    field,
+    message,
+    recommendation
+  };
+}
+
+function validateAggregateTaskSet(tasks: SddTask[]): SddTaskGap[] {
+  const gaps: SddTaskGap[] = [];
+  const tasksById = new Map<string, SddTask[]>();
+  for (const task of tasks) {
+    const matchingTasks = tasksById.get(task.id) ?? [];
+    matchingTasks.push(task);
+    tasksById.set(task.id, matchingTasks);
+  }
+
+  for (const [taskId, matchingTasks] of tasksById) {
+    if (matchingTasks.length > 1) {
+      gaps.push(taskGap(
+        taskId,
+        'id',
+        `Duplicate task id ${taskId} across parsed task files: ${matchingTasks.map(taskSourceEvidence).join('; ')}.`,
+        'Rename duplicate task ids or add deterministic source disambiguation before implementation.'
+      ));
+    }
+  }
+
+  for (const task of tasks) {
+    for (const dependency of task.dependsOn) {
+      const matchingDependencies = tasksById.get(dependency) ?? [];
+      if (matchingDependencies.length === 0) {
+        gaps.push({
+          type: 'Dependency Gap',
+          severity: 'blocking',
+          taskId: task.id,
+          field: 'depends_on',
+          message: `Task ${task.id} depends on unknown task ${dependency}.`,
+          recommendation: 'Fix depends_on to reference an existing task id, or add the missing task.'
+        });
+      } else if (matchingDependencies.length > 1) {
+        gaps.push({
+          type: 'Dependency Gap',
+          severity: 'blocking',
+          taskId: task.id,
+          field: 'depends_on',
+          message: `Task ${task.id} depends on ambiguous duplicate task id ${dependency}: ${matchingDependencies.map(taskSourceEvidence).join('; ')}.`,
+          recommendation: 'Rename duplicate task ids so dependencies resolve to one task.'
+        });
+      }
+    }
+  }
+
+  return gaps;
+}
+
+function taskSourceEvidence(task: Pick<SddTask, 'id' | 'source'>): string {
+  return `${task.id} at ${sourceLocationEvidence(task.source)}`;
+}
+
+function sourceLocationEvidence(source: SddTaskSourceLocation): string {
+  return `${source.filePath}:${source.lineStart}-${source.lineEnd}`;
+}