qualia-framework 5.8.0 → 5.9.1

package/skills/qualia-report/SKILL.md

@@ -168,6 +168,17 @@ 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)
 
+# Idempotency key — deterministic per (client_report_id, submitted_at). A retry
+# of the same shift report carries the same key, so the ERP can dedupe at the
+# header level in addition to the UPSERT on (project_id, client_report_id).
+IDEMPOTENCY_KEY=$(node -e "
+  const c=require('crypto');
+  const seed='$CLIENT_REPORT_ID|$SUBMITTED_AT|'+require('path').basename(process.cwd());
+  // RFC 4122 v5-style: deterministic UUID from sha1 of the seed
+  const h=c.createHash('sha1').update(seed).digest('hex');
+  console.log([h.slice(0,8),h.slice(8,12),'5'+h.slice(13,16),'8'+h.slice(17,20),h.slice(20,32)].join('-'));
+")
+
 # 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). Run: qualia-framework set-erp-key <key>"
@@ -189,6 +200,17 @@ PAYLOAD=$(
     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());
+    // Session duration: minutes from session_started_at to submitted_at. The ERP's
+    // example payload (docs/erp-contract.md:93) includes this; without it the ERP
+    // can't compute shift-length analytics without parsing notes.
+    let sessionDurationMinutes=0;
+    if(t.session_started_at){
+      const startMs=Date.parse(t.session_started_at);
+      const endMs=Date.parse(process.env.SUBMITTED_AT)||Date.now();
+      if(!Number.isNaN(startMs)&&endMs>startMs){
+        sessionDurationMinutes=Math.round((endMs-startMs)/60000);
+      }
+    }
     console.log(JSON.stringify({
       project:t.project||require('path').basename(process.cwd()),
       project_id:projectKey,team_id:t.team_id||'qualia-solutions',git_remote:gitRemote,
@@ -200,6 +222,7 @@ PAYLOAD=$(
       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||'',
+      session_duration_minutes:sessionDurationMinutes,
       lifetime:t.lifetime||{},commits:commits,notes:notes,
       submitted_by:process.env.SUBMITTED_BY||'unknown',submitted_at:process.env.SUBMITTED_AT
     }));
@@ -214,11 +237,15 @@ if [ "$DRY_RUN" = "true" ]; then
   exit 0
 fi
 
-# Upload — 3 attempts with 1s/3s/9s backoff
+# Upload — 3 attempts with 1s/3s/9s backoff.
+# Idempotency-Key header carries a deterministic UUID per (client_report_id, submitted_at)
+# so the ERP can dedupe at the request level in addition to the UPSERT key on the body.
+# Documented in docs/erp-contract.md:42-49 with a 24h replay window.
 if [ "$ERP_ENABLED" = "true" ]; then
   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" \
+      -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
       -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')
@@ -235,7 +262,42 @@ if [ "$ERP_ENABLED" = "true" ]; then
     fi
     [ $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
-  [ "$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."
+
+  # If all 3 in-process attempts failed, enqueue the report into the persistent
+  # retry queue (~/.claude/.erp-retry-queue.json). session-start.js drains it on
+  # the next Claude Code launch; `qualia-framework erp-flush` drains it on demand.
+  # This replaces the prior "will appear after retry" message which was a lie —
+  # no retry mechanism existed before v5.9.
+  if [ "$ATTEMPT" = "3" ] && [ "$HTTP_CODE" != "200" ]; then
+    LAST_ERR="HTTP ${HTTP_CODE:-timeout}"
+    if [ -n "$BODY" ]; then LAST_ERR="$LAST_ERR: $(echo "$BODY" | head -c 200)"; fi
+    PAYLOAD="$PAYLOAD" \
+    CLIENT_REPORT_ID="$CLIENT_REPORT_ID" \
+    IDEMPOTENCY_KEY="$IDEMPOTENCY_KEY" \
+    ERP_URL="$ERP_URL" \
+    LAST_ERR="$LAST_ERR" \
+    node -e "
+      try {
+        const {enqueue} = require(require('os').homedir() + '/.claude/bin/erp-retry.js');
+        enqueue({
+          client_report_id: process.env.CLIENT_REPORT_ID,
+          idempotency_key: process.env.IDEMPOTENCY_KEY,
+          url: process.env.ERP_URL + '/api/v1/reports',
+          payload: process.env.PAYLOAD,
+          last_error: process.env.LAST_ERR,
+        });
+        process.stdout.write('enqueued');
+      } catch (e) {
+        process.stderr.write('enqueue failed: ' + (e.message || e));
+        process.exit(1);
+      }
+    " 2>/dev/null && {
+      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts — $CLIENT_REPORT_ID enqueued for auto-retry on next session"
+      node ~/.claude/bin/qualia-ui.js info "Drain manually with: qualia-framework erp-flush"
+    } || {
+      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts AND queue enqueue failed. $CLIENT_REPORT_ID is committed locally — re-run /qualia-report later to retry."
+    }
+  fi
 fi
 
 [ "$ERP_ENABLED" != "true" ] && node ~/.claude/bin/qualia-ui.js info "ERP upload skipped (disabled). $CLIENT_REPORT_ID committed locally."

package/skills/qualia-verify/SKILL.md

@@ -104,6 +104,22 @@ Append '## Adversarial Findings' to verification file. Empty section fine if not
 
 Findings merge into main report. Union PASS/FAIL: either pass found CRITICAL/HIGH → phase FAIL.
 
+### 2d. INSUFFICIENT EVIDENCE downgrade (mandatory)
+
+The verifier marks criteria it could not check (budget exhaustion, missing context) as `INSUFFICIENT EVIDENCE`. The orchestrator treats those as silent PASS unless explicitly downgraded — that's the #1 false-pass vector. Grep the verification file before declaring PASS:
+
+```bash
+IE_COUNT=$(grep -c "INSUFFICIENT EVIDENCE" .planning/phase-{N}-verification.md 2>/dev/null || echo 0)
+if [ "$IE_COUNT" -gt 0 ]; then
+  node ~/.claude/bin/qualia-ui.js warn "${IE_COUNT} criteria marked INSUFFICIENT EVIDENCE — downgrading verdict to FAIL"
+  # Rewrite the verdict line in-place
+  sed -i 's/^result: PASS$/result: FAIL/' .planning/phase-{N}-verification.md
+  sed -i 's/^## Verdict$/## Verdict\n\n**Downgraded to FAIL:** '"${IE_COUNT}"' criteria left unchecked. Re-run with larger budget (`max(25, tasks*5)` already applied) or simplify the phase plan./' .planning/phase-{N}-verification.md
+fi
+```
+
+The same check runs after the adversarial pass if it executed.
+
 ### 3. Present Results
 
 Read verification report. Present:

package/templates/help.html

@@ -374,9 +374,8 @@
       <h3>Quick Paths</h3>
       <p class="cmd-group-note">Lightweight alternatives when the full road is overkill.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-quick</span><span class="cmd-desc">Fast path for small tasks &mdash; bug fixes, tweaks, hot fixes. Skips full phase planning.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-task</span><span class="cmd-desc">Build a single task &mdash; more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-design</span><span class="cmd-desc">One-shot design transformation &mdash; critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-feature</span><span class="cmd-desc">Auto-scoped single-feature build. Inline for trivia (typo, config), fresh builder spawn for 1-5 file features. Refuses and routes to /qualia-plan for phase-sized work. Flags: --force-spawn, --force-inline.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design pass, scope-adaptive &mdash; component, route, full app, redesign, critique, quick. Add --loop for the autonomous screenshot &rarr; score &rarr; fix loop.</span></div>
       </div>
     </div>
 

package/tests/bin.test.sh

@@ -719,18 +719,36 @@ else
   fail_case "research-synthesizer missing model frontmatter"
 fi
 
-# 64. Other agents do NOT have model frontmatter (conservative matrix)
-SAFE_AGENTS=("planner.md" "builder.md" "verifier.md" "plan-checker.md")
+# 64. v5.9 model tiering: structured agents (verifier, plan-checker, roadmapper,
+# qa-browser) use Sonnet. Real-reasoning agents (planner, builder, researcher,
+# visual-evaluator) keep inherited Opus.
+SONNET_AGENTS=("verifier.md" "plan-checker.md" "roadmapper.md" "qa-browser.md")
+OPUS_AGENTS=("planner.md" "builder.md" "researcher.md" "visual-evaluator.md")
+
+ALL_OK=1
+for a in "${SONNET_AGENTS[@]}"; do
+  if ! grep -q '^model: sonnet$' "$TMP/.claude/agents/$a" 2>/dev/null; then
+    ALL_OK=0
+    echo "    missing 'model: sonnet' in $a"
+  fi
+done
+if [ "$ALL_OK" = "1" ]; then
+  pass "structured agents (verifier/plan-checker/roadmapper/qa-browser) use sonnet (v5.9 tiering)"
+else
+  fail_case "v5.9 sonnet-tier agent has wrong model frontmatter"
+fi
+
 ALL_OK=1
-for a in "${SAFE_AGENTS[@]}"; do
+for a in "${OPUS_AGENTS[@]}"; do
   if grep -q '^model: ' "$TMP/.claude/agents/$a" 2>/dev/null; then
     ALL_OK=0
+    echo "    unexpected 'model:' in $a (should inherit Opus)"
   fi
 done
 if [ "$ALL_OK" = "1" ]; then
-  pass "high-stakes agents (planner/builder/verifier/plan-checker) keep default model"
+  pass "reasoning agents (planner/builder/researcher/visual-evaluator) inherit Opus"
 else
-  fail_case "high-stakes agent has unexpected model frontmatter"
+  fail_case "Opus-tier agent has unexpected model frontmatter"
 fi
 
 echo ""

package/tests/refs.test.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# Qualia Framework — surface-drift guard
+# Greps every active surface for backtick-quoted /qualia-{name} command references.
+# Asserts each name has a matching skills/qualia-{name}/SKILL.md.
+#
+# Why: v5.7 + v5.8 removed /qualia-quick, /qualia-task, /qualia-prd, /qualia-design,
+# /qualia-polish-loop. Three user-facing files (rules/speed.md, templates/help.html,
+# docs/onboarding.html) still pointed at the removed commands. New hires hit dead
+# ends. This test fails when that happens again.
+#
+# Scoping rules:
+# - Only matches references quoted in markdown backticks (`/qualia-foo`) or shown
+#   as a slash-command at line start. Bare path refs (/qualia-templates/,
+#   /qualia-ui.js) are excluded — they're directories or scripts, not commands.
+# - Historical surfaces (docs/reviews/, docs/research/, CHANGELOG) are excluded —
+#   they intentionally describe past states.
+# - Migration mentions on active surfaces (README/guide describing v5.7 removals)
+#   are excluded via a context prefix check.
+#
+# Run: bash tests/refs.test.sh
+
+FRAMEWORK_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILLS_DIR="$FRAMEWORK_ROOT/skills"
+
+PASS=0
+FAIL=0
+
+pass() {
+  echo "  ✓ $1"
+  PASS=$((PASS + 1))
+}
+
+fail_case() {
+  echo "  ✗ $1"
+  echo "    $2"
+  FAIL=$((FAIL + 1))
+}
+
+# Files we never scan — historical records, backups, vendored deps.
+EXCLUDE_REGEX='/docs/reviews/|/docs/research/|/docs/playwright-loop-pilot-results\.md$|/CHANGELOG\.md$|\.bak\.|\.git/|/node_modules/|/\.continue-here\.md$'
+
+# When a `/qualia-foo` ref appears AFTER one of these context tokens on the same line,
+# it's a migration-explainer ("Replaces /qualia-quick" / "deprecated in v5.7"), not
+# a live command reference. Treat it as exempt.
+MIGRATION_CONTEXT_REGEX='Replaces|Removed|removed in|consolidated|deprecated|renamed|former|previously|was the|now the|now\s+`?/qualia|absorbed|superseded|legacy|migrated|after\s+`?/qualia.*-(quick|task|prd|design|polish-loop)'
+
+ACTIVE_DIRS=(
+  "$FRAMEWORK_ROOT/rules"
+  "$FRAMEWORK_ROOT/skills"
+  "$FRAMEWORK_ROOT/agents"
+  "$FRAMEWORK_ROOT/hooks"
+  "$FRAMEWORK_ROOT/templates"
+)
+
+ACTIVE_FILES=(
+  "$FRAMEWORK_ROOT/README.md"
+  "$FRAMEWORK_ROOT/guide.md"
+  "$FRAMEWORK_ROOT/CLAUDE.md"
+  "$FRAMEWORK_ROOT/AGENTS.md"
+  "$FRAMEWORK_ROOT/docs/onboarding.html"
+)
+
+echo "refs.test.sh — surface-drift guard (active /qualia-* references must point at shipped skills)"
+echo ""
+
+SCAN_FILES=$(
+  {
+    for d in "${ACTIVE_DIRS[@]}"; do
+      [ -d "$d" ] && find "$d" -type f \( -name "*.md" -o -name "*.html" \)
+    done
+    for f in "${ACTIVE_FILES[@]}"; do
+      [ -f "$f" ] && echo "$f"
+    done
+  } | grep -Ev "$EXCLUDE_REGEX" | sort -u
+)
+
+# Extract backtick-quoted command refs only. Two patterns:
+#   1. `/qualia-foo`       — backticked, the canonical command-doc style
+#   2. <dt>/qualia-foo</dt> — HTML help/onboarding pages
+# We capture name + file:line so we can show context per failure.
+declare -A SEEN_REFS
+declare -A REF_LOCATIONS
+
+while IFS= read -r file; do
+  # Pattern A: backtick-quoted commands. Allow trailing flag/word but only capture base name.
+  while IFS=: read -r path lineno line; do
+    [ -z "$line" ] && continue
+    # Skip migration-context lines.
+    if echo "$line" | grep -qE "$MIGRATION_CONTEXT_REGEX"; then
+      continue
+    fi
+    # Extract every backticked /qualia-foo on this line.
+    matches=$(echo "$line" | grep -oE '`/qualia(-[a-z]+){0,3}`' | sed 's/^`//; s/`$//')
+    for ref in $matches; do
+      SEEN_REFS["$ref"]=1
+      REF_LOCATIONS["$ref"]="${REF_LOCATIONS[$ref]:+${REF_LOCATIONS[$ref]}, }$(basename "$path"):$lineno"
+    done
+  done < <(grep -nE '`/qualia(-[a-z]+){0,3}`' "$file" 2>/dev/null)
+
+  # Pattern B: HTML <dt>/qualia-foo</dt>.
+  while IFS=: read -r path lineno line; do
+    [ -z "$line" ] && continue
+    if echo "$line" | grep -qE "$MIGRATION_CONTEXT_REGEX"; then
+      continue
+    fi
+    matches=$(echo "$line" | grep -oE '<dt>/qualia(-[a-z]+){0,3}( [^<]*)?</dt>' | sed -E 's|<dt>(/qualia(-[a-z]+){0,3}).*|\1|')
+    for ref in $matches; do
+      SEEN_REFS["$ref"]=1
+      REF_LOCATIONS["$ref"]="${REF_LOCATIONS[$ref]:+${REF_LOCATIONS[$ref]}, }$(basename "$path"):$lineno"
+    done
+  done < <(grep -nE '<dt>/qualia' "$file" 2>/dev/null)
+done <<<"$SCAN_FILES"
+
+if [ ${#SEEN_REFS[@]} -eq 0 ]; then
+  fail_case "scan" "no backticked /qualia-* references found across active surfaces (scanner broken?)"
+  echo ""
+  echo "Results: $PASS passed, $FAIL failed"
+  exit 1
+fi
+
+# Sort refs for deterministic output.
+for ref in $(printf '%s\n' "${!SEEN_REFS[@]}" | sort); do
+  name="${ref#/}"
+  skill_dir="$SKILLS_DIR/$name"
+  locations="${REF_LOCATIONS[$ref]}"
+  if [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
+    pass "$ref → skills/$name/SKILL.md"
+    continue
+  fi
+  fail_case "$ref" "no skills/$name/SKILL.md — referenced by: $locations"
+done
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "Surface drift detected. To fix one of:"
+  echo "  1. Restore the missing skill at skills/<name>/SKILL.md"
+  echo "  2. Update the offending file to point at the replacement command"
+  echo "  3. Reframe the mention as a migration note (this test skips lines containing"
+  echo "     'Replaces', 'consolidated', 'deprecated', 'now', 'former', 'superseded', etc.)"
+  exit 1
+fi
+
+exit 0