qualia-framework 4.1.0 → 4.3.0

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-report/SKILL.md

@@ -80,10 +80,23 @@ Each session report gets a stable, sequential client-side identifier that travel
 
 ```bash
 # --dry-run: peek without incrementing
-if [ "$DRY_RUN" = "true" ]; then
-  CLIENT_REPORT_ID=$(node ~/.claude/bin/state.js next-report-id --peek 2>/dev/null | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0,'utf8')).report_id||'')")
-else
-  CLIENT_REPORT_ID=$(node ~/.claude/bin/state.js next-report-id 2>/dev/null | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0,'utf8')).report_id||'')")
+# Wrap the pipe in try/catch so a state.js failure (missing tracking.json,
+# corrupt JSON) produces a clear error instead of silently becoming "".
+PEEK_FLAG=""
+[ "$DRY_RUN" = "true" ] && PEEK_FLAG="--peek"
+CLIENT_REPORT_ID=$(node ~/.claude/bin/state.js next-report-id $PEEK_FLAG 2>/dev/null | node -e "
+  try {
+    const raw = require('fs').readFileSync(0,'utf8');
+    if (!raw.trim()) process.exit(2);
+    const j = JSON.parse(raw);
+    if (!j.report_id) process.exit(3);
+    process.stdout.write(j.report_id);
+  } catch (e) { process.exit(1); }
+")
+
+if [ -z "$CLIENT_REPORT_ID" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "Could not obtain report ID from state.js — is .planning/tracking.json valid?"
+  exit 1
 fi
 ```
 
@@ -113,54 +126,73 @@ ERP_ENABLED=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require
 
 API_KEY=$(cat ~/.claude/.erp-api-key 2>/dev/null)
 REPORT_FILE=".planning/reports/report-{date}.md"
-SUBMITTED_BY=$(git config user.name)
+SUBMITTED_BY=$(git config user.name || echo "unknown")
 SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
+# Guard: ERP upload requires a non-empty API key. Without this check, curl
+# would POST with "Authorization: Bearer " (blank bearer) and the server
+# returns a generic 401 that is hard to diagnose.
+if [ "$ERP_ENABLED" = "true" ] && [ -z "$API_KEY" ] && [ "$DRY_RUN" != "true" ]; then
+  node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key is empty or unreadable). Skipping upload."
+  node ~/.claude/bin/qualia-ui.js info "Ask Fawzi for the ERP key, save to ~/.claude/.erp-api-key, then re-run /qualia-report --upload-only."
+  ERP_ENABLED="false"
+fi
+
 # Build structured JSON payload from tracking.json (matches ERP contract /api/v1/reports)
 # v4: include milestone_name, milestones[], team_id, project_id, git_remote,
 # session_started_at, last_pushed_at, build_count, deploy_count — the ERP
 # uses these to render the project tree (milestone → phases → unphased) correctly.
 # v4.0.4: client_report_id carries the QS-REPORT-NN identifier.
