qualia-framework 5.9.1 → 6.2.7

package/docs/ecosystem-operating-model.md

@@ -0,0 +1,121 @@
+# Qualia Ecosystem Operating Model
+
+The three systems have different jobs:
+
+| Layer | System | Owns |
+|---|---|---|
+| Execution | Qualia Framework | Planning, building, verifying, shipping, handoff, and reporting inside a project repo. |
+| Knowledge | Qualia Memory | Lessons, client preferences, recurring mistakes, durable research, and reusable patterns. |
+| Operations | Qualia ERP | Live clients, projects, assignments, milestones, reports, invoices, payments, schedules, dashboards, and client portal state. |
+
+Short version: **Framework builds. Memory remembers. ERP operates.**
+
+## Boundaries
+
+- Framework `.planning/` is execution state for agents and local reporting.
+- ERP is the operational source of truth for admin and employee visibility.
+- Memory stores durable knowledge, not live operational status.
+- Read.ai and meeting tools are inputs, not a fourth source of truth.
+
+## Safe Flows
+
+### ERP to Framework
+
+ERP can provide a work packet before a session starts:
+
+```text
+ERP project context
+  -> templates/work-packet.md
+  -> Claude/Codex session
+  -> Framework command
+  -> plan/build/verify/report
+```
+
+The work packet should include project/client IDs, current milestone, open blockers, latest report, assigned employee, approved work, and guardrails. It should not silently change Framework state; the agent still uses `state.js` and `.planning/` for execution.
+
+### Framework to ERP
+
+Framework reports through `/qualia-report`:
+
+```text
+Framework session
+  -> .planning/reports/report-YYYY-MM-DD.md
+  -> POST /api/v1/reports
+  -> ERP session report and admin dashboard
+```
+
+This is the primary sync. It is explicit, idempotent, and employee-visible.
+
+Framework can also export a project-level snapshot for admin visibility:
+
+```text
+qualia-framework project-snapshot --write
+  -> .planning/snapshots/project-snapshot-*.json
+  -> ERP imports current 0-to-100 progress as a draft/project telemetry record
+```
+
+Or, when ERP credentials are configured:
+
+```text
+qualia-framework project-snapshot --upload
+  -> POST /api/v1/project-snapshots
+  -> ERP updates the canonical project's latest Framework progress metadata
+```
+
+The snapshot is not a replacement for `/qualia-report`; it is the project-level rollup. It carries shared IDs, current milestone/phase, closed milestones, lifetime counters, deployment counters, and a progress percentage so ERP/admin views can show where a project stands without guessing from names or scraping local files.
+
+### Framework Planning Snapshots to ERP
+
+If ERP wants `.planning/JOURNEY.md`, `ROADMAP.md`, `STATE.md`, or `tracking.json`, use an explicit import/snapshot workflow. Do not depend on passive git scraping or hook-created bot commits.
+
+Acceptable future contract:
+
+```text
+Framework creates a planning snapshot
+  -> .planning/snapshots/project-snapshot-*.json
+  -> or POST /api/v1/project-snapshots
+  -> GitHub or API upload
+  -> ERP imports phases/items as draft operational records
+  -> human or approved automation confirms client-visible changes
+```
+
+Framework tasks remain internal execution units. ERP assignments, deadlines, and client-visible statuses remain ERP-owned.
+
+### Framework to Memory
+
+Framework promotes durable lessons through `/qualia-learn`, `/qualia-postmortem`, or the knowledge flush:
+
+```text
+session report / postmortem / lesson
+  -> Memory raw note
+  -> wiki concept, client preference, or project lesson
+  -> future recall before planning
+```
+
+### Memory to Framework and ERP
+
+Memory can provide context and draft suggestions. It must not directly override ERP operational state.
+
+```text
+Memory context
+  -> draft or planning context
+  -> human/approved automation confirms
+  -> ERP update or Framework execution
+```
+
+## Shared Identifiers
+
+Use these wherever available:
+
+| Identifier | Meaning |
+|---|---|
+| `project_id` | Stable Framework/project key, safe across folder renames. |
+| `erp_project_id` | ERP canonical project UUID. |
+| `client_id` | ERP/client canonical UUID. |
+| `team_id` | Qualia/team identity. |
+| `workspace_id` | Tenant/workspace UUID. |
+| `git_remote` | Repository correlation key. |
+| `framework_version` | Framework version that produced a report. |
+| `client_report_id` | Per-project report sequence such as `QS-REPORT-03`. |
+
+The less these systems guess from names, the cleaner admin tracking becomes.

