qualia-framework 4.3.0 → 4.4.0

package/templates/help.html

@@ -297,7 +297,7 @@
   <div class="header-content">
     <h1><span>Qualia</span> Framework</h1>
     <p>Plan, build, verify, ship. The AI-powered workflow for Qualia Solutions.</p>
-    <div class="version">{{VERSION}} &middot; 26 skills</div>
+    <div class="version">{{VERSION}} &middot; 28 skills</div>
   </div>
 </div>
 
@@ -328,7 +328,7 @@
 
   <!-- Skills -->
   <section>
-    <h2>Skills (26)</h2>
+    <h2>Skills (28)</h2>
 
     <!-- Road (core flow) -->
     <div class="cmd-group">
@@ -336,7 +336,7 @@
       <p class="cmd-group-note">The seven steps every project walks through.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-new</span><span class="cmd-desc">Set up a new project from scratch &mdash; deep questioning, parallel research, REQUIREMENTS.md, ROADMAP.md, approval gate. Use when starting any new client project.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase &mdash; spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase &mdash; spawns planner, validates with plan-checker in a revision loop (max 2), optionally runs discuss/research first. Use when ready to plan a phase.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-build</span><span class="cmd-desc">Execute the current phase &mdash; spawns builder subagents per task with wave-based parallelization. Fresh context per task.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-verify</span><span class="cmd-desc">Goal-backward verification &mdash; checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
@@ -365,7 +365,6 @@
         <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured debugging &mdash; symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken'.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check'.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-optimize</span><span class="cmd-desc">Deep optimization pass &mdash; reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Supports --perf, --ui, --backend, --alignment, --fix flags.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-test</span><span class="cmd-desc">Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'test coverage'.</span></div>
       </div>
     </div>
@@ -387,6 +386,7 @@
       <p class="cmd-group-note">Persist learnings and log work.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-learn</span><span class="cmd-desc">Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-flush</span><span class="cmd-desc">Promote raw daily logs into curated knowledge concepts. Use weekly or when session logs contain durable lessons.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-report</span><span class="cmd-desc">Generate session report and commit to repo. Mandatory before clock-out.</span></div>
       </div>
     </div>
@@ -418,6 +418,7 @@
       <p class="cmd-group-note">Extend the framework itself.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia-skill-new</span><span class="cmd-desc">Author a new Qualia skill or agent. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-postmortem</span><span class="cmd-desc">Analyze a verification failure and turn the lesson into a framework improvement.</span></div>
       </div>
     </div>
   </section>
@@ -430,8 +431,13 @@
         <div class="cmd"><span class="cmd-name">qualia-framework install</span><span class="cmd-desc">Install or reinstall the framework.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework update</span><span class="cmd-desc">Update to the latest version.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework version</span><span class="cmd-desc">Show installed version + check for updates.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework uninstall</span><span class="cmd-desc">Clean removal from ~/.claude/ while preserving user-owned settings.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework migrate</span><span class="cmd-desc">Upgrade legacy settings.json to the current hook layout.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework analytics</span><span class="cmd-desc">Hook telemetry, verification pass rates, gap cycles.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework set-erp-key</span><span class="cmd-desc">Save and enable the ERP API key.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework erp-ping</span><span class="cmd-desc">Verify ERP connectivity and API key health.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework doctor</span><span class="cmd-desc">Health-check installed files, hooks, settings, and knowledge layer.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework flush</span><span class="cmd-desc">Run the non-interactive knowledge flush.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework team</span><span class="cmd-desc">List, add, or remove team members.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework traces</span><span class="cmd-desc">View recent hook activity.</span></div>
       </div>
@@ -470,11 +476,11 @@
   <section>
     <h2>Rules</h2>
     <ul class="rules">
