qualia-framework 2.4.0 → 2.4.2

package/framework/hooks/migration-validate.sh

@@ -10,37 +10,39 @@ if [ ! -t 0 ]; then
     fi
 fi
 
+DESTRUCTIVE=0
+WARNINGS_COUNT=0
+
 check_sql_file() {
     local file="$1"
-    local issues=0
     [ ! -f "$file" ] && return 0
 
+    # Destructive ops → block
     if grep -iE '\bDROP\s+(TABLE|SCHEMA|DATABASE)\b' "$file" > /dev/null 2>&1; then
-        q_warn "DROP TABLE/SCHEMA in ${file}"
-        issues=$((issues + 1))
+        q_fail "DROP TABLE/SCHEMA in ${file}"
+        DESTRUCTIVE=$((DESTRUCTIVE + 1))
     fi
     if grep -iE '\bTRUNCATE\b' "$file" > /dev/null 2>&1; then
-        q_warn "TRUNCATE in ${file}"
-        issues=$((issues + 1))
+        q_fail "TRUNCATE in ${file}"
+        DESTRUCTIVE=$((DESTRUCTIVE + 1))
     fi
     if grep -iE '\bDELETE\s+FROM\b' "$file" > /dev/null 2>&1 && ! grep -iE '\bWHERE\b' "$file" > /dev/null 2>&1; then
-        q_warn "DELETE without WHERE in ${file}"
-        issues=$((issues + 1))
+        q_fail "DELETE without WHERE in ${file}"
+        DESTRUCTIVE=$((DESTRUCTIVE + 1))
     fi
     if grep -iE '\bALTER\s+TABLE\b.*\bDROP\s+COLUMN\b' "$file" > /dev/null 2>&1; then
-        q_warn "DROP COLUMN in ${file}"
-        issues=$((issues + 1))
+        q_fail "DROP COLUMN in ${file}"
+        DESTRUCTIVE=$((DESTRUCTIVE + 1))
     fi
+    # Missing RLS → warn only (reminder, not destructive)
     if grep -iE '\bCREATE\s+TABLE\b' "$file" > /dev/null 2>&1 && ! grep -iE '\bENABLE\s+ROW\s+LEVEL\s+SECURITY\b' "$file" > /dev/null 2>&1; then
-        q_warn "New table needs security rules (RLS) in ${file} — tell Claude: 'add RLS policies to the new table'"
-        issues=$((issues + 1))
+        q_warn "New table needs RLS in ${file} — tell Claude: 'add RLS policies to the new table'"
+        WARNINGS_COUNT=$((WARNINGS_COUNT + 1))
     fi
-    return $issues
 }
 
 TOTAL=0
 TRIGGERED=false
-WARN_DETAILS=""
 
 # Mode 1: SQL file written
 if [ -n "$FILE_PATH" ] && [[ "$FILE_PATH" == *.sql ]]; then
@@ -59,9 +61,12 @@ if [ -n "$COMMAND" ] && echo "$COMMAND" | grep -qE 'supabase\s+db\s+push'; then
     done
 fi
 
-# Warn but don't block — surface via systemMessage
-if $TRIGGERED && [ "$TOTAL" -gt 0 ]; then
-    printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: %d issue(s) found — tell Claude to review and fix the migration warnings before proceeding."}' "$TOTAL"
+# Block on destructive ops, warn on missing RLS
+if $TRIGGERED && [ "$DESTRUCTIVE" -gt 0 ]; then
+    printf '{"continue":false,"stopReason":"◆ MIGRATION: %d destructive operation(s) blocked","systemMessage":"◆ MIGRATION BLOCKED: %d destructive operation(s) found. Tell Claude to review the SQL and confirm these operations are intentional."}' "$DESTRUCTIVE" "$DESTRUCTIVE"
+    exit 2
+elif $TRIGGERED && [ "$WARNINGS_COUNT" -gt 0 ]; then
+    printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: %d warning(s) — tell Claude to review missing RLS policies."}' "$WARNINGS_COUNT"
 elif $TRIGGERED; then
     printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: clean"}'
 fi

