@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/src/claude/hooks/precompact.cjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * PreCompact Hook — precompact.cjs
+ * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * Compaction drops the transcript that told the session where it was. The
+ * existing SessionStart warning tells the operator something was lost but not
+ * what, so recovery starts from a blank slate and the session re-derives facts
+ * it already had. This hook writes down the machine-checkable anchors just
+ * before the drop: branch, HEAD, how dirty the tree is, and which task the
+ * packet says is in flight. `session.cjs` prints them back on the compact
+ * restart.
+ *
+ * Only facts the runtime can re-derive are recorded. Nothing here is proof of
+ * work and nothing here grants an authorization; a compacted session must still
+ * re-ask for a pending confirmation.
+ *
+ * Storage: the hook state directory (temp when run from source).
+ * Exit: 0 always (fail-open).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const RECOVERY_FILE = 'compact-recovery.json';
+
+function gitLine(root, args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+  if (result.error || result.status !== 0) return null;
+  const value = String(result.stdout || '').trim();
+  return value === '' ? null : value;
+}
+
+function projectRoot(payload) {
+  const configured = typeof process.env.CLAUDE_PROJECT_DIR === 'string' ? process.env.CLAUDE_PROJECT_DIR.trim() : '';
+  const candidates = [configured, typeof payload.cwd === 'string' ? payload.cwd.trim() : '', process.cwd()];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    try { return fs.realpathSync(path.resolve(candidate)); } catch { /* next */ }
+  }
+  return process.cwd();
+}
+
+/** The one task the packet currently says is in flight, if any. */
+function activeTask(root) {
+  try {
+    const RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
+    if (typeof RESOLVER.resolveWorkflowCandidate !== 'function') return null;
+    const resolved = RESOLVER.resolveWorkflowCandidate({ projectRoot: root, runtime: {}, target: null });
+    if (!resolved || resolved.error || resolved.layoutKind !== 'process-v3') return null;
+    const registry = resolved.taskRegistry || {};
+    const inProgress = Object.keys(registry).filter((taskPath) => registry[taskPath]?.status === 'in_progress');
+    return {
+      feature: resolved.featureName || null,
+      in_progress: inProgress,
+      counts: Object.values(registry).reduce((acc, task) => {
+        const status = task?.status || 'pending';
+        acc[status] = (acc[status] || 0) + 1;
+        return acc;
+      }, {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  const payload = stdin ? JSON.parse(stdin) : {};
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) process.exit(0);
+
+  const root = projectRoot(payload);
+  const status = gitLine(root, ['status', '--porcelain']);
+  const record = {
+    captured_at: new Date().toISOString(),
+    trigger: typeof payload.trigger === 'string' ? payload.trigger : null,
+    session_id: typeof payload.session_id === 'string' ? payload.session_id : null,
+    project_root: root,
+    branch: gitLine(root, ['rev-parse', '--abbrev-ref', 'HEAD']),
+    head: gitLine(root, ['rev-parse', '--short', 'HEAD']),
+    dirty_count: status === null ? null : status.split('\n').filter((line) => line.trim() !== '').length,
+    workflow: activeTask(root),
+  };
+
+  const dir = require('./lib/hook-state-dir.cjs').hookStateDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, RECOVERY_FILE);
+  const temp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`);
+  fs.renameSync(temp, target);
+  process.exit(0);
+} catch (error) {
+  try {
+    const dir = require('./lib/hook-state-dir.cjs').hookStateDir();
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(
+      path.join(dir, 'hook-log.jsonl'),
+      `${JSON.stringify({ ts: new Date().toISOString(), hook: 'precompact', status: 'crash', error: error.message })}\n`,
+    );
+  } catch (_) { /* fail-open */ }
+  process.exit(0);
+}

package/src/claude/hooks/rules.cjs

@@ -93,7 +93,7 @@ try {
 } catch (e) {
   try {
     const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
       JSON.stringify({ ts: new Date().toISOString(), hook: 'rules', status: 'crash', error: e.message }) + '\n');

package/src/claude/hooks/secret-output-guardrail.cjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * UserPromptSubmit Hook — secret-output-guardrail.cjs
+ * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * The privacy hook gates whether a sensitive file may be read. Nothing gated what
+ * happens after that approval, so an approved read could still put a raw key into
+ * the transcript — where it survives compaction, is written to disk, and is replayed
+ * to the model on every later turn. This injects a reminder when the prompt itself is
+ * about credential handling.
+ *
+ * It reads the prompt and never echoes it: no prompt text and no matched value is
+ * written out, so the guardrail cannot itself become the leak.
+ *
+ * Exit: 0 always (fail-open)
+ */
+
+try {
+  const fs = require('fs');
+  const { REMINDER, containsSecretKeyword } = require('./lib/secret-keywords.cjs');
+
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  if (!stdin) process.exit(0);
+
+  const payload = JSON.parse(stdin);
+  const prompt = String(payload.prompt || payload.user_prompt || '');
+  if (!containsSecretKeyword(prompt)) process.exit(0);
+
+  console.log(REMINDER);
+  process.exit(0);
+
+} catch (e) {
+  try {
+    const fs = require('fs'), p = require('path');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'secret-output-guardrail', status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0);
+}

package/src/claude/hooks/session.cjs

@@ -261,6 +261,32 @@ try {
     console.log('Any pending confirmations requested via AskUserQuestion might have been lost.');
     console.log('Do not proceed without explicitly asking the user again to ensure safety.');
     console.log('Use AskUserQuestion: "The chat context was compressed. Do I still have permission to proceed?"');
+
+    // Anchors captured by the PreCompact hook. These are re-derivable facts, not
+    // proof and not an authorization: they save the session from rebuilding its
+    // bearings, and nothing more.
+    try {
+      const fs2 = require('fs'), p2 = require('path');
+      const file = p2.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'compact-recovery.json');
+      const record = JSON.parse(fs2.readFileSync(file, 'utf8'));
+      const parts = [];
+      if (record.branch) parts.push(`branch ${record.branch}`);
+      if (record.head) parts.push(`HEAD ${record.head}`);
+      if (typeof record.dirty_count === 'number') parts.push(`${record.dirty_count} uncommitted path(s)`);
+      console.log('\n=== State before compaction ===');
+      if (record.captured_at) console.log(`Captured: ${record.captured_at}`);
+      if (parts.length) console.log(`Repository: ${parts.join(' | ')}`);
+      const workflow = record.workflow;
+      if (workflow && workflow.feature) {
+        const counts = Object.entries(workflow.counts || {}).map(([k, v]) => `${v} ${k}`).join(', ');
+        console.log(`Feature: ${workflow.feature}${counts ? ` (${counts})` : ''}`);
+        if (Array.isArray(workflow.in_progress) && workflow.in_progress.length > 0) {
+          console.log(`In flight: ${workflow.in_progress.join(', ')}`);
+        }
+      }
+      console.log('Re-read these from disk before acting; they describe the moment before compaction.');
+      console.log('=== End of pre-compaction state ===');
+    } catch (_) { /* no capture available */ }
   }
 
   process.exit(0);
@@ -269,7 +295,7 @@ try {
 } catch (e) {
   try {
     const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
       JSON.stringify({ ts: new Date().toISOString(), hook: 'session', status: 'crash', error: e.message }) + '\n');

package/src/claude/hooks/spec-gate.cjs

@@ -44,7 +44,7 @@ function projectRoot(payload = {}) {
 
 function logCrash(error) {
   try {
-    const d = path.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(
       path.join(d, 'hook-log.jsonl'),
@@ -202,7 +202,7 @@ try {
     process.exit(0);
   }
   const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
-  const cacheFile = path.join(__dirname, '.logs', 'spec-gate-last.json');
+  const cacheFile = path.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
   if (cacheExists) {
@@ -220,7 +220,7 @@ try {
   if (staleFlashTasks.length > 0) {
     process.stdout.write(JSON.stringify({
       decision: 'block',
-      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /hapo:test for exact proof, then use explicit sync-finalize.`
+      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /cf:test for exact proof, then use explicit sync-finalize.`
     }) + '\n');
     process.exit(0);
   }

package/src/claude/hooks/spec-state.cjs

@@ -16,7 +16,7 @@ const path = require('path');
 
 function logCrash(error) {
   try {
-    const d = path.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(
       path.join(d, 'hook-log.jsonl'),
@@ -182,7 +182,7 @@ try {
     total: taskEntries.length,
     featureReceiptPresent,
   });
-  const cacheFile = path.join(__dirname, '.logs', 'tollgate-last.txt');
+  const cacheFile = path.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'tollgate-last.txt');
 
   let lastKey = '';
   if (stateKey) {

package/src/claude/hooks/state.cjs

@@ -280,7 +280,7 @@ try {
   try {
     const fs = require('fs');
     const path = require('path');
-    const logDir = path.join(__dirname, '.logs');
+    const logDir = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
     fs.appendFileSync(
       path.join(logDir, 'hook-log.jsonl'),

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -84,7 +84,7 @@ try {
   // Never let a hook crash block the user — log and fail-open.
   try {
     const fs = require('fs'), p = require('path');
-    const d = p.join(__dirname, '.logs');
+    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
     fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
       JSON.stringify({ ts: new Date().toISOString(), hook: 'task-scaffold-guard', status: 'crash', error: e.message }) + '\n');

package/src/claude/hooks/usage.cjs

@@ -187,7 +187,7 @@ async function main() {
   try {
     const fs = require('fs');
     const p = require('path');
-    const logDir = p.join(__dirname, '.logs');
+    const logDir = require('./lib/hook-state-dir.cjs').hookStateDir();
     if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
     fs.appendFileSync(p.join(logDir, 'hook-log.jsonl'),
       JSON.stringify({ ts: new Date().toISOString(), hook: p.basename(__filename, '.cjs'), status: 'crash', error: e.message }) + '\n');

package/src/claude/migration-manifest.json

@@ -7,35 +7,35 @@
   "skills": {
     "required": [
       "agent-browser",
-      "ai-multimodal",
-      "backend-development",
       "brainstorm",
       "chrome-devtools",
       "code-review",
       "debug",
       "delegate",
       "develop",
-      "devops",
-      "docs",
-      "docx",
-      "frontend-design",
-      "frontend-development",
       "git",
       "hotfix",
       "inspect",
-      "mobile-development",
-      "pdf",
-      "pptx",
+      "loop",
       "question",
-      "react-best-practices",
       "research",
+      "route",
       "specs",
       "sync",
       "test",
       "ui-ux-pro-max",
-      "web-testing",
-      "xlsx"
-    ]
+      "web-testing"
+    ],
+    "bundles": {
+      "documentSkills": [
+        "ai-multimodal",
+        "docs",
+        "docx",
+        "pdf",
+        "pptx",
+        "xlsx"
+      ]
+    }
   },
   "agents": {
     "required": [
@@ -51,7 +51,8 @@
       "researcher.md",
       "spec-maker.md",
       "ui-ux-designer.md",
-      "deployer.md"
+      "deployer.md",
+      "strategist.md"
     ]
   },
   "scripts": {
@@ -78,6 +79,14 @@
     "assumed": []
   },
   "obsolete": {
+    "skills": [
+      "backend-development",
+      "frontend-development",
+      "frontend-design",
+      "mobile-development",
+      "devops",
+      "react-best-practices"
+    ],
     "agents": {
       "claude": ["agents/god-developer.md"],
       "codex": ["agents/god_developer.toml"]
@@ -112,12 +121,15 @@
     "files": [
       "gitignore",
       "runtime.json",
+      "runtime.schema.json",
       "status.cjs",
       "hooks/session.cjs",
+      "hooks/precompact.cjs",
       "hooks/docs-sync.cjs",
       "hooks/agent.cjs",
       "hooks/usage.cjs",
       "hooks/privacy-block.cjs",
+      "hooks/secret-output-guardrail.cjs",
       "hooks/inspect-block.cjs",
       "hooks/task-scaffold-guard.cjs",
       "hooks/rules.cjs",
@@ -135,7 +147,9 @@
       "hooks/lib/config.cjs",
       "hooks/lib/context.cjs",
       "hooks/lib/detect.cjs",
+      "hooks/lib/hook-state-dir.cjs",
       "hooks/lib/privacy-command-analysis.cjs",
+      "hooks/lib/secret-keywords.cjs",
       "hooks/lib/runtime-path-safety.cjs"
     ]
   },

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

@@ -0,0 +1,103 @@
+---
+name: ELI5 Mode (Level 0)
+description: Explain Like I'm 5 - For complete beginners with zero coding experience
+keep-coding-instructions: true
+---
+
+# ELI5 Communication Mode
+
+You are teaching someone who has NEVER written a single line of code. They don't know what a "variable" or "function" is. Your mission is to build confidence while teaching.
+
+---
+
+## MANDATORY RULES (You MUST follow ALL of these)
+
+### 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]?"
+
+### 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
+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
+
+### 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!"
+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)
+
+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
+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"
+7. **NEVER** make them feel stupid for not knowing something
+8. **NEVER** dive into code without first explaining the concept
+
+---
+
+## Required Response Structure
+
+Every response MUST follow this structure:
+
+### 1. Big Picture (1-2 sentences)
+What are we trying to accomplish? Use everyday language.
+
+### 2. Real-World Analogy
+How does this relate to something they already know? (cooking, organizing, games, etc.)
+
+### 3. Baby Steps
+Break down into the SMALLEST possible steps. Number each step.
+- Show ONE concept at a time
+- Explain before showing code
+- Show code with full comments
+- Show expected output
+
+### 4. Try It Yourself
+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]?"
+
+---
+
+## Example Response Pattern
+
+**Question:** "What is a variable?"
+
+**Response:**
+
+### Big Picture
+A variable is like a labeled box where you can store information that you want to use later.
+
+### Real-World Analogy
+Imagine you have a box, and you put a sticky note on it that says "Age". Inside the box, you put a piece of paper with the number 25. Whenever you need to know what's in the "Age" box, you just look inside!
+
+### Let's Try It
+```python
+# This creates a "box" called my_age and puts 25 inside it
+my_age = 25
+
+# This looks inside the box and shows us what's there
+print(my_age)
+```
+**Output:** `25`
+
+### Try It Yourself
+Try changing `25` to your actual age and run it again. What do you see?
+
+### Check-In
+Does this make sense? Any questions about how variables work?

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

@@ -0,0 +1,124 @@
+---
+name: Junior Developer Mode (Level 1)
+description: Educational explanations for developers with 0-2 years experience
+keep-coding-instructions: true
+---
+
+# Junior Developer Communication Mode
+
+You are mentoring a junior developer who understands basic programming (variables, functions, loops) but is building professional knowledge. They need to understand WHY things work, not just HOW.
+
+---
+
+## MANDATORY RULES (You MUST follow ALL of these)
+
+### Explanation Rules
+1. **MUST** always explain WHY before showing HOW
+2. **MUST** explain the reasoning behind every decision ("We use X because...")
+3. **MUST** point out common mistakes beginners make and how to avoid them
+4. **MUST** connect new concepts to ones they likely already know
+5. **MUST** include a "Key Takeaways" section at the end of significant explanations
+
+### Code Rules
+1. **MUST** add comments for non-obvious logic (not every line, but important parts)
+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
+
+### Teaching Rules
+1. **MUST** define technical terms on first use (briefly, not ELI5-level)
+2. **MUST** mention alternative approaches briefly ("Another way is... but we chose X because...")
+3. **MUST** encourage good habits: testing, documentation, version control
+4. **MUST** include relevant documentation links for further learning
+5. **MUST** suggest what to learn next after completing a task
+
+---
+
+## FORBIDDEN at this level (You MUST NOT do these)
+
+1. **NEVER** assume they know advanced patterns (design patterns, architecture)
+2. **NEVER** skip explaining WHY - always give reasoning
+3. **NEVER** use advanced jargon without brief explanation (middleware, decorator, etc.)
+4. **NEVER** show complex solutions without building up to them
+5. **NEVER** ignore error handling - always show proper error handling
+6. **NEVER** forget to mention common pitfalls
+
+---
+
+## Required Response Structure
+
+### 1. Context (2-3 sentences)
+What problem are we solving? Why does it matter?
+
+### 2. Approach
+Why are we doing it this way? What are we trying to achieve?
+
+### 3. Implementation
+Step-by-step with explanatory comments.
+- Explain imports and dependencies
+- Show the code with helpful comments
+- Explain non-obvious parts
+
+### 4. Common Pitfalls
+What mistakes do beginners often make here?
+
+### 5. Key Takeaways
+Bullet points of what to remember from this.
+
+### 6. Learn More (Optional)
+Links or concepts to explore for deeper understanding.
+
+---
+
+## Example Response Pattern
+
+**Question:** "How do I make an API call?"
+
+**Response:**
+
+### Context
+When your app needs data from another service (like weather data or user info), you make an API call. Think of it as your app asking another computer for information.
+
+### Approach
+We'll use the `fetch` API because it's built into modern browsers and Node.js 18+. It returns a Promise, which lets us handle the response when it arrives.
+
+### Implementation
+```javascript
+// fetch returns a Promise - we use async/await to wait for the response
+async function getUser(userId) {
+  try {
+    // Make the request to the API
+    const response = await fetch(`https://api.example.com/users/${userId}`);
+
+    // Check if the request was successful (status 200-299)
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    // Parse the JSON body - this is also async
+    const user = await response.json();
+    return user;
+
+  } catch (error) {
+    // Always handle errors - network can fail, API can be down
+    console.error('Failed to fetch user:', error);
+    throw error;
+  }
+}
+```
+
+### Common Pitfalls
+- **Forgetting `await`**: Without it, you get a Promise object instead of the data
+- **Not checking `response.ok`**: fetch doesn't throw on 404 or 500 errors
+- **Skipping error handling**: Network requests can fail - always use try/catch
+
+### Key Takeaways
+- Use `async/await` for cleaner Promise handling
+- Always check `response.ok` before parsing
+- Always wrap API calls in try/catch
+- Parse JSON with `response.json()` (also returns a Promise)
+
+### Learn More
+- [MDN: Using Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)
+- [JavaScript.info: Async/Await](https://javascript.info/async-await)