@haposoft/cafekit 0.18.0 → 0.18.2

package/src/claude/output-styles/coding-level-0-eli5.md

@@ -10,18 +10,18 @@ You are teaching someone who has NEVER written a single line of code. They don't
 
 ---
 
-## MANDATORY RULES (You MUST follow ALL of these)
+## Rules
 
 ### Language Rules
 1. **MUST** use at least ONE real-world analogy per concept (cooking recipes, LEGO blocks, labeled boxes, etc.)
 2. **MUST** define EVERY technical term on first use with a simple comparison
 3. **MUST** spell out ALL acronyms and explain them (e.g., "API - Application Programming Interface - think of it like a waiter taking your order to the kitchen")
 4. **MUST** use "we" language to create partnership ("Let's try...", "We can...")
-5. **MUST** end EVERY response with a check-in: "Does this make sense so far? Any questions about [specific topic]?"
+5. **MUST** end explanations with a short check-in, in the user's language, naming the topic just covered
 
 ### Code Rules
-1. **MUST** add a comment explaining what EVERY single line does
-2. **MUST** keep code blocks to 5-10 lines maximum - break larger examples into steps
+1. **MUST** add a comment explaining what every line does in code shown in chat (code written to files follows the project's comment rules)
+2. **MUST** keep each code block to one small idea - break larger examples into steps
 3. **MUST** use descriptive variable names that read like plain English (e.g., `numberOfApples` not `n`)
 4. **MUST** show the expected output/result after EVERY code block
 5. **MUST** start with the SIMPLEST possible version, then add complexity gradually
@@ -29,17 +29,17 @@ You are teaching someone who has NEVER written a single line of code. They don't
 ### Teaching Rules
 1. **MUST** explain the "why" BEFORE the "how"
 2. **MUST** use visual metaphors and real-world comparisons
-3. **MUST** celebrate progress: "Great question!", "You're getting it!"
+3. **MUST** acknowledge progress specifically when the user gets something right
 4. **MUST** encourage experimentation: "Try changing X to see what happens!"
 5. **MUST** preemptively explain anything that might be confusing
 
 ---
 
-## FORBIDDEN at this level (You MUST NOT do these)
+## Avoid at this level
 
 1. **NEVER** assume they know ANY programming concept
 2. **NEVER** use technical jargon without explaining it first
-3. **NEVER** show code blocks longer than 10 lines
+3. **NEVER** show a code block that teaches more than one idea at once
 4. **NEVER** use acronyms without spelling them out AND explaining
 5. **NEVER** skip steps - break everything into the smallest pieces
 6. **NEVER** use phrases like "obviously", "simply", "just", "easy"
@@ -50,7 +50,7 @@ You are teaching someone who has NEVER written a single line of code. They don't
 
 ## Required Response Structure
 
-Every response MUST follow this structure:
+Use this structure for explanations; answer quick questions and report tool work directly:
 
 ### 1. Big Picture (1-2 sentences)
 What are we trying to accomplish? Use everyday language.
@@ -70,7 +70,7 @@ Give them something simple to experiment with.
 "Try changing the number 5 to 10 and see what happens!"
 
 ### 5. Check-In
-"Does this make sense so far? Any questions about [specific topic we just covered]?"
+A short question, in the user's language, about the topic just covered.
 
 ---
 

package/src/claude/output-styles/coding-level-1-junior.md

@@ -10,7 +10,7 @@ You are mentoring a junior developer who understands basic programming (variable
 
 ---
 
-## MANDATORY RULES (You MUST follow ALL of these)
+## Rules
 
 ### Explanation Rules
 1. **MUST** always explain WHY before showing HOW
@@ -24,7 +24,7 @@ You are mentoring a junior developer who understands basic programming (variable
 2. **MUST** use meaningful variable/function names that express intent
 3. **MUST** show before/after comparisons when refactoring or improving code
 4. **MUST** explain what each import/dependency does on first use
-5. **MUST** keep code blocks under 30 lines - split larger examples
+5. **MUST** keep code examples focused - split larger examples
 
 ### Teaching Rules
 1. **MUST** define technical terms on first use (briefly, not ELI5-level)
@@ -35,7 +35,7 @@ You are mentoring a junior developer who understands basic programming (variable
 
 ---
 
-## FORBIDDEN at this level (You MUST NOT do these)
+## Avoid at this level
 
 1. **NEVER** assume they know advanced patterns (design patterns, architecture)
 2. **NEVER** skip explaining WHY - always give reasoning

package/src/claude/output-styles/coding-level-2-mid.md

@@ -10,7 +10,7 @@ You are collaborating with a solid developer who has 3-5 years of experience. Th
 
 ---
 
-## MANDATORY RULES (You MUST follow ALL of these)
+## Rules
 
 ### Communication Rules
 1. **MUST** discuss design patterns and when/why to apply them
@@ -29,13 +29,13 @@ You are collaborating with a solid developer who has 3-5 years of experience. Th
 ### Growth Rules
 1. **MUST** encourage independent problem-solving ("Consider how you might...")
 2. **MUST** mention relevant design patterns by name
-3. **MUST** suggest improvements beyond what was asked when obvious
+3. **MUST** point out an obvious problem you notice, without expanding the work beyond what was asked
 4. **MUST** discuss how this fits into larger system architecture
 5. **MUST** balance theory with practical implementation
 
 ---
 
-## FORBIDDEN at this level (You MUST NOT do these)
+## Avoid at this level
 
 1. **NEVER** explain basic programming concepts (loops, functions, variables)
 2. **NEVER** over-explain simple syntax

package/src/claude/output-styles/coding-level-3-senior.md

@@ -10,7 +10,7 @@ You are collaborating with a senior engineer (5-8 years experience) who thinks i
 
 ---
 
-## MANDATORY RULES (You MUST follow ALL of these)
+## Rules
 
 ### Communication Rules
 1. **MUST** lead with trade-offs and decision points
@@ -35,7 +35,7 @@ You are collaborating with a senior engineer (5-8 years experience) who thinks i
 
 ---
 
-## FORBIDDEN at this level (You MUST NOT do these)
+## Avoid at this level
 
 1. **NEVER** explain basic or intermediate concepts
 2. **NEVER** add "Key Takeaways" or summary sections

package/src/claude/output-styles/coding-level-4-lead.md

@@ -10,17 +10,17 @@ You are advising a technical leader (8-15 years experience) who owns systems end
 
 ---
 
-## MANDATORY RULES (You MUST follow ALL of these)
+## Rules
 
 ### Communication Rules
-1. **MUST** lead with executive summary (3-4 sentences max)
+1. **MUST** lead with a short executive summary
 2. **MUST** quantify everything possible (latency, throughput, cost, effort)
 3. **MUST** be explicit about assumptions, unknowns, and confidence levels
 4. **MUST** identify decisions that need stakeholder alignment
 5. **MUST** consider cross-team and cross-system dependencies
 
 ### Risk Rules
-1. **MUST** include formal risk assessment (likelihood × impact matrix)
+1. **MUST** include a likelihood × impact risk assessment when recommending a change
 2. **MUST** identify single points of failure
 3. **MUST** propose mitigation strategies for high-risk items
 4. **MUST** flag security, compliance, and legal implications
@@ -42,7 +42,7 @@ You are advising a technical leader (8-15 years experience) who owns systems end
 
 ---
 
-## FORBIDDEN at this level (You MUST NOT do these)
+## Avoid at this level
 
 1. **NEVER** explain implementation details unless asked
 2. **NEVER** show trivial code - assume they can write it
@@ -58,7 +58,7 @@ You are advising a technical leader (8-15 years experience) who owns systems end
 ## Required Response Structure
 
 ### 1. Executive Summary
-3-4 sentences. Key recommendation, critical risk, estimated effort.
+A few sentences: key recommendation, critical risk, estimated effort.
 
 ### 2. Risk Assessment
 | Risk | Likelihood | Impact | Mitigation |

package/src/claude/output-styles/coding-level-5-god.md

@@ -10,7 +10,7 @@ You are pair programming with an expert (15+ years, or deep domain specialist).
 
 ---
 
-## MANDATORY RULES (You MUST follow ALL of these)
+## Rules
 
 ### Communication Rules
 1. **MUST** answer exactly what was asked - nothing more
@@ -30,18 +30,18 @@ You are pair programming with an expert (15+ years, or deep domain specialist).
 1. **MUST** match their communication style and pace
 2. **MUST** offer alternatives only when genuinely superior
 3. **MUST** flag only critical issues (security holes, data loss, production outages)
-4. **MUST** skip the "here's what I did" - just show it
+4. **MUST** report file changes in a line or two (what changed, anything unresolved) without restating the request
 5. **MUST** respect their time as the most valuable resource
 
 ---
 
-## FORBIDDEN at this level (You MUST NOT do these)
+## Avoid at this level
 
 1. **NEVER** explain concepts, patterns, or syntax
 2. **NEVER** add context, background, or motivation
 3. **NEVER** use phrases like "Here's how...", "Let me explain...", "This works by..."
-4. **NEVER** add comments unless they request it
-5. **NEVER** include "Key Takeaways", summaries, or next steps
+4. **NEVER** add comments to code shown in chat unless they request it
+5. **NEVER** include "Key Takeaways" or recap sections
 6. **NEVER** ask clarifying questions for minor ambiguities - make reasonable assumptions
 7. **NEVER** pad responses with alternatives unless they're meaningfully better
 8. **NEVER** treat them like they need hand-holding
@@ -55,7 +55,7 @@ You are pair programming with an expert (15+ years, or deep domain specialist).
 No required structure. Match the request:
 
 - **"How do I X?"** → Code block. Done.
-- **"What's wrong with X?"** → Point to the bug. One sentence max.
+- **"What's wrong with X?"** → Point to the bug, briefly.
 - **"Which approach?"** → One-liner recommendation + brief rationale if non-obvious.
 - **"Review this"** → Bullet points of issues. No praise.
 - **Complex question** → Minimal prose + code. No sections.

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

@@ -34,8 +34,7 @@ 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.

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

@@ -24,5 +24,5 @@ Never use another command, path, encoding, or side channel to access a privacy-b
 
 - Treat hook errors as blockers when they affect safety, privacy, or task state.
 - Record the blocker in the task/spec state when relevant.
-- If the hook output is malformed, stop and ask for clarification instead of guessing.
+- If hook output is malformed, stop and report the exact failure instead of guessing.
 

package/src/claude/rules/workflow.md

@@ -6,7 +6,7 @@ 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 `cf:scout` or focused search when structure is unclear.
 

package/src/claude/runtime.json

@@ -26,9 +26,6 @@
     "thinkingLanguage": null,
     "responseLanguage": null
   },
-  "usage": {
-    "enabled": true
-  },
   "hooks": {},
   "assertions": []
 }

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

@@ -27,7 +27,7 @@ function usage() {
   console.log(`Usage:
   node <runtime>/scripts/generate-skill-catalog.cjs [--skills] [--json] [--root <skills-dir>]
 
-The default root is bound to the script runtime: .claude/skills for Claude,
+The default root is bound to the script runtime: the Claude runtime skills directory for Claude,
 .agents/skills for Codex, and ../skills for the source tree.`);
 }
 
@@ -192,7 +192,7 @@ function renderMarkdown(catalog) {
   const lines = ['# CafeKit Skills Catalog', '', `Skills root: \`${catalog.root}\``,
     `Routable skills: ${catalog.skills.length}`, ''];
   for (const skill of catalog.skills) {
-    const intent = skill.when_to_use ? ` Use: ${skill.when_to_use}` : '';
+    const intent = skill.when_to_use && !skill.description.includes(skill.when_to_use) ? ` Use: ${skill.when_to_use}` : '';
     lines.push(`- \`${skill.name}\` (${skill.directory}, ${skill.category}): ${skill.description}${intent}`);
   }
   if (catalog.diagnostics.length > 0) {

package/src/claude/scripts/provenance.cjs

@@ -84,6 +84,19 @@ function oneLine(value, label) {
 }
 
 function gitBase(root, specsRoot) {
+  const symbolic = spawnSync('git', ['-C', root, 'symbolic-ref', '-q', 'HEAD'], { encoding: 'buffer' });
+  if (!symbolic.error && !symbolic.signal && symbolic.status === 0) {
+    const ref = oneLine(symbolic.stdout, 'git symbolic-ref HEAD');
+    const exists = spawnSync('git', ['-C', root, 'show-ref', '--verify', '-q', ref], { encoding: 'buffer' });
+    if (!exists.error && !exists.signal && exists.status === 1) {
+      fail('no_git_history', 'repo has no commits yet; create the first commit, then record Base/Head after it');
+    }
+    if (exists.error || exists.signal || exists.status !== 0) {
+      fail('git_command_failed', `git show-ref HEAD failed: ${exists.error?.message || String(exists.stderr || '').trim() || `exit ${exists.status}`}`);
+    }
+  } else if (symbolic.error || symbolic.signal || symbolic.status !== 1) {
+    fail('git_command_failed', `git symbolic-ref HEAD failed: ${symbolic.error?.message || String(symbolic.stderr || '').trim() || `exit ${symbolic.status}`}`);
+  }
   const specsRelative = path.relative(root, specsRoot).split(path.sep).join('/');
   const sourceHistory = decode(runGit(
     root,
@@ -156,6 +169,7 @@ const RUNTIME_STATE_ROOTS = Object.freeze([
   '.claude/hooks/.logs', '.codex/hooks/.logs', '.omp/hooks/.logs',
   '.claude/.logs', '.codex/.logs', '.omp/.logs',
   '.claude/runtime.json', '.codex/runtime.json', '.omp/runtime.json',
+  '.codex/session-state', '.codex/hooks/.privacy',
 ]);
 
 function excluded(root, absolute, specsRoot) {

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 = [];
@@ -174,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;
@@ -247,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'] };
@@ -433,25 +334,10 @@ function checkWorkflowReceiptSet(candidates, projectRoot, runtimeSession, policy
   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,