package/framework/hooks/pre-commit.sh

@@ -2,6 +2,12 @@
 # Pre-commit validation — secrets, debug statements, TypeScript, lint
 source "$(dirname "$0")/qualia-colors.sh"
 
+if ! command -v node &>/dev/null; then
+    [ ! -t 0 ] && cat > /dev/null
+    printf '{"continue":false,"stopReason":"PRE-COMMIT: node is not installed — cannot verify safety. Install node to proceed."}'
+    exit 2
+fi
+
 if [ ! -t 0 ]; then
     INPUT=$(cat)
     COMMAND=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_input?.command||d.tool_input||'')}catch(e){}" 2>/dev/null)
@@ -41,12 +47,14 @@ if [ -n "$ENV_FILES" ]; then
     BLOCKED=true
 fi
 
-# Debug statements in JS/TS
-JS_FILES=$(echo "$STAGED_FILES" | grep -E '\.(js|jsx|ts|tsx)$' || true)
-if [ -n "$JS_FILES" ]; then
-    for file in $JS_FILES; do
+# Debug statements in JS/TS (block in production code, allow in tests/stories)
+JS_PROD_FILES=$(echo "$STAGED_FILES" | grep -E '\.(js|jsx|ts|tsx)$' | grep -vE '\.test\.|\.spec\.|__tests__/|\.stories\.' || true)
+if [ -n "$JS_PROD_FILES" ]; then
+    for file in $JS_PROD_FILES; do
         if [ -f "$file" ] && grep -E "console\.(log|debug|info)|debugger" "$file" > /dev/null 2>&1; then
-            q_warn "Debug statement in ${file}"
+            q_fail "Debug statement in ${file}"
+            FAIL_DETAILS="${FAIL_DETAILS}Debug statement in ${file} — tell Claude: 'remove console.log/debugger from production code.' "
+            BLOCKED=true
         fi
     done
 fi

package/framework/hooks/pre-deploy-gate.sh

@@ -5,6 +5,12 @@
 
 source "$(dirname "$0")/qualia-colors.sh"
 
+if ! command -v node &>/dev/null; then
+    [ ! -t 0 ] && cat > /dev/null
+    printf '{"continue":false,"stopReason":"DEPLOY GATE: node is not installed — cannot verify safety. Install node to proceed."}'
+    exit 2
+fi
+
 # Parse command from stdin JSON
 if [ ! -t 0 ]; then
     INPUT=$(cat)
@@ -14,7 +20,7 @@ else
 fi
 
 # Only gate production deploys
-if ! echo "$COMMAND" | grep -qE 'vercel\s+.*--prod|vercel\s+--prod'; then
+if ! echo "$COMMAND" | grep -qE '(npx\s+|bunx\s+)?vercel\s+.*--prod|(npx\s+|bunx\s+)?vercel\s+--prod'; then
     exit 0
 fi
 
@@ -84,6 +90,22 @@ else
     q_pass "Environment"
 fi
 
+# ─── Check 5: Build ───
+if [ -f "package.json" ]; then
+    BUILD_SCRIPT=$(node -e "try{console.log(require('./package.json').scripts?.build||'')}catch(e){console.log('')}" 2>/dev/null)
+    if [ -n "$BUILD_SCRIPT" ]; then
+        if npm run build 2>/tmp/build-gate.txt 1>/dev/null; then
+            q_pass "Build"
+        else
+            q_fail "Build failed"
+            FAIL_DETAILS="${FAIL_DETAILS}Build is failing — tell Claude: 'fix the build errors' before deploying. "
+            FAILURES=$((FAILURES + 1))
+        fi
+    else
+        q_skip "Build"
+    fi
+fi
+
 # ─── Check 6: REVIEW.md ───
 REVIEW_FILE=""
 [ -f ".planning/REVIEW.md" ] && REVIEW_FILE=".planning/REVIEW.md"

package/framework/hooks/retention-cleanup.sh

@@ -10,7 +10,7 @@
 #   paste-cache/      3 days
 #   shell-snapshots/  3 days
 #   projects/*.jsonl  7 days
