qualia-framework 4.0.0 → 4.0.5

package/CLAUDE.md

@@ -23,25 +23,37 @@ Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, ElevenLab
 
 ## The Road (how projects flow)
 
+v4 hierarchy: **Project → Journey → Milestones (2–5, Handoff always last) → Phases (2–5 tasks each) → Tasks (one commit, one verification contract).**
+
 ```
-/qualia-new → set up project
+/qualia-new        → kickoff + parallel research + JOURNEY.md (all milestones upfront)
+                     add --auto to chain the whole road end-to-end
      ↓
-For each phase:
-  /qualia-plan  → plan the phase (planner agent, fresh context)
-  /qualia-build → build it (builder subagents per task, fresh context each)
-  /qualia-verify → verify it works (verifier agent, goal-backward checks)
+For each milestone, for each phase:
+  /qualia-plan     → plan the phase (planner + plan-checker revision loop, fresh context)
+  /qualia-build    → build it (builder subagents per task, wave-based parallel)
+  /qualia-verify   → goal-backward check (verifier agent, fresh context)
      ↓
-/qualia-polish → design/UX pass
-/qualia-ship   → deploy to production
-/qualia-handoff → deliver to client
+/qualia-milestone  → close milestone, archive artifacts, prep next (human gate)
+     ↓ (repeat for each milestone until Handoff)
+Final milestone = Handoff:
+  /qualia-polish   → design/UX pass (Phase 1 of Handoff)
+  (content + SEO)  → Phase 2
+  (final QA)       → Phase 3
+  /qualia-ship     → deploy to production (quality gates → deploy → verify)
+  /qualia-handoff  → 4 deliverables: credentials, doc, final update, report
      ↓
 Done.
 
-Lost? → /qualia (tells you exactly what's next)
-Quick fix? → /qualia-quick (skip planning for small tasks)
-End of day? → /qualia-report (mandatory before clock-out)
+Lost?        → /qualia        (state router — tells you the next command)
+Stuck/weird? → /qualia-idk    (diagnostic — spawns plan-view + code-view agents in parallel)
+Quick fix?   → /qualia-quick  (skip planning for small tasks)
+Paused?      → /qualia-resume (restore from .continue-here.md or STATE.md)
+End of day?  → /qualia-report (mandatory before clock-out; writes ERP payload)
 ```
 
+**Human gates:** journey approval after `/qualia-new`, then one at each milestone boundary via `/qualia-milestone`. `--auto` runs everything between gates automatically.
+
 ## Context Isolation
 Every task runs in a fresh subagent context. Task 50 gets the same quality as Task 1.
 - Planner gets: PROJECT.md + phase requirements

package/agents/plan-checker.md

@@ -34,7 +34,7 @@ Plan must have YAML frontmatter with:
 
 **FAIL if:** frontmatter missing, incomplete, or `goal` differs from ROADMAP.md.
 
-### Rule 2: Every task has the 6 mandatory story-file fields
+### Rule 2: Every task has the 7 mandatory story-file fields
 
 Each `## Task N — title` block must include ALL of these:
 

package/agents/roadmapper.md

@@ -85,14 +85,18 @@ Use the research SUMMARY.md as your starting point. Don't force-fit the template
 - **Phases** — 2-5 phases. For Milestone 1, include full detail (goal + success criteria). For M2..M{N-1}, names + one-line goals are enough (progressive detail — full detail gets written when that milestone opens). For Handoff, use the fixed 4-phase template.
 - **Requirements covered** — list the REQ-IDs this milestone delivers
 
-### 4. Build ROADMAP.md — ONLY Milestone 1's phases (fully detailed)
+### 4. Build ROADMAP.md — Milestone 1's phases (progressive detail by default)
 
-The current milestone gets full phase detail. Future milestones stay as sketches in JOURNEY.md until they open.
+Check the `<full_detail>` flag in your prompt:
 
