qualia-framework 5.4.0 → 5.5.0

package/docs/install-redesign-pilot.md

@@ -1,234 +0,0 @@
-# Install Redesign — Pilot Results (v5.1.0)
-
-Captured output and timing measurements for the three install-target
-scenarios, run on Linux 6.19 / Node 22 / non-TTY (piped stdin).
-
-All three scenarios pass cleanly. Total installer wall-clock cost
-remains under 200ms; the live-progress lifecycle adds negligible
-overhead because most file copies finish under 50ms (sub-50ms ops skip
-the "doing" state and go straight to `✓`).
-
-## Method
-
-```bash
-TMP=$(mktemp -d)
-START=$(date +%s%N)
-printf 'QS-FAWZI-01\n<CHOICE>\n' | HOME="$TMP" node bin/install.js > log.txt 2>&1
-END=$(date +%s%N)
-echo "wall-clock: $(( (END-START)/1000000 ))ms"
-```
-
-ANSI codes stripped from the captured logs below for readability. The
-real install renders the same lines with OKLCH-tinted teal / dim white
-/ green / yellow per `bin/qualia-ui.js`.
-
-## Scenario 1 — Claude Code only (target=1, the default)
-
-**Wall-clock:** 99ms · **Lines:** 202 · **Result:** `~/.claude/` populated
-(11 entries: agents, bin, CLAUDE.md, hooks, knowledge, qualia-guide.md,
-qualia-references, qualia-templates, rules, settings.json, skills),
-`~/.codex/` not created.
-
-```
-  ⬢  Q U A L I A
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Framework v5.1.0  ·  Qualia Solutions
-  Plan → Build → Verify → Ship
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Enter install code: QS-FAWZI-01
-
-  ✓ Welcome, Fawzi Goussous
-    Role: OWNER
-
-  Where would you like to install Qualia?
-
-    [1] Claude Code only     — recommended, full feature set
-    [2] OpenAI Codex only    — AGENTS.md (Codex's open standard)
-    [3] Both                 — max compatibility
-
-  Choice [1]: 1
-
-    Target: Claude Code
-
-  ▸ Skills
-  ────────────────────────────────────────
-  ✓ qualia
-  ✓ qualia-build
-  ✓ qualia-debug
-  ... (33 skills total) ...
-  ✓ zoho-workflow
-  └─ 33 skills · 4ms
-
-  ▸ Agents
-  ────────────────────────────────────────
-  ✓ builder.md
-  ... (9 agents total) ...
-  ✓ visual-evaluator.md
-  └─ 9 agents · 0ms
-
-  ▸ Rules
-  ────────────────────────────────────────
-  ... (10 rules) ...
-  └─ 10 rules · 0ms
-
-  ▸ Hooks                    (12 wired)
-  ▸ Templates                (16 entries, recursive)
-  ▸ Knowledge layer          (initialized on first install)
-  ▸ References               (methodology docs)
-  ▸ Configuration            (CLAUDE.md role substituted)
-  ▸ Scripts                  (state.js, qualia-ui.js, etc.)
-  ▸ Knowledge Base           (learned-patterns / common-fixes / client-prefs)
-  ▸ ERP Integration          (key opt-in)
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  ⬢  INSTALLED
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Fawzi Goussous  ·  OWNER  ·  v5.1.0
-
-  Targets   Claude Code
-  Time      99ms
-
-  Skills    33     Agents  9     Hooks   12
-  Rules     10     Scripts 7     Templates 16
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Quick Start
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  1. Restart Claude Code (loads new settings)
-  2. cd into any project and run claude
-  3. Try /qualia-new — kickoff a new project
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Welcome to the future with Qualia.
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Scenario 2 — Codex only (target=2)
-
-**Wall-clock:** 183ms (extra cost is the `which codex` probe via
-`spawnSync`) · **Lines:** 56 · **Result:** `~/.codex/AGENTS.md` written
-with `Role: OWNER` substituted, `~/.claude/` not touched.
-
-```
-  ⬢  Q U A L I A
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Framework v5.1.0  ·  Qualia Solutions
-  ...
-
-  Choice [1]: 2
-
-    Target: Codex
-
-  ▸ Codex
-  ────────────────────────────────────────
-  ✓ AGENTS.md (configured as OWNER)
-  └─ Codex install scope: AGENTS.md only — Codex's runtime does not currently
-     consume the framework's skills/hooks/agents on disk. AGENTS.md carries
-     the rules; commands route through Claude Code.
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  ⬢  INSTALLED
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Fawzi Goussous  ·  OWNER  ·  v5.1.0
-
-  Targets   Codex
-  Time      183ms
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Quick Start
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  1. Open Codex in any project
-  2. Codex picks up ~/.codex/AGENTS.md automatically
-  3. Ask Codex about Qualia rules — they're in AGENTS.md
-```
-
-If `which codex` fails (CLI not installed), the section prints a soft
-warning before the file write; the AGENTS.md is still written so the
-user is set up for when they install Codex via
-`npm install -g @openai/codex`.
-
-## Scenario 3 — Both (target=3)
-
-**Wall-clock:** 193ms · **Lines:** 209 · **Result:** Both `~/.claude/`
-and `~/.codex/AGENTS.md` populated. Final summary shows
-`Targets   Claude Code · Codex`.
-
-The Claude install runs first (identical to Scenario 1), then the Codex
-section appends:
-
-```
-  ▸ Codex
-  ────────────────────────────────────────
-  ✓ AGENTS.md (configured as OWNER)
-  └─ Codex install scope: AGENTS.md only — ...
-```
-
-Final card:
-
-```
-  Targets   Claude Code · Codex
-  Time      193ms
-```
-
-## Backward compatibility — legacy single-line piped install
-
-```bash
-echo "QS-FAWZI-01" | npx qualia-framework install
-```
-
-still works untouched. The target prompt sees EOF on stdin, normalizes
-to `1` (Claude only). Confirmed by test 121 in `tests/bin.test.sh`.
-
-## TTY-degradation verification
-
-In non-TTY mode (output piped to a file), the live-progress primitives
-in `bin/qualia-ui.js` skip:
-
-- The Braille spinner (`spinner()`) — prints a one-shot `→ text` /
-  `✓ text` instead of an animated frame loop.
-- The cursor-up / clear-line overwrites (`step()`) — skips the
-  `⏳ doing` line and prints the result line directly when finalized.
-- Cursor hide/show escapes — never emitted.
-
-Verified by test 124: `grep` for bare `\r`, `?25` (hide-cursor), and
-`\[2K` (clear-line) on a piped install log returns nothing.
-
-## Timing budget
-
-| Scenario | Wall-clock | Lines emitted | Notes |
-|----------|------------|---------------|-------|
-| 1 — Claude only | 99ms | 202 | Baseline |
-| 2 — Codex only | 183ms | 56 | + `which codex` probe (~80ms on Node 22 / Linux) |
-| 3 — Both | 193ms | 209 | Claude + Codex back-to-back |
-
-The spec budget was "≤ 2× the current install time." v5.1 stays comfortably
-under it — the live updates and section timing add only the cost of the
-extra console.log calls (negligible) and a couple of `Date.now()` calls
-per section.
-
-## Known limitations / deferred to v5.2
-
-- **Codex skills/hooks/agents not mirrored.** Codex uses `.toml` agent
-  format and a different hook schema. AGENTS.md is the rule layer they
-  share; the rest stays Claude-only until Codex's on-disk surface
-  stabilizes for cross-mapping.
-- **Spinner cosmetics on `cmd.exe`.** Braille frames may render as
-  boxes on legacy `cmd.exe`. Modern Windows Terminal handles them. The
-  install completes correctly either way; this is purely cosmetic.
-- **`Time` row precision.** Sub-second installs show `Xms`; ≥1s installs
-  show `X.Ys`. Either format is grep-friendly (regex
-  `Time *[0-9]+(\.[0-9]+)?(ms|s)`).
-
-## What this enables
-
-A user piping `npx qualia-framework install` from a fresh box now has
-a one-keystroke choice between Claude-only (the recommended default)
-and shipping Qualia's rule layer to OpenAI Codex via the open AGENTS.md
-standard. The live-progress redesign means even a 5-second install
-feels like an intentional product, not a hung process. First impression
-matches the rest of the framework's polish.

package/docs/instruction-budget-audit.md

@@ -1,113 +0,0 @@
-# Instruction-Budget Audit
-
-> **Date:** 2026-05-06
-> **Trigger:** Re-study of *Skills and Strategies for Real Engineering with Claude Code* (Matt Pocock) and *Context and Tools: Mastering the AI Engineering Lifecycle* (Patrick Debois, Karpathy, Pocock, Mario Zechner).
-> **Question:** Does Qualia Framework actually honor the "load on demand, not always" promise written in `CLAUDE.md`?
-
-## Finding 1 — `~/.claude/rules/*.md` is loaded eagerly by Claude Code
-
-Claude Code auto-discovers and injects every Markdown file under `~/.claude/rules/` into the system prompt of every session. This is **harness behavior**, not framework behavior — there is no `@-import` declaration in `~/.claude/CLAUDE.md`, yet the rules appear in the system reminder verbatim.
-
-**Measured cost (2026-05-06 install):**
-
-| File | Lines | Notes |
-|---|---|---|
-| `design-reference.md` | 179 | Motion specs, WCAG checklist, breakpoints |
-| `design-rubric.md` | 157 | 8-dimension verifier rubric |
-| `design-laws.md` | 148 | OKLCH, color strategy, typography |
-| `frontend.md` | 118 | Brand standards |
-| `design-brand.md` | 114 | Brand register |
-| `design-product.md` | 114 | Product register |
-| `grounding.md` | 114 | Severity rubric, citation format |
-| `infrastructure.md` | 87 | Stack, MCP servers, CLIs |
-| `deployment.md` | 30 | Post-deploy checklist |
-| `speed.md` | 23 | Speed rules |
-| `context7.md` | 14 | Context7 trigger rule |
-| `security.md` | 12 | RLS, auth, secrets |
-| **Total** | **1110** | |
-
-At ~4 chars/line average that is **~28 KB injected on every session**, regardless of whether the user is touching frontend, backend, infra, or nothing.
-
-The rule files themselves are written under the assumption that a skill or agent will read them on demand (e.g., `agents/builder.md` line 139 says *"Security, design, and performance rules auto-load from `rules/*.md` based on the files you touch"*) — which is correct **inside subagent fork prompts** but **wrong for the user's main session**, where the harness loads them all preemptively.
-
-## Finding 2 — `CLAUDE.md` template is already disciplined
-
-The framework `CLAUDE.md` template is 24 lines and ends with the right note:
-
-> *"this file stays under 25 lines. Steering rules go into discoverable skills, not into the global system prompt. CLI preferences go into hooks. Stack/architecture details are trivially discoverable in package.json/config."*
-
-This part is healthy. The leak is in `rules/`, not `CLAUDE.md`.
-
-## Finding 3 — Skill dedup hypothesis was wrong
-
-A first pass suggested deleting `qualia-quick`, `qualia-road`, `qualia-help`, `qualia-handoff` as duplicates. Cross-reference check showed:
-
-- `qualia-quick` is referenced from `bin/install.js`, `hooks/session-start.js`, `templates/help.html`, `README.md`, `guide.md`, `skills/qualia-prd/SKILL.md`, `skills/qualia-task/SKILL.md` — load-bearing.
-- `qualia-road` is referenced from `CLAUDE.md`, `AGENTS.md`, `README.md`, `guide.md`, `skills/qualia-help/SKILL.md` description — load-bearing.
-- `qualia-help` opens an HTML reference — distinct purpose from `qualia-road` (terminal map).
-- `qualia-handoff` is the final delivery skill, referenced from `bin/state.js:490`, ship/verify, journey-demo — load-bearing.
-
-**Each skill has a job.** No deletion is safe in this PR. The right fix is *boundary clarity in descriptions* (so the LLM picks correctly), not deletion.
-
-## Recommended follow-ups (deferred to separate PRs)
-
-### R1 — Move design rules to a lazy folder *(big, risky)*
-
-```
-~/.claude/rules/                           # always-loaded (HARNESS)
-  ├── grounding.md       (114)             # KEEP — universal
-  ├── security.md         (12)             # KEEP — universal
-  ├── speed.md            (23)             # KEEP — universal
-  ├── context7.md         (14)             # KEEP — universal
-  └── infrastructure.md   (87)             # KEEP — universal stack
-                                            #   total: ~250 lines
-
-~/.claude/qualia-design/                    # explicit-load only
-  ├── design-laws.md     (148)
-  ├── design-brand.md    (114)
-  ├── design-product.md  (114)
-  ├── design-reference.md (179)
-  ├── design-rubric.md   (157)
-  ├── frontend.md        (118)
-  └── deployment.md       (30)             # post-deploy checklist; loaded by /qualia-ship
-                                            #   total: 860 lines, NOT auto-loaded
-```
-
-Skills/agents that need design rules `Read` them on demand (already the pattern in `agents/builder.md` and `agents/verifier.md`). The save: **~28 KB → ~6 KB injected per session, ~22 KB recovered.**
-
-Required changes:
-1. `bin/install.js` — install design rules to `~/.claude/qualia-design/` instead of `~/.claude/rules/`.
-2. Every skill/agent reference path `rules/design-*.md` → `qualia-design/design-*.md` or use `~/.claude/qualia-design/design-*.md` absolute.
-3. Update `hooks/session-start.js` `CRITICAL_FILES` health check.
-4. Migration step in `bin/install.js` to clean up old `~/.claude/rules/design-*.md` for existing installs.
-
-**Effort:** M-L. **Impact:** ~80% reduction in always-loaded substrate.
-
-### R2 — Skill description sharpening *(small, safe)*
-
-`qualia-quick` and `qualia-task` overlap in description. Tighten:
-- `qualia-quick`: "≤1 hour, 1 file, no plan, no spawn — just do it."
-- `qualia-task`: "1–3 hours, 1–5 files, fresh builder spawn, atomic commit, no phase plan."
-
-`qualia-road` and `qualia-help` overlap. Clarify:
-- `qualia-road`: "Terminal-rendered workflow map. Use over SSH or when no browser."
-- `qualia-help`: "Browser-rendered HTML reference. Default."
-
-### R3 — Per-skill versioning + eval harness *(carry-over from notebook 1, source 6 — Debois)*
-
-Each skill carries its own `version:` in frontmatter and a `tests/skills/{skill-name}.spec.sh` fixture. CI runs the fixture against the skill spec. Catches silent skill rot when CC behavior changes underneath.
-
-### R4 — MCP tier-list rule in `rules/speed.md` *(carry-over from notebook 1, source 5 — CLI vs MCP)*
-
-Codify the "CLI-first" principle. Reference the existing `/supabase` skill replacing 32 supabase MCP tools as the canonical example.
-
-## What changed in *this* PR
-
-This PR ships the changes that don't require user-state migration:
-
-1. **Citation enforcement preamble** in `agents/builder.md` and `agents/verifier.md` — closes notebook 2, source #9 (*Never Trust an LLM*). Builders and verifiers must cite `file:line — "quoted"` or write `INSUFFICIENT EVIDENCE`. No hedging, no narration.
-2. **`rules/architecture.md`** — net-new, deep-modules + scout-for-shallow-code from notebook 2 sources #5 + #12 (Pocock de-slop, codebase-not-ready-for-AI). Skill `/qualia-optimize --deepen` already exists; this rule formalizes the architectural taste it scouts for.
-3. **README warning** — "Never run Claude's `/init`" — direct users to `/qualia-new` or `/qualia-map`. Per notebook 2 sources #3 + #8.
-4. **This audit document** — anchors the deferred follow-ups so they don't get lost.
-
-The relocation in R1 is the biggest single win available; it is intentionally deferred so this PR stays small and reversible.