-#   tasks/            3 days
+#   tasks/            14 days
 #   plans/            7 days
 
 CLAUDE_DIR="$HOME/.claude"
@@ -37,9 +37,9 @@ find "$CLAUDE_DIR/shell-snapshots/" -type f -mtime +3 -delete 2>/dev/null
 find "$CLAUDE_DIR/projects/" -name "*.jsonl" -mtime +7 -delete 2>/dev/null
 find "$CLAUDE_DIR/projects/" -type d -empty -delete 2>/dev/null
 
-# tasks/ — keep 3 days (stale task files from old sessions)
-find "$CLAUDE_DIR/tasks/" -type f -mtime +3 -delete 2>/dev/null
-find "$CLAUDE_DIR/tasks/" -type d -empty -delete 2>/dev/null
+# tasks/ — keep 14 days (team sessions may span multiple days)
+find "$CLAUDE_DIR/tasks/" -type f -mtime +14 -delete 2>/dev/null
+find "$CLAUDE_DIR/tasks/" -mindepth 1 -type d -empty -delete 2>/dev/null
 
 # plans/ — keep 7 days (old Claude Code plan mode files)
 find "$CLAUDE_DIR/plans/" -type f -mtime +7 -delete 2>/dev/null

package/framework/hooks/save-session-state.sh

@@ -82,14 +82,17 @@ if [ "$PROJECT_NAME" != ".claude" ] && [ "$PROJECT_NAME" != "Projects" ] && { [
 
     # Dedup: skip if ANY existing entry has the same project + branch + summary
     NEW_KEY="${PROJECT_NAME}|${GIT_BRANCH:-—}|${SUMMARY:-—}"
-    if tail -n +4 "$DIGEST_FILE" | while IFS= read -r line; do
+    DUPLICATE=false
+    while IFS= read -r line; do
         ENTRY_KEY=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); gsub(/^ +| +$/,"",$4); gsub(/^ +| +$/,"",$6); print $3"|"$4"|"$6}')
-        [ "$ENTRY_KEY" = "$NEW_KEY" ] && exit 0
-    done; then
-        : # no match found, continue
+        if [ "$ENTRY_KEY" = "$NEW_KEY" ]; then
+            DUPLICATE=true
+            break
+        fi
+    done < <(tail -n +4 "$DIGEST_FILE")
+    if [ "$DUPLICATE" = "true" ]; then
+        : # duplicate found, skip adding to digest
     else
-        exit 0  # duplicate found, skip
-    fi
 
     # Read existing entries (skip header — first 3 lines), keep last 19
     EXISTING=$(tail -n +4 "$DIGEST_FILE" | head -19)
@@ -101,6 +104,7 @@ if [ "$PROJECT_NAME" != ".claude" ] && [ "$PROJECT_NAME" != "Projects" ] && { [
 ${ENTRY}
 ${EXISTING}
 HEADER
+    fi
 fi
 
 # --- Auto-handoff for significant sessions (>5 files changed) ---
@@ -156,15 +160,19 @@ HANDOFF
     fi
 fi
 
-# --- Push to portal (non-blocking, fire-and-forget) ---
+# --- Push to portal (with error tracking) ---
 PORTAL_API_KEY="${CLAUDE_PORTAL_API_KEY:-}"
 if [ -n "$PORTAL_API_KEY" ] && [ "$PROJECT_NAME" != ".claude" ]; then
-    curl -s -X POST "https://portal.qualiasolutions.net/api/claude/session-log" \
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "https://portal.qualiasolutions.net/api/claude/session-log" \
         -H "X-API-Key: $PORTAL_API_KEY" \
         -H "Content-Type: application/json" \
         -d @"$SESSION_FILE" \
-        --max-time 5 \
-        > /dev/null 2>&1 &
+        --max-time 5 2>/dev/null || echo "000")
+    if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ]; then
+        rm -f "$SESSION_DIR/.portal-last-error"
+    else
+        echo "$HTTP_CODE" > "$SESSION_DIR/.portal-last-error"
+    fi
 fi
 
 # --- Cleanup old session files (keep last 50 for retrospective analytics — RETR-04) ---

