@haposoft/cafekit 0.16.0-rc.3 → 0.16.0-rc.4

package/src/claude/scripts/spec-readiness.cjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const SEMANTIC = require('./spec-semantic-model.cjs');
+const VALIDATOR = require('./validate-spec-output.cjs');
+const { canonicalProjectRoot, groundSpec } = require('./spec-ground.cjs');
+
+function plain(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function exactKeys(value, fields) {
+  return plain(value)
+    && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...fields].sort());
+}
+
+function readReviewResult(input) {
+  if (!exactKeys(input, ['reviewed_criteria', 'counterexamples'])) {
+    throw new Error('semantic review result fields must be exactly reviewed_criteria and counterexamples');
+  }
+  return JSON.parse(JSON.stringify(input));
+}
+
+function atomicReplace(file, bytes, io = fs) {
+  const stat = io.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('spec.json must be a regular non-symlink file');
+  const original = io.readFileSync(file);
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.finalize-${process.pid}-${Date.now()}`);
+  let descriptor;
+  try {
+    descriptor = io.openSync(temporary, 'wx', stat.mode);
+    io.writeFileSync(descriptor, bytes);
+    io.fsyncSync(descriptor);
+    io.closeSync(descriptor);
+    descriptor = undefined;
+    if (process.env.CAFEKIT_FINALIZE_FAIL_BEFORE_RENAME === '1') throw new Error('injected finalization failure before rename');
+    io.renameSync(temporary, file);
+  } catch (error) {
+    if (descriptor !== undefined) try { io.closeSync(descriptor); } catch {}
+    try { io.unlinkSync(temporary); } catch {}
+    if (!io.readFileSync(file).equals(original)) {
+      const rollback = `${temporary}-rollback`;
+      try {
+        io.writeFileSync(rollback, original, { flag: 'wx', mode: stat.mode });
+        io.renameSync(rollback, file);
+      } finally { try { io.unlinkSync(rollback); } catch {} }
+    }
+    throw error;
+  }
+}
+
+function finalizeReadiness({ specDir, reviewResult, projectRoot, io = fs }) {
+  const directory = io.realpathSync(path.resolve(specDir));
+  const root = projectRoot ? io.realpathSync(path.resolve(projectRoot)) : canonicalProjectRoot(directory);
+  const relative = path.relative(root, directory);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error('spec directory escapes the canonical project root');
+  }
+  const specFile = path.join(directory, 'spec.json');
+  const original = io.readFileSync(specFile);
+  let spec;
+  try { spec = JSON.parse(original); } catch (error) { throw new Error(`spec.json is invalid JSON (${error.message})`); }
+  if (!plain(spec) || spec.schema_version !== '2.1') throw new Error('readiness finalization accepts canonical schema 2.1 only');
+  const review = readReviewResult(reviewResult);
+  const projection = SEMANTIC.modelFromMarkdown(directory, spec);
+  if (projection.errors.length) throw new Error(`semantic projection failed (${projection.errors.join('; ')})`);
+  const candidate = JSON.parse(JSON.stringify(spec));
+  candidate.semantic_model = projection.model;
+  candidate.validation = {
+    status: 'completed',
+    semantic_review: {
+      status: 'not-run', semantic_digest: null, reviewed_criteria: [], counterexamples: [],
+    },
+  };
+  candidate.ready_for_implementation = false;
+  const digestResult = VALIDATOR.computeSemanticDigest21(directory, candidate);
+  if (digestResult.errors.length) throw new Error(`semantic digest failed (${digestResult.errors.join('; ')})`);
+  candidate.validation.semantic_review = {
+    status: 'completed', semantic_digest: digestResult.digest,
+    reviewed_criteria: review.reviewed_criteria, counterexamples: review.counterexamples,
+  };
+  candidate.ready_for_implementation = true;
+  candidate.updated_at = new Date().toISOString();
+  const validation = VALIDATOR.validateSpec(directory, candidate);
+  if (validation.errors.length) throw new Error(`readiness validation failed (${validation.errors.join('; ')})`);
+  const grounding = groundSpec({ specDir: directory, root, spec: candidate });
+  if (grounding.errors.length) throw new Error(`readiness grounding failed (${grounding.errors.join('; ')})`);
+  const bytes = Buffer.from(`${JSON.stringify(candidate, null, 2)}\n`);
+  atomicReplace(specFile, bytes, io);
+  return { spec: candidate, semantic_digest: digestResult.digest };
+}
+
+function usage() {
+  process.stderr.write('Usage: node .claude/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>\n');
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const marker = args.indexOf('--review-result');
+  if (args.length !== 3 || marker !== 1) { usage(); process.exitCode = 2; return; }
+  try {
+    const reviewFile = path.resolve(args[2]);
+    const reviewStat = fs.lstatSync(reviewFile);
+    if (!reviewStat.isFile() || reviewStat.isSymbolicLink()) throw new Error('review result must be a regular non-symlink JSON file');
+    const reviewResult = JSON.parse(fs.readFileSync(reviewFile, 'utf8'));
+    const result = finalizeReadiness({ specDir: args[0], reviewResult });
+    process.stdout.write(`SPEC_READY ${args[0]} ${result.semantic_digest}\n`);
+  } catch (error) {
+    process.stderr.write(`SPEC_NOT_READY ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { atomicReplace, finalizeReadiness, readReviewResult };
+
+if (require.main === module) main();

package/src/claude/scripts/spec-receipt.cjs

@@ -0,0 +1,162 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const EVIDENCE_HEADINGS = new Set([
+  'Evidence',
+  'Task Test Plan & Verification Evidence',
+  'Verification & Evidence',
+]);
+
+function inside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function safeRead(root, relativePath) {
+  if (typeof relativePath !== 'string' || path.isAbsolute(relativePath)) return { status: 'unsafe' };
+  const segments = relativePath.split(/[\\/]+/);
+  if (segments.length === 0 || segments.some((segment) => !segment || segment === '.' || segment === '..')) return { status: 'unsafe' };
+  const resolvedRoot = path.resolve(root);
+  const target = path.resolve(resolvedRoot, ...segments);
+  if (!inside(resolvedRoot, target)) return { status: 'unsafe' };
+  try {
+    const canonicalRoot = fs.realpathSync(resolvedRoot);
+    let current = resolvedRoot;
+    for (const segment of segments) {
+      current = path.join(current, segment);
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink()) return { status: 'unsafe' };
+    }
+    const canonicalTarget = fs.realpathSync(target);
+    if (!inside(canonicalRoot, canonicalTarget) || !fs.statSync(target).isFile()) return { status: 'unsafe' };
+    return { status: 'ok', path: canonicalTarget, bytes: fs.readFileSync(target) };
+  } catch (error) {
+    return { status: error && error.code === 'ENOENT' ? 'missing' : 'unsafe' };
+  }
+}
+
+function canonicalTaskReceiptPath(taskPath) {
+  if (typeof taskPath !== 'string') return null;
+  const match = taskPath.match(/^tasks\/(task-[A-Za-z0-9][A-Za-z0-9._-]*\.md)$/);
+  return match ? `receipts/${match[1]}` : null;
+}
+
+function evidenceBody(text, policy = {}) {
+  const lines = String(text || '').split('\n');
+  let start = -1;
+  let level = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^(#{2,3})\s+(.+?)\s*$/);
+    if (match && EVIDENCE_HEADINGS.has(match[2])) {
+      start = index + 1;
+      level = match[1].length;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let index = start; index < lines.length; index += 1) {
+    const heading = lines[index].match(/^(#{1,6})\s+/);
+    const tap = typeof policy.isTapMetadataHeading === 'function' && policy.isTapMetadataHeading(lines[index]);
+    if (heading && heading[1].length <= level && !tap) { end = index; break; }
+  }
+  return lines.slice(start, end).join('\n');
+}
+
+function fieldValues(body, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const matcher = new RegExp(`^\\s*${escaped}\\s*:\\s*(.*?)\\s*$`, 'i');
+  return String(body || '').split('\n').map((line) => line.match(matcher)).filter(Boolean).map((match) => match[1]);
+}
+
+function concrete(value) {
+  return typeof value === 'string' && value.trim() !== '' && !/^(?:N\/A|NONE|PENDING|TBD|UNKNOWN|\{\{.*\}\})$/i.test(value.trim());
+}
+
+function plannedField(taskText, name) {
+  const plan = String(taskText || '').split(/^##\s+Verification Plan\s*$/m)[1];
+  if (!plan) return null;
+  const value = fieldValues(plan.split(/^##\s+/m)[0], `- **${name}**`)[0];
+  return value ? value.replace(/^`|`$/g, '').trim() : null;
+}
+
+function identity(body) {
+  const names = ['Verification', 'Command', 'Commands', 'Exit', 'Result', 'Base', 'Head', 'base_sha', 'head_sha'];
+  const fields = names.flatMap((name) => fieldValues(body, name).map((value) => [name.toLowerCase(), value.trim()]));
+  const artifacts = String(body || '').split('\n').filter((line) => /^\s*Artifacts?\s*:|^\s*Artifact\s+produced\b/i.test(line)).map((line) => line.trim());
+  return crypto.createHash('sha256').update(JSON.stringify({ fields, artifacts })).digest('hex');
+}
+
+function canonicalFailures(body, task, runtimeContext, policy) {
+  if (!policy || typeof policy.validateCanonicalReceipt !== 'function') return ['validator_unavailable'];
+  const options = typeof policy.receiptValidatorOptions === 'function'
+    ? policy.receiptValidatorOptions(task || {}, { runtimeContext, requireProvenanceBinding: true })
+    : { requireProvenanceBinding: true };
+  return policy.validateCanonicalReceipt(body, options);
+}
+
+function separateMetadataFailures(body, taskPath, taskText) {
+  const failures = [];
+  const basename = path.posix.basename(taskPath);
+  if (fieldValues(body, 'Task').length !== 1 || fieldValues(body, 'Task')[0] !== basename) failures.push('task_identity');
+  if (fieldValues(body, 'Task path').length !== 1 || fieldValues(body, 'Task path')[0] !== taskPath) failures.push('task_identity');
+  if (!concrete(fieldValues(body, 'Expected')[0]) || !concrete(fieldValues(body, 'Observed')[0])) failures.push('expected_observed');
+  const plannedCommand = plannedField(taskText, 'Command');
+  const actualCommand = fieldValues(body, 'Command')[0] || fieldValues(body, 'Commands')[0];
+  if (plannedCommand && !/^N\/A\b/i.test(plannedCommand) && actualCommand !== plannedCommand) failures.push('command_identity');
+  for (const name of ['Negative path', 'Reachability']) {
+    const planned = plannedField(taskText, name);
+    if (planned && !/^(?:N\/A|none|not relevant)\b/i.test(planned) && !concrete(fieldValues(body, name)[0])) failures.push(name.toLowerCase().replace(' ', '_'));
+  }
+  return [...new Set(failures)];
+}
+
+function readTaskProof(featureDir, taskPath, policy = {}) {
+  const receiptPath = canonicalTaskReceiptPath(taskPath);
+  if (typeof taskPath !== 'string' || !/^tasks\/[^/]+\.md$/.test(taskPath)) return { status: 'unsafe', taskPath, receiptPath: null };
+  const taskFile = safeRead(featureDir, taskPath);
+  if (taskFile.status !== 'ok') return { status: taskFile.status, taskPath, receiptPath };
+  const taskText = taskFile.bytes.toString('utf8');
+  const separate = receiptPath ? safeRead(featureDir, receiptPath) : { status: 'missing' };
+  const legacyBody = evidenceBody(taskText, policy);
+  if (separate.status === 'unsafe') return { status: 'unsafe', taskPath, receiptPath, taskFile };
+  if (separate.status === 'ok') {
+    const body = separate.bytes.toString('utf8');
+    return { status: 'ok', source: 'separate', body, receiptBytes: separate.bytes, receiptFile: separate, taskFile, taskText, taskPath, receiptPath, legacyBody };
+  }
+  if (legacyBody !== null) return { status: 'ok', source: 'legacy', body: legacyBody, receiptBytes: Buffer.from(legacyBody), taskFile, taskText, taskPath, receiptPath, legacyBody };
+  return { status: 'missing', taskPath, receiptPath, taskFile, taskText };
+}
+
+function checkTaskReceipt(featureDir, taskPath, task, runtimeContext, policy) {
+  const proof = readTaskProof(featureDir, taskPath, policy);
+  const failures = [];
+  if (proof.status !== 'ok') return { ...proof, failures: [proof.status === 'unsafe' ? 'unsafe_path' : 'missing_receipt'] };
+  const status = proof.taskText.split('\n').find((line) => /^\s*(?:\*\*)?Status(?:\*\*)?\s*:/i.test(line));
+  if (!status || !/\bdone\b/i.test(status)) failures.push('task_status');
+  failures.push(...canonicalFailures(proof.body, task, runtimeContext, policy));
+  if (proof.source === 'separate') {
+    failures.push(...separateMetadataFailures(proof.body, taskPath, proof.taskText));
+    if (proof.legacyBody !== null
+      && /^\s*Verification:\s*PASS\s*$/m.test(proof.legacyBody)
+      && identity(proof.legacyBody) !== identity(proof.body)) failures.push('receipt_conflict');
+  }
+  const completedAt = task && task.completed_at;
+  if (typeof completedAt !== 'string' || !/^\d{4}-\d{2}-\d{2}T/.test(completedAt) || Number.isNaN(Date.parse(completedAt))) failures.push('completed_at');
+  return { ...proof, failures: [...new Set(failures)] };
+}
+
+function checkFeatureReceipt(featureDir, runtimeContext, policy) {
+  const receipt = safeRead(featureDir, 'feature-receipt.md');
+  if (receipt.status !== 'ok') return { status: receipt.status, failures: [receipt.status === 'unsafe' ? 'unsafe_path' : 'missing_receipt'] };
+  const body = receipt.bytes.toString('utf8');
+  const failures = canonicalFailures(body, {}, runtimeContext, policy);
+  if (fieldValues(body, 'Feature').length !== 1 || fieldValues(body, 'Feature')[0] !== path.basename(featureDir)) failures.push('feature_identity');
+  if (!concrete(fieldValues(body, 'Expected')[0]) || !concrete(fieldValues(body, 'Observed')[0])) failures.push('expected_observed');
+  return { status: 'ok', source: 'feature', body, receiptBytes: receipt.bytes, receiptFile: receipt, failures: [...new Set(failures)] };
+}
+
+module.exports = { canonicalTaskReceiptPath, checkFeatureReceipt, checkTaskReceipt, evidenceBody, readTaskProof, safeRead };

package/src/claude/scripts/spec-resolver.cjs

@@ -250,9 +250,7 @@ function isPathInsideLegacy(parent, child) {
 }
 
 function explicitTargetValue(value) {
-  if (typeof value !== 'string') return null;
-  const trimmed = value.trim();
-  return trimmed ? trimmed : null;
+  return typeof value === 'string' ? value.trim() : value;
 }
 
 /**
@@ -265,12 +263,14 @@ function extractExplicitTarget(...sources) {
     if (!source || typeof source !== 'object') continue;
 
     for (const key of ['explicitFeature', 'featureName', 'feature']) {
-      const value = explicitTargetValue(source[key]);
-      if (value) return { explicitFeature: value };
+      if (Object.prototype.hasOwnProperty.call(source, key)) {
+        return { explicitFeature: explicitTargetValue(source[key]) };
+      }
     }
     for (const key of ['explicitPath', 'specPath', 'spec_path', 'featurePath']) {
-      const value = explicitTargetValue(source[key]);
-      if (value) return { explicitPath: value };
+      if (Object.prototype.hasOwnProperty.call(source, key)) {
+        return { explicitPath: explicitTargetValue(source[key]) };
+      }
     }
 
     const target = source.target;
@@ -278,8 +278,8 @@ function extractExplicitTarget(...sources) {
       const nested = extractExplicitTarget(target);
       if (nested) return nested;
     }
-    const targetValue = explicitTargetValue(target);
-    if (targetValue) {
+    if (Object.prototype.hasOwnProperty.call(source, 'target')) {
+      const targetValue = explicitTargetValue(target);
       return /[\\/]/.test(targetValue) || /(?:^|[\\/])spec\.json$/.test(targetValue)
         ? { explicitPath: targetValue }
         : { explicitFeature: targetValue };
@@ -302,14 +302,23 @@ function resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath
   if (!projectRoot) throw new TypeError('projectRoot required');
   const rt = runtime || {};
   const normalizedTarget = extractExplicitTarget(target);
-  explicitFeature = explicitFeature || normalizedTarget?.explicitFeature;
-  explicitPath = explicitPath || normalizedTarget?.explicitPath;
+  if (explicitFeature === undefined && normalizedTarget
+    && Object.prototype.hasOwnProperty.call(normalizedTarget, 'explicitFeature')) {
+    explicitFeature = normalizedTarget.explicitFeature;
+  }
+  if (explicitPath === undefined && normalizedTarget
+    && Object.prototype.hasOwnProperty.call(normalizedTarget, 'explicitPath')) {
+    explicitPath = normalizedTarget.explicitPath;
+  }
+  const hasExplicitFeature = explicitFeature !== undefined && explicitFeature !== null;
+  const hasExplicitPath = explicitPath !== undefined && explicitPath !== null;
+  const hasExplicitTarget = hasExplicitFeature || hasExplicitPath;
   let specsDir;
   try {
     specsDir = specsDirectory(projectRoot, rt);
   } catch (error) {
     return {
-      error: explicitFeature || explicitPath ? 'explicit_malformed' : 'invalid_specs',
+      error: hasExplicitTarget ? 'explicit_malformed' : 'invalid_specs',
       candidates: ['<specs>'],
       explicitFeature,
       explicitPath,
@@ -319,7 +328,7 @@ function resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath
   let canonicalSpecs;
   const specsLstat = lstatOptional(specsDir);
   if (specsLstat.error) {
-    if (explicitFeature || explicitPath) {
+    if (hasExplicitTarget) {
       return { error: 'explicit_malformed', explicitFeature, explicitPath, reason: `specs lstat error: ${specsLstat.error.message}` };
     }
     return { error: 'invalid_specs', candidates: ['<specs>'], invalid: [{ featureName: '<specs>', reason: `specs lstat error: ${specsLstat.error.message}`, specFile: specsDir }], reason: `Invalid spec JSON: <specs>: specs lstat error: ${specsLstat.error.message}` };
@@ -330,14 +339,14 @@ function resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath
     try {
       canonicalSpecs = fs.realpathSync(specsDir);
     } catch (e) {
-      if (explicitFeature || explicitPath) {
+      if (hasExplicitTarget) {
         return { error: 'explicit_malformed', explicitFeature, explicitPath, reason: `specs root canonicalization error: ${e.message}` };
       }
       return { error: 'invalid_specs', candidates: ['<specs>'], invalid: [{ featureName: '<specs>', reason: `specs root canonicalization error: ${e.message}`, specFile: specsDir }], reason: `Invalid spec JSON: <specs>: specs root canonicalization error: ${e.message}` };
     }
   }
 
-  if (explicitFeature) {
+  if (hasExplicitFeature) {
     if (typeof explicitFeature !== 'string' || explicitFeature.trim() === '' || explicitFeature.includes('/') || explicitFeature.includes('\\') || explicitFeature.includes('..')) {
       return { error: 'explicit_malformed', explicitFeature, reason: `malformed feature name: ${explicitFeature}` };
     }
@@ -367,7 +376,7 @@ function resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath
     }
   }
 
-  if (explicitPath) {
+  if (hasExplicitPath) {
     if (typeof explicitPath !== 'string' || explicitPath.trim() === '') {
       return { error: 'explicit_malformed', explicitPath, reason: 'empty explicit path' };
     }
@@ -441,10 +450,52 @@ function resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath
   };
 }
 
+/**
+ * Resolve one persisted feature identity. Explicit host targets are inspected
+ * directly and never scan siblings; only the no-target path performs a global
+ * persisted-candidate scan and therefore owns ambiguity/invalid-sibling errors.
+ */
+function resolvePersistedSpec({ projectRoot, runtime, explicitFeature, explicitPath, target } = {}) {
+  const normalized = extractExplicitTarget(
+    target,
+    explicitFeature !== undefined ? { explicitFeature } : null,
+    explicitPath !== undefined ? { explicitPath } : null,
+  );
+  if (normalized) {
+    const value = Object.prototype.hasOwnProperty.call(normalized, 'explicitFeature')
+      ? normalized.explicitFeature
+      : normalized.explicitPath;
+    if (value === null || value === undefined) {
+      return { error: 'explicit_malformed', ...normalized, reason: 'explicit target must be a non-empty string' };
+    }
+    return resolveActiveSpec({ projectRoot, runtime, ...normalized });
+  }
+  try {
+    const candidates = findAllSpecCandidates(projectRoot, runtime);
+    if (candidates.length === 0) return null;
+    if (candidates.length === 1) return candidates[0];
+    return {
+      error: 'multiple_persisted',
+      candidates: candidates.map((candidate) => candidate.featureName),
+      reason: `Multiple persisted specs found: ${candidates.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
+    };
+  } catch (error) {
+    return {
+      error: 'invalid_specs',
+      candidates: Array.isArray(error.invalid)
+        ? error.invalid.map((entry) => entry.featureName)
+        : ['<specs>'],
+      invalid: error.invalid || [],
+      reason: error.message,
+    };
+  }
+}
+
 module.exports = {
   specsDirectory,
   findAllActiveSpecs,
   findAllSpecCandidates,
   extractExplicitTarget,
   resolveActiveSpec,
+  resolvePersistedSpec,
 };