qualia-framework 2.5.1 → 3.1.0

package/bin/statusline.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// Qualia status line — teal branded, shows phase + context + git.
+// Pure Node.js port of the original statusline.sh. Cross-platform
+// (Windows/macOS/Linux). No jq, no GNU stat, no /tmp hardcoding.
+//
+// Reads JSON from stdin (Claude Code status line schema), prints
+// two ANSI-formatted lines to stdout. Never throws — every section
+// is wrapped so missing data degrades gracefully.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const HOME = os.homedir();
+
+// ─── Colors (matches bin/qualia-ui.js palette) ───────────
+const TEAL = "\x1b[38;2;0;206;209m";
+const TEAL_GLOW = "\x1b[38;2;0;170;175m";
+const TEAL_DIM = "\x1b[38;2;0;130;135m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const DIM = "\x1b[38;2;80;90;100m";
+const GREEN = "\x1b[38;2;52;211;153m";
+const YELLOW = "\x1b[38;2;234;179;8m";
+const RED = "\x1b[38;2;239;68;68m";
+const RESET = "\x1b[0m";
+
+// ─── Read input ──────────────────────────────────────────
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+const input = readInput();
+
+function pick(obj, keypath, fallback) {
+  try {
+    let cur = obj;
+    for (const k of keypath.split(".")) {
+      if (cur == null) return fallback;
+      cur = cur[k];
+    }
+    return cur == null ? fallback : cur;
+  } catch {
+    return fallback;
+  }
+}
+
+const MODEL = String(pick(input, "model.display_name", ""));
+const DIR = String(pick(input, "workspace.current_dir", process.cwd()));
+const PCT_RAW = Number(pick(input, "context_window.used_percentage", 0)) || 0;
+const PCT = Math.floor(PCT_RAW);
+const COST = Number(pick(input, "cost.total_cost_usd", 0)) || 0;
+const DURATION_MS = Number(pick(input, "cost.total_duration_ms", 0)) || 0;
+const AGENT = String(pick(input, "agent.name", "") || "");
+const WORKTREE = String(pick(input, "worktree.name", "") || "");
+
+// ─── Context bar ─────────────────────────────────────────
+let BAR = "";
+let BAR_COLOR = TEAL;
+try {
+  if (PCT >= 80) BAR_COLOR = RED;
+  else if (PCT >= 50) BAR_COLOR = YELLOW;
+  else BAR_COLOR = TEAL;
+
+  const BAR_WIDTH = 10;
+  const filled = Math.max(0, Math.min(BAR_WIDTH, Math.floor((PCT * BAR_WIDTH) / 100)));
+  const empty = BAR_WIDTH - filled;
+  BAR = "━".repeat(filled) + "╌".repeat(empty);
+} catch {
+  BAR = "╌".repeat(10);
+}
+
+// ─── Git branch (cached, cross-platform) ─────────────────
+let BRANCH = "";
+let CHANGES = 0;
+try {
+  const username = (os.userInfo().username || "anon").replace(/[^a-zA-Z0-9_-]/g, "_");
+  const cacheFile = path.join(os.tmpdir(), `qualia-git-cache-${username}`);
+
+  let fresh = false;
+  try {
+    const st = fs.statSync(cacheFile);
+    if (Date.now() - st.mtimeMs <= 3000) fresh = true;
+  } catch {
+    fresh = false;
+  }
+
+  if (!fresh) {
+    let branch = "";
+    let changes = 0;
+    try {
+      const dirCheck = spawnSync("git", ["rev-parse", "--git-dir"], {
+        cwd: DIR,
+        encoding: "utf8",
+        timeout: 1000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      if (dirCheck.status === 0) {
+        const br = spawnSync("git", ["branch", "--show-current"], {
+          cwd: DIR,
+          encoding: "utf8",
+          timeout: 1000,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (br.status === 0) branch = (br.stdout || "").trim();
+
+        const st = spawnSync("git", ["status", "--porcelain"], {
+          cwd: DIR,
+          encoding: "utf8",
+          timeout: 1000,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (st.status === 0) {
+          const out = (st.stdout || "").trim();
+          changes = out ? out.split("\n").length : 0;
+        }
+      }
+    } catch {}
+    try {
+      fs.writeFileSync(cacheFile, `${branch}|${changes}`);
+    } catch {}
+  }
+
+  try {
+    const cached = fs.readFileSync(cacheFile, "utf8");
+    const [b, c] = cached.split("|");
+    BRANCH = b || "";
+    CHANGES = parseInt(c, 10) || 0;
+  } catch {}
+} catch {}
+
+// ─── Phase info from .planning/tracking.json ─────────────
+let PHASE_INFO = "";
+try {
+  const trackingPath = path.join(DIR, ".planning", "tracking.json");
+  if (fs.existsSync(trackingPath)) {
+    const tracking = JSON.parse(fs.readFileSync(trackingPath, "utf8"));
+    const phase = Number(tracking.phase || 0) || 0;
+    const total = Number(tracking.total_phases || 0) || 0;
+    const status = String(tracking.status || "");
+    if (total > 0) {
+      const pdone = Math.floor((phase * 100) / total);
+      const pfill = Math.max(0, Math.min(4, Math.floor(pdone / 25)));
+      const pempt = 4 - pfill;
+      const pbar = "●".repeat(pfill) + "○".repeat(pempt);
+      PHASE_INFO = `${TEAL}${pbar}${RESET} ${WHITE}P${phase}/${total}${RESET} ${TEAL_GLOW}${status}${RESET}`;
+    }
+  }
+} catch {}
+
+// ─── Memory count ────────────────────────────────────────
+let MEMORY_COUNT = 0;
+try {
+  const dirKey = DIR.replace(/\//g, "-");
+  const memDir = path.join(HOME, ".claude", "projects", dirKey, "memory");
+  if (fs.existsSync(memDir)) {
+    const files = fs.readdirSync(memDir).filter(f => f.endsWith(".md") && f !== "MEMORY.md");
+    MEMORY_COUNT = files.length;
+  }
+} catch {}
+
+// ─── Hooks count ─────────────────────────────────────────
+let HOOKS_COUNT = 0;
+try {
+  const settingsPath = path.join(HOME, ".claude", "settings.json");
+  if (fs.existsSync(settingsPath)) {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    if (settings.hooks) {
+      for (const event of Object.values(settings.hooks)) {
+        if (Array.isArray(event)) {
+          for (const matcher of event) {
+            if (matcher.hooks && Array.isArray(matcher.hooks)) {
+              HOOKS_COUNT += matcher.hooks.length;
+            }
+          }
+        }
+      }
+    }
+  }
+} catch {}
+
+// ─── Skills count ────────────────────────────────────────
+let SKILLS_COUNT = 0;
+try {
+  const skillsDir = path.join(HOME, ".claude", "skills");
+  if (fs.existsSync(skillsDir)) {
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    SKILLS_COUNT = entries.filter(e => e.isDirectory() || e.name.endsWith(".md")).length;
+  }
+} catch {}
+
+// ─── Duration ────────────────────────────────────────────
+let DUR = "0s";
+try {
+  if (DURATION_MS >= 60000) {
+    DUR = `${Math.floor(DURATION_MS / 60000)}m`;
+  } else {
+    DUR = `${Math.floor(DURATION_MS / 1000)}s`;
+  }
+} catch {}
+
+// ─── Cost ────────────────────────────────────────────────
+let COST_FMT = "$0.00";
+try {
+  COST_FMT = `$${COST.toFixed(2)}`;
+} catch {}
+
+// ─── Line 1: Project + Git + Agent + Worktree + Phase + Memory + Hooks ──
+let LINE1 = "";
+try {
+  const dirBase = path.basename(DIR) || DIR;
+  LINE1 = `${TEAL}⬢${RESET} ${WHITE}${dirBase}${RESET}`;
+  if (BRANCH) {
+    if (CHANGES > 0) {
+      LINE1 += ` ${DIM}on${RESET} ${TEAL_GLOW}${BRANCH}${RESET} ${YELLOW}~${CHANGES}${RESET}`;
+    } else {
+      LINE1 += ` ${DIM}on${RESET} ${TEAL_GLOW}${BRANCH}${RESET}`;
+    }
+  }
+  if (AGENT) LINE1 += ` ${DIM}│${RESET} ${TEAL}⚡${AGENT}${RESET}`;
+  if (WORKTREE) LINE1 += ` ${DIM}│${RESET} ${TEAL_DIM}⎇ ${WORKTREE}${RESET}`;
+  if (PHASE_INFO) LINE1 += ` ${DIM}│${RESET} ${PHASE_INFO}`;
+  // Memory, hooks, skills — context indicators with labels
+  const contextParts = [];
+  if (MEMORY_COUNT > 0) contextParts.push(`${DIM}mem${RESET} ${TEAL}${MEMORY_COUNT}${RESET}`);
+  if (HOOKS_COUNT > 0) contextParts.push(`${DIM}hooks${RESET} ${TEAL_GLOW}${HOOKS_COUNT}${RESET}`);
+  if (SKILLS_COUNT > 0) contextParts.push(`${DIM}skills${RESET} ${TEAL_DIM}${SKILLS_COUNT}${RESET}`);
+  if (contextParts.length > 0) {
+    LINE1 += ` ${DIM}│${RESET} ${contextParts.join(` ${DIM}·${RESET} `)}`;
+  }
+} catch {
+  LINE1 = `${TEAL}⬢${RESET} ${WHITE}qualia${RESET}`;
+}
+
+// ─── Line 2: Context bar + Cost + Duration + Model ───────
+let LINE2 = "";
+try {
+  LINE2 =
+    `${BAR_COLOR}${BAR}${RESET} ${DIM}${PCT}%${RESET} ` +
+    `${DIM}│${RESET} ${DIM}${COST_FMT}${RESET} ` +
+    `${DIM}│${RESET} ${DIM}${DUR}${RESET} ` +
+    `${DIM}│${RESET} ${TEAL_DIM}${MODEL}${RESET}`;
+} catch {
+  LINE2 = `${DIM}${PCT}%${RESET}`;
+}
+
+process.stdout.write(LINE1 + "\n");
+process.stdout.write(LINE2 + "\n");

package/docs/erp-contract.md

@@ -0,0 +1,161 @@
+# ERP API Contract
+
+The Qualia Framework optionally uploads session reports to the company ERP at `https://portal.qualiasolutions.net`. This document specifies the API shape.
+
+## Configuration
+
+Stored in `~/.claude/.qualia-config.json`:
+
+```json
+{
+  "erp": {
+    "enabled": true,
+    "url": "https://portal.qualiasolutions.net",
+    "api_key_file": ".erp-api-key"
+  }
+}
+```
+
+The API key is read from `~/.claude/.erp-api-key` (file mode 0600).
+
+## Endpoints
+
+### POST /api/v1/reports
+
+Upload a session report.
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "project": "client-project-name",
+  "client": "Client Name",
+  "phase": 2,
+  "phase_name": "Authentication & Dashboard",
+  "total_phases": 4,
+  "status": "built",
+  "tasks_done": 5,
+  "tasks_total": 5,
+  "verification": "pass",
+  "gap_cycles": 0,
+  "deployed_url": "https://client.vercel.app",
+  "session_duration_minutes": 45,
+  "commits": ["abc1234", "def5678"],
+  "notes": "Completed auth flow, dashboard layout, and API routes.",
+  "submitted_by": "Fawzi Goussous",
+  "submitted_at": "2026-04-12T14:30:00Z"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "report_id": "rpt_abc123def456",
+  "message": "Report received"
+}
+```
+
+**Response (401 Unauthorized):**
+```json
+{
+  "ok": false,
+  "error": "INVALID_API_KEY",
+  "message": "API key is invalid or expired"
+}
+```
+
+**Response (422 Unprocessable Entity):**
+```json
+{
+  "ok": false,
+  "error": "VALIDATION_FAILED",
+  "message": "Missing required field: project"
+}
+```
+
+### GET /api/v1/reports/:project
+
+Retrieve reports for a project.
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "reports": [
+    {
+      "report_id": "rpt_abc123def456",
+      "phase": 2,
+      "status": "built",
+      "submitted_at": "2026-04-12T14:30:00Z",
+      "submitted_by": "Fawzi Goussous"
+    }
+  ]
+}
+```
+
+### GET /api/v1/tracking/:project
+
+Retrieve current tracking state (same shape as tracking.json).
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "tracking": {
+    "project": "client-project-name",
+    "phase": 2,
+    "total_phases": 4,
+    "status": "built",
+    "last_updated": "2026-04-12T14:30:00Z"
+  }
+}
+```
+
+## Behavior
+
+- When `erp.enabled` is `false`, `/qualia-report` skips the upload silently.
+- When the API key file is missing or empty, the upload is skipped with a warning.
+- Network failures are non-blocking — the report is saved locally regardless.
+- The ERP reads `tracking.json` directly from git for real-time status (no API call needed for passive monitoring).
+- Reports are append-only — no update or delete endpoints exist.
+
+## Required Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| project | string | yes | Project slug from tracking.json |
+| phase | number | yes | Current phase number |
+| status | string | yes | Current status (setup, planned, built, verified, etc.) |
+| submitted_by | string | yes | Team member name |
+| submitted_at | string | yes | ISO 8601 timestamp |
+
+All other fields are optional but recommended for complete reporting.
+
+## Rate Limits
+
+- 60 requests per minute per API key
+- Report body max size: 64KB
+- No batch endpoint — one report per request
+
+## Security
+
+- API keys are per-user, not per-project
+- Keys expire after 90 days (re-issue via Fawzi)
+- All traffic is HTTPS-only
+- No PII beyond team member names is transmitted

package/guide.md

@@ -0,0 +1,63 @@
+# Qualia Developer Guide
+
+> Follow the road. Type the commands. The framework handles the rest.
+
+## The Road
+
+```
+/qualia-new          ← Set up project (once)
+     ↓
+For each phase:
+  /qualia-plan       ← Plan it (planner agent)
+  /qualia-build      ← Build it (builder subagents)
+  /qualia-verify     ← Verify it works (verifier agent)
+     ↓
+/qualia-polish       ← Design pass
+/qualia-ship         ← Deploy to production
+/qualia-handoff      ← Deliver to client
+     ↓
+Done.
+```
+
+## The 10 Commands
+
+| When | Command | What it does |
+|------|---------|-------------|
+| Starting | `/qualia-new` | Set up project from scratch |
+| Building | `/qualia-plan` | Plan the current phase |
+| | `/qualia-build` | Build it (parallel tasks) |
+| | `/qualia-verify` | Check it actually works |
+| Quick fix | `/qualia-quick` | Skip planning, just do it |
+| Finishing | `/qualia-polish` | Design and UX pass |
+| | `/qualia-ship` | Deploy to production |
+| | `/qualia-handoff` | Deliver to client |
+| Reporting | `/qualia-report` | Log what you did (mandatory) |
+| **Lost?** | **`/qualia`** | **Tells you the exact next command** |
+
+## Rules
+
+1. **Feature branches only** — never push to main
+2. **Read before write** — don't edit files you haven't read
+3. **MVP first** — build what's asked, nothing extra
+4. **`/qualia` is your friend** — lost? type it
+
+## When You're Stuck
+
+```
+/qualia       ← "what's next?"
+```
+
+If that doesn't help, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
+
+## Session Start / End
+
+**Start:** Claude loads your project context automatically.
+**End:** Run `/qualia-report` — this is mandatory before clock-out.
+
+## How It Works (you don't need to know this, but if curious)
+
+- **Context isolation:** Each task runs in a fresh AI brain. Task 50 gets the same quality as Task 1.
+- **Goal-backward verification:** The verifier doesn't trust "I built it." It greps the code to check if things actually work.
+- **Plans are prompts:** The plan file IS what the builder reads. No translation loss.
+- **Wave execution:** Independent tasks run in parallel. Dependent tasks wait.
+- **tracking.json:** Updated on every push. The ERP reads it automatically.

package/hooks/auto-update.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/auto-update.js — daily silent update check in the background.
+// PreToolUse hook on every Bash tool call. Fast path: single stat() call that
+// returns immediately if last check was <24h ago. Cross-platform.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawn, spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const CLAUDE_DIR = path.join(os.homedir(), ".claude");
+const CACHE_FILE = path.join(CLAUDE_DIR, ".qualia-last-update-check");
+const CONFIG_FILE = path.join(CLAUDE_DIR, ".qualia-config.json");
+const LOCK_FILE = path.join(CLAUDE_DIR, ".qualia-updating");
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+function _trace(hookName, result, extra) {
+  try {
+    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 traceFile = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(traceFile, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+try {
+  // Fast path: recently checked
+  if (fs.existsSync(CACHE_FILE)) {
+    const last = Number(fs.readFileSync(CACHE_FILE, "utf8")) || 0;
+    if (Date.now() - last * 1000 < MAX_AGE_MS) {
+      _trace("auto-update", "allow", { reason: "recently-checked" });
+      process.exit(0);
+    }
+  }
+
+  // Already updating
+  if (fs.existsSync(LOCK_FILE)) {
+    _trace("auto-update", "allow", { reason: "already-updating" });
+    process.exit(0);
+  }
+
+  // Update cache timestamp immediately to debounce concurrent checks
+  fs.writeFileSync(CACHE_FILE, String(Math.floor(Date.now() / 1000)));
+
+  // Read current config
+  let cfg = {};
+  try {
+    cfg = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    _trace("auto-update", "allow", { reason: "config-unreadable" });
+    process.exit(0);
+  }
+  if (!cfg.code || !cfg.version) {
+    _trace("auto-update", "allow", { reason: "config-incomplete" });
+    process.exit(0);
+  }
+
+  // Fork the check-and-update into a detached background process so the hook
+  // returns immediately and Claude Code is never blocked.
+  const script = `
+    const fs = require("fs");
+    const path = require("path");
+    const { spawnSync } = require("child_process");
+    const CLAUDE_DIR = ${JSON.stringify(CLAUDE_DIR)};
+    const LOCK_FILE = ${JSON.stringify(LOCK_FILE)};
+    const CONFIG_FILE = ${JSON.stringify(CONFIG_FILE)};
+    const cfg = ${JSON.stringify(cfg)};
+    try {
+      fs.writeFileSync(LOCK_FILE, String(process.pid));
+      const r = spawnSync("npm", ["view", "qualia-framework", "version"], {
+        encoding: "utf8",
+        timeout: 15000,
+        shell: process.platform === "win32",
+      });
+      const latest = ((r.stdout || "").trim());
+      if (!latest) { fs.unlinkSync(LOCK_FILE); 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++) {
+          if ((pa[i]||0) > (pb[i]||0)) return 1;
+          if ((pa[i]||0) < (pb[i]||0)) return -1;
+        }
+        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",
+        });
+      }
+    } catch {}
+    try { fs.unlinkSync(LOCK_FILE); } catch {}
+  `;
+
+  const child = spawn(process.execPath, ["-e", script], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+} catch {
+  // Silent — never block the tool call
+}
+
+_trace("auto-update", "allow", { reason: "check-spawned" });
+process.exit(0);

package/hooks/block-env-edit.js

@@ -0,0 +1,52 @@
+#!/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);