package/docs/erp-contract.md

@@ -15,7 +15,7 @@ Phase and task counters remain framework telemetry. They help agents plan/build/
 
 ## Configuration
 
-Stored in `~/.claude/.qualia-config.json`:
+Stored in the active install home, either `~/.claude/.qualia-config.json` or `~/.codex/.qualia-config.json`:
 
 ```json
 {
@@ -27,7 +27,7 @@ Stored in `~/.claude/.qualia-config.json`:
 }
 ```
 
-The API key is read from `~/.claude/.erp-api-key` (file mode 0600).
+The API key is read from `.erp-api-key` in the same install home (file mode 0600).
 
 ## Endpoints
 
@@ -54,7 +54,10 @@ below).
 {
   "project": "client-project-name",
   "project_id": "qs-acme-portal",
+  "erp_project_id": "7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef",
+  "client_id": "5f5a8d8e-8c58-4c30-9b76-13a08f0d0d8a",
   "team_id": "qualia-solutions",
+  "workspace_id": "2af02a2d-6f1f-4d43-a6cb-6a1e7e09ac43",
   "git_remote": "github.com/QualiasolutionsCY/acme-portal",
   "client": "Client Name",
   "client_report_id": "QS-REPORT-03",
@@ -97,8 +100,7 @@ below).
 }
 ```
 
-**`gap_cycles` polymorphism (v3.5+):** in `tracking.json` (the file the ERP
-reads from git for passive monitoring) `gap_cycles` is an OBJECT keyed by
+**`gap_cycles` polymorphism (v3.5+):** in local `tracking.json`, `gap_cycles` is an OBJECT keyed by
 phase number — `{"1": 0, "2": 1}`. In the POST `/api/v1/reports` body,
 `/qualia-report` flattens to a NUMBER for the current phase. Receivers must
 accept both shapes: if object, use `gap_cycles[String(phase)] || 0`.
@@ -171,42 +173,90 @@ Authorization: Bearer <api-key>
 }
 ```
 
-### GET /api/v1/tracking/:project
+## Project Snapshot Export
 
-Retrieve current tracking state (same shape as tracking.json).
+`qualia-framework project-snapshot --write` creates a local project-level rollup at:
 
-**Headers:**
+```text
+.planning/snapshots/project-snapshot-YYYY-MM-DDTHH-MM-SS-sssZ.json
 ```
+
+This is the explicit Framework -> ERP import artifact for admin/project dashboards. It is separate from `/qualia-report`: reports describe one work session; snapshots describe where the project stands from kickoff to handoff.
+
+`qualia-framework project-snapshot --upload` sends the same JSON to ERP:
+
+```http
+POST /api/v1/project-snapshots
 Authorization: Bearer <api-key>
+Content-Type: application/json
 ```
 
