sdd-agent-platform 0.4.0 → 0.4.2

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/document-hashes.ts

@@ -0,0 +1,306 @@
+import { createHash } from 'node:crypto';
+
+const TASK_CONTRACT_METADATA_KEYS = [
+  'id',
+  'wave',
+  'depends_on',
+  'acceptance_refs',
+  'plan_refs',
+  'affected_files',
+  'change_surface',
+  'implementation_wave',
+  'validation_batch',
+  'validation_timing',
+  'requires_verify_before_next',
+  'validation',
+  'risk',
+  'required_artifacts',
+  'allowed_agents',
+  'verification_availability',
+  'autonomy',
+  'validation_wave',
+  'review_gate'
+];
+
+const TASK_CONTRACT_SECTION_TITLES = [
+  'Boundary',
+  'Acceptance',
+  'Definition of Done',
+  'Evidence Expectations'
+];
+
+const TOP_LEVEL_CONTRACT_SECTION_TITLES = [
+  'Delivery Map',
+  'Wave Plan',
+  'Implementation Waves',
+  'Validation Waves',
+  'Review Gate',
+  'Review Gates',
+  'Review Gate Declarations',
+  'Phase Gate Checkpoint'
+];
+
+const RUNTIME_METADATA_KEYS = new Set([
+  'accepted_status',
+  'close_status',
+  'created_at',
+  'decision_id',
+  'generated_at',
+  'generatedat',
+  'reviewhash',
+  'run_id',
+  'runtime_decision_id',
+  'targethash',
+  'updated_at'
+]);
+
+export function hashDocumentContent(raw: string): string {
+  return sha256(normalizeLineEndings(raw));
+}
+
+export function hashNormalizedMarkdownContent(raw: string | null): string | null {
+  return raw === null ? null : sha256(normalizeMarkdownContentV1(raw));
+}
+
+export function normalizeMarkdownContentV1(raw: string): string {
+  const withoutBom = raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw;
+  let lines = normalizeLineEndings(withoutBom).split('\n');
+  if (lines[0]?.trim() === '---') {
+    const frontmatterEnd = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (frontmatterEnd > 0) {
+      const frontmatter = lines.slice(1, frontmatterEnd).filter((line) => !isRuntimeMetadataLine(line));
+      lines = [...(frontmatter.some((line) => line.trim()) ? ['---', ...frontmatter, '---'] : []), ...lines.slice(frontmatterEnd + 1)];
+    }
+  }
+
+  const normalized: string[] = [];
+  let fence: { character: '`' | '~'; length: number } | null = null;
+  let previousBlank = false;
+
+  for (const line of lines) {
+    if (fence) {
+      normalized.push(line);
+      if (isClosingFence(line, fence)) {
+        fence = null;
+      }
+      previousBlank = false;
+      continue;
+    }
+
+    const openingFence = parseOpeningFence(line);
+    if (openingFence) {
+      normalized.push(line);
+      fence = openingFence;
+      previousBlank = false;
+      continue;
+    }
+
+    const withoutTrailingWhitespace = line.replace(/[ \t]+$/g, '');
+    if (isStandaloneHtmlComment(withoutTrailingWhitespace) || isRuntimeMetadataLine(withoutTrailingWhitespace)) {
+      continue;
+    }
+    if (withoutTrailingWhitespace.trim() === '') {
+      if (!previousBlank) {
+        normalized.push('');
+        previousBlank = true;
+      }
+      continue;
+    }
+    normalized.push(withoutTrailingWhitespace);
+    previousBlank = false;
+  }
+
+  while (normalized.length > 0 && normalized[0] === '') {
+    normalized.shift();
+  }
+  while (normalized.length > 0 && normalized[normalized.length - 1] === '') {
+    normalized.pop();
+  }
+  return normalized.length > 0 ? `${normalized.join('\n')}\n` : '';
+}
+
+export function hashSemanticDocument(raw: string | null): string | null {
+  return hashNormalizedMarkdownContent(raw);
+}
+
+export function hashTasksContract(raw: string | null): string | null {
+  if (raw === null) {
+    return null;
+  }
+  return sha256(stableJson({
+    tasks: parseTaskContracts(raw),
+    declarations: TOP_LEVEL_CONTRACT_SECTION_TITLES.map((title) => [title, normalizeSectionText(sectionText(raw, title))]).filter(([, value]) => value !== null)
+  }));
+}
+
+export function documentHashMatches(expected: string, actual: string): boolean {
+  return expected.replace(/^sha256:/, '') === actual;
+}
+
+function parseTaskContracts(raw: string): unknown[] {
+  const fencedBlocks = Array.from(raw.matchAll(/^\s*```sdd-task\s*\r?\n([\s\S]*?)\r?^\s*```\s*$/gm));
+  return fencedBlocks.map((blockMatch, index) => {
+    const block = blockMatch[1] ?? '';
+    const blockStart = blockMatch.index ?? 0;
+    const blockEnd = blockStart + blockMatch[0].length;
+    const nextBlockStart = fencedBlocks[index + 1]?.index ?? raw.length;
+    const section = raw.slice(blockEnd, nextTaskStart(raw, blockEnd, nextBlockStart));
+    const metadata = parseSimpleYamlBlock(block);
+    const heading = nearestTaskHeading(raw.slice(0, blockStart));
+    const id = scalarValue(metadata.id) ?? heading?.id ?? null;
+    return {
+      id,
+      title: heading?.title ?? null,
+      metadata: Object.fromEntries(TASK_CONTRACT_METADATA_KEYS.map((key) => [key, normalizedMetadataValue(metadata[key])])),
+      sections: Object.fromEntries(TASK_CONTRACT_SECTION_TITLES.map((title) => [title, normalizeSectionText(sectionText(section, title))]))
+    };
+  }).sort((left, right) => String((left as { id: string | null }).id ?? '').localeCompare(String((right as { id: string | null }).id ?? '')));
+}
+
+function normalizeLineEndings(raw: string): string {
+  return raw.replace(/\r\n?/g, '\n');
+}
+
+function parseOpeningFence(line: string): { character: '`' | '~'; length: number } | null {
+  const match = line.match(/^\s*(`{3,}|~{3,})/);
+  if (!match) {
+    return null;
+  }
+  const marker = match[1];
+  return { character: marker[0] as '`' | '~', length: marker.length };
+}
+
+function isClosingFence(line: string, fence: { character: '`' | '~'; length: number }): boolean {
+  const escaped = fence.character === '`' ? '`' : '~';
+  const match = line.match(new RegExp(`^\\s*(${escaped}{${fence.length},})\\s*$`));
+  return Boolean(match);
+}
+
+function isStandaloneHtmlComment(line: string): boolean {
+  return /^\s*<!--[\s\S]*?-->\s*$/.test(line);
+}
+
+function isRuntimeMetadataLine(line: string): boolean {
+  const match = line.match(/^\s*(?:-\s*)?([A-Za-z0-9_]+):\s*/);
+  if (!match) {
+    return false;
+  }
+  const key = match[1];
+  const normalizedKey = key.toLowerCase();
+  return /^based_on_.*_hash$/.test(normalizedKey)
+    || RUNTIME_METADATA_KEYS.has(normalizedKey);
+}
+
+function normalizeSectionText(value: string | null): string | null {
+  if (!value) {
+    return null;
+  }
+  return value.replace(/\r\n/g, '\n').split('\n').map((line) => line.trim()).filter((line) => line && !/^<!--.*-->$/.test(line)).join('\n');
+}
+
+function sectionText(raw: string, title: string): string | null {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const sectionPattern = `^\\s*#{2,4}\\s+${escaped}\\s*$([\\s\\S]*?)(?=^\\s*#{2,4}\\s+|$(?![\\s\\S]))`;
+  const match = raw.match(new RegExp(sectionPattern, 'im'));
+  const text = match?.[1]?.trim() ?? '';
+  return text.length > 0 ? text : null;
+}
+
+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 normalizedMetadataValue(value: string | string[] | undefined): string | string[] | null {
+  if (Array.isArray(value)) {
+    return [...value].filter(Boolean).sort();
+  }
+  return value && value !== '[]' ? value : null;
+}
+
+function scalarValue(value: string | string[] | undefined): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+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 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 stableJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/run-binding.ts

@@ -1,8 +1,11 @@
+import path from 'node:path';
 import { appendEvent } from '../run-state/events.js';
 import { readRunState, writeRunState } from '../run-state/run-state.js';
 import type { RunDocumentSnapshot, RunState } from '../run-state/model.js';
 import type { ContextResolverContract } from './context.js';
 import type { SddTask, SddTaskModel } from './task-parser.js';
+import { getRunEvidenceRoot } from '../runtime-paths.js';
+import { branchToSafePartition } from '../path-safety.js';
 
 export async function bindRunStateToTask(projectRoot: string, state: RunState, context: ContextResolverContract, model: SddTaskModel, task: SddTask | null, taskId: string): Promise<RunState> {
   if (state.partition && state.partition !== context.partition) {
@@ -22,7 +25,8 @@ export async function bindRunStateToTask(projectRoot: string, state: RunState, c
     gitBranch: context.rawBranch,
     taskId,
     affectedFiles: task?.affectedFiles ?? state.affectedFiles,
-    documentSnapshot: documentSnapshotFromModel(model)
+    documentSnapshot: documentSnapshotFromModel(model, task),
+    artifactRoot: path.relative(projectRoot, path.join(getRunEvidenceRoot(projectRoot), branchToSafePartition(context.partition)))
   };
   await writeRunState(projectRoot, nextState);
   await appendEvent(projectRoot, state.runId, {
@@ -57,7 +61,8 @@ export async function bindRunStateToTaskContext(projectRoot: string, state: RunS
     partition: context.partition,
     gitBranch: context.rawBranch,
     affectedFiles: [...new Set([...state.affectedFiles, ...(task?.affectedFiles ?? [])])],
-    documentSnapshot: documentSnapshotFromModel(model)
+    documentSnapshot: documentSnapshotFromModel(model, task),
+    artifactRoot: path.relative(projectRoot, path.join(getRunEvidenceRoot(projectRoot), branchToSafePartition(context.partition)))
   };
   await writeRunState(projectRoot, nextState);
   await appendEvent(projectRoot, state.runId, {
@@ -75,12 +80,18 @@ export async function bindRunStateToTaskContext(projectRoot: string, state: RunS
   return readRunState(projectRoot, state.runId);
 }
 
-export function documentSnapshotFromModel(model: SddTaskModel): RunDocumentSnapshot {
+export function documentSnapshotFromModel(model: SddTaskModel, task: SddTask | null = null): RunDocumentSnapshot {
   return {
     specHash: model.documents.specHash ?? null,
     planHash: model.documents.planHash ?? null,
     tasksHash: model.documents.tasksHash ?? null,
+    specContractHash: model.documents.specContractHash ?? null,
+    planContractHash: model.documents.planContractHash ?? null,
+    tasksContractHash: model.documents.tasksContractHash ?? null,
+    taskContractHash: task?.contractHash ?? null,
     planBasedOnSpecHash: model.documents.planBasedOnSpecHash ?? null,
-    tasksBasedOnPlanHash: model.documents.tasksBasedOnPlanHash ?? null
+    tasksBasedOnPlanHash: model.documents.tasksBasedOnPlanHash ?? null,
+    planBasedOnSpecContractHash: model.documents.planBasedOnSpecContractHash ?? null,
+    tasksBasedOnPlanContractHash: model.documents.tasksBasedOnPlanContractHash ?? null
   };
 }

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 { hashNormalizedMarkdownContent, hashTasksContract, normalizeMarkdownContentV1 } 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,256 @@ None yet.
   assert.deepEqual(model.tasks[0].acceptance, ['Task metadata is structured.', 'Boundary is retained.']);
 });
 
+test('parseSddTasksMarkdown stops companion sections at level-two task headings', () => {
+  const markdown = `# Tasks
+
+## T1: First task
+
+\`\`\`sdd-task
+id: T1
+status: pending
+wave: 1
+depends_on: []
+affected_files:
+  - packages/app/login.ts
+change_surface: backend_only
+validation_timing: task_end
+requires_verify_before_next: true
+validation:
+  - npm test
+risk: []
+\`\`\`
+
+#### Boundary
+
+Only T1.
+
+#### Acceptance
+
+- T1 passes.
+
+#### Implementation Notes
+
+Keep T1 narrow.
+
+## T2: Second task
+
+T2 introduction must not be parsed as T1 notes.
+
+\`\`\`sdd-task
+id: T2
+status: pending
+wave: 1
+depends_on: [T1]
+affected_files:
+  - packages/core/src/index.ts
+change_surface: backend_only
+validation_timing: task_end
+requires_verify_before_next: true
+validation:
+  - npm test
+risk: []
+\`\`\`
+
+#### Boundary
+
+Only T2.
+
+#### Acceptance
+
+- T2 passes.
+`;
+  const model = parseSddTasksMarkdown(markdown, { tasksPath: 'specs/master/tasks.md' });
+
+  assert.equal(model.gaps.length, 0);
+  assert.equal(model.tasks[0].source.heading, 'T1: First task');
+  assert.equal(model.tasks[0].implementationNotes, 'Keep T1 narrow.');
+  assert.equal(model.tasks[0].implementationNotes?.includes('T2 introduction'), false);
+});
+
+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('normalizeMarkdownContentV1 applies conservative formatting normalization', () => {
+  const base = `---
+contract: sdd-spec-doc-v1
+based_on_spec_hash: legacy
+created_at: 2026-01-01T00:00:00.000Z
+---
+
+# Spec   
+
+<!-- standalone comment -->
+
+- keep list order
+  - keep indentation
+
+\`\`\`md
+<!-- keep fenced comment -->   
+based_on_spec_hash: keep-in-code
+\`\`\`
+`;
+  const equivalent = `---\r\ncontract: sdd-spec-doc-v1\r\nbased_on_spec_hash: changed\r\nupdated_at: 2026-01-02T00:00:00.000Z\r\n---\r\n\r\n# Spec\t\r\n\r\n\r\n<!-- standalone comment -->\r\n\r\n- keep list order\r\n  - keep indentation\r\n\r\n\`\`\`md\r\n<!-- keep fenced comment -->   \r\nbased_on_spec_hash: keep-in-code\r\n\`\`\`\r\n`;
+
+  assert.equal(normalizeMarkdownContentV1(base), normalizeMarkdownContentV1(equivalent));
+  assert.match(normalizeMarkdownContentV1(base), /<!-- keep fenced comment -->   /);
+  assert.doesNotMatch(normalizeMarkdownContentV1(base), /standalone comment/);
+});
+
+test('spec and plan contract hashes ignore runtime metadata and formatting noise only', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-normalized-contract-hash-'));
+  try {
+    const branchDir = path.join(root, 'specs', 'feature');
+    await mkdir(branchDir, { recursive: true });
+    const spec = '# Spec\n\nInitial requirement.\n';
+    const plan = '# Plan\n\nInitial plan.\n';
+    await writeFile(path.join(branchDir, 'spec.md'), spec, 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), plan, 'utf8');
+    await writeFile(path.join(branchDir, 'tasks.md'), validTaskMarkdown('T1', []), 'utf8');
+    const base = await parseSddBranch(root, 'feature');
+
+    await writeFile(path.join(branchDir, 'spec.md'), `---\nbased_on_spec_hash: ignored\nupdated_at: now\n---\n\n# Spec  \n\n\nInitial requirement.\n\n<!-- runtime note -->\n`, 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), `# Plan\n\nbased_on_plan_hash: ignored\n\nInitial plan.\n`, 'utf8');
+    const normalizedOnly = await parseSddBranch(root, 'feature');
+
+    await writeFile(path.join(branchDir, 'spec.md'), '# Spec\n\nChanged requirement.\n', 'utf8');
+    const changed = await parseSddBranch(root, 'feature');
+
+    assert.notEqual(normalizedOnly.documents.specHash, base.documents.specHash);
+    assert.equal(normalizedOnly.documents.specContractHash, base.documents.specContractHash);
+    assert.equal(normalizedOnly.documents.planContractHash, base.documents.planContractHash);
+    assert.notEqual(changed.documents.specContractHash, base.documents.specContractHash);
+    assert.notEqual(hashNormalizedMarkdownContent('# Spec\n\nChanged requirement.\n'), hashNormalizedMarkdownContent(spec));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+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