qualia-framework 4.0.3 → 4.1.0

package/README.md

@@ -9,19 +9,21 @@ It is not an application framework like Rails or Next.js. It doesn't generate co
 ## Install
 
 ```bash
-npx qualia-framework install
+npx qualia-framework@latest install
 ```
 
 Enter your team code when prompted. Get your code from Fawzi.
 
+> **Why `@latest`?** npx caches packages at `~/.npm/_npx/` and has no time-based TTL — `npx qualia-framework install` (without `@latest`) will silently run whatever version you happened to fetch the first time, even if a newer one shipped. Always pin `@latest` when installing or upgrading. If a stale cache still bites you: `npx clear-npx-cache` then re-run.
+
 **Other commands:**
 ```bash
-npx qualia-framework version    # Check installed version + updates
-npx qualia-framework update     # Update to latest (remembers your code)
-npx qualia-framework uninstall  # Clean removal from ~/.claude/
-npx qualia-framework team list  # Show team members
-npx qualia-framework team add   # Add a team member
-npx qualia-framework traces     # View recent hook telemetry
+npx qualia-framework@latest version    # Check installed version + updates
+npx qualia-framework@latest update     # Update to latest (remembers your code)
+npx qualia-framework@latest uninstall  # Clean removal from ~/.claude/
+npx qualia-framework@latest team list  # Show team members
+npx qualia-framework@latest team add   # Add a team member
+npx qualia-framework@latest traces     # View recent hook telemetry
 ```
 
 ## Usage
