ctx-cc 3.5.0 → 4.1.0

package/commands/visual-qa.md

@@ -0,0 +1,559 @@
+---
+name: ctx:visual-qa
+description: Pixel-perfect visual QA — measurement-driven design parity, WCAG 2.2 AA accessibility audit, responsive matrix at 375/768/1440px. Uses Playwright + Figma MCP + Gemini.
+---
+
+<objective>
+Run a complete visual QA pass: extract design specs from Figma, measure rendered output in the browser, compute precision diffs, audit WCAG 2.2 AA compliance, and produce a correction report with specific file/property/value changes.
+</objective>
+
+<usage>
+```bash
+/ctx:visual-qa                          # Full QA — parity + a11y + responsive
+/ctx:visual-qa --component "Button"     # Single component QA
+/ctx:visual-qa --page "/login"          # Full page QA
+/ctx:visual-qa --a11y-only              # Accessibility audit only
+/ctx:visual-qa --parity-only            # Design parity only (no a11y)
+/ctx:visual-qa --baseline               # Save new baseline screenshots (before change)
+/ctx:visual-qa --regression             # Compare current state against baselines
+```
+</usage>
+
+<process>
+
+## Step 1: Environment Check
+
+```bash
+# Load app URL
+cat .ctx/.env 2>/dev/null | grep APP_URL || echo "APP_URL_MISSING"
+
+# Check for Figma file key
+cat .ctx/.env 2>/dev/null | grep FIGMA_FILE_KEY || echo "FIGMA_KEY_MISSING"
+
+# Check for BRAND_KIT.md (needed for spec context)
+ls BRAND_KIT.md 2>/dev/null && echo "BRAND_KIT_FOUND" || echo "BRAND_KIT_MISSING"
+
+# Ensure output directories exist
+mkdir -p .ctx/qa/visual .ctx/qa/baselines .ctx/qa/a11y
+```
+
+If APP_URL is missing:
+```
+APP_URL not found in .ctx/.env.
+
+Add it:
+  echo "APP_URL=http://localhost:3000" >> .ctx/.env
+
+Then re-run /ctx:visual-qa.
+```
+
+## Step 2: Collect QA Target
+
+If no flags provided, ask:
+
+```
+What do you want to QA?
+
+  Component name or page route:
+  > [e.g., "Button", "LoginForm", "/dashboard"]
+
+  Figma node ID (optional — enables spec extraction):
+  > [e.g., "1234:5678" or leave blank]
+
+  Scope:
+    A  Full QA (parity + a11y + responsive + Gemini)
+    B  Accessibility only
+    C  Design parity only
+    D  Responsive layout only
+    E  Regression check (compare against baselines)
+
+  > [A/B/C/D/E]
+```
+
+## Step 3: Navigate to Target
+
+```javascript
+// Load APP_URL from .ctx/.env
+const appUrl = process.env.APP_URL || 'http://localhost:3000';
+const targetPath = '<path from user input>';
+
+await mcp__playwright__browser_navigate({ url: `${appUrl}${targetPath}` });
+await mcp__playwright__browser_snapshot();
+```
+
+If authentication is required:
+```javascript
+// Check if redirected to login
+const snapshot = await mcp__playwright__browser_snapshot();
+if (snapshot.includes('/login') || snapshot.includes('Sign in')) {
+  // Load credentials from .ctx/.env
+  await mcp__playwright__browser_navigate({ url: `${appUrl}/login` });
+  await mcp__playwright__browser_type({ ref: 'email-input',    text: process.env.TEST_USER_EMAIL });
+  await mcp__playwright__browser_type({ ref: 'password-input', text: process.env.TEST_USER_PASSWORD });
+  await mcp__playwright__browser_click({ ref: 'submit-button' });
+  await mcp__playwright__browser_navigate({ url: `${appUrl}${targetPath}` });
+}
+```
+
+## Step 4: Design Parity Check
+
+### 4.1 Extract Figma Specs (if node ID provided)
+
+```javascript
+const designContext = await mcp__figma__get_design_context({
+  fileKey: process.env.FIGMA_FILE_KEY,
+  nodeId: figmaNodeId
+});
+
+const variables = await mcp__figma__get_variable_defs({
+  fileKey: process.env.FIGMA_FILE_KEY
+});
+
+// Save Figma reference screenshot
+await mcp__figma__get_screenshot({
+  fileKey: process.env.FIGMA_FILE_KEY,
+  nodeId: figmaNodeId
+});
+// Copy output to .ctx/qa/visual/figma-spec-[component].png
+```
+
+Build spec table from Figma context.
+
+### 4.2 Measure Rendered Output (All Breakpoints)
+
+Run at each breakpoint:
+
+```javascript
+const breakpoints = [
+  { name: 'mobile',  width: 375,  height: 812  },
+  { name: 'tablet',  width: 768,  height: 1024 },
+  { name: 'desktop', width: 1440, height: 900  }
+];
+
+for (const bp of breakpoints) {
+  await mcp__playwright__browser_resize({ width: bp.width, height: bp.height });
+  await mcp__playwright__browser_wait_for({ time: 0.3 });
+
+  const measurements = await mcp__playwright__browser_evaluate({
+    function: `
+      const el = document.querySelector('[data-testid="${selector}"]')
+               || document.querySelector('${cssSelector}');
+      if (!el) return { error: 'Element not found' };
+      const s = getComputedStyle(el);
+      const r = el.getBoundingClientRect();
+      return {
+        fontSize:        s.fontSize,         fontWeight:   s.fontWeight,
+        lineHeight:      s.lineHeight,        letterSpacing: s.letterSpacing,
+        fontFamily:      s.fontFamily,
+        paddingTop:      s.paddingTop,        paddingRight:  s.paddingRight,
+        paddingBottom:   s.paddingBottom,     paddingLeft:   s.paddingLeft,
+        marginTop:       s.marginTop,         marginBottom:  s.marginBottom,
+        width:           r.width,             height:        r.height,
+        minHeight:       s.minHeight,         minWidth:      s.minWidth,
+        backgroundColor: s.backgroundColor,  color:         s.color,
+        borderRadius:    s.borderRadius,      borderWidth:   s.borderWidth,
+        borderColor:     s.borderColor,       boxShadow:     s.boxShadow,
+        display:         s.display,           flexDirection: s.flexDirection,
+        gap:             s.gap,               alignItems:    s.alignItems
+      };
+    `
+  });
+
+  // Take screenshot at this breakpoint
+  await mcp__playwright__browser_take_screenshot({
+    filename: `.ctx/qa/visual/${component}-${bp.name}.png`
+  });
+
+  // Store measurements keyed by breakpoint
+  results[bp.name] = measurements;
+}
+```
+
+### 4.3 Generate Precision Diff Table
+
+For each breakpoint, compare measured values against Figma spec:
+
+```markdown
+## Precision Diff — [Component] — [Breakpoint]
+
+| Property | Spec | Rendered | Delta | Status |
+|----------|------|----------|-------|--------|
+| font-size | 16px | 16px | 0 | PASS |
+| font-weight | 600 | 600 | 0 | PASS |
+| min-height | 44px | 40px | -4px | FAIL |
+| border-radius | 8px | 6px | -2px | FAIL |
+| background-color | oklch(0.52 0.18 264) | rgb(46,120,227) | ~0 | PASS* |
+| padding-right | 16px | 16px | 0 | PASS |
+
+*Color values converted to same space for comparison.
+Tolerance: ±1px for dimensions. Exact match for weights and radii.
+```
+
+## Step 5: Accessibility Audit
+
+### WCAG 2.2 AA Automated Checks
+
+Navigate to target at desktop breakpoint (1440px), then run:
+
+**Color contrast:**
+```javascript
+const contrastViolations = await mcp__playwright__browser_evaluate({
+  function: `
+    function lum(str) {
+      const m = str.match(/rgb\\((\\d+),\\s*(\\d+),\\s*(\\d+)\\)/);
+      if (!m) return null;
+      return [m[1],m[2],m[3]].reduce((acc, v, i) => {
+        const s = parseInt(v)/255;
+        const lin = s <= 0.04045 ? s/12.92 : Math.pow((s+0.055)/1.055, 2.4);
+        return acc + lin * [0.2126,0.7152,0.0722][i];
+      }, 0);
+    }
+    function cr(a, b) {
+      const l = [lum(a), lum(b)];
+      if (l.includes(null)) return null;
+      return ((Math.max(...l)+0.05)/(Math.min(...l)+0.05)).toFixed(2);
+    }
+    const fails = [];
+    document.querySelectorAll('*').forEach(el => {
+      const s = getComputedStyle(el);
+      if (!el.textContent.trim() || el.children.length > 0) return;
+      const ratio = parseFloat(cr(s.color, s.backgroundColor));
+      if (!ratio) return;
+      const fs = parseFloat(s.fontSize);
+      const fw = parseInt(s.fontWeight);
+      const large = fs >= 18 || (fs >= 14 && fw >= 700);
+      const req = large ? 3.0 : 4.5;
+      if (ratio < req) fails.push({
+        tag: el.tagName, text: el.textContent.trim().substring(0,40),
+        fg: s.color, bg: s.backgroundColor, ratio, required: req
+      });
+    });
+    return fails.slice(0, 50);
+  `
+});
+```
+
+**Touch targets (WCAG 2.2 SC 2.5.8):**
+```javascript
+const targetViolations = await mcp__playwright__browser_evaluate({
+  function: `
+    return [...document.querySelectorAll('a, button, input, select, textarea, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"]')]
+      .map(el => ({ el, r: el.getBoundingClientRect() }))
+      .filter(({ r }) => r.width < 24 || r.height < 24)
+      .map(({ el, r }) => ({
+        tag: el.tagName, role: el.getAttribute('role'),
+        text: (el.textContent || el.getAttribute('aria-label') || '').trim().substring(0,40),
+        w: Math.round(r.width), h: Math.round(r.height)
+      }));
+  `
+});
+```
+
+**Focus visibility:**
+```javascript
+const focusViolations = await mcp__playwright__browser_evaluate({
+  function: `
+    const fails = [];
+    [...document.querySelectorAll('a, button, input, select, [tabindex]:not([tabindex="-1"])')].slice(0, 50).forEach(el => {
+      el.focus();
+      const s = getComputedStyle(el);
+      const ow = parseFloat(s.outlineWidth);
+      const ring = s.boxShadow !== 'none' && s.boxShadow.includes('0 0 0');
+      if (ow < 2 && !ring) {
+        fails.push({ tag: el.tagName, text: el.textContent.trim().substring(0,40), outlineWidth: ow, boxShadow: s.boxShadow });
+      }
+      el.blur();
+    });
+    return fails;
+  `
+});
+```
+
+**Heading hierarchy:**
+```javascript
+const headingViolations = await mcp__playwright__browser_evaluate({
+  function: `
+    const hs = [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h => ({
+      level: +h.tagName[1], text: h.textContent.trim().substring(0,50)
+    }));
+    const fails = [];
+    for (let i = 1; i < hs.length; i++) {
+      if (hs[i].level - hs[i-1].level > 1)
+        fails.push({ from: 'h'+hs[i-1].level+': '+hs[i-1].text, to: 'h'+hs[i].level+': '+hs[i].text });
+    }
+    const h1s = hs.filter(h => h.level === 1).length;
+    if (h1s !== 1) fails.push({ issue: 'h1 count is '+h1s+' (must be 1)' });
+    return { structure: hs, violations: fails };
+  `
+});
+```
+
+**Image alt text:**
+```javascript
+const altViolations = await mcp__playwright__browser_evaluate({
+  function: `
+    return [...document.querySelectorAll('img')]
+      .filter(img => img.getAttribute('alt') === null)
+      .map(img => ({ src: img.src.substring(0,80), issue: 'Missing alt attribute' }));
+  `
+});
+```
+
+**ARIA names:**
+```javascript
+const ariaViolations = await mcp__playwright__browser_evaluate({
+  function: `
+    return [...document.querySelectorAll('button, [role="button"]')]
+      .filter(el => {
+        const text = el.textContent.trim();
+        const label = el.getAttribute('aria-label');
+        const lby = el.getAttribute('aria-labelledby');
+        return !text && !label && !lby;
+      })
+      .map(el => ({ tag: el.tagName, html: el.outerHTML.substring(0,100) }));
+  `
+});
+```
+
+### Accessibility Summary Table
+
+```markdown
+## WCAG 2.2 AA — Automated Audit
+
+| Criterion | Description | Violations | Status |
+|-----------|-------------|-----------|--------|
+| 1.1.1 Non-text Content | Alt text on images | {n} | PASS/FAIL |
+| 1.4.3 Contrast (Minimum) | Text 4.5:1 / Large text 3:1 | {n} | PASS/FAIL |
+| 2.4.7 Focus Visible | Focus indicator present | {n} | PASS/FAIL |
+| 2.5.8 Target Size | Interactive targets 24x24px | {n} | PASS/FAIL |
+| 3.1.2 Heading Hierarchy | No skipped heading levels | {n} | PASS/FAIL |
+| 4.1.2 Name, Role, Value | ARIA labels on icon elements | {n} | PASS/FAIL |
+
+WCAG 2.2 AA Score: {passing}/{total} criteria automated
+Manual checks required: 2.4.11 Focus Not Obscured, 2.5.7 Dragging Alternatives, 2.1.1 Keyboard
+```
+
+## Step 6: Gemini Design Analysis
+
+```javascript
+// Analyze desktop screenshot with Gemini
+const analysis = await mcp__gemini-design__gemini_analyze_design({
+  imagePath: `.ctx/qa/visual/${component}-desktop.png`,
+  prompt: `
+    You are a senior product designer reviewing a UI screenshot.
+    Evaluate each area precisely. No vague feedback.
+
+    1. VISUAL HIERARCHY (1-5)
+       Does the eye move naturally through the content?
+       What is the focal point? Is it correct?
+
+    2. SPACING CONSISTENCY (1-5)
+       Is spacing uniform and following a grid?
+       List any specific spacing inconsistencies with pixel estimates.
+
+    3. TYPOGRAPHY SCALE (1-5)
+       Do font sizes create clear hierarchy?
+       Are line heights appropriate for readability?
+
+    4. COLOR HARMONY (1-5)
+       Do colors complement each other?
+       Any jarring contrast issues beyond accessibility requirements?
+
+    5. ALIGNMENT (1-5)
+       Are elements aligned to a consistent grid?
+       Any orphaned or misaligned elements?
+
+    6. OVERALL POLISH (1-5)
+       Does this feel production-ready or prototype-level?
+
+    Format each as:
+    Rating: X/5
+    Observation: [specific observation]
+    Fix: [exact action to take, or "none needed"]
+  `
+});
+```
+
+## Step 7: Regression Check (--regression flag)
+
+```javascript
+const breakpoints = ['mobile', 'tablet', 'desktop'];
+
+for (const bp of breakpoints) {
+  // Take current screenshot
+  await mcp__playwright__browser_resize({
+    width: { mobile: 375, tablet: 768, desktop: 1440 }[bp],
+    height: { mobile: 812, tablet: 1024, desktop: 900 }[bp]
+  });
+  await mcp__playwright__browser_take_screenshot({
+    filename: `.ctx/qa/visual/${component}-${bp}-current.png`
+  });
+
+  // Compare against baseline with Gemini
+  const diff = await mcp__gemini-design__gemini_analyze_design({
+    images: [
+      `.ctx/qa/baselines/${component}-${bp}-baseline.png`,
+      `.ctx/qa/visual/${component}-${bp}-current.png`
+    ],
+    prompt: `
+      Compare these two screenshots: [0] is the baseline, [1] is current.
+      List only UNINTENDED visual differences (regressions, not intentional changes).
+      For each difference:
+        - Element affected
+        - What changed (size, color, position, visibility)
+        - Severity: minor (cosmetic) or major (layout/functional)
+      If identical or only intentional changes, say "No regressions detected."
+    `
+  });
+
+  regressionResults[bp] = diff;
+}
+```
+
+## Step 8: Save Baseline (--baseline flag)
+
+```javascript
+for (const bp of breakpoints) {
+  await mcp__playwright__browser_resize({ width: bp.width, height: bp.height });
+  await mcp__playwright__browser_take_screenshot({
+    filename: `.ctx/qa/baselines/${component}-${bp.name}-baseline.png`
+  });
+}
+console.log('Baselines saved to .ctx/qa/baselines/');
+```
+
+## Step 9: Write QA Report
+
+Write to `.ctx/qa/VISUAL_QA_REPORT.md`:
+
+```markdown
+# Visual QA Report
+
+**Target:** [component or page]
+**Date:** [ISO-8601]
+**App URL:** [URL]
+**Figma Node:** [ID or "not provided"]
+**Breakpoints:** 375px / 768px / 1440px
+
+---
+
+## Executive Summary
+
+| Check | Result | Issues |
+|-------|--------|--------|
+| Design Parity | PASS/FAIL | {n} deltas |
+| Accessibility | PASS/FAIL | {n} violations |
+| Responsive Layout | PASS/FAIL | {n} issues |
+| Visual Regression | PASS/FAIL | {n} regressions |
+| Gemini Design Score | {n}/5 | [summary] |
+
+**Overall: PASS / FAIL**
+
+---
+
+## Design Parity
+
+### Mobile 375px
+[precision diff table]
+
+### Tablet 768px
+[precision diff table]
+
+### Desktop 1440px
+[precision diff table]
+
+---
+
+## Accessibility Audit
+[full WCAG 2.2 AA table + violation details]
+
+---
+
+## Gemini Design Analysis
+[structured feedback per category]
+
+---
+
+## Regression Analysis
+[diff results per breakpoint]
+
+---
+
+## Corrections Required
+
+Developer action items — apply in order:
+
+| # | File | Property | Current | Change To |
+|---|------|----------|---------|-----------|
+| 1 | src/components/Button.tsx:24 | fontSize | 14px | 16px |
+| 2 | src/components/Button.tsx:30 | minHeight | 40px | 44px |
+| 3 | src/components/Button.css:12 | border-radius | 6px | 8px |
+| 4 | src/components/Button.tsx:18 | focus outline | missing | add outline 2px solid var(--color-interactive-focus) |
+
+---
+
+## Screenshots
+
+.ctx/qa/visual/
+├── [component]-mobile.png
+├── [component]-tablet.png
+├── [component]-desktop.png
+└── figma-spec-[component].png (if Figma node provided)
+```
+
+## Step 10: Update STATE.json
+
+```bash
+python3 -c "
+import json
+from datetime import datetime
+
+with open('.ctx/STATE.json', 'r') as f:
+    state = json.load(f)
+
+state.setdefault('visualQA', {})
+state['visualQA']['lastRun'] = datetime.utcnow().isoformat() + 'Z'
+state['visualQA']['target'] = '$TARGET'
+state['visualQA']['reportPath'] = '.ctx/qa/VISUAL_QA_REPORT.md'
+state['visualQA']['pass'] = $OVERALL_PASS
+
+with open('.ctx/STATE.json', 'w') as f:
+    json.dump(state, f, indent=2)
+"
+```
+
+</process>
+
+<output>
+```
+[CTX VISUAL QA]
+
+Target: [component or page]
+App URL: [URL]
+Figma Node: [ID or not provided]
+
+Running: parity check + accessibility + responsive + Gemini
+
+Mobile  375px  → [PASS/FAIL] {n} deltas
+Tablet  768px  → [PASS/FAIL] {n} deltas
+Desktop 1440px → [PASS/FAIL] {n} deltas
+
+Accessibility (WCAG 2.2 AA):
+  Contrast violations:     {n}
+  Touch target violations: {n}
+  Focus indicator gaps:    {n}
+  Heading hierarchy:       {n}
+  Alt text missing:        {n}
+  ARIA name missing:       {n}
+
+Gemini design score: {n}/5
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+VISUAL QA: [PASS / FAIL]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Corrections required: {n}
+Report: .ctx/qa/VISUAL_QA_REPORT.md
+Screenshots: .ctx/qa/visual/
+```
+</output>

