qualia-framework 3.1.0 → 3.2.1

package/bin/install.js

@@ -26,22 +26,22 @@ const DEFAULT_TEAM = {
   "QS-HASAN-02": {
     name: "Hasan",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-MOAYAD-03": {
     name: "Moayad",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-RAMA-04": {
     name: "Rama",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-SALLY-05": {
     name: "Sally",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
 };
 
@@ -208,6 +208,13 @@ async function main() {
       }
     }
   } catch {}
+  // v3.2.0: purge deprecated hooks from existing installs on upgrade.
+  // block-env-edit.js was retired — team now has full read/write on .env*.
+  const DEPRECATED_HOOKS = ["block-env-edit.js"];
+  for (const f of DEPRECATED_HOOKS) {
+    const p = path.join(hooksDest, f);
+    try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
+  }
   for (const file of fs.readdirSync(hooksSource)) {
     try {
       const dest = path.join(hooksDest, file);
@@ -521,12 +528,6 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "Edit|Write",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("block-env-edit.js"),
-            timeout: 5,
-            statusMessage: "⬢ Checking file permissions...",
-          },
           {
             type: "command",
             if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)",
@@ -572,7 +573,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-  ok("Hooks: session-start, auto-update, branch-guard, pre-push, block-env-edit, migration-guard, deploy-gate, pre-compact");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, pre-compact");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 

package/bin/qualia-ui.js

@@ -16,6 +16,7 @@
 //   done <N> <title> [commit]            — task line (completed)
 //   next <command>                       — "Run: /qualia-X" footer
 //   end <status> [next-command]          — closing banner with optional next
+//   update <current> <latest>            — sticky framework update banner
 
 const fs = require("fs");
 const path = require("path");
@@ -258,6 +259,19 @@ function cmdEnd(status, nextCmd) {
   console.log("");
 }
 
+function cmdUpdate(current, latest) {
+  if (!current || !latest) return;
+  console.log("");
+  console.log(`  ${YELLOW}${BOLD}▲${RESET} ${WHITE}${BOLD}QUALIA FRAMEWORK UPDATE AVAILABLE${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
+  console.log(`  ${pad(DIM + "Current" + RESET, 20)}${DIM}${current}${RESET}`);
+  console.log(`  ${pad(DIM + "Latest" + RESET, 20)}${GREEN}${BOLD}${latest}${RESET}`);
+  console.log(`  ${pad(DIM + "Update" + RESET, 20)}${TEAL}npx qualia-framework@latest install${RESET}`);
+  console.log(`  ${DIM2}${RULE}${RESET}`);
+  console.log(`  ${DIM}This notice shows every session until you update.${RESET}`);
+  console.log("");
+}
+
 // ─── Main ────────────────────────────────────────────────
 const [cmd, ...rest] = process.argv.slice(2);
 switch (cmd) {
@@ -276,9 +290,10 @@ switch (cmd) {
   case "done":     cmdDone(rest[0], rest[1], rest[2]); break;
   case "next":     cmdNext(rest.join(" ")); break;
   case "end":      cmdEnd(rest[0], rest.slice(1).join(" ")); break;
+  case "update":   cmdUpdate(rest[0], rest[1]); break;
   default:
     console.error(
-      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end> [args]`
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update> [args]`
     );
     process.exit(1);
 }

package/hooks/auto-update.js

@@ -66,6 +66,11 @@ try {
 
   // Fork the check-and-update into a detached background process so the hook
   // returns immediately and Claude Code is never blocked.
+  //
+  // OWNER: silent auto-install (unchanged behavior).
+  // EMPLOYEE: write a sticky notification file — session-start.js renders a
+  // banner every session until they run the update manually. Fawzi (OWNER)
+  // never sees the banner because his framework auto-updates ahead of it.
   const script = `
     const fs = require("fs");
     const path = require("path");
@@ -73,6 +78,7 @@ try {
     const CLAUDE_DIR = ${JSON.stringify(CLAUDE_DIR)};
     const LOCK_FILE = ${JSON.stringify(LOCK_FILE)};
     const CONFIG_FILE = ${JSON.stringify(CONFIG_FILE)};
+    const NOTIF_FILE = path.join(CLAUDE_DIR, ".qualia-update-available.json");
     const cfg = ${JSON.stringify(cfg)};
     try {
       fs.writeFileSync(LOCK_FILE, String(process.pid));
@@ -82,7 +88,7 @@ try {
         shell: process.platform === "win32",
       });
       const latest = ((r.stdout || "").trim());
-      if (!latest) { fs.unlinkSync(LOCK_FILE); process.exit(0); }
+      if (!latest) { try { fs.unlinkSync(LOCK_FILE); } catch {} process.exit(0); }
       const cmp = (a, b) => {
         const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
         for (let i = 0; i < 3; i++) {
@@ -92,13 +98,29 @@ try {
         return 0;
       };
       if (cmp(latest, cfg.version) > 0) {
-        // Silent update — pipe the install code via stdin
-        const child = spawnSync("npx", ["qualia-framework@latest", "install"], {
-          input: cfg.code + "\\n",
-          timeout: 120000,
-          stdio: ["pipe", "ignore", "ignore"],
-          shell: process.platform === "win32",
-        });
+        if (cfg.role === "OWNER") {
+          // Silent auto-install for OWNER — no notification banner ever shown.
+          spawnSync("npx", ["qualia-framework@latest", "install"], {
+            input: cfg.code + "\\n",
+            timeout: 120000,
+            stdio: ["pipe", "ignore", "ignore"],
+            shell: process.platform === "win32",
+          });
+          try { fs.unlinkSync(NOTIF_FILE); } catch {}
+        } else {
+          // EMPLOYEE: write sticky notification. session-start.js will render
+          // a visible banner every session until the employee runs the update.
+          try {
+            fs.writeFileSync(NOTIF_FILE, JSON.stringify({
+              current: cfg.version,
+              latest: latest,
+              detected_at: new Date().toISOString(),
+            }, null, 2));
+          } catch {}
+        }
+      } else {
+        // Already up to date — clear any stale notification file.
+        try { fs.unlinkSync(NOTIF_FILE); } catch {}
       }
     } catch {}
     try { fs.unlinkSync(LOCK_FILE); } catch {}

package/hooks/session-start.js

@@ -18,6 +18,7 @@ const HOME = os.homedir();
 const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
 const STATE_FILE = path.join(".planning", "STATE.md");
 const CONTINUE_HERE = ".continue-here.md";
+const NOTIF_FILE = path.join(HOME, ".claude", ".qualia-update-available.json");
 
 function runUi(...args) {
   if (!fs.existsSync(UI)) return;
@@ -65,7 +66,23 @@ function fallbackText() {
   }
 }
 
+function maybeRenderUpdateBanner() {
+  // EMPLOYEE-only sticky banner. auto-update.js writes NOTIF_FILE when a new
+  // version is detected; we render it every session until the user actually
+  // runs `npx qualia-framework@latest install`. The file is cleared by
+  // auto-update.js once the install completes or the version catches up.
+  if (!fs.existsSync(NOTIF_FILE) || !fs.existsSync(UI)) return;
+  try {
+    const notif = JSON.parse(fs.readFileSync(NOTIF_FILE, "utf8"));
+    if (notif && notif.current && notif.latest) {
+      runUi("update", notif.current, notif.latest);
+    }
+  } catch {}
+}
+
 try {
+  maybeRenderUpdateBanner();
+
   if (!fs.existsSync(UI)) {
     fallbackText();
   } else if (fs.existsSync(STATE_FILE)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/skills/qualia-optimize/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: qualia-optimize
+description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Use this skill whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --fix flags."
+---
+
+# Qualia Optimize — Deep Codebase + Planning Optimization
+
+Comprehensive optimization that reads BOTH `.planning/` docs AND the actual codebase. Never analyze one without the other.
+
+## Usage
+
+- `/qualia-optimize` — Full optimization (all 6 dimensions)
+- `/qualia-optimize --perf` — Performance only (queries, bundle, render, latency)
+- `/qualia-optimize --ui` — Frontend/design/UI only
+- `/qualia-optimize --backend` — Backend only (RLS, auth, queries, edge functions)
+- `/qualia-optimize --alignment` — Planning-code alignment check only
+- `/qualia-optimize --fix` — Auto-fix LOW/MEDIUM findings from existing OPTIMIZE.md
+
+## Process
+
+### Step 1: Parse Arguments
+
+Extract mode from $ARGUMENTS. Default to `full`.
+
+Supported modes: `full`, `perf`, `ui`, `backend`, `alignment`, `fix`.
+
+If `--fix`: skip to Step 9 (requires existing `.planning/OPTIMIZE.md`).
+
+### Step 2: Load Planning Context (MANDATORY — never skip)
+
+Read ALL of these (skip silently if file doesn't exist, but always attempt):
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"
+```
+
+```bash
+cat .planning/REQUIREMENTS.md 2>/dev/null || echo "NO_REQUIREMENTS"
+```
+
+```bash
+cat .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"
+```
+
+```bash
+cat .planning/STATE.md 2>/dev/null || echo "NO_STATE"
+```
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+Also read the rules:
+```bash
+cat ~/.claude/rules/frontend.md 2>/dev/null
+cat ~/.claude/rules/security.md 2>/dev/null
+```
+
+Store all content — you will inline it into agent prompts.
+
+**If NO planning docs exist at all**: warn the user but proceed. The optimization still works on raw codebase — it just can't check alignment.
+
+### Step 3: Discover Codebase
+
+```bash
+pwd && node -e "try{const p=require('./package.json');console.log(JSON.stringify({name:p.name,deps:Object.keys(p.dependencies||{}),devDeps:Object.keys(p.devDependencies||{})}))}catch(e){console.log('{}')}" 2>/dev/null
+```
+
+```bash
+git log --oneline -15 2>/dev/null
+```
+
+```bash
+git diff --stat HEAD~10..HEAD 2>/dev/null | tail -5
+```
+
+```bash
+# Project structure
+ls -d app/ src/ pages/ components/ lib/ actions/ hooks/ supabase/ types/ 2>/dev/null
+```
+
+Classify project type: `web` | `voice` | `mobile` | `agent` | `edge-functions` | `unknown`
+
+### Step 4: Spawn Wave 1 Agents (parallel)
+
+Based on mode, spawn agents in a **single message** with multiple Agent() calls.
+
+| Mode | Agents |
+|------|--------|
+| `full` | frontend-agent + backend-agent + performance-oracle (3 parallel) |
+| `perf` | performance-oracle only |
+| `ui` | frontend-agent only |
+| `backend` | backend-agent only |
+| `alignment` | general-purpose with alignment prompt |
+
+**CRITICAL**: Inline ALL planning context into each agent prompt. `@` references don't work across Agent() boundaries.
+
+#### Frontend Agent Prompt
+
+```
+Agent(
+  prompt="You are optimizing a project's frontend. Read the planning docs and codebase rules below, then analyze the actual code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+{DESIGN.md content}
+</planning>
+
+<rules>
+{rules/frontend.md content}
+</rules>
+
+<task>
+Analyze the frontend codebase for issues in these categories:
+
+1. **UI Quality**
+   - Loading states: every async operation should show a loading indicator
+   - Error states: every data-fetching component should handle errors gracefully
+   - Empty states: lists/tables should handle zero items with helpful messaging
+   - Responsive: check for fixed pixel widths on containers, missing breakpoint handling
+   - Accessibility: alt text on images, ARIA labels on interactive elements, keyboard navigation
+
+2. **Design Alignment**
+   - Compare actual components against DESIGN.md decisions (colors, typography, spacing)
+   - Check rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids or blue-purple gradients?
+   - Consistency: are the same patterns used throughout? (button styles, spacing, color usage)
+
+3. **Frontend Performance**
+   - Bundle: large library imports that could be tree-shaken or dynamically imported
+   - Images: using next/image? width/height set? lazy loading below fold?
+   - Fonts: using next/font? No render-blocking font loads?
+   - CSS: unused Tailwind classes? conflicting styles?
+   - Rendering: unnecessary re-renders, missing React.memo on list items, heavy computations in render
+
+For EVERY finding, output in this exact format:
+- **What**: [description]
+- **Where**: [file:line]
+- **Why**: [impact on users/performance]
+- **Fix**: [concrete fix suggestion]
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+</task>",
+  subagent_type="frontend-agent",
+  description="Frontend optimization analysis"
+)
+```
+
+#### Backend Agent Prompt
+
+```
+Agent(
+  prompt="You are optimizing a project's backend. Read the planning docs and security rules below, then analyze the actual code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+</planning>
+
+<rules>
+{rules/security.md content}
+</rules>
+
+<task>
+Analyze the backend codebase for issues:
+
+1. **Security**
+   - RLS: every Supabase table must have ROW LEVEL SECURITY enabled with policies
+   - Service role: grep for service_role key usage in client-side code (app/, components/, src/) — should be ZERO
+   - Auth: all mutations use server-side auth check (supabase.auth.getUser())
+   - Validation: input validated with Zod before database operations
+   - No dangerouslySetInnerHTML or eval()
+
+2. **Data Access Patterns**
+   - Server actions vs client mutations: data writes should use 'use server' actions, not direct Supabase client calls
+   - Proper error handling: try/catch with meaningful error messages
+   - Revalidation: revalidatePath/revalidateTag after mutations
+
+3. **Edge Functions** (if supabase/functions/ exists)
+   - Cold start optimization: bundle size, dependency count
+   - Error handling and logging
+   - CORS configuration
+   - Timeout protection (maxDuration)
+
+4. **API Quality**
+   - Rate limiting on public endpoints
+   - Proper HTTP status codes
+   - Consistent error response format
+
+For EVERY finding, output:
+- **What**: [description]
+- **Where**: [file:line]
+- **Why**: [impact]
+- **Fix**: [concrete suggestion]
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+</task>",
+  subagent_type="backend-agent",
+  description="Backend optimization analysis"
+)
+```
+
+#### Performance Oracle Prompt
+
+```
+Agent(
+  prompt="You are analyzing cross-cutting performance issues. Read the project context, then analyze the codebase.
+
+<planning>
+{PROJECT.md content}
+</planning>
+
+<task>
+Analyze for performance issues across the full stack:
+
+1. **Database Queries**
+   - N+1 queries: Supabase .from() calls inside loops or .map()
+   - Missing indexes: .eq()/.filter()/.order() columns without corresponding indexes in migrations
+   - Sequential queries that could be parallel (Promise.all)
+   - Over-fetching: SELECT * when only specific columns needed
+
+2. **API Latency**
+   - Sequential API calls from client that could be batched
+   - Missing caching (SWR/React Query stale times, HTTP cache headers)
+   - Large payloads without pagination
+
+3. **Bundle Size**
+   - Barrel exports (index.ts re-exporting everything) preventing tree-shaking
+   - Large libraries imported for single functions (lodash, moment)
+   - Missing dynamic imports for heavy components (charts, editors, maps)
+
+4. **Render Performance**
+   - Expensive computations in render path without useMemo
+   - Event handlers recreated on every render without useCallback
+   - Large lists without virtualization
+   - Context providers causing unnecessary re-renders
+
+For EVERY finding, output:
+- **What**: [description]
+- **Where**: [file:line]
+- **Why**: [performance impact, quantified if possible]
+- **Fix**: [concrete suggestion]
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+</task>",
+  subagent_type="performance-oracle",
+  description="Performance optimization analysis"
+)
+```
+
+### Step 5: Spawn Wave 2 Agent (after Wave 1 completes)
+
+After all Wave 1 agents return, spawn the architecture strategist with their combined findings:
+
+```
+Agent(
+  prompt="You are synthesizing optimization findings from 3 specialist agents. Look for cross-cutting architectural issues.
+
+<wave1_findings>
+{All findings from frontend-agent, backend-agent, performance-oracle}
+</wave1_findings>
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+</planning>
+
+<task>
+1. Identify patterns across findings — recurring issues that point to a structural problem
+2. Find coupling issues between frontend and backend
+3. Check for inconsistent patterns (e.g., some routes use server actions, others use API routes)
+4. Identify missing abstractions (same pattern repeated 3+ times)
+5. Check for dead code and unused exports
+
+Output:
+- **Structural findings** (architectural issues, not covered by Wave 1)
+- **Pattern consolidation** (where Wave 1 findings share a root cause)
+- Each finding in the same format: What/Where/Why/Fix/Severity
+</task>",
+  subagent_type="architecture-strategist",
+  description="Architecture synthesis"
+)
+```
+
+**Skip Wave 2 for single-mode runs** (`--perf`, `--ui`, `--backend`). Only run for `full` mode.
+
+### Step 6: Alignment Check (always runs in `full` and `alignment` modes)
+
+For `alignment` mode, this is the sole analysis. For `full` mode, run alongside Wave 1.
+
+Read REQUIREMENTS.md and ROADMAP.md. For each requirement marked "Complete" or mapped to a completed phase:
+
+```bash
+# Find completed requirements
+grep -E "Complete|✓" .planning/REQUIREMENTS.md 2>/dev/null
+```
+
+For each completed requirement:
+- Grep the codebase for evidence it actually exists (routes, components, API endpoints)
+- If not found: flag as "Claimed complete but not implemented"
+
+Then scan for orphan features:
+```bash
+# Find all routes/pages
+find app -name "page.tsx" -o -name "route.ts" 2>/dev/null
+# Find all API routes
+find app/api -name "route.ts" 2>/dev/null
+```
+
+Cross-reference with REQUIREMENTS.md — any route/feature NOT in requirements is flagged as "Undocumented feature".
+
+### Step 7: Collect and Score Findings
+
+After all agents return:
+1. Deduplicate (same file:line from multiple agents → keep the most detailed one)
+2. Sort by severity: CRITICAL first
+3. Group by dimension: Performance, Design Alignment, UI Quality, Backend, Frontend, Planning-Code Alignment, Architecture
+
+Count totals per severity.
+
+### Step 8: Write OPTIMIZE.md and Present Results
+
+Write to `.planning/OPTIMIZE.md`:
+
+```markdown
+---
+date: {YYYY-MM-DD HH:MM}
+mode: {full|perf|ui|backend|alignment}
+critical: {N}
+high: {N}
+medium: {N}
+low: {N}
+status: {clean|needs_attention|critical_issues}
+---
+
+# Optimization Report
+
+**Project:** {name} | **Mode:** {mode} | **Date:** {date}
+
+## Summary
+
+{2-3 sentence overview}
+
+{If status is clean: "No critical issues found. Project is in good shape."}
+
+## Critical Issues
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+
+## High Priority
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+
+## Medium Priority
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+
+## Low Priority
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+```
+
+Commit:
+```bash
+node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: optimization report ({mode} mode, {critical} critical)" --files .planning/OPTIMIZE.md
+```
+
+**Present results:**
+
+If CRITICAL findings exist:
+```
+{critical} critical issues found. Options:
+
+1. Create a fix phase in ROADMAP.md for critical + high findings
+2. Auto-fix LOW/MEDIUM findings: /qualia-optimize --fix
+3. Review full report: cat .planning/OPTIMIZE.md
+```
+
+If no CRITICAL:
+```
+Optimization complete. {total} findings ({high} high, {medium} medium, {low} low).
+Report: .planning/OPTIMIZE.md
+
+Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
+```
+
+### Step 9: --fix Mode
+
+When `--fix` is provided:
+
+1. Read existing `.planning/OPTIMIZE.md` — if not found, error: "Run /qualia-optimize first"
+2. Filter to LOW and MEDIUM findings only
+3. For each finding with a clear, safe fix:
+   - Read the target file
+   - Apply the fix
+   - Verify it doesn't break (npx tsc --noEmit if TypeScript)
+4. Update OPTIMIZE.md: mark fixed findings, recount severities
+5. Commit changes
+6. Report what was fixed and what remains
+
+**Never auto-fix CRITICAL or HIGH** — those require human judgment.
+
+### Step 10: Gap Phase Creation (if user selects option 1 from Step 8)
+
+If user wants a fix phase for critical issues:
+
+1. Read ROADMAP.md, find current phase number
+2. Insert a decimal phase: `Phase {N}.1: Optimization Fixes (INSERTED)`
+3. Map CRITICAL and HIGH findings as success criteria
+4. Update STATE.md
+5. Commit
+6. Suggest: "Fix phase created. Run `/qualia-plan {N}.1`"

package/tests/runner.js

@@ -806,7 +806,7 @@ waves: 1
 describe("Hooks", () => {
   it("all hooks pass syntax check", () => {
     const hooks = fs.readdirSync(HOOKS).filter(f => f.endsWith(".js"));
-    assert.ok(hooks.length >= 8, `Expected 8+ hooks, found ${hooks.length}`);
+    assert.ok(hooks.length >= 7, `Expected 7+ hooks, found ${hooks.length}`);
     for (const hook of hooks) {
       const r = spawnSync(process.execPath, ["--check", path.join(HOOKS, hook)], {
         encoding: "utf8", timeout: 5000,
@@ -880,49 +880,8 @@ describe("Hooks", () => {
     assert.equal(r.status, 0);
   });
 
-  // --- block-env-edit.js ---
-
-  it("block-env-edit blocks .env files", () => {
-    const r = runHook("block-env-edit.js", {
-      tool_input: { file_path: "/project/.env" },
-    });
-    assert.equal(r.status, 2);
-  });
-
-  it("block-env-edit blocks .env.local files", () => {
-    const r = runHook("block-env-edit.js", {
-      tool_input: { file_path: "/project/.env.local" },
-    });
-    assert.equal(r.status, 2);
-  });
-
-  it("block-env-edit blocks .env.production files", () => {
-    const r = runHook("block-env-edit.js", {
-      tool_input: { file_path: ".env.production" },
-    });
-    assert.equal(r.status, 2);
-  });
-
-  it("block-env-edit blocks Windows-style .env paths", () => {
-    const r = runHook("block-env-edit.js", {
-      tool_input: { file_path: "C:\\project\\.env.local" },
-    });
-    assert.equal(r.status, 2);
-  });
-
-  it("block-env-edit allows non-env files", () => {
-    const r = runHook("block-env-edit.js", {
-      tool_input: { file_path: "src/app.tsx" },
-    });
-    assert.equal(r.status, 0);
-  });
-
-  it("block-env-edit allows component files", () => {
-    const r = runHook("block-env-edit.js", {
-      tool_input: { file_path: "components/Footer.tsx" },
-    });
-    assert.equal(r.status, 0);
-  });
+  // block-env-edit.js was retired in v3.2.0 — team now has full read/write on
+  // .env* files. See CHANGELOG v3.2.0 and bin/install.js DEPRECATED_HOOKS.
 
   // --- pre-push.js ---
 
@@ -1756,12 +1715,12 @@ describe("install.js", () => {
     }
   });
 
-  it("8 hooks installed", () => {
+  it("7 hooks installed (block-env-edit removed in v3.2.0)", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
       runInstall("QS-FAWZI-01", tmpHome);
       const hooks = fs.readdirSync(path.join(tmpHome, ".claude", "hooks")).filter(f => f.endsWith(".js"));
-      assert.equal(hooks.length, 8);
+      assert.equal(hooks.length, 7);
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }

package/hooks/block-env-edit.js

@@ -1,52 +0,0 @@
-#!/usr/bin/env node
-// ~/.claude/hooks/block-env-edit.js — prevent editing .env files.
-// PreToolUse hook on Edit/Write tool calls. Reads tool input as JSON on stdin.
-// Exits 2 to BLOCK the tool call. Exits 0 to allow it.
-// Cross-platform (Windows/macOS/Linux).
-
-const fs = require("fs");
-
-const _traceStart = Date.now();
-
-function readInput() {
-  try {
-    const raw = fs.readFileSync(0, "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return {};
-  }
-}
-
-const input = readInput();
-const file = (input.tool_input && (input.tool_input.file_path || input.tool_input.command)) || "";
-
-// Match .env, .env.local, .env.production, .env.*, etc.
-// Normalize separators so Windows paths (C:\project\.env.local) also match.
-const normalized = String(file).replace(/\\/g, "/");
-
-function _trace(hookName, result, extra) {
-  try {
-    const os = require("os");
-    const path = require("path");
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
-    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
-    const entry = {
-      hook: hookName,
-      result,
-      timestamp: new Date().toISOString(),
-      duration_ms: Date.now() - _traceStart,
-      ...extra,
-    };
-    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
-    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
-  } catch {}
-}
-
-if (/\.env(\.|$)/.test(normalized)) {
-  console.log("BLOCKED: Cannot edit environment files. Ask Fawzi to update secrets.");
-  _trace("block-env-edit", "block", { file: normalized });
-  process.exit(2);
-}
-
-_trace("block-env-edit", "allow");
-process.exit(0);