qualia-framework 4.4.0 → 5.1.0

package/bin/state.js

@@ -735,6 +735,22 @@ function cmdTransition(opts) {
 function cmdInit(opts) {
   if (!opts.project) return output(fail("MISSING_ARG", "--project required"));
 
+  // v5.0: Throwaway-name guard. The insights report documents the user
+  // accidentally creating a project literally named "test-name-only" instead
+  // of the real client name. Names matching common scratch/test patterns get
+  // a 1-line confirmation step (bypass with --force).
+  if (!opts.force) {
+    const SUSPICIOUS = /^(test|tmp|temp|foo|bar|baz|scratch|demo|sample|untitled|new[\W_-]?project|example)(\b|[\W_-])/i;
+    if (SUSPICIOUS.test(opts.project)) {
+      return output(
+        fail(
+          "SUSPICIOUS_NAME",
+          `Project name '${opts.project}' looks temporary/test-like. If this is the real client project name, re-run with --force. Otherwise re-run with the actual project name.`
+        )
+      );
+    }
+  }
+
   // Refuse to clobber an active project unless --force.
   // Lifetime preservation runs lower in this fn — but current-phase fields
   // (phase, status, wave, tasks_done, tasks_total, gap_cycles) ARE wiped
@@ -1173,7 +1189,24 @@ function cmdCloseMilestone(opts) {
   t.milestone_name = readNextMilestoneNameFromJourney(t.milestone);
   t.last_updated = new Date().toISOString();
 
-  writeTracking(t);
+  // v5.0 — journal-protected write. STATE.md is intentionally NOT mutated here
+  // (the next /qualia-milestone step calls `state.js init --force` which fully
+  // rewrites STATE.md for the new milestone). The journal still snapshots
+  // tracking.json so a crash mid-write can be detected and recovered by the
+  // next session via recoverFromJournal().
+  const backupTracking = (() => {
+    try { return fs.readFileSync(TRACKING_FILE, "utf8"); } catch { return null; }
+  })();
+  try {
+    writeJournal(null, backupTracking);
+    writeTracking(t);
+    clearJournal();
+  } catch (e) {
+    // Restore tracking.json from backup if write failed mid-way.
+    try { if (backupTracking) atomicWrite(TRACKING_FILE, backupTracking); } catch {}
+    clearJournal();
+    return output(fail("WRITE_ERROR", `close-milestone write failed: ${e.message}. tracking.json restored from backup.`));
+  }
 
   _trace("close-milestone", "allow", {
     closed_milestone: closedMilestone,
@@ -1267,6 +1300,186 @@ function cmdBackfillLifetime(opts) {
   });
 }
 
+// ─── Backfill Milestones from JOURNEY.md ─────────────────
+// Reconstructs the milestones[] array + lifetime counters from the
+// "Milestone arc" table in .planning/JOURNEY.md. Required when a project
+// pre-dates v4 milestone bookkeeping (or had its tracking.json reset)
+// but JOURNEY.md captures the historical arc. Idempotent — only adds
+// missing milestones or overwrites entries flagged backfilled:true.
+//
+// JOURNEY.md table format expected:
+//   | # | Milestone | Status | Phases | Closed |
+//   | 1 | Name      | CLOSED | 1–13   | YYYY-MM-DD |
+//   | 5 | Name      | OPEN   | rolling| —      |
+//
+// Phase counting handles ranges (`1–13` → 13), comma lists (`14, 15, 16.1–16.6` → 8),
+// and "rolling" / "—" / "-" → 0.
+function cmdBackfillMilestones(opts) {
+  const t = readTracking();
+  if (!t) return output(fail("NO_PROJECT", "No .planning/ found."));
+  ensureLifetime(t);
+
+  const journeyPath = path.join(PLANNING, "JOURNEY.md");
+  if (!fs.existsSync(journeyPath)) {
+    return output(fail("NO_JOURNEY", "JOURNEY.md not found. Cannot backfill without milestone history source."));
+  }
+
+  const content = fs.readFileSync(journeyPath, "utf8");
+
+  // Parse the milestone arc table. Each row must have 5 columns:
+  // num | name | status | phases | closed
+  const rows = [];
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(
+      /^\|\s*(\d+)\s*\|\s*([^|]+?)\s*\|\s*(CLOSED|OPEN|CURRENT)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|/i
+    );
+    if (m) {
+      rows.push({
+        num: parseInt(m[1], 10),
+        name: m[2].trim(),
+        status: m[3].trim().toUpperCase(),
+        phasesStr: m[4].trim(),
+        closedStr: m[5].trim(),
+      });
+    }
+  }
+
+  if (rows.length === 0) {
+    return output(
+      fail(
+        "NO_MILESTONE_TABLE",
+        "No milestone arc table found in JOURNEY.md. Expected `| # | Milestone | Status | Phases | Closed |` header followed by rows."
+      )
+    );
+  }
+
+  // Count phases from a phasesStr.
+  // "1–13" → 13. "14, 15, 16.1–16.6" → 8. "19–25" → 7. "rolling" / "—" / "-" → 0.
+  const countPhases = (s) => {
+    if (!s) return 0;
+    const lower = s.toLowerCase();
+    if (lower === "—" || lower === "-" || lower === "rolling" || lower === "n/a") return 0;
+    let count = 0;
+    for (const seg of s.split(",")) {
+      const trimmed = seg.trim();
+      if (!trimmed || trimmed === "—" || trimmed === "-") continue;
+      // Match X–Y or X-Y where X/Y can be "13" or "16.6"
+      const range = trimmed.match(/^(\d+(?:\.\d+)?)\s*[–-]\s*(\d+(?:\.\d+)?)$/);
+      if (range) {
+        const startStr = range[1];
+        const endStr = range[2];
+        // Sub-phase range like "16.1–16.6" → count by sub-index difference + 1
+        if (startStr.includes(".") && endStr.includes(".")) {
+          const startSub = parseInt(startStr.split(".")[1], 10);
+          const endSub = parseInt(endStr.split(".")[1], 10);
+          count += Math.max(0, endSub - startSub + 1);
+        } else {
+          const start = parseInt(startStr, 10);
+          const end = parseInt(endStr, 10);
+          count += Math.max(0, end - start + 1);
+        }
+      } else {
+        // Single phase like "14" or "17.1"
+        count += 1;
+      }
+    }
+    return count;
+  };
+
+  const closed = rows.filter((r) => r.status === "CLOSED").sort((a, b) => a.num - b.num);
+  const openRow = rows.find((r) => r.status === "OPEN" || r.status === "CURRENT");
+
+  t.milestones = Array.isArray(t.milestones) ? t.milestones : [];
+  let added = 0;
+  let updated = 0;
+  let totalClosedPhases = 0;
+  const closedSummaries = [];
+
+  for (const row of closed) {
+    const phaseCount = countPhases(row.phasesStr);
+    totalClosedPhases += phaseCount;
+
+    const dateMatch = row.closedStr.match(/\d{4}-\d{2}-\d{2}/);
+    const closedAt = dateMatch ? `${dateMatch[0]}T00:00:00.000Z` : "";
+
+    const summary = {
+      num: row.num,
+      name: row.name,
+      total_phases: phaseCount,
+      phases_completed: phaseCount,
+      tasks_completed: 0, // unknown for historical backfill
+      shipped_url: "",
+      closed_at: closedAt,
+      backfilled: true,
+    };
+    closedSummaries.push({ num: row.num, name: row.name, phases: phaseCount });
+
+    const existing = t.milestones.findIndex((mm) => mm && mm.num === row.num);
+    if (existing >= 0) {
+      // Don't override entries that came from real /qualia-milestone close
+      // (they have richer data). Only overwrite previously-backfilled entries.
+      if (t.milestones[existing].backfilled) {
+        t.milestones[existing] = summary;
+        updated++;
+      }
+    } else {
+      t.milestones.push(summary);
+      added++;
+    }
+  }
+
+  // Stable order by milestone number.
+  t.milestones.sort((a, b) => (a.num || 0) - (b.num || 0));
+
+  const lastClosed = closed.length > 0 ? closed[closed.length - 1].num : 0;
+
+  // Math.max — never reduce lifetime counters. Preserves real /qualia-milestone
+  // history if a project was partly closed properly and partly backfilled.
+  t.lifetime.milestones_completed = Math.max(
+    t.lifetime.milestones_completed || 0,
+    closed.length
+  );
+  t.lifetime.last_closed_milestone = Math.max(
+    t.lifetime.last_closed_milestone || 0,
+    lastClosed
+  );
+  t.lifetime.total_phases = Math.max(
+    t.lifetime.total_phases || 0,
+    totalClosedPhases
+  );
+
+  // Set current milestone — prefer the OPEN row; otherwise next-after-last-closed.
+  if (openRow) {
+    t.milestone = openRow.num;
+    t.milestone_name = openRow.name;
+  } else if (lastClosed > 0) {
+    t.milestone = lastClosed + 1;
+    t.milestone_name = readNextMilestoneNameFromJourney(t.milestone);
+  }
+
+  t.last_updated = new Date().toISOString();
+  writeTracking(t);
+
+  _trace("backfill-milestones", "allow", {
+    added,
+    updated,
+    closed_count: closed.length,
+    total_phases: totalClosedPhases,
+    lifetime: t.lifetime,
+  });
+
+  output({
+    ok: true,
+    action: "backfill-milestones",
+    added,
+    updated,
+    closed: closedSummaries,
+    open_milestone: openRow ? { num: openRow.num, name: openRow.name } : null,
+    lifetime: t.lifetime,
+  });
+}
+
 // ─── 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
@@ -1342,6 +1555,9 @@ try {
     case "backfill-lifetime":
       cmdBackfillLifetime(opts);
       break;
+    case "backfill-milestones":
+      cmdBackfillMilestones(opts);
+      break;
     case "next-report-id":
       cmdNextReportId(opts);
       break;
@@ -1349,7 +1565,7 @@ try {
       output(
         fail(
           "UNKNOWN_COMMAND",
-          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|next-report-id> [--options]`
+          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|backfill-milestones|next-report-id> [--options]`
         )
       );
   }

package/docs/erp-contract.md

@@ -200,6 +200,11 @@ Authorization: Bearer <api-key>
   external callers. Internal idempotent UPSERT on `(project_id,
   client_report_id)` retries is the one exception (see "Idempotent UPSERT
   on retry" above).
+- The ERP resolves each report to a canonical internal project when possible.
+  Repository URL is the strongest signal, followed by repo/project slug, then
+  configured aliases, then the human report project name. This keeps legacy
+  repo/report names like `USD-Academy` or `USD-ACVADEMY` correctly linked to
+  ERP project names like `Underdog-Sales-Academy`.
 - **`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)

package/docs/install-redesign-builder-prompt.md

@@ -0,0 +1,290 @@
+# Qualia Framework — Install Redesign (v5.1.0 candidate)
+## Builder Agent Prompt
+
+**Hand this entire file to a fresh Claude Code session.** Self-contained — no context from the originating session is needed. Same pattern as `docs/playwright-loop-builder-prompt.md` which produced v5.0's polish-loop work.
+
+---
+
+## What you are building
+
+A redesigned installer for the Qualia Framework that:
+
+1. **Asks the user where to install** — Claude Code (`~/.claude/`), OpenAI Codex (`~/.codex/`), or both — and adapts the install per target
+2. **Shows real-time visual progress** during the install — what file is being read, what's being copied, what's being configured — not silent then suddenly done
+3. **Has top-notch cosmetics** throughout — every line of output is intentional and beautiful
+
+The current installer (`bin/install.js`, ~830 lines) is functional but minimal. It copies files in batches and prints section headers ("Skills", "Templates", "Hooks") with terse `✓ {name}` lines. Fawzi wants the install to FEEL like a polished product — like the framework is announcing itself with care, not just dumping files.
+
+## Why this matters
+
+- **First impression is the install.** Every Qualia user (Fawzi, Hasan, Moayad, Rama, Sally, future hires) experiences the framework first through `npx qualia-framework install`. A boring install signals a boring framework.
+- **Cross-tool reach.** v5.0.0 already produces `AGENTS.md` (the cross-vendor open standard adopted by Codex, Cursor, Aider, Continue). Codex users could already use the framework today — they just don't know it because the installer only writes to `~/.claude/`. Multi-target makes that explicit.
+- **Visual feedback is trust.** When the installer is silent for 5 seconds while it copies 32 skills + 12 hooks + 24 templates, the user wonders if it hung. Live progress makes the framework feel alive.
+
+## The repository you're working in
+
+`/home/qualia-new/qualia-framework` — the Qualia Framework npm package, currently at v5.0.0 on branch `feat/env-empty-guard` (locally, not yet pushed). 274 tests pass. v5.0.0 release is queued for tomorrow morning publish to npm.
+
+**Your work goes ON TOP of v5.0.0, as v5.1.0.** You'll bump version, add CHANGELOG entry, modify `bin/install.js`, possibly add `bin/install-cosmetics.js` helper, update tests.
+
+## Files to study before writing code
+
+1. `/home/qualia-new/qualia-framework/bin/install.js` — the current installer (~830 lines). Read it fully to understand the install phases (cleanup → CLAUDE.md/AGENTS.md → skills → agents → rules → hooks → settings.json → MCP → templates → knowledge layer → bin scripts → ERP config → final banner).
+2. `/home/qualia-new/qualia-framework/bin/qualia-ui.js` — the existing cosmetics helper (banners, dividers, end-cards, status). Reuse and extend; don't duplicate.
+3. `/home/qualia-new/qualia-framework/CLAUDE.md` and `AGENTS.md` — to understand what gets templated with `{{ROLE}}` for each install target
+4. `/home/qualia-new/qualia-framework/CHANGELOG.md` v5.0.0 entry — to match the writing style for v5.1.0
+5. `/home/qualia-new/qualia-framework/tests/bin.test.sh` — the install test patterns (lines ~440 onward have the install assertions you'll mirror)
+
+## The 3 deliverables
+
+### Deliverable 1 — Multi-target install (Claude Code / Codex / Both)
+
+**Behavior:**
+
+After the user enters their team code (existing flow), the installer asks:
+
+```
+  Where would you like to install Qualia?
+
+  [1] Claude Code only       (recommended — full feature set)
+  [2] OpenAI Codex only      (AGENTS.md + project-level rules)
+  [3] Both                   (max compatibility)
+
+  Choice [1]:
+```
+
+Default is `1` (Claude Code only) for backward-compat. The user types `1`/`2`/`3` and Enter.
+
+**Per-target install paths:**
+
+| Target | Directory | What gets installed |
+|---|---|---|
+| Claude Code | `~/.claude/` | Everything as today (skills/, agents/, hooks/, rules/, qualia-templates/, knowledge/, settings.json, CLAUDE.md, AGENTS.md, bin/, .qualia-config.json) |
+| Codex | `~/.codex/` (or wherever Codex config lives — research this) | A subset that Codex actually uses: `AGENTS.md` (the framework conventions), `instructions.md` if Codex uses one, possibly mirrored skills/ and templates/ if Codex's runtime supports skills (research this — it might not; in that case skip those) |
+| Both | both directories | Run the Claude Code install first, then the Codex install |
+
+**Critical research step you MUST do FIRST:**
+
+Use `WebFetch` or `Bash` to research Codex CLI's actual configuration layout:
+
+```bash
+# Check if user has codex installed
+which codex 2>/dev/null
+codex --version 2>/dev/null
+
+# Look for documented config paths
+ls ~/.codex/ 2>/dev/null
+ls ~/.config/codex/ 2>/dev/null
+```
+
+Search for: "OpenAI Codex CLI configuration directory", "Codex AGENTS.md", "Codex skills system" (if any).
+
+If Codex CLI is too thin to support a meaningful framework install (e.g., it only reads AGENTS.md and that's it), say so explicitly in your output — don't pretend to install more than makes sense. Write a clear note in the CHANGELOG entry: "Codex install writes AGENTS.md only — Codex's runtime does not currently support skills/hooks/agents on disk."
+
+**If Codex is not installed locally:**
+
+Don't crash. Show a soft warning:
+
+```
+⚠ Codex CLI not detected on this system.
+  Installing AGENTS.md to ~/.codex/AGENTS.md anyway — Codex will pick it up
+  when you install via `npm install -g @openai/codex`.
+```
+
+Then proceed with the Codex-side install (just the file writes).
+
+### Deliverable 2 — Real-time visual progress
+
+**Current installer:** prints section headers, then a batch of `✓ {name}` lines all at once when each section completes. Looks like nothing → nothing → blast of green checkmarks.
+
+**Redesigned installer:** every meaningful operation prints a "doing" line before, then updates to "done" after. Like a live activity log.
+
+**Pattern (use Unicode box-drawing for the progression):**
+
+```
+  ▸ Skills (32)
+  ─────────────────────────────────────────
+    ⏳ Reading skills/ from framework...
+    ✓ Reading skills/ from framework
+    ⏳ Copying qualia-build...
+    ✓ qualia-build (3 files)
+    ⏳ Copying qualia-discuss...
+    ✓ qualia-discuss (1 file)
+    ⏳ Copying qualia-issues...
+    ✓ qualia-issues (1 file)
+    ...
+    ✓ Skills installed (32 total)
+```
+
+Use ANSI escape sequences to OVERWRITE the `⏳` line with the `✓` line in place (cursor-up + clear-line) — so the output reads as a steadily-completing list, not a doubled set of lines.
+
+**For long ops (template recursive copy, knowledge layer init, settings.json merge):**
+
+Show a spinner that ticks every 100ms:
+
+```
+    ⠋ Merging settings.json (preserving 14 user keys)
+```
+
+Implement as a tiny helper `startSpinner(text)` returning `stop({ status: "ok" | "warn" | "error", message?: string })`. Don't pull in `ora` or any external dep — write ~30 lines of vanilla Node using `process.stdout.write` + an interval.
+
+**For each skill/agent/hook/rule/template copied:**
+
+The current `ok({name})` print becomes a 2-line lifecycle:
+
+1. Before copy: `⏳ {name}` (dim, with a working glyph)
+2. After copy: `✓ {name}` (green, replacing the line above)
+
+For very fast ops (single file, < 50ms) you can skip the "doing" state and go straight to ✓.
+
+**Enhancements to existing `bin/qualia-ui.js`:**
+
+Add these new helpers and export them:
+
+- `spinner(text)` → `{ stop(result) }` — animated spinner with cursor-hide/show
+- `step(text)` → returns a step-handle with `.ok(suffix?)`, `.warn(msg)`, `.fail(msg)` that overwrite the line
+- `progress(current, total, label)` — render a bar like `[████████░░] 8/10 — Skills`
+- `divider(width)` — variable-width dim divider
+- `box({title, lines, color})` — boxed section like the welcome banner
+- `kv(label, value, options?)` — left-padded label, right-aligned value, dim/highlight options
+
+Preserve all existing `qualia-ui.js` exports — additive only.
+
+### Deliverable 3 — Top-notch cosmetics throughout
+
+The full install output, end-to-end, should feel like a single intentional document. Specific things to fix:
+
+**The current install banner** (the welcome card at the top with `⬢ Q U A L I A`) is good. Keep its bones, but consider:
+- Subtle 2-color gradient on the title (teal → cyan) using truecolor escape
+- A breath of vertical space (one blank line above and below)
+- Version + framework subtitle aligned right of the hex glyph
+
+**Section separators** between phases (Skills, Agents, Rules, Hooks, Templates, etc.):
+- Currently: bold teal triangle + section name + dim divider
+- Upgrade: add a 2-letter status indicator at the right margin showing pass count, like `▸ Skills                    32 ✓`
+- After each section completes, show a one-line "section summary" with the count and elapsed time: `  └─ 32 skills · 0.3s`
+
+**Final summary card** (the "INSTALLED" banner at the end):
+- Currently: name + role + version + 7 metric kv lines + Quick Start
+- Upgrade: add a "Targets" row showing where you installed (`Claude Code · Codex · Both`)
+- Add a "Time" row showing total install duration
+- Add a contextual "First command to try" line based on whether the user has a `.planning/` already (suggest `/qualia` if they do, `/qualia-new` if not)
+
+**Color palette discipline:**
+- Match the existing OKLCH-tinted neutrals in `bin/qualia-ui.js`
+- Don't introduce new colors — extend the existing teal/green/dim/white system
+- Errors stay red (#ef4444), warns stay yellow (#eab308) — don't change these (muscle memory)
+
+**Glyph rules:**
+- ⬢ = brand mark, only for the welcome banner and final card
+- ▸ = section header
+- ✓ = success
+- ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏ = spinner frames (Braille pattern dots)
+- ⏳ = pending/in-flight
+- ⚠ = warning
+- ✗ = error
+- └─ = section close
+- · = inline separator
+
+Don't introduce other glyphs without strong reason.
+
+## Hard constraints (non-negotiable)
+
+1. **Backward compatibility.** A user typing only their team code with no target choice (legacy stdin pipe `echo "QS-FAWZI-01" | npx qualia-framework install`) MUST still work — default to Claude Code only. Don't break the existing `bin.test.sh` install assertions.
+
+2. **No new external dependencies.** No `ora`, no `chalk`, no `ink`. Vanilla Node + ANSI escapes. The current installer is dependency-free; preserve that.
+
+3. **Cross-platform (Windows + macOS + Linux).** ANSI escapes work on modern Windows 10+ but verify the spinner doesn't break on `cmd.exe`. If `process.stdout.isTTY` is false (piped install), degrade gracefully — print plain `→ {name}` and `✓ {name}` lines instead of overwriting.
+
+4. **Atomic writes for new target paths.** When installing to `~/.codex/`, follow the same atomic-write (tmp + rename) pattern that v5.0 added for `settings.json` and CLAUDE.md.
+
+5. **Backups before overwrite** — same as v5.0's CLAUDE.md/settings.json discipline. If `~/.codex/AGENTS.md` exists with a different content hash than what we'd write, back it up to `~/.codex/AGENTS.md.bak.{ISO-timestamp}` before overwriting.
+
+6. **No surprise side effects.** Installing to Codex doesn't auto-install Codex CLI itself. If it's not present, write the files and tell the user to install Codex separately.
+
+7. **Slop-detect clean.** Run `node bin/slop-detect.mjs` on every modified `.md` file. The CHANGELOG and any new docs you write must pass.
+
+8. **Tests pass.** All 274 existing tests must continue to pass. Add new tests for: target selection (1/2/3 input), Codex install path creation, AGENTS.md backup-before-overwrite, spinner degradation when non-TTY, multi-target ("Both") flow.
+
+## Deliverables (the DONE definition)
+
+Return DONE only when all of these are true:
+
+1. ✅ `bin/install.js` modified to ask the install-target question after the team code prompt
+2. ✅ Codex-target install actually writes to `~/.codex/` (or whatever the research found is correct)
+3. ✅ All file copies have a "before/after" 2-line lifecycle (or single-line for sub-50ms ops)
+4. ✅ `bin/qualia-ui.js` extended with `spinner()`, `step()`, `progress()`, `box()`, `kv()` helpers
+5. ✅ Final summary card shows install targets, total time, and contextual first-command suggestion
+6. ✅ TTY-degraded mode works (test: `echo QS-FAWZI-01 | node bin/install.js > /tmp/log.txt`; the log should be readable, no orphaned escape codes)
+7. ✅ Backups for existing AGENTS.md / instructions.md in Codex target dir
+8. ✅ All 274 v5.0 tests still pass + at least 5 new tests for v5.1 multi-target
+9. ✅ `node bin/slop-detect.mjs` clean on all modified .md files
+10. ✅ `package.json` bumped to 5.1.0
+11. ✅ CHANGELOG.md has a v5.1.0 entry with the same writing style as the v5.0.0 entry, including:
+    - The "why this matters" framing (first impression, cross-tool reach, visual trust)
+    - The 3 deliverables
+    - The Codex install scope (whatever the research determined)
+    - Honest caveats (what doesn't work, what's deferred)
+12. ✅ `docs/install-redesign-pilot.md` documenting:
+    - The full install output captured for each target choice (1, 2, 3)
+    - Screenshots or terminal-recording converted to ANSI text
+    - Timing measurements
+    - Any TTY-degradation issues found
+
+## Self-test scenarios (run all 3 before declaring DONE)
+
+**Scenario 1 — Claude Code only.**
+```bash
+TMP=$(mktemp -d)
+echo -e "QS-FAWZI-01\n1\n" | HOME="$TMP" node bin/install.js > "$TMP/log.txt" 2>&1
+```
+- Verify: `~/.claude/` populated as today. `~/.codex/` does not exist or is empty.
+- Verify: `$TMP/log.txt` shows the new visual progress (every section has live updates).
+- Verify: total install time is ≤ 2× the current install time (live updates shouldn't more than double cost).
+
+**Scenario 2 — Codex only.**
+```bash
+TMP=$(mktemp -d)
+echo -e "QS-FAWZI-01\n2\n" | HOME="$TMP" node bin/install.js > "$TMP/log.txt" 2>&1
+```
+- Verify: `~/.codex/AGENTS.md` exists with `Role: OWNER` substituted.
+- Verify: `~/.claude/` is NOT populated (we picked target 2 only).
+- Verify: log shows "Codex CLI not detected — file written anyway" if `which codex` fails.
+
+**Scenario 3 — Both.**
+```bash
+TMP=$(mktemp -d)
+echo -e "QS-FAWZI-01\n3\n" | HOME="$TMP" node bin/install.js > "$TMP/log.txt" 2>&1
+```
+- Verify: both `~/.claude/` and `~/.codex/` populated correctly.
+- Verify: final summary card shows "Targets: Claude Code · Codex".
+
+## Things you MUST NOT do
+
+- Don't change the team-code prompt itself (existing format works, has tests, don't break them).
+- Don't add interactive yes/no prompts beyond the target-selection question — the install should still complete via stdin pipe with no extra input needed.
+- Don't change `~/.claude/` install behavior beyond cosmetics. The semantic install logic (which files go where) stays exactly as v5.0.
+- Don't wire Codex to any external API or auto-install. File copies only.
+- Don't bump major version (still 5.x). This is a minor (5.1.0).
+- Don't break the ERP API key save/load flow — `~/.claude/.erp-api-key` stays where it is.
+- Don't drop the EXPERIMENTAL Playwright caveat in the v5.0.0 CHANGELOG — preserve it as historical context.
+
+## Reference: where v5.0's similar work happened
+
+Look at how the polish-loop builder agent (commit `907312c`) handled a similar scope — building a flagship feature with self-tests, CHANGELOG, install assertions. Match its discipline:
+- Per-iteration commits during pilot scenarios (`qpl-N:` prefix style — yours could be `install-redesign-N:`)
+- Honest caveats in CHANGELOG (don't oversell)
+- Pilot results doc with concrete measurements
+- Trust-boundary comment in any new agent role file (none expected here, but if you create one, copy the pattern from `agents/builder.md` lines 11-17)
+
+## When you encounter unknowns
+
+- **Codex config layout** — the most likely unknown. If web search + local probing don't give a clear answer, write the simplest version (just `~/.codex/AGENTS.md`) and document it explicitly: "Codex install scope: AGENTS.md only. If Codex's runtime later supports skills/hooks on disk, the framework can extend this."
+- **TTY degradation edge cases** — if cmd.exe on Windows has issues, document and gate the spinner behind `process.platform !== "win32"` for the spinner specifically. The 2-line copy/✓ pattern should work everywhere.
+- **Existing install test breakage** — if you can't avoid breaking a test, the test was overspecified. Update the test, but document WHY in the commit message.
+
+## One last thing
+
+Fawzi (the framework owner, OWNER role) will read your output as the FIRST install he runs. He's tired tonight and trusting you to deliver. Honest reporting beats good-news theater. If something doesn't work cleanly, mark it experimental and say so — same discipline as the polish-loop EXPERIMENTAL Playwright caveat.
+
+When you finish, write your DONE report at `docs/install-redesign-pilot.md` (file already mentioned above) and return a tight summary: targets working, lines of code added/changed, test count, slop-detect status, any BLOCKED items.