chati-dev 4.0.11 → 4.1.0

package/framework/hooks/session-digest.js

@@ -6,9 +6,13 @@
  * recovered after context compaction. Writes to .chati/memories/shared/session/.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { join } from 'path';
 
+/**
+ * Extract structured 8-section digest from session state.
+ * Enriched version captures decisions, blockers, gotchas for better recovery.
+ */
 function extractDigest(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
   if (!existsSync(sessionPath)) return null;
@@ -19,13 +23,40 @@ function extractDigest(projectDir) {
     return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
   };
 
-  return {
+  // Base digest (backward-compatible)
+  const base = {
     timestamp: new Date().toISOString(),
     mode: extract('mode') || 'discover',
     currentAgent: extract('current_agent') || 'none',
     pipelinePosition: extract('pipeline_position') || 'unknown',
     workflow: extract('workflow') || 'unknown',
   };
+
+  // Enrich with gotchas (lightweight read, capped at 10)
+  let gotchas = [];
+  try {
+    const gotchasPath = join(projectDir, '.chati', 'memories', 'shared', 'gotchas.json');
+    if (existsSync(gotchasPath)) {
+      const gotchasData = JSON.parse(readFileSync(gotchasPath, 'utf-8'));
+      const entries = Array.isArray(gotchasData) ? gotchasData : (gotchasData.gotchas || []);
+      gotchas = entries.slice(0, 10).map(g => ({
+        id: g.id,
+        message: (g.message || '').slice(0, 200),
+        severity: g.severity,
+      }));
+    }
+  } catch { /* ignore read errors */ }
+
+  return {
+    ...base,
+    version: '2.0',
+    // Structured sections (enriched)
+    active_task: extract('active_task') || null,
+    blockers: [],      // Populated by agents at runtime
+    decisions_made: [], // Populated by agents at runtime
+    gotchas_found: gotchas,
+    next_steps: [],    // Populated by agents at runtime
+  };
 }
 
 async function main() {
@@ -44,15 +75,136 @@ async function main() {
       mkdirSync(digestDir, { recursive: true });
 
       const fileName = `digest-${Date.now()}.yaml`;
-      const content = Object.entries(digest)
-        .map(([k, v]) => `${k}: "${v}"`)
-        .join('\n');
+      // Serialize to YAML-like format supporting arrays and objects
+      const lines = [];
+      for (const [k, v] of Object.entries(digest)) {
+        if (Array.isArray(v)) {
+          if (v.length === 0) {
+            lines.push(`${k}: []`);
+          } else {
+            lines.push(`${k}:`);
+            for (const item of v) {
+              lines.push(`  - ${typeof item === 'object' ? JSON.stringify(item) : item}`);
+            }
+          }
+        } else if (v === null) {
+          lines.push(`${k}: null`);
+        } else {
+          lines.push(`${k}: ${JSON.stringify(String(v))}`);
+        }
+      }
+
+      writeFileSync(join(digestDir, fileName), lines.join('\n') + '\n', 'utf-8');
+
+      // Auto daily digest: append session entry on every PreCompact
+      try {
+        const dailyDir = join(projectDir, '.chati', 'memories', 'shared', 'daily');
+        mkdirSync(dailyDir, { recursive: true });
+        const dateStr = new Date().toISOString().split('T')[0];
+        const dailyPath = join(dailyDir, `${dateStr}.md`);
+        const time = new Date().toISOString().split('T')[1].split('.')[0];
+        const entry = `### ${time} -- ${digest.mode} (${digest.currentAgent})\n- Pipeline: ${digest.pipelinePosition}\n\n`;
+        let existing = '';
+        if (existsSync(dailyPath)) {
+          existing = readFileSync(dailyPath, 'utf-8');
+        } else {
+          existing = `# Daily Digest -- ${dateStr}\n\n`;
+        }
+        writeFileSync(dailyPath, existing + entry, 'utf-8');
+      } catch (err) {
+        process.stderr.write(`[chati] session-digest daily-append: ${err.message}\n`);
+      }
+
+      // Auto memory consolidation: trigger when memories accumulate
+      try {
+        const memBase = join(projectDir, '.chati', 'memories');
+        if (existsSync(memBase)) {
+          let totalEntries = 0;
+          const dirs = readdirSync(memBase, { withFileTypes: true })
+            .filter(d => d.isDirectory() && d.name !== 'shared');
+          for (const d of dirs) {
+            const memFile = join(memBase, d.name, 'MEMORY.md');
+            if (existsSync(memFile)) {
+              const content = readFileSync(memFile, 'utf-8');
+              totalEntries += (content.match(/^- /gm) || []).length;
+            }
+          }
+          // Consolidate when > 100 entries (50% of 200 cap)
+          if (totalEntries > 100) {
+            process.stderr.write(`[chati] auto-dream: ${totalEntries} entries, triggering consolidation\n`);
+            // Fire-and-forget: consolidation runs in background
+            // Import would fail in hook context, so we spawn a child process
+            const { execSync } = await import('child_process');
+            try {
+              execSync(`node -e "import('./packages/chati-dev/src/memory/dream.js').then(m => m.runDreamConsolidation('${projectDir.replace(/'/g, "\\'")}'))"`, {
+                cwd: projectDir,
+                timeout: 10000,
+                stdio: 'ignore',
+              });
+            } catch { /* expected: consolidation may timeout or fail */ }
+          }
+        }
+      } catch (err) {
+        process.stderr.write(`[chati] session-digest auto-dream: ${err.message}\n`);
+      }
+    }
+
+    // Session telemetry ping (moved from license-guard to reduce per-prompt overhead)
+    // 5-minute throttle with phase/agent change detection
+    try {
+      const homedir = process.env.HOME || '';
+      const pingsPath = join(homedir, '.chati-dev', 'pings.yaml');
+      const licensePath = join(homedir, '.chati-dev', 'license.yaml');
+
+      if (existsSync(licensePath)) {
+        const licenseRaw = readFileSync(licensePath, 'utf-8');
+        const keyMatch = licenseRaw.match(/key:\s*["']?([^"'\n]+)/);
+        const licenseKey = keyMatch ? keyMatch[1].trim() : null;
+
+        if (licenseKey && digest) {
+          let shouldPing = false;
+          const now = Date.now();
+          const currentState = `${digest.mode}|${digest.currentAgent}`;
+
+          if (existsSync(pingsPath)) {
+            const pingsRaw = readFileSync(pingsPath, 'utf-8');
+            const entryMatch = pingsRaw.match(new RegExp(`${projectDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*?'([^']+)'`));
+            if (entryMatch) {
+              const [ts, phase, agent] = entryMatch[1].split('|');
+              const elapsed = now - parseInt(ts);
+              const stateChanged = `${phase}|${agent}` !== currentState;
+              shouldPing = elapsed > 300000 || stateChanged; // 5 min or state change
+            } else {
+              shouldPing = true;
+            }
+          } else {
+            shouldPing = true;
+          }
+
+          if (shouldPing) {
+            // Update ping timestamp
+            mkdirSync(join(homedir, '.chati-dev'), { recursive: true });
+            writeFileSync(pingsPath, `'${projectDir}': '${now}|${currentState}'\n`, 'utf-8');
 
-      writeFileSync(join(digestDir, fileName), content + '\n', 'utf-8');
+            // Fire-and-forget telemetry (3s timeout, never blocks)
+            try {
+              const body = JSON.stringify({
+                license_key: licenseKey,
+                project_name: digest.currentAgent || 'unknown',
+                events: [{ type: 'session_active', timestamp: new Date().toISOString(), properties: { pipeline_phase: digest.mode, current_agent: digest.currentAgent } }],
+              });
+              fetch('https://chati.dev/api/telemetry', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(3000) }).catch(() => {});
+            } catch { /* expected: network may be unavailable */ }
+          }
+        }
+      }
+    } catch (err) {
+      process.stderr.write(`[chati] session-digest telemetry-ping: ${err.message}\n`);
     }
 
     process.stdout.write(JSON.stringify({ result: 'allow' }));
-  } catch {
+  } catch (err) {
+    process.stderr.write(`[chati] session-digest: ${err.message}\n`);
     process.stdout.write(JSON.stringify({ result: 'allow' }));
   }
 }

package/framework/hooks/settings.json

@@ -5,10 +5,6 @@
       {
         "matcher": ".*",
         "hooks": [
-          {
-            "type": "command",
-            "command": "node chati.dev/hooks/license-guard.js"
-          },
           {
             "type": "command",
             "command": "node chati.dev/hooks/prism-engine.js"
@@ -51,6 +47,14 @@
           {
             "type": "command",
             "command": "node chati.dev/hooks/constitution-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node chati.dev/hooks/undercover-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node chati.dev/hooks/style-guard.js"
           }
         ]
       },
@@ -60,6 +64,14 @@
           {
             "type": "command",
             "command": "node chati.dev/hooks/constitution-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node chati.dev/hooks/undercover-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node chati.dev/hooks/style-guard.js"
           }
         ]
       }

