@haposoft/cafekit 0.16.7 → 0.18.1

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

@@ -44,6 +44,40 @@ function canonicalPath(value) {
   try { return fs.realpathSync(value); } catch { return null; }
 }
 
+/** Real path of `value`, resolving its deepest existing ancestor (the file may not exist yet). */
+function canonicalTarget(value) {
+  if (typeof value !== 'string' || !value) return null;
+  let current = path.resolve(value);
+  const rest = [];
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    rest.unshift(path.basename(current));
+    current = parent;
+  }
+  const real = canonicalPath(current);
+  return real ? path.join(real, ...rest) : null;
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Packets the prompt names: `specs/<name>`, a `/cf:<command> <name>` token, or the bare
+ * name when it carries `-`, `_` or a digit. A plain word such as `docs` must use `specs/`,
+ * so an ordinary sentence does not touch a packet.
+ */
+function packetsNamedIn(text, names) {
+  if (typeof text !== 'string' || !text) return [];
+  return names.filter((name) => {
+    const n = escapeRegExp(name);
+    if (new RegExp(`(^|[^\\w-])specs/${n}(?![\\w-])`).test(text)) return true;
+    if (new RegExp(`/cf:[\\w-]+\\s+(?:specs/)?${n}(?![\\w-])`).test(text)) return true;
+    return /[-_0-9]/.test(name) && new RegExp(`(^|[^\\w/-])${n}(?![\\w-])`).test(text);
+  });
+}
+
 try {
   // ── Main ──────────────────────────────────────────────────────────────────
 
@@ -51,7 +85,8 @@ try {
   if (!stdin) process.exit(0);
 
   const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
-  const payload = normalizeHookPayload(JSON.parse(stdin));
+  const rawPayload = JSON.parse(stdin);
+  const payload = normalizeHookPayload(rawPayload);
   const cwd     = payload.cwd || process.cwd();
 
   let POLICY;
@@ -61,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);
@@ -84,10 +119,97 @@ try {
   const baseDir   = installedRoot || process.env.PROJECT_ROOT || cwd;
   const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
   const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
-  const resolveWorkflow = typeof RESOLVER.resolveWorkflowCandidate === 'function'
-    ? RESOLVER.resolveWorkflowCandidate
-    : RESOLVER.resolveActiveSpec;
-  const resolved = resolveWorkflow({ projectRoot: baseDir, runtime, explicitFeature, explicitPath });
+
+  // ── Per-session touch set (Claude only) ───────────────────────────────────
+  // Several sessions can share one checkout. On Claude the tollgate speaks only about a
+  // packet this session touched. omp and Codex run their own copies, and grok sends
+  // `sessionId` before normalization, so all three keep the old behaviour.
+  const claudeSession = rawPayload && typeof rawPayload.session_id === 'string' && rawPayload.session_id
+    ? rawPayload.session_id
+    : null;
+  const touchFilter = runtimeDirName() === '.claude' && claudeSession !== null;
+  const touchFile = touchFilter
+    ? path.join(
+      require('./lib/hook-state-dir.cjs').hookStateDir(),
+      `spec-touched-${require('crypto').createHash('sha256').update(claudeSession).digest('hex')}.json`,
+    )
+    : null;
+  const readTouched = () => {
+    try {
+      const list = JSON.parse(fs.readFileSync(touchFile, 'utf8'));
+      return new Set(Array.isArray(list) ? list : []);
+    } catch { return new Set(); }
+  };
+  const addTouched = (names) => {
+    const touched = readTouched();
+    const before = touched.size;
+    for (const name of names) touched.add(name);
+    if (touched.size === before) return;
+    try {
+      fs.mkdirSync(path.dirname(touchFile), { recursive: true });
+      fs.writeFileSync(touchFile, JSON.stringify([...touched].sort()));
+    } catch { /* an unwritable state dir only loses the touch */ }
+  };
+  let specsRoot = null;
+  try { specsRoot = RESOLVER.specsDirectory(baseDir, runtime); } catch { /* resolver reports it below */ }
+
+  if (payload.hook_event_name === 'PostToolUse') {
+    // Record only; no resolve, no git, no tollgate cache.
+    if (touchFilter && specsRoot && /^(Edit|Write|MultiEdit)$/.test(payload.tool_name || '')) {
+      const realRoot = canonicalPath(specsRoot);
+      const realTarget = canonicalTarget(payload.tool_input && payload.tool_input.file_path);
+      if (realRoot && realTarget) {
+        const rel = path.relative(realRoot, realTarget);
+        const parts = rel.split(path.sep);
+        if (rel && parts[0] !== '..' && !path.isAbsolute(rel) && parts.length > 1) addTouched([parts[0]]);
+      }
+    }
+    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 {
+      packets = fs.readdirSync(specsRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    } catch { /* no specs root */ }
+    const named = packetsNamedIn(payload.prompt, packets);
+    if (typeof explicitFeature === 'string' && explicitFeature) named.push(explicitFeature);
+    if (named.length) addTouched(named);
+  }
+
+  const resolved = RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, explicitFeature, explicitPath });
 
   if (!resolved) {
     process.exit(0); // No active spec, do nothing
@@ -101,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);
   }
 