-      <li><span class="rule-icon">1</span> Feature branches only &mdash; never push to main</li>
+      <li><span class="rule-icon">1</span> Feature branches by default &mdash; OWNER overrides must be explicit</li>
       <li><span class="rule-icon">2</span> Read before write &mdash; understand files before editing</li>
       <li><span class="rule-icon">3</span> MVP first &mdash; build what's asked, nothing extra</li>
       <li><span class="rule-icon">4</span> /qualia-report before clock-out &mdash; mandatory, enforced by ERP</li>
-      <li><span class="rule-icon">5</span> No .env edits &mdash; ask Fawzi for secrets</li>
+      <li><span class="rule-icon">5</span> Secrets through approved flows &mdash; use set-erp-key or ask Fawzi</li>
       <li><span class="rule-icon">6</span> Stuck 30+ minutes? Ask Fawzi</li>
     </ul>
   </section>
@@ -536,7 +542,7 @@
 <div class="footer">
   <strong>Welcome to the future with Qualia.</strong><br>
   Qualia Solutions &mdash; Nicosia, Cyprus
-  <span class="footer-version">qualia-framework {{VERSION}} &middot; 26 skills</span>
+  <span class="footer-version">qualia-framework {{VERSION}} &middot; 28 skills</span>
 </div>
 
 </body>

package/tests/bin.test.sh

@@ -638,8 +638,11 @@ else
   fail_case "knowledge idempotency" "exit=$EXIT"
 fi
 
-# 43. ERP API key file created and not overwritten on re-install
-if [ -f "$TMP/.claude/.erp-api-key" ]; then
+# 43. ERP API key is opt-in and preserved on re-install
+CONFIG_ENABLED=$($NODE -e "const c=require('$TMP/.claude/.qualia-config.json'); console.log(c.erp && c.erp.enabled === false ? 'disabled' : 'enabled')")
+if [ ! -f "$TMP/.claude/.erp-api-key" ] && [ "$CONFIG_ENABLED" = "disabled" ]; then
+  echo "  ✓ ERP disabled when no API key is provided"
+  PASS=$((PASS + 1))
   echo "custom-erp-key" > "$TMP/.claude/.erp-api-key"
   echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/out3.log" 2>&1
   if grep -q "custom-erp-key" "$TMP/.claude/.erp-api-key"; then
@@ -648,7 +651,7 @@ if [ -f "$TMP/.claude/.erp-api-key" ]; then
     fail_case ".erp-api-key preservation"
   fi
 else
-  fail_case ".erp-api-key missing after install"
+  fail_case "ERP opt-in default" "key_exists=$(test -f "$TMP/.claude/.erp-api-key" && echo yes || echo no) config=$CONFIG_ENABLED"
 fi
 
 # 44. Templates copied to qualia-templates/

package/tests/hooks.test.sh

