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

package/src/claude/rules/state-sync.md

@@ -1,31 +1,62 @@
-# Tollgate Protocol (State Sync)
+# Specs v2.1 state synchronization
 
-## Single Source of Truth
+## Authority layers
 
-In any Spec-driven workflow (`specs`), the state of the project is physically persisted in **two layers**:
-1. **Machine Layer (`spec.json`)**: Tracks phase, status, overall completion, and per-task machine state via `task_registry`.
-2. **Human Layer (`tasks/task-*.md`)**: Checkboxes indicating granular execution progress.
+`spec.json` is machine semantic authority. Requirements, design, conditional
+research, and conditional task Markdown are human projections. Host state may
+record authority or integrity, but it never supplies product semantics.
 
-## The Sync-back Rule (Mandatory)
+Planning depth and assurance level remain independent. The artifact router runs
+before discovery: None persists no spec; Compact and Full persist the bounded
+core; research and tasks remain absent unless their semantic triggers exist.
 
-Whenever an agent finishes a task or blocks due to an issue, it **MUST NOT** simply respond with "Done" or "Blocked" in chat. 
-Before returning control to the user or orchestrator, the agent **MUST**:
+## Canonical lifecycle
 
-### On Success:
-1. Update `spec.json`: Modify `current_phase` if moving forward, ensure `status` accurately reflects progress, keep `task_files` synchronized with the real files on disk, and update the corresponding `task_registry` entry (`status`, `blocker`, `started_at`, `completed_at`, `last_updated_at`).
-2. Edit `task-R*.md`: Change `Status` only after real verification has passed (build/test/runtime/artifact). Then check `[x]` the sub-task boxes and relevant completion criteria.
-3. Call `TaskUpdate` if Claude Tasks are active, setting the status to "completed" only after the physical files were updated.
+The feature lifecycle is exactly `in_progress`, `paused`, `blocked`, or `done`.
+Authoring state is independently `draft`, `validated`, or `absent`. Do not emit
+legacy lifecycle aliases in a new 2.1 artifact.
 
-### On Block/Failure (>3 retries):
-1. Update `spec.json`: Set `"status": "blocked"` and fill out the `"blocker"` string with the root cause.
-2. Update the corresponding `task_registry` entry to `blocked`, persist the blocker reason, and stamp `last_updated_at`.
-3. Edit `task-R*.md`: Change `Status: pending` (or `in_progress`) to `Status: blocked` with a note.
-4. Alert the orchestrator or user via `AskUserQuestion` or explicit warning.
+Technical readiness is not lifecycle completion. `ready_for_implementation`
+may change only through the installed machine finalization path after every
+routed artifact, projection, semantic review, grounding check, and deterministic
+gate passes. An author must not directly declare readiness, authority, approval,
+review capability, execution proof, or closeout.
 
-**Canonical state values:** New specs MUST use `status: "in_progress"` for active work. Legacy `in-progress` may be read for compatibility, but must not be emitted in new files.
+## Projection sync
 
-**Golden Rule:** If the current phase changes, or a task completes, the agent must update the physical files. Never mark a task completed before there is execution proof, and never let `task_registry` disagree with the matching markdown task file. The context is intentionally NOT persisted in the chat to save tokens. An injected Hook (`spec-state.cjs`) constantly enforces and validates this state.
+After any semantic Markdown edit:
 
-### Completion gate (Stop)
+1. invoke the explicit installed machine semantic-sync step to promote `semantic_model`;
+2. regenerate or reconcile every affected Markdown projection;
+3. verify requirements, decisions, anchors, task registry, typed boundaries,
+   and verification refs round-trip without loss; and
+4. rerun the applicable deterministic validation and grounding checks.
 
-Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, `## Evidence` (legacy heading aliases still parse) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).
+For Claude Code, the isolated promotion is
+`node .claude/scripts/spec-scaffold.cjs <feature> --sync-semantic-model`.
+
+Task Markdown exists only when typed ownership, dependency, transition, proof,
+or parallel topology requires it. Its status and dependencies project the
+matching `task_registry` entry. Its Verification Plan is prospective and never
+contains an execution verdict or proof claim. Topology comes only from typed
+`coordination.boundaries`, never from legacy trigger fields, priority markers,
+related-file lists, or prose.
+
+## Lifecycle updates
+
+- Starting or continuing authored work keeps the feature `in_progress`.
+- A deliberate resumable stop uses `paused` with the exact remaining decision.
+- An external or semantic blocker uses `blocked` with a concrete cause.
+- Task state changes update `task_registry` and the matching task projection
+  together, but only from observed work and verification.
+- Feature `done` is reserved for final-state authority after implementation
+  closeout; authoring or readiness cannot produce it.
+
+State synchronization never fabricates commands, PASS results, timestamps,
+receipts, completed work, reviewer identity, or user approval. When execution
+evidence is absent, preserve the unfinished state and report the missing proof.
+Never hand-author the `semantic_model` shape or treat an unsynchronized Markdown
+edit as machine authority.
+
+Claude-native plan/task state may mirror physical state when available, but it
+is never a substitute for `spec.json` or authority to advance the lifecycle.

package/src/claude/rules/workflow.md

@@ -13,14 +13,16 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 ## 2. Plan
 
 - For non-trivial features, use `/specs` to create or validate the spec.
-- For approved specs, work one task file at a time.
+- For technically ready specs, start implementation only after a new explicit Develop invocation and work one task file at a time.
 - Extract from the active task:
-  - `Context`
-  - `Steps`
-  - `Requirements`
-  - `Related Files`
-  - `Completion Criteria`
-  - `Evidence`
+  - `Status`
+  - `Outcome`
+  - `Scope`
+  - `Anchors and Ownership`
+  - `Changes`
+  - `Acceptance`
+  - `Dependencies`
+  - `Verification Plan`
 - If these are missing or too vague to verify, route back to spec correction.
 
 ## 3. Execute
@@ -32,7 +34,7 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 
 ## 4. Verify
 
-- Run exact commands from `Evidence` first.
+- Run exact commands from `Verification Plan` first.
 - Then run repo-level lint/test/build as needed for confidence.
 - Use only fresh verification from the current run when claiming completion.
 - `PRECHECK_FAIL` outranks `NO_TESTS`.
@@ -42,7 +44,13 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 ## 5. Sync
 
 - Mark task state only after implementation, tests/evidence, and review pass.
-- Write a verification receipt with commands run, outcomes, and artifact/runtime proof.
+- Write task proof to `receipts/<task-basename>.md`; use legacy task-local
+  `## Evidence` only when consuming an old task format.
+- Create `feature-receipt.md` only for final integration closeout.
+- Treat `spec.json` as machine authority; task Markdown is a human projection.
+- Derive task ordering, ownership, proof, and parallel eligibility only from
+  typed `coordination.boundaries`, never `(P)`, `task_triggers`, `Related Files`,
+  or prose markers.
 - Keep `spec.json.task_registry` and markdown task files aligned.
 - Run docs checkpoint when a completed task affects public docs or architecture docs.
 

package/src/claude/scripts/provenance.cjs