-PAYLOAD=$(node -e "
-  const fs = require('fs');
-  const t = JSON.parse(fs.readFileSync('.planning/tracking.json', 'utf8'));
-  const notes = fs.readFileSync('$REPORT_FILE', 'utf8').substring(0, 60000);
-  const commits = [];
-  try {
-    const { spawnSync } = require('child_process');
-    const r = spawnSync('git', ['log', '--oneline', '--since=8 hours ago', '--format=%h'], { encoding: 'utf8', timeout: 3000 });
-    if (r.stdout) commits.push(...r.stdout.trim().split('\n').filter(Boolean));
-  } catch {}
-  console.log(JSON.stringify({
-    project: t.project || require('path').basename(process.cwd()),
-    project_id: t.project_id || '',
-    team_id: t.team_id || '',
-    git_remote: t.git_remote || '',
-    client: t.client || '',
-    client_report_id: '$CLIENT_REPORT_ID',
-    milestone: t.milestone || 1,
-    milestone_name: t.milestone_name || '',
-    milestones: Array.isArray(t.milestones) ? t.milestones : [],
-    phase: t.phase,
-    phase_name: t.phase_name,
-    total_phases: t.total_phases,
-    status: t.status,
-    tasks_done: t.tasks_done || 0,
-    tasks_total: t.tasks_total || 0,
-    verification: t.verification || 'pending',
-    gap_cycles: (t.gap_cycles || {})[String(t.phase)] || 0,
-    build_count: t.build_count || 0,
-    deploy_count: t.deploy_count || 0,
-    deployed_url: t.deployed_url || '',
-    session_started_at: t.session_started_at || '',
-    last_pushed_at: t.last_pushed_at || '',
-    lifetime: t.lifetime || {},
-    commits: commits,
-    notes: notes,
-    submitted_by: '$SUBMITTED_BY',
-    submitted_at: '$SUBMITTED_AT'
-  }));
-")
+# Build payload. Pass user-controlled values (SUBMITTED_BY, CLIENT_REPORT_ID,
+# SUBMITTED_AT, REPORT_FILE) via env vars instead of shell interpolation — a
+# single quote or backslash in git user.name would otherwise break the node -e
+# script silently. process.env.* is inert to shell metacharacters.
+PAYLOAD=$(
+  SUBMITTED_BY="$SUBMITTED_BY" \
+  SUBMITTED_AT="$SUBMITTED_AT" \
+  CLIENT_REPORT_ID="$CLIENT_REPORT_ID" \
+  REPORT_FILE="$REPORT_FILE" \
+  node -e "
+    const fs = require('fs');
+    const t = JSON.parse(fs.readFileSync('.planning/tracking.json', 'utf8'));
+    const notes = fs.readFileSync(process.env.REPORT_FILE, 'utf8').substring(0, 60000);
+    const commits = [];
+    try {
+      const { spawnSync } = require('child_process');
+      const r = spawnSync('git', ['log', '--oneline', '--since=8 hours ago', '--format=%h'], { encoding: 'utf8', timeout: 3000 });
+      if (r.stdout) commits.push(...r.stdout.trim().split('\n').filter(Boolean));
+    } catch {}
+    console.log(JSON.stringify({
+      project: t.project || require('path').basename(process.cwd()),
+      project_id: t.project_id || '',
+      team_id: t.team_id || '',
+      git_remote: t.git_remote || '',
+      client: t.client || '',
+      client_report_id: process.env.CLIENT_REPORT_ID,
+      milestone: t.milestone || 1,
+      milestone_name: t.milestone_name || '',
+      milestones: Array.isArray(t.milestones) ? t.milestones : [],
+      phase: t.phase,
+      phase_name: t.phase_name,
+      total_phases: t.total_phases,
+      status: t.status,
+      tasks_done: t.tasks_done || 0,
+      tasks_total: t.tasks_total || 0,
+      verification: t.verification || 'pending',
+      gap_cycles: (t.gap_cycles || {})[String(t.phase)] || 0,
+      build_count: t.build_count || 0,
+      deploy_count: t.deploy_count || 0,
+      deployed_url: t.deployed_url || '',
+      session_started_at: t.session_started_at || '',
+      last_pushed_at: t.last_pushed_at || '',
+      lifetime: t.lifetime || {},
+      commits: commits,
+      notes: notes,
+      submitted_by: process.env.SUBMITTED_BY || 'unknown',
+      submitted_at: process.env.SUBMITTED_AT
+    }));
+  "
+)
 
 # --dry-run: print payload and stop (no POST, no commit, no increment already handled in step 4)
 if [ "$DRY_RUN" = "true" ]; then
@@ -199,7 +231,11 @@ if [ "$ERP_ENABLED" = "true" ]; then
 
     # 401 / 422 are permanent failures — no retry.
     if [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "422" ]; then
-      node ~/.claude/bin/qualia-ui.js warn "ERP rejected report (HTTP $HTTP_CODE). Ask Fawzi."
+      if [ "$HTTP_CODE" = "401" ]; then
+        node ~/.claude/bin/qualia-ui.js warn "ERP auth failed (HTTP 401) — API key in ~/.claude/.erp-api-key is invalid or revoked. Ask Fawzi for a fresh key."
+      else
+        node ~/.claude/bin/qualia-ui.js warn "ERP rejected payload (HTTP 422) — schema validation failed. Response body:"
+      fi
       echo "$BODY" | head -3
       break
     fi

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-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-ship
-description: "Deploy to production — quality gates, commit, push, deploy, verify. Use when ready to go live."
+description: "Deploy to production — state-guard, full security scan, quality gates, commit, push, deploy, verify. Trigger on 'deploy', 'ship it', 'go live', 'push to prod', 'launch', 'release to production'."
 allowed-tools:
   - Bash
   - Read
@@ -18,6 +18,35 @@ Full deployment pipeline with quality gates.
 node ~/.claude/bin/qualia-ui.js banner ship
 ```
 
+### 0. State Guard — refuse to ship from an invalid state
+
+`/qualia-ship` is a terminal operation — it writes a deployed tag, bumps counters, and produces a verified URL. It must NEVER run on an unpolished, unverified, or malformed project.
+
+```bash
+STATE=$(node ~/.claude/bin/state.js check 2>/dev/null)
+if [ -z "$STATE" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "No project loaded. Run /qualia-new first or cd to a Qualia-managed project."
+  exit 1
+fi
+
+STATUS=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.status||'')}catch{}")
+VERIFICATION=$(echo "$STATE" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.verification||'')}catch{}")
+
+# Valid ship-from states:
+#   polished     — /qualia-polish ran cleanly; ready for deploy
+#   verified+pass — final phase verified; skipping polish is allowed for hotfixes
+# Anything else (setup, planned, built, shipped, handed_off, verified+fail) is refused.
+if [ "$STATUS" != "polished" ] && ! { [ "$STATUS" = "verified" ] && [ "$VERIFICATION" = "pass" ]; }; then
+  node ~/.claude/bin/qualia-ui.js fail "Cannot ship from state '$STATUS' (verification: ${VERIFICATION:-none})."
+  node ~/.claude/bin/qualia-ui.js info "Run /qualia-polish first, or /qualia-verify {phase} if verification is still pending."
+  node ~/.claude/bin/qualia-ui.js info "Override: add --force to the skill invocation (hotfix escape hatch, use with care)."
+  # The --force escape hatch exists for production hotfixes where the polished
+  # state was never reached. The operator is expected to have read and
+  # understood the pending verification findings.
+  exit 1
+fi
+```
+
 ### 1. Quality Gates
 
 Run in sequence. Auto-fix failures (up to 2 attempts).
@@ -34,12 +63,49 @@ On failure:
 3. Re-run the gate
 4. If still failing after 2 attempts: tell the employee, suggest `/qualia-debug`
 
-### 2. Security Check
+### 2. Security Check — full depth
+
+Shallow grep on `service_role` alone was missing hardcoded keys, tracked `.env` files, and dangerous DOM injection. Match the CRITICAL checks from `/qualia-review` exactly so the two skills agree.
 
 ```bash
