qualia-framework 4.0.3 → 4.1.0

package/bin/statusline.js

@@ -153,7 +153,21 @@ try {
   } catch {}
 } catch {}
 
+// ─── Pill-style badge helper ─────────────────────────────
+// Renders text as an inline pill with a solid background color, similar to
+// Claude Code's native worktree tag. Pads with a leading+trailing space so
+// the background band has visual weight.
+function pill(text, rgb) {
+  const [r, g, b] = rgb;
+  const bg = `\x1b[48;2;${r};${g};${b}m`;
+  const fg = `\x1b[38;2;240;250;255m`;
+  const bold = `\x1b[1m`;
+  return `${bg}${fg}${bold} ${text} ${RESET}`;
+}
+
 // ─── Phase info from .planning/tracking.json ─────────────
+// Rendered as a pill at the start of line 1 — teal for normal, red when blockers > 0.
+// Every segment is optional — missing data is skipped, never rendered as a placeholder.
 let PHASE_INFO = "";
 try {
   const trackingPath = path.join(DIR, ".planning", "tracking.json");
@@ -162,16 +176,53 @@ try {
     const phase = Number(tracking.phase || 0) || 0;
     const total = Number(tracking.total_phases || 0) || 0;
     const status = String(tracking.status || "");
-    if (total > 0) {
-      const pdone = Math.floor((phase * 100) / total);
-      const pfill = Math.max(0, Math.min(4, Math.floor(pdone / 25)));
-      const pempt = 4 - pfill;
-      const pbar = "●".repeat(pfill) + "○".repeat(pempt);
-      PHASE_INFO = `${TEAL}${pbar}${RESET} ${WHITE}P${phase}/${total}${RESET} ${TEAL_GLOW}${status}${RESET}`;
+    const milestone = Number(tracking.milestone || 0) || 0;
+    const milestoneName = String(tracking.milestone_name || "");
+    const tasksDone = Number(tracking.tasks_done || 0) || 0;
+    const tasksTotal = Number(tracking.tasks_total || 0) || 0;
+    const blockers = Array.isArray(tracking.blockers) ? tracking.blockers.length : 0;
+
+    const parts = [];
+
+    if (milestone > 0) {
+      let mStr = `M${milestone}`;
+      if (milestoneName) {
+        const shortName = milestoneName.length > 14 ? milestoneName.slice(0, 13) + "…" : milestoneName;
+        mStr += `·${shortName}`;
+      }
+      parts.push(mStr);
+    }
+
+    if (total > 0) parts.push(`P${phase}/${total}`);
+    if (tasksTotal > 0) parts.push(`T${tasksDone}/${tasksTotal}`);
+    if (status) parts.push(status);
+
+    let badgeText = parts.join(" · ");
+    if (blockers > 0) badgeText += badgeText ? ` · !${blockers}` : `!${blockers}`;
+
+    if (badgeText) {
+      // Red pill when blockers present, teal otherwise
+      const bg = blockers > 0 ? [153, 27, 27] : [0, 130, 135];
+      PHASE_INFO = pill(`⬢ ${badgeText}`, bg);
     }
   }
 } catch {}
 
+// ─── Framework-dev badge ────────────────────────────────
+// When editing the Qualia framework itself (detected by presence of the
+// skills/ dir + qualia-ui.js), show a FRAMEWORK DEV pill even though
+// there's no tracking.json. Gives the same "you're in Qualia mode" signal
+// during framework work.
+let FRAMEWORK_BADGE = "";
+try {
+  const isFramework =
+    fs.existsSync(path.join(DIR, "skills", "qualia-plan", "SKILL.md")) &&
+    fs.existsSync(path.join(DIR, "bin", "qualia-ui.js"));
+  if (isFramework) {
+    FRAMEWORK_BADGE = pill("⬢ FRAMEWORK DEV", [120, 60, 140]);
+  }
+} catch {}
+
 // ─── Memory count ────────────────────────────────────────
 let MEMORY_COUNT = 0;
 try {
@@ -186,36 +237,22 @@ try {
   }
 } catch {}
 
-// ─── Hooks count ─────────────────────────────────────────
-let HOOKS_COUNT = 0;
+// ─── Qualia identity: first name of the installed employee ─────────
+// Read from ~/.claude/.qualia-config.json. Used as the "signature" at the
+// end of line 2. Gracefully degrades to empty string if the config is
+// missing (pre-install, broken install, or running outside a Qualia env).
+let QUALIA_FIRST_NAME = "";
 try {
-  const settingsPath = path.join(HOME, ".claude", "settings.json");
-  if (fs.existsSync(settingsPath)) {
-    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-    if (settings.hooks) {
-      for (const event of Object.values(settings.hooks)) {
-        if (Array.isArray(event)) {
-          for (const matcher of event) {
-            if (matcher.hooks && Array.isArray(matcher.hooks)) {
-              HOOKS_COUNT += matcher.hooks.length;
-            }
-          }
-        }
-      }
+  const configPath = path.join(HOME, ".claude", ".qualia-config.json");
+  if (fs.existsSync(configPath)) {
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const fullName = String(cfg.installed_by || "").trim();
+    if (fullName) {
+      QUALIA_FIRST_NAME = fullName.split(/\s+/)[0] || "";
     }
   }
 } catch {}
 
-// ─── Skills count ────────────────────────────────────────
-let SKILLS_COUNT = 0;
-try {
-  const skillsDir = path.join(HOME, ".claude", "skills");
-  if (fs.existsSync(skillsDir)) {
-    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-    SKILLS_COUNT = entries.filter(e => e.isDirectory() || e.name.endsWith(".md")).length;
-  }
-} catch {}
-
 // ─── Duration ────────────────────────────────────────────
 let DUR = "0s";
 try {
@@ -232,11 +269,14 @@ try {
   COST_FMT = `$${COST.toFixed(2)}`;
 } catch {}
 
-// ─── Line 1: Project + Git + Agent + Worktree + Phase + Memory + Hooks ──
+// ─── Line 1: Pill badge + Project + Git + Agent + Worktree + Memory + Identity ──
+// Leading pill (phase info or framework-dev) — one of these at most, phase wins.
 let LINE1 = "";
 try {
   const dirBase = path.basename(DIR) || DIR;
-  LINE1 = `${TEAL}⬢${RESET} ${WHITE}${dirBase}${RESET}`;
+  const leadingBadge = PHASE_INFO || FRAMEWORK_BADGE;
+  if (leadingBadge) LINE1 += `${leadingBadge} `;
+  LINE1 += `${TEAL}⬢${RESET} ${WHITE}${dirBase}${RESET}`;
   if (BRANCH) {
     if (CHANGES > 0) {
       LINE1 += ` ${DIM}on${RESET} ${TEAL_GLOW}${BRANCH}${RESET} ${YELLOW}~${CHANGES}${RESET}`;
@@ -246,14 +286,11 @@ try {
   }
   if (AGENT) LINE1 += ` ${DIM}│${RESET} ${TEAL}⚡${AGENT}${RESET}`;
   if (WORKTREE) LINE1 += ` ${DIM}│${RESET} ${TEAL_DIM}⎇ ${WORKTREE}${RESET}`;
-  if (PHASE_INFO) LINE1 += ` ${DIM}│${RESET} ${PHASE_INFO}`;
-  // Memory, hooks, skills — context indicators with labels
-  const contextParts = [];
-  if (MEMORY_COUNT > 0) contextParts.push(`${DIM}mem${RESET} ${TEAL}${MEMORY_COUNT}${RESET}`);
-  if (HOOKS_COUNT > 0) contextParts.push(`${DIM}hooks${RESET} ${TEAL_GLOW}${HOOKS_COUNT}${RESET}`);
-  if (SKILLS_COUNT > 0) contextParts.push(`${DIM}skills${RESET} ${TEAL_DIM}${SKILLS_COUNT}${RESET}`);
-  if (contextParts.length > 0) {
-    LINE1 += ` ${DIM}│${RESET} ${contextParts.join(` ${DIM}·${RESET} `)}`;
+  if (MEMORY_COUNT > 0) {
+    LINE1 += ` ${DIM}│${RESET} ${DIM}mem${RESET} ${TEAL}${MEMORY_COUNT}${RESET}`;
+  }
+  if (QUALIA_FIRST_NAME) {
+    LINE1 += ` ${DIM}│${RESET} ${TEAL}⬢${RESET} ${TEAL_GLOW}Qualia member${RESET}${DIM}:${RESET} ${WHITE}${QUALIA_FIRST_NAME}${RESET}`;
   }
 } catch {
   LINE1 = `${TEAL}⬢${RESET} ${WHITE}qualia${RESET}`;

package/docs/erp-contract.md

@@ -28,8 +28,16 @@ Upload a session report.
 ```
 Authorization: Bearer <api-key>
 Content-Type: application/json
+Idempotency-Key: <uuid>   # optional; 24h replay window — see below
 ```
 
+**Idempotency-Key behavior (v3.6+):**
+When present, must be a valid UUID. Replays of the same key within 24h return
+the original `report_id` with `Idempotent-Replay: true` response header and
+200 status — no new row is created. Invalid UUID format returns 400.
+Independent of `client_report_id` UPSERT (both can be used together; see
+below).
+
 **Request Body:**
 ```json
 {
@@ -38,6 +46,7 @@ Content-Type: application/json
   "team_id": "qualia-solutions",
   "git_remote": "github.com/QualiasolutionsCY/acme-portal",
   "client": "Client Name",
+  "client_report_id": "QS-REPORT-03",
   "milestone": 2,
   "milestone_name": "Core Product",
   "milestones": [
@@ -87,11 +96,27 @@ accept both shapes: if object, use `gap_cycles[String(phase)] || 0`.
 ```json
 {
   "ok": true,
-  "report_id": "rpt_abc123def456",
+  "report_id": "QS-REPORT-03",
   "message": "Report received"
 }
 ```
 
+`report_id` semantics:
+- **v4.0.4+ payloads** (`client_report_id` present): ERP echoes the
+  `client_report_id` string back as `report_id` for display consistency.
+  Example: request sends `client_report_id: "QS-REPORT-03"` → response
+  returns `report_id: "QS-REPORT-03"`.
+- **Legacy payloads** (no `client_report_id`): ERP returns its internal UUID
+  (e.g. `"a5304d8b-a5ac-4e22-b0c0-fed5f50299bb"`) as `report_id`.
+
+**Idempotent UPSERT on retry (v4.0.4+):**
+When BOTH `project_id` and `client_report_id` are present, the ERP treats
+`(project_id, client_report_id)` as a unique key and UPSERTs. Retries after
+a transient failure produce the same row and return the same `report_id`
+— no duplicate. This is stronger than the 24h Idempotency-Key window (which
+is exact-replay only) because `client_report_id` uniqueness is enforced
+permanently.
+
 **Response (401 Unauthorized):**
 ```json
 {
@@ -171,7 +196,15 @@ Authorization: Bearer <api-key>
 - When the API key file is missing or empty, the upload is skipped with a warning.
 - Network failures are non-blocking — the report is saved locally regardless.
 - The ERP reads `tracking.json` directly from git for real-time status (no API call needed for passive monitoring).
-- Reports are append-only — no update or delete endpoints exist.
+- Reports are append-only — no PUT/PATCH/DELETE endpoints exist for
+  external callers. Internal idempotent UPSERT on `(project_id,
+  client_report_id)` retries is the one exception (see "Idempotent UPSERT
+  on retry" above).
+- **`dry_run` retention (v4.0.4+):** The ERP deletes rows where
+  `dry_run = true AND submitted_at < now() - 7 days` via a daily cron at
+  03:00 UTC. Production report views (list, project tree, email digests)
+  exclude `dry_run = true` rows at read time by default. Admins can opt in
+  via `includeDryRun: true` on the server-action readers for diagnostics.
 - `tracking.json` includes `milestone` and `lifetime` fields (added in v3.4). These survive across milestone resets and `state.js init` calls. For aggregate reporting, use `lifetime.total_phases` + current `total_phases` for the grand total across all milestones.
 - Backward compatibility: if `lifetime` is absent in tracking.json, treat all counters as 0 and `milestone` as 1.
 
@@ -195,6 +228,8 @@ Authorization: Bearer <api-key>
 | last_pushed_at | string | optional (v3.6+) | ISO 8601 — distinct from `last_updated` (which fires on local writes too). |
 | build_count | number | optional (v3.6+) | Lifetime build counter. |
 | deploy_count | number | optional (v3.6+) | Lifetime deploy counter. |
+| client_report_id | string | recommended (v4.0.4+) | Client-side sequential identifier: `QS-REPORT-01`, `QS-REPORT-02`, … per-project. Stable across retries. Preferred dedupe key over the ERP-generated `report_id`; safe to adopt as the ERP's primary report key. |
+| dry_run | boolean | optional (v4.0.4+) | `true` marks a synthetic ping (from `qualia-framework erp-ping`). Receivers should filter these out of production report views. |
 
 All other fields are optional but recommended for complete reporting.
 

package/docs/research/2026-04-21-command-quality-deep-research.md

@@ -0,0 +1,128 @@
+# Qualia Framework — Command Quality & Build Workflow Deep Research
+**Date:** 2026-04-21
+**Scope:** design, debug, optimize, review + plan/build/verify workflow + 8 subagent prompts
+**Method:** 4 parallel Opus agents, each auditing one dimension, synthesized by framework owner
+
+## Executive Summary
+
+The framework's biggest accuracy leak is **evidence-free claims**: 3 of 4 diagnostic commands (design, debug, review) do not require file:line citations for findings, so the model hallucinates specifics under pressure. The biggest speed leak is **serial work that should be parallel**: qualia-design and qualia-review list `Agent` in allowed-tools but never spawn, so large codebases get processed in a single context window; the plan-checker revision loop serially re-spawns the planner for issues (frontmatter, wave assignment) that can be fixed mechanically.
+
+The single highest-leverage change is a shared **Grounding Protocol** + **Rubric Library** referenced from every skill and agent — it eliminates ~60% of the determinism defects at once.
+
+---
+
+## Top 15 Improvements — Ranked by Impact × Ease
+
+| # | Change | Impact | Effort | Where |
+|---|--------|--------|--------|-------|
+| 1 | Add shared Grounding Protocol (cite-or-say-INSUFFICIENT-EVIDENCE) to all agents | 🔥 Accuracy | 30 min | `rules/grounding.md` + import into 8 agent files |
+| 2 | Add deterministic severity formula (CRITICAL=8/HIGH=4/MED=2/LOW=1; score = max(1, 5−⌊Σ/8⌋)) to qualia-review | 🔥 Accuracy | 45 min | `skills/qualia-review/SKILL.md:124` |
+| 3 | Pre-inline PROJECT.md into verifier prompt (currently missing) | 🔥 Accuracy | 10 min | `skills/qualia-verify/SKILL.md:42` |
+| 4 | Make qualia-build spawn wave tasks in parallel explicitly ("all Agent() calls in SAME response") | ⚡ Speed | 30 min | `skills/qualia-build/SKILL.md:65` |
+| 5 | Convert qualia-debug from interactive (4 questions) to investigative (parse $ARGUMENTS, run diagnostic greps) | 🔥 Accuracy | 2 hrs | `skills/qualia-debug/SKILL.md:39-44` |
+| 6 | Add structured Output Contract (DONE/BLOCKED/PARTIAL prefix) to builder.md | ⚡ Speed + 🔥 Accuracy | 20 min | `agents/builder.md:14` |
+| 7 | Mechanical-fix bypass in plan-checker (skip planner re-spawn for frontmatter/wave issues) | ⚡ Speed | 4 hrs | `skills/qualia-plan/SKILL.md:129-153` |
+| 8 | Make wave assignment deterministic: file-based dependency graph, topological sort (not "tasks with no dependencies") | 🔥 Accuracy | 3 hrs | `agents/planner.md:33` |
+| 9 | Add Rule 8 to plan-checker: "Validation must test behavior, not file-existence only" (stops stubs passing) | 🔥 Accuracy | 30 min | `agents/plan-checker.md` after Rule 7 |
+| 10 | Split qualia-design/review into parallel agent fan-out for large file sets (5+ files) | ⚡ Speed | 3 hrs | `skills/qualia-design/SKILL.md`, `skills/qualia-review/SKILL.md` |
+| 11 | Add wave-context summary (adjacent task titles + files) to builder prompt — stops semantic drift across parallel tasks | 🔥 Accuracy | 1 hr | `skills/qualia-build/SKILL.md:82` |
+| 12 | Fix `grep -qL` bug in qualia-review API auth check (backwards logic) | 🔥 Accuracy | 15 min | `skills/qualia-review/SKILL.md:59-61` |
+| 13 | Add tool budgets: researcher (8 external calls), verifier (25 bash calls), debug (10 reads) | ⚡ Speed | 45 min | `agents/researcher.md`, `agents/verifier.md`, `skills/qualia-debug` |
+| 14 | Standardize input contracts across 8 agents with `<variable>` typed blocks (only plan-checker does this today) | 🔥 Accuracy | 2 hrs | All 8 agent files |
+| 15 | Drop full `next build` from qualia-review; read existing `.next/` or skip with warning | ⚡ Speed | 20 min | `skills/qualia-review/SKILL.md:98` |
+
+**Total effort for #1–#15:** ~20 hours of focused work → framework-wide accuracy and speed step-change.
+
+---
+
+## Per-Command Scores (before changes)
+
+| Command | Score | Weakest Dimension |
+|---------|-------|-------------------|
+| qualia-debug | 4/10 | Interactive-by-default (4 mandatory questions), no output file, cheat sheets instead of diagnostic commands |
+| qualia-design | 6/10 | No critique output contract, `Agent` listed but never spawned, tsc-only verification |
+| qualia-review | 7/10 | Serial bash scans, latent `grep -qL` bug, no parallelism |
+| qualia-optimize | 8/10 | Strongest — uses agent fan-out, severity labels, OPTIMIZE.md output. Loses points on inline `find`/`grep` in Step 6 + no `--fix` dry-run |
+
+## Per-Agent Scores (before changes)
+
+| Agent | Overall | Biggest Gap |
+|-------|---------|-------------|
+| plan-checker | 9.5/10 | No tool budget |
+| verifier | 9.0/10 | No frontend gate on design verification (runs 40 greps on backend phases) |
+| planner | 8.5/10 | Prose input contract, no failure-mode handling |
+| builder | 8.5/10 | No structured output contract |
+| researcher | 8.5/10 | Unbounded WebSearch loops |
+| qa-browser | 8.5/10 | Probes for dev server URL instead of receiving it; no fallback when Playwright unavailable |
+| roadmapper | 8.5/10 | `full_detail` is a ghost parameter — referenced but not declared |
+| research-synthesizer | 8.0/10 | No evidence requirement on milestone suggestions |
+
+---
+
+## Rubrics to Ship as `rules/rubrics.md`
+
+**Severity (with deterministic category score):**
+```
+CRITICAL = 8 | HIGH = 4 | MEDIUM = 2 | LOW = 1
+weighted_sum = Σ(count_i × weight_i)
+category_score = max(1, 5 − ⌊weighted_sum / 8⌋)
+```
+
+**Design Quality (1–5 per dimension, any <3 = mandatory fix):**
+Typography / Color / Spacing / States / Responsiveness / Accessibility — each with objective criteria (see `skills/qualia-design` comment thread for full matrix).
+
+**Task-Done:**
+- Compiles (`tsc --noEmit` = 0)
+- No stubs (`grep -c "TODO|FIXME|placeholder" touched_files` = 0)
+- Wired (every export imported somewhere)
+- Each acceptance criterion has a passing validation command
+- Committed (git log matches task title)
+
+**Evidence Citation Format:**
+```
+file:line — "quoted code" — {assessment}
+```
+Claims missing this format are rejected. If evidence cannot be found: `INSUFFICIENT EVIDENCE: searched {files} with {commands}`.
+
+---
+
+## Grounding Protocol (paste into every agent)
+
+```markdown
+## Grounding Protocol (MANDATORY)
+1. Every factual claim requires `file:line — "quoted code"`. No exception.
+2. No hedging: "seems / probably / might" → verified or INSUFFICIENT EVIDENCE.
+3. Findings without file:line are discarded.
+4. Scores without evidence on the next line = 0.
+5. Severity requires quoting the matching Severity Rubric criterion.
+6. Output shape is a contract — missing sections = protocol violation.
+7. Stop at tool budget. Return what you found, not what you wish.
+8. Precondition: verify every @file exists before work; HALT if missing.
+```
+
+---
+
+## 3 Architectural Changes (bigger, keep for later)
+
+1. **Pre-Build Context Packet** — assemble one JSON with PROJECT.md + DESIGN.md + plan + wave-context before spawning builders. Eliminates per-builder file reads.
+2. **Intra-Wave Verification** — run each task's Validation contracts immediately after its builder completes, before next wave starts. Catches failure at task granularity, not phase.
+3. **Plan Cache** — cache parsed project identity in `.planning/.project-cache.json`; invalidate on PROJECT.md change. Saves ~30% planner context on multi-phase `--auto` runs.
+
+---
+
+## Missing Agents Worth Adding (ranked)
+
+1. **`migrator.md`** — generates + validates Supabase migrations. Current gap: builder writes raw SQL ad-hoc, migration guard catches only obvious patterns.
+2. **`dependency-auditor.md`** — pre-build peer-dependency / vulnerability check. Current gap: builder hits `npm install` conflicts mid-phase and wastes context debugging.
+3. **`rollback.md`** — on verify FAIL, bisect to last-good commit instead of always patching forward. Current gap: gap-closure plans build on broken code.
+
+---
+
+## Anti-Patterns to Kill
+
+- `find` inside skills (use Glob) — qualia-optimize:302, qualia-review multiple places
+- `Agent` in allowed-tools but never spawned — qualia-design, qualia-debug, qualia-review
+- Interactive question gates in one-shot commands — qualia-debug
+- Full `next build` as part of a "scan" — qualia-review:98
+- Vague "investigate the codebase" with no tool budget — qualia-debug, researcher
+- "seems / probably / might" language anywhere in agent output