qualia-framework 3.6.0 → 4.0.3

package/skills/qualia-handoff/SKILL.md

@@ -1,11 +1,31 @@
 ---
 name: qualia-handoff
-description: "Client delivery — credentials, handover doc, final update. Use after shipping."
+description: "Client delivery — produces the 4 mandatory Handoff deliverables (production URL, documentation, client assets archive, ERP finalization). Triggered at the end of the Handoff milestone."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-handoff — Client Delivery
 
-Prepare and deliver the finished project to the client.
+Finishes a project by producing the 4 mandatory Handoff deliverables defined in `JOURNEY.md`'s Handoff milestone. Every Qualia client project ends with this skill.
+
+## When to Use
+
+- After `/qualia-ship` on the final phase of the Handoff milestone
+- Invoked automatically at the end of `/qualia-new --auto` chain
+- Can also be run manually if the project deviated from auto mode
+
+## The 4 Deliverables
+
+Every Handoff milestone must produce these. They are checked against in `REQUIREMENTS.md` as `HAND-10..HAND-15`.
+
+1. **Production URL verified** — HTTP 200, auth flow, latency under 500ms
+2. **Documentation** — README with architecture, setup, API docs
+3. **Client Assets** — `.planning/archive/` contains every milestone's verification reports + credentials doc + recorded walkthrough
+4. **ERP Finalization** — final `/qualia-report` with `lifetime.milestones_completed` incremented
 
 ## Process
 
@@ -13,7 +33,35 @@ Prepare and deliver the finished project to the client.
 node ~/.claude/bin/qualia-ui.js banner handoff
 ```
 
-### 1. Generate Handover Doc
+### 1. Verify Production URL (Deliverable 1)
+
+```bash
+URL=$(node -e "const t=JSON.parse(require('fs').readFileSync('.planning/tracking.json','utf8'));console.log(t.deployed_url||'')")
+if [ -z "$URL" ]; then
+  node ~/.claude/bin/qualia-ui.js fail "No deployed_url — run /qualia-ship first"
+  exit 1
+fi
+HTTP=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
+LATENCY=$(curl -s -o /dev/null -w "%{time_total}" "$URL")
+AUTH=$(curl -s -o /dev/null -w "%{http_code}" "$URL/api/auth/callback" 2>/dev/null || echo "N/A")
+node ~/.claude/bin/qualia-ui.js ok "URL: $URL (HTTP $HTTP, ${LATENCY}s, auth:$AUTH)"
+```
+
+If HTTP is not 2xx or latency > 1.0s → halt; deliverable fails.
+
+### 2. Update Documentation (Deliverable 2)
+
+Ensure the repo's `README.md` has:
+- **Overview** — what the project does
+- **Architecture** — stack summary, key services (Supabase / Vercel / third-party)
+- **Setup** — how to run locally (clone, env, `npm install`, `npm run dev`)
+- **Env vars** — list from `.env.local.example` (mask values)
+- **Deploy** — "Production deploys via `vercel --prod`. GitHub auto-deploy is DISABLED."
+- **Support** — contact: Fawzi Goussous, fawzi@qualiasolutions.net
+
+If README is stale or missing sections, update it and commit.
+
+### 3. Generate Handover Doc + Archive (Deliverable 3)
 
 Create `.planning/HANDOFF.md`:
 
@@ -21,46 +69,78 @@ Create `.planning/HANDOFF.md`:
 # {Project Name} — Handover
 
 ## What Was Built
-{3-5 bullet summary of delivered features}
+{3-5 bullet summary of delivered features, pulled from JOURNEY.md milestone exit criteria}
 
 ## Access
 - **URL:** {production URL}
-- **Admin login:** {credentials or where to find them}
+- **Admin login:** {credentials doc location — typically `.planning/credentials.md` (git-ignored)}
 - **Supabase:** {project ref}
 - **GitHub:** {repo URL}
 - **Vercel:** {project URL}
+- **Walkthrough:** {Loom or video link — recorded demo of primary flows}
 
 ## How to Use
 {Brief walkthrough of the main user flows}
 
 ## Known Limitations
-{Anything not in scope or deferred}
+{Anything not in scope or deferred, copied from REQUIREMENTS.md Out of Scope + Post-Handoff v2}
 
 ## Maintenance
-- Hosting: Vercel (auto-deploys from main branch)
+- Hosting: Vercel (MANUAL deploys via `vercel --prod`)
 - Database: Supabase ({region})
 - Domain: {domain provider if applicable}
+- Monitoring: UptimeRobot status page https://stats.uptimerobot.com/bKudHy1pLs
+
+## Milestones Shipped
+{Summary pulled from tracking.json milestones[] — one line per closed milestone with date and phase count}
 
 ## Support
 Contact: Fawzi Goussous — fawzi@qualiasolutions.net
+Standard support window: 30 days post-handoff.
+```
+
+Also ensure `.planning/archive/` contains every milestone's phase verification reports (qualia-milestone moves them there on close — verify they're present).
+
+```bash
+ls -la .planning/archive/ 2>/dev/null
 ```
 