@@ -115,21 +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';
@@ -137,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',
@@ -156,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
@@ -184,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');
 
@@ -194,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);
   }
 
@@ -218,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/hooks/state.cjs

@@ -148,6 +148,21 @@ try {
     return data;
   }
 
+  /**
+   * True when latest.md holds something beyond the filler this hook writes itself:
+   * headings, HTML comments, the three placeholder bullets and timestamp-only agent results.
+   */
+  function hasPriorContent(text) {
+    const filler = [
+      /^#{1,6}\s/,
+      /^<!--.*-->$/,
+      /^- \((No completed tasks recorded|All tasks completed|No file changes detected)\)$/,
+      /^- Completed at \d{2}:\d{2}:\d{2}$/,
+    ];
+    return text.split('\n').map((line) => line.trim())
+      .some((line) => line && !filler.some((pattern) => pattern.test(line)));
+  }
+
   function buildStateContent(data) {
     const done = data.todos.filter((todo) => todo.status === 'completed' || todo.status === 'done');
     const pending = data.todos.filter((todo) => !['completed', 'done'].includes(todo.status));
@@ -226,14 +241,18 @@ try {
     if (!stdin) process.exit(0);
 
     const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
-    const data = normalizeHookPayload(JSON.parse(stdin));
+    const rawPayload = JSON.parse(stdin);
+    const data = normalizeHookPayload(rawPayload);
     const event = data.hook_event_name || '';
     const cwd = data.cwd || process.cwd();
     const dir = stateDir(cwd);
 
     if (event === 'SessionStart') {
       const previous = loadLatest(cwd);
-      if (previous) {
+      // Claude only: grok (camelCase sessionId), omp and Codex keep printing the block.
+      const claudeSession = runtimeDirName() === '.claude'
+        && typeof rawPayload.session_id === 'string' && rawPayload.session_id.length > 0;
+      if (previous && (!claudeSession || hasPriorContent(previous))) {
         console.log('\n=== Prior Execution Context ===');
         console.log(previous.trim());
         console.log('=== End of Prior Context ===\n');

package/src/claude/migration-manifest.json

@@ -7,23 +7,21 @@
   "skills": {
     "required": [
       "agent-browser",
+      "ask",
       "brainstorm",
       "chrome-devtools",
       "code-review",
       "debug",
-      "delegate",
       "develop",
+      "fix",
       "git",
-      "hotfix",
-      "inspect",
-      "loop",
       "orca",
-      "question",
       "research",
-      "route",
+      "scout",
       "specs",
       "sync",
       "test",
+      "ui-ux",
       "ui-ux-pro-max",
       "web-testing"
     ],
@@ -61,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"
     ]
   },
@@ -86,13 +79,31 @@
       "frontend-design",
       "mobile-development",
       "devops",
-      "react-best-practices"
+      "react-best-practices",
+      "inspect",
+      "hotfix",
+      "question",
+      "loop",
+      "route",
+      "delegate"
     ],
     "agents": {
       "claude": ["agents/god-developer.md"],
       "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",
@@ -112,10 +123,27 @@
       "skills/specs/rules/ears-format.md",
       "skills/specs/rules/phase-decision-matrix.md",
       "skills/specs/rules/task-scoring-rubric.md",
-      "skills/specs/rules/tasks-generation.md"
+      "skills/specs/rules/tasks-generation.md",
+      "hooks/usage.cjs",
+      "hooks/completion-authority.cjs",
+      "hooks/completion-authority-check.cjs",
+      "hooks/completion-authority-state.cjs",
+      "hooks/semantic-review-authority.cjs",
+      "hooks/task-scaffold-guard.cjs"
     ],
     "settingsHookCommandSubstrings": [
-      "hooks/skill-router.cjs"
+      "hooks/skill-router.cjs",
+      ".claude/hooks/usage.cjs",
+      ".claude/hooks/docs-sync.cjs",
+      ".claude/hooks/completion-authority.cjs",
+      ".codex/hooks/completion-authority.cjs",
+      ".codex\\hooks\\completion-authority.cjs",
+      ".claude/hooks/semantic-review-authority.cjs",
+      ".codex/hooks/semantic-review-authority.cjs",
+      ".codex\\hooks\\semantic-review-authority.cjs",
+      ".claude/hooks/task-scaffold-guard.cjs",
+      ".codex/hooks/task-scaffold-guard.cjs",
+      ".codex\\hooks\\task-scaffold-guard.cjs"
     ]
   },
   "runtime": {
@@ -128,26 +156,18 @@
       "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",
       "hooks/spec-state.cjs",
       "hooks/spec-gate.cjs",
-      "hooks/completion-authority.cjs",
-      "hooks/completion-authority-check.cjs",
-      "hooks/completion-authority-state.cjs",
-      "hooks/semantic-review-authority.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
       "hooks/lib/parser.cjs",
       "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.