qualia-framework 4.3.0 → 4.5.0

package/templates/PRODUCT.md

@@ -0,0 +1,95 @@
+# PRODUCT — {Project Name}
+
+> **Required.** The "who and why" every Qualia agent reads before designing or building anything.
+> `/qualia-new` generates this from 5 questions. Update as the product clarifies.
+
+## Register
+
+**One of:** `brand` · `product`
+
+- **brand** — design IS the product (marketing, landing, campaign, portfolio). Distinctiveness is the bar.
+- **product** — design SERVES the product (app, admin, dashboard, tool). Earned familiarity is the bar.
+
+A project may have BOTH (e.g., marketing site + app). When that's true, list both, and note which surfaces fall under each.
+
+```
+register: product
+secondary: brand (only for /marketing/* routes)
+```
+
+## Users (specific, not personas)
+
+Real humans with real jobs who will use this. Not "small business owners" — Sarah, who runs a 3-person bookkeeping practice in Limassol and pays for QuickBooks because she trusts it. Three users, named, with the workflow in mind.
+
+```
+1. {Name} — {role + scenario}. {What they're trying to do when they open this}.
+2. ...
+3. ...
+```
+
+## Brand voice
+
+How the product sounds in writing. UI strings, error messages, marketing copy. Three adjectives, then one sentence of "voice in motion."
+
+```
+Voice: {three adjectives — e.g., "direct, confident, dry"}
+
+Voice in motion: {one paragraph showing the voice in actual sentences. What an
+error message sounds like. What a confirmation sounds like. What the empty state
+sounds like. Concrete, not adjectives.}
+```
+
+## Anti-references (mandatory, 3-5)
+
+Sites the project should NOT look like. Anti-references pin down what the design is reacting against — more useful than positive references.
+
+```
+- {URL or descriptor} — {what it gets wrong for our use case}
+- {URL or descriptor} — ...
+- {URL or descriptor} — ...
+```
+
+For Brand register, these are usually saturated aesthetic lanes (see `rules/design-brand.md`).
+For Product register, these are usually patterns we don't want to inherit (e.g., "Salesforce Lightning — too dense, too many panels").
+
+## Positive references (optional, ≤3)
+
+Sites that demonstrate qualities we want to inherit. Less important than anti-references.
+
+```
+- {URL or app name} — {specific quality, e.g., "Linear's keyboard fluency", "Stripe's empty state copy", "Vercel's color restraint"}
+```
+
+## Strategic principles
+
+3-5 statements that resolve future arguments. Not feature ideas — design/UX principles that compound.
+
+```
+- {Principle}. {One-line rationale.}
+- {Principle}. {One-line rationale.}
+- {Principle}. {One-line rationale.}
+```
+
+Examples:
+- **Density before delight.** Users live in this app 6+ hours/day. Density wins over flourish.
+- **Power users are the primary persona.** Beginners get onboarding. The app optimizes for power.
+- **Speed of glance, not depth of click.** Information visible without interaction beats information one click away.
+
+## Constraints
+
+```
+Framework:        {Next.js 16 / React 19 / Vite / Astro / etc}
+Component library: {shadcn-ui · custom · radix · arco · ...}
+Performance budget: {LCP < 2.5s, INP < 200ms, CLS < 0.1, etc}
+Accessibility:    WCAG 2.2 AA minimum
+Browsers:         {evergreen / IE11 / mobile-first / ...}
+i18n:             {languages supported, RTL needed?}
+```
+
+## Differentiation (one sentence)
+
+What someone will remember about this product 24 hours after using it for the first time. If you can't write this in one sentence, the product hasn't decided what it is yet.
+
+```
+{One sentence. What's the memory hook?}
+```

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 ]