@haposoft/cafekit 0.16.7 → 0.18.1

package/src/claude/rules/ai-dev-rules.md

@@ -34,15 +34,14 @@ Keep implementation simple, scoped, and verifiable.
 
 ## Skill And Tooling Use
 
-- Activate relevant skills before specialized work.
-- If a skill plausibly matches the task, prefer its workflow and references over an ad hoc plan.
+- When a skill covers the task, follow its workflow and references instead of an ad hoc plan.
 - Use documentation lookup when current external docs matter.
 - Use `gh` for GitHub workflows and `psql` for Postgres inspection when needed.
 - Use multimodal/image/document skills for visual or document-heavy tasks.
 
 ## Git Hygiene
 
-- Lint before commit.
+- Lint before commit when the project has a linter.
 - Run required tests before push.
 - Keep commits focused.
 - Use conventional commits.

package/src/claude/rules/hook-protocols.md

@@ -4,28 +4,21 @@ Hooks are instruction boundaries. Do not bypass or work around them.
 
 ## Privacy Block Hook
 
-When a tool call is blocked by the privacy hook, the output contains a JSON marker between:
+When a tool call touches a sensitive file, or the hook cannot classify it safely,
+the privacy hook returns a permission decision of `ask` with the reason, and the
+host asks the user to approve or deny that one call. Do not ask again yourself.
+On a host whose hook can only deny, the call is blocked; ask the user instead of
+retrying it another way.
 
-```text
-@@PRIVACY_PROMPT_START@@
-...
-@@PRIVACY_PROMPT_END@@
-```
-
-Required flow:
-
-1. Parse the JSON payload from the marker.
-2. Ask the user for approval using the available user-question tool and the prompt/options from the payload.
-3. If approved, retry only the blocked action.
-4. If denied, continue without reading that file or performing that blocked action.
+- If approved, the call runs; do not widen it to other files.
+- If denied, continue without reading that file or performing that blocked action.
 
 Never use another command, path, encoding, or side channel to access a privacy-blocked file without explicit approval.
 
 ## State And Spec Hooks
 
 - If a hook reports state drift, run the appropriate sync/audit flow before continuing.
-- If a hook rejects task completion, keep the task `in_progress` or `blocked` until proof exists.
-- Do not mark a task `done` unless the matching task file contains a valid verification receipt.
+- If a hook rejects task completion, keep the task `in_progress` or `blocked` until proof exists; the receipt contract lives in `state-sync.md`.
 
 ## Hook Failure Handling
 

package/src/claude/rules/manage-docs.md

@@ -2,7 +2,7 @@
 
 ## Living Documents
 
-The project maintains these core documents in `./docs`:
+When the project keeps these core documents in `./docs`, keep them current (a project may have only some of them):
 
 | Document | Purpose |
 |----------|---------|
@@ -14,8 +14,6 @@ The project maintains these core documents in `./docs`:
 ### Freshness Rule
 
 - Before updating any doc, check its last modified date
-- If a doc hasn't been updated in >2 weeks while development is active, flag it for review
-- The `docs-keeper` agent should proactively scan for stale docs during weekly reviews
 
 ## When to Update
 
@@ -26,7 +24,6 @@ The `docs-keeper` agent is responsible for keeping these documents current. Trig
 - A significant feature ships or a critical bug is resolved
 - Security patches are applied or dependencies change
 - Project scope or timeline shifts
-- Weekly progress reviews are due
 
 ### Update Discipline
 