package/framework/hooks/style-guard.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * Style Guard Hook — PreToolUse (Write/Edit/Bash)
+ *
+ * Enforces Constitution Article V writing standards:
+ * - No em-dashes (U+2013 EN DASH, U+2014 EM DASH)
+ * - No emojis in generated content
+ *
+ * Mode: Advisory (warn, not block). Agent receives warning and should self-correct.
+ * Feature-flag gated: respects anti_dash and no_emojis in config.yaml.
+ *
+ * Exempt paths: framework files (chati.dev/, .chati/), YAML configs, CLAUDE.md
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join, basename } from 'path';
+
+/** Em-dash and en-dash characters */
+const EM_DASH_PATTERN = /[\u2013\u2014]/;
+
+/** Emoji unicode ranges (comprehensive) */
+const EMOJI_PATTERN = /[\u{1F600}-\u{1F64F}\u{1F300}-\u{1F5FF}\u{1F680}-\u{1F6FF}\u{1F1E0}-\u{1F1FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{1F900}-\u{1F9FF}\u{1FA00}-\u{1FA6F}\u{1FA70}-\u{1FAFF}\u{231A}-\u{231B}\u{23E9}-\u{23F3}\u{23F8}-\u{23FA}\u{25AA}-\u{25AB}\u{25B6}\u{25C0}\u{25FB}-\u{25FE}\u{2614}-\u{2615}\u{2648}-\u{2653}\u{267F}\u{2693}\u{26A1}\u{26AA}-\u{26AB}\u{26BD}-\u{26BE}\u{26C4}-\u{26C5}\u{26CE}\u{26D4}\u{26EA}\u{26F2}-\u{26F3}\u{26F5}\u{26FA}\u{26FD}\u{2702}\u{2705}\u{2708}-\u{270D}\u{270F}]/u;
+
+/**
+ * Paths exempt from style enforcement.
+ * Framework files, configs, and context files may legitimately contain special chars.
+ */
+const EXEMPT_PATTERNS = [
+  /^chati\.dev\//,
+  /^\.chati\//,
+  /^\.claude\//,
+  /CLAUDE\.md$/,
+  /CLAUDE\.local\.md$/,
+  /GEMINI\.md$/,
+  /AGENTS\.md$/,
+  /\.yaml$/,
+  /\.yml$/,
+  /\.json$/,
+  /package\.json$/,
+  /\.lock$/,
+];
+
+function isExemptPath(filePath, projectDir) {
+  if (!filePath) return true;
+  const rel = filePath.startsWith(projectDir)
+    ? filePath.slice(projectDir.length).replace(/^[/\\]/, '')
+    : filePath;
+  return EXEMPT_PATTERNS.some(p => p.test(rel));
+}
+
+/**
+ * Check content for style violations.
+ * @returns {{ violations: string[], hasDash: boolean, hasEmoji: boolean }}
+ */
+function checkStyle(content) {
+  if (!content || typeof content !== 'string') return { violations: [], hasDash: false, hasEmoji: false };
+
+  const violations = [];
+  const hasDash = EM_DASH_PATTERN.test(content);
+  const hasEmoji = EMOJI_PATTERN.test(content);
+
+  if (hasDash) {
+    violations.push('Em-dash or en-dash detected. Use commas, semicolons, colons, or periods instead (Article V).');
+  }
+  if (hasEmoji) {
+    violations.push('Emoji detected. Use icons from approved libraries instead (Directive 1).');
+  }
+
+  return { violations, hasDash, hasEmoji };
+}
+
+/**
+ * Check bash command for style violations in commit messages / PR descriptions.
+ */
+function checkBashStyle(command) {
+  if (!command) return { violations: [], hasDash: false, hasEmoji: false };
+
+  // Only check git commit and PR commands
+  const isGitOutput = /git\s+commit|gh\s+pr\s+create/i.test(command);
+  if (!isGitOutput) return { violations: [], hasDash: false, hasEmoji: false };
+
+  return checkStyle(command);
+}
+
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  try {
+    const event = JSON.parse(input);
+    const projectDir = event.cwd || process.cwd();
+    const toolName = event.tool_name || '';
+    const toolInput = event.tool_input || {};
+
+    // Skip exempt paths
+    const filePath = toolInput.file_path || '';
+    if (isExemptPath(filePath, projectDir)) {
+      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      return;
+    }
+
+    let result = { violations: [], hasDash: false, hasEmoji: false };
+
+    if (toolName === 'Write' || toolName === 'Edit') {
+      const content = toolInput.content || toolInput.new_string || '';
+      result = checkStyle(content);
+    } else if (toolName === 'Bash') {
+      const command = toolInput.command || '';
+      result = checkBashStyle(command);
+    }
+
+    if (result.violations.length > 0) {
+      process.stdout.write(JSON.stringify({
+        decision: 'allow',
+        reason: `[Style Guard] ${result.violations.join(' ')}`,
+      }));
+      return;
+    }
+
+    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+  } catch (err) {
+    process.stderr.write(`[chati] style-guard: ${err.message}\n`);
+    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+  }
+}
+
+export { checkStyle, checkBashStyle, isExemptPath, EM_DASH_PATTERN, EMOJI_PATTERN };
+
+import { fileURLToPath } from 'url';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main();
+}