-### 2. Commit
+If `.planning/archive/` is empty, something went wrong — milestones should have been archived on close. Investigate and recover from git history if needed.
+
+### 4. Commit + Push
 
 ```bash
-git add .planning/HANDOFF.md
-git commit -m "docs: client handoff document"
+git add .planning/HANDOFF.md README.md
+git commit -m "docs: client handoff — {project name}"
 git push
 ```
 
-### 3. Update State
+### 5. Update State
 
 ```bash
 node ~/.claude/bin/state.js transition --to handed_off
 ```
+
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
+### 6. ERP Finalization (Deliverable 4)
+
+Trigger the final `/qualia-report`. This uploads the closing state to the ERP with `lifetime.milestones_completed` incremented by the Handoff close that just happened.
+
+In `--auto` mode, inline-invoke `/qualia-report` now. In guided mode, show the next step:
+
 ```bash
-node ~/.claude/bin/qualia-ui.js ok "{Project Name} handed off to {client}"
+node ~/.claude/bin/qualia-ui.js ok "Production URL verified"
+node ~/.claude/bin/qualia-ui.js ok "Documentation updated"
+node ~/.claude/bin/qualia-ui.js ok "Client assets archived + handoff doc written"
+node ~/.claude/bin/qualia-ui.js ok "Ready for final ERP report"
 node ~/.claude/bin/qualia-ui.js end "DELIVERED" "/qualia-report"
 ```
+
+## Rules
+
+1. **No handoff without verified production URL.** Step 1 halts if URL is down or latency > 1s.
+2. **Archive is mandatory.** `.planning/archive/` must contain every closed milestone's phase artifacts. If empty, the project was handled outside the framework — recover from git history.
+3. **README is the public face.** If it's stale, fix it before handoff. Client reads it first.
+4. **Credentials never in the repo.** `.planning/credentials.md` is git-ignored. Deliver credentials via secure channel (1Password shared vault, encrypted email).
+5. **Support clause is 30 days by default.** If the client contract says otherwise, override it in HANDOFF.md.

package/skills/qualia-help/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: qualia-help
 description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+allowed-tools:
+  - Bash
+  - Read
 ---
 
 # /qualia-help — Framework Reference
@@ -12,14 +15,25 @@ Opens a Qualia-themed HTML reference guide in your default browser.
 ### 1. Generate the HTML
 
 ```bash
-# Read the template and inject the current version
-VERSION=$(node -e "console.log(require(require('os').homedir() + '/.claude/.qualia-config.json').version || 'v3')" 2>/dev/null || echo "v3")
+# Read the template and inject the current version.
+# Prefer .qualia-config.json; fall back to the framework package.json; last resort is the
+# literal string "latest" so the UI never lies about a specific version.
+VERSION=$(node -e "
+  const fs = require('fs'), path = require('path'), os = require('os');
+  const cfg = path.join(os.homedir(), '.claude', '.qualia-config.json');
+  const pkg = path.join(os.homedir(), '.claude', 'qualia-framework', 'package.json');
+  try { const v = JSON.parse(fs.readFileSync(cfg,'utf8')).version; if (v) { console.log(v); process.exit(0); } } catch {}
+  try { const v = JSON.parse(fs.readFileSync(pkg,'utf8')).version; if (v) { console.log('v'+v); process.exit(0); } } catch {}
+  console.log('latest');
+" 2>/dev/null || echo "latest")
 TEMPLATE="$HOME/.claude/qualia-templates/help.html"
 OUTPUT="/tmp/qualia-help.html"
 
-# If template doesn't exist, check the framework install
+# If template doesn't exist in the user home, check the installed framework copy.
 if [ ! -f "$TEMPLATE" ]; then
-  TEMPLATE="$(dirname "$(dirname "$(which qualia-framework 2>/dev/null || echo '')")")/templates/help.html"
+  for CANDIDATE in "$HOME/.claude/qualia-framework/templates/help.html"; do
+    if [ -f "$CANDIDATE" ]; then TEMPLATE="$CANDIDATE"; break; fi
+  done
 fi
 ```
 