-For each phase in Milestone 1:
+**`full_detail=false` (default):** Only Milestone 1 gets full phase detail in ROADMAP.md. Future milestones stay as sketches in JOURNEY.md until they open. This matches progressive-detail planning and is the recommended default.
+
+**`full_detail=true`:** Write full phase detail for EVERY milestone (M1..Handoff) in ROADMAP.md, sectioned by milestone. Use when the client wants a fully-committed plan at kickoff. Trade-off: M2+ detail often needs revision as M1 ships — flag this in your summary.
+
+For each phase in the milestone(s) you're detailing:
 - **Name** + **goal** (one line)
 - **Success criteria** — 2-5 observable user-facing behaviors
-- **Requirements covered** — REQ-IDs from REQUIREMENTS.md Milestone 1 section
+- **Requirements covered** — REQ-IDs from REQUIREMENTS.md section for that milestone
 
 ### 5. Validate Coverage
 
@@ -104,7 +108,8 @@ Before writing, verify:
 - [ ] Final milestone is literally named "Handoff" with the 4 standard phases
 - [ ] No milestone depends on a later milestone
 - [ ] Milestone 1 has full phase-level detail (goals + success criteria) ready for `/qualia-plan 1`
-- [ ] M2..M{N-1} have phase names + one-line goals (sketch, not full detail)
+- [ ] If `full_detail=false` (default): M2..M{N-1} have phase names + one-line goals (sketch, not full detail)
+- [ ] If `full_detail=true`: every milestone in ROADMAP.md has full phase detail; flag this mode explicitly in your summary output
 
 If any check fails, fix it. The orchestrator trusts your output.
 

package/bin/cli.js