package/framework/hooks/undercover-guard.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * Undercover Guard Hook — PreToolUse (Write/Edit/Bash)
+ *
+ * Inspired by Claude Code's Undercover Mode: automatically sanitizes
+ * internal chati.dev references from generated code, commits, and PRs
+ * so end-user deliverables don't expose framework internals.
+ *
+ * Purpose: When users ship code to clients, open-source, or production,
+ * their outputs should look like professional developer work — not
+ * reveal the orchestration framework behind it.
+ *
+ * What gets sanitized:
+ *   - Agent names (greenfield-wu, brownfield-wu, qa-planning, etc.)
+ *   - Pipeline terminology (PRISM, L0-L5, deviation protocol)
+ *   - Internal paths (chati.dev/artifacts/, .chati/)
+ *   - Framework name references in generated code/commits
+ *   - Constitution/Article references
+ *   - Quality gate internals (adversarial review, devil's advocate)
+ *
+ * What is NOT sanitized:
+ *   - Files inside chati.dev/ directory (framework's own files)
+ *   - Files inside .chati/ directory (session state)
+ *   - User's CLAUDE.md (framework context file)
+ *   - Hook files themselves
+ *
+ * Mode: Advisory (warn, not block). Injects cleaned content suggestion
+ * but does NOT block the operation. The agent should self-correct.
+ *
+ * Activation: Always active during BUILD and DEPLOY phases.
+ * Can be disabled via config.yaml: undercover_mode: false
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Internal terms that should not appear in user-facing deliverables.
+ * Each entry: { pattern: RegExp, replacement: string, category: string }
+ */
+const UNDERCOVER_RULES = [
+  // Agent names → generic descriptions
+  { pattern: /\bgreenfield-wu\b/gi, replacement: 'discovery analysis', category: 'agent' },
+  { pattern: /\bbrownfield-wu\b/gi, replacement: 'codebase analysis', category: 'agent' },
+  { pattern: /\bqa-planning\b/gi, replacement: 'planning review', category: 'agent' },
+  { pattern: /\bqa-implementation\b/gi, replacement: 'code review', category: 'agent' },
+  { pattern: /\bdevops agent\b/gi, replacement: 'deployment', category: 'agent' },
+  { pattern: /\bdev agent\b/gi, replacement: 'implementation', category: 'agent' },
+  { pattern: /\bbrief agent\b/gi, replacement: 'requirements analysis', category: 'agent' },
+  { pattern: /\bdetail agent\b/gi, replacement: 'specification', category: 'agent' },
+  { pattern: /\barchitect agent\b/gi, replacement: 'architecture design', category: 'agent' },
+  { pattern: /\bux agent\b/gi, replacement: 'UX design', category: 'agent' },
+  { pattern: /\bphases agent\b/gi, replacement: 'roadmap planning', category: 'agent' },
+  { pattern: /\btasks agent\b/gi, replacement: 'task breakdown', category: 'agent' },
+
+  // Pipeline terminology
+  { pattern: /\bPRISM (?:engine|context|L[0-5])\b/gi, replacement: 'context system', category: 'pipeline' },
+  { pattern: /\bdeviation protocol\b/gi, replacement: 'change request', category: 'pipeline' },
+  { pattern: /\btwo-layer handoff\b/gi, replacement: 'transition document', category: 'pipeline' },
+  { pattern: /\bhandoff document\b/gi, replacement: 'transition document', category: 'pipeline' },
+  { pattern: /\bcontext bracket\b/gi, replacement: 'context status', category: 'pipeline' },
+  { pattern: /\bquality gate\b/gi, replacement: 'quality check', category: 'pipeline' },
+  { pattern: /\badversarial review\b/gi, replacement: 'critical review', category: 'pipeline' },
+  { pattern: /\bdevil'?s advocate\b/gi, replacement: 'critical analysis', category: 'pipeline' },
+  { pattern: /\bRalph Wiggum\b/gi, replacement: 'autonomous mode', category: 'pipeline' },
+
+  // Framework references in generated content
+  { pattern: /\bchati\.dev(?:\/|\s|$)/gi, replacement: 'framework ', category: 'framework' },
+  { pattern: /\bchati-dev\b/gi, replacement: 'framework', category: 'framework' },
+  { pattern: /\bConstitution Article [IVXLC]+\b/gi, replacement: 'governance rule', category: 'framework' },
+  { pattern: /\bArticle [IVXLC]+(?:\s*[-:]\s*\w+)/gi, replacement: 'governance rule', category: 'framework' },
+
+  // Internal paths in comments/strings
+  { pattern: /chati\.dev\/artifacts\/\S+/gi, replacement: 'project artifacts', category: 'path' },
+  { pattern: /\.chati\/memories\/\S+/gi, replacement: 'project memory', category: 'path' },
+  { pattern: /\.chati\/session\.yaml/gi, replacement: 'session state', category: 'path' },
+
+  // Blocker taxonomy (internal codes)
+  { pattern: /\b[CG]\d{2}\s*[-:]\s*/gi, replacement: '', category: 'internal' },
+];
+
+/**
+ * Paths that are exempt from undercover sanitization.
+ * These are the framework's own files — internal references are expected.
+ */
+const EXEMPT_PATH_PATTERNS = [
+  /^chati\.dev\//,
+  /^\.chati\//,
+  /^\.claude\//,
+  /CLAUDE\.md$/,
+  /CLAUDE\.local\.md$/,
+  /GEMINI\.md$/,
+  /AGENTS\.md$/,
+];
+
+/**
+ * Check if a file path is exempt from undercover sanitization.
+ */
+function isExemptPath(filePath, projectDir) {
+  if (!filePath) return true;
+  const relative = filePath.startsWith(projectDir)
+    ? filePath.slice(projectDir.length).replace(/^[/\\]/, '')
+    : filePath;
+  return EXEMPT_PATH_PATTERNS.some(p => p.test(relative));
+}
+
+/**
+ * Check if undercover mode is enabled.
+ * Default: true (enabled). Disable via config.yaml undercover_mode: false
+ */
+function isUndercoverEnabled(projectDir) {
+  try {
+    const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+    if (!existsSync(configPath)) return true;
+    const raw = readFileSync(configPath, 'utf-8');
+    const match = raw.match(/^\s*undercover_mode:\s*(false|no|off|0)/mi);
+    return !match;
+  } catch { /* expected: config may not exist — default to enabled */
+    return true;
+  }
+}
+
+/**
+ * Scan content for internal references and return findings.
+ * @param {string} content - Text to scan
+ * @returns {{ found: boolean, matches: Array<{term: string, category: string}> }}
+ */
+function scanForInternals(content) {
+  if (!content || typeof content !== 'string') return { found: false, matches: [] };
+
+  const matches = [];
+  const seen = new Set();
+
+  for (const rule of UNDERCOVER_RULES) {
+    // Create fresh regex to avoid shared lastIndex state issues
+    const match = new RegExp(rule.pattern.source, rule.pattern.flags).exec(content);
+    if (match) {
+      const term = match[0];
+      if (!seen.has(term.toLowerCase())) {
+        seen.add(term.toLowerCase());
+        matches.push({ term, category: rule.category, replacement: rule.replacement });
+      }
+    }
+  }
+
+  return { found: matches.length > 0, matches };
+}
+
+/**
+ * Check if a bash command contains internal references (commit messages, PR descriptions).
+ */
+function scanBashForInternals(command) {
+  if (!command) return { found: false, matches: [] };
+
+  // Only check git commit and PR-related commands
+  const isGitOutput = /git\s+(commit|push|pr|pull-request)|gh\s+(pr|issue)\s+create/i.test(command);
+  if (!isGitOutput) return { found: false, matches: [] };
+
+  return scanForInternals(command);
+}
+
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  try {
+    const event = JSON.parse(input);
+    const projectDir = event.cwd || process.cwd();
+    const toolName = event.tool_name || '';
+    const toolInput = event.tool_input || {};
+
+    // Check if undercover mode is enabled
+    if (!isUndercoverEnabled(projectDir)) {
+      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      return;
+    }
+
+    // Skip framework-internal files
+    const filePath = toolInput.file_path || '';
+    if (isExemptPath(filePath, projectDir)) {
+      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      return;
+    }
+
+    let scan = { found: false, matches: [] };
+
+    if (toolName === 'Write' || toolName === 'Edit') {
+      const content = toolInput.content || toolInput.new_string || '';
+      scan = scanForInternals(content);
+    } else if (toolName === 'Bash') {
+      const command = toolInput.command || '';
+      scan = scanBashForInternals(command);
+    }
+
+    if (scan.found) {
+      const terms = scan.matches.map(m => `"${m.term}" → "${m.replacement}"`).join(', ');
+      process.stdout.write(JSON.stringify({
+        decision: 'allow',  // Advisory — don't block, just warn
+        reason: `[Undercover] Internal references detected in output: ${terms}. Please sanitize before shipping to production. Replace internal terms with their generic equivalents.`,
+      }));
+      return;
+    }
+
+    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+  } catch (err) {
+    process.stderr.write(`[chati-hook-error] undercover-guard: ${err?.message || 'unknown'}\n`);
+    // Fail-open: undercover is advisory, not security-critical
+    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+  }
+}
+
+export { scanForInternals, scanBashForInternals, isExemptPath, isUndercoverEnabled, UNDERCOVER_RULES };
+
+// Only run main when executed directly (not imported by tests)
+import { fileURLToPath } from 'url';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main();
+}

package/framework/intelligence/context-engine.md

@@ -17,6 +17,14 @@ Four brackets define behavior based on remaining context:
 | **DEPLETED** | 25-40% | 3 layers (L0-L2). Heavy reinforcement (4.0%) — significant context loss. Chunk memory recovery. |
 | **CRITICAL** | <25% | 2 layers (L0-L1). Maximum reinforcement (5.0%) — last interactions before handoff. Full memory dump. |
 
+### Static/Dynamic PRISM Boundary
+
+The PRISM engine separates context into a **static prefix** (L0 Constitution + L1 Global rules) and a **dynamic suffix** (L2-L5, changes per turn). A `<!-- STATIC_BOUNDARY -->` marker separates them in the XML output.
+
+This enables prompt cache reuse — the static prefix is identical across turns within the same mode, so the LLM provider can cache it and only reprocess the dynamic portion.
+
+The static cache is invalidated when the governance mode changes (planning → build → deploy).
+
 ---
 
 ## Layered Context Injection
@@ -100,6 +108,19 @@ bracket = calculateBracket(100 - contextPercent)
 
 The orchestrator recalculates the bracket before each agent interaction and adjusts injection accordingly.
 
+### Token-Based Bracket Estimation
+
+Context remaining percentage is estimated from actual prompt content size rather than conversation turn count:
+
+```
+estimatedTokens = promptText.length / 4
+remainingPercent = (1 - estimatedTokens / providerLimit) * 100
+```
+
+This replaces the legacy heuristic (`turnCount / maxTurns`) which was inaccurate for sessions with large tool results or long agent outputs. The token-based approach scales correctly across providers (Claude 200K, Gemini 1M, Codex 128K).
+
+Fallback: If prompt text is unavailable, the turn-count heuristic is used.
+
 ---
 
 ## Autonomous Context Recovery

package/framework/intelligence/hooks-performance.md

@@ -0,0 +1,54 @@
+# Hook Performance Reference
+
+## Execution Model
+
+Each hook runs as a separate Node.js process via stdin/stdout JSON protocol.
+Hooks execute SEQUENTIALLY within the same event matcher.
+Claude Code spawns each hook as a child process, waits for JSON output, then proceeds.
+
+## Hook Registry (11 total)
+
+| Event | Matcher | Hook | Purpose |
+|-------|---------|------|---------|
+| UserPromptSubmit | `.*` | license-guard.js | License validation + session ping |
+| UserPromptSubmit | `.*` | prism-engine.js | Context injection (bracket, memory, frustration) |
+| UserPromptSubmit | `.*` | model-governance.js | Model assignment advisory |
+| PreCompact | `.*` | session-digest.js | Session state capture + auto-dream + daily digest |
+| PreToolUse | `Read` | read-protection.js | Block reading sensitive files |
+| PreToolUse | `Write\|Edit` | mode-governance.js | Write scope enforcement by phase |
+| PreToolUse | `Write\|Edit` | constitution-guard.js | Secret detection + 23 shell injection checks |
+| PreToolUse | `Write\|Edit` | undercover-guard.js | Sanitize framework terms from deliverables |
+| PreToolUse | `Write\|Edit` | style-guard.js | Em-dash and emoji enforcement |
+| PreToolUse | `Bash` | constitution-guard.js | Destructive command + shell injection checks |
+| PreToolUse | `Bash` | undercover-guard.js | Sanitize framework terms from git commits |
+| PreToolUse | `Bash` | style-guard.js | Em-dash and emoji in commit messages |
+
+## Latency Budget
+
+| Event | Hook Count | Expected Latency | Notes |
+|-------|-----------|-----------------|-------|
+| UserPromptSubmit | 3 | ~150ms | Runs before every user message |
+| PreCompact | 1 | ~50-200ms | Runs rarely (context compaction). Auto-dream may add 5-10s if triggered |
+| PreToolUse (Read) | 1 | ~30ms | Minimal overhead per file read |
+| PreToolUse (Write/Edit) | 4 | ~200ms | Heaviest path. 4 sequential hooks |
+| PreToolUse (Bash) | 3 | ~150ms | 23 regex checks in constitution-guard are negligible (<5ms) |
+
+## Performance Characteristics
+
+- **Fastest path**: Read (1 hook, ~30ms)
+- **Heaviest path**: Write/Edit (4 hooks, ~200ms)
+- **Most frequent**: UserPromptSubmit (3 hooks on every message)
+- **Rarest**: PreCompact (1 hook, only on context compaction)
+
+## Optimization Notes
+
+1. constitution-guard's 23 shell injection regex checks run in <5ms total (all patterns compiled once)
+2. undercover-guard and style-guard could be skipped in discover/plan phases (no code being written)
+3. If latency becomes noticeable, consider merging undercover-guard + style-guard into one hook (same event, similar logic)
+4. license-guard has a 5-minute ping throttle to avoid network latency on every message
+
+## When to Worry
+
+- If Write/Edit operations feel sluggish (>500ms added latency), profile hooks individually
+- If auto-dream triggers during PreCompact and takes >10s, consider increasing the trigger threshold from 100 to 150 entries
+- If UserPromptSubmit hooks add noticeable delay, license-guard's network call is the most likely culprit (has 3s timeout)