-**Response (200 OK):**
+ERP resolves `identifiers.erp_project_id` first, then falls back to repo/name matching. A successful import stores the latest snapshot and `framework_progress_percent` on the canonical ERP project's metadata so project dashboards can show current Framework progress.
+
+Snapshot shape:
+
 ```json
 {
-  "ok": true,
-  "tracking": {
-    "project": "client-project-name",
+  "snapshot_version": 1,
+  "generated_at": "2026-05-21T00:00:00.000Z",
+  "source": "qualia-framework",
+  "framework_version": "6.2.6",
+  "identifiers": {
+    "project_id": "qs-acme-portal",
+    "team_id": "qualia-solutions",
+    "git_remote": "github.com/QualiasolutionsCY/acme-portal",
+    "erp_project_id": "7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef",
+    "client_id": "5f5a8d8e-8c58-4c30-9b76-13a08f0d0d8a"
+  },
+  "project": {
+    "name": "acme-portal",
+    "client": "Acme",
+    "status": "built",
+    "deployed_url": "https://client.vercel.app",
+    "progress_percent": 42
+  },
+  "current": {
     "milestone": 2,
+    "milestone_name": "Product",
     "phase": 2,
+    "phase_name": "Dashboard",
     "total_phases": 4,
-    "status": "built",
-    "last_updated": "2026-04-12T14:30:00Z",
-    "lifetime": {
-      "tasks_completed": 23,
-      "phases_completed": 8,
-      "milestones_completed": 1,
-      "total_phases": 8
-    }
+    "tasks_done": 3,
+    "tasks_total": 5,
+    "verification": "pending",
+    "gap_cycles": 1
+  },
+  "journey": {
+    "total_milestones": 3,
+    "milestones": [
+      { "num": 1, "name": "Foundation", "status": "closed" },
+      { "num": 2, "name": "Product", "status": "active" },
+      { "num": 3, "name": "Handoff", "status": "pending" }
+    ],
+    "closed_milestones": []
+  },
+  "lifetime": {
+    "tasks_completed": 12,
+    "phases_completed": 4,
+    "milestones_completed": 1,
+    "total_phases": 4,
+    "last_closed_milestone": 1,
+    "build_count": 4,
+    "deploy_count": 1
   }
 }
 ```
 
 ## Behavior
 
-- When `erp.enabled` is `false`, `/qualia-report` skips the upload silently.
+- When `erp.enabled` is `false`, `/qualia-report` skips the upload and prints an info line so the employee knows the report stayed local.
 - When the API key file is missing or empty, the upload is skipped with a warning.
 - Network failures are non-blocking — the report is saved locally regardless.