@@ -0,0 +1,315 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const PROVENANCE_MODE = 'worktree-sha256-v1';
+const CONTEXT_SCHEMA_VERSION = '1';
+const trustedContexts = new WeakSet();
+
+class ProvenanceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ProvenanceError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new ProvenanceError(code, message);
+}
+
+function valueOf(input, snake, camel) {
+  const hasSnake = Object.prototype.hasOwnProperty.call(input, snake);
+  const hasCamel = Object.prototype.hasOwnProperty.call(input, camel);
+  if (hasSnake && hasCamel && input[snake] !== input[camel]) {
+    fail('ambiguous_identity', `${snake} and ${camel} disagree`);
+  }
+  return hasSnake ? input[snake] : input[camel];
+}
+
+function text(value, field) {
+  if (typeof value !== 'string' || value.trim() !== value || value === '' || /[\0\r\n]/.test(value)) {
+    fail('malformed_input', `${field} must be a non-empty single-line string`);
+  }
+  return value;
+}
+
+function inside(root, candidate, field) {
+  const relative = path.relative(root, candidate);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    fail('path_escape', `${field} escapes the project root`);
+  }
+  return relative;
+}
+
+function existingPath(value, field, kind, base = process.cwd()) {
+  const requested = text(value, field);
+  let canonical;
+  try { canonical = fs.realpathSync(path.resolve(base, requested)); } catch (error) {
+    fail('path_error', `${field} cannot be canonicalized (${error.code || error.message})`);
+  }
+  let stat;
+  try { stat = fs.lstatSync(canonical); } catch (error) {
+    fail('path_error', `${field} cannot be inspected (${error.code || error.message})`);
+  }
+  if ((kind === 'directory' && !stat.isDirectory()) || (kind === 'file' && !stat.isFile())) {
+    fail('malformed_input', `${field} is not a ${kind}`);
+  }
+  return canonical;
+}
+
+function runGit(root, args, label) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+  if (result.error || result.status !== 0 || result.signal) {
+    const detail = result.error?.message || String(result.stderr || '').trim() || `exit ${result.status}`;
+    fail('git_command_failed', `${label} failed: ${detail}`);
+  }
+  if (!Buffer.isBuffer(result.stdout)) fail('malformed_git_output', `${label} did not return bytes`);
+  return result.stdout;
+}
+
+function decode(value, label) {
+  const decoded = value.toString('utf8');
+  if (!Buffer.from(decoded, 'utf8').equals(value)) fail('malformed_git_output', `${label} is not valid UTF-8`);
+  return decoded;
+}
+
+function oneLine(value, label) {
+  const output = decode(value, label);
+  if (!/^[^\0\r\n]+\n?$/.test(output)) fail('malformed_git_output', `${label} is not a single line`);
+  return output.replace(/\n$/, '');
+}
+
+function gitBase(root) {
+  const output = oneLine(runGit(root, ['rev-parse', 'HEAD'], 'git rev-parse HEAD')).toLowerCase();
+  if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(output)) fail('malformed_git_output', 'git rev-parse HEAD did not return a commit id');
+  return output;
+}
+
+function gitRoot(requested) {
+  const input = existingPath(requested, 'projectRoot', 'directory');
+  const reported = oneLine(runGit(input, ['rev-parse', '--show-toplevel'], 'git rev-parse --show-toplevel'));
+  const root = existingPath(reported, 'git project root', 'directory');
+  inside(root, input, 'projectRoot');
+  return root;
+}
+
+function splitNul(bytes, label) {
+  if (bytes.length && bytes[bytes.length - 1] !== 0) fail('malformed_git_output', `${label} is not NUL terminated`);
+  return bytes.length === 0 ? [] : bytes.subarray(0, -1).toString('binary').split('\0').map((entry) => {
+    const raw = Buffer.from(entry, 'binary');
+    return decode(raw, label);
+  });
+}
+
+function pathKey(root, relative, label) {
+  if (typeof relative !== 'string' || relative === '' || relative.includes('\0') || path.posix.isAbsolute(relative)) {
+    fail('malformed_git_output', `${label} contains an invalid path`);
+  }
+  const normalized = path.sep === '\\' ? relative.replaceAll('\\', '/') : relative;
+  if (normalized.split('/').includes('..')) fail('path_escape', `${label} escapes the project root`);
+  const absolute = path.resolve(root, ...normalized.split('/'));
+  inside(root, absolute, label);
+  return { relative: normalized, absolute };
+}
+
+function parseStatus(bytes) {
+  const values = splitNul(bytes, 'git status');
+  const entries = new Map();
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value.length < 4 || value[2] !== ' ') fail('malformed_git_output', 'git status emitted an invalid porcelain record');
+    const xy = value.slice(0, 2);
+    const first = value.slice(3);
+    if (xy.includes('R') || xy.includes('C')) {
+      const next = values[++index];
+      if (!next) fail('malformed_git_output', 'git status rename record is incomplete');
+      entries.set(first, { xy, role: 'rename-source', counterpart: next });
+      entries.set(next, { xy, role: 'rename-target', counterpart: first });
+    } else {
+      entries.set(first, { xy, role: xy === '??' || xy === '!!' ? 'untracked' : 'tracked' });
+    }
+  }
+  return entries;
+}
+
+function excluded(root, absolute, specsRoot) {
+  const relative = path.relative(root, absolute).split(path.sep).join('/');
+  const specsRelative = path.relative(root, specsRoot);
+  // These roots are generated runtime state, not source evidence. The selected
+  // canonical specs root is excluded above to avoid receipt/state recursion.
+  const roots = [
+    '.git', 'node_modules', '.claude/hooks/.logs', '.codex/hooks/.logs',
+    '.claude/.logs', '.codex/.logs', '.claude/runtime.json', '.codex/runtime.json',
+  ];
+  if (relative === specsRelative || relative.startsWith(`${specsRelative}/`)) return true;
+  return roots.some((entry) => relative === entry || relative.startsWith(`${entry}/`));
+}
+
+function manifest(root, specsRoot) {
+  const statuses = parseStatus(runGit(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all'], 'git status'));
+  const tracked = [
+    ...splitNul(runGit(root, ['ls-files', '-z', '--cached'], 'git ls-files'), 'git ls-files'),
+    ...splitNul(runGit(root, ['ls-tree', '-r', '-z', '--name-only', 'HEAD'], 'git ls-tree'), 'git ls-tree'),
+    ...statuses.keys(),
+  ];
+  const paths = [...new Set(tracked)].map((entry) => pathKey(root, entry, 'worktree path'))
+    .filter(({ absolute }) => !excluded(root, absolute, specsRoot))
+    .sort((left, right) => left.relative < right.relative ? -1 : left.relative > right.relative ? 1 : 0);
+  const unique = new Map(paths.map((entry) => [entry.relative, entry]));
+  const records = [];
+  for (const { relative, absolute } of unique.values()) {
+    let before;
+    try { before = fs.lstatSync(absolute); } catch (error) {
+      if (error.code === 'ENOENT') { records.push({ path: relative, type: 'deleted', mode: '0000', status: statuses.get(relative) || null, content: null }); continue; }
+      fail('path_error', `cannot inspect ${relative} (${error.code || error.message})`);
+    }
+    const mode = (before.mode & 0o7777).toString(8).padStart(4, '0');
+    let content;
+    let type = 'file';
+    if (before.isSymbolicLink()) { type = 'symlink'; content = Buffer.from(fs.readlinkSync(absolute), 'utf8'); }
+    else if (before.isFile()) { content = fs.readFileSync(absolute); }
+    else { type = before.isDirectory() ? 'directory' : 'special'; content = Buffer.alloc(0); }
+    let after;
+    try { after = fs.lstatSync(absolute); } catch { fail('worktree_race', `${relative} changed during provenance capture`); }
+    if (before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.mode !== after.mode) {
+      fail('worktree_race', `${relative} changed during provenance capture`);
+    }
+    records.push({ path: relative, type, mode, status: statuses.get(relative) || null, content: content.toString('base64') });
+  }
+  return { status: [...statuses.entries()], records };
+}
+
+function manifestDigest(snapshot) {
+  const hash = crypto.createHash('sha256');
+  hash.update('cafekit-provenance\0');
+  for (const record of snapshot.records) hash.update(`${JSON.stringify(record)}\n`);
+  return hash.digest('hex');
+}
+
+function identity(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail('malformed_input', 'runtime provenance input must be an object');
+  const root = gitRoot(valueOf(input, 'project_root', 'projectRoot'));
+  const specsRoot = existingPath(valueOf(input, 'specs_root', 'specsRoot'), 'specsRoot', 'directory', root);
+  inside(root, specsRoot, 'specsRoot');
+  if (specsRoot === root) fail('ambiguous_identity', 'specsRoot must be a distinct project subdirectory');
+  const specFile = existingPath(valueOf(input, 'spec_file', 'specFile'), 'specFile', 'file', root);
+  inside(specsRoot, specFile, 'specFile');
+  const feature = text(valueOf(input, 'feature_name', 'featureName'), 'feature_name');
+  if (feature.includes('/') || feature.includes('\\') || feature === '.' || feature === '..') fail('ambiguous_identity', 'feature_name must be one path segment');
+  const featureDir = existingPath(path.join(specsRoot, feature), 'feature directory', 'directory');
+  if (path.dirname(specFile) !== featureDir) fail('ambiguous_identity', 'feature_name does not identify the selected spec file');
+  const session = text(valueOf(input, 'runtime_session', 'runtimeSession'), 'runtime_session');
+  const requestedMode = valueOf(input, 'provenance_mode', 'provenanceMode');
+  const mode = requestedMode === undefined ? PROVENANCE_MODE : text(requestedMode, 'provenance_mode');
+  if (mode !== PROVENANCE_MODE) fail('malformed_input', `unsupported provenance mode: ${mode}`);
+  return { root, specsRoot, specFile, feature, session, mode };
+}
+
+function deriveRuntimeProvenance(input) {
+  const current = identity(input);
+  const base = gitBase(current.root);
+  const first = manifest(current.root, current.specsRoot);
+  const head = manifestDigest(first);
+  const second = manifest(current.root, current.specsRoot);
+  if (JSON.stringify(first) !== JSON.stringify(second) || gitBase(current.root) !== base) fail('worktree_race', 'checkout changed during provenance capture');
+  const stable = {
+    schema_version: CONTEXT_SCHEMA_VERSION,
+    project_root: current.root,
+    specs_root: current.specsRoot,
+    spec_file: current.specFile,
+    feature_name: current.feature,
+    runtime_session: current.session,
+    provenance_mode: current.mode,
+    Base: base,
+    Head: head,
+  };
+  const contextId = crypto.createHash('sha256').update(JSON.stringify(stable)).digest('hex');
+  const context = Object.freeze({
+    ...stable,
+    base,
+    head,
+    context_id: contextId,
+    contextId,
+    expected_provenance: Object.freeze({ base, head }),
+  });
+  trustedContexts.add(context);
+  return context;
+}
+
+function isTrustedRuntimeContext(value) {
+  return Boolean(value && typeof value === 'object' && trustedContexts.has(value));
+}
+
+function recomputeRuntimeProvenance(value) {
+  if (!isTrustedRuntimeContext(value)) fail('untrusted_context', 'runtime provenance context was not derived by the runtime helper');
+  return deriveRuntimeProvenance({
+    projectRoot: value.project_root,
+    specsRoot: value.specs_root,
+    specFile: value.spec_file,
+    featureName: value.feature_name,
+    runtimeSession: value.runtime_session,
+    provenanceMode: value.provenance_mode,
+  });
+}
+
+function createReceiptBinding(value) {
+  const context = recomputeRuntimeProvenance(value);
+  const binding = Object.freeze({
+    expectedProvenance: Object.freeze({ base: context.base, head: context.head }),
+    requireProvenanceBinding: true,
+    runtimeContext: context,
+    contextId: context.context_id,
+  });
+  return binding;
+}
+
+function parseArgs(argv) {
+  const result = { json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') result.json = true;
+    else if (arg === '--project-root') result.projectRoot = argv[++index];
+    else if (arg === '--specs-root') result.specsRoot = argv[++index];
+    else if (arg === '--spec-file') result.specFile = argv[++index];
+    else if (arg === '--feature-name') result.featureName = argv[++index];
+    else if (arg === '--runtime-session' || arg === '--session') result.runtimeSession = argv[++index];
+    else if (arg === '--provenance-mode') result.provenanceMode = argv[++index];
+    else fail('malformed_input', `unknown option: ${arg}`);
+  }
+  return result;
+}
+
+function runCli(argv = process.argv.slice(2)) {
+  let options;
+  try {
+    options = parseArgs(argv);
+    const context = deriveRuntimeProvenance(options);
+    const output = { ok: true, context, Base: context.base, Head: context.head, context_id: context.context_id };
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+    return 0;
+  } catch (error) {
+    const output = { ok: false, error: { code: error.code || 'provenance_failed', message: error.message } };
+    if (options?.json) process.stdout.write(`${JSON.stringify(output)}\n`);
+    else process.stderr.write(`${output.error.code}: ${output.error.message}\n`);
+    return 2;
+  }
+}
+
+if (require.main === module) process.exitCode = runCli();
+
+module.exports = {
+  CONTEXT_SCHEMA_VERSION,
+  PROVENANCE_MODE,
+  ProvenanceError,
+  createReceiptBinding,
+  deriveRuntimeContext: deriveRuntimeProvenance,
+  deriveRuntimeProvenance,
+  isTrustedRuntimeContext,
+  recomputeRuntimeContext: recomputeRuntimeProvenance,
+  recomputeRuntimeProvenance,
+  runCli,
+};