@@ -34,28 +34,17 @@ for f in "$HOOKS_DIR"/*.js; do
   fi
 done
 
-# --- block-env-edit.js ---
+# --- block-env-edit.js retired in v3.2.0 ---
 echo ""
 echo "block-env-edit:"
 
-echo '{"tool_input":{"file_path":".env.local"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
-assert_exit "blocks .env.local" 2 $?
-
-echo '{"tool_input":{"file_path":".env.production"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
-assert_exit "blocks .env.production" 2 $?
-
-echo '{"tool_input":{"file_path":".env"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
-assert_exit "blocks .env" 2 $?
-
-# Windows-style path with backslashes (normalized by the hook)
-echo '{"tool_input":{"file_path":"C:\\project\\.env.local"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
-assert_exit "blocks windows .env.local" 2 $?
-
-echo '{"tool_input":{"file_path":"src/app.tsx"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
-assert_exit "allows src/app.tsx" 0 $?
-
-echo '{"tool_input":{"file_path":"components/Footer.tsx"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
-assert_exit "allows components/Footer.tsx" 0 $?
+if [ ! -f "$HOOKS_DIR/block-env-edit.js" ]; then
+  echo "  ✓ retired hook is absent"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ retired hook still exists"
+  FAIL=$((FAIL + 1))
+fi
 
 # --- migration-guard.js ---
 echo ""
@@ -329,7 +318,7 @@ mkdir -p "$TMP/app/admin"
 echo 'const key = "service_role"; export default function Page() { return <div>{key}</div>; }' > "$TMP/app/admin/page.tsx"
 OUT=$( (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js") 2>&1 )
 RC=$?
-assert_exit "regular page.tsx with service_role → blocked (exit 1)" 1 $RC
+assert_exit "regular page.tsx with service_role → blocked (exit 2)" 2 $RC
 rm -rf "$TMP"
 
 # --- session-start.js — must exit 0 always ---

package/tests/lib.test.sh

@@ -0,0 +1,217 @@
+#!/bin/bash
+# Qualia Framework — bin/plan-contract.js + bin/agent-runs.js
+# Run: bash tests/lib.test.sh
+
+PASS=0
+FAIL=0
+FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+NODE="${NODE:-node}"
+
+TMP_DIRS=()
+cleanup() {
+  for d in "${TMP_DIRS[@]}"; do
+    [ -d "$d" ] && rm -rf "$d"
+  done
+}
+trap cleanup EXIT
+
+mktmp() {
+  local t
+  t=$(mktemp -d)
+  TMP_DIRS+=("$t")
+  echo "$t"
+}
+
+ok()   { echo "  ✓ $1"; PASS=$((PASS + 1)); }
+fail() { echo "  ✗ $1"; FAIL=$((FAIL + 1)); }
+
+echo "lib.test.sh — plan-contract + agent-runs"
+
+# ─── plan-contract ──────────────────────────────────────────
+
+PC="$FRAMEWORK_DIR/bin/plan-contract.js"
+$NODE --check "$PC" >/dev/null 2>&1 && ok "plan-contract.js parses" || fail "plan-contract.js parse"
+
+OUT=$($NODE -e '
+const pc = require("'"$PC"'");
+const good = {
+  version: 1, phase: 1, goal: "x", why: "y",
+  generated_at: "2026-04-28T12:00:00Z", generated_by: "planner",
+  source_plan_hash: "sha256:abc", success_criteria: ["sc"],
+  tasks: [{
+    id: "T1", title: "t1", wave: 1, depends_on: [],
+    files_modify: [], files_create: [], files_delete: [],
+    acceptance_criteria: ["ac"], action: "do", context_files: [],
+    verification: [{ type: "file-exists", path: "a.ts" }]
+  }]
+};
+const errs = pc.validate(good);
+console.log(errs.length === 0 ? "VALID" : "INVALID:" + errs.join(";"));
+')
+[ "$OUT" = "VALID" ] && ok "validates well-formed contract" || fail "well-formed contract: $OUT"
+
+OUT=$($NODE -e '
+const pc = require("'"$PC"'");
+const errs = pc.validate({ version: 2, phase: 0, tasks: [] });
+console.log(errs.length > 0 ? "REJECTED" : "ACCEPTED");
+')
+[ "$OUT" = "REJECTED" ] && ok "rejects malformed contract" || fail "malformed accepted"
+
+OUT=$($NODE -e '
+const pc = require("'"$PC"'");
+const c = {
+  version: 1, phase: 1, goal: "x", why: "y",
+  generated_at: "t", generated_by: "planner", source_plan_hash: "h",
+  success_criteria: ["sc"],
+  tasks: [
+    { id: "T1", title: "a", wave: 1, depends_on: ["T2"], files_modify: [], files_create: [], files_delete: [],
+      acceptance_criteria: ["x"], action: "", context_files: [],
+      verification: [{ type: "file-exists", path: "a" }] },
+    { id: "T2", title: "b", wave: 1, depends_on: ["T1"], files_modify: [], files_create: [], files_delete: [],
+      acceptance_criteria: ["x"], action: "", context_files: [],
+      verification: [{ type: "file-exists", path: "b" }] },
+  ],
+};
+const errs = pc.validate(c);
+const cycle = errs.some(e => /cycle/.test(e));
+console.log(cycle ? "CYCLE-DETECTED" : "MISSED:" + errs.join(";"));
+')
+[ "$OUT" = "CYCLE-DETECTED" ] && ok "detects depends_on cycle" || fail "cycle missed: $OUT"
+
+OUT=$($NODE -e '
+const pc = require("'"$PC"'");
+const c = {
+  version: 1, phase: 1, goal: "x", why: "y",
+  generated_at: "t", generated_by: "planner", source_plan_hash: "h",
+  success_criteria: ["sc"],
+  tasks: [{ id: "T1", title: "a", wave: 1, depends_on: [], files_modify: [], files_create: [], files_delete: [],
+    acceptance_criteria: ["x"], action: "", context_files: [],
+    verification: [{ type: "command-exit", command: "node && rm", args: [], expected_exit: 0 }] }],
+};
+const errs = pc.validate(c);
+const blocked = errs.some(e => /shell metacharacters/.test(e));
+console.log(blocked ? "BLOCKED" : "ALLOWED");
+')
+[ "$OUT" = "BLOCKED" ] && ok "blocks shell metacharacters in command-exit" || fail "shell metas allowed: $OUT"
+
+OUT=$($NODE -e '
+const pc = require("'"$PC"'");
+const c = {
+  version: 1, phase: 1, goal: "x", why: "y",
+  generated_at: "t", generated_by: "planner", source_plan_hash: "h",
+  success_criteria: ["sc"],
+  tasks: [{ id: "T1", title: "a", wave: 1, depends_on: [], files_modify: [], files_create: [], files_delete: [],
+    acceptance_criteria: ["x"], action: "", context_files: [],
+    verification: [{ type: "behavioral", description: "feel", evidence_required: [] }] }],
+};
+const errs = pc.validate(c);
+const blocked = errs.some(e => /evidence_required/.test(e));
+console.log(blocked ? "BLOCKED" : "ALLOWED");
+')
+[ "$OUT" = "BLOCKED" ] && ok "rejects behavioral check with empty evidence" || fail "empty evidence allowed: $OUT"
+
+# Drift detection
+TMP=$(mktmp)
+$NODE -e '
+const pc = require("'"$PC"'");
+const fs = require("fs"), path = require("path");
+const dir = "'"$TMP"'/.planning";
+fs.mkdirSync(dir, { recursive: true });
+fs.writeFileSync(path.join(dir, "phase-1-plan.md"), "plan v1");
+const h = pc.hashPlan("plan v1");
+fs.writeFileSync(path.join(dir, "phase-1-contract.json"), JSON.stringify({ source_plan_hash: h }));
+const d1 = pc.checkDrift(path.join(dir, "phase-1-contract.json"), path.join(dir, "phase-1-plan.md"));
+console.log(d1.drift ? "FAIL1" : "");
+fs.appendFileSync(path.join(dir, "phase-1-plan.md"), "\nedit\n");
+const d2 = pc.checkDrift(path.join(dir, "phase-1-contract.json"), path.join(dir, "phase-1-plan.md"));
+console.log(d2.drift ? "DRIFT-DETECTED" : "FAIL2");
+' | tail -1 > /tmp/qfdrift.out
+[ "$(cat /tmp/qfdrift.out)" = "DRIFT-DETECTED" ] && ok "drift detection" || fail "drift detection: $(cat /tmp/qfdrift.out)"
+
+# ─── agent-runs ──────────────────────────────────────────
+
+AR="$FRAMEWORK_DIR/bin/agent-runs.js"
+$NODE --check "$AR" >/dev/null 2>&1 && ok "agent-runs.js parses" || fail "agent-runs.js parse"
+
+TMP=$(mktmp)
+mkdir -p "$TMP/.planning"
+RES=$($NODE -e '
+const ar = require("'"$AR"'");
+const tok = ar.start({ agent_type: "builder", model: "claude-sonnet-4-6", phase: 1, task_id: "T1" });
+const r = ar.finish(tok, { status: "success", commit_sha: "abc", cwd: "'"$TMP"'" });
+console.log(r.written ? "WRITTEN" : "NOT");
+')
+[ "$RES" = "WRITTEN" ] && ok "agent-runs writes a record" || fail "agent-runs write: $RES"
+
+RES=$($NODE -e '
+const ar = require("'"$AR"'");
+const recs = ar.read("'"$TMP"'");
+console.log(recs.length === 1 && recs[0].agent_type === "builder" ? "READ-OK" : "READ-FAIL");
+')
+[ "$RES" = "READ-OK" ] && ok "agent-runs reads back the record" || fail "read failed: $RES"
+
+# Telemetry off → no write
+TMP2=$(mktmp)
+mkdir -p "$TMP2/.planning"
+RES=$(QUALIA_TELEMETRY=off $NODE -e '
+const ar = require("'"$AR"'");
+const tok = ar.start({ agent_type: "verifier", model: "claude-opus-4-7" });
+const r = ar.finish(tok, { status: "success", cwd: "'"$TMP2"'" });
+console.log(r.written ? "WRITTEN" : "SKIPPED");
+')
+[ "$RES" = "SKIPPED" ] && ok "QUALIA_TELEMETRY=off disables writes" || fail "telemetry off: $RES"
+
+# Read still works after opt-out (history not hidden) — synthesize one record then disable
+TMP3=$(mktmp)
+mkdir -p "$TMP3/.planning"
+$NODE -e '
+const ar = require("'"$AR"'");
+const tok = ar.start({ agent_type: "builder", model: "x" });
+ar.finish(tok, { status: "success", cwd: "'"$TMP3"'" });
+' >/dev/null
+RES=$(QUALIA_TELEMETRY=off $NODE -e '
+const ar = require("'"$AR"'");
+console.log(ar.read("'"$TMP3"'").length);
+')
+[ "$RES" = "1" ] && ok "QUALIA_TELEMETRY=off does NOT hide existing records" || fail "history hidden: $RES"
+
+# Failure log file
+TMP4=$(mktmp)
+mkdir -p "$TMP4/.planning"
+RES=$($NODE -e '
+const ar = require("'"$AR"'");
+const tok = ar.start({ agent_type: "verifier", model: "x" });
+const r = ar.finish(tok, { status: "failure", failure_reason: "tsc-failed",
+  failure_detail: "x".repeat(800), full_stderr: "trace lines", cwd: "'"$TMP4"'" });
+console.log(r.log_file ? "LOG:" + r.log_file : "NO-LOG");
+' )
+echo "$RES" | grep -q '^LOG:' && ok "failure writes side log file" || fail "no log on failure: $RES"
+
+# Truncation: must keep tail
+RES=$($NODE -e '
+const ar = require("'"$AR"'");
+const recs = ar.read("'"$TMP4"'");
+const fd = recs[0].failure_detail;
+const allXs = /^x+$/.test(fd) && fd.length === 500;
+console.log(allXs ? "TAIL-KEPT-500" : "WRONG-LEN-OR-CONTENT:" + fd.length);
+')
+[ "$RES" = "TAIL-KEPT-500" ] && ok "failure_detail keeps tail at 500 chars" || fail "truncation: $RES"
+
+# Prune
+TMP5=$(mktmp)
+mkdir -p "$TMP5/.planning"
+$NODE -e '
+const ar = require("'"$AR"'");
+const t1 = ar.start({ agent_type: "builder", model: "x" });
+ar.finish(t1, { status: "success", cwd: "'"$TMP5"'" });
+' >/dev/null
+RES=$($NODE -e '
+const ar = require("'"$AR"'");
+const r = ar.prune("'"$TMP5"'", "2099-01-01T00:00:00Z");
+console.log("removed:" + r.removed);
+')
+[ "$RES" = "removed:1" ] && ok "prune --before removes old records" || fail "prune: $RES"
+
+echo ""
+echo "lib.test.sh: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]