@@ -177,7 +179,7 @@ Plans are grouped into waves for parallel execution. No fancy DAG solver — the
 ## Architecture
 
 ```
-npx qualia-framework install
+npx qualia-framework@latest install
      |
      v
 ~/.claude/

package/agents/builder.md

@@ -11,8 +11,18 @@ You execute ONE task from a phase plan. You run in a fresh context — you have
 ## Input
 You receive: one task block from the plan + PROJECT.md context.
 
-## Output
-Working code + atomic git commit.
+## Output Contract
+
+Return EXACTLY one of these three prefixed lines as the first line of your final message:
+
+- `DONE — Task {N}: {commit_hash}` — followed by a list of files changed (one per line), then any trivial/minor deviation notes. Use this ONLY if every Validation command passed AND every Acceptance Criterion is observably met.
+- `BLOCKED — {reason}` — followed by a JSON block documenting the block:
+  ```json
+  {"type": "major_deviation|dependency_missing|wave_ordering", "task": {N}, "file": "path/to/file", "planned": "...", "actual": "...", "impact": "..."}
+  ```
+- `PARTIAL — {what completed}; remaining: {what's left}` — only if context limit forces early stop. Commit what works.
+
+Never return without one of these three prefixes. The orchestrator parses the prefix to route next steps.
 
 ## How to Execute
 

package/agents/plan-checker.md

@@ -1,12 +1,12 @@
 ---
 name: qualia-plan-checker
-description: Validates a phase plan before execution. Checks task specificity, wave assignment, verification contracts, and coverage of success criteria. Spawned by qualia-plan in a revision loop (max 3 iterations).
+description: Validates a phase plan before execution. Checks task specificity, wave assignment, verification contracts, and coverage of success criteria. Spawned by qualia-plan in a revision loop (max 2 iterations).
 tools: Read, Bash, Grep
 ---
 
 # Plan Checker
 
-You validate phase plans before they go to the builder. You do NOT write plans — you evaluate them. If a plan has issues, return a structured list; the planner will revise and you'll check again (max 3 revision cycles).
+You validate phase plans before they go to the builder. You do NOT write plans — you evaluate them. If a plan has issues, return a structured list; the planner will revise and you'll check again (max 2 revision cycles).
 
 ## Input
 
@@ -105,6 +105,28 @@ If `.planning/phase-{N}-context.md` exists, read its "Locked Decisions" section.
 
 **FAIL if:** plan contradicts a locked decision (e.g., context says "use library X" but plan uses library Y).
 
+### Rule 8: Validation commands test behavior, not just existence
+
+Each task's `**Validation:**` list must contain at least one `grep-match` or `command-exit` check — a command that proves the code DOES something. A task whose ONLY validation is `test -f {file}` will pass even if the file contains only `// TODO`.
+
+**FAIL if:** any task has only `file-exists`-type validations. Require at least one of:
+- `grep -c "{specific_call}" {file}` returning non-zero
+- `npx tsc --noEmit` exiting 0
+- `curl -s {endpoint}` returning expected content
+- Any command whose success/failure depends on the code doing something, not just being there
+
+**Pass examples:**
+- `grep -c "signInWithPassword" src/lib/auth.ts` → ≥ 1
+- `npx tsc --noEmit 2>&1 | grep -c "error"` → 0
+
+**Fail examples:**
+- `test -f src/lib/auth.ts && echo EXISTS` (only) — file exists, but could be empty or stubbed
+- `ls src/components/Chat.tsx` (only) — same problem
+
+## Tool Budget
+
+Read the plan file once. Grep the codebase only to validate Rule 7 (locked decisions). Do NOT speculatively check whether files listed in the plan already exist — that's the builder's job. Max 10 tool calls per invocation.
+
 ## Output Format
 
 ### If all rules pass:
@@ -145,12 +167,12 @@ The planner uses your output to revise the plan. Be specific enough that the rev
 
 ## Revision Limits
 
-You will be called up to 3 times per plan. If the plan still fails after 3 revisions, report:
+You will be called up to 2 times per plan. If the plan still fails after 2 revisions, report:
 
 ```
 ## BLOCKED
 
-Plan failed validation after 3 revision cycles. Issues remaining:
+Plan failed validation after 2 revision cycles. Issues remaining:
 
 {list}
 

package/agents/planner.md

@@ -9,7 +9,15 @@ tools: Read, Write, Bash, Glob, Grep, WebFetch
 You create phase plans. Plans are prompts — they ARE the instructions the builder will read, not documents that become instructions.
 
 ## Input
-You receive: PROJECT.md + the current phase goal + success criteria from the roadmap.
+
+- `<project_context>` — inlined `.planning/PROJECT.md` contents
+- `<current_state>` — inlined `.planning/STATE.md` contents
+- `<phase_details>` — phase goal + success criteria + REQ-IDs from ROADMAP.md
+- `<locked_decisions>` (optional) — Locked Decisions from `.planning/phase-{N}-context.md` if it exists
+- `<research_findings>` (optional) — inlined `.planning/phase-{N}-research.md` if present
+- `<relevant_learnings>` (optional) — applicable patterns from `~/.claude/knowledge/learned-patterns.md`
+- `<revision_mode>` (optional, boolean) — when `true`, also receives `<current_plan>` and `<checker_feedback>`; revise in place, don't rewrite
+- `<gaps_mode>` (optional, boolean) — when `true`, also receives `<verification_path>`; create gap-closure tasks only
 
 ## Output
 Write `.planning/phase-{N}-plan.md` — a plan file with 2-5 tasks.
@@ -29,11 +37,32 @@ Start from the phase goal. Work backwards:
 
 Each truth → one task. 2-5 tasks per phase. Each task must fit in one context window.
 
-### 3. Assign Waves
-- **Wave 1:** Tasks with no dependencies (run in parallel)
-- **Wave 2:** Tasks that depend on Wave 1 (run after Wave 1 completes)
+### 3. Assign Waves (file-based dependency graph — deterministic)
+
+Wave assignment is NOT a vibes call. Use this mechanical algorithm:
+
+1. **Build adjacency list.** For each task T, define:
+   - `writes(T)` = the set of file paths in `**Files:**` that T creates or modifies
+   - `reads(T)` = file paths T consumes from `**Context:**` (@references) + any paths declared in `**Depends on:**`
+2. **Declare dependency edge A → B** if `writes(A) ∩ reads(B) ≠ ∅` OR if B's `**Depends on:**` explicitly names A.
+3. **Topological-sort into waves.** Wave 1 = all tasks with in-degree 0 (no incoming edges). Wave 2 = tasks whose only dependencies are in Wave 1. Continue until all tasks placed.
+4. **Parallel-safety check.** No two tasks in the same wave may share a file in their `writes()` sets. If they do, serialize them into consecutive waves.
+
+Two tasks that both *read* the same file (same entry in `Context:`) are fine in the same wave — only *write conflicts* force serialization.
+
 - Most phases need 1-2 waves. If you need 3+, your tasks are too granular.
 
+**Worked example:**
+
+| Task | Files (writes) | Context/Depends-on (reads) | Edges | Wave |
+|------|----------------|----------------------------|-------|------|
+| T1 — Create auth lib | `src/lib/auth.ts` | `@.planning/PROJECT.md` | none | 1 |
+| T2 — Create login page | `src/app/login/page.tsx` | `@src/lib/auth.ts` (reads T1's write) | T1 → T2 | 2 |
+| T3 — Create signup page | `src/app/signup/page.tsx` | `@src/lib/auth.ts` (reads T1's write) | T1 → T3 | 2 |
+| T4 — Add RLS policies | `supabase/migrations/001.sql` | `@.planning/PROJECT.md` | none | 1 |
+
+T1 and T4 → Wave 1 (no shared writes, both reading PROJECT.md is fine). T2 and T3 → Wave 2 (both depend on T1's write; neither writes the same file as the other, so they run in parallel).
+
 ### 4. Write the Plan (Story-File Format)
 
 Plans are STORY FILES, not task lists. Every task is a self-contained package that embeds *why*, *what*, and *how to verify* — so the builder can execute without re-reading PRDs and the verifier has explicit acceptance targets.

package/agents/qa-browser.md

@@ -11,7 +11,11 @@ You verify that the **running app actually looks and behaves right** — not jus
 **Critical mindset:** You are the user. You don't trust the code — you drive the app and see what happens. If it breaks at 375px, it's broken. If the console screams, it's broken. If clicking the primary CTA does nothing, it's broken.
 
 ## Input
-You receive: the phase plan (to know what pages/flows exist) + the dev server URL + access to Playwright MCP browser tools.
+
+- `<plan_path>` — path to `.planning/phase-{N}-plan.md`
+- `<dev_server_url>` — e.g. `http://localhost:3000`. If omitted, probe ports 3000–3001 as fallback; if no server answers within 10s, write `BLOCKED: dev server not reachable` and exit.
+- `<phase_number>` — integer, used for the verification filename
+- Access to Playwright MCP browser tools
 
 ## Output
 Append a `## Browser QA` section to `.planning/phase-{N}-verification.md` with PASS/FAIL per check.

package/agents/research-synthesizer.md

@@ -48,6 +48,8 @@ Don't duplicate full documents. Summarize the 3-5 most important items from each
 
 This is the most important section. Suggest the **full milestone arc**, not just a v1 phase list.
 
+**Evidence requirement:** Every milestone suggestion MUST cite at least one research finding from STACK.md, FEATURES.md, ARCHITECTURE.md, or PITFALLS.md as justification. Format the citation as `[DIMENSION.md: <specific finding or item>]` — e.g., `[FEATURES.md: table-stakes AUTH-*]` or `[PITFALLS.md: risk P3, stall risk for downstream milestones]`. Milestones without a citable finding are speculative — mark them explicitly with `[speculative — no source]` and the roadmapper will scrutinize.
+
 Based on:
 - FEATURES.md split (table stakes = v1 across milestones, differentiators = later milestones or post-handoff)
 - ARCHITECTURE.md build order → what depends on what, which foundation must land in Milestone 1 to support final-milestone requirements

package/agents/researcher.md

@@ -17,6 +17,10 @@ You receive from the orchestrator:
 - `<milestone_context>` — greenfield or subsequent
 - `<output_path>` — absolute path where you write your research file
 
+## Tool Budget
+
+Maximum 8 external calls total per invocation: 3 Context7 queries + 3 WebFetch calls + 2 WebSearch queries. If you exhaust this budget, write what you have and mark remaining sections as `confidence: LOW`. Research is time-boxed, not exhaustive — a 10-minute deep dive with concrete sources beats a 30-minute wander.
+
 ## Output
 
 Write exactly ONE file to `<output_path>`, using the template matching your dimension:

package/agents/roadmapper.md

@@ -17,6 +17,7 @@ You receive:
 - `.planning/research/SUMMARY.md` — research synthesis (optional — may not exist if research was skipped)
 - `.planning/config.json` — project config (`depth`, `template_type`)
 - User's confirmed feature scope (from the scoping conversation in qualia-new)
+- `<full_detail>` — boolean (default `false`). When `true`, write full phase detail for EVERY milestone in ROADMAP.md, not just M1. Passed by the orchestrator when the user runs `/qualia-new --full-plan`.
 
 ## Output
 
@@ -85,14 +86,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 +109,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/agents/verifier.md

@@ -11,10 +11,17 @@ You verify that a phase achieved its GOAL, not just completed its TASKS.
 **Critical mindset:** Do NOT trust claims about what was built. Summaries document what Claude SAID it did. You verify what ACTUALLY EXISTS in the code. These often differ.
 
 ## Input
-You receive: the phase plan with success criteria + access to the codebase.
+
+- `<plan_path>` — path to `.planning/phase-{N}-plan.md`
+- `<project_context>` — inlined `.planning/PROJECT.md` contents (for Quality scoring against project conventions)
+- `<previous_verification>` (optional) — inlined `.planning/phase-{N}-verification.md` from a prior run
 
 ## Output
-Write `.planning/phase-{N}-verification.md` — PASS or FAIL with evidence.
+Write `.planning/phase-{N}-verification.md` — PASS or FAIL with evidence. Apply the Grounding Protocol: every finding needs `file:line — "quoted"` evidence, no hedging, scores with rubric criterion citations.
+
+## Tool Budget
+
+Maximum 25 Bash/Grep calls per invocation. Prefer one multi-pattern grep over many single-pattern greps. If you exhaust the budget, write what you found and mark unchecked criteria as `INSUFFICIENT EVIDENCE` — do not fabricate.
 
 ## Goal-Backward Verification
 
@@ -260,7 +267,19 @@ Phase goal: "Working real-time chat interface with message history."
 
 ## Design Verification (for phases with frontend work)
 
-If the phase involved UI/frontend tasks, add a **Design Quality** section to the report.
+**Gate (run first):** Only execute this section if the phase touched frontend.
+
+```bash
+# Is this a frontend phase?
+FRONTEND=false
+if grep -qE "\.tsx|\.jsx|\.css|\.scss|app/|components/|pages/|Persona:\s*(frontend|ux)" .planning/phase-{N}-plan.md 2>/dev/null; then
+  FRONTEND=true
+fi
+```
+
+If `FRONTEND=false`, write `Design Verification: N/A (no frontend tasks in phase)` in the report and skip the rest of this section. This saves ~40 greps on backend-only phases.
+
+If `FRONTEND=true`, proceed. Add a **Design Quality** section to the report.
 
 First, read the project's DESIGN.md:
 ```bash

package/bin/cli.js

@@ -144,8 +144,17 @@ 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"];
@@ -557,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 = [];
 
@@ -649,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++;
@@ -760,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("");
@@ -772,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?`);
@@ -824,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 {
@@ -673,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/state.js

@@ -194,6 +194,7 @@ function ensureLifetime(t) {
   if (typeof t.milestone !== "number") t.milestone = 1;
   if (typeof t.milestone_name !== "string") t.milestone_name = "";
   if (!Array.isArray(t.milestones)) t.milestones = [];
+  if (typeof t.report_seq !== "number") t.report_seq = 0;
   if (!t.lifetime || typeof t.lifetime !== "object") {
     t.lifetime = {
       tasks_completed: 0,
@@ -205,6 +206,26 @@ function ensureLifetime(t) {
   return t;
 }
 
+// Parse JOURNEY.md and extract the human name of the Nth milestone.
+// Matches headers like:
+//   ## Milestone 2 · Core Features
+//   ## Milestone 2 · Core Features     [CURRENT]
+//   ## Milestone 5 · Handoff           [FINAL]
+// Returns "" if JOURNEY.md is absent or the milestone isn't in it.
+function readNextMilestoneNameFromJourney(milestoneNum) {
+  try {
+    const journeyPath = path.join(PLANNING, "JOURNEY.md");
+    if (!fs.existsSync(journeyPath)) return "";
+    const content = fs.readFileSync(journeyPath, "utf8");
+    const re = new RegExp(`^##\\s+Milestone\\s+${milestoneNum}\\s*[·•-]\\s*([^\\n\\[]+)`, "m");
+    const m = content.match(re);
+    if (m && m[1]) return m[1].trim();
+    return "";
+  } catch {
+    return "";
+  }
+}
+
 function readState() {
   try {
     return fs.readFileSync(STATE_FILE, "utf8");
@@ -1141,7 +1162,12 @@ function cmdCloseMilestone(opts) {
   t.lifetime.total_phases += (parseInt(t.total_phases) || 0);
   t.lifetime.last_closed_milestone = closedMilestone;
   t.milestone = closedMilestone + 1;
-  t.milestone_name = ""; // cleared; /qualia-milestone reads next one from JOURNEY.md
+  // Try to pre-populate next milestone's name from JOURNEY.md so the ERP
+  // tree view doesn't show a blank between close-milestone and the next
+  // state.js init --force (which happens in /qualia-milestone step 7).
+  // If JOURNEY.md is missing or unparseable, fall through with blank —
+  // /qualia-milestone will still set it via init --force.
+  t.milestone_name = readNextMilestoneNameFromJourney(t.milestone);
   t.last_updated = new Date().toISOString();
 
   writeTracking(t);
@@ -1238,6 +1264,27 @@ function cmdBackfillLifetime(opts) {
   });
 }
 
+// ─── Next Report ID ──────────────────────────────────────
+// Increments report_seq and returns the next QS-REPORT-NN id. Per-project
+// counter (lives in tracking.json). /qualia-report calls this to tag each
+// session report with a stable, human-readable client ID before POSTing
+// to the ERP. If --peek is passed, the next id is returned WITHOUT
+// incrementing — useful for --dry-run previews.
+function cmdNextReportId(opts) {
+  const t = readTracking();
+  if (!t) return output(fail("NO_PROJECT", "No .planning/ found."));
+  ensureLifetime(t);
+  const peek = !!opts.peek;
+  const next = (parseInt(t.report_seq) || 0) + 1;
+  const id = `QS-REPORT-${String(next).padStart(2, "0")}`;
+  if (!peek) {
+    t.report_seq = next;
+    t.last_updated = new Date().toISOString();
+    writeTracking(t);
+  }
+  output({ ok: true, action: "next-report-id", report_id: id, report_seq: next, peeked: peek });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -1289,11 +1336,14 @@ try {
     case "backfill-lifetime":
       cmdBackfillLifetime(opts);
       break;
+    case "next-report-id":
+      cmdNextReportId(opts);
+      break;
     default:
       output(
         fail(
           "UNKNOWN_COMMAND",
-          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime> [--options]`
+          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|next-report-id> [--options]`
         )
       );
   }