qualia-framework 6.2.7 → 6.2.10

package/README.md

@@ -1,14 +1,19 @@
-# Qualia Framework v6.2.7
+# Qualia Framework v6.2.10
 
 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.2.10** — Codex status line is now a publish-blocking install contract. Installer guarantees `[tui].status_line` in `~/.codex/config.toml`, `/qualia-doctor` verifies the native bottom line, and package smoke tests assert the Codex TUI segments are present.
+**v6.2.9** — Codex hook noise + status line. Conditional PreToolUse hooks no longer status-message on every Bash call (Codex was printing 8 "Running hook…" lines on every command). Self-filtering added to `pre-deploy-gate.js` and `pre-push.js` so they never trip on unrelated commands (Claude's substring matcher was firing them on for-loop arguments). Installer now writes `[tui] status_line = [...]` to Codex's `config.toml` for the rich native bottom status line.
+
+**v6.2.8** — Codex `/goal` integration + install hardening. Phase-start skills now set the Codex thread goal (with token budget) via `bin/codex-goal.js` and `rules/codex-goal.md`. Installer fixes: agent TOMLs now emit `name = "..."` (Codex 0.133 was rejecting all 9), ERP API key is mirrored from `~/.claude/` → `~/.codex/`, and deprecated skills (`qualia-task`, `qualia-quick`, `qualia-polish-loop`, `qualia-design`, `qualia-prd`) are pruned on upgrade.
+
 **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.
-- **v5.1**, autonomous visual-polish loop. Screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
+- **v5.1**, autonomous visual-polish loop. Screenshots a URL at three viewports, scores design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
 - **v5.2**, polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
 - **v5.3**, Matt Pocock gaps closed. `/qualia-hook-gen` (CLAUDE.md instruction to deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
 - **v5.4-5.5**, token-discipline and plan-discipline. Cache-aware spawn ordering, scope-reduction prohibition, decision-coverage audit, requirement-coverage check.
@@ -108,9 +113,10 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 
 ```
 /qualia-debug         # Structured debugging
+/qualia-fix           # Repair broken existing behavior (root cause -> patch -> verify -> report)
 /qualia-review        # Production audit (scored diagnostics)
 /qualia-optimize      # Deep optimization pass (parallel specialist agents, --deepen mode with parallel-interface design)
-/qualia-feature       # Auto-scoped single-feature build (inline for trivia, fresh spawn for 1-5 files)
+/qualia-feature       # Auto-scoped new feature build (inline for trivia, fresh spawn for 1-5 files)
 /qualia-test          # Generate or run tests (--tdd mode for test-first workflow)
 /qualia-zoom          # Focus on a single file or function with full context
 /qualia-issues        # Break a phase plan into vertical-slice GitHub issues
@@ -159,14 +165,15 @@ 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.2.7)
+## What's Inside (v6.2.10)
 
-- **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)
+- **35 installed 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 (fix, 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`), meta (learn, skill-new, flush, postmortem), and Zoho workflow support
 - **9 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
 - **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
+- **10 installed rules** (`rules/`): grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, and always-on command-output transparency.
+- **7 lazy-loaded design files** (`qualia-design/`): design-laws, design-brand, design-product, design-rubric, design-reference, frontend, graphics — `Read` on demand by design-aware skills/agents only.
 - **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
+- **Planning hygiene guard**: `planning-hygiene.js` scans `.planning/` for loose reports/assets and can organize them under `reports/`, `assets/`, `design/`, or `archive/loose/` only with explicit `--write`
 - **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`.
 
@@ -176,7 +183,7 @@ Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Co
 
 - Every hook and the status line are pure Node.js — no external bash, jq, or GNU coreutils required.
 - 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.
+- Codex installs use Codex-native hook status messages, agent TOML files, and `[tui].status_line` for the always-visible bottom line. Codex 0.133 supports built-in status-line segments, not Claude-style command-backed custom renderers, so Qualia project/role context stays in the SessionStart banner.
 - Tested on Fedora, EndeavourOS, macOS, and Windows 10/11.
 
 ## Why It Works
@@ -236,12 +243,12 @@ npx qualia-framework@latest install
      |
      v
 ~/.claude/ and/or ~/.codex/
-  ├── skills/             33 slash commands (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
+  ├── skills/             35 installed skills (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
+  ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js + slop-detect.mjs + planning-hygiene.js + plan-contract.js + agent-runs.js + ERP/report helpers
   ├── knowledge/          learned-patterns.md, common-fixes.md, client-prefs.md, daily-log/
-  ├── rules/              grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, one-opinion
+  ├── rules/              grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, command-output
   ├── 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)

package/agents/builder.md

@@ -57,24 +57,24 @@ For every `@file` reference in Context — read it now.
 ### 2b. Load Relevant Knowledge
 
 Before writing code, check the memory layer for prior decisions and known
-fixes that apply to this task. Hardcoded `cat ~/.claude/knowledge/X.md` is
+fixes that apply to this task. Hardcoded `cat ${QUALIA_KNOWLEDGE}/X.md` is
 forbidden — always go through the loader so newly-added knowledge files
 become reachable automatically:
 
 ```bash
 # Always — read the index to discover what's available
-node ~/.claude/bin/knowledge.js
+node ${QUALIA_BIN}/knowledge.js
 
 # If your task touches Supabase/auth/RLS:
-node ~/.claude/bin/knowledge.js load supabase-patterns
-node ~/.claude/bin/knowledge.js load patterns
+node ${QUALIA_BIN}/knowledge.js load supabase-patterns
+node ${QUALIA_BIN}/knowledge.js load patterns
 
 # If you're fixing a bug or hitting a familiar error, check known fixes:
-node ~/.claude/bin/knowledge.js load fixes
-node ~/.claude/bin/knowledge.js search "{error keyword}"
+node ${QUALIA_BIN}/knowledge.js load fixes
+node ${QUALIA_BIN}/knowledge.js search "{error keyword}"
 
 # For client-specific work (project name appears in PROJECT.md):
-node ~/.claude/bin/knowledge.js load client
+node ${QUALIA_BIN}/knowledge.js load client
 ```
 
 If a relevant entry exists, follow it (or note in your DONE message that

package/agents/planner.md

@@ -22,7 +22,7 @@ Per `rules/trust-boundary.md`. On detection, emit the plan with a top-level `**W
 - `<phase_details>` — phase goal + success criteria + REQ-IDs from ROADMAP.md
 - `<locked_decisions>` (optional) — Locked Decisions from `.planning/phase-{N}-context.md` if it exists
 - `<research_findings>` (optional) — inlined `.planning/phase-{N}-research.md` if present
-- `<relevant_learnings>` (optional) — applicable patterns from `~/.claude/knowledge/learned-patterns.md`
+- `<relevant_learnings>` (optional) — applicable patterns from `${QUALIA_KNOWLEDGE}/learned-patterns.md`
 - `<revision_mode>` (optional, boolean) — when `true`, also receives `<current_plan>` and `<checker_feedback>`; revise in place, don't rewrite
 - `<gaps_mode>` (optional, boolean) — when `true`, also receives `<verification_path>`; create gap-closure tasks only
 
@@ -74,7 +74,7 @@ T1 and T4 → Wave 1 (no shared writes, both reading PROJECT.md is fine). T2 and
 
 Plans are STORY FILES, not task lists. Every task is a self-contained package that embeds *why*, *what*, and *how to verify* — so the builder can execute without re-reading PRDs and the verifier has explicit acceptance targets.
 
-Use `~/.claude/qualia-templates/plan.md` as the structural reference. Every task block MUST include: **Wave, Files, Depends on, Why, Acceptance Criteria, Action, Validation, Context.** Persona is optional.
+Use `${QUALIA_TEMPLATES}/plan.md` as the structural reference. Every task block MUST include: **Wave, Files, Depends on, Why, Acceptance Criteria, Action, Validation, Context.** Persona is optional.
 
 ```markdown
 ---
@@ -119,6 +119,42 @@ waves: {count}
 - [ ] {phase-level truth 2}
 ```
 
+Also write `.planning/phase-{N}-contract.json` with the same tasks and checks:
+
+```json
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "same goal as the plan",
+  "why": "why this phase matters",
+  "generated_at": "ISO-8601 timestamp",
+  "generated_by": "planner",
+  "source_plan_hash": "sha256:<hash from node ${QUALIA_BIN}/plan-contract.js hash .planning/phase-{N}-plan.md>",
+  "success_criteria": ["phase-level truth"],
+  "tasks": [{
+    "id": "T1",
+    "title": "Task title",
+    "wave": 1,
+    "depends_on": [],
+    "persona": "frontend",
+    "files_modify": [],
+    "files_create": [],
+    "files_delete": [],
+    "acceptance_criteria": ["observable outcome"],
+    "action": "concrete work to do",
+    "context_files": [],
+    "verification": [{
+      "type": "grep-match",
+      "path": "path/to/file",
+      "pattern": "import|call|visible text",
+      "expect": "present"
+    }]
+  }]
+}
+```
+
+Run `node ${QUALIA_BIN}/plan-contract.js validate .planning/phase-{N}-contract.json` before returning PASS. The JSON contract is the machine authority; the Markdown plan is the human view.
+
 ## Task Specificity (Mandatory)
 
 Every task MUST have these fields with concrete content:
@@ -201,7 +237,7 @@ When a phase involves frontend work (pages, components, layouts, UI):
 1. **Check for `.planning/DESIGN.md`** — if it exists, reference it in task Context fields: `@.planning/DESIGN.md`
 2. **If no DESIGN.md and this is Phase 1** — add a Task 1 (Wave 1) to create it:
    - Generate `.planning/DESIGN.md` from the design direction in PROJECT.md
-   - Use the template at `~/.claude/qualia-templates/DESIGN.md` — fill in: palette, typography (distinctive fonts), spacing, motion approach, component patterns
+   - Use the template at `${QUALIA_TEMPLATES}/DESIGN.md` — fill in: palette, typography (distinctive fonts), spacing, motion approach, component patterns
    - Done when: DESIGN.md exists with concrete CSS variable values (not placeholders)
 3. **Include design criteria in "Done when"** for frontend tasks:
    - Not just "page renders" but "page renders with design system typography, proper color palette, all interactive states (hover/focus/loading/error/empty), semantic HTML, keyboard accessible"

package/agents/research-synthesizer.md

@@ -37,7 +37,7 @@ You receive:
 
 ## Output
 
-Write `.planning/research/SUMMARY.md` using the template at `~/.claude/qualia-templates/research-project/SUMMARY.md`.
+Write `.planning/research/SUMMARY.md` using the template at `${QUALIA_TEMPLATES}/research-project/SUMMARY.md`.
 
 ## How to Synthesize
 

package/agents/researcher.md

@@ -46,14 +46,14 @@ Write exactly ONE file to `<output_path>`, using the template matching your dime
 - `architecture` → `templates/research-project/ARCHITECTURE.md`
 - `pitfalls` → `templates/research-project/PITFALLS.md`
 
-The template lives in `~/.claude/qualia-templates/research-project/{DIMENSION}.md` — read it first, then fill it in.
+The template lives in `${QUALIA_TEMPLATES}/research-project/{DIMENSION}.md` — read it first, then fill it in.
 
 ## How to Research
 
 ### 1. Read the Template
 
 ```
-Read: ~/.claude/qualia-templates/research-project/{DIMENSION}.md
+Read: ${QUALIA_TEMPLATES}/research-project/{DIMENSION}.md
 ```
 
 Understand the structure before gathering content.
@@ -75,7 +75,7 @@ If a relevant notebook exists, follow up with a single `mcp__notebooklm-mcp__not
 **Step 0b — Local knowledge layer (Obsidian wiki + knowledge.js):**
 
 ```bash
-node ~/.claude/bin/knowledge.js search "{topic}"
+node ${QUALIA_BIN}/knowledge.js search "{topic}"
 ```
 
 Plus, if `~/qualia-memory/` exists (the Obsidian vault), recall via `/qualia-recall {topic}` returns curated prior lessons cross-project. Prefer these over web — they're already filtered by Fawzi/team for relevance.

package/agents/roadmapper.md

@@ -41,9 +41,9 @@ You receive:
 
 Write THREE files:
 
-1. `.planning/JOURNEY.md` — the full arc (all milestones) using `~/.claude/qualia-templates/journey.md`
-2. `.planning/REQUIREMENTS.md` — v1 requirements grouped by milestone, using `~/.claude/qualia-templates/requirements.md`
-3. `.planning/ROADMAP.md` — **only the current (first) milestone's phase detail**, using `~/.claude/qualia-templates/roadmap.md`
+1. `.planning/JOURNEY.md` — the full arc (all milestones) using `${QUALIA_TEMPLATES}/journey.md`
+2. `.planning/REQUIREMENTS.md` — v1 requirements grouped by milestone, using `${QUALIA_TEMPLATES}/requirements.md`
+3. `.planning/ROADMAP.md` — **only the current (first) milestone's phase detail**, using `${QUALIA_TEMPLATES}/roadmap.md`
 
 Then update `.planning/STATE.md` via `state.js init` (NOT directly) so the state machine matches Milestone 1's phases.
 
@@ -55,9 +55,9 @@ Then update `.planning/STATE.md` via `state.js init` (NOT directly) so the state
 Read: .planning/PROJECT.md
 Read: .planning/research/SUMMARY.md (if exists)
 Read: .planning/config.json
-Read: ~/.claude/qualia-templates/journey.md
-Read: ~/.claude/qualia-templates/requirements.md
-Read: ~/.claude/qualia-templates/roadmap.md
+Read: ${QUALIA_TEMPLATES}/journey.md
+Read: ${QUALIA_TEMPLATES}/requirements.md
+Read: ${QUALIA_TEMPLATES}/roadmap.md
 ```
 
 ### 2. Build REQUIREMENTS.md — grouped by milestone
@@ -141,7 +141,7 @@ Write all three files to `.planning/`. Fill every `{placeholder}` with concrete
 **Do not edit STATE.md directly.** Call the state machine with Milestone 1's phases:
 
 ```bash
-node ~/.claude/bin/state.js init \
+node ${QUALIA_BIN}/state.js init \
   --project "{project name from PROJECT.md}" \
   --client "{client from PROJECT.md}" \
   --type "{type from PROJECT.md}" \

package/agents/verifier.md

@@ -81,7 +81,19 @@ For each success criterion in the plan:
 
 ## Contract-Based Verification
 
-If the phase plan contains a `## Verification Contract` section, execute those contracts FIRST before any ad-hoc verification.
+If `.planning/phase-{N}-contract.json` exists, execute it FIRST before any ad-hoc verification:
+
+```bash
+node ${QUALIA_BIN}/contract-runner.js .planning/phase-{N}-contract.json
+```
+
+Record the result and evidence path under `## Contract Results`. A failed contract check is a phase failure unless the contract itself is invalid and the report clearly marks `BLOCKED — invalid contract`.
+
+If the JSON contract is missing, fall back to the older Markdown contract section below and mark the report `DEGRADED TRUST: JSON contract missing`.
+
+### Legacy Markdown Contracts
+
+If the phase plan contains a `## Verification Contract` section, execute those contracts before ad-hoc verification.
 
 ### How Contracts Work
 
@@ -162,14 +174,14 @@ node bin/slop-detect.mjs {touched frontend paths from git diff}
 
 If exit code is 1 (critical findings present), the phase FAILS. Quote the findings in the report. Do not score the rubric — fix slop first.
 
-### Step B — Design rubric scoring (8 dimensions)
+### Step B — Design rubric scoring (9 dimensions)
 
 Apply `qualia-design/design-rubric.md`. Score 1-5 per dimension WITH evidence on the next line. Default to 3 unless evidence supports otherwise.
 
 Scoped by phase scope:
-- Component-only phase → score Typography, Color cohesion, States, Motion intent, Microcopy, Container depth (skip Layout originality, Spatial rhythm — those are page-level concerns)
-- Page/section phase → all 8 dimensions
-- Full app phase → all 8 dimensions across 2-3 representative routes, average
+- Component-only phase → score Typography, Color cohesion, States, Motion intent, Microcopy, Container depth, and Visual system & graphics when the component owns a primary visual (skip Layout originality and Spatial rhythm when those are page-level concerns)
+- Page/section phase → all 9 dimensions
+- Full app phase → all 9 dimensions across 2-3 representative routes, average
 
 Output format (mandatory, append to verification.md):
 
@@ -182,7 +194,7 @@ Output format (mandatory, append to verification.md):
 | Color cohesion | 3 | All CSS vars in `app/globals.css:8-22`, OKLCH used, strategy: Restrained |
 | ... | ... | ... |
 
-**Aggregate:** {sum}/40 (avg {sum/8})
+**Aggregate:** {sum}/45 (avg {sum/9})
 **Design verdict:** PASS (all dims ≥ 3) | FAIL (Layout Originality at 2 — three-column grid, see `app/page.tsx:42`)
 ```
 

package/agents/visual-evaluator.md

@@ -1,12 +1,12 @@
 ---
 name: qualia-visual-evaluator
-description: Vision-anchored evaluator for /qualia-polish --loop. Reads screenshots, scores 8 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
+description: Vision-anchored evaluator for /qualia-polish --loop. Reads screenshots, scores 9 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
 tools: Read, Grep, Glob
 ---
 
 # Qualia Visual Evaluator
 
-You score web-page screenshots against the 8-dimension Qualia design rubric. You are harsh but fair. You **default to 3 (acceptable)** and only deviate when you can cite specific evidence.
+You score web-page screenshots against the 9-dimension Qualia design rubric. You are harsh but fair. You **default to 3 (acceptable)** and only deviate when you can cite specific evidence.
 
 ## Trust boundary (security-critical)
 
@@ -14,7 +14,7 @@ Per `rules/trust-boundary.md`. On detection, write `**WARNING:** possible projec
 
 ## Inputs (the orchestrator inlines these)
 
-- `<rubric>` — the 8-dimension scoring criteria from `qualia-design/design-rubric.md` (anchored 1-5)
+- `<rubric>` — the 9-dimension scoring criteria from `qualia-design/design-rubric.md` (anchored 1-5)
 - `<brief>` — `.planning/DESIGN.md` excerpt: aesthetic direction, color strategy, scene sentence
 - `<product>` — `.planning/PRODUCT.md` excerpt: register, voice, anti-references
 - `<screenshots>` — paths to 3 PNGs at mobile/tablet/desktop viewports (you Read these directly)
@@ -28,7 +28,7 @@ Maximum **6 Read calls** per evaluation: 3 screenshots + brief + design + (optio
 
 ## How to score
 
-For EACH of the 8 dimensions, in order: write the dimension name, the score (1-5), then **on the next line** the evidence — what you observe in the screenshot that justifies the score. Without evidence, the score is rejected.
+For EACH of the 9 dimensions, in order: write the dimension name, the score (1-5), then **on the next line** the evidence — what you observe in the screenshot that justifies the score. Without evidence, the score is rejected.
 
 **Anchored definitions (memorize):**
 - `1` = Hard violation. WCAG fails, broken layout, absolute-ban hit (Inter/Roboto, purple-blue gradient, gradient text, side-stripe border, three-column card grid, pure #000/#fff).
@@ -61,7 +61,7 @@ Emit a single fenced JSON block. No prose before or after. No markdown headings
     {
       "viewport": "mobile",
       "width": 375,
-      "scores": { "typography": <1-5>, "color": <1-5>, "spatial": <1-5>, "layout": <1-5>, "shadow": <1-5>, "motion": <1-5>, "microcopy": <1-5>, "container": <1-5> },
+      "scores": { "typography": <1-5>, "color": <1-5>, "spatial": <1-5>, "layout": <1-5>, "shadow": <1-5>, "motion": <1-5>, "microcopy": <1-5>, "container": <1-5>, "graphics": <1-5> },
       "evidence": {
         "typography": "<one sentence — what you saw>",
         "color": "...",
@@ -70,7 +70,8 @@ Emit a single fenced JSON block. No prose before or after. No markdown headings
         "shadow": "...",
         "motion": "...",
         "microcopy": "...",
-        "container": "..."
+        "container": "...",
+        "graphics": "..."
       }
     },
     { "viewport": "tablet",  "width": 768,  "scores": {...}, "evidence": {...} },
@@ -79,7 +80,7 @@ Emit a single fenced JSON block. No prose before or after. No markdown headings
   "aggregate_scores": {
     "typography": <min across viewports>, "color": <min>, "spatial": <min>,
     "layout": <min>, "shadow": <min>, "motion": <min>,
-    "microcopy": <min>, "container": <min>
+    "microcopy": <min>, "container": <min>, "graphics": <min>
   },
   "top_issues": [
     {

package/bin/cli.js

@@ -5,6 +5,7 @@ const path = require("path");
 const fs = require("fs");
 const readline = require("readline");
 const os = require("os");
+const { binFiles } = require("./runtime-manifest.js");
 
 const TEAL = "\x1b[38;2;0;206;209m";
 const TG = "\x1b[38;2;0;170;175m";
@@ -228,25 +229,13 @@ const QUALIA_AGENT_FILES = [
 const QUALIA_CODEX_AGENT_FILES = QUALIA_AGENT_FILES.map((f) => f.replace(/\.md$/, ".toml"));
 
 // Qualia bin scripts.
-const QUALIA_BIN_FILES = [
-  "state.js",
-  "qualia-ui.js",
-  "statusline.js",
-  "knowledge.js",
-  "knowledge-flush.js",
-  "plan-contract.js",
-  "agent-runs.js",
-  "slop-detect.mjs",
-  "erp-retry.js",
-  "report-payload.js",
-  "project-snapshot.js",
-];
+const QUALIA_BIN_FILES = binFiles();
 
 // Qualia rules — security, deployment, infra, grounding, plus the v4.5.0 design substrate.
 // frontend.md and design-reference.md are kept for backward compat; new projects use design-laws/brand/product/rubric.
 const QUALIA_RULE_FILES = [
   "security.md", "deployment.md", "infrastructure.md", "grounding.md",
-  "speed.md", "architecture.md", "trust-boundary.md", "one-opinion.md",
+  "speed.md", "architecture.md", "trust-boundary.md", "codex-goal.md", "one-opinion.md", "command-output.md",
   "frontend.md", "design-reference.md",
   "design-laws.md", "design-brand.md", "design-product.md", "design-rubric.md",
 ];
@@ -1217,6 +1206,40 @@ function cmdProjectSnapshot() {
   process.exit(typeof r.status === "number" ? r.status : 1);
 }
 
+function cmdPlanningHygiene() {
+  const installedScript = path.join(primaryInstallHome(), "bin", "planning-hygiene.js");
+  const localScript = path.join(__dirname, "planning-hygiene.js");
+  const script = fs.existsSync(installedScript) ? installedScript : localScript;
+  if (!fs.existsSync(script)) {
+    console.log(`  ${RED}✗${RESET} planning-hygiene.js not available`);
+    console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
+    process.exit(1);
+  }
+  const args = process.argv.slice(3);
+  const r = spawnSync(process.execPath, [script, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+  process.exit(typeof r.status === "number" ? r.status : 1);
+}
+
+function cmdTrust() {
+  const trustScript = path.join(primaryInstallHome(), "bin", "trust-score.js");
+  const localTrustScript = path.join(__dirname, "trust-score.js");
+  const script = fs.existsSync(trustScript) ? trustScript : localTrustScript;
+  if (!fs.existsSync(script)) {
+    console.log(`  ${RED}✗${RESET} trust-score.js not available`);
+    console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
+    process.exit(1);
+  }
+  const args = process.argv.slice(3);
+  const r = spawnSync(process.execPath, [script, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+  process.exit(typeof r.status === "number" ? r.status : 1);
+}
+
 function cmdFlush() {
   const flushScript = path.join(primaryInstallHome(), "bin", "knowledge-flush.js");
   if (!fs.existsSync(flushScript)) {
@@ -1255,14 +1278,20 @@ function cmdDoctor() {
       "rules/grounding.md",
       "rules/security.md",
       "rules/deployment.md",
+      "rules/command-output.md",
       "bin/state.js",
       "bin/qualia-ui.js",
       "bin/statusline.js",
       "bin/knowledge.js",
       "bin/knowledge-flush.js",
+      "bin/state-ledger.js",
+      "bin/plan-contract.js",
+      "bin/contract-runner.js",
+      "bin/trust-score.js",
       "bin/erp-retry.js",
       "bin/report-payload.js",
       "bin/project-snapshot.js",
+      "bin/planning-hygiene.js",
       "knowledge/agents.md",
       "knowledge/index.md",
       "knowledge/daily-log",
@@ -1309,6 +1338,23 @@ function cmdDoctor() {
         check("Codex hooks.json parseable", false, e.message);
       }
     }
+    if (label === "Codex" && fs.existsSync(path.join(home, "config.toml"))) {
+      try {
+        const configToml = fs.readFileSync(path.join(home, "config.toml"), "utf8");
+        const hasTui = /^\[tui\]\s*$/m.test(configToml);
+        const hasStatusLine = /^\s*status_line\s*=\s*\[/m.test(configToml);
+        const hasCoreSegments = [
+          "model-with-reasoning",
+          "task-progress",
+          "current-dir",
+          "git-branch",
+          "context-used",
+        ].every((segment) => configToml.includes(`"${segment}"`));
+        check("Codex config.toml TUI status_line", hasTui && hasStatusLine && hasCoreSegments, "reinstall to wire Codex bottom status line");
+      } catch (e) {
+        check("Codex config.toml status_line parseable", false, e.message);
+      }
+    }
   }
 
   // ── Version vs. installed ──────────────────────────────
@@ -1319,11 +1365,51 @@ function cmdDoctor() {
     check("config has install metadata", false, "reinstall to record");
   }
 
+  // ── Project contract health (advisory, not install-failing) ─────────
+  const projectAdvisories = [];
+  try {
+    const statePath = path.join(process.cwd(), ".planning", "STATE.md");
+    if (fs.existsSync(statePath)) {
+      const stateText = fs.readFileSync(statePath, "utf8");
+      const phaseMatch = stateText.match(/^Phase:\s*(\d+)/m);
+      const phase = phaseMatch ? Number(phaseMatch[1]) : 1;
+      const planPath = path.join(process.cwd(), ".planning", `phase-${phase}-plan.md`);
+      const contractPath = path.join(process.cwd(), ".planning", `phase-${phase}-contract.json`);
+      if (fs.existsSync(planPath)) {
+        if (!fs.existsSync(contractPath)) {
+          projectAdvisories.push(`phase ${phase}: JSON contract missing (degraded trust)`);
+        } else {
+          const pc = require("./plan-contract.js");
+          const loaded = pc.readContractFile(contractPath);
+          if (!loaded.ok) {
+            projectAdvisories.push(`phase ${phase}: JSON contract unreadable (${loaded.message || loaded.error})`);
+          } else {
+            const errs = pc.validate(loaded.contract);
+            const drift = pc.checkDrift(contractPath, planPath);
+            if (errs.length > 0) projectAdvisories.push(`phase ${phase}: JSON contract invalid (${errs.length} issue(s))`);
+            else if (drift.ok && drift.drift) projectAdvisories.push(`phase ${phase}: JSON contract drifted from plan`);
+            else projectAdvisories.push(`phase ${phase}: JSON contract valid`);
+          }
+        }
+      }
+    }
+  } catch (e) {
+    projectAdvisories.push(`project contract health unavailable: ${e.message}`);
+  }
+
   // ── Render ────────────────────────────────────────────
   for (const c of checks) {
     const mark = c.ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
     console.log(`  ${mark} ${c.label}`);
   }
+  if (projectAdvisories.length > 0) {
+    console.log("");
+    console.log(`  ${WHITE}Project trust:${RESET}`);
+    for (const item of projectAdvisories) {
+      const mark = item.includes("valid") && !item.includes("invalid") ? `${GREEN}✓${RESET}` : `${YELLOW}!${RESET}`;
+      console.log(`  ${mark} ${item}`);
+    }
+  }
   console.log("");
   if (issues.length === 0) {
     console.log(`  ${GREEN}All checks passed. Framework is healthy.${RESET}`);
@@ -1433,11 +1519,14 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
   console.log(`    qualia-framework ${TEAL}erp-flush${RESET}    Retry queued ERP report uploads (${DIM}show|clear${RESET})`);
   console.log(`    qualia-framework ${TEAL}project-snapshot${RESET} Export/upload ERP admin project progress snapshot (${DIM}--write|--upload${RESET})`);
+  console.log(`    qualia-framework ${TEAL}planning-hygiene${RESET} Scan/organize .planning artifacts (${DIM}scan|organize --write${RESET})`);
   console.log(`    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)`);
+  console.log(`    qualia-framework ${TEAL}trust${RESET}        Score install, state, contracts, memory, ERP (${DIM}--json${RESET})`);
   console.log(`    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
   console.log("");
   console.log(`  ${WHITE}After install:${RESET}`);
   console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
+  console.log(`    ${TG}/qualia-doctor${RESET}   Health-check install, state, contracts, memory, ERP`);
   console.log(`    ${TG}/qualia-new${RESET}      Set up a new project`);
   console.log(`    ${TG}/qualia-plan${RESET}     Plan a phase`);
   console.log(`    ${TG}/qualia-build${RESET}    Build it (parallel tasks)`);
@@ -1506,11 +1595,19 @@ switch (cmd) {
   case "snapshot":
     cmdProjectSnapshot();
     break;
+  case "planning-hygiene":
+  case "planning":
+    cmdPlanningHygiene();
+    break;
   case "doctor":
   case "health":
   case "health-check":
     cmdDoctor();
     break;
+  case "trust":
+  case "score":
+    cmdTrust();
+    break;
   case "flush":
   case "knowledge-flush":
     cmdFlush();