qualia-framework 4.1.1 → 4.4.0

package/README.md

@@ -115,13 +115,13 @@ Project
 
 **Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted.
 
-## What's Inside (v4.0.0)
+## What's Inside (v4.3.0)
 
-- **26 skills** — from setup to handoff, plus debug, design, review, optimize, diagnostic (`qualia-idk`), session management, skill authoring, per-phase depth (discuss, research, map), and full-journey additions (`--auto` chaining, milestone closure)
+- **28 skills** — from setup to handoff, plus debug, design, review, optimize, diagnostic (`qualia-idk`), memory flush, postmortem, session management, skill authoring, per-phase depth (discuss, research, map), and full-journey additions (`--auto` chaining, milestone closure)
 - **8 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker
-- **7 hooks** (pure Node.js, cross-platform): session-start, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, auto-update
-- **5 rules**: security, frontend, design-reference, deployment, infrastructure
-- **19 template files**: project.md, **journey.md** (new in v4), plan.md (story-file format), state.md, DESIGN.md, tracking.json (now with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), help.html
+- **9 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, stop-session-log
+- **6 rules**: security, frontend, design-reference, deployment, infrastructure, grounding
+- **21 template files**: project.md, **journey.md** (new in v4), plan.md (story-file format), state.md, DESIGN.md, tracking.json (now with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), knowledge templates, help.html
 - **1 reference** — questioning.md methodology for deep project initialization
 
 ## Supported Platforms
@@ -156,13 +156,17 @@ Splitting planner, builder, and verifier into separate agents with separate cont
 
 ### Production-Grade Hooks
 
-All 7 hooks are real ops engineering, not theoretical:
+All 9 hooks are real ops engineering, not theoretical:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
+- **Session start** — Shows project state, next command, update notices, and health warnings at session start
+- **Auto-update** — Daily update check with cached failures so offline/npm issues do not slow every command
+- **Git guardrails** — Blocks destructive git operations like force-push to main/master, `git clean -fd`, and `rm -rf .git`
 - **Branch guard** — Role-aware: owner can push to main, employees can't (parses refspec so `feature/x:main` bypass is blocked)
 - **Migration guard** — Catches `DROP TABLE` without `IF EXISTS`, `DELETE`/`UPDATE` without `WHERE`, `CREATE TABLE` without RLS, `GRANT ... TO PUBLIC`, `ALTER TABLE ... DROP COLUMN`
 - **Pre-push** — Stamps tracking.json via a bot commit so the ERP always sees fresh data
 - **Pre-compact** — Saves state before context compression
+- **Stop-session log** — Writes lightweight daily session checkpoints into the knowledge layer
 
 ### Enforced State Machine
 
@@ -183,12 +187,12 @@ npx qualia-framework@latest install
      |
      v
 ~/.claude/
-  ├── skills/             26 slash commands
+  ├── skills/             28 slash commands
   ├── agents/             8 agent definitions (planner, builder, verifier, qa-browser, roadmapper, research-synthesizer, researcher, plan-checker)
-  ├── hooks/              7 Node.js hooks — cross-platform (no bash dependency)
-  ├── bin/                state.js (state machine) + qualia-ui.js (cosmetics, banners, journey-tree) + statusline.js
+  ├── hooks/              9 Node.js hooks — cross-platform (no bash dependency)
+  ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js
   ├── knowledge/          learned-patterns.md, common-fixes.md, client-prefs.md
