qualia-framework 4.0.3 → 4.1.0

package/skills/qualia-report/SKILL.md

@@ -12,6 +12,11 @@ allowed-tools:
 
 Generate a concise report of what was done. Committed to git and uploaded to the ERP for clock-out.
 
+## 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.
+
 ## Process
 
 ```bash
@@ -69,16 +74,33 @@ None. / - {blocker}
 {list from git log}
 ```
 
-### 4. Commit and Push
+### 4. Obtain Client Report ID (QS-REPORT-NN)
+
+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`.
 
 ```bash
-mkdir -p .planning/reports
-git add .planning/reports/report-{date}.md
-git commit -m "report: session {YYYY-MM-DD}"
-git push
+# --dry-run: peek without incrementing
+if [ "$DRY_RUN" = "true" ]; then
+  CLIENT_REPORT_ID=$(node ~/.claude/bin/state.js next-report-id --peek 2>/dev/null | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0,'utf8')).report_id||'')")
+else
+  CLIENT_REPORT_ID=$(node ~/.claude/bin/state.js next-report-id 2>/dev/null | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0,'utf8')).report_id||'')")
+fi
 ```
 
-### 5. Upload to ERP (if enabled)
+Example: first report on a fresh project → `QS-REPORT-01`. Next → `QS-REPORT-02`. Etc.
+
+### 5. Commit and Push (SKIP on --dry-run)
+
+```bash
+if [ "$DRY_RUN" != "true" ]; 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
+fi
+```
+
+### 6. Upload to ERP (SKIP on --dry-run)
 
 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)."
@@ -94,67 +116,126 @@ REPORT_FILE=".planning/reports/report-{date}.md"
 SUBMITTED_BY=$(git config user.name)
 SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
-# Only upload if ERP is enabled
+# Build structured JSON payload from tracking.json (matches ERP contract /api/v1/reports)
+# v4: include milestone_name, milestones[], team_id, project_id, git_remote,
+# session_started_at, last_pushed_at, build_count, deploy_count — the ERP
+# uses these to render the project tree (milestone → phases → unphased) correctly.
+# v4.0.4: client_report_id carries the QS-REPORT-NN identifier.
+PAYLOAD=$(node -e "
+  const fs = require('fs');
+  const t = JSON.parse(fs.readFileSync('.planning/tracking.json', 'utf8'));
+  const notes = fs.readFileSync('$REPORT_FILE', 'utf8').substring(0, 60000);
+  const commits = [];
+  try {
+    const { spawnSync } = require('child_process');
+    const r = spawnSync('git', ['log', '--oneline', '--since=8 hours ago', '--format=%h'], { encoding: 'utf8', timeout: 3000 });
+    if (r.stdout) commits.push(...r.stdout.trim().split('\n').filter(Boolean));
+  } catch {}
+  console.log(JSON.stringify({
+    project: t.project || require('path').basename(process.cwd()),
+    project_id: t.project_id || '',
+    team_id: t.team_id || '',
+    git_remote: t.git_remote || '',
+    client: t.client || '',
+    client_report_id: '$CLIENT_REPORT_ID',
+    milestone: t.milestone || 1,
+    milestone_name: t.milestone_name || '',
+    milestones: Array.isArray(t.milestones) ? t.milestones : [],
+    phase: t.phase,
+    phase_name: t.phase_name,
+    total_phases: t.total_phases,
+    status: t.status,
+    tasks_done: t.tasks_done || 0,
+    tasks_total: t.tasks_total || 0,
+    verification: t.verification || 'pending',
+    gap_cycles: (t.gap_cycles || {})[String(t.phase)] || 0,
+    build_count: t.build_count || 0,
+    deploy_count: t.deploy_count || 0,
+    deployed_url: t.deployed_url || '',
+    session_started_at: t.session_started_at || '',
+    last_pushed_at: t.last_pushed_at || '',
+    lifetime: t.lifetime || {},
+    commits: commits,
+    notes: notes,
+    submitted_by: '$SUBMITTED_BY',
+    submitted_at: '$SUBMITTED_AT'
+  }));
+")
+
+# --dry-run: print payload and stop (no POST, no commit, no increment already handled in step 4)
+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 · 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.
 if [ "$ERP_ENABLED" = "true" ]; then
-  # 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.
-  PAYLOAD=$(node -e "
-    const fs = require('fs');
-    const t = JSON.parse(fs.readFileSync('.planning/tracking.json', 'utf8'));
-    const notes = fs.readFileSync('$REPORT_FILE', 'utf8').substring(0, 60000);
-    const commits = [];
-    try {
-      const { spawnSync } = require('child_process');
-      const r = spawnSync('git', ['log', '--oneline', '--since=8 hours ago', '--format=%h'], { encoding: 'utf8', timeout: 3000 });
-      if (r.stdout) commits.push(...r.stdout.trim().split('\n').filter(Boolean));
-    } catch {}
-    console.log(JSON.stringify({
-      project: t.project || require('path').basename(process.cwd()),
-      project_id: t.project_id || '',
-      team_id: t.team_id || '',
-      git_remote: t.git_remote || '',
-      client: t.client || '',
-      milestone: t.milestone || 1,
-      milestone_name: t.milestone_name || '',
-      milestones: Array.isArray(t.milestones) ? t.milestones : [],
-      phase: t.phase,
-      phase_name: t.phase_name,
-      total_phases: t.total_phases,
-      status: t.status,
-      tasks_done: t.tasks_done || 0,
-      tasks_total: t.tasks_total || 0,
-      verification: t.verification || 'pending',
-      gap_cycles: (t.gap_cycles || {})[String(t.phase)] || 0,
-      build_count: t.build_count || 0,
-      deploy_count: t.deploy_count || 0,
-      deployed_url: t.deployed_url || '',
-      session_started_at: t.session_started_at || '',
-      last_pushed_at: t.last_pushed_at || '',
-      lifetime: t.lifetime || {},
-      commits: commits,
-      notes: notes,
-      submitted_by: '$SUBMITTED_BY',
-      submitted_at: '$SUBMITTED_AT'
-    }));
-  ")
-
-  curl -s -X POST "$ERP_URL/api/v1/reports" \
-    -H "Authorization: Bearer $API_KEY" \
-    -H "Content-Type: application/json" \
-    -d "$PAYLOAD"
+  MAX_ATTEMPTS=3
+  ATTEMPT=1
+  SUCCESS=false
+  while [ $ATTEMPT -le $MAX_ATTEMPTS ]; 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)
+    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{}")
+      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
+      node ~/.claude/bin/qualia-ui.js warn "ERP rejected report (HTTP $HTTP_CODE). Ask Fawzi."
+      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 ))
+  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
+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
 ```
 
