@haposoft/cafekit 0.18.0 → 0.18.1

package/src/claude/hooks/__tests__/spec-state-touched.test.js

@@ -132,3 +132,29 @@ test('a prompt touch is remembered even when two packets are active', () => {
     assert.match(fx.prompt('s7', 'Continue'), /auth-flow/);
   });
 });
+
+function writeLegacyPacket(root, name) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(path.join(dir, 'tasks'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'spec.json'), JSON.stringify({ feature_name: name, status: 'in_progress' }));
+}
+
+const LEGACY_NOTICE = /`specs\/old` is a legacy Specs packet without plan\.md; CafeKit no longer reads it/;
+
+test('a leftover legacy packet is noticed once per session, before the touch filter', () => {
+  within(fixture(['auth-flow']), (fx) => {
+    writeLegacyPacket(fx.root, 'old');
+    const first = fx.prompt('s1', 'Continue');
+    assert.match(first, LEGACY_NOTICE);
+    assert.strictEqual(first.match(new RegExp(LEGACY_NOTICE.source, 'g')).length, 1);
+    assert.strictEqual(fx.prompt('s1', 'Continue'), '', 'the same session is not told twice');
+    assert.match(fx.prompt('s2', 'Continue'), LEGACY_NOTICE, 'a new session is told once');
+  });
+});
+
+test('a legacy packet is noticed even when it is the only packet', () => {
+  within(fixture([]), (fx) => {
+    writeLegacyPacket(fx.root, 'old');
+    assert.match(fx.prompt('s1', 'Continue'), LEGACY_NOTICE);
+  });
+});

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