package/skills/qualia-idk/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: qualia-idk
+description: "Diagnostic intelligence for 'I don't know what's going on.' Runs two isolated scans (.planning/ vs codebase), cross-references against the user's confusion, then explains the situation in plain language with a concrete recommended next step. Use whenever the user says 'I don't know', 'something feels off', 'not sure what to do', 'am I doing this right', 'what's happening', 'help me understand'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /qualia-idk — "I Don't Know What's Going On"
+
+Not a router. A **diagnostician**. Use when the user isn't stuck on a command — they're stuck on *understanding*.
+
+## How This Differs from `/qualia`
+
+| `/qualia` | `/qualia-idk` |
+|---|---|
+| Mechanical: reads state.js, returns `/qualia-X` | Interpretive: reads the project + the code + the confusion |
+| "What command do I run next?" | "What is actually going on here?" |
+| Always returns a skill name | Returns an explanation + a recommendation |
+| Cheap, instant | Spawns 2 isolated agents, ~30s |
+
+Run `/qualia` first when the user knows what they're trying to do. Run `/qualia-idk` when the user's confusion is about the *situation itself*.
+
+## Process
+
+### Step 0. Banner
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js spawn "diagnostic" "Reading planning and codebase in isolation..."
+```
+
+Say: **"Let me take a proper look."**
+
+### Step 1. Gather the User's Confusion
+
+Look at the conversation context (if any). Note:
+- What did the user just say or ask?
+- Any recent errors, failed commands, surprising output?
+- Any mismatch between what they expected and what happened?
+
+If there's nothing in conversation context yet, ask:
+- header: "What's unclear?"
+- question: "Where are you stuck? (one sentence is fine)"
+- Free text.
+
+Store this as `<user_confusion>`.
+
+### Step 2. Spawn Two Isolated Scans (Parallel)
+
+Two fresh subagents. Each sees ONLY its respective scope — no cross-contamination.
+
+```
+Agent(prompt="
+You are a read-only diagnostic scanner for the .planning/ folder only.
+
+Read ALL of the following if present:
+  - .planning/PROJECT.md
+  - .planning/JOURNEY.md
+  - .planning/REQUIREMENTS.md
+  - .planning/ROADMAP.md
+  - .planning/STATE.md
+  - .planning/tracking.json
+  - .planning/phase-*-plan.md (latest 1-2)
+  - .planning/phase-*-verification.md (latest 1-2)
+  - .planning/DESIGN.md (skim)
+  - .continue-here.md (if present)
+
+DO NOT read any source code — no src/, app/, components/, lib/, etc.
+DO NOT run any build tools.
+
+Produce a 'Plan View' report answering:
+  1. What is this project? (one sentence from PROJECT.md)
+  2. Where does the plan say we ARE? (current milestone + phase + status)
+  3. What does the plan say should be TRUE right now? (current phase's acceptance criteria / success criteria)
+  4. What does the plan say is UNFINISHED? (upcoming phases or unresolved gaps from latest verification)
+  5. Any plan-level inconsistencies? (e.g. tracking.json says phase 3 but STATE.md says phase 2, JOURNEY.md missing, roadmap out of sync)
+
+Keep it under 250 words. Be specific. No filler.
+", subagent_type="Explore", description="Plan-view scan")
+
+Agent(prompt="
+You are a read-only diagnostic scanner for the source code only.
+
+DO NOT read anything in .planning/ — skip it entirely.
+
+Scan the repo:
+  - Package/framework detection (package.json, requirements.txt, etc.)
+  - Entry points (app/, src/, pages/, index.*)
+  - Key files referenced in recent commits (git log --oneline -5, then inspect)
+  - Run quick static checks if applicable: 'npx tsc --noEmit' output, lint errors, test status
+  - Look for stubs: grep for TODO, FIXME, 'not implemented', empty catch blocks, unused exports
+
+Produce a 'Code View' report answering:
+  1. What does the code look like it's BUILDING? (inferred from structure + imports, not from docs)
+  2. What ACTUALLY WORKS right now? (compile status, recent commit messages, any obvious smoke signals)
+  3. What's STUBBED or INCOMPLETE? (concrete file:line citations)
+  4. What's RUNNING locally or deployed? (if there's a dev server log, vercel link, supabase project — flag it)
+  5. Any code-level inconsistencies? (imports that don't resolve, routes referenced but not defined, schema mismatches)
+
+Keep it under 250 words. Cite specific files/lines. No filler.
+", subagent_type="Explore", description="Code-view scan")
+```
+
+Wait for both. Don't proceed to synthesis until you have both reports.
+
+### Step 3. Synthesize
+
+With both reports + the user's confusion in hand, cross-reference:
+
+**Produce a structured diagnosis** (use this exact shape):
+
+```
+## What I see
+
+**The plan says:** {1-2 sentences — current milestone/phase/status, what should be true}
+
+**The code says:** {1-2 sentences — what actually exists, what works, what's stubbed}
+
+**The mismatch (if any):** {1-2 sentences — where plan and code disagree. If no mismatch, say "plan and code are consistent".}
+
+## What I think is happening
+
+{3-5 sentences, plain language. Tie the user's confusion to what you found. Avoid jargon. If the user said "the login is broken", don't say "the auth middleware has a type inference issue" — say "you're seeing the login fail because the signin function isn't actually imported into the login page, even though the plan says it should be. Someone wrote the helper but forgot to wire it up."}
+
+## What to do next
+
+1. **{concrete action}** — {one sentence why}
+2. **{concrete action}** — {one sentence why}
+3. **{optional third}** — {one sentence why}
+
+If one of these maps to an existing Qualia command, use it:
+  - `/qualia-plan {N} --gaps` if the mismatch is "plan says X but code has stubs"
+  - `/qualia-verify {N}` if the mismatch is "code says built but no verification exists"
+  - `/qualia-debug` if a specific error is the block
+  - `/qualia-map` if the plan and code have drifted far apart
+  - `/qualia-pause` if the user is overwhelmed and should step away
+```
+
+### Step 4. Close
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js end "DIAGNOSED" "{top-recommended action if it's a command, else leave blank}"
+```
+
+## Rules
+
+1. **Two isolated scans, always.** Plan view never peeks at code, code view never peeks at planning. This is what keeps the diagnosis honest — each agent sees one side of the story, and the synthesis catches the delta.
+2. **Plain language over jargon.** If you can't explain it to a non-dev, rewrite it.
+3. **No fake certainty.** If the scans come back thin (e.g., brand new repo), say "I don't have enough signal yet — here's what I'd do to gather more."
+4. **Never invent facts.** If the code-view scan didn't find something, don't say it exists. Cite files.
+5. **One recommendation primary, two backups.** Decision fatigue is the problem — give the user a lead option.
+6. **Don't re-run if state.js already knows.** If the user's confusion is purely "what's my next command", `/qualia` already handles that — gently suggest it instead of spawning agents.
+
+## When NOT to Use
+
+- User knows what they're doing and just wants the next command → `/qualia`
+- User has a specific error message → `/qualia-debug`
+- User wants to review code quality → `/qualia-review`
+- User wants to pause and come back → `/qualia-pause`
+
+`/qualia-idk` is specifically for **"I'm not sure what I'm even looking at"** situations. Route to sharper tools when the question is sharper.

package/skills/qualia-learn/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-learn
 description: "Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions. Trigger on 'remember this', 'save this pattern', 'learned something', 'note for future', 'client prefers', 'qualia-learn'."
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
 ---
 
 # /qualia-learn — Save Knowledge

package/skills/qualia-map/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-map
 description: "Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-map — Codebase Mapping (Brownfield)