sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,694 @@
+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' | '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;
+  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 (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 (documents.verifyStale) {
+    const staleBoundary = documents.verifyBasedOnTasksContractHash ? 'tasks contract hash' : 'tasks contract hash binding';
+    const currentHash = documents.verifyBasedOnTasksContractHash ? documents.tasksContractHash : 'required';
+    gaps.push(documentGap('verify.md', `Verify document is stale because based_on_${staleBoundary.replace(/ /g, '_')} ${documents.verifyBasedOnTasksContractHash ?? 'missing'} no longer matches current ${staleBoundary} ${currentHash}.`, 'Run /sdd:tasks or explicit sdd verifies write recovery before /sdd:test.'));
+  }
+  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)),
+      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 = 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 = Boolean(
+    input.rawVerify !== null && (
+      !verifyBasedOnTasksContractHash
+      || (verifyBasedOnTasksContractHash && tasksContractHash && !documentHashMatches(verifyBasedOnTasksContractHash, tasksContractHash))
+    )
+  );
+
+  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 === '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*###\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]))`;
+  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}`;
+}