qualia-framework 5.4.0 → 5.5.0

package/docs/archive/session-report-2026-04-18.md

@@ -1,199 +0,0 @@
-# Session Report — 2026-04-18
-
-**Project:** qualia-framework
-**Branch:** feature/full-journey (local, not pushed)
-**Released:** v3.7.0 (staged on feature/story-file-plans) and **v4.0.0** (staged on feature/full-journey)
-**Owner:** Fawzi Goussous
-**Duration:** ~4 hours
-
-## What this session shipped
-
-Two releases staged on separate feature branches, ready for push + merge + `npm publish`.
-
-| Tag | Branch | Commits | Theme |
-|---|---|---|---|
-| **v3.7.0** | feature/story-file-plans | 1 commit (8ae5b0e) | Story-file plan format — every phase plan task carries inline Why, Acceptance Criteria, Validation, explicit Depends on |
-| **v4.0.0** | feature/full-journey | 8 commits total (includes v3.7.0) | Full Journey release — /qualia-new maps the entire arc to handoff, --auto chains the Road end-to-end, milestone hierarchy locked, /qualia-idk rebuilt as diagnostician |
-
-**Test suite:** 150 → 156 green (+6 v4 coverage, 0 regressions).
-**Package:** version bumped 3.6.0 → 4.0.0.
-**Release candidate:** v4.0.0 commit is `f790554` on feature/full-journey.
-
-## Background & trigger
-
-Fawzi came in with three pain points from Sakani's ERP view:
-1. "Unphased Tasks" and "Phase 0: Central Bank Demo" rendering at the same tree level as "Milestone 1", "Milestone 2", etc. — milestones collapsed into single phases, numbering skipped (missing M5).
-2. `/qualia-new` stops at v1 — team improvises subsequent milestones, no clear path to handoff.
-3. Team members don't understand the framework's dev cycle. Need something a non-technical person can follow without getting lost.
-
-Plus: "make it sexier," personalize the Qualia experience, enhance every command for best practices, ship a stable v4.0.
-
-## The approach
-
-Split the work into labeled phases on a feature branch so commits tell the story:
-
-### v3.7.0 prerequisite — story-file plans
-- `templates/plan.md` rewritten to 7-field story-file format (Wave, Files, Depends on, Why, Acceptance Criteria, Action, Validation, Context + optional Persona)
-- `agents/planner.md` generates the new format
-- `agents/plan-checker.md` validates the 7 fields and cross-checks wave↔deps consistency
-- `agents/builder.md` reads rationale, respects Depends on, runs Validation before commit
-- `agents/verifier.md` adds 3-layer check (phase Success Criteria + per-task AC + Verification Contract)
-- `bin/qualia-ui.js` adds `plan-summary` command — terminal dashboard with colored persona chips, dependency arrows, AC/check counts per task
-- `bin/state.js` accepts both legacy `Done when:` and new `Acceptance Criteria:` anchors (backward-compatible)
-
-Committed on `feature/story-file-plans` as v3.7.0 (`8ae5b0e`). Standalone useful release; branched v4 off of it.
-
-### v4.0.0 — Full Journey, phased
-
-**Phase A — Model foundation** (`2e371c2`)
-- `templates/journey.md` — new JOURNEY.md schema (hard ceiling 5 milestones, hard floor 2, final milestone always Handoff with 4 fixed phases)
-- `tracking.json` gains `milestone_name`, `milestones[]` (array of closed milestone summaries)
-- `state.js close-milestone` readiness guards: MILESTONE_NOT_READY, MILESTONE_TOO_SMALL (both bypassable with --force)
-- `state.js init` accepts `--milestone_name` and preserves milestones[] across re-init
-- Tests: +4
-
-**Phase B — Roadmapper + /qualia-new full-journey output** (`87af253`)
-- `agents/roadmapper.md` rewritten: now produces JOURNEY.md (all milestones) + REQUIREMENTS.md (grouped by milestone) + ROADMAP.md (Milestone 1's phase detail only)
-- **Dropped** the old "no review/deploy/handoff phases" rule. **Replaced** with: final milestone is always literally named "Handoff" with fixed 4 phases.
-- `skills/qualia-new/SKILL.md` rewritten: always runs research (no more `workflow.research` gate), single approval on the whole journey, new `--auto` flag
-- `agents/research-synthesizer.md` thinks across all milestones
-- `skills/qualia-milestone/SKILL.md` reads next milestone from JOURNEY.md (no longer asks user)
-- `templates/requirements.md` multi-milestone format with standard Handoff section (HAND-01..HAND-15)
-- `templates/roadmap.md` scoped to current milestone only
-
-**Phase C — Auto-chain wiring** (`400cd17`)
-- `--auto` flag added to `/qualia-plan`, `/qualia-build`, `/qualia-verify`, `/qualia-milestone`
-- Auto-chain decision table in `/qualia-verify`: PASS → next phase OR milestone close OR ship+handoff; FAIL → gap closure OR halt at limit
-- Two human gates total per project: journey approval + each milestone boundary
-
-**Phase D+E — Builder pre-inline + journey visualization** (`74dd26e`)
-- Builder pre-inlines PROJECT.md + DESIGN.md + Context files into agent prompt BEFORE spawning (GSD-pattern borrowing, saves 3-5 Read calls per task)
-- `qualia-ui.js journey-tree` renders JOURNEY.md as ASCII ladder (green shipped, teal current, dim future, [FINAL] tag for Handoff)
-- `qualia-ui.js milestone-complete` celebration banner
-- 5 new banner actions: milestone ◆, journey ◯, auto ⚡, research ◱, roadmap ◐
-- `/qualia` router renders journey-tree for "you are here" orientation
-- `/qualia-milestone` renders journey-tree + milestone-complete
-
-**Phase F — Ship-side fields + handoff deliverables** (`b41a52d`)
-- `state.js` bumps `build_count` on each 'built' transition, `deploy_count` on each 'shipped' (previously never incremented)
-- `qualia-report` ERP payload now includes all v4 fields (project_id, team_id, git_remote, milestone_name, milestones[], build_count, deploy_count, session_started_at, last_pushed_at)
-- `/qualia-handoff` rewritten: explicit 4 mandatory deliverables — production URL verified (HTTP + latency + auth), docs updated, `.planning/archive/` check, final ERP report
-
-**Phase G — Smoke test fix + coverage** (`f62e753`)
-- Bug fix: close-milestone summary was recording current phase's tasks, not cumulative milestone total. Fixed via `lifetime.tasks_completed − sum(prior milestones[].tasks_completed)`
-- Tests: +2 (cumulative task count, build_count bump)
-
-**Release (`f790554`)**
-- Single unified v4.0.0 release commit
-- Package bumped 3.7.0 → 4.0.0
-- CHANGELOG.md v4.0.0 entry with full feature list + migration notes
-- `/qualia-idk` rebuilt as real diagnostician (was briefly v4.0.1 in the branch history, folded into v4.0.0 per owner request)
-
-### The `/qualia-idk` rebuild (folded into v4.0.0)
-
-Before: thin one-line alias to `/qualia`.
-
-Now: interpretive diagnostic. When user says "I don't know what's going on" / "something feels off":
-1. Spawns **Plan view** Explore subagent — reads only `.planning/*`, reports what plan says
-2. Spawns **Code view** Explore subagent in parallel — reads only source code, reports what's actually built, cites file:line
-3. Synthesizes: structured "What I see / The mismatch / What I think is happening / What to do next" in plain language
-4. Maps recommendations to existing commands where applicable
-
-`/qualia` description scoped back to mechanical state routing — no longer claims "idk/stuck/lost/confused" triggers (those route to `/qualia-idk` now).
-
-## Competitive research completed
-
-During the session, ran deep research on competing Claude Code frameworks:
-- **Superpowers** (Jesse Vincent) — 93K stars — rigid 5-phase gates, Visual Companion, cross-agent portability
-- **BMAD-METHOD** — 43K stars — 12-19 named role agents, story files, expansion packs
-- **gstack** (Garry Tan) — 74K stars — 23-role team, persistent browser daemon, /codex cross-model review
-- **GSD** (Get Shit Done, v1+v2) — 54K + 6K stars — state-machine auto-advance, pre-inlined dispatch, adaptive replanning
-- **SuperClaude, Agent OS, Context Engineering/PRP, Claude-Flow, Cursor 2.0, Windsurf** — broader landscape
-
-Patterns borrowed in v4.0.0:
-- **Story-file plan format** (BMAD) — inline rationale + acceptance criteria
-- **State-machine auto-advance** (GSD v2) — the --auto chain
-- **Pre-inline context at dispatch** (GSD v2) — builder's <pre-loaded-context> block
-- **Journey-as-first-class-artifact** (NotebookLM synthesis of Qualia's own docs)
-
-Patterns deferred to v4.1+:
-- Visual/mockup generation (gstack design-shotgun, Superpowers Visual Companion)
-- Cross-model review (gstack /codex)
-- Cross-project vector memory (claude-mem, Claude-Flow)
-- IDE integration
-- Token-budget compression
-
-## Verification at checkpoint
-
-```
-✅ Git            8 commits clean on feature/full-journey
-✅ Tests          156/156 pass
-✅ Smoke          state transitions + close-milestone + milestones[] summary verified on scratch project
-✅ UI             journey-tree + milestone-complete render correctly with real fixtures
-✅ Backward compat  older tracking.json without milestones[]/milestone_name still passes state.js check
-✅ No regressions Vs v3.6 baseline — all 150 existing tests still pass
-✅ Package        version 4.0.0, ready for `npm publish`
-✅ Handoff        V4_REVIEW.md written for next agent
-```
-
-## Pending (not done by this session)
-
-- **Git push** — both branches are local only
-- **Merge to main** — owner decides merge strategy (recommend v3.7.0 tag then v4.0.0 tag)
-- **`npm publish`** — requires owner auth
-- **Tag creation** — after merge
-- **Live auto-chain verification** — smoke tests covered state machine; the --auto chain (which spawns planner→builder→verifier subagents in sequence) wasn't exercised end-to-end. Recommended first real test is on a throwaway project post-publish.
-- **ERP-side updates** — v4 tracking.json fields are additive; ERP should accept them via its existing Zod strip-unknowns pattern, but worth verifying on deploy.
-
-## Files the next reviewer should eyeball
-
-Priority order (highest leverage first):
-
-1. `V4_REVIEW.md` — this file lives in repo root, written as the handoff doc
-2. `CHANGELOG.md` [4.0.0] section — full feature list
-3. `templates/journey.md` — new artifact schema
-4. `agents/roadmapper.md` — biggest agent rewrite
-5. `skills/qualia-new/SKILL.md` — core flow, 14 steps
-6. `skills/qualia-idk/SKILL.md` — new diagnostic
-7. `skills/qualia-verify/SKILL.md` — auto-chain decision table
-8. `skills/qualia-handoff/SKILL.md` — 4 deliverables enforcement
-9. `bin/state.js` close-milestone (~975-1050) — readiness guards + summary append
-10. `bin/qualia-ui.js` journey-tree + milestone-complete functions
-
-## Recommended publish sequence
-
-```bash
-# Push both branches
-git push -u origin feature/story-file-plans
-git push -u origin feature/full-journey
-
-# Merge v3.7.0 to main, tag, push
-git checkout main
-git merge --ff-only feature/story-file-plans
-git tag v3.7.0
-git push origin main --tags
-
-# Merge v4.0.0 to main, tag, push
-git merge --ff-only feature/full-journey
-git tag v4.0.0
-git push origin main --tags
-
-# Publish
-npm publish
-npm view qualia-framework version   # should return 4.0.0
-```
-
-## Known limitations / open questions
-
-1. **Auto-chain not live-tested.** Unit tests cover state transitions; subagent chaining is covered by the skill prompt text but not exercised. First real project run will reveal edge cases.
-2. **Milestone-summary `tasks_completed` accuracy** depends on lifetime counter deltas. Works if close-milestone is the only consumer — verified in test suite.
-3. **/qualia-idk two-pass isolation** depends on Explore subagent respecting the "do not read .planning/" and "do not read source code" instructions. Prompt-level enforcement, not hard boundary.
-4. **Builder pre-inline** inflates prompt size for monorepos with large DESIGN.md + multiple context files. Acceptable for most projects; could be optimized in v4.1.
-
-## For questions
-
-Contact: Fawzi Goussous — fawzi@qualiasolutions.net
-
----
-
-*Written 2026-04-18 at release-candidate time. Supersedes the 2026-04-17 session report covering v3.4.2 / v3.5.0 / v3.6.0.*

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

@@ -1,290 +0,0 @@
-# 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.