qualia-framework 6.1.0 → 6.2.7

package/README.md

@@ -1,10 +1,10 @@
-# Qualia Framework v6.0.0
+# Qualia Framework v6.2.7
 
-A harness engineering framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
+A harness engineering framework for Claude Code and OpenAI Codex. It installs into `~/.claude/` and/or `~/.codex/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
 It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
 
-**v6.0** — wide-surface audit and cleanup. No new flagship; every change is a real bug fix, a silent failure surfaced, an outdated reference replaced, or a token-budget reduction. Uninstall/migrate manifests now match what ships (orphan hooks/agents fixed). Silent `catch {}` blocks in `auto-update`, `pre-compact`, and `env-empty-guard` now write trace entries. Trust-boundary block extracted to `rules/trust-boundary.md` (saves ~500 tokens per phase that spawns the full agent set). Pre-v4 CHANGELOG archived (2726 → 1875 lines). `tests/run-all.sh` fail-collect runner replaces the `&&`-chain so early-suite failures no longer hide later ones. Same 32 skills, same road, same behavior — just the broken edges fixed.
+**v6.2.7** — Codex runtime compatibility. The installer now writes Codex-native hooks, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config under `~/.codex/`, not just `AGENTS.md`.
 
 **The v5 line (preserved):**
 - **v5.0**, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
@@ -19,6 +19,15 @@ It is not an application framework like Rails or Next.js. It doesn't generate co
 - **v5.9.1**, kickoff UX fix. `/qualia-new` now opens with the Demo/Full/Quick gate as Step 1 (`AskUserQuestion`), then exactly one free-text pitch question, then mandatory hand-off to `/qualia-discuss` — no ad-hoc clarification questioning between them. The shape gate drives the whole downstream interview, so it must come first.
 - **v5.9.2**, hook ordering + ERP payload fixes. `pre-push.js` self-gates against `branch-guard.js` so a blocked-push no longer leaves an orphan bot commit in local history. `qualia-report` ERP payload omits empty ISO datetime fields (`session_started_at`, `last_pushed_at`) instead of sending `''`, which the ERP validator rejected as 422.
 - **v6.0.0**, audit + cleanup pass. See CHANGELOG for the full list. Highlights: uninstall/migrate manifests fixed, silent hook `catch{}` blocks now traced, phantom `rules/frontend.md` references replaced, `/qualia-learn` and `/qualia-map` declare their actually-used tools, `/qualia-plan` revision-cycle contradiction reconciled (max 2), `agents/planner.md` and `agents/qa-browser.md` MCP tools declared in frontmatter, `rules/trust-boundary.md` extracted, hardcoded `/tmp` paths replaced with `mktemp`, fail-collect test runner, pre-v4 CHANGELOG archived.
+- **v6.1.0**, `/qualia-vibe` adds a fast layout-preserving design pivot path and strengthens design-surface guards.
+- **v6.2.0**, removes hook-created bot commits. The ERP/report contract is `/qualia-report` POSTs, not passive git scraping of `tracking.json`.
+- **v6.2.1**, active-surface drift guard. README, guide, onboarding, ERP contract, road, milestone, polish, verify, and roadmapper wording now align with v6.2 behavior; refs tests fail on the stale claims.
+- **v6.2.2**, Framework/Memory/ERP clarity. ERP can hand a work packet into Framework sessions, reports can carry ERP-native IDs, and public npm install proof is a first-class release smoke.
+- **v6.2.3**, ERP ID guard. ERP-native IDs are UUID-only in report payloads; slugs remain in `project_id`/`team_id`.
+- **v6.2.4**, report payload contract. The ERP payload builder is now a shipped, tested script instead of shell-embedded inline code.
+- **v6.2.5**, project snapshot export. Framework can write `.planning/snapshots/project-snapshot-*.json` for explicit ERP/admin import.
+- **v6.2.6**, project snapshot upload. Framework can POST that project snapshot directly to ERP's project snapshot intake.
+- **v6.2.7**, Codex runtime compatibility. Codex installs now get native `hooks.json`, `agents/*.toml`, runtime scripts, rules, skills, templates, knowledge, guide, and config under `~/.codex/`.
 
 The Full Journey architecture carries forward: `/qualia-new` maps the entire project arc from kickoff to client handoff upfront, and the Road chains end-to-end in `--auto` mode with only two human gates per project.
 
@@ -40,7 +49,7 @@ Enter your team code when prompted. Get your code from Fawzi.
 ```bash
 npx qualia-framework@latest version    # Check installed version + updates
 npx qualia-framework@latest update     # Update to latest (remembers your code)
-npx qualia-framework@latest uninstall  # Clean removal from ~/.claude/
+npx qualia-framework@latest uninstall  # Clean removal from installed Claude/Codex homes
 npx qualia-framework@latest team list  # Show team members
 npx qualia-framework@latest team add   # Add a team member
 npx qualia-framework@latest traces     # View recent hook telemetry
@@ -48,7 +57,7 @@ npx qualia-framework@latest traces     # View recent hook telemetry
 
 ## Usage
 
-Open Claude Code in any project directory.
+Open Claude Code or Codex in any project directory.
 
 > **New to Qualia?** Open [`docs/onboarding.html`](docs/onboarding.html) in a browser for a one-page roadmap of the golden path. Best file to send a new hire.
 
@@ -115,7 +124,7 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 ### Knowledge & meta
 
 ```
-/qualia-learn      # Save a pattern, fix, or client pref to ~/.claude/knowledge/
+/qualia-learn      # Save a pattern, fix, or client pref to the active install home's knowledge/
 /qualia-flush      # Promote daily-log raw entries into curated knowledge concepts
 /qualia-postmortem # Self-heal — when verification fails, propose rule/skill deltas
 /qualia-skill-new  # Author a new Qualia skill or agent
@@ -150,22 +159,24 @@ Project
 
 **Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted. In the ERP, the primary operational dates are project deadline, milestone deadline, and employee shift submission date; framework tasks stay internal to agent execution.
 
-## What's Inside (v6.1.0)
+## What's Inside (v6.2.7)
 
 - **33 skills**, full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with `--deepen` parallel-interface design, feature, test, zoom, issues, triage), design (`qualia-polish --loop`, `qualia-vibe` for fast aesthetic pivots), deterministic enforcement (`qualia-hook-gen`), and meta (learn, skill-new, flush, postmortem)
 - **9 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
-- **12 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard
+- **11 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking stamp, migration-guard, pre-deploy-gate, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard
 - **7 always-loaded rules + 1 lazy-loaded** (`rules/`): grounding, security, infrastructure, deployment, speed (CLI-first / MCP tier-list), architecture (deep modules / scout-for-shallow-code), trust-boundary (shared injection-defence — extracted from agents in v6.0). Lazy-loaded by design-adjacent skills: one-opinion (EventMaster discipline — propose ONE direction, never a menu; new in v6.1)
 - **6 lazy-loaded design files** (`qualia-design/`): design-laws, design-brand, design-product, design-rubric, design-reference, frontend — `Read` on demand by design-aware skills/agents only, ~22 KB recovered from the always-loaded budget
-- **24 template files**: project.md, journey.md, plan.md (story-file format), state.md, DESIGN.md, CONTEXT.md (domain glossary), decisions/ADR-template.md, tracking.json (with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), knowledge templates, help.html
+- **25 template files**: project.md, journey.md, plan.md (story-file format), state.md, DESIGN.md, CONTEXT.md (domain glossary), work-packet.md (ERP-approved session context), decisions/ADR-template.md, tracking.json (with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), knowledge templates, help.html
 - **1 reference** — questioning.md methodology for deep project initialization
+- **Codex-native install surface** — `~/.codex/AGENTS.md`, `hooks.json`, `hooks/`, `agents/*.toml`, `bin/`, `rules/`, `skills/`, `qualia-design/`, `qualia-templates/`, `knowledge/`, and `qualia-guide.md`.
 
 ## Supported Platforms
 
-Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Code.
+Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Code or OpenAI Codex.
 
 - Every hook and the status line are pure Node.js — no external bash, jq, or GNU coreutils required.
-- Skills are executed by Claude Code's own Bash tool (which Claude Code provides on all platforms, including Windows).
+- Skills are installed as Markdown instructions with Node.js helpers; Claude and Codex each receive paths native to their own home directory.
+- Codex installs use Codex-native hook status messages and agent TOML files; Codex does not expose a Claude-style global `statusLine` setting, so `statusline.js` is installed as a shared renderer/helper instead of a fake config key.
 - Tested on Fedora, EndeavourOS, macOS, and Windows 10/11.
 
 ## Why It Works
@@ -192,7 +203,7 @@ Splitting planner, builder, and verifier into separate agents with separate cont
 
 ### Production-Grade Hooks
 
-All 12 hooks are real ops engineering, not theoretical:
+All 11 hooks are real ops engineering, not theoretical:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
 - **Session start** — Shows project state, next command, update notices, and health warnings at session start
@@ -200,8 +211,7 @@ All 12 hooks are real ops engineering, not theoretical:
 - **Git guardrails** — Blocks destructive git operations like force-push to main/master, `git clean -fd`, and `rm -rf .git`
 - **Branch guard** — Role-aware: owner can push to main, employees can't (parses refspec so `feature/x:main` bypass is blocked)
 - **Migration guard** — Catches `DROP TABLE` without `IF EXISTS`, `DELETE`/`UPDATE` without `WHERE`, `CREATE TABLE` without RLS, `GRANT ... TO PUBLIC`, `ALTER TABLE ... DROP COLUMN`
-- **Pre-push** — Stamps tracking.json via a bot commit so the ERP always sees fresh data
-- **Pre-compact** — Saves state before context compression
+- **Pre-push** — Stamps `tracking.json` locally for statusline, stop-session-log, and `/qualia-report`; does not create commits
 - **Stop-session log** — Writes lightweight daily session checkpoints into the knowledge layer
 - **Vercel account guard** — Verifies the correct Vercel account is active before deploy
 - **Env-empty guard** — Catches empty or placeholder environment variables before they reach production
@@ -209,7 +219,7 @@ All 12 hooks are real ops engineering, not theoretical:
 
 ### Enforced State Machine
 
-Every workflow step calls `state.js` — a Node.js state machine that validates preconditions (including plan content), updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. Milestone readiness guards ensure `close-milestone` refuses to close a milestone with unverified phases or < 2 phases (unless `--force`), and appends a summary to `tracking.json.milestones[]` so the ERP renders a clean project tree.
+Every workflow step calls `state.js` — a Node.js state machine that validates preconditions (including plan content), updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. Milestone readiness guards ensure `close-milestone` refuses to close a milestone with unverified phases or < 2 phases (unless `--force`), and appends a summary to `tracking.json.milestones[]` for local status, reports, and future explicit integrations.
 
 ### Wave-Based Parallelization
 
@@ -225,19 +235,18 @@ Plans are grouped into waves for parallel execution. No fancy DAG solver — the
 npx qualia-framework@latest install
      |
      v
-~/.claude/
-  ├── skills/             32 slash commands (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
-  ├── agents/             9 agent definitions (planner, builder, verifier, qa-browser, roadmapper, research-synthesizer, researcher, plan-checker, visual-evaluator)
-  ├── hooks/              12 Node.js hooks — cross-platform (no bash dependency)
-  ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js + slop-detect.mjs + plan-contract.js + agent-runs.js
+~/.claude/ and/or ~/.codex/
+  ├── skills/             33 slash commands (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
+  ├── agents/             9 agent definitions (Claude .md, Codex .toml)
+  ├── hooks/              11 Node.js hooks — cross-platform (no bash dependency)
+  ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js + slop-detect.mjs + plan-contract.js + agent-runs.js + ERP/report helpers
   ├── knowledge/          learned-patterns.md, common-fixes.md, client-prefs.md, daily-log/
-  ├── rules/              always-loaded substrate (grounding, security, infrastructure, deployment, speed, architecture)
-  ├── qualia-design/      lazy-loaded design substrate (design-laws, design-brand, design-product, design-rubric, design-reference, frontend) — Read on demand
-  ├── qualia-templates/   project.md, journey.md, plan.md (story-file), state.md, DESIGN.md, CONTEXT.md, decisions/ADR-template.md, tracking.json, requirements.md, roadmap.md, + projects/*.md + research-project/*.md + help.html
+  ├── rules/              grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, one-opinion
+  ├── qualia-design/      lazy-loaded design substrate — read on demand
+  ├── qualia-templates/   project, journey, plan, state, DESIGN, CONTEXT, work-packet, decisions, tracking, requirements, roadmap, research, help
   ├── qualia-references/  questioning.md (deep project initialization methodology)
-  ├── CLAUDE.md           global instructions (role-configured per team member, deliberately ~25 lines per Matt Pocock instruction-budget rule)
-  ├── (~/.codex/AGENTS.md if user opted into multi-target install — v5.1+)
-  └── (settings.json wired for hooks, statusline, spinner verbs, etc.)
+  ├── CLAUDE.md or AGENTS.md
+  └── settings.json or hooks.json wired for native hooks/status messages
 ```
 
 ## For Qualia Solutions Team

package/agents/roadmapper.md

@@ -150,7 +150,7 @@ node ~/.claude/bin/state.js init \
   --total_phases {count of Milestone 1 phases}
 ```
 
-`--milestone_name` is the human name of Milestone 1 (e.g. "Foundation"). tracking.json records it so the status bar and ERP tree render correctly.
+`--milestone_name` is the human name of Milestone 1 (e.g. "Foundation"). tracking.json records it so the status bar and report payload have human-readable milestone context.
 
 ### 8. Return a Summary