qualia-framework 4.0.3 → 4.0.5

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

@@ -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]`
         )
       );
   }

package/bin/statusline.js

@@ -154,6 +154,8 @@ try {
 } catch {}
 
 // ─── Phase info from .planning/tracking.json ─────────────
+// Shows: [M{n}·{milestoneName}] P{phase}/{total} T{done}/{total} {status} [!{blockers}]
+// 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,12 +164,46 @@ try {
     const phase = Number(tracking.phase || 0) || 0;
     const total = Number(tracking.total_phases || 0) || 0;
     const status = String(tracking.status || "");
+    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 = [];
+
+    // Milestone: M{n}·{shortName}   (short name trimmed to 14 chars)
+    if (milestone > 0) {
+      let mStr = `M${milestone}`;
+      if (milestoneName) {
+        const shortName = milestoneName.length > 14 ? milestoneName.slice(0, 13) + "…" : milestoneName;
+        mStr += `${DIM}·${RESET}${TEAL_GLOW}${shortName}`;
+      }
+      parts.push(`${TEAL}${mStr}${RESET}`);
+    }
+
+    // Phase: P{phase}/{total}
     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}`;
+      parts.push(`${WHITE}P${phase}/${total}${RESET}`);
+    }
+
+    // Tasks within phase: T{done}/{total}
+    if (tasksTotal > 0) {
+      parts.push(`${DIM}T${RESET}${WHITE}${tasksDone}/${tasksTotal}${RESET}`);
+    }
+
+    // Status
+    if (status) {
+      parts.push(`${TEAL_GLOW}${status}${RESET}`);
+    }
+
+    // Blockers — red badge, only when > 0
+    if (blockers > 0) {
+      parts.push(`${RED}!${blockers}${RESET}`);
+    }
+
+    if (parts.length > 0) {
+      PHASE_INFO = parts.join(` ${DIM}·${RESET} `);
     }
   }
 } catch {}
@@ -186,36 +222,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 {
@@ -247,13 +269,13 @@ 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} `)}`;
+  // Memory — the one context indicator that's actually project-specific
+  if (MEMORY_COUNT > 0) {
+    LINE1 += ` ${DIM}│${RESET} ${DIM}mem${RESET} ${TEAL}${MEMORY_COUNT}${RESET}`;
+  }
+  // Qualia member signature — end of line 1 so it sits above line 2's model info
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/skills/qualia-new/SKILL.md

@@ -21,8 +21,9 @@ Initialize a project with the **entire arc mapped from kickoff to handoff**. All
 
 ## Flags
 
-- `/qualia-new` — full-journey flow, stops after approval (default, backward-compatible)
+- `/qualia-new` — full-journey flow, stops after approval (default, backward-compatible). **Progressive detail**: Milestone 1 gets full phase detail; M2..M{N-1} get sketched (names + one-line goals). Full detail for later milestones is filled in by `/qualia-milestone` when each one opens. This matches how real projects unfold — M1's discoveries reshape M3's plan, so deep-planning M3 now tends to waste effort.
 - `/qualia-new --auto` — full-journey flow, then auto-chains into `/qualia-plan 1 → /qualia-build → /qualia-verify` for Milestone 1
+- `/qualia-new --full-detail` — ALL milestones get full phase-level detail upfront (success criteria per phase for every milestone, not just M1). Use when the client wants a fully-committed plan at kickoff. Trade-off: later milestones often need revision as M1 ships. Combinable with `--auto`.
 - `/qualia-new --quick` — 4-phase flat wizard for trivial projects (landing pages, prototypes). Skips research and journey mapping.
 
 ## The Shift From Previous Versions
@@ -238,7 +239,7 @@ Gather any additional requirements the user wants that research missed.
 node ~/.claude/bin/qualia-ui.js banner roadmap
 ```
 
-Spawn the roadmapper with full-journey mandate:
+Spawn the roadmapper with full-journey mandate. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` in the prompt so the roadmapper writes complete phase detail for ALL milestones.
 
 ```
 Agent(prompt="
@@ -248,7 +249,7 @@ Read your role: @~/.claude/agents/roadmapper.md
 Create the FULL JOURNEY for this project:
   - .planning/JOURNEY.md — all milestones (2-5 including Handoff) with exit criteria
   - .planning/REQUIREMENTS.md — requirements grouped by milestone
-  - .planning/ROADMAP.md — Milestone 1's phase detail only (ready for /qualia-plan 1)
+  - .planning/ROADMAP.md — Milestone 1's phase detail (and ALL milestones if full_detail=true)
 
 User-scoped v1 features:
 {list of features selected in Step 9, grouped by category}
@@ -256,6 +257,10 @@ User-scoped v1 features:
 Template type: {template_type from config.json}
 If set, use ~/.claude/qualia-templates/projects/{type}.md as the milestone arc starting point.
 
+<full_detail>{true if --full-detail, else false}</full_detail>
+  - false (default): Milestone 1 gets full phase detail; M2..M{N-1} stay as sketches. Detail fills in when each milestone opens via /qualia-milestone.
+  - true: every milestone (M1..Handoff) gets full phase-level detail in ROADMAP.md upfront. Useful when the client wants a fully-committed plan at kickoff.
+
 The final milestone MUST be named 'Handoff' with the fixed 4 phases
 (Polish, Content + SEO, Final QA, Handoff). Do not omit it.
 
@@ -331,6 +336,16 @@ git add .planning/JOURNEY.md .planning/REQUIREMENTS.md .planning/ROADMAP.md .pla
 git commit -m "docs: journey + requirements + milestone 1 roadmap ({N} milestones)"
 ```
 
+**After approval, show the progressive-detail reminder explicitly:**
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Milestone 1 is fully planned now."
+node ~/.claude/bin/qualia-ui.js info "Milestones 2..{N-1} are sketched (names + one-line goals)."
+node ~/.claude/bin/qualia-ui.js info "Full phase detail for each later milestone gets written when /qualia-milestone opens it."
+```
+
+(Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
+
 ### Step 13. Environment Setup
 
 Supabase project? `supabase link` or create. Vercel project? `vercel link`. Env vars? `.env.local` with placeholders from PROJECT.md stack.

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/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 });
+    }
+  });
 });
 
 // ═══════════════════════════════════════════════════════════