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

package/src/claude/scripts/spec-authoring-digest.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+// Shared C16 freshness primitive (D13). Owned by R0-01. This module is the sole
+// place the raw-byte / stable-JSON digest algorithm for authoring artifacts is
+// implemented; R1-01's spec-authoring-validation.cjs and validate-spec-output.cjs's
+// authorized_evolution/finalizer freshness checks reuse it unmodified (I20).
+//
+// Non-circular: every digest here is computed only from an authored artifact's own
+// bytes (requirements.md, design.md, research.md, task files). None of these ever
+// hash semantic_digest, review_receipt_digest, or the C16 receipt's own bytes.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RESEARCH_ABSENT_DIGEST = 'RESEARCH_ABSENT_DIGEST';
+const TASKS_ABSENT_DIGEST = 'TASKS_ABSENT_DIGEST';
+
+function asciiOrdinalCompare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// Canonical stable-JSON bytes: object keys sorted by the same ordinal rule
+// (JS's default Array.prototype.sort() on strings already compares by UTF-16
+// code unit, i.e. ASCII ordinal for the ASCII-restricted keys/values in scope
+// here), arrays kept in caller-supplied order. Matches the stableJson
+// convention already used by spec-semantic-model.cjs / validate-spec-output.cjs.
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256Hex(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function sha256Tag(bytes) {
+  return `sha256:${sha256Hex(bytes)}`;
+}
+
+// Raw-byte sha256 of an exact file's current bytes, no normalization. Throws on
+// a missing/non-regular file so callers cannot silently digest a symlink or a
+// directory as if it were authored content.
+function digestFileBytes(absolutePath) {
+  const stat = fs.lstatSync(absolutePath);
+  if (!stat.isFile()) throw new Error(`${absolutePath} is not a regular file`);
+  return sha256Tag(fs.readFileSync(absolutePath));
+}
+
+function listTaskFiles(specDir) {
+  const tasksDir = path.join(specDir, 'tasks');
+  let entries;
+  try {
+    entries = fs.readdirSync(tasksDir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => `tasks/${entry.name}`);
+}
+
+// sha256 over the stable-JSON canonical bytes of an array of {path, digest}
+// objects, one per task file, sorted by path with the exact ASCII ordinal
+// comparator (never localeCompare) — or the exact sentinel when taskless.
+function computeTasksBundleDigest(specDir) {
+  const taskPaths = listTaskFiles(specDir);
+  if (taskPaths.length === 0) return TASKS_ABSENT_DIGEST;
+  const bundle = taskPaths
+    .map((relativePath) => ({
+      path: relativePath,
+      digest: digestFileBytes(path.join(specDir, relativePath)),
+    }))
+    .sort((a, b) => asciiOrdinalCompare(a.path, b.path));
+  return sha256Tag(Buffer.from(stableJson(bundle), 'utf8'));
+}
+
+// Raw-byte sha256 of research.md, or the exact sentinel when absent. Absence is
+// read from the file itself (the durable, unambiguous signal), not from the
+// authoring.research enum, so this never depends on a caller-supplied claim.
+function computeResearchDigest(specDir) {
+  const researchPath = path.join(specDir, 'research.md');
+  try {
+    const stat = fs.lstatSync(researchPath);
+    if (!stat.isFile()) return RESEARCH_ABSENT_DIGEST;
+  } catch (error) {
+    if (error.code === 'ENOENT') return RESEARCH_ABSENT_DIGEST;
+    throw error;
+  }
+  return digestFileBytes(researchPath);
+}
+
+// Fresh digests recomputed, at read time, over a spec's exact current authoring
+// bytes — the four C16 stages.
+function computeCurrentDigests(specDir) {
+  return {
+    requirements: digestFileBytes(path.join(specDir, 'requirements.md')),
+    design: digestFileBytes(path.join(specDir, 'design.md')),
+    research: computeResearchDigest(specDir),
+    tasks: computeTasksBundleDigest(specDir),
+  };
+}
+
+// I20 exact freshness algorithm: a stage is fresh iff its authoring.<field>
+// enum reads "validated" AND the C16 receipt is present with a stored digest
+// for that field that exactly equals a digest freshly recomputed over the
+// field's current bytes. Every other combination reads as draft.
+function isFieldFresh({ authoringValue, receiptEntry, currentDigest }) {
+  if (authoringValue !== 'validated') return false;
+  if (!receiptEntry || typeof receiptEntry !== 'object') return false;
+  if (typeof receiptEntry.digest !== 'string') return false;
+  return receiptEntry.digest === currentDigest;
+}
+
+// Convenience wrapper: given a spec.json's own `authoring` and
+// `validation.authoring_validation` (may be absent/null), report freshness for
+// the requested stages against the spec's current on-disk bytes.
+function assertAuthoringFresh({ specDir, authoring, receipt, fields = ['requirements', 'design'] }) {
+  const currentDigests = computeCurrentDigests(specDir);
+  const report = {};
+  for (const field of fields) {
+    const authoringValue = authoring && typeof authoring === 'object' ? authoring[field] : undefined;
+    const receiptEntry = receipt && typeof receipt === 'object' ? receipt[field] : undefined;
+    report[field] = {
+      digest: currentDigests[field],
+      authoringValue,
+      fresh: isFieldFresh({ authoringValue, receiptEntry, currentDigest: currentDigests[field] }),
+    };
+  }
+  return report;
+}
+
+module.exports = {
+  RESEARCH_ABSENT_DIGEST,
+  TASKS_ABSENT_DIGEST,
+  asciiOrdinalCompare,
+  stableJson,
+  sha256Hex,
+  sha256Tag,
+  digestFileBytes,
+  listTaskFiles,
+  computeTasksBundleDigest,
+  computeResearchDigest,
+  computeCurrentDigests,
+  isFieldFresh,
+  assertAuthoringFresh,
+};

package/src/claude/scripts/spec-authoring-validation.cjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+'use strict';
+
+// C16/D13 sole atomic writer (I21): the only code path permitted to set an
+// authoring stage to `validated` or to write `validation.authoring_validation`.
+// It builds an in-memory candidate spec.json (never persisted mid-run), proves
+// it clean via the canonical validate-spec-output.cjs + spec-ground.cjs pass
+// over that exact candidate, computes the C16 digests via the shared
+// R0-01-owned spec-authoring-digest.cjs primitive, and only on a fully clean
+// pass atomically replaces spec.json (write-temp-then-rename) with the updated
+// `authoring.*` enum values and the fresh receipt written together. A failed,
+// partial, or exceptional run leaves spec.json completely unchanged.
+
+const fs = require('fs');
+const path = require('path');
+const { validateSpec } = require('./validate-spec-output.cjs');
+const { groundSpec } = require('./spec-ground.cjs');
+const DIGEST = require('./spec-authoring-digest.cjs');
+
+const AUTHORING_FIELDS = ['requirements', 'design', 'research', 'tasks'];
+
+function usage() {
+  console.error('Usage: node spec-authoring-validation.cjs specs/<feature> [--root <path>]');
+}
+
+function resolveSpecDir(input) {
+  const cwd = process.cwd();
+  const direct = path.resolve(cwd, input);
+  if (fs.existsSync(direct)) return direct;
+  const viaSpecs = path.resolve(cwd, 'specs', input);
+  if (fs.existsSync(viaSpecs)) return viaSpecs;
+  return direct;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+// In-memory candidate: every non-absent authoring field flips to `validated`
+// and a fresh C16 receipt (all four stages, always present, non-circular —
+// computed only from the authored artifacts' own current bytes) is attached.
+// Both writes happen together in the same candidate object (I21).
+function buildCandidate(currentSpec, specDir, nowIso) {
+  if (!isPlainObject(currentSpec.authoring)) throw new Error('spec.json.authoring must be an object');
+  const currentDigests = DIGEST.computeCurrentDigests(specDir);
+  const candidate = cloneJson(currentSpec);
+  const authoring = { ...candidate.authoring };
+  for (const field of AUTHORING_FIELDS) {
+    if (authoring[field] !== 'absent') authoring[field] = 'validated';
+  }
+  candidate.authoring = authoring;
+  candidate.updated_at = nowIso;
+  candidate.validation = {
+    ...candidate.validation,
+    authoring_validation: {
+      schema_version: '1',
+      requirements: { digest: currentDigests.requirements, validated_at: nowIso },
+      design: { digest: currentDigests.design, validated_at: nowIso },
+      research: { digest: currentDigests.research, validated_at: nowIso },
+      tasks: { digest: currentDigests.tasks, validated_at: nowIso },
+    },
+  };
+  return candidate;
+}
+
+function atomicReplaceSpec(specJsonPath, candidate) {
+  const body = `${JSON.stringify(candidate, null, 2)}\n`;
+  const tempPath = `${specJsonPath}.spec-authoring-validation-${process.pid}-${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, body);
+  fs.renameSync(tempPath, specJsonPath);
+}
+
+// Runs the coordinator over one spec directory. Never partially persists: a
+// clean validate+ground pass on the candidate is required before any write.
+function runAuthoringValidation({ specDir, root = null }) {
+  const specJsonPath = path.join(specDir, 'spec.json');
+  const currentSpec = JSON.parse(fs.readFileSync(specJsonPath, 'utf8'));
+  const nowIso = new Date().toISOString();
+  const candidate = buildCandidate(currentSpec, specDir, nowIso);
+
+  const validation = validateSpec(specDir, candidate);
+  const grounding = groundSpec({ specDir, root, spec: candidate });
+  const errors = [
+    ...validation.errors.map((error) => `validate-spec-output: ${error}`),
+    ...grounding.errors.map((error) => `spec-ground: ${error}`),
+  ];
+  if (errors.length > 0) return { ok: false, errors, candidate: null };
+
+  atomicReplaceSpec(specJsonPath, candidate);
+  return { ok: true, errors: [], candidate };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const rootFlagIndex = args.indexOf('--root');
+  const root = rootFlagIndex >= 0 ? path.resolve(process.cwd(), args[rootFlagIndex + 1] || '') : null;
+  const positional = args.filter((arg, index) => arg !== '--root' && (rootFlagIndex < 0 || index !== rootFlagIndex + 1));
+  if (positional.length !== 1) { usage(); process.exit(2); }
+  const specDir = resolveSpecDir(positional[0]);
+  if (!fs.existsSync(path.join(specDir, 'spec.json'))) {
+    console.error(`spec-authoring-validation: no spec.json found at ${specDir}`);
+    process.exit(2);
+  }
+  let result;
+  try {
+    result = runAuthoringValidation({ specDir, root });
+  } catch (error) {
+    console.error(`AUTHORING_VALIDATION_ERROR ${specDir}`);
+    console.error(`- ${error.message}`);
+    process.exit(2);
+  }
+  if (!result.ok) {
+    console.error(`AUTHORING_VALIDATION_FAIL ${specDir}`);
+    for (const error of result.errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+  console.log(`AUTHORING_VALIDATED ${specDir}`);
+}
+
+module.exports = { runAuthoringValidation, buildCandidate };
+
+if (require.main === module) main();

package/src/claude/scripts/spec-final-state.cjs

@@ -3,6 +3,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const SEMANTIC = require('./spec-semantic-model.cjs');
 
 const SHA256_RE = /^sha256:[a-f0-9]{64}$/;
 
@@ -49,6 +50,49 @@ function validatorApi(validatorPath) {
   return imported;
 }
 
+function stableDigest(value) {
+  return `sha256:${crypto.createHash('sha256').update(SEMANTIC.stableJson(value), 'utf8').digest('hex')}`;
+}
+
+function validateTerminalSemanticReview(spec, semanticDigest) {
+  const review = spec.validation?.semantic_review;
+  if (!plain(review) || review.status !== 'completed') {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires a completed semantic review receipt' };
+  }
+  if (review.verdict !== 'PASS' || review.lifecycle_disposition !== 'CONTINUE') {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires semantic review PASS CONTINUE' };
+  }
+  if (!Array.isArray(review.findings) || !Array.isArray(review.unresolved_decisions)) {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires canonical semantic review findings and decisions' };
+  }
+  const blockingCount = review.findings.filter((finding) => finding?.blocking === true).length
+    + review.unresolved_decisions.filter((decision) => decision?.blocking === true).length;
+  if (blockingCount !== 0) {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires zero blocking findings or decisions' };
+  }
+
+  const entries = spec.validation?.semantic_review_history?.entries;
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires a latest semantic review history entry' };
+  }
+  const latest = entries[entries.length - 1];
+  if (latest?.verdict !== 'PASS'
+    || latest?.lifecycle_disposition !== 'CONTINUE'
+    || latest?.blocking_count !== 0) {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires latest history PASS CONTINUE with blocking_count 0' };
+  }
+  if (latest.semantic_digest !== semanticDigest || latest.semantic_digest !== review.semantic_digest) {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires latest history and receipt semantic_digest to match' };
+  }
+  if (!Number.isInteger(review.repair_round) || review.repair_round !== latest.attempt_index) {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires receipt repair_round to equal latest history attempt_index' };
+  }
+  if (latest.review_receipt_digest !== stableDigest(review)) {
+    return { ok: false, reason: 'canonical schema 2.1 final state requires latest history review_receipt_digest to match the canonical receipt' };
+  }
+  return { ok: true };
+}
+
 function isDurableCloseout(spec) {
   if (!plain(spec)) return false;
   if (spec.schema_version === '2.1') return spec.status === 'done';
@@ -99,6 +143,8 @@ function validateCanonicalFinalState({ policy, projectRoot, candidate, dependenc
     return { ok: false, reason: `canonical semantic digest could not be recomputed (${error.message})` };
   }
   if (digest !== review.semantic_digest) return { ok: false, reason: 'canonical semantic digest is stale for the current final-state artifacts' };
+  const terminalReview = validateTerminalSemanticReview(candidate.spec, digest);
+  if (!terminalReview.ok) return { ok: false, reason: terminalReview.reason };
   if (policy.readWorkflowPolicySnapshot(candidate.spec).assurance_level === 'Strict') {
     const observed = apis.semanticAuthority.verifyAttestation(projectRoot, candidate.specFile, candidate.featureName, digest);
     if (!observed?.ok) return { ok: false, reason: `Strict semantic authority requires an allowlisted host-hook-observed reviewer PASS event (${observed?.reason || 'observation unavailable'})` };

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

@@ -343,7 +343,11 @@ function intendedAction(anchor) {
   return anchor.schema21 ? anchor.action : legacyIntendedAction(anchor);
 }
 
-function groundPathTarget(anchor, root, createdTargets, errors) {
+function createTargetMayAlreadyExist(anchor) {
+  return anchor.schema21 && ['in_progress', 'done'].includes(anchor.taskStatus);
+}
+
+function groundPathTarget(anchor, root, createdTargets, plannedDependencyReads, errors) {
   const prefix = `${anchor.label}: ${anchor.id || anchor.type}`;
   const inspected = inspectPath(root, anchor.target);
   if (!inspected.valid) {
@@ -355,9 +359,11 @@ function groundPathTarget(anchor, root, createdTargets, errors) {
     const parent = inspectPath(root, path.dirname(anchor.target));
     if (!parent.valid || !parent.exists || !parent.stat.isDirectory()) {
       errors.push(`${prefix}: create target parent is not grounded for ${anchor.target}`);
-    } else if (inspected.exists) errors.push(`${prefix}: create target already exists: ${anchor.target}`);
+    } else if (inspected.exists && !createTargetMayAlreadyExist(anchor)) {
+      errors.push(`${prefix}: create target already exists: ${anchor.target}`);
+    }
     else createdTargets.add(anchor.target);
-  } else if (!inspected.exists && !createdTargets.has(anchor.target)) {
+  } else if (!inspected.exists && !plannedDependencyReads.has(`${anchor.label}\0${anchor.target}`)) {
     errors.push(`${prefix}: ${action} target not found in work tree: ${anchor.target}`);
   }
 }
@@ -421,10 +427,12 @@ function groundCommand(anchor, root, scripts, errors, warnings) {
   void warnings;
 }
 
-function groundAnchor(anchor, root, scripts, bodies, createdTargets, reachableAnchors, errors, warnings) {
+function groundAnchor(anchor, root, scripts, bodies, createdTargets, plannedDependencyReads, reachableAnchors, errors, warnings) {
   const prefix = `${anchor.label}: ${anchor.id || anchor.type}`;
   if (!ANCHOR_TYPES.has(anchor.type)) return;
-  if (anchor.type === 'file' || anchor.type === 'artifact') return groundPathTarget(anchor, root, createdTargets, errors);
+  if (anchor.type === 'file' || anchor.type === 'artifact') {
+    return groundPathTarget(anchor, root, createdTargets, plannedDependencyReads, errors);
+  }
   if (anchor.type === 'symbol') {
     const parts = symbolParts(anchor.target);
     if (!parts) {
@@ -441,7 +449,9 @@ function groundAnchor(anchor, root, scripts, bodies, createdTargets, reachableAn
     const body = fs.readFileSync(inspected.target, 'utf8');
     const escaped = parts.symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const exists = new RegExp(`(?:^|[^A-Za-z0-9_$])${escaped}(?:$|[^A-Za-z0-9_$])`, 'm').test(body);
-    if (intendedAction(anchor) === 'create' && exists) errors.push(`${prefix}: create symbol already exists: ${anchor.target}`);
+    if (intendedAction(anchor) === 'create' && exists && !createTargetMayAlreadyExist(anchor)) {
+      errors.push(`${prefix}: create symbol already exists: ${anchor.target}`);
+    }
     else if (intendedAction(anchor) !== 'create' && !exists) {
       errors.push(`${prefix}: symbol ${parts.symbol} not found in containing file ${parts.file}`);
     }
@@ -452,7 +462,9 @@ function groundAnchor(anchor, root, scripts, bodies, createdTargets, reachableAn
     const exists = semanticTargetExists(anchor, bodies);
     if (intendedAction(anchor) === 'create' && !reachableAnchors.has(anchor.id)) {
       errors.push(`${prefix}: create ${anchor.type} requires repository entrypoint registration reachability`);
-    } else if (intendedAction(anchor) === 'create' && exists) errors.push(`${prefix}: create ${anchor.type} already exists: ${anchor.target}`);
+    } else if (intendedAction(anchor) === 'create' && exists && !createTargetMayAlreadyExist(anchor)) {
+      errors.push(`${prefix}: create ${anchor.type} already exists: ${anchor.target}`);
+    }
     else if (intendedAction(anchor) !== 'create' && !exists) errors.push(`${prefix}: ${anchor.type} target is not semantically reachable: ${anchor.target}`);
     return;
   }
@@ -521,10 +533,20 @@ function groundSpec({ specDir: inputSpecDir, root: inputRoot = null, spec: input
       if (SEMANTIC.stableJson(spec.semantic_model) !== SEMANTIC.stableJson(projection.model)) {
         errors.push('spec.json: semantic_model differs from authored Markdown projection; rerun spec-readiness with the current semantic review result');
       }
-      const labelByTask = new Map(Object.entries(spec.task_registry || {}).map(([taskPath, entry]) => [entry?.id, taskPath]));
+      const taskById = new Map(Object.entries(spec.task_registry || {}).map(([taskPath, entry]) => [entry?.id, {
+        path: taskPath,
+        status: entry?.status,
+      }]));
       anchors = (spec.semantic_model.anchors || []).map((anchor) => {
         const taskId = anchor.id.match(/^A-(R\d+-\d{2})-/)?.[1];
-        return { ...anchor, label: taskId ? (labelByTask.get(taskId) || taskId) : 'design.md', design: !taskId, schema21: true };
+        const task = taskId ? taskById.get(taskId) : null;
+        return {
+          ...anchor,
+          label: task?.path || taskId || 'design.md',
+          taskStatus: task?.status || null,
+          design: !taskId,
+          schema21: true,
+        };
       });
       verificationDefinitions = new Map((spec.semantic_model.verification_definitions || []).map((definition) => [definition.id, definition]));
     }
@@ -558,6 +580,20 @@ function groundSpec({ specDir: inputSpecDir, root: inputRoot = null, spec: input
   const scripts = packageScripts(root);
   const bodies = sourceBodies(root, [specDir]);
   const createdTargets = new Set();
+  const plannedDependencyReads = new Set();
+  if (is21) {
+    const creatorsByTarget = new Map();
+    for (const anchor of anchors) if (!anchor.design && intendedAction(anchor) === 'create') {
+      if (!creatorsByTarget.has(anchor.target)) creatorsByTarget.set(anchor.target, []);
+      creatorsByTarget.get(anchor.target).push(anchor.label);
+    }
+    for (const anchor of anchors) if (!anchor.design && intendedAction(anchor) === 'read') {
+      const dependencies = spec.task_registry?.[anchor.label]?.dependencies || [];
+      if ((creatorsByTarget.get(anchor.target) || []).some((producer) => producer === anchor.label || dependencies.includes(producer))) {
+        plannedDependencyReads.add(`${anchor.label}\0${anchor.target}`);
+      }
+    }
+  }
   const reachableAnchors = new Set();
   if (is21) for (const definition of verificationDefinitions.values()) {
     const entrypoint = inspectPath(root, definition.reachability?.entrypoint);
@@ -574,7 +610,7 @@ function groundSpec({ specDir: inputSpecDir, root: inputRoot = null, spec: input
     }
   }
   if (isV2) for (const anchor of anchors) {
-    groundAnchor(anchor, root, scripts, bodies, createdTargets, reachableAnchors, errors, warnings);
+    groundAnchor(anchor, root, scripts, bodies, createdTargets, plannedDependencyReads, reachableAnchors, errors, warnings);
   }
   else groundLegacy(anchors, spec?.task_registry, root, errors);
   return { errors, warnings, checked: anchors.length, specDir, root };