qualia-framework 4.4.0 → 5.1.0

package/skills/qualia-report/SKILL.md

@@ -1,123 +1,160 @@
 ---
 name: qualia-report
-description: "Generate session report and commit to repo. Mandatory before clock-out."
+description: "Generate session report, commit to git, push, and upload to the Qualia ERP — the mandatory clock-out flow. Use when the user says 'qualia-report', 'clock out', 'end of day', 'wrap up', 'session report', 'submit report', 'I'm done for today', or before stopping work. Handles empty days (no commits), missing API key, ERP outages, and dry-run preview gracefully."
 allowed-tools:
   - Bash
   - Read
   - Write
   - Edit
+  - AskUserQuestion
 ---
 
-# /qualia-report — Session Report
+# /qualia-report — Daily Clock-Out Report
 
-Generate a concise report of what was done. Committed to git and uploaded to the ERP for clock-out.
+The end-of-day flow. Generates a report, commits it, pushes, uploads to the ERP, and tells the employee they can stop. Designed so Hasan and Moayad never get stuck on it.
 
 ## Flags
-
 - `/qualia-report` — normal flow (generate, commit, push, upload to ERP)
-- `/qualia-report --dry-run` — generate + show payload, SKIP upload and SKIP commit. Useful for debugging or previewing before a real clock-out.
+- `/qualia-report --dry-run` — preview the payload without committing/uploading
 
 ## Process
 
+### Step 0 — Pre-flight (graceful)
+
 ```bash
 node ~/.claude/bin/qualia-ui.js banner report
+
+# Sanity checks — soft failures only, never block the report
+test -d .git || node ~/.claude/bin/qualia-ui.js warn "Not a git repo — local commit will be skipped, ERP upload will still try"
+test -f .planning/tracking.json || node ~/.claude/bin/qualia-ui.js warn "No tracking.json yet — ERP payload will use defaults"
+
+DRY_RUN="${DRY_RUN:-false}"
+echo "$ARGUMENTS" | grep -q -- '--dry-run' && DRY_RUN="true"
 ```
 
-### 1. Gather Data
+### Step 1 — Gather
 
 ```bash
 SINCE="8 hours ago"
-echo "---COMMITS---"
-git log --oneline --since="$SINCE" 2>/dev/null | head -20
-echo "---STATS---"
-echo "COUNT:$(git log --oneline --since="$SINCE" 2>/dev/null | wc -l)"
-echo "---PROJECT---"
-echo "DIR:$(basename $(pwd))"
-echo "BRANCH:$(git branch --show-current 2>/dev/null)"
-echo "---STATE---"
-node ~/.claude/bin/state.js check 2>/dev/null
+COMMITS=$(git log --oneline --since="$SINCE" 2>/dev/null)
+COUNT=$(echo "$COMMITS" | grep -c . 2>/dev/null || echo 0)
+BRANCH=$(git branch --show-current 2>/dev/null || echo "no-branch")
+PROJECT=$(basename "$(pwd)")
+```
+
+### Step 2 — Synthesize (with empty-day handling)
+
+**If `COUNT > 0`** — build a structured summary using this template:
+
+```markdown
+## What Was Done
+- {Verb} {object}. Why: {one-clause reason}.   ← write 3–6 of these, one per related-commits group
+                                                   verbs: Built, Fixed, Refactored, Added, Removed,
+                                                   Migrated, Documented, Investigated, Reverted
+
+## Blockers
+None.   ← or list 1–N actual blockers (NOT "had to read docs" — that's normal)
+
+## Next Steps
+1. {Concrete next action — a command or a decision needed}
+2. ...
 ```
 