-  ├── rules/              security, frontend, design-reference, deployment, infrastructure
+  ├── rules/              security, frontend, design-reference, deployment, infrastructure, grounding
   ├── qualia-templates/   project.md, journey.md, plan.md (story-file), state.md, DESIGN.md, tracking.json, requirements.md, roadmap.md, + projects/*.md + research-project/*.md + help.html
   ├── qualia-references/  questioning.md (deep project initialization methodology)
   ├── CLAUDE.md           global instructions (role-configured per team member)
@@ -201,6 +205,6 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, El
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) for the full version history. v4.0.0 release notes are the most recent section.
+See [CHANGELOG.md](./CHANGELOG.md) for the full version history. v4.3.0 release notes are the most recent section.
 
 Built by [Qualia Solutions](https://qualiasolutions.net) — Nicosia, Cyprus.

package/agents/builder.md

@@ -42,6 +42,34 @@ Parse every field in your task block:
 For every file you're about to modify — read it first. No exceptions.
 For every `@file` reference in Context — read it now.
 
+### 2b. Load Relevant Knowledge
+
+Before writing code, check the memory layer for prior decisions and known
+fixes that apply to this task. Hardcoded `cat ~/.claude/knowledge/X.md` is
+forbidden — always go through the loader so newly-added knowledge files
+become reachable automatically:
+
+```bash
+# Always — read the index to discover what's available
+node ~/.claude/bin/knowledge.js
+
+# If your task touches Supabase/auth/RLS:
+node ~/.claude/bin/knowledge.js load supabase-patterns
+node ~/.claude/bin/knowledge.js load patterns
+
+# If you're fixing a bug or hitting a familiar error, check known fixes:
+node ~/.claude/bin/knowledge.js load fixes
+node ~/.claude/bin/knowledge.js search "{error keyword}"
+
+# For client-specific work (project name appears in PROJECT.md):
+node ~/.claude/bin/knowledge.js load client
+```
+
+If a relevant entry exists, follow it (or note in your DONE message that
+you deviated and why). If nothing matches, proceed normally — the loader
+prints `(no entries in X — use /qualia-learn to add one)` for missing files,
+which is fine and means there is nothing to apply yet.
+
 ### 3. Build It
 - Follow the Action exactly as specified
 - Keep every Acceptance Criterion in mind — you are building toward observable user behaviors, not just files

package/agents/research-synthesizer.md

@@ -2,8 +2,15 @@
 name: qualia-research-synthesizer
 description: Merges 4 parallel research outputs (STACK, FEATURES, ARCHITECTURE, PITFALLS) into SUMMARY.md with roadmap implications. Spawned by qualia-new after researchers complete.
 tools: Read, Write
+model: haiku
 ---
 
+<!-- model: haiku — pure synthesis of already-gathered markdown. No new
+     reasoning beyond merging well-structured research files. Cole Medin's
+     "model-per-node" pattern: switch to haiku only where the work is
+     mechanical, not where it's high-stakes. -->
+
+
 # Research Synthesizer
 
 You merge 4 dimensional research files into one executive SUMMARY.md that informs roadmap creation. You don't do new research — you synthesize what's already gathered.

package/bin/agent-runs.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Agent runs telemetry — JSONL writer + reader. See docs/agent-runs.md.
+//
+// Pure library. Atomic writes via fs.appendFileSync (single write() syscall
+// to an O_APPEND file descriptor; safe at our record sizes — see the spec).
+//
+// Zero npm dependencies.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const SCHEMA_VERSION = 1;
+
+const VALID_AGENT_TYPES = new Set([
+  "planner", "plan-checker", "builder", "verifier", "qa-browser",
+  "researcher", "research-synthesizer", "roadmapper", "team-orchestrator",
+  "custom",
+]);
+
+const VALID_STATUS = new Set([
+  "success", "partial", "blocked", "failure", "timeout", "interrupted",
+]);
+
+// One UUID per process — fallback when Claude Code doesn't expose a session id.
+let _processSessionId = null;
+function processSessionId() {
+  if (!_processSessionId) {
+    const buf = crypto.randomBytes(16);
+    // RFC 4122 v4
+    buf[6] = (buf[6] & 0x0f) | 0x40;
+    buf[8] = (buf[8] & 0x3f) | 0x80;
+    const h = buf.toString("hex");
+    _processSessionId = `${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20)}`;
+  }
+  return _processSessionId;
+}
+
+// ULID-ish: timestamp prefix + random suffix. Sortable by time.
+function newRunId() {
+  const ts = Date.now().toString(36).toUpperCase().padStart(10, "0");
+  const rand = crypto.randomBytes(10).toString("hex").toUpperCase();
+  return `${ts}${rand}`.slice(0, 26);
+}
+
+function planningDir(cwd) {
+  return path.join(cwd || process.cwd(), ".planning");
+}
+
+function jsonlPath(cwd) {
+  return path.join(planningDir(cwd), "agent-runs.jsonl");
+}
+
+function logDir(cwd) {
+  return path.join(planningDir(cwd), "agent-runs");
+}
+
+function telemetryEnabled() {
+  return (process.env.QUALIA_TELEMETRY || "").toLowerCase() !== "off";
+}
+
+function ensureDir(p) {
+  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+}
+
+function truncTail(s, max) {
+  if (typeof s !== "string") return undefined;
+  if (s.length <= max) return s;
+  return s.slice(s.length - max);
+}
+
+// ─── Writer ────────────────────────────────────────────────────────────
+
+// start({ agent_type, model, ... }) → opaque token used by finish()
+function start(opts) {
+  const now = new Date().toISOString();
+  const token = {
+    started_at: now,
+    started_ms: Date.now(),
+    record: {
+      schema_version: SCHEMA_VERSION,
+      run_id: opts.run_id || newRunId(),
+      parent_run_id: opts.parent_run_id || undefined,
+      skill_invocation_id: opts.skill_invocation_id || processSessionId(),
+      session_id: opts.session_id || processSessionId(),
+      agent_type: opts.agent_type,
+      agent_name: opts.agent_name || undefined,
+      model: opts.model,
+      effort: opts.effort || undefined,
+      project: opts.project || undefined,
+      phase: opts.phase != null ? opts.phase : undefined,
+      milestone: opts.milestone != null ? opts.milestone : undefined,
+      task_id: opts.task_id || undefined,
+      wave: opts.wave != null ? opts.wave : undefined,
+      retry_of: opts.retry_of || undefined,
+      started_at: now,
+    },
+  };
+  return token;
+}
+
+// finish(token, { status, ... }) → writes the JSONL line + optional log file
+function finish(token, result) {
+  if (!token || !token.record) throw new Error("finish: invalid token");
+  if (!telemetryEnabled()) return { written: false, reason: "telemetry-off" };
+
+  const cwd = result.cwd || process.cwd();
+  if (!fs.existsSync(planningDir(cwd))) {
+    return { written: false, reason: "no-planning-dir" };
+  }
+
+  const finishedMs = Date.now();
+  const record = {
+    ...token.record,
+    status: result.status,
+    started_at: token.record.started_at,
+    finished_at: new Date(finishedMs).toISOString(),
+    duration_ms: finishedMs - token.started_ms,
+    input_tokens: result.input_tokens,
+    output_tokens: result.output_tokens,
+    cache_read_tokens: result.cache_read_tokens,
+    cache_creation_tokens: result.cache_creation_tokens,
+    tool_calls_count: result.tool_calls_count,
+    files_changed: Array.isArray(result.files_changed) ? [...new Set(result.files_changed)] : undefined,
+    commit_sha: result.commit_sha || undefined,
+    verifier_score: result.verifier_score,
+    verification_result: result.verification_result,
+    failure_reason: result.failure_reason,
+    failure_detail: truncTail(result.failure_detail, 500),
+  };
+
+  if (!VALID_AGENT_TYPES.has(record.agent_type)) {
+    record.failure_reason = record.failure_reason || "unknown";
+    // don't reject — we want the trace even if the caller misnamed itself
+  }
+  if (!VALID_STATUS.has(record.status)) {
+    record.status = "failure";
+    record.failure_reason = record.failure_reason || "unknown";
+  }
+
+  // Side log for non-success runs.
+  if (record.status !== "success" && typeof result.full_stderr === "string" && result.full_stderr.length) {
+    try {
+      ensureDir(logDir(cwd));
+      const logFile = path.join(logDir(cwd), `${record.run_id}.log`);
+      fs.writeFileSync(logFile, result.full_stderr);
+      record.log_file = path.relative(cwd, logFile).split(path.sep).join("/");
+    } catch {
+      // Side-log is best-effort — never block the JSONL write.
+    }
+  }
+
+  // Drop undefined keys for a compact line.
+  const clean = {};
+  for (const [k, v] of Object.entries(record)) if (v !== undefined) clean[k] = v;
+
+  const line = JSON.stringify(clean) + "\n";
+  ensureDir(planningDir(cwd));
+  fs.appendFileSync(jsonlPath(cwd), line);
+  return { written: true, run_id: record.run_id, log_file: record.log_file };
+}
+
+// ─── Reader ────────────────────────────────────────────────────────────
+
+function read(cwd, opts) {
+  const file = jsonlPath(cwd);
+  if (!fs.existsSync(file)) return [];
+  const lines = fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean);
+  const records = [];
+  for (const line of lines) {
+    try { records.push(JSON.parse(line)); }
+    catch { /* skip corrupt line; we never want a single bad record to mask the rest */ }
+  }
+  let out = records;
+  if (opts && opts.failed) {
+    out = out.filter((r) => r.status !== "success");
+  }
+  if (opts && opts.task_id) {
+    out = out.filter((r) => r.task_id === opts.task_id);
+  }
+  if (opts && opts.phase != null) {
+    out = out.filter((r) => r.phase === opts.phase);
+  }
+  if (opts && opts.limit) {
+    out = out.slice(-opts.limit);
+  }
+  return out;
+}
+
+function prune(cwd, beforeIso) {
+  const file = jsonlPath(cwd);
+  if (!fs.existsSync(file)) return { removed: 0, logs_removed: 0 };
+  const cutoff = Date.parse(beforeIso);
+  if (!Number.isFinite(cutoff)) throw new Error(`prune: invalid date "${beforeIso}"`);
+
+  const lines = fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean);
+  const kept = [];
+  const removedRunIds = [];
+  for (const line of lines) {
+    let rec;
+    try { rec = JSON.parse(line); }
+    catch { kept.push(line); continue; } // preserve unparseable; never destroy data we don't understand
+    const ts = Date.parse(rec.finished_at || rec.started_at || "");
+    if (Number.isFinite(ts) && ts < cutoff) {
+      removedRunIds.push(rec.run_id);
+    } else {
+      kept.push(line);
+    }
+  }
+  fs.writeFileSync(file, kept.join("\n") + (kept.length ? "\n" : ""));
+
+  let logsRemoved = 0;
+  if (fs.existsSync(logDir(cwd))) {
+    for (const id of removedRunIds) {
+      const lf = path.join(logDir(cwd), `${id}.log`);
+      try { fs.unlinkSync(lf); logsRemoved++; } catch {}
+    }
+  }
+  return { removed: removedRunIds.length, logs_removed: logsRemoved };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  start,
+  finish,
+  read,
+  prune,
+  // exposed for tests / introspection
+  newRunId,
+  processSessionId,
+  jsonlPath,
+  logDir,
+};