@haposoft/cafekit 0.15.3 → 0.16.0-rc.2

package/src/claude/scripts/validate-spec-output.cjs

@@ -20,6 +20,9 @@ const REQUIRED_REGISTRY_KEYS = [
   'completed_at',
   'last_updated_at',
 ];
+const APPROVAL_SCHEMA_VERSION = '2.0';
+const LEGACY_APPROVAL_ERROR =
+  `Legacy approval field "approved" detected. Migration required: replace "approved" with "agent_validated" and "user_approved" per schema v${APPROVAL_SCHEMA_VERSION} (schema_version: "${APPROVAL_SCHEMA_VERSION}"). See spec-state.json template. Refusing to infer user approval.`;
 
 function usage() {
   console.error('Usage: node .claude/scripts/validate-spec-output.cjs specs/<feature>');
@@ -63,6 +66,17 @@ function hasHeading(content, heading) {
   return new RegExp(`^##\\s+${escaped}\\s*$`, 'm').test(content);
 }
 
+function extractSection(content, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^##\\s+${escaped}\\s*$`, 'im');
+  const match = content.match(re);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  const after = content.slice(start);
+  const next = after.match(/^##\s+/m);
+  return next ? after.slice(0, next.index) : after;
+}
+
 function extractRequirementIds(requirementsText) {
   const ids = new Set();
   const headingRe = /^#{2,4}\s+(?:(?:Requirement)\s+)?((?:REQ-\d+)|(?:R\d+))\b/gim;
@@ -88,10 +102,8 @@ function extractRequirementIds(requirementsText) {
 /**
  * Extract sub-criteria IDs (e.g. R3.4) ONLY when requirements.md declares them
  * as explicit literals — bold `**R3.4**` or a line-leading `R3.4`. Specs that
- * write acceptance criteria as a plain numbered list under a heading declare no
- * such literals, so this returns empty and per-criterion coverage is skipped
- * for them (no behaviour change). This is a progressive check: it rewards an
- * unambiguous format, it never penalises the legacy one.
+ * write acceptance criteria as a plain numbered list declare no such literals.
+ * Every declared literal must have an explicit numeric task mapping.
  */
 function extractSubCriteriaIds(requirementsText) {
   const ids = new Set();
@@ -125,11 +137,39 @@ function validateTaskSections(taskPath, content, errors) {
   if (!hasSteps) errors.push(`${taskPath}: missing Steps/Implementation Steps`);
   if (!hasRequirements) errors.push(`${taskPath}: missing Requirements mapping`);
   if (!hasRelatedFiles) errors.push(`${taskPath}: missing Related Files`);
+  else if (relatedFilesSection(content).rows.length === 0) errors.push(`${taskPath}: Related Files section must not be empty`);
   if (!hasCompletionCriteria) errors.push(`${taskPath}: missing Completion Criteria`);
   if (!hasEvidence) errors.push(`${taskPath}: missing Evidence or task test plan`);
   if (!hasRiskAssessment) errors.push(`${taskPath}: missing Risk Assessment`);
-  if (hasEvidence && !/Runtime reachability verification/i.test(content)) {
-    errors.push(`${taskPath}: missing Runtime reachability verification`);
+  if (hasEvidence) {
+    const evidenceSection = extractSection(content, 'Evidence')
+      || extractSection(content, 'Task Test Plan & Verification Evidence')
+      || extractSection(content, 'Verification & Evidence')
+      || '';
+    if (!/Runtime reachability verification/i.test(evidenceSection)) {
+      errors.push(`${taskPath}: missing Runtime reachability verification`);
+    } else {
+      // Reachability must prove a concrete path/anchor, not just the phrase.
+      // Require at least one of: backtick file path, Entrypoint/caller line, or anchor.
+      const hasConcreteAnchor =
+        /`[^`]*\.[a-z]{1,4}`/i.test(evidenceSection) ||
+        /Entrypoint\/caller\s*:/i.test(evidenceSection) ||
+        /Route is registered|import.*from|anchor:\s*`/i.test(evidenceSection);
+      if (!hasConcreteAnchor) {
+        errors.push(`${taskPath}: Runtime reachability verification must reference a concrete file path or anchor (e.g. \`src/...\` or Entrypoint/caller)`);
+      } else {
+        // Cross-check against declared Related Files paths
+        const relatedPaths = new Set(relatedFilesSection(content).rows.map((r) => r.path));
+        const referencedPaths = [...evidenceSection.matchAll(/`([^`]*\.[a-z0-9]{1,4})`/gi)].map((m) => m[1].replace(/^\.\//, ''));
+        // At least one referenced path should correspond to a declared Related Files entry (or be clearly external)
+        if (referencedPaths.length > 0 && relatedPaths.size > 0) {
+          const overlaps = referencedPaths.some((p) => [...relatedPaths].some((rp) => p === rp || p.endsWith(rp) || rp.endsWith(p) || p.includes(rp.split('/').pop())));
+          if (!overlaps && !/Entrypoint\/caller/i.test(evidenceSection)) {
+            errors.push(`${taskPath}: Runtime reachability verification references no Related Files path — must anchor to a declared file`);
+          }
+        }
+      }
+    }
   }
 }
 
@@ -227,6 +267,222 @@ function extractTaskContracts(taskText) {
   return { names, blocks, firstBlock };
 }
 
+const RELATED_FILE_ACTIONS = new Set(['create', 'modify', 'delete', 'read']);
+
+function relatedFilesSection(content) {
+  const lines = content.split('\n');
+  const headingIndex = lines.findIndex((line) => /^##+\s+Related Files\s*$/i.test(line));
+  if (headingIndex < 0) return { present: false, rows: [] };
+  const rows = [];
+  for (let index = headingIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^##+\s+/.test(line)) break;
+    if (!line.trim().startsWith('|')) continue;
+    const cells = line.split('|').map((cell) => cell.trim());
+    const filePath = (cells[1] || '').replace(/`/g, '').trim();
+    const action = (cells[2] || '').replace(/`/g, '').trim().toLowerCase();
+    if (!filePath || filePath.toLowerCase() === 'path' || /^-+$/.test(filePath)) continue;
+    rows.push({ path: filePath, action });
+  }
+  return { present: true, rows };
+}
+
+function unsafeRelatedPath(filePath) {
+  return path.isAbsolute(filePath)
+    || /^[A-Za-z]:[\\/]/.test(filePath)
+    || filePath.split(/[\\/]+/).includes('..');
+}
+
+function validateRelatedFiles(taskPath, content, errors) {
+  const section = relatedFilesSection(content);
+  if (!section.present || section.rows.length === 0) return;
+  for (const row of section.rows) {
+    if (!RELATED_FILE_ACTIONS.has(row.action)) {
+      errors.push(`${taskPath}: unsupported Related Files action "${row.action}" for ${row.path}`);
+    }
+    if (unsafeRelatedPath(row.path)) {
+      errors.push(`${taskPath}: Related Files path must be relative and stay within work root: ${row.path}`);
+    }
+  }
+}
+
+function validateStateTransitions(spec, errors) {
+  // Approval schema v2: generated, agent_validated, user_approved independent.
+  // Legacy "approved" field is rejected fail-closed with migration guidance.
+  const approvals = spec.approvals || {};
+  let hasLegacy = false;
+  for (const [stage, approval] of Object.entries(approvals)) {
+    if (!approval || typeof approval !== 'object') {
+      errors.push(`spec.json.approvals.${stage}: must be an object`);
+      continue;
+    }
+    if ('approved' in approval) {
+      errors.push(`spec.json.approvals.${stage}: ${LEGACY_APPROVAL_ERROR}`);
+      hasLegacy = true;
+    }
+    // Unsupported/ambiguous: if schema_version missing when approvals use v2 shape, warn but not fail? B2 says fail closed.
+    // We fail closed when version is unsupported or ambiguous and ready_for_implementation is true.
+  }
+
+  // Schema version validation
+  if (spec.schema_version !== undefined && spec.schema_version !== APPROVAL_SCHEMA_VERSION) {
+    errors.push(`spec.json.schema_version: unsupported "${spec.schema_version}", expected "${APPROVAL_SCHEMA_VERSION}" — migration required`);
+  }
+  if (spec.approval_schema_version !== undefined && spec.approval_schema_version !== APPROVAL_SCHEMA_VERSION) {
+    errors.push(`spec.json.approval_schema_version: unsupported "${spec.approval_schema_version}", expected "${APPROVAL_SCHEMA_VERSION}"`);
+  }
+  // If approvals use v2 fields but no schema_version, treat as ambiguous — fail closed when ready flag is set
+  const usesV2 = Object.values(approvals).some((a) => a && typeof a === 'object' && ('agent_validated' in a || 'user_approved' in a));
+  if (usesV2 && spec.schema_version === undefined && spec.approval_schema_version === undefined) {
+    // Only warn now; will be error if ready_for_implementation is true (checked below)
+    // Provide guidance
+    if (spec.ready_for_implementation === true) {
+      errors.push(`spec.json.schema_version: missing — spec uses v2 approvals (agent_validated/user_approved) but has no schema_version "${APPROVAL_SCHEMA_VERSION}"`);
+    }
+  }
+
+  if (spec.validation?.status === 'completed' && !spec.timestamps?.validation_done) {
+    errors.push('spec.json.validation: completed transition requires timestamps.validation_done');
+  }
+
+  if (spec.ready_for_implementation === true) {
+    if (hasLegacy) {
+      errors.push(`spec.json.ready_for_implementation: cannot be true with legacy approval fields — migrate to agent_validated/user_approved`);
+    }
+    for (const stage of ['requirements', 'design', 'tasks']) {
+      const approval = spec.approvals?.[stage];
+      if (!approval || approval?.generated !== true || approval?.agent_validated !== true || approval?.user_approved !== true) {
+        errors.push(`spec.json.ready_for_implementation: requires generated and agent_validated and user_approved ${stage} evidence (v2)`);
+      }
+    }
+    if (spec.validation?.status === 'in_progress' || spec.validation?.status === 'not-run') {
+      errors.push('spec.json.ready_for_implementation: cannot be true while validation evidence is incomplete');
+    }
+  }
+}
+
+function validateDependencyTopology(spec, taskFiles, registry, taskRecords, errors) {
+  const dependencies = new Map(taskFiles.map((taskFile) => [taskFile, new Set(registry?.[taskFile]?.dependencies || [])]));
+  if (dependencies.size === 0) return;
+
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(taskFile, stack = []) {
+    if (visiting.has(taskFile)) {
+      const cycleStart = stack.indexOf(taskFile);
+      errors.push(`spec.json.task_registry.dependencies: dependency cycle detected (${stack.slice(cycleStart).concat(taskFile).join(' -> ')})`);
+      return;
+    }
+    if (visited.has(taskFile)) return;
+    visiting.add(taskFile);
+    for (const dependency of dependencies.get(taskFile) || []) visit(dependency, [...stack, taskFile]);
+    visiting.delete(taskFile);
+    visited.add(taskFile);
+  }
+  for (const taskFile of taskFiles) visit(taskFile);
+
+  const roots = taskFiles.filter((taskFile) => (dependencies.get(taskFile) || new Set()).size === 0);
+  const reachable = new Set();
+  const dependents = new Map(taskFiles.map((taskFile) => [taskFile, []]));
+  for (const [taskFile, deps] of dependencies) {
+    for (const dependency of deps) dependents.get(dependency)?.push(taskFile);
+  }
+  const queue = [...roots];
+  while (queue.length > 0) {
+    const taskFile = queue.shift();
+    if (reachable.has(taskFile)) continue;
+    reachable.add(taskFile);
+    queue.push(...(dependents.get(taskFile) || []));
+  }
+  for (const taskFile of taskFiles) {
+    if (!reachable.has(taskFile)) errors.push(`spec.json.task_registry.${taskFile}: orphan or unreachable task in dependency graph`);
+  }
+
+  function dependsOn(taskFile, ancestor, seen = new Set()) {
+    if (taskFile === ancestor) return true;
+    if (seen.has(taskFile)) return false;
+    seen.add(taskFile);
+    return [...(dependencies.get(taskFile) || [])].some((dependency) => dependsOn(dependency, ancestor, seen));
+  }
+
+  const producers = new Map();
+  for (const [taskFile, record] of taskRecords) {
+    for (const [index, row] of record.rows.entries()) {
+      if (row.action !== 'create') continue;
+      const prior = producers.get(row.path);
+      if (prior && prior.taskFile !== taskFile) {
+        errors.push(`${taskFile}: Related Files path ${row.path} is created by multiple tasks (${prior.taskFile}, ${taskFile})`);
+      } else {
+        producers.set(row.path, { taskFile, index });
+      }
+    }
+  }
+  // Lifecycle ordering: Create must precede Modify/Delete/Read within task for same path
+  for (const [taskFile, record] of taskRecords) {
+    const createIndexByPath = new Map();
+    for (const [index, row] of record.rows.entries()) {
+      if (row.action === 'create' && !createIndexByPath.has(row.path)) {
+        createIndexByPath.set(row.path, index);
+      }
+    }
+    for (const [index, row] of record.rows.entries()) {
+      if (!['modify', 'delete', 'read'].includes(row.action)) continue;
+      if (!createIndexByPath.has(row.path)) continue;
+      const createIdx = createIndexByPath.get(row.path);
+      if (createIdx > index) {
+        errors.push(`${taskFile}: Create must precede ${row.action} for ${row.path} within Related Files order`);
+      }
+    }
+  }
+  // Cross-task lifecycle: Modify/Delete/Read of a path created by another task must depend on creator
+  for (const [taskFile, record] of taskRecords) {
+    for (const [index, row] of record.rows.entries()) {
+      if (!['modify', 'delete', 'read'].includes(row.action)) continue;
+      const producer = producers.get(row.path);
+      if (!producer) continue;
+      if (producer.taskFile === taskFile) continue;
+      if (!dependsOn(taskFile, producer.taskFile)) {
+        errors.push(`${taskFile}: ${row.action} of ${row.path} must depend on creator ${producer.taskFile}`);
+      }
+    }
+  }
+
+  // Existing implementation: Modify/Delete on non-produced paths must have a Read before them.
+  // This ensures lifecycle Read is not skipped for existing files.
+  for (const [taskFile, record] of taskRecords) {
+    for (const [index, row] of record.rows.entries()) {
+      if (!['modify', 'delete'].includes(row.action)) continue;
+      if (producers.has(row.path)) continue; // produced by spec, not existing
+      // Check if there's a Read for same path preceding this Modify/Delete
+      let hasPrecedingRead = false;
+      // Same task earlier row
+      for (let i = 0; i < index; i += 1) {
+        const r = record.rows[i];
+        if (r.action === 'read' && r.path === row.path) { hasPrecedingRead = true; break; }
+      }
+      if (hasPrecedingRead) continue;
+      // In any dependency ancestor
+      const deps = dependencies.get(taskFile) || new Set();
+      // Walk transitive deps for Read
+      const stack = [...deps];
+      const seen = new Set();
+      while (stack.length > 0) {
+        const dep = stack.pop();
+        if (seen.has(dep)) continue;
+        seen.add(dep);
+        const depRecord = taskRecords.get(dep);
+        if (depRecord && depRecord.rows.some((r) => r.action === 'read' && r.path === row.path)) {
+          hasPrecedingRead = true; break;
+        }
+        for (const d of dependencies.get(dep) || []) stack.push(d);
+      }
+      if (!hasPrecedingRead) {
+        errors.push(`${taskFile}: ${row.action} of ${row.path} targets existing implementation but has no preceding Read — add a Read for ${row.path} before modifying it (lifecycle ordering)`);
+      }
+    }
+  }
+}
+
 function validateSpec(specDir) {
   const errors = [];
   const warnings = [];
@@ -256,6 +512,7 @@ function validateSpec(specDir) {
   }
 
   validateTimestamps(spec, errors);
+  validateStateTransitions(spec, errors);
 
   const taskFiles = listTaskFiles(specDir);
   const taskFileSet = new Set(taskFiles);
@@ -361,14 +618,15 @@ function validateSpec(specDir) {
 
   const coveredRequirementIds = new Set();
   const coveredSubCriteriaIds = new Set();
+  const taskRecords = new Map();
   // Cross-layer contract defs (opt-in): empty unless design.md uses
   // <!-- contract:NAME --> markers, so legacy specs are unaffected.
   const contractDefs = fs.existsSync(designPath)
     ? extractContractDefs(fs.readFileSync(designPath, 'utf8'))
     : new Map();
   if (taskFiles.length >= 5 && contractDefs.size === 0) {
-    warnings.push(
-      'design.md declares no contract blocks; specs spanning BE/FE must declare shared shapes (<!-- contract:NAME -->)',
+    errors.push(
+      'design.md: 5+ task spec requires contract blocks for BE/FE shared shapes (<!-- contract:NAME -->) — fail closed, not warning',
     );
   }
   for (const taskFile of taskFiles) {
@@ -376,16 +634,20 @@ function validateSpec(specDir) {
     const content = fs.readFileSync(fullPath, 'utf8');
     validateTaskSections(taskFile, content, errors);
     validateTaskPlaceholders(taskFile, content, errors, warnings);
-
-    const idRe = /\b((?:REQ-\d+)|(?:R\d+))\b/gi;
-    let match;
-    while ((match = idRe.exec(content)) !== null) {
-      const id = match[1].toUpperCase();
-      if (id !== 'R0') coveredRequirementIds.add(id);
-    }
-
+    validateRelatedFiles(taskFile, content, errors);
+    taskRecords.set(taskFile, { rows: relatedFilesSection(content).rows });
+
+    // Requirement traceability: only structured _Requirements: ..._ mappings inside Steps/Requirements sections count.
+    // Incidental mentions elsewhere (prose Context, Constraints) must not be counted.
+    const stepsSection = extractSection(content, 'Steps') || extractSection(content, 'Implementation Steps') || '';
+    const reqSectionInTask = extractSection(content, 'Requirements') || '';
+    const mappingSource = `${stepsSection}\n${reqSectionInTask}`;
+    // Also consider inline _Requirements: inside Steps bullet lines that may be outside section extraction edge cases,
+    // so fallback to whole content scanning only if sections are null (e.g., malformed heading). But prefer scoped.
+    const effectiveMappingSource = mappingSource.trim() ? mappingSource : content;
     const numericMappingRe = /_Requirements:\s*([^_\n]+)_/gi;
-    while ((match = numericMappingRe.exec(content)) !== null) {
+    let match;
+    while ((match = numericMappingRe.exec(effectiveMappingSource)) !== null) {
       for (const token of match[1].split(',')) {
         const trimmed = token.trim();
         const major = trimmed.match(/^(\d+)(?:\.\d+)?$/);
@@ -397,12 +659,16 @@ function validateSpec(specDir) {
     }
 
     // Cross-layer contract check (opt-in via design.md markers). When a task
-    // claims `Contracts: NAME`, that name must exist in design.md and the task's
-    // local copy of the block must match the canonical definition byte-for-byte
-    // (after whitespace normalization). This catches BE/FE drift like
-    // user_name vs userName before integration.
+    // claims `Contracts: NAME`, design.md must define the name and the task's
+    // local copy must match the canonical definition byte-for-byte (after
+    // whitespace normalization). This catches BE/FE drift like user_name vs
+    // userName before integration, and rejects declarations with no canonical
+    // source instead of silently accepting an orphan contract.
+    const { names, blocks, firstBlock } = extractTaskContracts(content);
+    if (names.length > 0 && contractDefs.size === 0) {
+      errors.push(`${taskFile}: declares contract(s) but design.md defines no canonical contract blocks`);
+    }
     if (contractDefs.size > 0) {
-      const { names, blocks, firstBlock } = extractTaskContracts(content);
       for (const name of names) {
         if (!contractDefs.has(name)) {
           errors.push(`${taskFile}: declares unknown contract "${name}" (not defined in design.md)`);
@@ -414,9 +680,7 @@ function validateSpec(specDir) {
           ? blocks.get(name)
           : (names.length === 1 ? firstBlock : null);
         if (localCopy === null) {
-          if (names.length > 1) {
-            errors.push(`${taskFile}: contract "${name}" has no <!-- contract:${name} --> tagged block (multi-contract tasks must tag each copy)`);
-          }
+          errors.push(`${taskFile}: contract "${name}" is missing a copied canonical block`);
           continue;
         }
         if (localCopy !== contractDefs.get(name)) {
@@ -432,17 +696,17 @@ function validateSpec(specDir) {
     }
   }
 
+  validateDependencyTopology(spec, taskFiles, spec.task_registry, taskRecords, errors);
+
   for (const requirementId of requirementIds) {
     if (!coveredRequirementIds.has(requirementId)) {
       errors.push(`requirements.md:${requirementId}: not covered by any task`);
     }
   }
 
-  // Per-criterion coverage: only enforced when requirements.md declares explicit
-  // R{N}.{M} literals AND tasks use the numeric `_Requirements: x.y_` mapping.
-  // If a spec declares sub-criteria but no task maps any at sub-level, that is the
-  // legacy coarse format (major-only) — skip silently to avoid false failures.
-  if (subCriteriaIds.length > 0 && coveredSubCriteriaIds.size > 0) {
+  // Per-criterion coverage: every explicit R{N}.{M} literal in requirements.md
+  // must appear in a numeric `_Requirements: x.y_` task mapping.
+  if (subCriteriaIds.length > 0) {
     for (const subId of subCriteriaIds) {
       if (!coveredSubCriteriaIds.has(subId)) {
         errors.push(`requirements.md:${subId}: acceptance criterion not covered by any task`);