@@ -43,7 +40,7 @@ Use [Keep a Changelog](https://keepachangelog.com/) convention:
 ## [version] - YYYY-MM-DD
 
 ### Added
-- Feature description (#PR-number)
+- Feature description (#PR-number when there is one)
 
 ### Fixed
 - Bug fix description (#issue-number)
@@ -74,38 +71,27 @@ specs/
 
 Task files are direct children beside `plan.md`; do not place them in a task
 subdirectory.
-The plan records the C1 scope decision, explicit exclusions, acceptance
+The plan records the GATE-SCOPE scope decision, explicit exclusions, acceptance
 criteria, and task mapping. Each task owns one usable outcome, bounded paths,
 dependencies, acceptance, and a runnable Verification Plan.
 
 ### Gates and execution handoff
 
-- C1: the user chooses EXPAND, KEEP, or CUT before the plan is written.
-- C2: the user accepts, rejects, or revises deduplicated adversarial findings.
+- GATE-SCOPE: the user chooses EXPAND, KEEP, or CUT before the plan is written.
+- GATE-REVIEW: the user accepts, rejects, or revises deduplicated adversarial findings.
 - Specs stops after planning; implementation begins only through a new explicit
   Develop invocation.
-- C3: after execution, current receipts and limitations are shown and the user
+- GATE-DONE: after execution, current receipts and limitations are shown and the user
   decides whether the feature is complete.
 
 ### Task state and proof
 
-Each task contains exactly one `Status:` field. The final inline `## Receipt`
-is canonical proof and must contain the exact command, `Exit: 0`,
-`Verification: PASS`, runtime-derived Base and Head values, and non-empty
-fenced current output before the task becomes done.
+Task status, the inline `## Receipt` and its proof contract are defined in
+`state-sync.md`.
 
 Sync only observed state with surgical edits. Re-read the changed task after
 every update; never infer missing proof, approval, or readiness. When a done
 task changes user-facing behavior, architecture, API contracts, operations, or
 project status, classify docs impact and update only affected existing docs.
 
-Comply with the overarching rules in `./rules/ai-dev-rules.md`.
-
-## Legacy specification layout
-
-Existing features containing `spec.json`, nested `tasks/task-R*.md`, or other
-legacy kernel artifacts keep their installed adapters and original layout.
-Preserve `task_registry`, `semantic_model`, `planning_depth`, lane,
-`execution_tier`, machine authority, typed topology, separate receipts, and
-feature closeout files. Do not migrate them as part of unrelated documentation
-work.
+Comply with the overarching rules in `ai-dev-rules.md`.

package/src/claude/rules/orchestrator.md

@@ -22,10 +22,9 @@ Example prompt:
 
 ## Resource Constraints
 
-- Each subagent has a **200K token context window** — scope tasks to fit comfortably within it
-- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out. For parallel implementation waves the cap is 3 concurrent agents by default, never more than 5 (each agent carries the 200K budget above)
+- Each subagent has its own context window — scope tasks to fit comfortably within it
+- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out. For parallel implementation waves the cap is 3 concurrent agents by default, never more than 5 (each agent carries its own context window)
 - Prefer fewer, well-scoped agents over many overlapping ones
-- Include system resource info (from hook injection) when delegating tasks so subagents can self-regulate
 
 ---
 
@@ -132,7 +131,7 @@ Docs: [docs path]
 
 | ❌ Vague | ✅ Precise |
 |----------|-----------|
-| "Pick up where we left off" | "Add the `/users` POST endpoint per `phase-02.md`" |
+| "Pick up where we left off" | "Add the `/users` POST endpoint per `task-02-api.md`" |
 | "Fix the issues we talked about" | "Add null-check in `auth.ts:45` — root cause: missing input validation" |
 | "Explore the codebase" | "Read `src/api/routes.ts`, then add the missing handler" |
 | Dumping 50+ lines of chat history | A 5-line summary with file paths |

package/src/claude/rules/review-audit-self-decision.md

@@ -12,10 +12,10 @@ When rejecting an audit concern, name the verification source briefly.
 
 ## User Decisions
 
-Do not silently undo an explicit user decision. This covers the C1 scope choice,
-C2 finding dispositions, and C3 completion judgement, along with thresholds,
+Do not silently undo an explicit user decision. This covers the GATE-SCOPE scope choice,
+GATE-REVIEW finding dispositions, and GATE-DONE completion judgement, along with thresholds,
 selected libraries, feature scope, schema shape, pricing, timelines, compliance
-choices, and UX trade-offs. Those gates are defined in `workflow.md`; this rule
+choices, and UX trade-offs. Those gates are defined in `state-sync.md`; this rule
 governs only how a later review may treat them.
 
 If an audit suggests reversing a user decision, present:

package/src/claude/rules/skill-domain-routing.md

@@ -27,6 +27,4 @@ an entry condition for the primary. If zero valid capabilities match, continue
 inline when safe or name the gap. If multiple catalog entries expose the same
 public identity, do not auto-route; require explicit user disambiguation.
 
-Never infer an optional document capability from this rule. Never select the
-explicit-only numeric optimization capability unless the user invokes it with
-its required bounded metric/guard contract.
+Never infer an optional document capability from this rule.

package/src/claude/rules/skill-workflow-routing.md

@@ -9,9 +9,9 @@ workflow.
 1. If the user names a valid installed skill, use it directly.
 2. If one obvious low-risk installed skill covers the intent, use it directly.
 3. For direct factual conversation, answer directly or use the installed
-   evidence-answer capability; do not invoke Route or agents for ceremony.
-4. For ambiguous, multi-step, multi-domain, or elevated/high-risk work, use the
-   installed Route capability to classify and compose the shortest valid chain.
+   evidence-answer capability; do not spawn agents for ceremony.
+4. For ambiguous, multi-step, multi-domain, or elevated/high-risk work, classify
+   it yourself and compose the shortest valid chain below.
 
 Resolve every abstract link against the current runtime catalog. An absent,
 invalid, folder-mismatched, duplicate, or retired entry is not routable. Continue
@@ -28,5 +28,4 @@ owner, entry condition, and observable exit per retained link. Diagnosis does
 not authorize repair; implementation does not authorize commit, push, deploy,
 publish, or release; no route expands the user's existing authority.
 
-Use `skill-domain-routing.md` to resolve domain capability slots. The numeric
-optimization capability remains explicit-only and must never be auto-routed.
+Use `skill-domain-routing.md` to resolve domain capability slots.

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

@@ -51,19 +51,10 @@ proves only the boundary it executed.
 
 ## Human gates and workflow ownership
 
-- C1 records the user's scope decision before the plan is written.
-- C2 records the user's disposition of deduplicated adversarial findings.
+- GATE-SCOPE records the user's scope decision before the plan is written.
+- GATE-REVIEW records the user's disposition of deduplicated adversarial findings.
 - Develop starts only after a new explicit user invocation and executes one
   unblocked task at a time.
 - Sync changes only observed file state and never starts implementation.
-- C3 occurs after current receipts and limitations are shown; the user decides
+- GATE-DONE occurs after current receipts and limitations are shown; the user decides
   whether the requested feature is complete.
-
-## Legacy compatibility
-
-Existing packets containing `spec.json`, nested `tasks/task-R*.md`, or other
-legacy kernel artifacts stay on their installed adapters. Preserve their
-`task_registry`, `semantic_model`, `planning_depth`, lane,
-`execution_tier`, typed topology, separate receipts, and feature closeout
-contract. Do not migrate that machine authority or storage shape while syncing
-an unrelated process-first packet.

package/src/claude/rules/workflow.md

@@ -6,16 +6,16 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 
 - Read `./README.md` before feature planning or coding.
 - Read the active spec/task file when one exists.
-- Read and activate any CafeKit skill that likely applies before taking action.
+- Use a CafeKit skill when its description matches the request; how to choose is in `skill-workflow-routing.md`.
 - Inspect only the code needed to understand the affected area.
-- Use `inspect` or focused search when structure is unclear.
+- Use `cf:scout` or focused search when structure is unclear.
 
 ## 2. Plan
 
 - For non-trivial features, use `/cf:specs` to challenge the minimum scope,
-  open C1, and create `specs/<feature>/plan.md` with flat
+  open GATE-SCOPE, and create `specs/<feature>/plan.md` with flat
   `task-NN-*.md` files beside it.
-- After adversarial review, open C2 and apply only the findings the user accepts
+- After adversarial review, open GATE-REVIEW and apply only the findings the user accepts
   or revises. Specs never starts implementation.
 - Start implementation only after a new explicit `/cf:develop` invocation,
   then select one unblocked task at a time.
@@ -24,16 +24,18 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
   - `Outcome`
   - `Scope`
   - `Ownership`
+  - `Steps`
   - `Acceptance`
   - `Dependencies`
   - `Verification Plan`
+  - `Failure Protocol`
 - If these are missing or too vague to verify, route back to spec correction.
 
 ## 3. Execute
 
 - Implement only the active scope.
 - Modify existing files directly; do not create duplicate "enhanced" variants.
-- Keep named contracts from `design.md` intact.
+- Keep named contracts from the plan and task intact.
 - Do not use placeholder wiring, process-local stand-ins, or fake adapters as completion proof.
 
 ## 4. Verify
@@ -53,16 +55,15 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
   sole writer of task Status and proof.
 - Keep exactly one `Status:` field. Write or replace the task's final inline
   `## Receipt` before setting `Status: done`.
-- A canonical Receipt contains the exact command, `Exit: 0`,
-  `Verification: PASS`, runtime-derived Base and Head values, and non-empty
-  fenced current output. Never invent, copy, or infer missing proof.
+- The canonical Receipt is defined in `state-sync.md`. Never invent, copy, or
+  infer missing proof.
 - When the binding to Base and Head applies, and what the gate does and does not
   detect, are stated once in `state-sync.md`.
 - Re-read each edited task and reconcile its plan row, dependencies, acceptance
   mapping, status, and receipt without rewriting unrelated bytes.
-- Run docs checkpoint when a completed task affects public docs or architecture docs.
+- Update affected existing docs when a completed task changes public or architecture docs.
 - After all requested work has current proof, show evidence and limitations at
-  C3. The user decides whether the feature is complete.
+  GATE-DONE. The user decides whether the feature is complete.
 
 ## Production Or CI Issues
 
@@ -73,12 +74,3 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 5. Review before syncing or shipping.
 
 Do not patch symptoms before diagnosis unless the issue is a trivial syntax/type/lint failure with an obvious local cause.
-
-## Legacy compatibility
-
-When an existing feature contains `spec.json`, nested `tasks/task-R*.md`, or
-other legacy kernel artifacts, keep using the installed adapter. Preserve its
-`task_registry`, `semantic_model`, `planning_depth`, lane,
-`execution_tier`, typed boundaries, separate receipts, and final feature
-receipt. Do not project that machine authority or storage shape into a new
-process-first packet.

package/src/claude/runtime.schema.json

@@ -58,7 +58,8 @@
         "scaffold_guard": {
           "type": "boolean",
           "default": true,
-          "description": "Require task files to be generated by the scaffold script. Set false to write them by hand."
+          "deprecated": true,
+          "description": "Not honoured. The task-scaffold guard that read this key was removed; the key is kept so existing runtime.json files stay valid."
         },
         "tollgate": {
           "type": "boolean",
@@ -75,12 +76,13 @@
     "usage": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Usage and quota reporting.",
+      "deprecated": true,
+      "description": "Not honoured. The usage hook that read this key was removed; the statusline takes quota from the rate_limits Claude Code sends. Kept so existing runtime.json files stay valid.",
       "properties": {
         "enabled": {
           "type": "boolean",
           "default": true,
-          "description": "Set false to stop fetching quota data for the statusline."
+          "description": "Not honoured. Nothing fetches quota data any more."
         }
       }
     },

package/src/claude/scripts/generate-skill-catalog.cjs

@@ -15,12 +15,13 @@ const RETIRED_DIRECTORIES = new Set([
   'mobile-development',
   'devops',
   'react-best-practices',
+  'inspect',
+  'hotfix',
+  'question',
+  'loop',
+  'route',
+  'delegate',
 ]);
-const PUBLIC_SUFFIX_BY_DIRECTORY = {
-  hotfix: 'fix',
-  inspect: 'scout',
-  question: 'ask',
-};
 
 function usage() {
   console.log(`Usage:
@@ -124,7 +125,7 @@ function publicIdentity(name) {
 }
 
 function expectedIdentity(directory) {
-  return `cf:${PUBLIC_SUFFIX_BY_DIRECTORY[directory] || directory}`;
+  return `cf:${directory}`;
 }
 
 function diagnostic(code, directory, message) {

package/src/claude/scripts/provenance.cjs

@@ -228,13 +228,30 @@ function identity(input) {
   return { root, specsRoot, specFile, feature, session, mode };
 }
 
+// A Stop hook checks every done receipt against one checkout. Without a memo each
+// receipt re-read the whole repository twice, so the gate grew with the number of
+// done tasks (minutes on a large specs root). The memo is opt-in and lives only in
+// the enabling process; every other caller still captures a fresh snapshot.
+const snapshotMemo = new Map();
+let snapshotMemoEnabled = false;
+function enableSnapshotMemo() { snapshotMemoEnabled = true; }
+
+function captureSnapshot(root, specsRoot) {
+  const key = `${root}\0${specsRoot}`;
+  if (snapshotMemoEnabled && snapshotMemo.has(key)) return snapshotMemo.get(key);
+  const base = gitBase(root, specsRoot);
+  const first = manifest(root, specsRoot);
+  const head = manifestDigest(first);
+  const second = manifest(root, specsRoot);
+  if (JSON.stringify(first) !== JSON.stringify(second) || gitBase(root, specsRoot) !== base) fail('worktree_race', 'checkout changed during provenance capture');
+  const snapshot = { base, head };
+  if (snapshotMemoEnabled) snapshotMemo.set(key, snapshot);
+  return snapshot;
+}
+
 function deriveRuntimeProvenance(input) {
   const current = identity(input);
-  const base = gitBase(current.root, current.specsRoot);
-  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, current.specsRoot) !== base) fail('worktree_race', 'checkout changed during provenance capture');
+  const { base, head } = captureSnapshot(current.root, current.specsRoot);
   const stable = {
     schema_version: CONTEXT_SCHEMA_VERSION,
     project_root: current.root,
@@ -328,6 +345,7 @@ module.exports = {
   createReceiptBinding,
   deriveRuntimeContext: deriveRuntimeProvenance,
   deriveRuntimeProvenance,
+  enableSnapshotMemo,
   isTrustedRuntimeContext,
   recomputeRuntimeContext: recomputeRuntimeProvenance,
   recomputeRuntimeProvenance,

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

@@ -6,12 +6,6 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { annotatedMarkdownLines } = require('./spec-resolver.cjs');
 
-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));
@@ -40,34 +34,6 @@ function safeRead(root, relativePath) {
   }
 }
 
-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 workflowReceiptBody(text, policy = {}) {
   const lines = annotatedMarkdownLines(text);
   const starts = [];
@@ -149,11 +115,18 @@ function workflowVerificationCommand(taskText) {
     if (current) current.push(line);
   }
   if (sections.length !== 1) return null;
-  const commands = sections[0]
-    .map((line) => line.match(/^\s*-\s+(?:\*\*Command\*\*|Command)\s*:\s*(.*?)\s*$/i))
-    .filter(Boolean)
+  // Only a top-level `- Command:` counts: an indented one belongs to another field such as a
+  // Counterexample, and one under a `###` sub-heading is a side step that must not outrank
+  // the main block. When commands exist only under sub-headings, they are used as before.
+  const commandOf = (line) => line.match(/^-\s+(?:\*\*Command\*\*|Command)\s*:\s*(.*?)\s*$/i);
+  const firstSub = sections[0].findIndex((line) => /^###\s+/.test(line));
+  const main = (firstSub === -1 ? sections[0] : sections[0].slice(0, firstSub)).map(commandOf).filter(Boolean);
+  const commands = (main.length ? main : sections[0].map(commandOf).filter(Boolean))
     .map((match) => normalizedCommand(match[1]));
-  return commands.length === 1 ? commands[0] : null;
+  // A plan may declare several commands when its proof takes more than one step. The last
+  // is canonical: earlier ones are prerequisites, and binding the Receipt to any of them
+  // would let a task close on its cheapest step. None declared still fails closed.
+  return commands.length >= 1 ? commands[commands.length - 1] : null;
 }
 
 function workflowCommandFailures(taskText, body) {
@@ -167,20 +140,6 @@ function workflowCommandFailures(taskText, body) {
     : ['command_identity'];
 }
 
-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 tryGitBytes(root, args) {
   const result = spawnSync('git', ['-C', root, ...args], { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
   if (result.error || result.status !== 0) return null;
@@ -240,57 +199,6 @@ function canonicalFailures(body, task, runtimeContext, policy, { bindProvenance
   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 checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, policy) {
   const safeTaskPath = typeof taskPath === 'string' && /^task-[A-Za-z0-9][A-Za-z0-9._-]*\.md$/.test(taskPath);
   if (!safeTaskPath) return { status: 'unsafe', taskPath, failures: ['unsafe_path'] };
@@ -354,12 +262,22 @@ const RECEIPT_FIX_HINTS = Object.freeze([
 ]);
 
 /**
- * Turn receipt check codes into one instruction naming what to change.
+ * Turn receipt check codes into one instruction naming what to change. When the receipt
+ * body is available, a provenance failure is refined: telling someone to add lines they
+ * already wrote sends them looking in the wrong place, and the common cause is a pair
+ * typed by hand — git short SHAs — rather than the pair this runtime derives.
  */
-function receiptFixHint(failures) {
+function receiptFixHint(failures, body) {
   const codes = new Set(Array.isArray(failures) ? failures : []);
   const hints = RECEIPT_FIX_HINTS.filter(([code]) => codes.has(code)).map(([, hint]) => hint);
   if (hints.length === 0) return null;
+  if (codes.has('provenance') && typeof body === 'string'
+    && fieldValues(body, 'Base').length > 0 && fieldValues(body, 'Head').length > 0) {
+    const index = hints.length - 1;
+    hints[index] = 'the `Base:` and `Head:` lines are present but are not the pair this runtime derives'
+      + ' — re-derive them (`Base` is a 40-character commit id, `Head` a 64-character tree digest);'
+      + ' git short SHAs typed by hand never match';
+  }
   return hints.length === 1 ? hints[0] : `${hints.slice(0, -1).join('; ')}; and ${hints[hints.length - 1]}`;
 }
 
@@ -409,32 +327,17 @@ function checkWorkflowReceiptSet(candidates, projectRoot, runtimeSession, policy
     for (const taskPath of doneTasks) {
       const proof = checkWorkflowTaskReceipt(candidate.featureDir, taskPath, runtimeContext, policy);
       if (proof.failures.length > 0) {
-        failures.push({ featureName: candidate.featureName, taskPath, failures: proof.failures });
+        failures.push({ featureName: candidate.featureName, taskPath, failures: proof.failures, body: proof.body });
       }
     }
   }
   return { 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,
   checkWorkflowReceiptSet,
   checkWorkflowTaskReceipt,
   receiptFixHint,
-  evidenceBody,
-  readTaskProof,
   safeRead,
   workflowDependencyProofState,
   workflowReceiptBody,