qualia-framework 5.9.1 → 6.1.0

package/docs/archive/CHANGELOG-pre-v4.md

@@ -0,0 +1,855 @@
+# CHANGELOG (pre-v4)
+
+Archive of v2.x and v3.x releases. Active changelog lives in [../../CHANGELOG.md](../../CHANGELOG.md) (v4.0.0 onward).
+
+## [3.7.0] — 2026-04-18
+
+Story-file plan format. Every phase plan task now carries inline rationale,
+acceptance criteria, explicit dependencies, and self-validation commands —
+so builders read plans as briefs and verifiers check against observable
+user behaviors, not just grep counts.
+
+### Added
+
+- **Story-file plan format** — `templates/plan.md` rewritten. Each task
+  block now mandates: `Wave`, `Files`, `Depends on` (explicit task refs
+  or `none`, not blank), `Why` (one-sentence motivation), `Acceptance
+  Criteria` (2-4 observable user behaviors), `Action`, `Validation` (1-3
+  grep/curl/tsc self-check commands), `Context`. Optional `Persona`
+  (security | architect | ux | frontend | backend | performance).
+- **Plan-summary dashboard** — new `node bin/qualia-ui.js plan-summary
+  <path>` command renders the plan as a terminal dashboard: phase goal,
+  waves, colored persona chips, dependency arrows, AC count, validation
+  count per task. `/qualia-plan` calls it automatically after the plan
+  is finalized.
+- **Verifier reads per-task Acceptance Criteria** — verifier now does a
+  3-layer check: phase-level Success Criteria + per-task AC + formal
+  Verification Contracts. Catches "files exist but user flow doesn't
+  work" cases that grep-only verification would miss.
+- **Builder reads rationale** — builder agent now reads `Why`, respects
+  `Depends on` (refuses to start before deps commit), runs `Validation`
+  commands before `git commit`.
+- **`ac_count` in validate-plan output** — `state.js validate-plan` now
+  reports AC anchor count alongside `done_when_count` and `contract_count`.
+
+### Changed
+
+- **`plan-checker` Rule 2** — expanded from 3 mandatory fields to the 7
+  story-file fields. Task without a `Why` or with vague AC now fails
+  validation.
+- **`plan-checker` Rule 3** — wave assignments now cross-check against
+  `Depends on` lines (Wave 2+ with `Depends on: none` is a contradiction).
+- **`state.js` plan preconditions** — accepts either `**Done when:**`
+  (legacy) or `**Acceptance Criteria:**` (new) as the per-task anchor,
+  so in-flight projects with older plans don't break on upgrade.
+
+### Backward compatibility
+
+Fully additive. Plans written before v3.7.0 (with `**Done when:**` only)
+continue to pass state.js precondition checks. New plans generated by
+the v3.7.0 planner use the story-file format with `**Acceptance
+Criteria:**`. No migration required.
+
+## [3.6.0] — 2026-04-17
+
+P2 cleanup release. Schema reconciliation with the ERP, log retention,
+and remaining state-machine polish from the audit. Third release of the
+night, after v3.4.2 (P0 hotfix) and v3.5.0 (P1 hardening).
+
+### Added
+
+- **`tracking.json` schema additions** — new fields:
+  - `team_id`, `project_id` — stable identifiers for ERP dedupe
+    (composite `(team_id, project_id)` is the canonical project key,
+    surviving directory renames)
+  - `git_remote` — lets the ERP correlate tracking with the source repo
+  - `session_started_at`, `last_pushed_at` — distinct timestamps
+  - `build_count`, `deploy_count` — lifetime counters
+  - `submitted_by` — mirrored at the top level (was only in /qualia-report
+    payloads)
+  - `lifetime.last_closed_milestone` — sentinel for close-milestone
+    idempotency (introduced in v3.4.2)
+- **Log retention.** Trace files in `~/.claude/.qualia-traces/` older than
+  30 days are pruned on ~1% of writes. Heavy users no longer accumulate
+  unbounded MB/day.
+- 2 new tests covering schema additions and defensive lifetime hydrate.
+  Suite is now 150 tests, all green.
+
+### Fixed
+
+- **`polished` transition no longer mis-marks the roadmap.** Was setting
+  the LAST roadmap row to status `verified` regardless of which phase the
+  user polished. Now marks every passed phase as `polished`.
+- **`cmdInit` defensively hydrates partial lifetime objects.** If
+  `prevLife.lifetime` was missing keys (older tracking.json format), the
+  spread left `undefined`s that subsequent `+=` produced `NaN`. Defaults
+  layer underneath the spread so missing keys are 0, not NaN.
+
+### Changed
+
+- **`docs/erp-contract.md`** documents `gap_cycles` polymorphism (object
+  in tracking.json, number in `/api/v1/reports` payload — receivers must
+  accept both shapes) and adds the new v3.6+ fields to the request body
+  example and required-fields table.
+
+## [3.5.0] — 2026-04-17
+
+P1 hardening release. 9 hooks/scripts overhauled, false positives killed,
+false negatives caught, cross-platform robustness throughout. Companion to
+the v3.4.2 P0 hotfix shipped earlier today.
+
+### Fixed
+
+- **`branch-guard.js` refspec bypass.** Hook checked the *current* branch,
+  so EMPLOYEE could push `feature/x:main` from a feature branch and land on
+  main. Hook now parses `tool_input.command` from the Claude Code stdin
+  payload and rejects any refspec whose destination is `main` or `master`.
+  Block messages also routed to stderr (Claude Code surfaces stderr in
+  block reasons) and `shell: process.platform === "win32"` added to git
+  spawn for Windows reliability.
+- **`migration-guard.js` false positives.** SQL comments (`-- …` lines and
+  `/* … */` blocks) are now stripped before pattern matching, so
+  commented-out `DROP TABLE` calls no longer block. File-path regex
+  tightened from `migration|migrate|\.sql$` to
+  `(^|/)migrations?/` OR `\.sql$` — `MigrationModal.tsx` and `migrations.md`
+  no longer trigger scans. `CREATE TEMP TABLE` and partition tables exempt
+  from the RLS requirement.
+- **`migration-guard.js` false negatives.** New blockers: `ALTER TABLE …
+  DROP COLUMN`, `DROP DATABASE`, `DROP SCHEMA … CASCADE`, `UPDATE …` without
+  WHERE, `GRANT … TO PUBLIC`. Edit-tool calls now scan `old_string +
+  new_string + content` (was only new_string).
+- **`pre-deploy-gate.js` `service_role` scanner.** Tightened from literal
+  substring match to `\bservice_role` regex with per-line exemptions for
+  comments (`//`, `/*`, `*`), `process.env.SUPABASE_SERVICE_ROLE` reads,
+  and explicit `eslint-disable` allowlists. Walk now excludes `dist/`,
+  `out/`, `build/`, `coverage/`, `.next/`, `.vercel/`, `.turbo/` so
+  post-build artifacts don't slow the gate or false-positive on minified
+  output. Block messages routed to stderr.
+- **`auto-update.js` 24-hour blackout fixed.** Cache timestamp was written
+  *before* the npm version fetch — failed fetches suppressed re-checks for
+  24h. Now written only after successful fetch.
+- **`auto-update.js` no longer corrupts running sessions.** OWNER branch
+  used to spawn `npx qualia-framework@latest install` in the background,
+  which rewrote `~/.claude/settings.json` mid-session. Both OWNER and
+  EMPLOYEE now write the same notification file; user must explicitly run
+  `npx qualia-framework update` to actually upgrade.
+- **`pre-compact.js` silent commit failures.** Auto-commit ran with
+  `stdio: "ignore"` and could fail invisibly when user had pre-commit
+  hooks or commit signing → STATE.md not persisted before context
+  compaction → context loss. Commit now uses `--no-verify --no-gpg-sign
+  --author="Qualia Framework <bot@qualia.solutions>"` so it can't be
+  blocked by user hooks. Commit status traced for visibility.
+- **`statusline.js` 3-spawns-per-prompt.** Collapsed three separate `git`
+  invocations into a single `git status -b --porcelain=v1` call. Saves
+  ~300ms per cold prompt on Windows. Cache write is now atomic
+  (`tmp + rename`) so concurrent prompts can't produce corrupt cache.
+- **`state.js` CRLF tolerance.** Every `^Field:\s*(.+)$/m` regex is now
+  `(.+?)\r?$/m` so Windows editors saving STATE.md with CRLF don't leak
+  `\r` into captured `phase_name`, `status`, `assigned_to`.
+- **`cli.js cmdMigrate` no longer adds duplicate hooks.** Old check used
+  substring match against the absolute path; if home directory ever
+  changed, the OLD path didn't match the NEW path and `migrate` appended a
+  second entry. Now compares basenames, so `migrate` is idempotent
+  regardless of path changes.
+
+### Cleaned
+
+- **Skill agent path refs corrected.** `qualia-verify`, `qualia-build`
+  used `@agents/<name>.md` (relative to project cwd, broken from
+  `.planning/`). All skills now use `@~/.claude/agents/<name>.md`
+  consistently.
+- **`qualia-quick` description gained trigger phrases** so the smart
+  router actually fires it on natural-language requests.
+- **`qualia-map` skill uses `Agent(...)`** instead of legacy `Task(...)`,
+  matching framework convention everywhere else.
+- **`qualia-idk` skill removed.** Fully redundant — `qualia` (the router)
+  already lists "idk" as a trigger phrase.
+- **`templates/help.html` regenerated.** Now lists all 26 skills (was 17).
+  Grouped: Road, Phase Depth, Quality, Quick Paths, Knowledge, Session,
+  Navigation, Meta. Version pill bumped to v3.5.0.
+
+### Added
+
+- **GitHub Actions CI workflow.** `.github/workflows/test.yml` runs
+  `npm test` on Ubuntu + macOS + Windows × Node 18/20/22. Triggered on
+  every push and PR. 5-minute timeout per job. Tests are no longer
+  "local-only" — every commit is verified across the supported matrix.
+- 11 new tests covering refspec bypass (3), comment-stripped SQL,
+  ALTER TABLE DROP COLUMN, DROP DATABASE, UPDATE-without-WHERE, GRANT TO
+  PUBLIC, TEMP-table RLS exemption, MigrationModal.tsx bypass, CRLF
+  STATE.md parsing. Suite is now 148 tests, all green.
+
+## [3.4.2] — 2026-04-17
+
+P0 hotfix release. Closes 7 critical bugs surfaced by a deep audit.
+
+### Fixed
+
+- **`pre-push.js` stamp now actually reaches the remote.** Previously the hook
+  wrote `last_commit` + `last_updated` to `tracking.json` and `git add`-ed it,
+  but the push itself ran on a snapshot prepared before the hook — so the
+  stamp never made it onto the wire. The ERP, which reads `tracking.json`
+  straight from git, saw stale data forever. Hook now creates a real bot
+  commit (`--no-verify --no-gpg-sign --author="Qualia Framework <bot@…>"`)
+  so the stamp ships with the push that triggered it.
+- **`session-start.js` no longer silently fails on first run.** `TEAL`,
+  `RESET`, `DIM` ANSI constants were referenced in the no-project welcome
+  branch but never defined in the file (only in `bin/install.js`). The outer
+  `try/catch` swallowed the `ReferenceError`, so new users saw a blank
+  session. Constants now defined at top of file.
+- **`/qualia-optimize` works on fresh installs.** Skill spawned
+  `frontend-agent`, `backend-agent`, `performance-oracle`,
+  `architecture-strategist` — none of which ship with the framework.
+  Rewritten to use `general-purpose` with the same specialized prompts.
+- **`.qualia-config.json` is now mode 0600.** Previously written with default
+  0644, so any local user could edit `role` to `OWNER` and bypass
+  `branch-guard`. The role bit is now access-restricted.
+- **Default ERP key no longer shipped.** Installs no longer write the
+  hardcoded literal `"qualia-claude-2026"`. New sources, in order:
+  `$QUALIA_ERP_KEY` env var → existing `~/.claude/.erp-api-key` →
+  ERP disabled until configured. Also chmods existing key file to 0600.
+- **Atomic file writes for `STATE.md` and `tracking.json`.** Previous
+  direct `writeFileSync` could leave half-written files on SIGINT, OOM, or
+  AV scanner interruption — the next `cmdCheck` would return `NO_PROJECT`.
+  All writes now go through `tmp + rename` (atomic on POSIX, near-atomic
+  on NTFS). Added `.planning/.state.lock` exclusive lockfile so two
+  concurrent state.js mutations can't race.
+- **`close-milestone` is now idempotent.** Sentinel `last_closed_milestone`
+  prevents re-running from double-counting `milestones_completed` and
+  `total_phases`. Pass `--force` to deliberately re-close.
+- **`backfill-lifetime` no longer destroys history.** Now uses `Math.max`
+  instead of overwrite — recomputed values from the current milestone's
+  STATE.md cannot reduce lifetime counters that were already accumulated
+  by `close-milestone`.
+
+### Added
+
+- **`init` refuses to clobber an existing project.** `state.js init` against
+  an active `.planning/STATE.md` now errors with `ALREADY_INITIALIZED`.
+  Pass `--force` to re-initialize (lifetime is still preserved).
+- **`_trace` signature normalized to 3 args** — `_trace(event, result, data)`.
+  Old call sites passing the result string in the data slot produced
+  malformed JSONL. Telemetry is now well-formed.
+- 8 new tests covering the fixes — pre-push behavioral mutation +
+  bot-commit, init guard, close-milestone idempotency, backfill Math.max,
+  atomic write cleanup, lock release. Suite is now 137 tests, all green.
+
+### Migration
+
+- Existing installs will pick up the fixes via auto-update or
+  `npx qualia-framework@latest install`.
+- The `qualia-claude-2026` shared key is grandfathered server-side for 30
+  days. After that, every employee needs a per-user token.
+- `init --force` is required to re-initialize an existing project (was
+  silent before — a footgun).
+
+## [3.4.1] — 2026-04-14
+
+### Added
+
+- **`state.js backfill-lifetime` command** — reconstructs lifetime counters from
+  STATE.md roadmap + plan files for existing projects upgrading from pre-v3.4.0.
+  Idempotent and safe to run multiple times. Use after updating to sync historical data.
+- 2 new tests for backfill (53 state tests, 129 total).
+
+## [3.4.0] — 2026-04-14
+
+ERP tracking was systematically wrong — milestone transitions destroyed all
+historical data, phase advances reset task counts, quick/task work was never
+counted. This release adds lifetime counters that survive every reset.
+
+### Added
+
+- **`lifetime` object in tracking.json** — `tasks_completed`, `phases_completed`,
+  `milestones_completed`, `total_phases`. These counters accumulate and NEVER
+  reset on init or phase advance. The ERP can now see the real total.
+- **`milestone` field in tracking.json** — current milestone number (1-indexed),
+  survives across `state.js init` calls.
+- **`state.js close-milestone` command** — snapshots the closing milestone's data
+  into lifetime before init resets current-phase fields.
+- **`--tasks-done N` on note/activity transitions** — `/qualia-quick` and
+  `/qualia-task` now increment `lifetime.tasks_completed` by 1 per invocation.
+- **`cmdCheck()` includes milestone + lifetime** in JSON output for ERP/statusline.
+- **tracking.json archived during milestone closeout** — previously only STATE.md
+  and ROADMAP.md were archived.
+- 12 new tests covering lifetime preservation, cross-phase accumulation,
+  close-milestone, backward compat. Suite is now 51 state tests, 129 total.
+
+### Fixed
+
+- **`state.js init` no longer destroys historical data.** It now reads the existing
+  tracking.json and preserves `milestone` and `lifetime` fields. Current-phase
+  fields still reset as expected.
+- **`verified(pass)` accumulates before resetting.** Task counts are added to
+  `lifetime.tasks_completed` and `lifetime.phases_completed` BEFORE `tasks_done`
+  resets to 0. The last phase of a milestone also counts (accumulation moved
+  outside the auto-advance conditional).
+- **`/qualia-report` endpoint fixed.** Was posting multipart to
+  `/api/claude/report-upload`; now sends structured JSON to `/api/v1/reports`
+  matching the ERP contract, including milestone + lifetime data.
+- Test 38 updated: `--force` bypasses `INVALID_PLAN` (matches v3.3.2 behavior).
+
+### Changed
+
+- `templates/tracking.json` includes `milestone` and `lifetime` fields.
+- `docs/erp-contract.md` documents the new fields in request/response schemas.
+- `skills/qualia-milestone/SKILL.md` calls `close-milestone` before `init`.
+
+## [3.3.2] — 2026-04-13
+
+Patch release. `state.js transition --force` now bypasses `INVALID_PLAN`
+errors so retroactive bookkeeping works.
+
+### Fixed
+
+- **`state.js transition --to planned --force` now unblocks retroactive
+  documentation.** When a phase is built without `/qualia-plan` (e.g. an
+  employee shipped the work before the framework was wired up), the
+  retroactive plan file is documentation, not a runnable plan — so it
+  often lacks `**Done when:**` markers. Previously `--force` only
+  bypassed status-ordering errors and still hard-failed on
+  `INVALID_PLAN`, leaving STATE.md stuck behind reality. `--force` now
+  also bypasses `INVALID_PLAN`. It still refuses `MISSING_FILE` /
+  `MISSING_ARG` — those would point the state machine at nothing.
+- New test: `--force bypasses INVALID_PLAN (retroactive bookkeeping)`,
+  plus a sanity test that `--force` still rejects `MISSING_FILE`.
+  Suite is now 129 tests, all green.
+
+## [3.3.1] — 2026-04-13
+
+Patch release. Fixes broken `@path` references inside the v3.3.0 deep-flow
+skills that were caught by post-release verification. Subagent spawning
+itself was unaffected (resolves via frontmatter `name:`), but the literal
+`Read your role: @~/.claude/agents/qualia-{name}.md` instruction passed
+into the spawned agent's prompt would fail to resolve the file because
+agents ship without the `qualia-` prefix (e.g. `researcher.md`, not
+`qualia-researcher.md`).
+
+### Fixed
+
+- `skills/qualia-new/SKILL.md` — 6 refs rewritten (4× researcher,
+  1× research-synthesizer, 1× roadmapper).
+- `skills/qualia-plan/SKILL.md` — 3 refs rewritten (2× planner,
+  1× plan-checker).
+- `skills/qualia-research/SKILL.md` — 1 researcher ref rewritten.
+- `skills/qualia-milestone/SKILL.md` — 1 roadmapper ref rewritten.
+- `skills/qualia-optimize/SKILL.md` — removed dead call to
+  `~/.claude/qualia-framework/bin/qualia-tools.js` (never shipped in v3.x);
+  replaced with a plain `git add && git commit`.
+
+All 128 tests still green.
+
+## [3.3.0] — 2026-04-13
+
+Deep flow release. Adds the comprehensive v2.6-era capabilities (research, plan-check,
+requirements traceability, roadmap generation) back into the v3 architecture — ~2k
+lines total instead of the v2.6 55k bloat. Same command surface for end users. No
+migration needed — existing projects keep working.
+
+### Added
+
+- **`/qualia-new` comprehensive flow** — now runs deep questioning → 4 parallel
+  research agents → requirements with REQ-IDs → ROADMAP.md with phases → approval
+  gate. The 323-line wizard is replaced by a structured pipeline. Still ships with
+  `--quick` flag for trivial projects.
+- **`/qualia-plan` plan-checker loop** — planner output is now validated by a
+  plan-checker agent against 7 rules (task specificity, wave assignment, contract
+  coverage, etc.). Up to 3 revision cycles. `--skip-check` flag available for
+  emergencies.
+- **4 new skills:**
+  - `/qualia-discuss {N}` — capture locked decisions before planning a phase
+  - `/qualia-research {N}` — deep research for a niche phase (Context7/WebFetch/WebSearch)
+  - `/qualia-map` — brownfield codebase mapping (4 parallel scanners)
+  - `/qualia-milestone` — close current milestone, open next
+- **4 new agents:**
+  - `qualia-researcher` — single researcher agent invoked 4× in parallel with a
+    `<dimension>` arg (stack/features/architecture/pitfalls). No more 4 duplicate
+    agent files.
+  - `qualia-research-synthesizer` — merges 4 research outputs into SUMMARY.md
+  - `qualia-roadmapper` — produces REQUIREMENTS.md + ROADMAP.md from PROJECT.md
+    + research synthesis
+  - `qualia-plan-checker` — validates plans against 7 rules
+- **New templates** in `~/.claude/qualia-templates/`:
+  - `requirements.md` — REQ-ID traceability format
+  - `roadmap.md` — phase structure with REQ mapping
+  - `phase-context.md` — output shape for `/qualia-discuss`
+  - `research-project/STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md, SUMMARY.md`
+  - `projects/website.md, ai-agent.md, voice-agent.md, mobile-app.md` — per-type
+    phase templates
+- **New references directory** `~/.claude/qualia-references/`:
+  - `questioning.md` — the methodology guide loaded by `/qualia-new` during the
+    questioning stage
+- **`install.js` recursive template copy** — templates/ now supports nested
+  directories (projects/, research-project/) via a new `copyTree` helper.
+- **`install.js` legacy cleanup** — automatically removes orphaned v2.6 install
+  cruft from `~/.claude/qualia-framework/` and any broken `~/.claude/agents/qualia-*.md`
+  files that reference the old `/home/qualia/` paths. Runs on upgrade.
+
+### Changed
+
+- **`/qualia-new` replaces the 323-line inline wizard** with a structured 14-step
+  process that delegates research/requirements/roadmap generation to specialized
+  agents. Still feels the same to the user — same banner, same question style,
+  same terminal output — but the backing logic is comprehensive instead of flat.
+- **`/qualia-plan` adds the plan-checker revision loop** by default. Existing
+  behavior (single planner call) is available via `--skip-check`.
+- **ROADMAP.md is now first-class.** v3.0 → v3.2.1 didn't create ROADMAP.md; this
+  release does. The ERP sync parser can now read structured roadmap data instead
+  of falling back to STATE.md table parsing.
+
+### Compatibility
+
+- **Existing v3.2.1 projects:** continue to work unchanged. The new features are
+  only triggered for newly-initialized projects.
+- **v3.2.1 skill flow:** same command names, same aesthetics, same statusline.
+- **Statusline:** unchanged (`state.js` still writes the same `phase`,
+  `total_phases`, `status` fields to `tracking.json`).
+
+### Philosophy
+
+The v2.6 framework was 55k lines because it duplicated bash boilerplate across
+30 workflow files and built mega-agents (43KB planner alone). This release ports
+the *concepts* (research, plan-check, requirements, roadmap) into the v3
+architecture (small focused agents, inline skills, single state tool). Total
+added: ~2k lines. Philosophy preserved: skills orchestrate, agents focus.
+
+## [3.2.1] — 2026-04-12
+
+Patch release. Republishes the v3.2.0 feature set on top of the committed
+main branch. The original v3.2.0 was published from an uncommitted working
+tree earlier in the day and then rebased onto `origin/main` during cleanup;
+this release captures the post-rebase state — correct `repository.url`,
+fixed test assertions (hook count 8 → 7), and minor comment tweaks.
+
+No behavior changes from v3.2.0 for end users.
+
+## [3.2.0] — 2026-04-12
+
+Sticky update notifications for employees, env access unblocked for the whole
+team, new `/qualia-optimize` deep optimization skill.
+
+### Added
+- **Sticky update banner** for EMPLOYEE installs. When `auto-update.js` detects
+  a newer version on npm, it writes `.qualia-update-available.json` instead of
+  auto-installing. `session-start.js` renders a visible banner every session
+  until the employee runs `npx qualia-framework@latest install`. OWNER still
+  auto-updates silently — never sees the banner.
+- **`qualia-optimize`** skill — deep optimization pass that reads `.planning/`
+  AND the codebase together. Spawns parallel specialists (frontend, backend,
+  performance, architecture). Modes: `full`, `--perf`, `--ui`, `--backend`,
+  `--alignment`, `--fix`.
+- `bin/qualia-ui.js` — new `update <current> <latest>` command renders the
+  sticky banner.
+- `bin/install.js` — new `DEPRECATED_HOOKS` cleanup list proactively removes
+  retired hooks from existing installs during upgrade.
+
+### Changed
+- `hooks/auto-update.js` now branches on `cfg.role`. OWNER gets the silent
+  background install (unchanged). EMPLOYEE writes the sticky notification so
+  they can no longer ignore updates by accident.
+
+### Removed
+- **`hooks/block-env-edit.js`** — team decision. Claude now has full read/write
+  on `.env*` files across the team. `install.js` no longer wires this hook and
+  `DEPRECATED_HOOKS` purges it from existing installs on upgrade.
+- Employee role descriptions updated — no longer claim "cannot edit .env files".
+
+## [3.1.0] — 2026-04-12
+
+Package rename and gap closure release. The package is now `qualia-framework`
+(dropping the `-v2` suffix). Adds settings migration, skill outcome scoring,
+analytics, cross-platform tests, and fills all v3.0.0 gaps.
+
+### Changed
+- **Package renamed** `qualia-framework-v2` → `qualia-framework`. All CLI
+  commands are now `qualia-framework install`, `qualia-framework update`, etc.
+  The old name continues to work via npm alias.
+
+### Added
+- **`qualia-framework migrate`** — upgrades v2 settings to v3 without
+  reinstalling. Wires missing hooks, env vars, status line, and MCP config.
+- **`qualia-framework analytics`** — aggregates hook telemetry and shows
+  first-pass verification rate, gap cycles, per-hook breakdown.
+- **Skill outcome scoring** — state transitions now write trace entries to
+  `~/.claude/.qualia-traces/` for plan→outcome correlation tracking.
+- **Verification contract format validation** — `validate-plan` now checks
+  contract structure (check-type, command, expected, fail-if fields) with
+  warnings for invalid types or missing fields. Backward compatible.
+- **next-devtools-mcp integration** — install and migrate now configure
+  `next-devtools-mcp@0.3.10` as an MCP server for runtime error visibility
+  in Next.js 16+ projects.
+- **Cross-platform Node.js test runner** — 134 tests using `node:test`,
+  replacing bash-only test scripts. Works on Fedora, EndeavourOS, Windows.
+- **ERP API contract documentation** — `docs/erp-contract.md` specifying
+  endpoints, auth, request/response shapes, rate limits, and security.
+
+### Fixed
+- Contract validation regex in `validate-plan` — section extraction was
+  always returning empty due to `$` matching end-of-line in multiline mode.
+
+## [3.0.0] — 2026-04-11
+
+Harness engineering release. Applies lessons from Anthropic's "Harness Design
+for Long-Running Apps" article. The verifier becomes a scored evaluator, the
+planner generates verification contracts, guards get smarter, and the harness
+gains observability.
+
+### Added
+- **Scored evaluator rubric** — verifier now scores on 4 dimensions
+  (Correctness, Completeness, Wiring, Quality), each 1-5. Hard threshold:
+  any score < 3 = FAIL. Two few-shot calibration examples included.
+- **Verification contracts** — planner generates testable contract entries
+  (`file-exists`, `grep-match`, `command-exit`, `behavioral`) per task.
+  Verifier executes contracts before ad-hoc verification.
+- **Plan content validation** — `state.js` now rejects plans with no task
+  headers or missing "Done when" criteria. New `validate-plan` subcommand.
+- **Configurable gap cycle limit** — default remains 2; override via
+  `tracking.json.gap_cycle_limit` or `PROJECT.md gap_cycle_limit:` field.
+- **Pre-deploy gate: Server Component detection** — `route.ts`,
+  `middleware.ts`, `app/api/` paths, and `"use server"` directive files are
+  now exempt from the service_role leak scan.
+- **Dynamic team management** — `qualia-framework team list|add|remove`
+  CLI commands. Team dict externalized to `~/.claude/.qualia-team.json`;
+  falls back to embedded defaults.
+- **ERP decoupling** — ERP config (`enabled`, `url`, `api_key_file`) stored
+  in `.qualia-config.json`. `/qualia-report` skips upload when disabled.
+- **Hook telemetry** — all 8 hooks write JSONL traces to
+  `~/.claude/.qualia-traces/YYYY-MM-DD.jsonl`. New `traces` CLI command
+  shows recent hook activity.
+- **Build recovery tags** — `/qualia-build` creates `pre-build-phase-{N}`
+  git tag before execution. `--force` flag on `state.js transition` enables
+  state recovery after failed builds.
+- **Knowledge base dedup** — `/qualia-learn` checks for existing entries
+  before appending. Entries now include UUID and ISO timestamp.
+- New tests for deploy gate, state machine, and guard hooks.
+  Total: 152 tests passing (50 hooks + 40 state + 48 bin + 14 statusline).
+
+### Fixed
+- **block-env-edit + branch-guard hooks not wired** — both hooks were
+  copied during install but never registered in `settings.json`. Employees
+  could push to main and edit `.env` files unchecked. Now registered in
+  `PreToolUse` hooks.
+- **Auto-update background script broken** — detached child script used
+  `return` at top level in `node -e`, which is a SyntaxError. The entire
+  update check silently failed every time. Replaced with `process.exit(0)`.
+- **branch-guard exit code** — used `exit(1)` (hook error) instead of
+  `exit(2)` (clean block). Now consistent with block-env-edit and
+  migration-guard.
+- Install summary hardcoded "Hooks: 6" despite installing 8. Fixed.
+- Duplicate `statusline.js` copy in installer removed.
+
+### Changed
+- `agents/verifier.md` — complete rewrite of the Scoring section into a
+  structured 4-criterion rubric with calibration examples and contract
+  verification workflow.
+- `agents/planner.md` — new Verification Contracts section with contract
+  format, types, and rules.
+- `templates/plan.md` — includes Verification Contract section.
+- `bin/state.js` — `getGapCycleLimit()`, `cmdValidatePlan()`, `--force`
+  flag, `gap_cycle_limit` in check output, plan content validation in
+  preconditions.
+- `bin/install.js` — `CLAUDE_DIR`/`FRAMEWORK_DIR` moved above `loadTeam()`;
+  team dict externalized via `loadTeam()`; ERP config in `.qualia-config.json`.
+- `bin/cli.js` — `team`, `traces` commands; uninstall cleans team file and
+  traces dir; updated help text.
+- `bin/qualia-ui.js` — gap cycle display uses dynamic limit from state.
+- `hooks/pre-deploy-gate.js` — 4 new server-side file exemptions.
+- `skills/qualia-verify/SKILL.md` — spawn prompt references contracts.
+- `skills/qualia-report/SKILL.md` — config-driven ERP upload.
+- `skills/qualia-build/SKILL.md` — recovery point step before execution.
+- `skills/qualia-learn/SKILL.md` — dedup check, UUID+timestamp format.
+
+## [2.10.0] — 2026-04-11
+
+Modern icon system, statusline context indicators.
+
+### Added
+- Statusline now shows memory count (`⊙`), hooks count (`⚙`), and skills count (`✦`) on the top bar.
+- Each Qualia action has a unique, meaningful glyph: `⬢` router, `✦` new, `▣` plan, `⚙` build,
+  `◎` verify, `✧` polish, `△` ship, `⇢` handoff, `▤` report, `⊘` debug, `⊙` learn,
+  `⏸` pause, `▶` resume, `⊛` review, `◈` design, `⚡` quick, `▪` task, `⟐` gaps.
+
+### Changed
+- Replaced all `◆` diamond glyphs with `⬢` hexagon (Qualia brand mark) across all files:
+  qualia-ui.js, statusline.js, install.js, cli.js, hooks, and skill documentation.
+- Updated utility glyphs: spawn (`⬡`), wave (`»`), next (`⟶`), banner separator (`▸`).
+- Spinner tips and hook status messages now use `⬢` prefix.
+
+## [2.9.0] — 2026-04-11
+
+Housekeeping, test coverage, and release hygiene.
+
+### Added
+- GitHub Actions CI workflow — runs the full test suite on every push and PR.
+- Behavioral test suites for `bin/cli.js`, `bin/install.js`, `bin/qualia-ui.js`,
+  `bin/statusline.js`, and the `pre-deploy-gate` / `branch-guard` hooks.
+- `CHANGELOG.md` — this file. Backfilled from commit history.
+- `npx qualia-framework uninstall` — clean, surgical removal of the framework
+  from `~/.claude/`. Supports `--yes` / `-y` for scripted use. Preserves
+  user-customized `CLAUDE.md` and non-Qualia entries in `settings.json`.
+  Optionally preserves the knowledge base (default Yes).
+- Seeded knowledge base content — `learned-patterns.md` and `common-fixes.md`
+  now ship with real entries harvested from v2.7–v2.8 work, so new installs
+  have something to learn from immediately instead of empty stubs.
+
+### Changed
+- `bin/cli.js` version check: `execSync("npm view ... 2>/dev/null")` → `spawnSync`
+  with argv. Removes the last bash-only redirect from the CLI, matching the
+  cross-platform pattern established in v2.8.0.
+- `STATE.md` parser hardened against edge cases (missing sections, malformed
+  phase headers, non-ASCII phase names).
+- `README.md` — adds a Changelog section and documents the `uninstall` command.
+
+## [2.8.1] — 2026-04-10
+
+Small patch release. Dogfood-driven: caught while installing v2.8.0 on a real
+machine immediately after publishing — typing `QS-FAWZI-O1` (letter O) instead
+of `QS-FAWZI-01` (digit zero) was rejected by the exact-match TEAM lookup.
+
+### Added
+- `resolveTeamCode(input)` helper in `bin/install.js`. Normalizes case, trims
+  whitespace, and replaces letter `O` → digit `0` in the numeric suffix only
+  (after the last dash).
+- Invalid-code error message now echoes the code the user typed and adds a tip
+  about the `O` vs `0` convention.
+
+### Fixed
+- Install codes with letter `O` in the numeric suffix (`QS-FAWZI-O1`) are now
+  tolerated and normalized to the canonical form.
+- `package.json` `repository.url` and `homepage` corrected from the
+  hyphenated `qualia-solutions` owner to the real CamelCase `Qualiasolutions`
+  GitHub org. npm had been silently auto-normalizing on publish but the
+  metadata was still wrong.
+- Critical constraint: the O→0 normalization only touches the segment after
+  the last dash, so `QS-MOAYAD-03` (real `O` in the name) is preserved.
+  Verified against 13 test cases including the adversarial `qs-moayad-O3`.
+
+## [2.8.0] — 2026-04-10
+
+Cross-platform hardening, real test coverage for the state machine, and a
+pure-Node status line. Closes 6 audit findings in one pass. Windows, macOS,
+and Linux all get a more honest, more tested, more portable framework.
+
+### Added
+- `bin/statusline.js` — pure Node status line (~200 lines, zero deps). Same
+  teal palette and 2-line layout as the previous bash version. Uses
+  `os.tmpdir()` with a per-user cache filename instead of hardcoded `/tmp`.
+- `tests/state.test.sh` — 22 behavioral tests covering `cmdInit`, `cmdCheck`,
+  every `VALID_FROM` transition, every precondition failure mode
+  (`PRECONDITION_FAILED`, `MISSING_FILE`, `MISSING_ARG`, `INVALID_STATUS`),
+  the gap-cycle circuit breaker (1 → 2 → blocked → reset on pass), and
+  special note/activity transitions.
+- `package.json` `test` script now runs both the hooks and state suites.
+  Total: 56 tests (34 hooks + 22 state), all passing.
+
+### Changed
+- `bin/qualia-ui.js` `readState`: `execSync` shell string → `spawnSync` argv.
+  Fixes the Windows banner when the username has spaces and removes the
+  bash-only `2>/dev/null` redirect.
+- `bin/cli.js` `cmdUpdate`: replaced bash `<<<` here-string with `spawnSync`
+  + `input:`. Manual `npx qualia-framework update` now works on Windows
+  and on Debian/Ubuntu (where `/bin/sh` is `dash`, which also lacks `<<<`).
+- `skills/qualia-skill-new/SKILL.md` — removed 5 hardcoded
+  `/home/qualia/Projects/...` paths in favor of `${FRAMEWORK_DIR}` detection
+  (env var → git origin check → ask user). The skill no longer violates its
+  own anti-patterns section.
+- `bin/install.js` wires the status line as `node ~/.claude/bin/statusline.js`
+  instead of shelling out to bash. Scripts count updated 2 → 3 in the
+  install summary.
+- README truthfulness pass: "3 rules" → "4 rules"; "auto-loaded by skills"
+  → "loaded by /qualia-plan, /qualia-debug, /qualia-new" (only those skills
+  actually cat the knowledge files); "No Git Bash, no WSL, no bash dependency"
+  claim rescoped to be accurate (hooks and status line are pure Node; skills
+  run through Claude Code's own Bash tool); "Production-Grade Hooks" bullet
+  now says "All 8 hooks" instead of leaving the count ambiguous.
+
+### Fixed
+- Windows session-start banner now shows phase/status even when the user's
+  path contains spaces.
+- Manual `update` command no longer fails silently on Windows or Debian/Ubuntu.
+- The `qualia-skill-new` skill no longer embeds developer-specific absolute
+  paths into generated skills.
+
+### Removed
+- `bin/statusline.sh` — replaced by `bin/statusline.js`. "Every hook and the
+  status line are pure Node.js" is now a claim the framework actually keeps.
+- `SubagentStart` echo hook from `install.js` — cosmetic-only, and it shipped
+  broken output on Windows cmd.exe due to literal single quotes.
+- Undocumented `settings.effortLevel = "high"` no-op from `install.js`.
+
+## [2.7.0] — 2026-04-10
+
+Every hook is now pure Node.js with zero shell dependencies. Works identically
+on Windows 10/11, macOS, and Linux. The only runtime requirement is Node.js
+18+, which was already required for `state.js`, `qualia-ui.js`, and the
+installer itself. Motivation: the previous `.sh` hooks required bash in PATH,
+which on Windows means Git Bash — an extra install most team members don't
+have. Windows team members had been running the framework with silently
+broken hooks for weeks.
+
+### Added
+- 8 pure-Node hooks: `session-start.js`, `auto-update.js`, `branch-guard.js`,
+  `block-env-edit.js`, `migration-guard.js`, `pre-push.js`, `pre-compact.js`,
+  `pre-deploy-gate.js`.
+- `tests/hooks.test.sh` now exercises `.js` hooks via stdin-piped JSON input,
+  including a Windows-path test case (`C:\project\.env.local` should block).
+- 34/34 hook tests passing (up from 21).
+
+### Changed
+- `install.js` writes hook commands as `node "<absolute-path>"` in
+  `settings.json`, avoiding any bash/Git Bash requirement on Windows.
+- `install.js` deletes orphaned `.sh` files from `~/.claude/hooks/` before
+  copying `.js` hooks (clean upgrade path for existing v2.5/v2.6 installs).
+- `chmod 755` on `.js` files (no-op on Windows, harmless).
+- `block-env-edit.js` normalizes Windows backslashes in file paths.
+- `pre-deploy-gate.js` uses a Node directory walker — no `grep -r`, no `find`.
+
+### Fixed
+- Relative `HOOKS_DIR` bug that broke tests after `cd` into subshells.
+
+### Removed
+- All 8 `.sh` hook files. Replaced 1:1 with `.js` equivalents.
+
+## [2.6.1] — 2026-04-09
+
+### Fixed
+- `session-start.js` hook never exits with a non-zero code. Previously, a
+  transient failure in the banner renderer could surface as a hard error on
+  session start, which felt broken even though nothing was actually wrong.
+
+## [2.6.0] — 2026-04-09
+
+### Added
+- `qa-browser` agent for browser-based verification.
+- `qualia-skill-new` skill — authoring tool for new skills and agents.
+- `bin/qualia-ui.js` cosmetics library — consistent banners across every
+  skill with a shared teal palette and layout.
+- Memory activation: framework now participates in Claude Code's memory
+  system instead of opting out.
+
+### Fixed
+- Deploy gate false positives reduced.
+
+## [2.5.0] — 2026-04-08
+
+### Added
+- `auto-update.js` hook — daily silent update in a detached subprocess so
+  teams stay on the current version without manual `update` calls.
+- Design best practices baked into the entire build pipeline (planner,
+  builder, verifier, and the design rules).
+
+### Changed
+- Quality gates are now role-aware: OWNER bypasses env/branch/sudo
+  restrictions; EMPLOYEE is held to the original rules.
+
+### Fixed
+- `/qualia-report` ERP upload path and API key setup flow in the installer.
+
+## [2.4.0] — 2026-04-08
+
+### Added
+- `version` and `update` CLI commands (`npx qualia-framework version`,
+  `npx qualia-framework update`).
+- Knowledge system: `~/.claude/knowledge/` with `learned-patterns.md`,
+  `common-fixes.md`, `client-prefs.md`.
+- `/qualia-learn` skill for capturing patterns, fixes, and client prefs to
+  the knowledge base.
+
+## [2.3.0] — 2026-04-08
+
+### Added
+- `bin/state.js` state machine — validates preconditions, updates `STATE.md`
+  and `tracking.json` atomically, tracks gap-closure cycles.
+- Smart router (`/qualia`) that reads project state and tells you the exact
+  next command.
+- `/qualia-idk` as an alias for the smart router.
+
+### Changed
+- All 10 skills replaced manual `STATE.md` / `tracking.json` updates with
+  `state.js` calls.
+- `/qualia-report` rewritten to drop DOCX generation and raw `curl` usage.
+
+### Fixed
+- Report generation pipeline.
+
+## [2.2.0] — 2026-04-08
+
+### Added
+- Ports of 6 skills from v1: `/qualia-idk`, `/qualia-design`, `/qualia-debug`,
+  `/qualia-review`, `/qualia-pause`, `/qualia-resume`.
+- `pre-push` hook rewritten to Node.js.
+- `state.js` install step added to the installer.
+- `gap_cycles` counter added to the `tracking.json` template.
+
+## [2.1.2] — 2026-04-08
+
+### Added
+- Install codes for Rama and Sally (team expansion).
+
+## [2.1.1] — 2026-04-07
+
+Safeguards release, incorporating lessons from the v1 code review.
+
+### Added
+- Task validation at plan-time.
+- Stub detection in the verifier (flags `// TODO` and placeholder-only files).
+- Scope discipline checks.
+- Explicit deviation criteria.
+- Routing clarity improvements in `/qualia`.
+- Gap-closure documentation.
+- Hook tests (first pass).
+
+## [2.1.0] — 2026-04-07
+
+### Added
+- Full agent wiring: planner, builder, verifier — each in an isolated
+  subagent context.
+- Full hook system (first production-grade pass).
+- Install codes and role-based access control (OWNER vs EMPLOYEE).
+
+### Changed
+- README rewritten with architecture rationale and accurate counts.
+
+## [2.0.0] — 2026-04-07
+
+Initial v2 release. Framework rewrite with agent wiring, full hook system,
+and install codes.
+
+### Added
+- Initial `qualia-framework` repo with full hook system and agent wiring.
+- Core skills, agents, hooks, rules, and templates.
+- `bin/install.js` and `bin/cli.js` installer / CLI.
+
+[Unreleased]: https://github.com/Qualiasolutions/qualia-framework/compare/v4.0.3...HEAD
+[4.0.3]: https://github.com/Qualiasolutions/qualia-framework/compare/v4.0.2...v4.0.3
+[4.0.2]: https://github.com/Qualiasolutions/qualia-framework/compare/v4.0.1...v4.0.2
+[4.0.1]: https://github.com/Qualiasolutions/qualia-framework/compare/v4.0.0...v4.0.1
+[4.0.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.7.0...v4.0.0
+[3.7.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.6.0...v3.7.0
+[3.6.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.5.0...v3.6.0
+[3.5.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.4.2...v3.5.0
+[3.4.2]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.4.1...v3.4.2
+[3.4.1]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.4.0...v3.4.1
+[3.4.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.3.2...v3.4.0
+[3.3.2]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.3.1...v3.3.2
+[3.3.1]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.3.0...v3.3.1
+[3.3.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.2.1...v3.3.0
+[3.2.1]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.2.0...v3.2.1
+[3.2.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.1.0...v3.2.0
+[3.1.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v3.0.0...v3.1.0
+[3.0.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.10.0...v3.0.0
+[2.10.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.9.0...v2.10.0
+[2.9.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.8.1...v2.9.0
+[2.8.1]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.8.0...v2.8.1
+[2.8.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.7.0...v2.8.0
+[2.7.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.6.1...v2.7.0
+[2.6.1]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.6.0...v2.6.1
+[2.6.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.5.0...v2.6.0
+[2.5.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.4.0...v2.5.0
+[2.4.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.3.0...v2.4.0
+[2.3.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.1.2...v2.2.0
+[2.1.2]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.1.1...v2.1.2
+[2.1.1]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/Qualiasolutions/qualia-framework/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/Qualiasolutions/qualia-framework/releases/tag/v2.0.0