package/commands/voice.md

@@ -4,7 +4,7 @@ description: Voice control for CTX - speak your requirements and commands using
 ---
 
 <objective>
-CTX 3.3 Voice Control - Speak your requirements instead of typing. Natural language processing converts speech to CTX commands and story descriptions.
+CTX 4.0 Voice Control - Speak your requirements instead of typing. Natural language processing converts speech to CTX commands and story descriptions.
 </objective>
 
 <usage>

package/hooks/post-tool-use.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+/**
+ * CTX PostToolUse Hook
+ * Runs after tool execution. Logs file modifications for audit trail.
+ * Installed to .claude/hooks/ctx-post-tool-use.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const ctxDir = path.join(process.cwd(), '.ctx');
+const auditLog = path.join(ctxDir, 'audit.log');
+
+// Read hook input from stdin
+let input = {};
+try {
+  const stdin = fs.readFileSync('/dev/stdin', 'utf-8');
+  if (stdin) input = JSON.parse(stdin);
+} catch {
+  process.exit(0);
+}
+
+const toolName = input.tool_name || '';
+const toolInput = input.tool_input || '';
+
+// Log file modifications for audit trail
+if (['Write', 'Edit'].includes(toolName) && fs.existsSync(ctxDir)) {
+  const filePath = typeof toolInput === 'object' ? toolInput.file_path : '';
+  if (filePath) {
+    try {
+      fs.appendFileSync(auditLog,
+        `${new Date().toISOString()} | ${toolName} | ${filePath}\n`
+      );
+    } catch {
+      // Non-fatal
+    }
+  }
+}

package/hooks/pre-tool-use.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * CTX PreToolUse Hook
+ * Enforces TDD mode and capability restrictions.
+ * Installed to .claude/hooks/ctx-pre-tool-use.js
+ *
+ * Reads hook input from stdin (JSON with tool_name, tool_input, agent_name).
+ * Exit 0 = allow, Exit 2 = block.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+const ctxDir = path.join(process.cwd(), '.ctx');
+
+// Read hook input from stdin
+let input = {};
+try {
+  const chunks = [];
+  const stdin = fs.readFileSync('/dev/stdin', 'utf-8');
+  if (stdin) input = JSON.parse(stdin);
+} catch {
+  // No stdin or invalid JSON — allow
+  process.exit(0);
+}
+
+const toolName = input.tool_name || '';
+const toolInput = input.tool_input || '';
+const agentName = input.agent_name || '';
+
+// --- TDD Enforcement ---
+if (toolName === 'Bash' && /git commit/.test(toolInput)) {
+  const tddMode = loadConfig('hooks.tddMode', 'off');
+
+  if (tddMode !== 'off') {
+    try {
+      const diff = execSync('git diff --cached --name-only', { encoding: 'utf-8', timeout: 5000 });
+      const files = diff.trim().split('\n').filter(Boolean);
+      const hasCode = files.some(f => /\.(js|ts|jsx|tsx|py|go|rs|rb|java|cs)$/.test(f) && !/\.(test|spec)\.|__tests__/.test(f));
+      const hasTest = files.some(f => /\.(test|spec)\.|__tests__/.test(f));
+
+      if (hasCode && !hasTest) {
+        if (tddMode === 'strict') {
+          process.stderr.write('CTX TDD: Commit blocked — code changes without tests.\n');
+          process.stderr.write('Files: ' + files.filter(f => /\.(js|ts|jsx|tsx|py|go|rs)$/.test(f)).join(', ') + '\n');
+          process.exit(2);
+        } else if (tddMode === 'warn') {
+          process.stderr.write('CTX TDD Warning: Code changes without corresponding tests.\n');
+        }
+      }
+    } catch {
+      // Git not available — skip check
+    }
+  }
+}
+
+// --- Capability Enforcement ---
+if (agentName && agentName.startsWith('ctx-')) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  try {
+    if (fs.existsSync(manifestPath)) {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      for (const [category, cfg] of Object.entries(manifest)) {
+        if (category.startsWith('_')) continue; // skip metadata keys like _version
+        if (cfg?.agents?.includes(agentName + '.md') && cfg.denied.includes(toolName)) {
+          process.stderr.write(`CTX: Tool "${toolName}" blocked for ${category} agent "${agentName}".\n`);
+          fs.appendFileSync(
+            path.join(ctxDir, 'violations.log'),
+            `${new Date().toISOString()} | ${agentName} | ${toolName} | BLOCKED\n`
+          );
+          process.exit(2);
+        }
+      }
+    }
+  } catch {
+    // Manifest not found or invalid — allow
+  }
+}
+
+process.exit(0);
+
+// --- Helpers ---
+
+function loadConfig(key, defaultValue) {
+  try {
+    const configPath = path.join(ctxDir, 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return key.split('.').reduce((o, k) => o?.[k], config) ?? defaultValue;
+  } catch {
+    return defaultValue;
+  }
+}