-If the upload succeeds, print: "Report uploaded to ERP. You can now clock out."
-If it fails (no API key, network error), print the error and tell the employee to ask Fawzi.
-If ERP is disabled, print: "ERP upload skipped (disabled in config)."
+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.
 
-### 6. Update State
+### 7. Update State (SKIP on --dry-run)
 
 ```bash
-node ~/.claude/bin/state.js transition --to activity --notes "Session report generated"
+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.

package/skills/qualia-review/SKILL.md

@@ -40,9 +40,11 @@ ls package.json next.config.* tsconfig.json supabase/ app/ src/ 2>/dev/null
 
 ### 1. Security Scan
 
-Run every command. Record each finding with severity.
+**Run the independent greps as parallel Bash calls in a single response** (they don't depend on each other — serial execution wastes 15-30s on large codebases). Only the `find … | for` loops are sequential.
 
 ```bash
+# PARALLEL BATCH (issue these in one response turn):
+
 # CRITICAL: service_role in client code
 grep -rn "service_role" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.server\.\|[\\/]server[\\/]\|[\\/]app[\\/]api[\\/]\|route\.\|middleware\."
 
@@ -55,21 +57,26 @@ grep -rn "dangerouslySetInnerHTML\|eval(" --include="*.ts" --include="*.tsx" --i
 # CRITICAL: .env files tracked in git
 git ls-files | grep -i "\.env" | grep -v "\.example\|\.template\|\.sample"
 
+# HIGH: client-side database mutations
+grep -rn "\.insert\|\.update\|\.delete\|\.upsert" --include="*.tsx" --include="*.jsx" app/ components/ 2>/dev/null | grep -v "use server" | grep -v "\.server\."
+
+# MEDIUM: npm vulnerabilities
+npm audit --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));const v=d.metadata?.vulnerabilities||{};console.log('critical:',v.critical||0,'high:',v.high||0,'moderate:',v.moderate||0)}catch{console.log('audit unavailable')}"
+
+# END PARALLEL BATCH
+
+# SEQUENTIAL (depends on find):
 # HIGH: API routes without auth
 for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
-  grep -qL "getUser\|getSession\|auth()\|createClient" "$f" && echo "UNPROTECTED: $f"
+  if ! grep -q "getUser\|getSession\|auth()\|createClient" "$f" 2>/dev/null; then
+    echo "UNPROTECTED: $f"
+  fi
 done
 
 # HIGH: API routes without input validation
 for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
   grep -L "z\.\|zod\|Zod\|parse\|safeParse" "$f" 2>/dev/null
 done
-
-# HIGH: client-side database mutations
-grep -rn "\.insert\|\.update\|\.delete\|\.upsert" --include="*.tsx" --include="*.jsx" app/ components/ 2>/dev/null | grep -v "use server" | grep -v "\.server\."
-
-# MEDIUM: npm vulnerabilities
-npm audit --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));const v=d.metadata?.vulnerabilities||{};console.log('critical:',v.critical||0,'high:',v.high||0,'moderate:',v.moderate||0)}catch{console.log('audit unavailable')}"
 ```
 
 ### 2. Code Quality Scan
@@ -94,8 +101,14 @@ grep -rn "console\.log" --include="*.ts" --include="*.tsx" app/ components/ src/
 ### 3. Performance Scan
 
 ```bash
-# Build output — route sizes and first load JS
-npx next build 2>&1 | grep -E "Route|First Load|shared by all|○|●|ƒ|λ" | tail -25
+# Build output — read existing build artifacts (don't trigger a fresh build during a scan)
+if [ -d ".next" ]; then
+  du -sh .next/static/chunks/*.js 2>/dev/null | sort -rh | head -10
+  echo "---"
+  find .next -name "*.js" -size +200k 2>/dev/null | head -5
+else
+  echo "No .next/ build output — run 'npx next build' separately for bundle analysis (review skill does NOT trigger builds — it's a scan)"
+fi
 
 # Heavy files (>300 lines often means split needed)
 find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
@@ -144,12 +157,19 @@ Write to `.planning/REVIEW.md`:
 {PASS: no critical/high | FAIL: N blockers — fix before /qualia-ship}
 ```
 
-**Scoring:**
-- 5 = zero high/critical, fewer than 3 medium
-- 4 = zero critical, 1 high or fewer than 5 medium
-- 3 = zero critical, 2-3 high
-- 2 = 1 critical or 4+ high
-- 1 = multiple critical
+**Scoring (deterministic — see `rules/grounding.md` for full rubric):**
+```
+weighted_sum   = (critical × 8) + (high × 4) + (medium × 2) + (low × 1)
+category_score = max(1, 5 − floor(weighted_sum / 8))
+```
+Same inputs always produce the same score. No subjective thresholds.
+
+Quick reference (computed from the formula — verified):
+- 0 findings, or only LOW/MEDIUM, or 1 HIGH → 5
+- 2–3 HIGH, or 1 CRITICAL → 4
+- 2 CRITICAL, or 1 CRITICAL + 2–3 HIGH → 3
+- 3 CRITICAL, or 2 CRITICAL + 2+ HIGH → 2
+- 4+ CRITICAL → 1
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider

package/skills/qualia-skill-new/SKILL.md

@@ -161,7 +161,7 @@ git add skills/{name}/
 git commit -m "feat: add /{name} skill"
 ```
 
-Remind the user to run `npx qualia-framework update` on their other machines, or bump the version and `npm publish`.
+Remind the user to run `npx qualia-framework@latest update` on their other machines (always pin `@latest` — npx caches aggressively), or bump the version and `npm publish`.
 
 ## Anti-Patterns
 

package/skills/qualia-verify/SKILL.md

@@ -41,6 +41,10 @@ node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/verifier.md
+Grounding + rubrics: @~/.claude/rules/grounding.md
+
+Project conventions (MUST consult before scoring Quality):
+@.planning/PROJECT.md
 
 Phase plan with success criteria AND verification contracts:
 @.planning/phase-{N}-plan.md
@@ -48,7 +52,7 @@ Phase plan with success criteria AND verification contracts:
 {If re-verification: Previous verification with gaps:}
 {@.planning/phase-{N}-verification.md}
 
-Verify this phase. Write report to .planning/phase-{N}-verification.md
+Verify this phase. Apply the Grounding Protocol — every finding needs file:line evidence. Use the Severity Rubric for all severity labels. Write report to .planning/phase-{N}-verification.md
 ", subagent_type="qualia-verifier", description="Verify phase {N}")
 ```
 

package/templates/tracking.json

@@ -26,6 +26,7 @@
   "build_count": 0,
   "deploy_count": 0,
   "deployed_url": "",
+  "report_seq": 0,
   "notes": "",
   "submitted_by": "",
   "lifetime": {

package/tests/runner.js

@@ -1288,6 +1288,104 @@ waves: 1
       fs.rmSync(tmpDir, { recursive: true, force: true });
     }
   });
+
+  // ─── v4.0.4: next-report-id ────────────────────────────────
+  it("next-report-id returns QS-REPORT-01 on fresh project and increments", () => {
+    const tmpDir = makeProject();
+    try {
+      const r1 = spawnSync(process.execPath,
+        [path.join(BIN, "state.js"), "next-report-id"],
+        { encoding: "utf8", cwd: tmpDir, timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+      assert.equal(r1.status, 0, `next-report-id failed: ${r1.stderr || r1.stdout}`);
+      const j1 = JSON.parse(r1.stdout);
+      assert.equal(j1.report_id, "QS-REPORT-01");
+      assert.equal(j1.report_seq, 1);
+      assert.equal(j1.peeked, false);
+
+      const r2 = spawnSync(process.execPath,
+        [path.join(BIN, "state.js"), "next-report-id"],
+        { encoding: "utf8", cwd: tmpDir, timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+      const j2 = JSON.parse(r2.stdout);
+      assert.equal(j2.report_id, "QS-REPORT-02");
+      assert.equal(j2.report_seq, 2);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("next-report-id --peek does NOT increment the counter", () => {
+    const tmpDir = makeProject();
+    try {
+      const r1 = spawnSync(process.execPath,
+        [path.join(BIN, "state.js"), "next-report-id", "--peek"],
+        { encoding: "utf8", cwd: tmpDir, timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+      const j1 = JSON.parse(r1.stdout);
+      assert.equal(j1.report_id, "QS-REPORT-01");
+      assert.equal(j1.peeked, true);
+
+      // Peek again — should still return QS-REPORT-01 since nothing incremented
+      const r2 = spawnSync(process.execPath,
+        [path.join(BIN, "state.js"), "next-report-id", "--peek"],
+        { encoding: "utf8", cwd: tmpDir, timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+      const j2 = JSON.parse(r2.stdout);
+      assert.equal(j2.report_id, "QS-REPORT-01");
+      assert.equal(j2.report_seq, 1);
+
+      // On-disk report_seq should still be 0
+      const t = JSON.parse(fs.readFileSync(path.join(tmpDir, ".planning", "tracking.json"), "utf8"));
+      assert.ok(!t.report_seq || t.report_seq === 0,
+        `report_seq should remain 0 after peek, got ${t.report_seq}`);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  // ─── v4.0.4: close-milestone pre-populates next milestone_name from JOURNEY.md
+  it("close-milestone pre-populates next milestone_name from JOURNEY.md", () => {
+    const tmpDir = makeProject();
+    try {
+      // Write JOURNEY.md with Milestone 2 definition
+      fs.writeFileSync(path.join(tmpDir, ".planning", "JOURNEY.md"), `# Journey
+
+## Milestone 1 · Foundation     [CURRENT]
+Exit: scaffolding done
+
+## Milestone 2 · Core Features
+Exit: auth + dashboard
+
+## Milestone 3 · Handoff     [FINAL]
+Exit: client takeover
+`);
+      const r = spawnSync(process.execPath,
+        [path.join(BIN, "state.js"), "close-milestone", "--force"],
+        { encoding: "utf8", cwd: tmpDir, timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+      assert.equal(r.status, 0, `close-milestone failed: ${r.stderr || r.stdout}`);
+
+      const t = JSON.parse(fs.readFileSync(path.join(tmpDir, ".planning", "tracking.json"), "utf8"));
+      assert.equal(t.milestone, 2);
+      assert.equal(t.milestone_name, "Core Features",
+        `milestone_name should be pre-populated from JOURNEY.md, got '${t.milestone_name}'`);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("close-milestone leaves milestone_name blank when JOURNEY.md is missing", () => {
+    const tmpDir = makeProject();
+    try {
+      // No JOURNEY.md — milestone_name should fall back to blank (legacy behavior)
+      const r = spawnSync(process.execPath,
+        [path.join(BIN, "state.js"), "close-milestone", "--force"],
+        { encoding: "utf8", cwd: tmpDir, timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
+      assert.equal(r.status, 0);
+
+      const t = JSON.parse(fs.readFileSync(path.join(tmpDir, ".planning", "tracking.json"), "utf8"));
+      assert.equal(t.milestone_name, "",
+        "milestone_name must be blank when JOURNEY.md is absent (fallback unchanged)");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
 });
 
 // ═══════════════════════════════════════════════════════════