@@ -97,8 +97,7 @@ try {
     RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
     RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
     if (typeof POLICY.validateCanonicalReceipt !== 'function'
-      || typeof POLICY.completionDecisionForSpec !== 'function'
-      || typeof RECEIPT.checkTaskReceipt !== 'function'
+      || typeof RECEIPT.checkWorkflowTaskReceipt !== 'function'
       || typeof RECEIPT.checkWorkflowReceiptSet !== 'function'
       || typeof RESOLVER.resolveWorkflowCandidate !== 'function') {
       throw new Error('shared workflow policy lacks completion authority functions');
@@ -164,7 +163,7 @@ try {
   if (resolved.error === 'invalid_specs') {
     process.stdout.write(JSON.stringify({
       decision: 'block',
-      reason: `Completion gate: invalid spec JSON detected (${resolved.candidates.join(', ')}): ${resolved.reason}. Fix or remove malformed spec.json before completing tasks.`
+      reason: `Completion gate: invalid workflow packet detected (${resolved.candidates.join(', ')}): ${resolved.reason}. Fix the packet's plan.md or task files before completing tasks.`,
     }) + '\n');
     process.exit(0);
   }
@@ -177,22 +176,12 @@ try {
   }
   if (resolved.error) process.exit(0);
 
-  const activeSpec = resolved.spec || {};
-  const processWorkflow = resolved.layoutKind === 'process-v3';
   const featureName = resolved.featureName;
   const specsPath = resolved.specsDir;
-  const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
-  const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
-    || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
-  // Legacy 2.1 closeout is retired; a 2.1 packet mid-execution keeps the ordinary receipt checks.
-  if (!processWorkflow && activeSpec.schema_version === '2.1' && explicitCloseout) {
-    emitBlock('Completion gate: Legacy spec.json closeout is no longer supported; move the packet to plan.md with flat task files');
-    process.exit(0);
-  }
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
-    specFile: resolved.stateFile || resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    specFile: resolved.stateFile,
     featureName,
     runtimeSession: sessionIdentity(payload),
   });
@@ -202,7 +191,7 @@ try {
     emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
     process.exit(0);
   }
-  const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
+  const taskRegistry = resolved.taskRegistry || {};
   const cacheFile = path.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
@@ -215,17 +204,6 @@ try {
     currentStatuses[tp] = task?.status || 'pending';
   }
 
-  const staleFlashTasks = processWorkflow ? [] : Object.entries(taskRegistry)
-    .filter(([, task]) => POLICY.isStaleFlashDone(task))
-    .map(([taskPath]) => taskPath);
-  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 /cf:test for exact proof, then use explicit sync-finalize.`
-    }) + '\n');
-    process.exit(0);
-  }
-
   // Cache hardening: every Stop re-reads and re-checks the receipt of every
   // task currently marked done, so a cached PASS cannot hide later mutations
   // (deletion, placeholder, changed Verification/Command/Exit, missing
@@ -241,29 +219,11 @@ try {
   const featureDir = path.join(specsPath, featureName);
   const failures = allDoneTasks
     .map((taskPath) => {
-      const proof = processWorkflow
-        ? RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY)
-        : RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY);
+      const proof = RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY);
       return { taskPath, fails: proof.failures, body: proof.body };
     })
     .filter((f) => f.fails.length > 0);
 
-  const featureCloseoutRequired = !processWorkflow && explicitCloseout && allDoneTasks.length > 0;
-  const featureReceipt = featureCloseoutRequired
-    ? RECEIPT.checkFeatureReceipt(featureDir, runtimeContext, POLICY)
-    : null;
-  if (featureReceipt && featureReceipt.failures.length) {
-    failures.push({ taskPath: 'feature-receipt.md', fails: featureReceipt.failures });
-  }
-  const completion = featureCloseoutRequired && featureReceipt?.failures.length === 0
-    && Object.prototype.hasOwnProperty.call(activeSpec, 'workflow_policy')
-    ? POLICY.completionDecisionForSpec(activeSpec, {
-      runtimeContext,
-      executionReceipt: featureReceipt.body,
-      taskContext: {},
-    })
-    : null;
-
   // Always persist status transitions, including done → pending. Keep
   // failing done tasks at their previous cached status so a stale valid
   // entry cannot mask a mutated receipt on the next Stop; with
@@ -279,27 +239,12 @@ try {
     fs.writeFileSync(cacheFile, JSON.stringify(cache));
   } catch { /* fail-open */ }
 
-  const completionBlocked = completion && completion.completion !== 'complete' && completion.completion !== 'not_applicable';
-  if (failures.length === 0 && !completionBlocked) process.exit(0);
+  if (failures.length === 0) process.exit(0);
 
-  const lines = [
-    failures.length > 0
-      ? `⚠️ Completion gate: ${failures.length} done task(s) lack a verification receipt.`
-      : '⚠️ Completion gate: workflow completion proof is incomplete.',
-  ];
+  const lines = [`⚠️ Completion gate: ${failures.length} done task(s) lack a verification receipt.`];
   for (const { taskPath, fails, body } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
-    lines.push(taskPath === 'feature-receipt.md'
-      ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
-      : processWorkflow
-        ? `  Fix in \`specs/${featureName}/${path.posix.basename(taskPath)}\`: ${(typeof RECEIPT.receiptFixHint === 'function' && RECEIPT.receiptFixHint(fails, body)) || 'write a runtime-bound `## Receipt` with command output'}.`
-        : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
-  }
-  if (completionBlocked) {
-    lines.push(`- Completion decision unfinished: ${completion.blocker || 'required workflow proof is missing.'}`);
-    if (Array.isArray(completion.missingProof) && completion.missingProof.length > 0) {
-      lines.push(`  Missing proof: ${completion.missingProof.join(', ')}`);
-    }
+    lines.push(`  Fix in \`specs/${featureName}/${path.posix.basename(taskPath)}\`: ${(typeof RECEIPT.receiptFixHint === 'function' && RECEIPT.receiptFixHint(fails, body)) || 'write a runtime-bound `## Receipt` with command output'}.`);
   }
   process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');
   process.exit(0);

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

@@ -96,7 +96,7 @@ try {
     POLICY = require(path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs'));
     RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
     RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
-    if (typeof POLICY.flashState !== 'function') throw new Error('shared workflow policy has no flashState function');
+    if (typeof RESOLVER.resolveWorkflowCandidate !== 'function') throw new Error('shared spec resolver has no resolveWorkflowCandidate function');
   } catch (error) {
     logCrash(error);
     emitControlledFailure(error.message);
@@ -167,6 +167,38 @@ try {
     process.exit(0);
   }
 
+  // A legacy packet (a specs/<x>/ directory without plan.md that the old flow left
+  // behind) is no longer read. Say so once per session instead of on every prompt.
+  const legacyPackets = typeof RESOLVER.findLegacyPackets === 'function'
+    ? RESOLVER.findLegacyPackets(baseDir, runtime)
+    : [];
+  if (legacyPackets.length > 0) {
+    const sessionKey = sessionIdentity(payload);
+    const noticeFile = sessionKey
+      ? path.join(
+        require('./lib/hook-state-dir.cjs').hookStateDir(),
+        `legacy-notice-${require('crypto').createHash('sha256').update(sessionKey).digest('hex')}.json`,
+      )
+      : null;
+    let noticed = [];
+    if (noticeFile) {
+      try { noticed = JSON.parse(fs.readFileSync(noticeFile, 'utf8')); } catch { noticed = []; }
+      if (!Array.isArray(noticed)) noticed = [];
+    }
+    const fresh = legacyPackets.filter((name) => !noticed.includes(name));
+    if (fresh.length > 0) {
+      for (const name of fresh) {
+        console.log(`\n> ⚠️ \`specs/${name}\` is a legacy Specs packet without plan.md; CafeKit no longer reads it. Move ongoing work to a process-first plan.md packet.`);
+      }
+      if (noticeFile) {
+        try {
+          fs.mkdirSync(path.dirname(noticeFile), { recursive: true });
+          fs.writeFileSync(noticeFile, JSON.stringify([...noticed, ...fresh].sort()));
+        } catch { /* an unwritable state dir only repeats the notice */ }
+      }
+    }
+  }
+
   if (touchFilter) {
     let packets = [];
     try {
@@ -177,10 +209,7 @@ try {
     if (named.length) addTouched(named);
   }
 
-  const resolveWorkflow = typeof RESOLVER.resolveWorkflowCandidate === 'function'
-    ? RESOLVER.resolveWorkflowCandidate
-    : RESOLVER.resolveActiveSpec;
-  const resolved = resolveWorkflow({ projectRoot: baseDir, runtime, explicitFeature, explicitPath });
+  const resolved = RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, explicitFeature, explicitPath });
 
   if (!resolved) {
     process.exit(0); // No active spec, do nothing
@@ -194,7 +223,7 @@ try {
 
   if (resolved.error === 'invalid_specs') {
     const cands = resolved.candidates.join(', ');
-    console.log(`\n> ⚠️ Invalid spec JSON detected: ${cands}. ${resolved.reason}. Fix or remove malformed spec.json before continuing. Tollgate paused.\n`);
+    console.log(`\n> ⚠️ Invalid workflow packet detected: ${cands}. ${resolved.reason}. Fix the packet's plan.md or task files before continuing. Tollgate paused.\n`);
     process.exit(0);
   }
 
@@ -208,22 +237,19 @@ try {
     process.exit(0);
   }
 
-  const activeSpec = resolved.spec || {};
-  const processWorkflow = resolved.layoutKind === 'process-v3';
   const featureName = resolved.featureName;
   if (touchFilter && !readTouched().has(featureName)) process.exit(0);
   const specsPath = resolved.specsDir;
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
-    specFile: resolved.stateFile || resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    specFile: resolved.stateFile,
     featureName,
     runtimeSession: sessionIdentity(payload),
   });
 
-  const phase = resolved.phase || activeSpec.current_phase || activeSpec.phase || 'unknown';
-  const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
-  const flashTasks = POLICY.flashState(taskRegistry);
+  const phase = resolved.phase || 'unknown';
+  const taskRegistry = resolved.taskRegistry || {};
   const taskEntries = Object.entries(taskRegistry);
   const taskCounts = taskEntries.reduce((acc, [, task]) => {
     const status = task?.status || 'pending';
@@ -231,10 +257,7 @@ try {
     return acc;
   }, {});
   const featureDir = path.join(specsPath, featureName);
-  const taskStatusByPath = new Map(taskEntries.map(([taskPath, task]) => [taskPath, task?.status || 'pending']));
-  const dependencyProof = processWorkflow
-    ? RECEIPT.workflowDependencyProofState(featureDir, taskRegistry, runtimeContext, POLICY)
-    : {};
+  const dependencyProof = RECEIPT.workflowDependencyProofState(featureDir, taskRegistry, runtimeContext, POLICY);
   const taskState = taskEntries.map(([taskPath, task]) => [
     taskPath,
     task?.status || 'pending',
@@ -250,12 +273,9 @@ try {
   const nextUnblocked = taskEntries.find(([, task]) => {
     const status = task?.status || 'pending';
     const deps = Array.isArray(task?.dependencies) ? task.dependencies : [];
-    return resolved.queueReady !== false && status === 'pending' && deps.every((dep) => (
-      processWorkflow ? dependencyProof[dep]?.eligible === true : taskStatusByPath.get(dep) === 'done'
-    ));
+    return resolved.queueReady !== false && status === 'pending'
+      && deps.every((dep) => dependencyProof[dep]?.eligible === true);
   });
-  const featureReceiptPresent = !processWorkflow
-    && RECEIPT.safeRead(featureDir, 'feature-receipt.md').status === 'ok';
 
   // ── State-change gate: only emit the full tollgate when spec state changed ──
   // The cache is shared by installed hook copies, so its key must carry the
@@ -278,7 +298,6 @@ try {
     proofState,
     done: taskCounts.done || 0,
     total: taskEntries.length,
-    featureReceiptPresent,
   });
   const cacheFile = path.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'tollgate-last.txt');
 
@@ -288,11 +307,10 @@ try {
   }
 
   if (stateKey && lastKey === stateKey) {
-    const stateTarget = processWorkflow ? 'task Markdown' : '`spec.json`';
-    const migration = processWorkflow && resolved.queueReady === false
+    const migration = resolved.queueReady === false
       ? ' Add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.'
       : '';
-    console.log(`\n> 🔵 Spec \`${featureName}\` @ \`${phase}\` (${taskCounts.done || 0}/${taskEntries.length} tasks done). Tollgate active — sync ${stateTarget} when state changes.${migration}\n`);
+    console.log(`\n> 🔵 Spec \`${featureName}\` @ \`${phase}\` (${taskCounts.done || 0}/${taskEntries.length} tasks done). Tollgate active — sync task Markdown when state changes.${migration}\n`);
     process.exit(0);
   }
 
@@ -312,20 +330,11 @@ try {
   if (nextUnblocked) {
     lines.push(`- Next unblocked: \`${nextUnblocked[0]}\``);
   }
-  if (flashTasks.length > 0) {
-    lines.push(`- Flash verification pending: ${flashTasks.map((taskPath) => `\`${taskPath}\``).join(', ')}. A PASS proof keeps the persisted task in_progress until explicit sync-finalize.`);
-  }
-  if (processWorkflow) {
-    if (resolved.queueReady === false) {
-      lines.push('- Migration required: add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.');
-    }
-    lines.push('- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.');
-    lines.push(`- Workflow source: \`specs/${featureName}/plan.md\`; Stop re-checks every done receipt, binding Base/Head to the runtime only while a committed task file no longer matches its committed bytes.`);
-  } else {
-    lines.push('- Sync `spec.json` + task Markdown status after verified work; task proof belongs in `receipts/<task-basename>.md`.');
-    lines.push(`- Create \`feature-receipt.md\` once after final integration proof${featureReceiptPresent ? ' (present)' : ' (not required before closeout)'}.`);
-    lines.push(`- Validate with \`node ${runtimeDirName()}/scripts/validate-spec-output.cjs specs/${featureName}\`; hooks revalidate receipt bytes but never grant approval.`);
+  if (resolved.queueReady === false) {
+    lines.push('- Migration required: add `Specs-Contract: process-first-ready-v1` after the plan title before tasks can enter Next.');
   }
+  lines.push('- Sync each flat task `Status:` only after verified work; task proof belongs in that task\'s inline `## Receipt`.');
+  lines.push(`- Workflow source: \`specs/${featureName}/plan.md\`; Stop re-checks every done receipt, binding Base/Head to the runtime only while a committed task file no longer matches its committed bytes.`);
   lines.push('');
 
   console.log(lines.join('\n'));

package/src/claude/migration-manifest.json

@@ -59,15 +59,10 @@
       "validate-docs.cjs",
       "validate-docs-reconstruct.cjs",
       "generate-skill-catalog.cjs",
-      "validate-spec-output.cjs",
       "scan-staged-secrets.cjs",
       "workflow-policy.cjs",
       "spec-resolver.cjs",
       "spec-receipt.cjs",
-      "spec-ground.cjs",
-      "spec-semantic-model.cjs",
-      "spec-final-state.cjs",
-      "spec-readiness.cjs",
       "provenance.cjs"
     ]
   },
@@ -97,6 +92,18 @@
       "codex": ["agents/god_developer.toml"]
     },
     "runtimeFiles": [
+      "scripts/validate-spec-output.cjs",
+      "scripts/spec-ground.cjs",
+      "scripts/spec-authoring-digest.cjs",
+      "scripts/spec-semantic-model.cjs",
+      "scripts/spec-final-state.cjs",
+      "skills/code-review/references/verification-gate.md",
+      "scripts/change-firewall.cjs",
+      "scripts/spec-scaffold.cjs",
+      "scripts/spec-readiness.cjs",
+      "scripts/spec-authoring-validation.cjs",
+      "hooks/lib/context.cjs",
+      "hooks/lib/detect.cjs",
       "hooks/skill-router.cjs",
       "hooks/lib/skill-router-routes.cjs",
       "scripts/browser-tool.cjs",
@@ -161,8 +168,6 @@
       "hooks/lib/counter.cjs",
       "hooks/lib/git.cjs",
       "hooks/lib/config.cjs",
-      "hooks/lib/context.cjs",
-      "hooks/lib/detect.cjs",
       "hooks/lib/hook-state-dir.cjs",
       "hooks/lib/runtime-dir.cjs",
       "hooks/lib/hook-payload.cjs",

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/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.