package/framework/hooks/session-context-loader.sh

@@ -62,6 +62,27 @@ if [ -f "$HOME/.claude/settings.json" ]; then
     fi
 fi
 
+# Check for stale knowledge files (>30 days old)
+STALE_COUNT=0
+STALE_NAMES=""
+for kf in "$HOME/.claude/knowledge"/*.md; do
+    [ -f "$kf" ] || continue
+    KF_AGE=$(( ($(date +%s) - $(stat -c %Y "$kf" 2>/dev/null || echo 0)) / 86400 ))
+    if [ "$KF_AGE" -gt 30 ]; then
+        STALE_COUNT=$((STALE_COUNT + 1))
+        STALE_NAMES="${STALE_NAMES} $(basename "$kf")(${KF_AGE}d)"
+    fi
+done
+if [ "$STALE_COUNT" -gt 0 ]; then
+    ISSUES="${ISSUES}${STALE_COUNT} stale knowledge file(s):${STALE_NAMES}. "
+fi
+
+# Check portal sync health
+if [ -f "$SESSION_DIR/.portal-last-error" ]; then
+    PORTAL_ERR=$(cat "$SESSION_DIR/.portal-last-error" 2>/dev/null)
+    ISSUES="${ISSUES}Portal sync failed (HTTP ${PORTAL_ERR}). "
+fi
+
 if [ -n "$ISSUES" ]; then
     MSG="${MSG} | ▲ ${ISSUES}"
 fi

package/framework/hooks/skill-announce.sh

@@ -29,6 +29,7 @@ SKILL_DESC=(
     # Navigation
     ["qualia-start"]="Activating Qualia mode"
     ["qualia-progress"]="Checking progress"
+    ["qualia-guide"]="Showing developer guide"
     ["qualia-idk"]="Analyzing next steps"
     ["qualia"]="Routing to next action"
     ["qualia-resume-work"]="Restoring session context"
@@ -36,6 +37,7 @@ SKILL_DESC=(
     # Quality
     ["qualia-review"]="Running code review"
     ["qualia-optimize"]="Running optimization pass"
+    ["qualia-evolve"]="Evolving framework"
     ["qualia-production-check"]="Running production audit"
     ["qualia-framework-audit"]="Auditing framework"
     ["deep-research"]="Spawning research agents"

package/framework/install.ps1

@@ -87,10 +87,10 @@ $dirs = @(
     "$ClaudeDir\hooks",
     "$ClaudeDir\rules",
     "$ClaudeDir\knowledge\retros",
-    "$ClaudeDir\qualia-engine\bin",
-    "$ClaudeDir\qualia-engine\references",
-    "$ClaudeDir\qualia-engine\templates",
-    "$ClaudeDir\qualia-engine\workflows",
+    "$ClaudeDir\qualia-framework\bin",
+    "$ClaudeDir\qualia-framework\references",
+    "$ClaudeDir\qualia-framework\templates",
+    "$ClaudeDir\qualia-framework\workflows",
     "$ClaudeDir\projects",
     "$ClaudeDir\session-env"
 )
@@ -129,7 +129,7 @@ $hookCount = (Get-ChildItem "$ClaudeDir\hooks\*.sh" -ErrorAction SilentlyContinu
 Write-Host "  + $hookCount hooks" -ForegroundColor Green
 
 # Qualia Engine
-Copy-Item "$ScriptDir\qualia-engine\*" "$ClaudeDir\qualia-engine\" -Recurse -Force -ErrorAction SilentlyContinue
+Copy-Item "$ScriptDir\qualia-framework\*" "$ClaudeDir\qualia-framework\" -Recurse -Force -ErrorAction SilentlyContinue
 Write-Host "  + Qualia engine" -ForegroundColor Green
 
 # Rules
@@ -273,7 +273,7 @@ $criticalFiles = @(
     "skills\qualia-start\SKILL.md",
     "skills\browser-qa\SKILL.md",
     "skills\ship\SKILL.md",
-    "qualia-engine\bin\qualia-tools.js",
+    "qualia-framework\bin\qualia-tools.js",
     "CLAUDE.md"
 )
 

package/framework/install.sh

@@ -90,7 +90,7 @@ printf "\n"
 # ─── Step 2: Create directory structure ───
 printf "${Q_WARN}[2/6] Directory structure${Q_RESET}\n"
 
-mkdir -p "$CLAUDE_DIR"/{skills,agents,hooks,rules,knowledge/retros,qualia-engine/{bin,references,templates,workflows},projects,session-env}
+mkdir -p "$CLAUDE_DIR"/{skills,agents,hooks,rules,knowledge/retros,qualia-framework/{bin,references,templates,workflows},projects,session-env}
 
 printf "${Q_PASS}  ✓ Ready${Q_RESET}\n"
 
@@ -123,7 +123,9 @@ HOOK_COUNT=$(find "$CLAUDE_DIR/hooks" -name "*.sh" -type f | wc -l)
 printf "${Q_PASS}  ✓ $HOOK_COUNT hooks${Q_RESET}\n"
 
 # Qualia Engine
-cp -r "$SCRIPT_DIR"/qualia-engine/* "$CLAUDE_DIR/qualia-engine/" 2>/dev/null || true
+cp -r "$SCRIPT_DIR"/qualia-engine/* "$CLAUDE_DIR/qualia-framework/" 2>/dev/null || true
+# Clean up old path if it exists from previous installs
+[ -d "$CLAUDE_DIR/qualia-engine" ] && rm -rf "$CLAUDE_DIR/qualia-engine"
 printf "${Q_PASS}  ✓ Qualia engine${Q_RESET}\n"
 
 # Rules
@@ -232,7 +234,7 @@ fi
 printf "${Q_WARN}[5/6] Platform setup${Q_RESET}\n"
 
 # Make qualia-tools executable
-[ -f "$CLAUDE_DIR/qualia-engine/bin/qualia-tools.js" ] && chmod +x "$CLAUDE_DIR/qualia-engine/bin/qualia-tools.js"
+[ -f "$CLAUDE_DIR/qualia-framework/bin/qualia-tools.js" ] && chmod +x "$CLAUDE_DIR/qualia-framework/bin/qualia-tools.js"
 
 # Askpass helper (works with zenity, kdialog, or falls back to terminal)
 if [ ! -f "$CLAUDE_DIR/askpass.sh" ]; then
@@ -273,7 +275,7 @@ for check in \
     "skills/qualia-start/SKILL.md" \
     "skills/browser-qa/SKILL.md" \
     "skills/ship/SKILL.md" \
-    "qualia-engine/bin/qualia-tools.js" \
+    "qualia-framework/bin/qualia-tools.js" \
     "CLAUDE.md"; do
     if [ ! -f "$CLAUDE_DIR/$check" ]; then
         printf "${Q_FAIL}  ✗ Missing: $check${Q_RESET}\n"

package/framework/qualia-engine/VERSION

@@ -1 +1 @@
-2.4.0
+2.4.2

package/framework/qualia-engine/bin/collect-metrics.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# Qualia Framework Metrics Collection
+# Run after a project ships to capture performance data.
+# Usage: collect-metrics.sh [project-dir]
+# Output: appends to ~/.claude/knowledge/framework-metrics.md
+
+PROJECT_DIR="${1:-.}"
+METRICS_FILE="$HOME/.claude/knowledge/framework-metrics.md"
+DATE=$(date +%Y-%m-%d)
+
+# Ensure metrics file exists
+if [ ! -f "$METRICS_FILE" ]; then
+  cat > "$METRICS_FILE" << 'HEADER'
+# Framework Performance Metrics
+
+> Auto-collected after each project ships. Read by `/qualia-evolve` to optimize the framework.
+
+| Date | Project | Phases | Sessions | Deviations | IDK Calls | Verify Pass Rate | Lab Notes | FQS |
+|------|---------|--------|----------|------------|-----------|-----------------|-----------|-----|
+HEADER
+fi
+
+cd "$PROJECT_DIR" || exit 1
+
+# Project name
+PROJECT=$(basename "$(pwd)")
+
+# Phase count
+PHASES=$(ls -d .planning/phases/*/ 2>/dev/null | wc -l)
+
+# Session count (from session-digest entries for this project)
+SESSIONS=$(grep -c "$PROJECT" ~/.claude/knowledge/session-digest.md 2>/dev/null || echo "?")
+
+# Deviation count (gap-fix plans)
+DEVIATIONS=$(find .planning/phases/ -name "*-PLAN.md" -exec grep -l "gaps" {} \; 2>/dev/null | wc -l)
+
+# IDK calls (search session digest for qualia-idk mentions with this project)
+IDK_CALLS=$(grep "$PROJECT" ~/.claude/knowledge/session-digest.md 2>/dev/null | grep -c "idk\|stuck\|lost" || echo "0")
+
+# Verify pass rate (UAT files with PASSED vs total UAT files)
+TOTAL_UAT=$(find .planning/phases/ -name "*-UAT.md" 2>/dev/null | wc -l)
+PASSED_UAT=$(grep -rl "PASSED\|✅.*Overall" .planning/phases/*/*.md 2>/dev/null | wc -l)
+if [ "$TOTAL_UAT" -gt 0 ]; then
+  PASS_RATE=$(( PASSED_UAT * 100 / TOTAL_UAT ))%
+else
+  PASS_RATE="n/a"
+fi
+
+# Lab Notes count
+LAB_NOTES=$(grep -c "^###" .planning/lab-notes.md 2>/dev/null || echo "0")
+
+# Completion rate from ROADMAP.md (actual, not assumed)
+TOTAL_PLANS=$(grep -c "^- \[" .planning/ROADMAP.md 2>/dev/null || echo "0")
+COMPLETED_PLANS=$(grep -c "^- \[x\]" .planning/ROADMAP.md 2>/dev/null || echo "0")
+if [ "$TOTAL_PLANS" -gt 0 ]; then
+  COMPLETION_RATE=$(( COMPLETED_PLANS * 100 / TOTAL_PLANS ))
+else
+  COMPLETION_RATE=100
+fi
+
+# FQS = completion_rate / avg_sessions_to_ship * 100 (per OBJECTIVE.md)
+if [ "$SESSIONS" != "?" ] && [ "$SESSIONS" -gt 0 ]; then
+  FQS=$(( COMPLETION_RATE * 100 / SESSIONS ))
+else
+  FQS="?"
+fi
+
+# Append to metrics file
+echo "| $DATE | $PROJECT | $PHASES | $SESSIONS | $DEVIATIONS | $IDK_CALLS | $PASS_RATE | $LAB_NOTES | $FQS |" >> "$METRICS_FILE"
+
+echo "Metrics collected for $PROJECT → $METRICS_FILE"

package/framework/qualia-engine/bin/qualia-tools.js

@@ -99,7 +99,8 @@ function loadConfig(cwd) {
       verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
       parallelization,
     };
-  } catch {
+  } catch (e) {
+    process.stderr.write(`WARNING: .planning/config.json is malformed or unreadable, using defaults: ${e.message}\n`);
     return defaults;
   }
 }
@@ -884,8 +885,8 @@ function cmdCommit(cwd, message, files, raw) {
       output(result, raw, 'nothing');
       return;
     }
-    const result = { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr };
-    output(result, raw, 'nothing');
+    const result = { committed: false, hash: null, reason: 'commit_failed', error: commitResult.stderr };
+    output(result, raw, 'COMMIT FAILED: ' + (commitResult.stderr || 'unknown error'));
     return;
   }
 
@@ -1156,79 +1157,95 @@ function cmdStateSnapshot(cwd, raw) {
 
   const content = fs.readFileSync(statePath, 'utf-8');
 
-  // Helper to extract **Field:** value patterns
-  const extractField = (fieldName) => {
-    const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, 'i');
-    const match = content.match(pattern);
-    return match ? match[1].trim() : null;
-  };
+  // Parse "Phase: X of Y (Name)" or "Phase: X of Y ([Name])"
+  let currentPhase = null, totalPhases = null, currentPhaseName = null;
+  const phaseMatch = content.match(/^Phase:\s*(\d+(?:\.\d+)?)\s*of\s*(\d+)\s*\(([^)]+)\)/m);
+  if (phaseMatch) {
+    currentPhase = phaseMatch[1];
+    totalPhases = parseInt(phaseMatch[2], 10);
+    currentPhaseName = phaseMatch[3].trim();
+  }
+
+  // Parse "Plan: A of B in current phase" or "Plan: Not started" or "Plan: All plans complete"
+  let currentPlan = null, totalPlansInPhase = null;
+  const planMatch = content.match(/^Plan:\s*(\d+)\s*of\s*(\d+)/m);
+  if (planMatch) {
+    currentPlan = planMatch[1];
+    totalPlansInPhase = parseInt(planMatch[2], 10);
+  } else {
+    const planAlt = content.match(/^Plan:\s*(.+)/m);
+    if (planAlt) currentPlan = planAlt[1].trim();
+  }
+
+  // Parse "Status: ..."
+  let status = null;
+  const statusMatch = content.match(/^Status:\s*(.+)/m);
+  if (statusMatch) status = statusMatch[1].trim();
+
+  // Parse "Last activity: DATE — Description"
+  let lastActivity = null, lastActivityDesc = null;
+  const activityMatch = content.match(/^Last activity:\s*(\S+)\s*(?:—|--)\s*(.+)/m);
+  if (activityMatch) {
+    lastActivity = activityMatch[1].trim();
+    lastActivityDesc = activityMatch[2].trim();
+  }
+
+  // Parse "Progress: [...] N%" — extract percentage
+  let progressPercent = null;
+  const progressMatch = content.match(/(\d+)%/);
+  if (progressMatch) progressPercent = parseInt(progressMatch[1], 10);
+
+  // Parse "Assigned to: ..."
+  let assignedTo = null;
+  const assignedMatch = content.match(/^Assigned to:\s*(.+)/m);
+  if (assignedMatch) assignedTo = assignedMatch[1].trim();
 
-  // Extract basic fields
-  const currentPhase = extractField('Current Phase');
-  const currentPhaseName = extractField('Current Phase Name');
-  const totalPhasesRaw = extractField('Total Phases');
-  const currentPlan = extractField('Current Plan');
-  const totalPlansRaw = extractField('Total Plans in Phase');
-  const status = extractField('Status');
-  const progressRaw = extractField('Progress');
-  const lastActivity = extractField('Last Activity');
-  const lastActivityDesc = extractField('Last Activity Description');
-  const pausedAt = extractField('Paused At');
-
-  // Parse numeric fields
-  const totalPhases = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
-  const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
-  const progressPercent = progressRaw ? parseInt(progressRaw.replace('%', ''), 10) : null;
-
-  // Extract decisions table
+  // Extract decisions from "### Decisions" section
+  // Format: "- [Phase X]: decision summary" or "- [Pre-roadmap]: decision"
   const decisions = [];
-  const decisionsMatch = content.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
-  if (decisionsMatch) {
-    const tableBody = decisionsMatch[1];
-    const rows = tableBody.trim().split('\n').filter(r => r.includes('|'));
-    for (const row of rows) {
-      const cells = row.split('|').map(c => c.trim()).filter(Boolean);
-      if (cells.length >= 3) {
+  const decisionsSection = content.match(/###\s*Decisions\s*\n([\s\S]*?)(?=\n###|\n##|$)/i);
+  if (decisionsSection) {
+    const lines = decisionsSection[1].split('\n');
+    for (const line of lines) {
+      const decMatch = line.match(/^-\s+\[([^\]]+)\]:\s*(.+)/);
+      if (decMatch) {
         decisions.push({
-          phase: cells[0],
-          summary: cells[1],
-          rationale: cells[2],
+          phase: decMatch[1].trim(),
+          summary: decMatch[2].trim(),
+          rationale: '',
         });
       }
     }
   }
 
-  // Extract blockers list
+  // Extract blockers from "### Blockers/Concerns" section
   const blockers = [];
-  const blockersMatch = content.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
-  if (blockersMatch) {
-    const blockersSection = blockersMatch[1];
-    const items = blockersSection.match(/^-\s+(.+)$/gm) || [];
+  const blockersSection = content.match(/###\s*Blockers\/Concerns\s*\n([\s\S]*?)(?=\n###|\n##|$)/i);
+  if (blockersSection) {
+    const items = blockersSection[1].match(/^-\s+(.+)$/gm) || [];
     for (const item of items) {
-      blockers.push(item.replace(/^-\s+/, '').trim());
+      const text = item.replace(/^-\s+/, '').trim();
+      if (text && !text.match(/^none/i)) blockers.push(text);
     }
   }
 
-  // Extract session info
-  const session = {
-    last_date: null,
-    stopped_at: null,
-    resume_file: null,
-  };
-
-  const sessionMatch = content.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
-  if (sessionMatch) {
-    const sessionSection = sessionMatch[1];
-    const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i);
-    const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i);
-    const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i);
-
+  // Extract session info from "## Session Continuity"
+  const session = { last_date: null, stopped_at: null, resume_file: null };
+  const sessionSection = content.match(/##\s*Session Continuity\s*\n([\s\S]*?)(?=\n##|$)/i);
+  if (sessionSection) {
+    const sec = sessionSection[1];
+    const lastDateMatch = sec.match(/^Last session:\s*(.+)/m);
+    const stoppedAtMatch = sec.match(/^Stopped at:\s*(.+)/m);
+    const resumeFileMatch = sec.match(/^Resume file:\s*(.+)/m);
     if (lastDateMatch) session.last_date = lastDateMatch[1].trim();
     if (stoppedAtMatch) session.stopped_at = stoppedAtMatch[1].trim();
-    if (resumeFileMatch) session.resume_file = resumeFileMatch[1].trim();
+    if (resumeFileMatch) {
+      const rf = resumeFileMatch[1].trim();
+      session.resume_file = rf.toLowerCase() === 'none' ? null : rf;
+    }
   }
 
-  const result = {
+  output({
     current_phase: currentPhase,
     current_phase_name: currentPhaseName,
     total_phases: totalPhases,
@@ -1238,13 +1255,11 @@ function cmdStateSnapshot(cwd, raw) {
     progress_percent: progressPercent,
     last_activity: lastActivity,
     last_activity_desc: lastActivityDesc,
+    assigned_to: assignedTo,
     decisions,
     blockers,
-    paused_at: pausedAt,
     session,
-  };
-
-  output(result, raw);
+  }, raw);
 }
 
 function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
@@ -2152,6 +2167,32 @@ function main() {
       break;
     }
 
+    case '--help':
+    case 'help': {
+      const cmds = [
+        'state load                — Load project state + config as JSON',
+        'state-snapshot            — Structured snapshot of STATE.md fields',
+        'resolve-model <agent>     — Resolve model for agent from profile',
+        'find-phase <number>       — Find phase directory path',
+        'commit <msg> --files ..   — Commit with planning-aware logic',
+        'verify-summary <path>     — Verify SUMMARY.md completeness',
+        'generate-slug <text>      — Generate URL-safe slug',
+        'current-timestamp         — ISO timestamp',
+        'list-todos [area]         — List pending todos',
+        'verify-path-exists <path> — Check if path exists',
+        'config-ensure-section     — Ensure config section exists',
+        'init <workflow> [args]    — Initialize workflow context',
+        'roadmap get-phase <N>     — Get phase details from ROADMAP.md',
+        'phase-plan-index <N>      — Get plan inventory with wave grouping',
+        'summary-extract <path>    — Extract fields from SUMMARY.md',
+      ];
+      console.log('qualia-tools v2.4.1\n');
+      console.log('Usage: qualia-tools <command> [args] [--raw]\n');
+      console.log('Commands:');
+      cmds.forEach(c => console.log('  ' + c));
+      process.exit(0);
+    }
+
     default:
       error(`Unknown command: ${command}`);
   }