sdd-agent-platform 0.4.0 → 0.4.1

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

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { validTaskMarkdown } from '../test-support/fixtures.js';
+import { hashTasksContract } from './document-hashes.js';
 import { inspectSddTask } from './task-inspection.js';
 import { parseSddBranch, parseSddTasksMarkdown } from './task-parser.js';
 import { renderTaskGapReport } from './task-rendering.js';
@@ -21,6 +22,11 @@ wave: 1
 depends_on: []
 affected_files:
   - packages/core/src/index.ts
+change_surface: backend_only
+implementation_wave: wave-1
+validation_batch: backend-unit-wave-1
+validation_timing: batch_end
+requires_verify_before_next: false
 validation:
   - npm test => AC-1, AC-2
 risk:
@@ -49,6 +55,11 @@ None yet.
   assert.equal(model.tasks[0].wave, 1);
   assert.deepEqual(model.tasks[0].dependsOn, []);
   assert.deepEqual(model.tasks[0].affectedFiles, ['packages/core/src/index.ts']);
+  assert.equal(model.tasks[0].changeSurface, 'backend_only');
+  assert.equal(model.tasks[0].implementationWave, 'wave-1');
+  assert.equal(model.tasks[0].validationBatch, 'backend-unit-wave-1');
+  assert.equal(model.tasks[0].validationTiming, 'batch_end');
+  assert.equal(model.tasks[0].requiresVerifyBeforeNext, false);
   assert.deepEqual(model.tasks[0].validation, ['npm test']);
   assert.deepEqual(model.tasks[0].validationCommands, [{ command: 'npm test', acceptanceRefs: ['AC-1', 'AC-2'], raw: 'npm test => AC-1, AC-2' }]);
   assert.deepEqual(model.tasks[0].risk, ['parser boundary']);
@@ -56,6 +67,134 @@ None yet.
   assert.deepEqual(model.tasks[0].acceptance, ['Task metadata is structured.', 'Boundary is retained.']);
 });
 
+test('parseSddTasksMarkdown blocks backend build validation for frontend-only tasks', () => {
+  const markdown = `# Tasks
+
+### T23: JSP rendering copy update
+
+\`\`\`sdd-task
+id: T23
+status: pending
+wave: 1
+depends_on: []
+affected_files:
+  - emp-upms/emp-upms-server/src/main/webapp/WEB-INF/views/demo.jsp
+  - emp-upms/emp-upms-server/src/main/webapp/static/img/banner.svg
+validation:
+  - mvn compile -Ptest -pl emp-upms/emp-upms-server -am
+risk: []
+\`\`\`
+
+#### Boundary
+
+Only JSP copy and static image rendering.
+
+#### Acceptance
+
+- JSP copy renders correctly.
+`;
+  const model = parseSddTasksMarkdown(markdown, { tasksPath: 'specs/master/tasks.md' });
+
+  assert.equal(model.gaps.some((gap) => gap.taskId === 'T23' && gap.field === 'validation' && /frontend-only/.test(gap.message)), true);
+  assert.equal(model.gaps.some((gap) => /Maven\/Gradle/.test(gap.recommendation)), true);
+});
+
+test('parseSddTasksMarkdown validates Phase 8.19 batch contract fields', () => {
+  const markdown = `# Tasks
+
+### T24: Invalid batch contract
+
+\`\`\`sdd-task
+id: T24
+status: pending
+wave: 1
+depends_on: []
+affected_files:
+  - packages/core/src/index.ts
+change_surface: api_only
+validation_timing: batch_end
+requires_verify_before_next: sometimes
+validation:
+  - npm test
+risk: []
+\`\`\`
+
+#### Boundary
+
+Stay in parser scope.
+
+#### Acceptance
+
+- Parser blocks invalid batch contract.
+`;
+  const model = parseSddTasksMarkdown(markdown, { tasksPath: 'specs/master/tasks.md' });
+  const fields = model.gaps.map((gap) => gap.field);
+
+  assert.equal(fields.includes('change_surface'), true);
+  assert.equal(fields.includes('validation_batch'), true);
+  assert.equal(fields.includes('requires_verify_before_next'), true);
+});
+
+test('hashTasksContract includes Phase 8.19 validation grouping fields', () => {
+  const base = `# Tasks
+
+### T1: Hash grouping
+
+\`\`\`sdd-task
+id: T1
+status: pending
+wave: 1
+depends_on: []
+affected_files:
+  - packages/core/src/index.ts
+change_surface: backend_only
+implementation_wave: wave-1
+validation_batch: batch-a
+validation_timing: batch_end
+requires_verify_before_next: false
+validation:
+  - npm test
+risk: []
+\`\`\`
+
+#### Boundary
+
+Stay in parser scope.
+
+#### Acceptance
+
+- Hash includes validation grouping.
+`;
+  const changed = base.replace('validation_batch: batch-a', 'validation_batch: batch-b');
+
+  assert.notEqual(hashTasksContract(base), hashTasksContract(changed));
+});
+
+test('parseSddBranch separates raw doc hash from semantic tasks contract hash', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-contract-hash-'));
+  try {
+    const branchDir = path.join(root, 'specs', 'feature');
+    await mkdir(branchDir, { recursive: true });
+    await writeFile(path.join(branchDir, 'spec.md'), '# Spec\n', 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), '# Plan\n', 'utf8');
+    const original = validTaskMarkdown('T1', []);
+    await writeFile(path.join(branchDir, 'tasks.md'), original, 'utf8');
+    const base = await parseSddBranch(root, 'feature');
+
+    await writeFile(path.join(branchDir, 'tasks.md'), `${original}\n\n<!-- formatting-only note -->\n`, 'utf8');
+    const formattingOnly = await parseSddBranch(root, 'feature');
+
+    await writeFile(path.join(branchDir, 'tasks.md'), original.replace('risk: []', 'risk:\n  - security'), 'utf8');
+    const semanticChange = await parseSddBranch(root, 'feature');
+
+    assert.notEqual(formattingOnly.documents.tasksHash, base.documents.tasksHash);
+    assert.equal(formattingOnly.documents.tasksContractHash, base.documents.tasksContractHash);
+    assert.notEqual(semanticChange.documents.tasksContractHash, base.documents.tasksContractHash);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('parseSddTasksMarkdown does not leak companion sections across indented task headings', () => {
   const markdown = `# Tasks
 

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

@@ -1,10 +1,12 @@
-import { createHash } from 'node:crypto';
+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';
 
@@ -26,6 +28,11 @@ export interface SddTask {
   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 +78,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;
@@ -99,13 +117,15 @@ export async function parseSddBranch(projectRoot: string, branch = 'master'): Pr
   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.'));
+    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}.`, 'Re-run /sdd:tasks for this partition before executing implementation.'));
+    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) {
-    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.'));
+    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.'));
@@ -224,6 +244,11 @@ export function parseSddTasksMarkdown(raw: string, options: { branch?: string; t
       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,50 +281,71 @@ 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 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 planStale = Boolean(planBasedOnSpecHash && specHash && !documentHashMatches(planBasedOnSpecHash, specHash));
-  const tasksHashMismatch = Boolean(tasksBasedOnPlanHash && planHash && !documentHashMatches(tasksBasedOnPlanHash, planHash));
-  const verifyHashMismatch = Boolean(verifyBasedOnTasksHash && tasksHash && !documentHashMatches(verifyBasedOnTasksHash, tasksHash));
+  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,
-    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 });
   const taskFiles = entries
@@ -344,6 +390,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/);
@@ -499,11 +575,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 +607,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',