@@ -126,21 +126,35 @@ function cmdUpdate() {
 // non-Qualia entries in settings.json (other hooks, user env vars, etc.).
 // --yes / -y skips the confirmation prompt for scripted use.
 
-// 8 Qualia hook filenames — only these are removed from ~/.claude/hooks/,
-// any other hooks the user dropped in there are left alone.
+// Current Qualia hook filenames — only these are removed from ~/.claude/hooks/,
+// any other hooks the user dropped in there are left alone. The LEGACY set
+// lists hooks that were shipped by older framework versions but have since
+// been removed; uninstall still tries to clean them so old installs get a
+// clean removal.
 const QUALIA_HOOK_FILES = [
   "session-start.js",
   "auto-update.js",
   "branch-guard.js",
   "pre-push.js",
-  "block-env-edit.js",
   "migration-guard.js",
   "pre-deploy-gate.js",
   "pre-compact.js",
 ];
+const QUALIA_LEGACY_HOOK_FILES = [
+  "block-env-edit.js", // removed in v3.2.0
+];
 
-// 4 Qualia agents — only these are removed.
-const QUALIA_AGENT_FILES = ["planner.md", "builder.md", "verifier.md", "qa-browser.md"];
+// 8 Qualia agents — only these are removed.
+const QUALIA_AGENT_FILES = [
+  "planner.md",
+  "builder.md",
+  "verifier.md",
+  "qa-browser.md",
+  "plan-checker.md",
+  "researcher.md",
+  "research-synthesizer.md",
+  "roadmapper.md",
+];
 
 // 3 Qualia bin scripts.
 const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js"];
@@ -210,14 +224,14 @@ function cleanSettingsJson(counters) {
   };
 
   if (settings.hooks && typeof settings.hooks === "object") {
-    for (const key of ["SessionStart", "PreToolUse", "PreCompact"]) {
-      if (settings.hooks[key]) {
-        const cleaned = filterHookArray(settings.hooks[key]);
-        if (cleaned && cleaned.length > 0) {
-          settings.hooks[key] = cleaned;
-        } else {
-          delete settings.hooks[key];
-        }
+    // Iterate every hook event key, not a hardcoded subset — future hook
+    // events added by Claude Code or the framework get cleaned automatically.
+    for (const key of Object.keys(settings.hooks)) {
+      const cleaned = filterHookArray(settings.hooks[key]);
+      if (cleaned && cleaned.length > 0) {
+        settings.hooks[key] = cleaned;
+      } else {
+        delete settings.hooks[key];
       }
     }
     // If hooks is now empty, remove it entirely.
@@ -305,8 +319,8 @@ async function cmdUninstall() {
     safeUnlink(path.join(CLAUDE_DIR, "agents", f), counters);
   }
 
-  // Hooks — only the 8 Qualia ones.
-  for (const f of QUALIA_HOOK_FILES) {
+  // Hooks — current set plus any legacy hook filenames from older versions.
+  for (const f of [...QUALIA_HOOK_FILES, ...QUALIA_LEGACY_HOOK_FILES]) {
     safeUnlink(path.join(CLAUDE_DIR, "hooks", f), counters);
   }
 
@@ -552,7 +566,7 @@ function cmdMigrate() {
 
   // Check PreToolUse hooks — ensure all critical hooks are present
   const requiredBashHooks = ["auto-update.js", "branch-guard.js", "pre-push.js", "pre-deploy-gate.js"];
-  const requiredEditHooks = ["block-env-edit.js", "migration-guard.js"];
+  const requiredEditHooks = ["migration-guard.js"];
 
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
@@ -644,7 +658,7 @@ function cmdMigrate() {
   if (!settings.mcpServers["next-devtools"]) {
     settings.mcpServers["next-devtools"] = {
       command: "npx",
-      args: ["next-devtools-mcp@0.3.10"],
+      args: ["next-devtools-mcp@latest"],
       disabled: false,
     };
     changes++;
@@ -755,6 +769,109 @@ function cmdAnalytics() {
   console.log("");
 }
 
+// ─── ERP Ping ───────────────────────────────────────────
+// Synthetic POST to ERP /api/v1/reports to verify connectivity, auth key
+// validity, and endpoint health. Uses a distinct dry_run=true flag in the
+// payload so receivers can filter these out of real report views.
+
+function cmdErpPing() {
+  banner();
+  console.log("");
+
+  const cfg = readConfig();
+  const erpUrl = (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net";
+  const erpEnabled = !(cfg.erp && cfg.erp.enabled === false);
+  const keyFile = path.join(CLAUDE_DIR, ".erp-api-key");
+
+  console.log(`  ${DIM}URL:${RESET}       ${WHITE}${erpUrl}${RESET}`);
+  console.log(`  ${DIM}Enabled:${RESET}   ${erpEnabled ? `${GREEN}yes${RESET}` : `${YELLOW}no (erp.enabled=false)${RESET}`}`);
+
+  let apiKey = "";
+  try {
+    apiKey = fs.readFileSync(keyFile, "utf8").trim();
+  } catch {}
+  if (!apiKey) {
+    console.log(`  ${DIM}Key:${RESET}       ${RED}missing${RESET} ${DIM}(${keyFile})${RESET}`);
+    console.log("");
+    console.log(`  ${RED}✗ Cannot ping — no API key. Ask Fawzi for one.${RESET}`);
+    console.log("");
+    process.exit(1);
+  }
+  console.log(`  ${DIM}Key:${RESET}       ${GREEN}present${RESET} ${DIM}(${apiKey.length} bytes)${RESET}`);
+  console.log("");
+
+  if (!erpEnabled) {
+    console.log(`  ${YELLOW}ERP is disabled in config. Enable with:${RESET}`);
+    console.log(`  ${DIM}  qualia-framework erp-ping --enable${RESET}`);
+    console.log("");
+    process.exit(1);
+  }
+
+  const payload = JSON.stringify({
+    project: "qualia-framework-erp-ping",
+    project_id: "ping",
+    team_id: "qualia-solutions",
+    client_report_id: "QS-PING-00",
+    phase: 0,
+    phase_name: "ping",
+    status: "setup",
+    milestone: 0,
+    milestone_name: "ping",
+    submitted_by: cfg.installed_by || "ping",
+    submitted_at: new Date().toISOString(),
+    notes: "ERP PING — synthetic connectivity test, safe to ignore",
+    dry_run: true,
+  });
+
+  const started = Date.now();
+  const r = spawnSync("curl", [
+    "-sS", "-X", "POST",
+    "-H", `Authorization: Bearer ${apiKey}`,
+    "-H", "Content-Type: application/json",
+    "-d", payload,
+    "--max-time", "10",
+    "-w", "\n__HTTP__%{http_code}",
+    `${erpUrl}/api/v1/reports`,
+  ], { encoding: "utf8", timeout: 12000 });
+
+  const duration = Date.now() - started;
+  const raw = (r.stdout || "") + (r.stderr || "");
+  const httpMatch = raw.match(/__HTTP__(\d+)/);
+  const httpCode = httpMatch ? httpMatch[1] : "—";
+  const body = raw.replace(/\n?__HTTP__\d+/, "").trim();
+
+  console.log(`  ${DIM}Response:${RESET}  ${WHITE}HTTP ${httpCode}${RESET} ${DIM}(${duration}ms)${RESET}`);
+  if (body) {
+    try {
+      const j = JSON.parse(body);
+      if (j.ok && j.report_id) {
+        console.log(`  ${DIM}report_id:${RESET} ${GREEN}${j.report_id}${RESET}`);
+      }
+      if (!j.ok && j.error) {
+        console.log(`  ${DIM}error:${RESET}     ${RED}${j.error}${RESET} ${DIM}${j.message || ""}${RESET}`);
+      }
+    } catch {
+      console.log(`  ${DIM}body:${RESET}      ${WHITE}${body.slice(0, 200)}${RESET}`);
+    }
+  }
+  console.log("");
+
+  if (httpCode === "200") {
+    console.log(`  ${GREEN}✓ ERP reachable, key valid, endpoint healthy.${RESET}`);
+    console.log("");
+    process.exit(0);
+  }
+  if (httpCode === "401") {
+    console.log(`  ${RED}✗ API key rejected. Ask Fawzi for a fresh key.${RESET}`);
+  } else if (httpCode === "—") {
+    console.log(`  ${RED}✗ No response — DNS, TLS, or network issue.${RESET}`);
+  } else {
+    console.log(`  ${YELLOW}! Unexpected response. Check ERP status.${RESET}`);
+  }
+  console.log("");
+  process.exit(1);
+}
+
 function cmdHelp() {
   banner();
   console.log("");
@@ -767,6 +884,7 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}team${RESET}         Manage team members (${DIM}list|add|remove${RESET})`);
   console.log(`    qualia-framework ${TEAL}traces${RESET}       View recent hook telemetry`);
   console.log(`    qualia-framework ${TEAL}analytics${RESET}    Show outcome scoring & gap cycle stats`);
+  console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
   console.log("");
   console.log(`  ${WHITE}After install:${RESET}`);
   console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
@@ -819,6 +937,10 @@ switch (cmd) {
   case "stats":
     cmdAnalytics();
     break;
+  case "erp-ping":
+  case "ping":
+    cmdErpPing();
+    break;
   default:
     cmdHelp();
 }

package/bin/install.js

@@ -517,7 +517,18 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     ok(".erp-api-key (from $QUALIA_ERP_KEY)");
   } else if (fs.existsSync(erpKeyFile)) {
     try { fs.chmodSync(erpKeyFile, 0o600); } catch {}
-    ok(".erp-api-key (existing — preserved)");
+    // Sanity check: warn on a clearly-empty/placeholder key. Genuine tokens
+    // from the ERP are ≥ 20 bytes; under 10 is almost certainly a mistake.
+    try {
+      const existingKey = fs.readFileSync(erpKeyFile, "utf8").trim();
+      if (existingKey.length < 10) {
+        warn(`.erp-api-key exists but looks truncated (${existingKey.length} bytes) — verify with 'qualia-framework erp-ping'`);
+      } else {
+        ok(".erp-api-key (existing — preserved)");
+      }
+    } catch {
+      ok(".erp-api-key (existing — preserved)");
+    }
   } else {
     // Disable ERP in the config we just wrote.
     try {
@@ -599,16 +610,23 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   // bash/Git Bash requirement on Windows.
   const hd = path.join(CLAUDE_DIR, "hooks");
   const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
-  settings.hooks = {
+  const QUALIA_HOOK_SET = new Set([
+    "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
+    "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
+  ]);
+  const isQualiaHookCmd = (cmd) => {
+    if (typeof cmd !== "string") return false;
+    for (const h of QUALIA_HOOK_SET) if (cmd.includes(h)) return true;
+    return false;
+  };
+
+  // Our canonical hook definitions, grouped per event/matcher.
+  const qualiaHooks = {
     SessionStart: [
       {
         matcher: ".*",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("session-start.js"),
-            timeout: 5,
-          },
+          { type: "command", command: nodeCmd("session-start.js"), timeout: 5 },
         ],
       },
     ],
@@ -616,44 +634,16 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "Bash",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("auto-update.js"),
-            timeout: 5,
-          },
-          {
-            type: "command",
-            if: "Bash(git push*)",
-            command: nodeCmd("branch-guard.js"),
-            timeout: 5,
-            statusMessage: "⬢ Checking branch permissions...",
-          },
-          {
-            type: "command",
-            if: "Bash(git push*)",
-            command: nodeCmd("pre-push.js"),
-            timeout: 15,
-            statusMessage: "⬢ Syncing tracking...",
-          },
-          {
-            type: "command",
-            if: "Bash(vercel --prod*)",
-            command: nodeCmd("pre-deploy-gate.js"),
-            timeout: 180,
-            statusMessage: "⬢ Running quality gates...",
-          },
+          { type: "command", command: nodeCmd("auto-update.js"), timeout: 5 },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
+          { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "⬢ Running quality gates..." },
         ],
       },
       {
         matcher: "Edit|Write",
         hooks: [
-          {
-            type: "command",
-            if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)",
-            command: nodeCmd("migration-guard.js"),
-            timeout: 10,
-            statusMessage: "⬢ Checking migration safety...",
-          },
+          { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "⬢ Checking migration safety..." },
         ],
       },
     ],
@@ -661,17 +651,27 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "compact",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("pre-compact.js"),
-            timeout: 15,
-            statusMessage: "⬢ Saving state...",
-          },
+          { type: "command", command: nodeCmd("pre-compact.js"), timeout: 15, statusMessage: "⬢ Saving state..." },
         ],
       },
     ],
   };
 
+  // Merge user hooks: strip Qualia-owned commands, preserve everything else.
+  if (!settings.hooks || typeof settings.hooks !== "object") settings.hooks = {};
+  for (const event of Object.keys(qualiaHooks)) {
+    const existing = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    // Remove Qualia-owned command entries from each matcher block, drop empty blocks.
+    const cleaned = [];
+    for (const block of existing) {
+      if (!block || !Array.isArray(block.hooks)) continue;
+      const kept = block.hooks.filter((h) => !isQualiaHookCmd(h && h.command));
+      if (kept.length > 0) cleaned.push({ ...block, hooks: kept });
+    }
+    // Append our canonical blocks after the preserved user ones.
+    settings.hooks[event] = [...cleaned, ...qualiaHooks[event]];
+  }
+
   // Permissions — no restrictions on env files or branches.
   // Everyone can read/write .env, push to main.
   if (!settings.permissions) settings.permissions = {};
@@ -684,7 +684,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   if (!settings.mcpServers["next-devtools"]) {
     settings.mcpServers["next-devtools"] = {
       command: "npx",
-      args: ["next-devtools-mcp@0.3.10"],
+      args: ["next-devtools-mcp@latest"],
       disabled: false,
     };
     ok("MCP: next-devtools (runtime error visibility for Next.js projects)");

package/bin/qualia-ui.js

@@ -320,10 +320,10 @@ function cmdJourneyTree(journeyPath) {
 
   // Project name from frontmatter if present
   const projMatch = content.match(/^project:\s*"?(.+?)"?\s*$/m);
-  const projectName = projMatch ? projMatch[1] : projectName();
+  const projName = projMatch ? projMatch[1] : projectName();
 
   console.log("");
-  console.log(`  ${TEAL}${BOLD}◯${RESET} ${WHITE}${BOLD}JOURNEY${RESET} ${DIM}▸${RESET} ${WHITE}${projectName}${RESET}`);
+  console.log(`  ${TEAL}${BOLD}◯${RESET} ${WHITE}${BOLD}JOURNEY${RESET} ${DIM}▸${RESET} ${WHITE}${projName}${RESET}`);
   console.log(`  ${RULE_DIM}`);
   console.log(`  ${DIM}${milestones.length} milestones · currently at M${currentMilestone}${RESET}`);
   console.log("");