-# service_role in client code?
-grep -r "service_role" app/ components/ src/ 2>/dev/null | grep -v node_modules | grep -v ".server."
-# Should be ZERO matches
+SEC_FAIL=0
+
+# CRITICAL: service_role in client-facing code
+HITS=$(grep -rn "service_role" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.server\.\|[\\/]server[\\/]\|[\\/]app[\\/]api[\\/]\|route\.\|middleware\.")
+if [ -n "$HITS" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "service_role leaked to client code:"
+  echo "$HITS" | head -5
+  SEC_FAIL=1
+fi
+
+# CRITICAL: hardcoded secrets
+HITS=$(grep -rn "sk_live\|sk_test\|SUPABASE_SERVICE_ROLE\|eyJhbGciOi" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.env")
+if [ -n "$HITS" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "Hardcoded secret found:"
+  echo "$HITS" | head -5
+  SEC_FAIL=1
+fi
+
+# CRITICAL: dangerouslySetInnerHTML / eval
+HITS=$(grep -rn "dangerouslySetInnerHTML\|eval(" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ 2>/dev/null | grep -v node_modules)
+if [ -n "$HITS" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "Dangerous innerHTML/eval pattern:"
+  echo "$HITS" | head -5
+  SEC_FAIL=1
+fi
+
+# CRITICAL: .env files tracked in git
+HITS=$(git ls-files | grep -i "\.env" | grep -v "\.example\|\.template\|\.sample")
+if [ -n "$HITS" ]; then
+  node ~/.claude/bin/qualia-ui.js fail ".env files tracked in git:"
+  echo "$HITS"
+  SEC_FAIL=1
+fi
+
+if [ $SEC_FAIL -ne 0 ]; then
+  node ~/.claude/bin/qualia-ui.js fail "Security check failed. Fix findings above or run /qualia-review for full audit."
+  exit 1
+fi
 ```
 
 ### 3. Git
@@ -64,29 +130,44 @@ wrangler deploy            # Cloudflare Workers
 
 ### 5. Post-Deploy Verification
 
-```bash
-# HTTP 200
-curl -s -o /dev/null -w "%{http_code}" {domain}
-
-# Latency under 500ms
-curl -s -o /dev/null -w "%{time_total}" {domain}
+Read the deployed URL from `tracking.json.deployed_url` — set by the deploy tool's output parser, or passed via `--url` to this skill. Do NOT use a `{domain}` placeholder — that expects the LLM to hallucinate the URL, which is exactly the kind of silent fail the state guard above prevents.
 
-# Auth endpoint responds
-curl -s -o /dev/null -w "%{http_code}" {domain}/api/auth/callback
+```bash
+# Read URL from tracking.json (set by /qualia-handoff or previous ship), or
+# let the operator pass it as an argument. Never assume a placeholder.
+URL=$(node -e "try{const t=JSON.parse(require('fs').readFileSync('.planning/tracking.json','utf8'));process.stdout.write(t.deployed_url||'')}catch{}")
+if [ -z "$URL" ]; then
+  node ~/.claude/bin/qualia-ui.js warn "No deployed_url in tracking.json — parse it from the deploy command output (vercel/supabase/wrangler all print the URL on success)."
+  node ~/.claude/bin/qualia-ui.js info "Re-run with: /qualia-ship --url https://your-site.com"
+  exit 1
+fi
+
+# HTTP 200 + latency under 500ms (combined)
+RESP=$(curl -sS -o /dev/null -w "%{http_code} %{time_total}" --max-time 15 "$URL")
+HTTP_CODE=$(echo "$RESP" | awk '{print $1}')
+LATENCY=$(echo "$RESP" | awk '{print $2}')
+
+if [ "$HTTP_CODE" != "200" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "Post-deploy check failed: HTTP $HTTP_CODE at $URL"
+  exit 1
+fi
+
+# Auth endpoint (best-effort — not every project has one)
+AUTH_CODE=$(curl -sS -o /dev/null -w "%{http_code}" --max-time 10 "$URL/api/auth/callback" 2>/dev/null)
 ```
 
 ### 6. Report
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "URL: {production url}"
-node ~/.claude/bin/qualia-ui.js ok "Status: HTTP 200"
-node ~/.claude/bin/qualia-ui.js ok "Latency: {time}ms"
-node ~/.claude/bin/qualia-ui.js ok "Auth endpoint responds"
+node ~/.claude/bin/qualia-ui.js ok "URL: $URL"
+node ~/.claude/bin/qualia-ui.js ok "Status: HTTP $HTTP_CODE"
+node ~/.claude/bin/qualia-ui.js ok "Latency: ${LATENCY}s"
+[ "$AUTH_CODE" = "200" ] || [ "$AUTH_CODE" = "401" ] && node ~/.claude/bin/qualia-ui.js ok "Auth endpoint responds (HTTP $AUTH_CODE)"
 ```
 
 ```bash
-node ~/.claude/bin/state.js transition --to shipped --deployed-url {production url}
+node ~/.claude/bin/state.js transition --to shipped --deployed-url "$URL"
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 

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"

package/templates/help.html

@@ -407,7 +407,7 @@
       <p class="cmd-group-note">When you don't know what to do next.</p>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">/qualia</span><span class="cmd-desc">Smart router &mdash; reads project state, classifies your situation, tells you the exact next command. Use whenever you're unsure about your next step.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-idk</span><span class="cmd-desc">Alias for /qualia. The smart router handles all 'idk', 'what now', 'I'm stuck' situations.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-idk</span><span class="cmd-desc">Diagnostic intelligence &mdash; spawns two isolated scans (planning + codebase) in parallel, cross-references against your confusion, explains the situation in plain language with a concrete next step. Use when something feels off or you need to understand what's going on.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-help</span><span class="cmd-desc">Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road.</span></div>
       </div>
     </div>