chati-dev 4.2.1 → 4.3.0

package/framework/hooks/advance-trigger.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Advance Trigger Hook — PostToolUse (runs after each Write tool call)
+ *
+ * Autonomous pipeline advance: when an agent writes its handoff file,
+ * this hook detects it and fires `chati-router.js advance` in the background
+ * so session.yaml, Magic Docs, and the next agent activation happen
+ * deterministically — without depending on Claude remembering to call advance.
+ *
+ * Trigger condition: the Write tool just wrote a file at
+ *   artifacts/handoffs/<agent>-handoff.md
+ * where the handoff's YAML frontmatter declares `status: completed` and
+ * contains `score: <N>`.
+ *
+ * The hook is observational — it always returns `{}` (no permission decision)
+ * and never blocks the tool call. The router is spawned detached with stdio
+ * ignored so it outlives the hook process.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { spawn } from 'child_process';
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+function extractFrontmatter(markdown) {
+  if (!markdown.startsWith('---')) return null;
+  const end = markdown.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const fm = markdown.slice(3, end + 1);
+  const fields = {};
+  for (const line of fm.split('\n')) {
+    const m = line.match(/^([a-zA-Z_][\w-]*):\s*(.+)$/);
+    if (m) fields[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fields;
+}
+
+async function main() {
+  let input;
+  try {
+    input = JSON.parse(await readStdin() || '{}');
+  } catch {
+    process.stdout.write('{}\n');
+    return;
+  }
+
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || '';
+  const cwd = input.cwd || process.cwd();
+
+  // Observational default — always allow the tool call through.
+  process.stdout.write('{}\n');
+
+  if (toolName !== 'Write') return;
+  if (!filePath) return;
+
+  // Match agent handoff files in either layout:
+  //   <root>/artifacts/handoffs/<agent>-handoff.md
+  //   <root>/.chati.dev/artifacts/handoffs/<agent>-handoff.md
+  const handoffMatch = filePath.match(/artifacts\/handoffs\/([a-z0-9-]+)-handoff\.md$/);
+  if (!handoffMatch) return;
+  const agent = handoffMatch[1];
+
+  // Load execution_mode from session to decide firing policy (Article XVII).
+  //
+  // Firing policy (v4.3.1):
+  // - autonomous: always fire (as before)
+  // - interactive (default): fire ONLY when the handoff is a QA agent
+  //   that failed its threshold (score below cutoff) OR verdict is
+  //   NEEDS_FIX/REJECTED. Correction loops are an INTERNAL quality process
+  //   (Fault Vector Protocol, Article XXII), not a forward step.
+  const sessionPath = join(cwd, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) return;
+  let raw;
+  try { raw = readFileSync(sessionPath, 'utf-8'); } catch { return; }
+  const modeMatch = raw.match(/^\s*execution_mode:\s*(.+)$/m);
+  const profile = modeMatch ? modeMatch[1].trim().replace(/^["']|["']$/g, '') : 'interactive';
+
+  // Read the written handoff and check its frontmatter declares completion.
+  if (!existsSync(filePath)) return;
+  let content;
+  try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+  const fm = extractFrontmatter(content);
+  if (!fm) return;
+  if ((fm.status || '').toLowerCase() !== 'completed' && (fm.status || '').toLowerCase() !== 'complete') return;
+  const score = parseInt(fm.score, 10);
+  if (isNaN(score)) return;
+  if ((fm.agent || agent) !== agent) return;
+
+  // Decide whether to fire under interactive mode.
+  if (profile !== 'autonomous') {
+    const QA_THRESHOLDS = { 'qa-planning': 95, 'qa-implementation': 95, 'qa-visual': 90 };
+    const threshold = QA_THRESHOLDS[agent];
+    const isQA = threshold !== undefined;
+    const verdict = (fm.verdict || '').toUpperCase();
+    const qaFailed = isQA && (
+      score < threshold ||
+      verdict === 'NEEDS_FIX' ||
+      verdict === 'REJECTED'
+    );
+    if (!qaFailed) return;
+  }
+
+  // Locate the router relative to the project root.
+  // Prefer .chati.dev/ layout; fall back to legacy chati.dev/.
+  const fwCandidates = ['.chati.dev', 'chati.dev'];
+  let routerPath = null;
+  for (const fw of fwCandidates) {
+    const p = join(cwd, fw, 'orchestrator', 'chati-router.js');
+    if (existsSync(p)) { routerPath = p; break; }
+  }
+  if (!routerPath) return;
+
+  // Fire and forget: detach so the router outlives this hook process.
+  try {
+    const child = spawn('node', [routerPath, 'advance', '--agent', agent, '--score', String(score)], {
+      cwd,
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+  } catch { /* non-fatal */ }
+}
+
+main().catch(() => process.stdout.write('{}\n'));

package/framework/hooks/brief-validator.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Brief Validator Hook — PostToolUse (runs after Write tool)
+ *
+ * When brief-handoff.md is written, validates that brief-report.md exists
+ * and contains required fields. Writes warnings directly into the handoff
+ * if validation fails. Deterministic — replaces Brief's self-validation.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+async function main() {
+  let input;
+  try {
+    input = JSON.parse(await readStdin() || '{}');
+  } catch {
+    process.stdout.write('{}\n');
+    return;
+  }
+
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || '';
+  const cwd = input.cwd || process.cwd();
+
+  process.stdout.write('{}\n');
+
+  if (toolName !== 'Write') return;
+  if (!filePath.endsWith('handoffs/brief-handoff.md')) return;
+
+  // Validate brief-report.md
+  const reportCandidates = [
+    join(cwd, 'artifacts', '1-Brief', 'brief-report.md'),
+  ];
+  const reportPath = reportCandidates.find(p => existsSync(p));
+
+  const warnings = [];
+
+  if (!reportPath) {
+    warnings.push('brief-report.md NOT FOUND — handoff written without artifact');
+  } else {
+    const content = readFileSync(reportPath, 'utf-8');
+
+    if (!content.includes('visual_quality')) {
+      warnings.push('visual_quality field missing — downstream UX agent needs this to set quality bar');
+    }
+    if (content.includes('[TODO]') || content.includes('[TBD]')) {
+      warnings.push('Placeholders found ([TODO] or [TBD]) — report has incomplete sections');
+    }
+    if (content.length < 500) {
+      warnings.push(`brief-report.md is very short (${content.length} chars) — may be incomplete`);
+    }
+    // Check if visual_references URLs exist but captures section is missing
+    const hasUrls = content.match(/url:\s*["']?https?:\/\//);
+    if (hasUrls && !content.includes('Visual Reference Captures')) {
+      warnings.push('visual_references URLs found but Visual Reference Captures section missing — reference-trigger hook may not have fired');
+    }
+  }
+
+  if (warnings.length === 0) return;
+
+  // Append warnings to the handoff file
+  try {
+    let handoff = readFileSync(filePath, 'utf-8');
+    if (handoff.includes('## Brief Validation Warnings')) return; // idempotent
+
+    handoff += `\n\n## Brief Validation Warnings\n\n`;
+    handoff += `> Auto-generated by brief-validator hook. These are deterministic checks.\n\n`;
+    for (const w of warnings) {
+      handoff += `- ⚠ ${w}\n`;
+    }
+    writeFileSync(filePath, handoff, 'utf-8');
+  } catch { /* ignore */ }
+}
+
+main().catch(() => process.stdout.write('{}\n'));

package/framework/hooks/constitution-guard.js

@@ -72,19 +72,34 @@ async function main() {
 
   try {
     const event = JSON.parse(input);
+    const projectDir = event.cwd || process.cwd();
     const toolName = event.tool_name || '';
     const toolInput = event.tool_input || {};
 
+    // Integrity check: verify license-guard.js exists on disk.
+    // If someone deletes license-guard.js to bypass license enforcement,
+    // constitution-guard (which is a separate hook) catches it.
+    // Cross-hook verification = no single point of removal.
+    const { existsSync } = await import('fs');
+    const { join } = await import('path');
+    const fwDir = existsSync(join(projectDir, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
+    const licenseGuardPath = join(projectDir, fwDir, 'hooks', 'license-guard.js');
+    if (!existsSync(licenseGuardPath)) {
+      process.stdout.write(JSON.stringify(denyOutput(
+        'License enforcement file (license-guard.js) is missing. System integrity compromised. Reinstall with: npx chati-dev init'
+      )));
+      return;
+    }
+
     // Check Write/Edit operations for secrets
     if (toolName === 'Write' || toolName === 'Edit') {
       const content = toolInput.content || toolInput.new_string || '';
       const secrets = containsSecrets(content);
 
       if (secrets.length > 0) {
-        process.stdout.write(JSON.stringify({
-          decision: 'block',
-          reason: `[Article IV] Potential secret detected in file content. Pattern: ${secrets[0]}. Use environment variables instead.`,
-        }));
+        process.stdout.write(JSON.stringify(denyOutput(
+          `[Article IV] Potential secret detected in file content. Pattern: ${secrets[0]}. Use environment variables instead.`
+        )));
         return;
       }
     }
@@ -93,57 +108,89 @@ async function main() {
     if (toolName === 'Bash') {
       const command = toolInput.command || '';
       if (isDestructiveCommand(command)) {
-        process.stdout.write(JSON.stringify({
-          decision: 'block',
-          reason: `[Article IV] Destructive command detected: "${command.slice(0, 60)}...". This requires explicit user confirmation.`,
-        }));
+        // Advisory, not blocking — destructive commands should be confirmed
+        // by the user via Claude Code's permission prompt, not hard-blocked
+        // by the hook (which runs AFTER user approval and blocks anyway).
+        process.stdout.write(JSON.stringify(allowOutput(
+          `[Article IV] Destructive command: "${command.slice(0, 60)}..." — proceeding with user approval.`
+        )));
         return;
       }
 
-      // Run 23-point shell injection security checks
+      // Run 21-point shell injection security checks
       const injectionFindings = runShellInjectionChecks(command);
       if (injectionFindings.length > 0) {
         const critical = injectionFindings.filter(f => f.severity === 'critical');
         if (critical.length > 0) {
-          process.stdout.write(JSON.stringify({
-            decision: 'block',
-            reason: `[Article IV] Shell injection risk detected (${critical.length} critical): ${critical.map(f => f.id).join(', ')}. Command: "${command.slice(0, 60)}..."`,
-          }));
+          process.stdout.write(JSON.stringify(denyOutput(
+            `[Article IV] Shell injection risk detected (${critical.length} critical): ${critical.map(f => f.id).join(', ')}. Command: "${command.slice(0, 60)}..."`
+          )));
           return;
         }
-        // High/medium findings: allow with warning (advisory)
-        process.stdout.write(JSON.stringify({
-          decision: 'allow',
-          reason: `[Security Advisory] ${injectionFindings.length} shell security finding(s): ${injectionFindings.map(f => f.id).join(', ')}`,
-        }));
+        // High/medium findings: allow (advisory only, surfaced via reason)
+        process.stdout.write(JSON.stringify(allowOutput(
+          `[Security Advisory] ${injectionFindings.length} shell security finding(s): ${injectionFindings.map(f => f.id).join(', ')}`
+        )));
         return;
       }
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati-hook-error] constitution-guard: ${err?.message || 'unknown'}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Hook error — fail-closed for safety' }));
+    // Fail-open on hook errors: a broken hook should not block legitimate work.
+    // Real security checks above are explicit and run before this catch.
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+  if (reason) out.hookSpecificOutput.permissionDecisionReason = reason;
+  return out;
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 /**
- * 23-point shell injection security checks.
+ * 21-point shell injection security checks.
  * Inline implementation (hooks are standalone — no imports from src/).
  * Based on Claude Code's bashSecurity.ts patterns.
  */
-// SYNC: These 23 check IDs MUST match packages/chati-dev/src/security/bash-security.js
+// SYNC: These 21 check IDs MUST match packages/chati-dev/src/security/bash-security.js
 // Hooks are standalone (no imports from src/), so duplication is necessary.
 // If you update here, update bash-security.js too. Run: npm test to verify both.
+// Severity tiers:
+// - critical = block immediately (clearly malicious, no legitimate use)
+// - high/medium = advisory only (surfaced as reason, allowed). Used to be
+//   blocking, but several patterns produced too many false positives
+//   (e.g. SHELL_METACHARACTERS firing on every $(date), GIT_COMMIT_SUBSTITUTION
+//   firing on git commit -m "$(date)"). Critical patterns below are narrowly
+//   scoped to actually-dangerous shell injection vectors.
 const SHELL_INJECTION_CHECKS = [
-  { id: 'INCOMPLETE_COMMANDS', pattern: /[|&;]\s*$/, severity: 'high' },
+  { id: 'INCOMPLETE_COMMANDS', pattern: /[|&;]\s*$/, severity: 'medium' },
   { id: 'JQ_SYSTEM_FUNCTION', pattern: /jq\b.*\bsystem\s*\(/i, severity: 'critical' },
-  { id: 'JQ_FILE_ARGUMENTS', pattern: /jq\b.*--from-file|jq\b.*-f\s+[^|&;]+/i, severity: 'high' },
-  { id: 'OBFUSCATED_FLAGS', pattern: /\$[({].*[)}].*-/, severity: 'high' },
-  { id: 'SHELL_METACHARACTERS', pattern: /[`]|\$\(/, severity: 'critical' },
-  { id: 'DANGEROUS_VARIABLES', pattern: /(?:^|\s)(?:PATH|LD_PRELOAD|LD_LIBRARY_PATH|DYLD_INSERT_LIBRARIES|PYTHONPATH|NODE_PATH|RUBYLIB|PERL5LIB)\s*=/, severity: 'critical' },
-  { id: 'NEWLINES', pattern: /(?<!\\)\n.*(?:rm|curl|wget|chmod|chown|sudo|eval|exec)/, severity: 'high' },
-  { id: 'BACKSLASH_ESCAPED_WHITESPACE', pattern: /\\\s+(?:-|\/)/,severity: 'medium' },
+  { id: 'JQ_FILE_ARGUMENTS', pattern: /jq\b.*--from-file|jq\b.*-f\s+[^|&;]+/i, severity: 'medium' },
+  { id: 'OBFUSCATED_FLAGS', pattern: /\$[({].*[)}].*-/, severity: 'medium' },
+  // SHELL_METACHARACTERS removed: $() and backticks are normal substitution.
+  // Genuinely dangerous substitutions are caught by DANGEROUS_PATTERNS_COMMAND_SUBSTITUTION below.
+  { id: 'DANGEROUS_VARIABLES', pattern: /(?:^|\s)(?:LD_PRELOAD|LD_LIBRARY_PATH|DYLD_INSERT_LIBRARIES|PYTHONPATH|NODE_PATH|RUBYLIB|PERL5LIB)\s*=/, severity: 'critical' },
+  // PATH= removed from critical (legitimate `PATH=/foo:$PATH cmd` exists).
+  { id: 'NEWLINES', pattern: /(?<!\\)\n.*(?:rm|curl|wget|chmod|chown|sudo|eval|exec)/, severity: 'medium' },
+  { id: 'BACKSLASH_ESCAPED_WHITESPACE', pattern: /\\\s+(?:-|\/)/, severity: 'medium' },
   // eslint-disable-next-line no-control-regex
   { id: 'CONTROL_CHARACTERS', pattern: /[\x00-\x08\x0e-\x1f\x7f]/, severity: 'critical' },
   { id: 'UNICODE_WHITESPACE', pattern: /[\u200B-\u200F\u2028-\u202F\uFEFF\u00A0\u2060\u180E]/, severity: 'critical' },
@@ -151,13 +198,13 @@ const SHELL_INJECTION_CHECKS = [
   { id: 'DANGEROUS_PATTERNS_INPUT_REDIRECTION', pattern: /<\s*(?:\/etc\/(?:passwd|shadow|sudoers)|\/proc\/|~\/\.ssh\/|~\/\.aws\/)/, severity: 'critical' },
   { id: 'DANGEROUS_PATTERNS_OUTPUT_REDIRECTION', pattern: />\s*(?:\/etc\/|~\/\.ssh\/|~\/\.bashrc|~\/\.zshrc|~\/\.profile|~\/\.gitconfig)/, severity: 'critical' },
   { id: 'IFS_INJECTION', pattern: /\bIFS\s*=/, severity: 'critical' },
-  { id: 'BRACE_EXPANSION', pattern: /\{.*(?:rm|curl|wget|chmod|eval|exec|sudo).*[,}]/, severity: 'high' },
-  { id: 'GIT_COMMIT_SUBSTITUTION', pattern: /git\s+(?:commit|push|tag).*\$[({]/, severity: 'high' },
+  { id: 'BRACE_EXPANSION', pattern: /\{.*(?:rm|curl|wget|chmod|eval|exec|sudo).*[,}]/, severity: 'medium' },
+  // GIT_COMMIT_SUBSTITUTION removed: `git commit -m "$(date)"` is legitimate.
   { id: 'PROC_ENVIRON_ACCESS', pattern: /\/proc\/(?:self|\d+)\/(?:environ|cmdline|maps|mem)/, severity: 'critical' },
-  { id: 'MALFORMED_TOKEN_INJECTION', pattern: /\\x[0-9a-f]{2}|\\u[0-9a-f]{4}|\\[0-7]{3}/i, severity: 'high' },
+  { id: 'MALFORMED_TOKEN_INJECTION', pattern: /\\x[0-9a-f]{2}|\\u[0-9a-f]{4}|\\[0-7]{3}/i, severity: 'medium' },
   { id: 'MID_WORD_HASH', pattern: /\w#\w/, severity: 'medium' },
   { id: 'COMMENT_QUOTE_DESYNC', pattern: /#.*['"][^'"]*$/, severity: 'medium' },
-  { id: 'QUOTED_NEWLINE', pattern: /["'][^"']*\n[^"']*["']/, severity: 'high' },
+  { id: 'QUOTED_NEWLINE', pattern: /["'][^"']*\n[^"']*["']/, severity: 'medium' },
   { id: 'ZSH_DANGEROUS_COMMANDS', pattern: /\b(?:zmodload|sysopen|sysread|syswrite|zsystem|zselect|ztcp)\b/, severity: 'critical' },
   { id: 'BACKSLASH_ESCAPED_OPERATORS', pattern: /\\[|;&]/, severity: 'medium' },
 ];
@@ -176,8 +223,16 @@ function runShellInjectionChecks(command) {
 
 export { containsSecrets, isDestructiveCommand, runShellInjectionChecks, SECRET_PATTERNS, DESTRUCTIVE_COMMANDS, SHELL_INJECTION_CHECKS };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }