qualia-framework 2.2.1 → 2.4.1

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 without RLS in ${file}"
-        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 — review carefully"}' "$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)
@@ -28,7 +34,7 @@ SECRETS_PATTERN="(api[_-]?key|apikey|secret[_-]?key|password|passwd|pwd|token|au
 for file in $STAGED_FILES; do
     if [ -f "$file" ] && grep -iE "$SECRETS_PATTERN" "$file" > /dev/null 2>&1; then
         q_fail "Secret in ${file}"
-        FAIL_DETAILS="${FAIL_DETAILS}Potential secret in ${file}. "
+        FAIL_DETAILS="${FAIL_DETAILS}A password or API key was found in ${file} — tell Claude: 'remove the secret and use an environment variable instead.' "
         BLOCKED=true
     fi
 done
@@ -37,16 +43,18 @@ done
 ENV_FILES=$(echo "$STAGED_FILES" | grep -E '\.env($|\.)' | grep -v '.example' | grep -v '.sample' || true)
 if [ -n "$ENV_FILES" ]; then
     q_fail ".env file staged: ${ENV_FILES}"
-    FAIL_DETAILS="${FAIL_DETAILS}.env file staged for commit. "
+    FAIL_DETAILS="${FAIL_DETAILS}.env file contains secrets and shouldn't be committed — tell Claude: 'unstage the .env file.' "
     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
@@ -70,7 +78,7 @@ if [ -f "tsconfig.json" ]; then
                 touch "$TSC_STAMP"
             else
                 q_fail "TypeScript errors"
-                FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors. Run npx tsc --noEmit. "
+                FAIL_DETAILS="${FAIL_DETAILS}Code errors found — tell Claude: 'fix the TypeScript errors and try committing again.' "
                 BLOCKED=true
             fi
         fi
@@ -82,7 +90,7 @@ if $BLOCKED; then
 {
   "continue": false,
   "stopReason": "◆ Pre-commit: blocked",
-  "systemMessage": "◆ PRE-COMMIT BLOCKED: ${FAIL_DETAILS}Fix issues, stage corrected files, and retry."
+  "systemMessage": "◆ PRE-COMMIT BLOCKED: ${FAIL_DETAILS}Tell Claude to fix these issues and try committing again."
 }
 EOJSON
     exit 2

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,10 +20,11 @@ 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
 
+
 # Skip if gate was passed recently (within 5 minutes)
 STAMP="/tmp/.deploy-gate-$(echo "$PWD" | md5sum | cut -c1-8)"
 if [ -f "$STAMP" ]; then
@@ -39,7 +46,7 @@ if [ -f "tsconfig.json" ]; then
         q_pass "TypeScript"
     else
         q_fail "TypeScript errors"
-        FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors found. Run npx tsc --noEmit to see details. "
+        FAIL_DETAILS="${FAIL_DETAILS}Code errors found — tell Claude: 'fix the TypeScript errors' before deploying. "
         FAILURES=$((FAILURES + 1))
     fi
 else
@@ -52,7 +59,7 @@ if [ -f ".eslintrc.json" ] || [ -f ".eslintrc.js" ] || [ -f "eslint.config.js" ]
         q_pass "Lint"
     else
         q_fail "Lint errors"
-        FAIL_DETAILS="${FAIL_DETAILS}ESLint errors found. Run npx eslint . to see details. "
+        FAIL_DETAILS="${FAIL_DETAILS}Code quality issues found — tell Claude: 'fix the lint errors' before deploying. "
         FAILURES=$((FAILURES + 1))
     fi
 else
@@ -67,7 +74,7 @@ if [ -f "package.json" ]; then
             q_pass "Tests"
         else
             q_fail "Tests failed"
-            FAIL_DETAILS="${FAIL_DETAILS}Tests failed. Run npm test to see details. "
+            FAIL_DETAILS="${FAIL_DETAILS}Tests are failing — tell Claude: 'fix the failing tests' before deploying. "
             FAILURES=$((FAILURES + 1))
         fi
     else
