sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -1,10 +1,12 @@
-import { createHash } from 'node:crypto';
+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';
 
@@ -23,9 +25,15 @@ export interface SddValidationCommand {
 
 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[];
@@ -71,9 +79,20 @@ export interface SddTaskModel {
     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;
@@ -98,15 +117,6 @@ export async function parseSddBranch(projectRoot: string, branch = 'master'): Pr
   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}.`, 'Re-run /sdd:plan 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}.`, 'Re-run /sdd:tasks for this partition before executing implementation.'));
-  }
-  if (documents.verifyStale) {
-    gaps.push(documentGap('verify.md', `Verify document is stale because based_on_tasks_hash ${documents.verifyBasedOnTasksHash} no longer matches current tasks hash ${documents.tasksHash}.`, 'Run /sdd:test for this partition so the test gate can refresh or block on the verification contract.'));
-  }
   if (!specExists) {
     gaps.push(documentGap('spec.md', 'Spec document is missing.', 'Create or restore specs/<branch>/spec.md before full SDD execution.'));
   }
@@ -219,11 +229,18 @@ export function parseSddTasksMarkdown(raw: string, options: { branch?: string; t
     }
     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),
@@ -256,49 +273,53 @@ export function parseSddTasksMarkdown(raw: string, options: { branch?: string; t
 }
 
 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 specHash = input.rawSpec === null ? null : hashDocumentContent(input.rawSpec);
-  const planHash = input.rawPlan === null ? null : hashDocumentContent(input.rawPlan);
-  const tasksHash = input.rawTasks === null ? null : hashDocumentContent(input.rawTasks);
-  const verifyHash = input.rawVerify === null ? null : hashDocumentContent(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 planStale = Boolean(planBasedOnSpecHash && specHash && !documentHashMatches(planBasedOnSpecHash, specHash));
-  const tasksHashMismatch = Boolean(tasksBasedOnPlanHash && planHash && !documentHashMatches(tasksBasedOnPlanHash, planHash));
-  const verifyHashMismatch = Boolean(verifyBasedOnTasksHash && tasksHash && !documentHashMatches(verifyBasedOnTasksHash, tasksHash));
+  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,
-    planHash,
-    tasksHash,
-    verifyHash,
+    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 hashDocumentContent(raw: string): string {
-  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-}
-
-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;
-}
-
-function documentHashMatches(expected: string, actual: string): boolean {
-  return expected.replace(/^sha256:/, '') === actual;
-}
 
 async function parseRetainedPhaseTasks(specBranchDir: string): Promise<Pick<SddTaskModel, 'tasks' | 'gaps'>> {
   const entries = await readdir(specBranchDir, { withFileTypes: true });
@@ -344,6 +365,36 @@ function parseWave(value: string | null): number | null {
   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/);
@@ -443,7 +494,7 @@ function lineNumberAt(raw: string, offset: number): number {
 }
 
 function nearestTaskHeading(prefix: string): { raw: string; id: string | null; title: string | null } | null {
-  const matches = Array.from(prefix.matchAll(/^\s*###\s+(.+)$/gm));
+  const matches = Array.from(prefix.matchAll(/^\s*#{2,3}\s+(.+)$/gm));
   const last = matches.at(-1);
   if (!last) {
     return null;
@@ -458,7 +509,7 @@ function nearestTaskHeading(prefix: string): { raw: string; id: string | null; t
 }
 
 function nextTaskStart(raw: string, offset: number, limit = raw.length): number {
-  const next = raw.slice(offset, limit).search(/^\s*###\s+/m);
+  const next = raw.slice(offset, limit).search(/^\s*#{2,3}\s+/m);
   return next < 0 ? limit : offset + next;
 }
 
@@ -470,9 +521,49 @@ function parseTaskCompanionSections(raw: string): { boundary: string | null; acc
   };
 }
 
+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*###\\s+|$(?![\\s\\S]))`;
+  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;
@@ -499,11 +590,29 @@ function validateTask(task: SddTask): SddTaskGap[] {
   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.'));
   }
@@ -513,6 +622,25 @@ function validateTask(task: SddTask): SddTaskGap[] {
   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',