qualia-framework 4.1.1 → 4.3.0

package/skills/qualia-flush/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: qualia-flush
+description: "Promote daily-log raw entries to the curated knowledge tier — Karpathy-style raw→wiki flush. Reads ~/.claude/knowledge/daily-log/*.md, identifies recurring patterns and decisions, writes them to ~/.claude/knowledge/concepts/{topic}.md, updates index.md. Trigger on 'flush memory', 'promote learnings', 'consolidate logs', 'qualia-flush', 'process daily logs', or run weekly."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+---
+
+# /qualia-flush — Promote Raw Daily Logs to Curated Concepts
+
+Closes the **raw → wiki** loop in the Qualia memory layer. The Stop hook
+(`hooks/stop-session-log.js`, shipped in v4.2.0 foundation) appends
+mechanical session checkpoints to `~/.claude/knowledge/daily-log/{date}.md`.
+Those entries accumulate but stay raw — they describe what happened, not
+what to do about it. This skill reads the recent daily-log entries with an
+LLM (you) and writes durable concepts that the builder, planner, and
+debug skills will surface later via `node ~/.claude/bin/knowledge.js`.
+
+Inspired by Karpathy's LLM knowledge bases and Cole Medin's self-evolving
+Claude memory pattern (NotebookLM, 2026-04-25). Both run a daily/weekly
+flush that promotes raw observations into structured wiki articles. We do
+the same — manually-triggered, internal-data only, no vector DB.
+
+## When to run
+
+- **Manually:** `/qualia-flush` whenever the daily-log feels rich. Once a week
+  is the recommended cadence. More than once a day is wasteful — the
+  signal-to-noise ratio is too low at single-day windows.
+- **Automatically:** not yet wired. v4.3.0 will add a cron-friendly
+  `bin/knowledge-flush.js` non-interactive runner.
+
+## Inputs
+
+- `--days N` (optional, default 14) — how many days of daily-log to consider
+- `--project NAME` (optional) — only flush entries for one project
+- `--dry-run` (optional) — print the proposed writes, don't touch disk
+
+If the user invokes the skill bare (no args), default to `--days 14` and
+all projects. Show a one-line preview before writing anything destructive.
+
+## Process
+
+### 1. Banner + check the floor
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner flush 2>/dev/null || true
+
+# Resolve the knowledge dir. Fail loud if it doesn't exist — flush is
+# meaningless without a daily-log to read.
+KNOWLEDGE_DIR="$HOME/.claude/knowledge"
+DAILY_DIR="$KNOWLEDGE_DIR/daily-log"
+if [ ! -d "$DAILY_DIR" ]; then
+  echo "QUALIA: No daily-log at $DAILY_DIR — Stop hook hasn't run yet, or knowledge layer wasn't initialized."
+  echo "Run: npx qualia-framework@latest install"
+  exit 1
+fi
+
+# Default 14-day window. Date math is cross-platform-safe with Node.
+WINDOW_DAYS="${WINDOW_DAYS:-14}"
+node -e "
+  const d = new Date();
+  d.setDate(d.getDate() - $WINDOW_DAYS);
+  console.log(d.toISOString().split('T')[0]);
+" > /tmp/qualia-flush-cutoff
+CUTOFF=$(cat /tmp/qualia-flush-cutoff)
+```
+
+### 2. Collect the daily-log entries in window
+
+```bash
+# Iterate every file in daily-log/ whose name (YYYY-MM-DD.md) is >= CUTOFF.
+# Concatenate them into one stream so the LLM (you) can scan as one corpus.
+ls "$DAILY_DIR"/*.md 2>/dev/null | while read -r f; do
+  base=$(basename "$f" .md)
+  if [ "$base" \> "$CUTOFF" ] || [ "$base" = "$CUTOFF" ]; then
+    echo "=== $base ==="
+    cat "$f"
+    echo ""
+  fi
+done
+```
+
+You now have the raw stream. Read it.
+
+### 3. Identify what's worth promoting
+
+Read every entry. Group by project. Look for these signals — these are
+the things that promote into the wiki:
+
+| Signal in raw entry | What to extract | Goes to |
+|---|---|---|
+| Same fix appears in 2+ sessions | A common fix recipe | `common-fixes.md` (via `knowledge.js append --type fix`) |
+| A pattern shows up in 3+ projects | A reusable pattern | `learned-patterns.md` (via `knowledge.js append --type pattern`) |
+| A client-name or project preference recurs | A client preference | `client-prefs.md` (via `knowledge.js append --type client`) |
+| A new technology/library used successfully | A stack note | `concepts/{tech}.md` (new file, Write directly) |
+| A recurring failure mode (verify-fail, regression) | A pitfall | `learned-patterns.md` framed as "anti-pattern: …" |
+
+Things to **NOT** promote:
+- Single-occurrence quirks (they're noise until they recur).
+- Bare commit/branch info — that's already in git, no value duplicating.
+- Anything containing secrets, tokens, customer PII. The knowledge layer
+  is plain markdown, never put secrets here.
+- Entries from `--dry-run` runs of other skills (they'll show as activity
+  but didn't actually do anything).
+
+### 4. Write the promotions
+
+For each thing worth promoting, use the loader's `append`:
+
+```bash
+node ~/.claude/bin/knowledge.js append \
+  --type {pattern|fix|client} \
+  --title "{Concise title — what's the recurring thing?}" \
+  --body "{The promoted lesson. Be specific. Include the project name(s) and dates where this pattern was observed so future you can verify.}" \
+  --project "{specific project, or 'general' if cross-project}" \
+  --context "Promoted by /qualia-flush from daily-log entries on {dates}"
+```
+
+For a brand-new topic that doesn't fit pattern/fix/client (e.g. a Stripe
+integration approach worth its own file), Write to
+`~/.claude/knowledge/concepts/{topic}.md`. Then **update `index.md`** so the
+new file is reachable — list it under "What's where" with one line:
+
+```bash
+# After writing concepts/stripe-checkout.md:
+node ~/.claude/bin/knowledge.js path stripe-checkout
+# Returned path = ~/.claude/knowledge/stripe-checkout.md  (NOTE: top-level, not concepts/)
+```
+
+> **Subdirectory caveat:** the v4.2.0 loader resolves bare filenames at
+> `~/.claude/knowledge/{name}.md`. Subdirectory `concepts/` files are not
+> reachable via `knowledge.js load <name>` yet (deferred to v4.3.0). For
+> now, write durable concept files at the top level — flat structure is
+> fine, the index keeps it organized.
+
+### 5. Mark the window as flushed
+
+Write a stamp file so subsequent flushes can default to "since the last
+flush" instead of "last 14 days":
+
+```bash
+date -u +%Y-%m-%dT%H:%M:%SZ > "$HOME/.claude/.qualia-last-flush"
+```
+
+### 6. Summarize
+
+Print to the user, in plain language:
+
+- N daily-log files scanned (date range)
+- M promotions written (with file:title for each)
+- K things considered but not promoted (single-occurrence — wait for them to recur)
+
+Format:
+
+```
+⬢ Flushed daily-log {start} → {end} ({N} files, {total entries} entries)
+  Promoted to wiki:
+    + learned-patterns.md  "Supabase RLS in same migration"  (3 sessions, 2 projects)
+    + common-fixes.md      "next/font crash on Vercel"       (2 sessions)
+    + concepts/voice-agent-call-state.md  (new file)
+  Skipped {K} single-occurrence entries — will revisit if they recur.
+```
+
+## Style
+
+- **Be conservative.** False-positive promotions (writing noise as if it's a
+  pattern) pollute the wiki and erode trust. Better to skip a candidate and
+  let it recur next week than to inflate the curated tier.
+- **Cite your sources.** Every promoted entry should reference the
+  daily-log dates that sourced it, in the `--context` field. If a future
+  flush wants to update it, the trail is there.
+- **Keep titles short.** `--title "Supabase RLS same migration"` not `"You should always remember that when working with Supabase you need to..."`. The body is for nuance.
+- **Don't promote private projects across boundaries.** A pattern from
+  Project A is fine to promote as cross-project ONLY if it generalizes.
+  Client-specific things stay client-specific (`--type client --project X`).
+
+## Anti-patterns
+
+- **Mass-promoting everything:** if you found "promotions" for 90% of
+  daily-log entries, you're labeling, not promoting. Be selective.
+- **Re-promoting on every flush:** before appending, run
+  `node ~/.claude/bin/knowledge.js search "{title keywords}"` to check if
+  the pattern already exists. If it does, either update it (find by `**ID:**`
+  line) or skip — never duplicate.
+- **Hand-writing to `learned-patterns.md` etc. directly:** always go
+  through `knowledge.js append` so the canonical entry format and ID
+  generation stay consistent. This skill is the only sanctioned promoter,
+  but even it uses the loader for writes.
+
+## Output contract
+
+If invoked with `--dry-run`, print the proposed writes and exit without
+touching disk. Otherwise, after step 6 returns the summary, the skill is
+done — no follow-up prompts. The user sees the summary and the wiki tier
+has new entries that are immediately reachable to every other skill via
+the loader.

package/skills/qualia-learn/SKILL.md

@@ -54,49 +54,45 @@ What did you learn?
 
 ### 2. Check for Duplicates
 
-Before saving, check if a similar entry already exists:
+Before saving, search the existing knowledge for a similar entry. Use the
+unified loader, **never** raw `cat` or `grep` directly — the loader handles
+missing-file edge cases and stays consistent across skills.
 
 ```bash
-# Search for the title (case-insensitive substring match)
-grep -i "{title keywords}" ~/.claude/knowledge/{type}.md 2>/dev/null
+node ~/.claude/bin/knowledge.js search "{title keywords}"
 ```
 
-If a near-match exists (title is similar to an existing entry):
+If a near-match exists:
 - Show the existing entry to the user
 - Ask: "A similar entry exists. Update it, create a new one, or skip?"
-- If update: replace the existing entry. If new: append. If skip: done.
+- If update: edit the file directly (find the entry by `**ID:**` line). If
+  new: continue to step 3. If skip: done.
 
-### 3. Format Entry
+### 3. Append the Entry
 
-Each entry gets a unique ID and ISO timestamp for dedup and ordering:
-
-```markdown
-
----
-
-### {Title}
-**ID:** {random 8-char hex, e.g. a3f7c1e9}
-**Date:** {ISO 8601, e.g. 2026-04-11}
-**Project:** {current project name or "general"}
-**Context:** {brief context — what you were building when you learned this}
-
-{The learning — be specific enough that future-you understands without context}
-```
-
-### 4. Append to Knowledge File
-
-Append-only — never overwrite the file, always add at the end:
+The loader's `append` subcommand handles ID generation, ISO date, project
+detection, and the canonical entry format — one call, no shell escaping
+concerns:
 
 ```bash
-# Append to the right file
-echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
+node ~/.claude/bin/knowledge.js append \
+  --type {pattern|fix|client} \
+  --title "{Title}" \
+  --body "{The learning — be specific enough that future-you understands without context}" \
+  --project "{current project name or 'general'}" \
+  --context "{brief context — what you were building when you learned this}"
 ```
 
-- Pattern → `~/.claude/knowledge/learned-patterns.md`
-- Fix → `~/.claude/knowledge/common-fixes.md`
-- Client pref → `~/.claude/knowledge/client-prefs.md`
+Type → file mapping (handled by the loader):
+- `pattern` → `learned-patterns.md`
+- `fix`     → `common-fixes.md`
+- `client`  → `client-prefs.md`
+
+The loader prints `appended {id} to {file}` on success. If the destination
+file does not exist, the loader creates it with a header — you do not need
+to bootstrap it.
 
-### 5. Confirm
+### 4. Confirm
 
 ```
 ⬢ Saved to {file}
@@ -105,13 +101,27 @@ echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
 
 ## Reading Knowledge
 
-Skills can read knowledge files for context:
+**Always use the loader.** Hardcoded `cat ~/.claude/knowledge/X.md` is an
+anti-pattern — it makes new files invisible (this was v4.1.0 audit finding
+#3). The loader, by contrast, lets agents discover available knowledge via
+the index.
+
 ```bash
-cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
-cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
-cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+# Print the index (entry point — read this first)
+node ~/.claude/bin/knowledge.js
+
+# Print a specific file (accepts aliases: patterns, fixes, client)
+node ~/.claude/bin/knowledge.js load patterns
+node ~/.claude/bin/knowledge.js load common-fixes.md
+
+# List everything available
+node ~/.claude/bin/knowledge.js list
+
+# Search across all files
+node ~/.claude/bin/knowledge.js search "RLS"
 ```
 
-The `/qualia-debug` skill should check `common-fixes.md` before investigating.
-The `/qualia-new` skill should check `client-prefs.md` when setting up client projects.
-The `/qualia-plan` skill should check `learned-patterns.md` when planning phases.
+The `/qualia-debug` skill should check `common-fixes.md` (`load fixes`) before
+investigating. The `/qualia-new` skill should check `client-prefs.md`
+(`load client`) when setting up client projects. The `/qualia-plan` skill
+should check `learned-patterns.md` (`load patterns`) when planning phases.

package/skills/qualia-new/SKILL.md

@@ -94,7 +94,7 @@ Plus free-text: "Any brand colors or reference sites I should look at?"
 
 If client, ask name. Check saved prefs:
 ```bash
-cat ~/.claude/knowledge/client-prefs.md 2>/dev/null | grep -A 10 "{client name}"
+node ~/.claude/bin/knowledge.js search "{client name}"
 ```
 
 ### Step 5. Write PROJECT.md

package/skills/qualia-plan/SKILL.md

@@ -33,8 +33,9 @@ Spawn a planner agent to break the current phase into executable tasks, then val
 cat .planning/STATE.md 2>/dev/null
 cat .planning/ROADMAP.md 2>/dev/null
 cat .planning/PROJECT.md 2>/dev/null
-cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
-cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+node ~/.claude/bin/knowledge.js
+node ~/.claude/bin/knowledge.js load patterns
+node ~/.claude/bin/knowledge.js load client
 ```
 
 If no phase number given, use the current phase from STATE.md.

package/skills/qualia-postmortem/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: qualia-postmortem
+description: "Self-healing AI layer — when /qualia-verify returns FAIL, identify which agent/rule/skill should have caught the failure and propose a delta to that file so the same class of bug never recurs. Trigger on 'postmortem', 'why did the framework miss this', 'self-heal', 'qualia-postmortem', or auto-invoked by /qualia-verify on FAIL with --auto."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+---
+
+# /qualia-postmortem — Self-Healing AI Layer
+
+When the verifier finds a gap, fixing the **code** alone is not enough.
+The framework let the bug through — that means a rule, agent prompt,
+plan-checker check, or skill instruction was insufficient. This skill
+runs after a verify FAIL and asks: *which file in the AI layer should
+have caught this, and what delta would catch the next one like it?*
+
+This is Cole Medin's **pillar 5** from the parallel-worktrees playbook
+(NotebookLM 2026-04-25): "anytime we encounter a bug in a pull request,
+we don't just fix the bug and move on, we fix the underlying system that
+allowed for the bug." Without this loop, the same class of bug ships in
+PR-3, PR-7, PR-11 of every project.
+
+## When to run
+
+- **Manually:** `/qualia-postmortem` after any verify FAIL where the gap
+  feels preventable — i.e. a rule could have flagged it, a builder
+  instruction could have steered around it, a plan-checker rule could
+  have rejected the plan that produced it.
+- **Auto:** `/qualia-verify --auto` will invoke this skill on every FAIL
+  before the gap-closure loop fires. The postmortem write happens before
+  the user re-plans, so the next planner spawn benefits from the
+  updated AI layer immediately.
+
+## Inputs
+
+- `--phase N` (default: current phase from STATE.md)
+- `--apply` (optional) — apply the proposed delta to disk. Without
+  `--apply`, the skill writes `.planning/phase-{N}-postmortem.md` for
+  human review and stops there.
+- `--report-only` (optional) — just emit the analysis, write nothing.
+
+If invoked from `/qualia-verify --auto`, default to writing the
+postmortem report but **not** applying — applying touches the AI layer
+itself, which is high-stakes. The user reviews and types `/qualia-learn`
+or applies manually.
+
+## Process
+
+### 1. Load the failure
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner postmortem 2>/dev/null || true
+
+PHASE="${PHASE:-$(node ~/.claude/bin/state.js check 2>/dev/null | node -e 'let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).phase)}catch{console.log("")}})')}"
+[ -z "$PHASE" ] && { echo "QUALIA: Could not resolve current phase. Pass --phase N explicitly."; exit 1; }
+
+VERIFY_FILE=".planning/phase-${PHASE}-verification.md"
+PLAN_FILE=".planning/phase-${PHASE}-plan.md"
+
+[ -f "$VERIFY_FILE" ] || { echo "QUALIA: $VERIFY_FILE missing — nothing to post-mortem."; exit 1; }
+[ -f "$PLAN_FILE" ] || echo "QUALIA: $PLAN_FILE missing — analysis will be partial."
+```
+
+Read both files. The verification report tells you *what failed*. The
+plan tells you *what was supposed to happen*. The gap between them is
+where the AI layer fell short.
+
+### 2. Read the AI layer
+
+The framework's prompts live in three places. Load all three so you can
+match a finding to the file most likely responsible:
+
+```bash
+# Agent prompts (planner, builder, plan-checker, verifier, etc.)
+ls ~/.claude/agents/
+# Skill descriptions (qualia-plan, qualia-build, qualia-verify, etc.)
+ls ~/.claude/skills/
+# Project rules + grounding
+ls ~/.claude/rules/
+# Already-curated knowledge
+node ~/.claude/bin/knowledge.js
+```
+
+You don't read all of them — you read the ones whose job description
+matches the failure. Use this lookup:
+
+| Failure shape | Likely AI-layer owner |
+|---|---|
+| Builder produced a stub / placeholder | `agents/builder.md` (Read Before Write, no-stub rule) |
+| Plan listed Validation: `test -f file.ts` only — missed behavior check | `agents/plan-checker.md` (Rule 8: at least one grep-match or command-exit per task) |
+| Wave 2 task ran before wave 1 committed | `agents/planner.md` (dependency graph) |
+| Build passed locally, broke in CI | `rules/deployment.md` or a missing pre-deploy-gate scan |
+| RLS missing on new table | `rules/security.md` + `agents/builder.md` (security persona handling) |
+| Design regression — fonts off, contrast fail | `rules/frontend.md` + `skills/qualia-design/SKILL.md` |
+| Migration unsafe (DROP without IF EXISTS, etc.) | `hooks/migration-guard.js` |
+| Verifier missed it | `agents/verifier.md` — most embarrassing case, address with extra care |
+
+### 3. Diagnose
+
+For **each** gap in the verification report (process them one at a time
+when there are multiple), produce a four-field analysis:
+
+```markdown
+## Gap: {gap title from verification report}
+
+**Severity:** {CRITICAL | HIGH | MEDIUM | LOW}  (from verifier's rubric)
+**Owner file:** `agents/builder.md` (or rules/X.md, skills/Y/SKILL.md, etc.)
+**Why it slipped:**
+  Quote the relevant section of the owner file. Show the gap. The owner
+  file SHOULD have prevented this — either the rule wasn't there, or it
+  was there but not enforceable, or a rule was there but the agent was
+  free to ignore it.
+
+**Proposed delta:**
+  Concrete diff for the owner file. New line, edited section, or rule
+  addition. Keep it minimal — one new sentence is better than a new
+  paragraph. The goal is "the next planner/builder spawn catches this
+  class of bug."
+```
+
+### 4. Write the postmortem report
+
+```bash
+cat > .planning/phase-${PHASE}-postmortem.md <<'EOF'
+# Phase {N} Postmortem
+
+**Phase:** {N}
+**Verify result:** FAIL ({gap_count} gaps)
+**Date:** {ISO date}
+**Run ID:** {short uid}
+
+## Findings
+
+{one ## Gap section per gap, format from step 3}
+
+## Cumulative AI-layer drift
+
+{If multiple postmortems exist for this project, group recurring owner
+files: "agents/builder.md has been flagged 3 times this milestone — its
+no-stub rule may need reinforcement or wave-2 stubs need a hard hook."}
+
+## Apply?
+
+To apply all proposed deltas:
+  /qualia-postmortem --apply --phase {N}
+
+To save the recurring patterns to knowledge instead (recommended for
+project-spanning lessons):
+  /qualia-learn  (pick the relevant entries from this report)
+
+EOF
+```
+
+### 5. (Optional) Apply
+
+If invoked with `--apply`, walk each "Proposed delta" and use the Edit
+tool to make the literal change to the owner file. After every edit, run
+the framework's own type/test gates (`node --test tests/runner.js` if you
+modified anything in `bin/`, `agents/`, or `rules/`) to confirm no
+regression.
+
+If a proposed delta is to a `~/.claude/agents/X.md` file (the installed
+copy), edit that copy directly — the user re-running the installer will
+overwrite it next release, so also flag a TODO in the postmortem report
+saying "this delta should be PR'd back to the framework repo at
+`agents/X.md`" so it survives reinstall.
+
+### 6. Promote durable lessons to the knowledge layer
+
+For lessons that apply across projects (e.g. "Supabase RLS must be in
+the same migration as the table — applying it later creates a window
+where data is unprotected"), append to the curated tier so future
+builders pick it up:
+
+```bash
+node ~/.claude/bin/knowledge.js append \
+  --type pattern \
+  --title "{lesson title}" \
+  --body "{lesson body}" \
+  --project "{project name from .planning/PROJECT.md or 'general' if cross-project}" \
+  --context "Postmortem from phase ${PHASE}, verify FAIL on {date}"
+```
+
+### 7. Summarize
+
+```
+⬢ Postmortem complete — phase {N}
+  {G} gaps analyzed
+  Owner files implicated:
+    - agents/builder.md (gap 1, gap 3)
+    - rules/security.md (gap 2)
+  Report: .planning/phase-${PHASE}-postmortem.md
+  {if --apply: deltas applied; framework reinstall TODO'd}
+  {if no --apply: review and run --apply OR /qualia-learn the patterns}
+```
+
+## Style
+
+- **Be charitable.** The framework didn't fail because someone was
+  careless. It failed because a contract wasn't tight enough. Frame
+  every finding as "the contract was X; it should have been Y."
+- **Keep deltas surgical.** A 2-line addition to a rule is durable; a
+  paragraph rewrite is brittle. Smaller deltas survive future framework
+  updates.
+- **Don't reach.** If a gap genuinely doesn't map to an AI-layer file
+  (e.g. it's an external service outage), say so explicitly — don't
+  invent a rule to retroactively own it.
+- **Rate limit yourself.** Don't propose more than 3 deltas per
+  postmortem. If there are 8 gaps, the top 3 by severity get deltas; the
+  rest get noted but not deltad. Otherwise the AI layer becomes a museum
+  of edge cases.
+
+## Anti-patterns
+
+- **Re-fixing the same code as the verifier.** This skill is about the
+  AI layer, not the codebase. The gap-closure loop (`/qualia-plan
+  {N} --gaps`) handles the code. Postmortem only touches `agents/`,
+  `rules/`, `skills/`, and the knowledge layer.
+- **Auto-applying deltas to `~/.claude/agents/X.md` without flagging a
+  framework PR TODO.** That edit lasts until the next reinstall. Always
+  note the TODO so the lesson reaches the framework repo.
+- **Promoting every postmortem finding to knowledge.** Most are
+  project-specific contract tightening — they belong in the project's
+  AI-layer files, not in cross-project knowledge. Only generalizable
+  patterns get appended via `knowledge.js`.
+
+## Output contract
+
+The skill writes `.planning/phase-{N}-postmortem.md` and either applies
+deltas (with `--apply`) or stops with a summary that points the user at
+the next step (`--apply` to apply, or `/qualia-learn` to promote
+specific patterns). No follow-up prompts. Idempotent: re-running on the
+same phase appends `### Re-run {timestamp}` to the existing report
+rather than overwriting.

package/skills/qualia-review/SKILL.md

@@ -29,8 +29,9 @@ node ~/.claude/bin/qualia-ui.js banner review
 ### 0. Load Context
 
 ```bash
-cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
-cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+node ~/.claude/bin/knowledge.js
+node ~/.claude/bin/knowledge.js load fixes
+node ~/.claude/bin/knowledge.js load patterns
 ```
 
 Detect project shape:

package/skills/qualia-verify/SKILL.md

@@ -19,6 +19,7 @@ Spawn a verifier agent to check if the phase goal was achieved. Does NOT trust b
 `/qualia-verify` — verify the current built phase
 `/qualia-verify {N}` — verify specific phase
 `/qualia-verify {N} --auto` — verify + auto-chain: PASS → next phase (or milestone close); FAIL → gap closure; gap limit → halt with escalation
+`/qualia-verify {N} --adversarial` — run a SECOND verifier in fresh context with an adversarial prompt ("find what's wrong, not what's right"). Union the findings. Recommended for high-stakes phases (Handoff milestone, payment/auth/migration code) where a biased single-pass review would silently approve a bad change. v4.3.0+.
 
 ## Process
 
@@ -80,6 +81,52 @@ Drive the running dev server and test the routes this phase touched. Append a '#
 
 Wait for both the main verifier and the QA browser agent before moving to step 3. If Playwright MCP is unavailable, the QA browser agent returns BLOCKED — that's not a phase failure, just a note in the report.
 
+### 2c. Adversarial Second Opinion (--adversarial flag, optional)
+
+When `--adversarial` is in the args, OR when the current milestone is
+`Handoff` OR the phase plan touches files matching `auth|payment|migration|rls|service_role`, spawn a SECOND verifier in fresh context with an
+adversarial prompt. This is the "kid-grading-their-own-homework"
+mitigation — a single verifier instance trained on the same rubric the
+planner+builder optimized against gets ~70% fewer real findings than a
+fresh-context adversarial pass (Cole Medin, NotebookLM 2026-04-25, citing
+PR-acceptance studies).
+
+```bash
+node ~/.claude/bin/qualia-ui.js spawn verifier "Adversarial pass — find what's wrong"
+```
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/verifier.md
+Grounding + rubrics: @~/.claude/rules/grounding.md
+
+You are an ADVERSARIAL reviewer. Your job is to find what's WRONG with
+this phase, not to confirm it works. Assume the previous verifier missed
+something. Use the same Severity Rubric, the same evidence-citation
+requirement, but bias your search toward edge cases the cooperative
+verifier would skip:
+  • What untested error path exists?
+  • What input would crash this?
+  • What concurrent access pattern is unhandled?
+  • What downstream consumer breaks if this contract changes?
+  • Where is a security assumption (auth, RLS, secrets) implicit
+    instead of enforced?
+
+Project conventions: @.planning/PROJECT.md
+Phase plan: @.planning/phase-{N}-plan.md
+Cooperative verifier's report (do NOT re-find what they found, find
+what they MISSED): @.planning/phase-{N}-verification.md
+
+Append a '## Adversarial Findings' section to the verification file.
+Empty section is fine if you genuinely found nothing — better that than
+inventing findings to look productive.
+", subagent_type="qualia-verifier", description="Adversarial verify phase {N}")
+```
+
+Findings from the adversarial pass merge into the main verification
+report. The combined PASS/FAIL is the union: if either pass found a
+CRITICAL or HIGH gap, the phase is FAIL.
+
 ### 3. Present Results
 
 Read the verification report. Present:
@@ -102,6 +149,19 @@ Then for each gap:
 node ~/.claude/bin/qualia-ui.js fail "{gap description}"
 ```
 
+**Self-healing layer (v4.3.0+):** before re-planning the gaps, run a
+postmortem so the framework itself learns from the miss. This is Cole
+Medin's pillar 5: don't just fix the bug, fix the AI-layer file that
+should have caught it. The postmortem writes a report to
+`.planning/phase-{N}-postmortem.md` for review — it does NOT auto-apply
+deltas to agents/rules unless the user runs `/qualia-postmortem --apply`
+explicitly. Without this loop, the same class of bug ships in PR-3, PR-7,
+PR-11 of the next project.
+
+```
+/qualia-postmortem --phase {N}
+```
+
 End:
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"