-- The ERP reads `tracking.json` directly from git for real-time status (no API call needed for passive monitoring).
+- `tracking.json` is **local-only** telemetry as of v6.2 (2026-05-20). Pre-v6.2
+  the pre-push hook bot-committed it on every push so the ERP could read it
+  from GitHub. That consumer was documented here but never actually implemented
+  on the ERP side; the bot commits were pollution. The ERP gets all state from
+  `/qualia-report` POSTs to `/api/v1/reports` — which is sufficient.
 - Reports are append-only — no PUT/PATCH/DELETE endpoints exist for
   external callers. Internal idempotent UPSERT on `(project_id,
   client_report_id)` retries is the one exception (see "Idempotent UPSERT
@@ -239,6 +289,9 @@ Authorization: Bearer <api-key>
 | lifetime | object | recommended | Cumulative counters — tasks_completed, phases_completed, milestones_completed, total_phases, last_closed_milestone |
 | project_id | string | recommended (v3.6+) | Stable per-project identifier — preferred dedupe key over `project` slug. Survives directory renames. |
 | team_id | string | recommended (v3.6+) | Installation's team identifier. Composite `(team_id, project_id)` is the canonical project key. |
+| erp_project_id | UUID string | optional | ERP's canonical project UUID when known. Strongest direct link for admin dashboards; `/qualia-report` only sends UUID-shaped values. |
+| client_id | UUID string | optional | ERP/client canonical UUID when known. Lets reports attach to the client without guessing from a display name; slug-like values are omitted to avoid ERP validation failures. |
+| workspace_id | UUID string | optional | Workspace/tenant scope for multi-company or multi-team installs; only UUID-shaped values are sent. |
 | git_remote | string | optional (v3.6+) | e.g. `github.com/QualiasolutionsCY/foo`. Lets the ERP correlate tracking with the source repo. |
 | session_started_at | string | optional (v3.6+) | ISO 8601 — when the current Claude Code session began. |
 | last_pushed_at | string | optional (v3.6+) | ISO 8601 — distinct from `last_updated` (which fires on local writes too). |

package/docs/onboarding.html

@@ -295,7 +295,7 @@
 
   <header class="marque">
     <span class="mark">Qualia Framework</span>
-    <span class="meta">For Moayad &amp; new hires · v5.5</span>
+    <span class="meta">For Moayad &amp; new hires · v6.0</span>
   </header>
 
   <section class="hero">
@@ -612,7 +612,7 @@
   </section>
 
   <footer>
-    <span>Qualia Framework v5.5.0 · Plan, build, verify, ship.</span>
+    <span>Qualia Framework v6.2.7 · Plan, build, verify, ship.</span>
     <span><a href="https://github.com/Qualiasolutions/qualia-framework">github.com/Qualiasolutions/qualia-framework</a></span>
   </footer>
 

package/docs/release.md

@@ -0,0 +1,44 @@
+# Release Verification
+
+Use this when the repo is ready but `npx qualia-framework@latest install` still needs proof.
+
+## Pre-Publish
+
+Run from the release branch before merging:
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+`npm test` proves the source tree and packaged tarball install path. `npm pack --dry-run` proves the files that will be shipped.
+
+## Publish
+
+Publish only from the versioned main commit:
+
+```bash
+npm whoami
+npm publish --access public
+npm view qualia-framework version
+```
+
+The final command must print the same version as `package.json`.
+
+## Post-Publish
+
+After npm `latest` matches the repo, run:
+
+```bash
+npm run test:published-install
+```
+
+This smoke uses an isolated `HOME` and npm cache, runs `npx --yes qualia-framework@latest install`, selects target `Both`, and verifies:
+
+- Claude `CLAUDE.md` is installed with the OWNER role.
+- Codex `AGENTS.md`, `hooks.json`, `agents/*.toml`, `bin/`, `skills/`, `rules/`, templates, and knowledge files are installed with the OWNER role.
+- Role placeholders are gone.
+- The installed hook set is the current 11-hook set with no `pre-compact.js`.
+- The installed `.qualia-config.json` version matches `package.json`.
+
+If this fails because npm latest is behind, the framework is not publicly revived yet even if local tests pass.

package/docs/reviews/v6.2.1-revival-audit.md

@@ -0,0 +1,53 @@
+# Qualia Framework Revival Audit - 2026-05-21
+
+Scope: current `qualia-framework` worktree moving from `package.json` version `6.2.0` to `6.2.1`, with emphasis on silent failures, dead references, ERP/report truth, Codex and Claude Code compatibility, token discipline, and the "0 to hero" project road.
+
+## Evidence Collected
+
+- `npm test` passed all 9 suites after the package-install smoke test was added.
+- `bash tests/refs.test.sh` passed after adding stale-surface guards: 25 checks, 0 failed.
+- `bash tests/skills.test.sh` passed: 168 checks, 0 failed.
+- `bash tests/install-smoke.test.sh` passed: 7 checks, 0 failed.
+- `npm pack --dry-run` succeeded after the version bump and showed `qualia-framework@6.2.1`, 144 package files, 466.7 kB package size, 1.5 MB unpacked.
+- `npm view qualia-framework version` returned `6.1.0`; local package is now `6.2.1`. This means `npx qualia-framework@latest install` does not yet install the local v6.2 contract.
+
+## External 2026 Check
+
+- Claude Code skills are live-discovered from `~/.claude/skills/`, project `.claude/skills/`, and parent directories; supporting files should be referenced from `SKILL.md` and loaded on demand. Current framework structure matches this pattern.
+- Claude Code hooks remain event-based and include `PreCompact`, but hooks are arbitrary commands and must be reviewed/tested. Removing Qualia's `pre-compact.js` bot commit is compatible because state durability belongs in `state.js`, not git history.
+- Claude Code subagents use separate context windows and should be used when repeated side work would flood the main context. Qualia's dedicated planner, builder, verifier, researcher, roadmapper, and QA agents still match this model.
+- Codex continues to treat `AGENTS.md` as the cross-agent project instruction surface. The framework's root `AGENTS.md` mirror is the right compatibility layer, but installed Codex behavior should be verified with a real `codex` session after publish.
+- MCP's 2026 direction emphasizes production readiness, security boundaries, and controlled user elicitation. Qualia should keep MCP use explicit and avoid tool servers asking for secrets through elicitation.
+
+Sources checked:
+- Claude Code skills: https://code.claude.com/docs/en/slash-commands
+- Claude Code hooks: https://code.claude.com/docs/en/hooks
+- Claude Code subagents: https://code.claude.com/docs/en/sub-agents
+- Codex AGENTS.md pointer: https://github.com/openai/codex/blob/main/docs/agents_md.md
+- AGENTS.md format: https://github.com/agentsmd/agents.md
+- MCP 2026 roadmap: https://blog.modelcontextprotocol.io/posts/2026-mcp-roadmap/
+- MCP elicitation: https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
+
+## Fixed In This Pass
+
+- README and onboarding version text now reflect `v6.2.0`, not `v6.0.0`.
+- README and guide now say 33 skills and include `/qualia-vibe`.
+- Active docs no longer claim the ERP passively reads `tracking.json` from git.
+- `/qualia-road`, `/qualia-milestone`, and `agents/roadmapper.md` now frame `tracking.json` as local/report telemetry instead of an ERP tree source.
+- `/qualia-verify` no longer repeats the old "silent PASS unless downgraded" wording for `INSUFFICIENT EVIDENCE`; it now states fail-closed behavior directly.
+- `/qualia-polish` no longer says optional Lighthouse/axe gates are skipped silently.
+- `tests/refs.test.sh` now fails on stale active-surface claims: passive ERP tracking, removed pre-compact guidance, stale skill count, stale README version, old `INSUFFICIENT EVIDENCE` wording, and silent optional gate language.
+- `tests/install-smoke.test.sh` now proves the packaged tarball can install into both Claude and Codex targets from an isolated HOME.
+
+## Current Verdict
+
+The core framework is functional and test-backed, but the public install path is not revived yet because npm latest is still `6.1.0` while this repo is `6.2.1`. Until a verified publish happens, employees using `npx qualia-framework@latest install` do not receive the no-bot-commit contract or the refreshed docs.
+
+## Remaining High-Leverage Work
+
+1. **Publish drift is the current release blocker.** After full tests, publish a patched release so `@latest` matches the repo. Evidence target: `npm view qualia-framework version` returns the new version.
+2. **Codex install verification should become a test.** The installer already writes `~/.codex/AGENTS.md`, but the next pass should add a non-interactive smoke test that verifies Codex-facing install output contains the role-filled root instructions and no `{{ROLE}}` placeholders.
+3. **Claude hook modernization should be explicit, not opportunistic.** Current Claude Code exposes newer hook events such as `PostToolUseFailure`, `PostToolBatch`, `InstructionsLoaded`, `SessionEnd`, and agent start/stop events. Qualia does not need to wire all of them, but a future phase should decide which are useful for employee/admin experience instead of drifting hook-by-hook.
+4. **ERP employee/admin experience should stay report-driven.** Framework telemetry should enrich `/qualia-report`; the ERP should not depend on git scraping internal `.planning` files. This keeps framework tasks internal and preserves the ERP as the oversight layer.
+5. **Skill count should not grow by default.** The 33-skill surface is already large. Prefer merging or tightening skills before adding new ones unless a new skill removes repeated work that cannot be handled by an existing command.
+6. **Token awareness should be measured in installed surfaces.** The next audit should report installed `CLAUDE.md`/`AGENTS.md` line count, skill description total size, and agent frontmatter count so "lightweight" is a measurable contract, not a claim.

package/docs/reviews/v6.2.2-memory-erp-audit.md

@@ -0,0 +1,41 @@
+# Qualia Framework Memory/ERP Audit - 2026-05-21
+
+Source reviewed: `/home/qualia-new/Downloads/qualia-framework-memory-erp-connection.md`.
+
+## Useful Model Adopted
+
+The note's core model is correct and now has a framework home:
+
+- Framework builds.
+- Memory remembers.
+- ERP operates.
+
+This became `docs/ecosystem-operating-model.md` so employees and admins have one clear boundary document instead of scattered assumptions.
+
+## Correction Applied
+
+The note says ERP can sync `.planning/` files from GitHub into project phases/items. That is acceptable only as an explicit import/snapshot workflow. It must not revive the old v6.1 passive `tracking.json` git-scrape story or hook-created bot commits.
+
+Current contract:
+
+- `/qualia-report` remains the primary Framework -> ERP sync.
+- `.planning` snapshots are allowed only through an explicit future import/API workflow.
+- ERP owns client-visible status, deadlines, assignments, payments, and dashboards.
+- Framework owns local execution state.
+- Memory owns durable knowledge, not live operational truth.
+
+## Changes Made
+
+- Added `docs/ecosystem-operating-model.md`.
+- Added `templates/work-packet.md` for ERP-approved session context.
+- Added optional `erp_project_id`, `client_id`, and `workspace_id` fields to `templates/tracking.json`.
+- Updated `bin/state.js` so those identifiers survive `state.js init` / re-init.
+- Updated `/qualia-report` payload construction to send those identifiers only when present.
+- Updated `docs/erp-contract.md` with the new optional fields.
+- Updated `/qualia-report` help text to use the safe piped `set-erp-key` command.
+
+## Remaining Work
+
+1. ERP backend should accept and store `erp_project_id`, `client_id`, and `workspace_id` if it does not already.
+2. ERP can generate `templates/work-packet.md` content or a JSON equivalent for agents.
+3. If planning snapshots are needed, define a real endpoint or import job with approval semantics. Do not depend on passive GitHub scraping.

package/docs/reviews/v6.2.3-erp-id-guard.md

@@ -0,0 +1,15 @@
+# Qualia Framework ERP ID Guard - 2026-05-21
+
+After the v6.2.2 Framework/Memory/ERP patch, the ERP route was checked directly in `/home/qualia-new/Projects/qualia-erp/app/api/v1/reports/route.ts`.
+
+Finding:
+
+- ERP `client_id` is validated as a UUID and stored as an FK to `clients`.
+- ERP already has an `erp_project_id` column and admin reporting reads it.
+- The v6.2.2 framework example used a slug-like `client_id` (`"acme"`) and `/qualia-report` would send any non-empty `client_id`.
+
+Fix:
+
+- `/qualia-report` now includes `erp_project_id`, `client_id`, and `workspace_id` only when values are UUID-shaped.
+- Docs now label those IDs as UUIDs.
+- `project_id` and `team_id` remain the slug/string identifiers for framework-level dedupe and reporting.

package/guide.md

@@ -1,9 +1,31 @@
-# Qualia Developer Guide (v5.8)
+# Qualia Developer Guide (v6.2.7)
 
 > Follow the road. Type the commands. The framework handles the rest.
 > `--auto` chains the whole road end-to-end with only two human checkpoints per project.
 
-**v5.8 cleans up the command surface:** `/qualia-polish-loop` is now `/qualia-polish --loop` (one flag instead of two skills). `/qualia-quick`, `/qualia-task`, and `/qualia-prd` are removed after their v5.7 deprecation window; use `/qualia-feature` for single-feature work and `/qualia-discuss` in PROJECT MODE for kickoff capture. Skill count goes from 35 to 32.
+**v6.2.7 is the Codex runtime compatibility patch.** Codex installs now get native `~/.codex/hooks.json`, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config in addition to `AGENTS.md`.
+
+**v6.2.5 carries forward.** `qualia-framework project-snapshot --write` creates a single `.planning/snapshots/project-snapshot-*.json` artifact with project identifiers, current milestone/phase, closed milestones, lifetime counters, and a project progress percentage for explicit ERP/admin import.
+
+**v6.2.4 carries forward.** The Framework -> ERP report payload now comes from the shipped and tested `report-payload.js` builder, so admin-visible report linking fields are covered by executable tests instead of only prompt prose.
+
+**v6.2.3 carries forward.** Framework slugs stay in `project_id`/`team_id`; ERP foreign-key identifiers (`erp_project_id`, `client_id`, `workspace_id`) are sent only when UUID-shaped, so reports do not fail validation because a local slug leaked into an ERP UUID field.
+
+**v6.2.2 carries forward.** Framework builds, Memory remembers, ERP operates. ERP work packets can seed Claude/Codex sessions, `/qualia-report` can carry ERP-native IDs, and release verification now has a public `@latest` install smoke.
+
+**v6.2.1 carries forward.** Active docs match the v6.2 no-bot-commit model, the explicit `/qualia-report` ERP contract, the current 33-skill surface, and fail-closed `INSUFFICIENT EVIDENCE` behavior. `tests/refs.test.sh` guards those claims.
+
+**v6.1.0 ships the design-pivot path you were missing.** New `/qualia-vibe` is fast aesthetic pivot (~3 min): swap design tokens, keep layout. Default proposes ONE direction per `rules/one-opinion.md` (the EventMaster discipline — never give the user a menu). Sub-modes: `--variants N` for the opt-in menu, `--extract URL` reverse-engineers DESIGN.md from a reference site, `--sync` shows code↔DESIGN.md drift and can patch DESIGN.md from code. Slop-detect grew banned fonts (Montserrat/Poppins/Lato/Open Sans) and a `--watch` flag for proactive single-file mode. Several design-surface bugs from v6.0 audit are fixed too (viewport mismatch, slop-detect path resolution in the polish loop, dead `/qualia-design` references, the bounce-easing token that contradicted design-laws).
+
+**v6.2.0 removes hook-created bot commits.** `pre-push.js` stamps local `tracking.json` telemetry but no longer commits it. `pre-compact.js` is gone because `state.js` already gives stronger crash safety with atomic writes plus a journal. ERP sync remains explicit through `/qualia-report` POSTs, not passive git scraping.
+
+**v5.9.2 carries forward.** `pre-push.js` self-gates against `branch-guard.js` so a blocked push no longer leaves an orphan bot commit. `qualia-report` ERP payload omits empty ISO datetime fields (avoids 422 from the ERP validator).
+
+**v5.9.1 carries forward.** `/qualia-new` opens with the Demo/Full/Quick project-shape gate via `AskUserQuestion`, then exactly one free-text pitch question, then a hard hand-off to `/qualia-discuss` for the structured interview (8 questions for demos, 14 for full projects).
+
+**v5.9.0 carries forward.** `tests/refs.test.sh` catches dead command references in user-facing surfaces on every release. `bin/erp-retry.js` is a real persistent retry queue for ERP report uploads. Four structured agents (verifier, plan-checker, roadmapper, qa-browser) run on Sonnet for ~40% per-phase cost cut, while builder/planner/researcher/visual-evaluator stay on Opus where the architectural and vision reasoning lives. The verifier downgrades to FAIL on any `INSUFFICIENT EVIDENCE` line.
+
+**Surface is 33 skills.** Use `/qualia-feature` for single-feature work and `/qualia-discuss` in PROJECT MODE for kickoff capture; `/qualia-polish --loop` for the autonomous visual loop; `/qualia-vibe` for fast layout-preserving aesthetic pivots.
 
 ## The Road
 
@@ -59,6 +81,9 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 | Single feature | `/qualia-feature` | Auto-scoped: inline for trivia, fresh spawn for 1-5 files |
 | Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick / loop) |
 | | `/qualia-polish --loop` | Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat |
+| Pivot the vibe | `/qualia-vibe` | Fast aesthetic pivot (~3 min): swap tokens, keep layout. Propose ONE direction. |
+| | `/qualia-vibe --extract <URL>` | Reverse-engineer DESIGN.md from a reference site |
+| | `/qualia-vibe --sync` | Show / patch drift between code (CSS vars + Tailwind) and DESIGN.md |
 | | `/qualia-ship` | Deploy to production |
 | | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
 | Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
@@ -119,7 +144,7 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 - **Story-file plans:** Every task has Why / Acceptance Criteria / Depends on / Validation inline — the plan IS the brief.
 - **Wave execution:** Independent tasks run in parallel. Dependent tasks wait.
 - **Milestone-boundary pauses:** In `--auto` mode, the framework pauses only at real decision points. Everything else runs on rails.
-- **tracking.json:** Updated on every push. The ERP reads it automatically. Includes `milestone_name` + `milestones[]` so the ERP can show project and milestone progress without exposing framework tasks as the main employee workflow.
+- **tracking.json:** Updated locally on push. It feeds local statusline, stop-session-log, and `/qualia-report`; the ERP receives explicit report uploads and does not passively scrape this file from git.
 
 ## Quick Reference
 

package/hooks/auto-update.js

@@ -10,16 +10,23 @@ const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
-const CLAUDE_DIR = path.join(os.homedir(), ".claude");
-const CACHE_FILE = path.join(CLAUDE_DIR, ".qualia-last-update-check");
-const CONFIG_FILE = path.join(CLAUDE_DIR, ".qualia-config.json");
-const LOCK_FILE = path.join(CLAUDE_DIR, ".qualia-updating");
-const NOTIF_FILE = path.join(CLAUDE_DIR, ".qualia-update-available.json");
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const CACHE_FILE = path.join(QUALIA_HOME, ".qualia-last-update-check");
+const CONFIG_FILE = path.join(QUALIA_HOME, ".qualia-config.json");
+const LOCK_FILE = path.join(QUALIA_HOME, ".qualia-updating");
+const NOTIF_FILE = path.join(QUALIA_HOME, ".qualia-update-available.json");
 const MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 function _trace(hookName, result, extra) {
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: hookName,
@@ -76,7 +83,9 @@ try {
       stdio: ["ignore", "pipe", "ignore"],
     });
     latest = ((r.stdout || "").trim());