@@ -75,7 +82,15 @@ if [ -f "package.json" ]; then
     fi
 fi
 
-# ─── Check 4: Build ───
+# ─── Check 4: Environment ───
+if [ -f ".env.example" ] && [ ! -f ".env.local" ] && [ ! -f ".env" ]; then
+    q_warn "Missing .env.local"
+    WARNINGS=$((WARNINGS + 1))
+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
@@ -83,7 +98,7 @@ if [ -f "package.json" ]; then
             q_pass "Build"
         else
             q_fail "Build failed"
-            FAIL_DETAILS="${FAIL_DETAILS}Build failed. Run npm run build to see errors. "
+            FAIL_DETAILS="${FAIL_DETAILS}Build is failing — tell Claude: 'fix the build errors' before deploying. "
             FAILURES=$((FAILURES + 1))
         fi
     else
@@ -91,14 +106,6 @@ if [ -f "package.json" ]; then
     fi
 fi
 
-# ─── Check 5: Environment ───
-if [ -f ".env.example" ] && [ ! -f ".env.local" ] && [ ! -f ".env" ]; then
-    q_warn "Missing .env.local"
-    WARNINGS=$((WARNINGS + 1))
-else
-    q_pass "Environment"
-fi
-
 # ─── Check 6: REVIEW.md ───
 REVIEW_FILE=""
 [ -f ".planning/REVIEW.md" ] && REVIEW_FILE=".planning/REVIEW.md"
@@ -132,7 +139,7 @@ if [ "$FAILURES" -gt 0 ]; then
 {
   "continue": false,
   "stopReason": "◆ Deploy gate: ${FAILURES} check(s) failed",
-  "systemMessage": "◆ DEPLOY BLOCKED: ${FAILURES} check(s) failed. ${FAIL_DETAILS}Fix and retry vercel --prod."
+  "systemMessage": "◆ DEPLOY BLOCKED: ${FAILURES} check(s) failed. ${FAIL_DETAILS}Fix issues and retry with /ship."
 }
 EOJSON
     exit 2

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.sh

@@ -150,14 +150,13 @@ elif [ ! -f "$CLAUDE_DIR/CLAUDE.md" ]; then
 ## Identity
 **$ROLE_NAME** — Developer at Qualia Solutions.
 
-- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, VAPI, ElevenLabs, Telnyx, Retell AI, OpenRouter
+- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, Retell AI, ElevenLabs, Telnyx, OpenRouter
 
 ## Role: DEVELOPER
 
 You are a developer at Qualia Solutions, working under Fawzi Goussous (founder).
 - Work on feature branches only — never push to main/master
-- Submit PRs for review before merging
-- Do NOT deploy to production — Fawzi handles deploys
+- Use \`/ship\` to deploy — it runs quality gates, auto-creates feature branches, and deploys
 - Cannot modify the Qualia framework (CLAUDE.md, skills, hooks)
 - Ask Fawzi when unsure about architecture decisions
 
@@ -169,10 +168,16 @@ You are a developer at Qualia Solutions, working under Fawzi Goussous (founder).
 - See \`rules/security.md\` for auth, RLS, Zod, secrets rules
 - See \`rules/frontend.md\` for design standards
 
+## Getting Started
+- Run \`/collab-onboard\` when joining a new project — it explains what's built and how to contribute
+- Onboarding guide: ~/Projects/qualia-erp/docs/trainee-onboarding.md
+
 ## Workflow
 - **MANDATORY FIRST ACTION**: On every session start, invoke the \`qualia-start\` skill before doing anything else.
-- Run \`/qualia-review\` before deploying anything
+- Run \`/qualia-review\` before deploying
 - Run \`/browser-qa\` after frontend changes
+- Run \`/pr\` to submit work for review — never push to main directly
+- Run \`/qualia-idk\` if stuck — it suggests next steps and can escalate to Fawzi
 - Ask for help if stuck — don't guess
 
 ## Qualia Mode (always active)

package/framework/qualia-engine/VERSION

@@ -1 +1 @@
-1.14.0
+2.4.1

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"