@haposoft/cafekit 0.16.7 → 0.18.0

package/src/claude/rules/workflow.md

@@ -8,14 +8,14 @@ Use the CafeKit loop: **Understand -> Plan -> Execute -> Verify -> Sync**.
 - Read the active spec/task file when one exists.
 - Read and activate any CafeKit skill that likely applies before taking action.
 - 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

@@ -149,11 +149,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) {
@@ -354,12 +361,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,7 +426,7 @@ 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 });
       }
     }
   }

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

@@ -860,8 +860,7 @@ function explicitWorkflowFeatureName({ projectRoot, specsDir, explicitFeature, e
 
 /**
  * Resolve the authoring/execution workflow visible to prompt and Stop hooks.
- * Persisted spec resolution remains unchanged; process-v3 is an additive adapter
- * and never becomes completion-authority input by way of findAllSpecCandidates.
+ * Persisted spec resolution remains unchanged; process-v3 is an additive adapter.
  */
 function resolveWorkflowCandidate({ projectRoot, runtime, explicitFeature, explicitPath, target, includeCompleted = false } = {}) {
   if (!projectRoot) throw new TypeError('projectRoot required');

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

@@ -724,11 +724,9 @@ function taskDeclaresParallel(content, taskPath, errors) {
 }
 
 /**
- * Task files are created from the scaffold template (the scaffold-guard hook
- * forces creation through it), so every task starts as a stub full of `{{...}}`
- * placeholders. The hook guarantees the stub is CREATED via scaffold, but
- * nothing guaranteed the model FILLED it. An unfilled `{{...}}` is an
- * incomplete task — SKILL.md: "Leave NO {{...}} placeholder ... fails DoCT" —
+ * Task files are usually created from the scaffold template, so a task can start as
+ * a stub full of `{{...}}` placeholders, and nothing guarantees the model FILLED it.
+ * An unfilled `{{...}}` is an incomplete task — SKILL.md: "Leave NO {{...}} placeholder ... fails DoCT" —
  * so it is a hard error here. A `.../` path fragment is a not-yet-resolved path
  * placeholder; it is only a warning, because it usually survives in prose Steps
  * while the Related Files table (which spec-ground.cjs does verify) is already
@@ -2471,23 +2469,7 @@ function validateSemanticReview(specDir, spec, context, subCriteriaIds, designTe
       errors.push('spec.json.validation.semantic_review.reviewed_artifact_digest: stale or does not match final artifacts and canonical state');
     }
   }
-  if (context.policy?.assurance_level === 'Strict' && SHA256_RE.test(review.reviewed_artifact_digest || '')) {
-    try {
-      const authority = require('../hooks/semantic-review-authority.cjs');
-      const canonicalSpecDir = fs.realpathSync(specDir);
-      let root = fs.realpathSync(process.cwd());
-      if (!isPathInside(root, canonicalSpecDir)) root = path.dirname(path.dirname(canonicalSpecDir));
-      const attestation = authority.verifyAttestation(
-        root,
-        path.join(canonicalSpecDir, 'spec.json'),
-        spec.feature_name,
-        review.reviewed_artifact_digest,
-      );
-      if (!attestation.ok) errors.push(`spec.json.validation.semantic_review: Strict assurance requires matching host-observed reviewer PASS attestation (${attestation.reason})`);
-    } catch (error) {
-      errors.push(`spec.json.validation.semantic_review: Strict assurance attestation is unavailable (${error.message})`);
-    }
-  }
+  if (context.policy?.assurance_level === 'Strict') errors.push('spec.json.validation.semantic_review: Strict assurance is no longer supported (its reviewer attestation hook was removed); move the packet to plan.md with flat task files');
 
   const criteria = Array.isArray(review.reviewed_criteria) ? review.reviewed_criteria : [];
   const criterionSet = new Set(criteria);
@@ -2901,16 +2883,7 @@ function validateSemanticReview21(specDir, spec, criteria, designIds, verificati
     }
   }
   for (const criterion of criteria) if (!covered.has(criterion)) errors.push(`semantic review counterexamples missing criterion ${criterion}`);
-  if (spec.workflow_policy?.assurance_level === 'Strict' && SHA256_RE.test(review.semantic_digest || '')) {
-    try {
-      const authority = require('../hooks/semantic-review-authority.cjs');
-      const root = canonicalProjectRoot(specDir);
-      const attestation = authority.verifyAttestation(root, path.join(specDir, 'spec.json'), spec.feature_name, review.semantic_digest);
-      if (!attestation.ok) errors.push(`spec.json.validation.semantic_review: Strict readiness requires matching allowlisted host-observed reviewer PASS attestation (${attestation.reason})`);
-    } catch (error) {
-      errors.push(`spec.json.validation.semantic_review: Strict readiness attestation is unavailable (${error.message})`);
-    }
-  }
+  if (spec.workflow_policy?.assurance_level === 'Strict') errors.push('spec.json.validation.semantic_review: Strict assurance is no longer supported (its reviewer attestation hook was removed); move the packet to plan.md with flat task files');
 }
 
 function computeLineageId(featureName, createdAt) {

package/src/claude/settings/settings.json

@@ -14,10 +14,6 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session.cjs\""
           },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""
@@ -58,18 +54,9 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/rules.cjs\""
           },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-authority.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-state.cjs\""
-          },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/usage.cjs\"",
-            "timeout": 30
           }
         ]
       }
@@ -87,15 +74,6 @@
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/inspect-block.cjs\""
           }
         ]
-      },
-      {
-        "matcher": "Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-scaffold-guard.cjs\""
-          }
-        ]
       }
     ],
     "PostToolUse": [
@@ -113,8 +91,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/usage.cjs\"",
-            "timeout": 30
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-state.cjs\""
           }
         ]
       }
@@ -126,10 +103,6 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-gate.cjs\""
           },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-authority.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""
@@ -140,10 +113,6 @@
     "SubagentStop": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/semantic-review-authority.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""

package/src/claude/skills/{question → ask}/SKILL.md

@@ -24,6 +24,7 @@ metadata:
 
 <ANSWER-ONLY-GATE>
 Do NOT implement, scaffold, refactor, modify files, generate full specs, or make final architecture decisions.
+This holds even when the question itself asks for a change ("and fix it", "rồi đổi luôn cho tôi"): answer the cause with evidence, edit nothing, and point to `cf:fix` for the change, or to `cf:debug` when the cause is not yet known.
 The output is an answer, evidence, confidence, and a follow-up only when needed.
 </ANSWER-ONLY-GATE>
 
@@ -43,10 +44,7 @@ Do not use it when:
 - The user asks to implement, fix, debug, test, commit, or publish.
 - The user wants ideation/tradeoff exploration; use `cf:brainstorm`.
 - The user wants a formal spec; use `cf:specs`.
-- The user wants full legacy documentation reconstruction: use
-  `cf:docs --reconstruct` when the optional document bundle is installed;
-  otherwise use `cf:scout` plus source evidence, or explain how to install the
-  bundle with `npx @haposoft/cafekit --with-document-skills`.
+- The user wants full legacy documentation reconstruction: use `cf:docs --reconstruct` when the optional document bundle is installed; otherwise use `cf:scout` plus source evidence, or explain how to install the bundle with `npx @haposoft/cafekit --with-document-skills`.
 - The user wants root-cause diagnosis for a failure; use `cf:debug`.
 
 ## Modes
@@ -60,50 +58,19 @@ Do not use it when:
 
 If modes conflict, prefer the most explicit source mode in this order: `--both`, `--repo`, `--web`, then default. Apply `--brief` or `--deep` as output depth modifiers.
 
-## Workflow
+## Standards
 
-### 1. Classify The Question
+**Unclear questions.** If `unclear`, ask one focused follow-up with the minimum choices needed.
 
-Pick one primary answer type:
+**Repo evidence priority:** `README.md`, `AGENTS.md`, `CLAUDE.md`; then relevant `docs/`, `specs/`, `.claude/`; then source files, tests, scripts, package manifests, config files; git history only when the question asks about changes or provenance. Use focused search (`rg`, targeted file reads) instead of broad scans. Use `cf:scout` when the user asks where something lives or the source surface is unclear.
 
-```text
-source-code behavior | config/version | spec/docs consistency | dependency/library | workflow/process | external/current knowledge | unclear
-```
-
-If `unclear`, ask one focused follow-up with the minimum choices needed.
-
-### 2. Gather Evidence
-
-Repo evidence priority:
-1. `README.md`, `AGENTS.md`, `CLAUDE.md`
-2. relevant `docs/`, `specs/`, `.claude/`
-3. source files, tests, scripts, package manifests, config files
-4. git history only when the question asks about changes or provenance
-
-Use focused search (`rg`, targeted file reads) instead of broad scans. Use `cf:scout` when the user asks where something lives or the source surface is unclear.
-
-External evidence:
-- Use external/current docs when repo evidence is absent, stale, or not authoritative.
-- Prefer official docs, standards, source repositories, or primary vendor docs.
-- State clearly when an answer is inferred from external docs rather than confirmed in the repo.
+**External evidence.** Use external/current docs when repo evidence is absent, stale, or not authoritative. Prefer official docs, standards, source repositories, or primary vendor docs. State clearly when an answer is inferred from external docs rather than confirmed in the repo.
 
-### 3. Decide Whether To Answer Or Ask Back
+**Broad questions.** When the question names no aspect or target — "Is this system stable?", "Is the code good?" — ask back before gathering evidence, offering 2-3 aspects (for example code and tests, runtime reliability, deploy readiness), even when a cautious answer would be possible.
 
-Answer directly when at least one of these is true:
-- repo evidence answers the question,
-- external/current evidence answers the non-project part,
-- a cautious answer can separate known facts from inference.
+**Answer or ask back.** Answer directly when at least one of these is true: repo evidence answers the question, external/current evidence answers the non-project part, or a cautious answer can separate known facts from inference. Ask back when the target system/module is not named and multiple targets are plausible, the needed file/source is blocked or private, the question requires business/domain judgment not present in source, the answer would require guessing customer intent, or the question bundles multiple unrelated topics. Ask only one follow-up question. Include 2-3 concrete options if helpful.
 
-Ask back when:
-- the target system/module is not named and multiple targets are plausible,
-- the needed file/source is blocked or private,
-- the question requires business/domain judgment not present in source,
-- the answer would require guessing customer intent,
-- the question bundles multiple unrelated topics.
-
-Ask only one follow-up question. Include 2-3 concrete options if helpful.
-
-### 4. Output Contract
+## Output Contract
 
 Default output:
 
@@ -135,36 +102,3 @@ Use `templates/question.md` when the user asks to save or document the answer.
 - Keep the answer proportional: concise for simple questions, structured for complex ones.
 - If external sources were used, include source links or names.
 - If no evidence exists, say "no evidence found in the current source" and explain what was checked.
-
-## Examples
-
-### Source Question
-
-```text
-/cf:ask "In this system, which file does cafekit use to toggle skill routing?"
-```
-
-Expected behavior:
-- read runtime/config/install files,
-- answer with exact config file and relevant keys,
-- say whether it is runtime-driven or hard-coded.
-
-### Mixed Source + Web Question
-
-```text
-/cf:ask "Which React version does this project use, and does that version still match current best practice?" --both
-```
-
-Expected behavior:
-- read `package.json` or lockfile,
-- check current React docs/release info if needed,
-- separate local version from external recommendation.
-
-### Ask Back
-
-```text
-/cf:ask "Is this system stable?"
-```
-
-Expected behavior:
-- ask one narrowing question because "stable" could mean architecture, security, performance, UX, tests, or deploy readiness.