-### 2. Synthesize
+**If `COUNT == 0`** — ask the employee gracefully (don't force a fake report):
+
+Use `AskUserQuestion`:
+- header: "Empty day?"
+- question: "No commits in the last 8 hours. What did you do today?"
+- options:
+  - "Investigation / research only"
+  - "Meetings / calls (no code)"
+  - "Blocked — tell me on what"
+  - "Time off / partial day"
 
-Build a concise summary:
-- **What was done:** 3-6 bullet points. Start with verbs (Built, Fixed, Added). Group related commits.
-- **Blockers:** Only if something is actually blocked.
-- **Next:** 1-3 clear next actions.
+Capture the answer as the report body. Empty days are still valid clock-outs — the ERP needs to see them.
 
-### 3. Generate Report
+### Step 3 — Write report file
 
-Write to `.planning/reports/report-{YYYY-MM-DD}.md`:
+`.planning/reports/report-{YYYY-MM-DD}.md`:
 
 ```markdown
 # Session Report — {YYYY-MM-DD}
 
-**Project:** {name}
+**Project:** {PROJECT}
 **Employee:** {git user.name}
-**Branch:** {branch}
-**Phase:** {N} — {name} ({status})
+**Branch:** {BRANCH}
+**Phase:** {N — name (status), or "no active phase"}
 **Date:** {YYYY-MM-DD}
 
-## What Was Done
-- {accomplishment 1}
-- {accomplishment 2}
-- {accomplishment 3}
-
-## Blockers
-None. / - {blocker}
-
-## Next Steps
-1. {next action}
-2. {next action}
+{synthesis from Step 2}
 
-## Commits
-{list from git log}
+## Commits ({COUNT})
+{git log output, or "none today"}
 ```
 
-### 4. Obtain Client Report ID (QS-REPORT-NN)
+### Step 4 — Allocate client report ID
 
-Each session report gets a stable, sequential client-side identifier that travels with the report all the way to the ERP. The sequence is per-project, persisted in `tracking.json.report_seq`.
+Per-project sequential ID (QS-REPORT-01, 02, ...). State.js owns the counter — never edit by hand.
 
 ```bash
-# --dry-run: peek without incrementing
-# 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); }
-")
+PEEK=""
+[ "$DRY_RUN" = "true" ] && PEEK="--peek"
+CLIENT_REPORT_ID=$(node ~/.claude/bin/state.js next-report-id $PEEK 2>/dev/null \
+  | node -e "try{const j=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(j.report_id||'')}catch{}")
 
 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?"
+  node ~/.claude/bin/qualia-ui.js fail "Could not allocate report ID. Try: cat .planning/tracking.json (is it valid JSON?)"
   exit 1
 fi
 ```
 
-Example: first report on a fresh project → `QS-REPORT-01`. Next → `QS-REPORT-02`. Etc.
-
-### 5. Commit and Push (SKIP on --dry-run)
+### Step 5 — Commit + push (skip on --dry-run)
 
 ```bash
-if [ "$DRY_RUN" != "true" ]; then
+if [ "$DRY_RUN" != "true" ] && [ -d .git ]; then
   mkdir -p .planning/reports
   git add .planning/reports/report-{date}.md .planning/tracking.json
-  git commit -m "report: {CLIENT_REPORT_ID} session {YYYY-MM-DD}"
-  git push
+  git commit -m "report: $CLIENT_REPORT_ID session {YYYY-MM-DD}" || node ~/.claude/bin/qualia-ui.js warn "Nothing to commit (clean tree?)"
+  git push 2>&1 | tail -3
+  PUSH_EXIT=${PIPESTATUS[0]}
+  [ "$PUSH_EXIT" != "0" ] && node ~/.claude/bin/qualia-ui.js warn "git push failed — report committed locally but not pushed. ERP upload will still try."
 fi
 ```
 
-### 6. Upload to ERP (SKIP on --dry-run)
+### Step 6 — Upload to ERP
+
+The full payload-builder + 3-attempt-retry logic lives unchanged from v4 — see the **ERP Upload** section below for the canonical implementation. Behavior summary:
+- ERP disabled in config → skip silently, note local commit
+- API key missing → warn with self-service fix instructions, skip upload
+- 401/422 → permanent failure, no retry, tell employee to ask Fawzi
+- Transient (timeout/5xx) → 3 attempts with 1s/3s/9s backoff
+- Success → "Uploaded as $CLIENT_REPORT_ID (ERP: {uuid})"
 
-Read `~/.claude/.qualia-config.json` and check the `erp` object:
-- If `erp.enabled` is `false`, skip this step and print: "ERP upload skipped (disabled in config)."
-- If `erp.enabled` is `true` (default) or the `erp` field is missing (backward compatibility), proceed with the upload.
+### Step 7 — State + closing
+
+```bash
+if [ "$DRY_RUN" != "true" ]; then
+  node ~/.claude/bin/state.js transition --to activity --notes "Session report $CLIENT_REPORT_ID generated" 2>/dev/null
+fi
+
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Report $CLIENT_REPORT_ID complete."
+node ~/.claude/bin/qualia-ui.js info "You can clock out now. See you tomorrow."
+```
+
+## Common errors (read this when something goes wrong)
+
+| Symptom | Likely cause | Self-service fix |
+|---|---|---|
+| "Could not allocate report ID" | tracking.json missing/corrupt | `cat .planning/tracking.json` to inspect, or restore from `git checkout HEAD -- .planning/tracking.json` |
+| "ERP API key missing" | `~/.claude/.erp-api-key` empty | `qualia-framework set-erp-key <key>` (ask Fawzi for the key) |
+| "ERP auth failed (401)" | Key revoked or wrong | Ask Fawzi for a fresh key |
+| "ERP upload failed after 3 attempts" | ERP down or network issue | Local commit is safe. Re-run `/qualia-report` later. |
+| "git push failed" | Auth or network or upstream issue | `git push` manually, see the error, fix, re-run |
+
+## ERP Upload (canonical implementation)
+
+The Step 6 payload + retry logic. Inlined to avoid a script-file fetch on every clock-out. The agent runs this verbatim.
 
 ```bash
 # Read ERP config
@@ -129,151 +166,75 @@ REPORT_FILE=".planning/reports/report-{date}.md"
 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.
+# Guard: API key required for upload (otherwise curl posts an empty bearer)
 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, run 'qualia-framework set-erp-key <key>', then run 'qualia-framework erp-ping'."
+  node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key). Run: qualia-framework set-erp-key <key>"
   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.
-# 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.
+# Build payload (env-var-passed user values to dodge shell escaping)
 PAYLOAD=$(
-  SUBMITTED_BY="$SUBMITTED_BY" \
-  SUBMITTED_AT="$SUBMITTED_AT" \
-  CLIENT_REPORT_ID="$CLIENT_REPORT_ID" \
-  REPORT_FILE="$REPORT_FILE" \
+  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 {}
+    const fs=require('fs'),path=require('path'),os=require('os');
+    const {spawnSync}=require('child_process');
+    const git=(a)=>{const r=spawnSync('git',a,{encoding:'utf8',timeout:3000});return r.status===0?r.stdout.trim():'';};
+    const repoSlug=(r)=>(r||'').replace(/^git@github\\.com:/,'github.com/').replace(/^https?:\\/\\//,'').replace(/\\.git$/,'').split('/').filter(Boolean).pop();
+    let config={};try{config=JSON.parse(fs.readFileSync(path.join(os.homedir(),'.claude/.qualia-config.json'),'utf8'));}catch{}
+    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 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{}
+    const gitRemote=t.git_remote||git(['config','--get','remote.origin.url']);
+    const projectKey=t.project_id||repoSlug(gitRemote)||require('path').basename(process.cwd());
     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
+      project:t.project||require('path').basename(process.cwd()),
+      project_id:projectKey,team_id:t.team_id||'qualia-solutions',git_remote:gitRemote,
+      client:t.client||'',client_report_id:process.env.CLIENT_REPORT_ID,
+      framework_version:config.version||'',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)
+# --dry-run: print and stop
 if [ "$DRY_RUN" = "true" ]; then
-  echo "--- DRY RUN · payload ---"
-  echo "$PAYLOAD" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8'));console.log(JSON.stringify(d,null,2))"
+  echo "--- DRY RUN · payload ---"; echo "$PAYLOAD" | node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync(0,'utf8')),null,2))"
   echo "--- DRY RUN · would POST to: $ERP_URL/api/v1/reports ---"
   echo "--- DRY RUN · client_report_id would be: $CLIENT_REPORT_ID ---"
   exit 0
 fi
 
-# Real upload — 3 attempts with exponential backoff (1s, 3s, 9s).
-# The local report file is already committed, so a failed upload doesn't
-# lose data — it just leaves the ERP view stale until the next push or
-# manual retry.
+# Upload — 3 attempts with 1s/3s/9s backoff
 if [ "$ERP_ENABLED" = "true" ]; then
-  MAX_ATTEMPTS=3
-  ATTEMPT=1
-  SUCCESS=false
-  while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
+  for ATTEMPT in 1 2 3; do
     RESPONSE=$(curl -sS -X POST "$ERP_URL/api/v1/reports" \
-      -H "Authorization: Bearer $API_KEY" \
-      -H "Content-Type: application/json" \
-      -d "$PAYLOAD" \
-      --max-time 10 \
-      -w "\n__HTTP__%{http_code}" 2>&1)
+      -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+      -d "$PAYLOAD" --max-time 10 -w "\n__HTTP__%{http_code}" 2>&1)
     HTTP_CODE=$(echo "$RESPONSE" | grep -o "__HTTP__[0-9]*" | sed 's/__HTTP__//')
     BODY=$(echo "$RESPONSE" | sed 's/__HTTP__[0-9]*//g')
 
     if [ "$HTTP_CODE" = "200" ]; then
-      SUCCESS=true
-      # Parse and display the ERP-returned report_id alongside our local QS-REPORT-NN
-      ERP_REPORT_ID=$(echo "$BODY" | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.report_id||'')}catch{}")
+      ERP_REPORT_ID=$(echo "$BODY" | node -e "try{process.stdout.write(JSON.parse(require('fs').readFileSync(0,'utf8')).report_id||'')}catch{}")
       node ~/.claude/bin/qualia-ui.js ok "Uploaded as $CLIENT_REPORT_ID (ERP: ${ERP_REPORT_ID:-none})"
       break
     fi
-
-    # 401 / 422 are permanent failures — no retry.
     if [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "422" ]; then
-      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
+      node ~/.claude/bin/qualia-ui.js warn "ERP rejected ($HTTP_CODE) — $([ "$HTTP_CODE" = "401" ] && echo "API key invalid, ask Fawzi" || echo "schema mismatch:")"
+      [ "$HTTP_CODE" = "422" ] && echo "$BODY" | head -3
       break
     fi
-
-    # Transient failure — back off and retry.
-    if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
-      SLEEP=$(( 1 * 3 ** (ATTEMPT - 1) ))
-      node ~/.claude/bin/qualia-ui.js warn "ERP upload attempt $ATTEMPT failed (HTTP ${HTTP_CODE:-timeout}), retrying in ${SLEEP}s..."
-      sleep $SLEEP
-    fi
-    ATTEMPT=$(( ATTEMPT + 1 ))
+    [ $ATTEMPT -lt 3 ] && { SLEEP=$((1 * 3 ** (ATTEMPT - 1))); node ~/.claude/bin/qualia-ui.js warn "Attempt $ATTEMPT failed (HTTP ${HTTP_CODE:-timeout}), retrying in ${SLEEP}s..."; sleep $SLEEP; }
   done
-
-  if [ "$SUCCESS" != "true" ]; then
-    node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after $MAX_ATTEMPTS attempts. $CLIENT_REPORT_ID is committed locally; it will NOT appear in the ERP until you retry with 'curl' or re-run /qualia-report."
-  fi
+  [ "$ATTEMPT" = "3" ] && [ "$HTTP_CODE" != "200" ] && node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts. $CLIENT_REPORT_ID is committed locally; will appear in ERP after retry."
 fi
 
-if [ "$ERP_ENABLED" != "true" ]; then
-  node ~/.claude/bin/qualia-ui.js info "ERP upload skipped (disabled in config). Report committed locally as $CLIENT_REPORT_ID."
-fi
+[ "$ERP_ENABLED" != "true" ] && node ~/.claude/bin/qualia-ui.js info "ERP upload skipped (disabled). $CLIENT_REPORT_ID committed locally."
 ```
-
-Summary rules:
-- **Upload succeeds:** print "Uploaded as QS-REPORT-NN (ERP: {uuid})". Employee can clock out.
-- **401/422:** no retry. Print the error, tell the employee to ask Fawzi.
-- **Transient (timeout, 5xx, network):** retry 3x with 1s/3s/9s backoff.
-- **All retries fail:** tell employee the report is committed locally, ERP will be stale until retry.
-- **ERP disabled:** skip silently with a note, local commit still happens.
-
-### 7. Update State (SKIP on --dry-run)
-
-```bash
-if [ "$DRY_RUN" != "true" ]; then
-  node ~/.claude/bin/state.js transition --to activity --notes "Session report $CLIENT_REPORT_ID generated"
-fi
-```
-
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.
-
-Employee cannot skip this. Run `/qualia-report` before clock-out.

package/skills/qualia-research/SKILL.md

@@ -12,14 +12,14 @@ allowed-tools:
 
 # /qualia-research — Per-Phase Deep Research
 
-Runs targeted research on a domain, library, or integration that a specific phase depends on. Distinct from `/qualia-new` research (which covers 4 dimensions project-wide) — this one is narrow and phase-scoped.
+Targeted research on domain, library, or integration for a specific phase. Narrow and phase-scoped (distinct from `/qualia-new` project-wide research).
 
 ## When to Use
 
-- A phase touches a library you've never used
-- A phase integrates with a niche API (FHIR, legal forms, payment gateways)
-- SUMMARY.md marked this phase as a "Research flag"
-- You're about to plan and realize you don't know the current best practice
+- Phase touches unfamiliar library
+- Phase integrates niche API (FHIR, legal forms, payment gateways)
+- SUMMARY.md flagged phase for research
+- Unsure of current best practice before planning
 
 ## Usage
 
@@ -33,7 +33,7 @@ Runs targeted research on a domain, library, or integration that a specific phas
 node ~/.claude/bin/state.js check 2>/dev/null
 ```
 
-Use phase N from args, or current phase from STATE.md.
+Phase N from args, or current phase from STATE.md.
 
 ### 2. Load Context
 
@@ -43,21 +43,19 @@ cat .planning/ROADMAP.md 2>/dev/null
 cat .planning/phase-{N}-context.md 2>/dev/null  # if /qualia-discuss was run first
 ```
 
-Identify what this phase needs to know.
+Identify what phase needs to know.
 
-### 3. Ask the User What to Research
+### 3. Ask User
 
-Inline free text:
+**"Researching Phase {N}: {phase name}. What to dig into? Library, domain, integration, pattern?"**
 
-**"I'm about to research Phase {N}: {phase name}. What specifically do you want me to dig into? Library, domain, integration, pattern?"**
+Wait for answer. Answer defines research question.
 
-Wait for their answer. Their answer defines the research question.
-
-### 4. Spawn the Researcher
+### 4. Spawn Researcher
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
+Role: @~/.claude/agents/researcher.md
 
 <dimension>phase-specific</dimension>
 
@@ -67,27 +65,24 @@ Read your role: @~/.claude/agents/researcher.md
 
 <phase_context>
 Phase: {N}
-Goal: {phase goal from ROADMAP.md}
-Requirements: {REQ-IDs covered by this phase}
+Goal: {goal from ROADMAP.md}
+Reqs: {REQ-IDs for this phase}
 </phase_context>
 
 <project_context>
 {PROJECT.md summary}
 </project_context>
 
-<output_path>
-.planning/phase-{N}-research.md
-</output_path>
+<output_path>.planning/phase-{N}-research.md</output_path>
 
-Research using Context7 first, then WebFetch, then WebSearch. Be specific and concrete.
-Include: recommendation, rationale, version numbers (if applicable), code examples,
-alternatives considered, what to avoid, sources.
+Priority: Context7 → WebFetch → WebSearch.
+Include: recommendation, rationale, versions, code examples, alternatives, pitfalls, sources.
 ", subagent_type="qualia-researcher", description="Phase {N} research")
 ```
 
-### 5. Review Output
+### 5. Review
 
-Read `.planning/phase-{N}-research.md`. Present the key findings:
+Read `.planning/phase-{N}-research.md`. Present findings:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider
@@ -100,15 +95,15 @@ Show:
 - Top 3 key findings
 - Sources used
 
-### 6. User Confirms or Asks More
+### 6. Confirm or Continue
 
 - header: "Enough?"
-- question: "Is this enough research, or should I dig deeper?"
+- question: "Enough research, or dig deeper?"
 - options:
-  - "Enough" — Move to planning
-  - "Dig deeper" — I have more questions
+  - "Enough"
+  - "Dig deeper"
 
-If "Dig deeper" — ask what they want, re-spawn the researcher with additional questions.
+"Dig deeper" → ask what, re-spawn researcher with additional questions.
 
 ### 7. Commit
 
@@ -125,7 +120,7 @@ node ~/.claude/bin/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
 
 ## Rules
 
-1. **One research session per run.** Don't try to research phases 1 through 5 in one call.
-2. **Must produce a file.** The research is worthless if it only lives in conversation context.
-3. **Honor locked decisions from phase-{N}-context.md.** Don't research alternatives to something already locked.
-4. **Context7 first.** Always try Context7 MCP before WebFetch — it's fastest and most current for known libraries.
+1. **One session per run.** Don't research phases 1-5 in one call.
+2. **Must produce a file.** Research in conversation only is worthless.
+3. **Honor locked decisions.** Don't research alternatives to locked choices.
+4. **Context7 first.** Try Context7 MCP before WebFetch.

package/skills/qualia-road/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: qualia-road
+description: "Show the Qualia workflow map in the terminal — Project → Journey → Milestones → Phases → Tasks. Lists every command, when to use it, and how phases chain. Use when user asks 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', or is new to the framework. (For an interactive HTML reference instead, use /qualia-help.)"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+---
+
+# The Qualia Road — Project Workflow Map
+
+**Hierarchy:** Project → Journey → Milestones (2–5, Handoff always last) → Phases (2–5 tasks each) → Tasks (one commit, one verification contract).
+
+```
+/qualia-new        → kickoff + parallel research + JOURNEY.md (all milestones upfront)
+                     add --auto to chain the whole road end-to-end
+     ↓
+For each milestone, for each phase:
+  /qualia-plan     → plan the phase (planner + plan-checker revision loop, fresh context)
+  /qualia-build    → build it (builder subagents per task, wave-based parallel)
+  /qualia-verify   → goal-backward check (verifier agent, fresh context)
+     ↓
+/qualia-milestone  → close milestone, archive artifacts, prep next (human gate)
+     ↓ (repeat for each milestone until Handoff)
+
+Final milestone = Handoff:
+  /qualia-polish   → final design pass (whole app)
+  (content + SEO)  → Phase 2
+  (final QA)       → Phase 3
+  /qualia-ship     → deploy to production (quality gates → deploy → verify)
+  /qualia-handoff  → 4 deliverables: credentials, doc, final update, report
+     ↓
+Done.
+```
+
+## Design as a thread (v4.5.0+)
+Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Builders run `slop-detect` on every frontend commit. Verifiers score 8 design dimensions per phase.
+
+## /qualia-polish is scope-adaptive
+```
+/qualia-polish src/components/Button.tsx     ~30s component touch-up
+/qualia-polish app/dashboard                 ~3m  section pass
+/qualia-polish                               ~12m whole app, fan-out
+/qualia-polish --redesign                    ~30m ground-up redesign
+/qualia-polish --critique                    read-only scored audit
+/qualia-polish --quick                       ~1m  gates only
+```
+
+## /qualia-polish-loop -- autonomous visual QA (v5.1+)
+```
+/qualia-polish-loop http://localhost:3000     screenshot + eval + fix loop
+/qualia-polish-loop {url} --max 4            cap iterations
+/qualia-polish-loop {url} --ref design.png   anchor to reference image
+```
+Screenshots at 3 viewports (375/768/1440), scores 8 design dimensions using vision, fixes issues, re-screenshots, loops until all dims >= 3 or kill-switch triggers. Per-iteration git commits for clean revert.
+
+## Alignment substrate (v5.0+)
+Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
+
+```
+/qualia-discuss            → relentless one-question interview, updates CONTEXT.md inline
+/qualia-zoom               → map an unfamiliar code area using glossary terms
+/qualia-optimize --deepen  → find shallow modules, propose Ousterhout-style refactors
+/qualia-test --tdd         → vertical-slice red→green→refactor for one feature
+/qualia-issues             → break a phase plan into independent GH issues
+/qualia-triage             → label + route open issues (ready-for-agent vs human)
+/qualia-map                → adapt Qualia to an existing brownfield repo's conventions (5th onboarding agent)
+```
+
+## Auxiliary commands
+```
+Lost?        → /qualia        (state router — tells you the next command)
+Stuck/weird? → /qualia-idk    (diagnostic — spawns plan-view + code-view agents in parallel)
+Quick fix?   → /qualia-quick  (skip planning for small tasks)
+Paused?      → /qualia-resume (restore from .continue-here.md or STATE.md)
+End of day?  → /qualia-report (mandatory before clock-out; writes ERP payload)
+Debug bug?   → /qualia-debug  (feedback-loop-first investigation)
+Unsure plan? → /qualia-discuss (capture decisions before planning)
+```
+
+## Human gates
+Journey approval after `/qualia-new`, then one at each milestone boundary via `/qualia-milestone`. `--auto` runs everything between gates automatically.
+
+## Context isolation
+Every task runs in a fresh subagent context. Task 50 gets the same quality as Task 1.
+- Planner gets: PROJECT.md + CONTEXT.md + phase requirements
+- Builder gets: single task from plan + PROJECT.md + CONTEXT.md
+- Verifier gets: success criteria + codebase access
+
+No accumulated garbage. No context rot.
+
+## Quality gates (always active via hooks)
+- **Frontend guard** — Read `.planning/DESIGN.md` before any frontend changes
+- **Deploy guard** — tsc + lint + build + tests must pass before deploy
+- **Migration guard** — Catches dangerous SQL (DROP without IF EXISTS, DELETE without WHERE, CREATE TABLE without RLS)
+- **Slop-detect** — Em-dash and AI-tells check on every UI commit
+- **Intent verification** — Confirm before modifying 3+ files (OWNER role: just do it)
+
+## Tracking
+`.planning/tracking.json` is updated on every push. The ERP reads it via git.
+Never edit tracking.json manually — hooks update it from STATE.md.
+
+## Compaction — ALWAYS preserve
+Project path/name, branch, current phase, modified files, decisions, test results, in-progress work, errors, tracking.json state.