-  } catch {}
+  } catch (e) {
+    _trace("auto-update", "npm-error", { error: e && e.message });
+  }
   try { fs.unlinkSync(LOCK_FILE); } catch {}
 
   if (!latest) {
@@ -109,7 +118,7 @@ try {
     // Invalidate the session-start health cache so the next session re-checks
     // whether new critical files shipped in the latest version are installed.
     try {
-      fs.unlinkSync(path.join(CLAUDE_DIR, ".qualia-install-health.json"));
+      fs.unlinkSync(path.join(QUALIA_HOME, ".qualia-install-health.json"));
     } catch {}
     _trace("auto-update", "allow", { reason: "notification-written", current: cfg.version, latest });
   } else {
@@ -117,8 +126,9 @@ try {
     try { fs.unlinkSync(NOTIF_FILE); } catch {}
     _trace("auto-update", "allow", { reason: "up-to-date", version: cfg.version });
   }
-} catch {
-  // Silent — never block the tool call
+} catch (e) {
+  // Never block the tool call, but leave a trace so failures are debuggable.
+  _trace("auto-update", "error", { error: e && e.message });
 }
 
 process.exit(0);

package/hooks/branch-guard.js

@@ -12,11 +12,19 @@ const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
-const CONFIG = path.join(os.homedir(), ".claude", ".qualia-config.json");
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const CONFIG = path.join(QUALIA_HOME, ".qualia-config.json");
 
 function _trace(hookName, result, extra) {
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: hookName,

package/hooks/env-empty-guard.js

@@ -9,9 +9,18 @@ const os = require("os");
 
 const _traceStart = Date.now();
 
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+
 function _trace(result, extra) {
   try {
-    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
       hook: "env-empty-guard", result,
@@ -30,10 +39,11 @@ try { if (!process.stdin.isTTY) payload = fs.readFileSync(0, "utf8"); } catch {}
 let command = "";
 try {
   if (payload) command = (JSON.parse(payload).tool_input || {}).command || "";
-} catch {
-  console.error("BLOCKED: env-empty-guard could not parse hook payload.");
-  _trace("block", { reason: "parse-error" });
-  process.exit(2);
+} catch (e) {
+  // Allow on parse error — this hook only cares about `vercel env` commands, and
+  // a malformed payload is not by itself a reason to block unrelated tool calls.
+  _trace("allow", { reason: "parse-error", error: e && e.message });
+  process.exit(0);
 }
 
 // Only act on vercel env commands.