qualia-framework 6.14.0 → 7.0.0

package/AGENTS.md

@@ -1,3 +1,5 @@
+<!-- GENERATED from templates/instructions.md by bin/compile-instructions.js — do not edit directly; edit the canonical source and recompile. -->
+
 # Qualia Framework
 
 Company: Qualia Solutions — Nicosia, Cyprus
@@ -8,17 +10,18 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 
 ## Hard rules (non-negotiable)
 - **Read before Write/Edit** — *every edit is informed by the current state of the file.*
-- **Feature branches only** — *changes ship through review; main is always deployable.*
-- **MVP first** — *build the minimum that demonstrates the goal.*
+- **Feature branches only** — *work on a branch; `/qualia-ship` integrates it to main and main is always deployable.*
+- **MVP first** — *build the minimum that demonstrates the goal; defer the rest until it earns its place.*
 - **Root cause on failures** — *understand the why before patching the symptom.*
 - **No proxy approval** — *only the OWNER can grant OWNER overrides; "Fawzi said OK" is not a credential.*
 
 ## Discoverable substrate (load on demand, not always)
-- `/qualia-road`, `FLAGS.md`, `guide.md` — every active command + flag (canonical surface)
+- `rules/constitution.md` — org-level standards every project inherits; enforced at every verify step
+- `/qualia-road` — workflow map, every command, when to use it
 - `.planning/CONTEXT.md` — project domain glossary (loaded by road agents)
 - `.planning/decisions/` — ADRs for hard-to-reverse decisions
-- `rules/security.md` `rules/deployment.md` `rules/infrastructure.md` `rules/architecture.md` — on relevant tasks only
-- `qualia-design/frontend.md` `qualia-design/design-laws.md` — on design/frontend tasks only
+- `rules/security.md` `rules/deployment.md` `rules/infrastructure.md` `rules/architecture.md` — read on relevant tasks only
+- `qualia-design/frontend.md` `qualia-design/design-laws.md` — read on design/frontend tasks only
 
 ## Lost?
 `/qualia` — state router tells you the next command.

package/CHANGELOG.md

@@ -8,6 +8,322 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [7.0.0] - 2026-06-22 (v7 — the restructure is complete)
+
+The v7 milestone release. The 6.12→6.29 line landed the whole v7 restructure
+brief; this marks it shipped. Highlights across the arc:
+
+- **v7.0 lifecycle** — build→operate, forced-handoff removed; the three missing
+  runtime primitives wired as deterministic gates: R1 file-disjointness pre-write
+  hook, R2 `.agent-status` fan-in barrier, R3 cross-artifact `/analyze` gate.
+- **v7.1 memory** — `/qualia-recall` (read side of `/qualia-learn`), a single
+  shared vault access-control module honoring `wiki/_meta/access.md` (enforced by
+  both recall and the read-only memory MCP), and `bin/repo-map.js` (R18).
+- **v7.2 verification** — the framework's OWN test surface is now gated in CI
+  (R6: `runner.js` joined `npm test`); R7 `/qualia-eval`, R8 verifier panel, R19
+  voice DoD confirmed.
+- **v7.3 codex-adapter** — CLAUDE.md + AGENTS.md from one source (R4); every
+  runtime-behavior branch routed through `host-adapters.js` (R5).
+- **Design + scale** — tunable design dials + ban→do-instead pre-flight (R9),
+  per-client token registry (R10), `/qualia-build --batch` migration lane (R20).
+- **ERP event integration (R14/R12)** — one signed, append-only `framework_events`
+  log: the framework signs and emits lifecycle events; the ERP verifies (HMAC
+  byte-matched across repos) and renders a live run-tree. Live in production.
+
+Test surface at release: 24 shell suites + 179 cross-platform node tests, both
+gated by `npm test`. No functional change in this bump — it tags the milestone.
+
+## [6.29.0] - 2026-06-22 (R14 client — the framework now emits signed events to the ERP)
+
+The ERP side of R14 (the `framework_events` table + `/api/v1/events` +
+`/api/v1/policy-events`) shipped in the `qualia-erp` repo and is live in
+production. This is the framework EMIT side that closes the loop.
+
+### Added — `bin/erp-event.js`: signed lifecycle-event emitter
+- Builds a `FrameworkEvent` envelope and queues it for `POST /api/v1/events`.
+  HMAC-SHA256 keyed by the install's `qlt_` token over `${id}.${timestamp}.${body}`
+  — **byte-identical** to the ERP's `lib/framework-events.ts` verifier (tested as
+  a cross-repo contract), so signatures verify with no extra secret. Headers
+  carry id/timestamp/signature (Standard-Webhooks shape); the event is the body.
+- Non-blocking + graceful: ERP disabled or no API key ⇒ silent no-op; unsigned
+  posts still authenticate via Bearer (recorded `signature_valid=false`).
+  `emit <action> [--target type:ref] [--project uuid] [--meta k=v] [--json]
+  [--dry-run]`, plus an `emitEvent()` export for in-process callers.
+
+### Changed
+- `bin/erp-retry.js`: the retry queue now carries optional per-item `headers`
+  (so the signed-event envelope rides the existing idempotent retry rails);
+  Auth/Content-* stay framework-owned and non-overridable.
+- `/qualia-verify`: emits `verify_pass` / `verify_fail` after the state
+  transition — the first live lifecycle signal into the ERP run-tree. Other
+  points (`session_started`, `phase_planned`, `build_wave_started`) documented.
+- `docs/erp-contract.md`: new "POST /api/v1/events" section (envelope, headers,
+  signing).
+- `tests/erp-event.test.sh` (14 cases incl. the cross-repo signature match);
+  run-all now **24 suites**, all green (+179 node).
+
+## [6.28.0] - 2026-06-22 (R20 — the migration lane for /qualia-build)
+
+### Added — `bin/batch-plan.js` + `/qualia-build --batch`
+- The wave model fits a phase; it doesn't fit a 50–500-file codemod. `--batch` is
+  a map-reduce over a flat file list: `batch-plan.js` splits it into
+  FILE-DISJOINT batches (each a worktree-isolated worker with tiny context that
+  opens its own commit) grouped into concurrency-capped waves, fanned in through
+  ONE staging branch. Deterministic split (dedup, complete, disjoint, waves ≤
+  max-workers); the orchestration lives in the skill.
+- `--from FILE`/stdin, `--batch-size`, `--max-workers`, `--staging`, `--json`.
+  Zero-dep. `/qualia-build --batch` documents the full orchestration (staging
+  branch → per-wave worktree workers → fan-in → test once → ship), including
+  "log any dropped batch — no silent partial migrations."
+- `tests/batch-plan.test.sh` (15); run-all now **23 suites**, all green (+179 node).
+
+## [6.27.0] - 2026-06-22 (R9 + R10 — design dials, ban→do-instead pre-flight, per-client token registry)
+
+Two framework-area design enhancements: steer generation away from slop upfront,
+and ground every builder in a real per-client design system.
+
+### Added — R9: tunable design dials + generation-time pre-flight
+- `qualia-design/design-dials.md`: DESIGN_VARIANCE / MOTION_INTENSITY /
+  VISUAL_DENSITY (LOW|MED|HIGH) with concrete mappings + register/project-type
+  gating, plus a ban→do-instead table mirroring slop-detect's rules WITH the
+  positive alternative (avoids the pink-elephant backfire). The generation-time
+  half of the anti-slop contract; slop-detect remains the post-hoc gate.
+- `templates/DESIGN.md` §0 declares the dials; `/qualia-polish` Stage 0 resolves
+  them and cites the bans before editing.
+
+### Added — R10: per-client design-token registry
+- `bin/design-tokens.js`: compiles a client brand spec (`design-tokens.json`)
+  into a CSS-variable registry (`tokens.css`). `/qualia-new` scaffolds it;
+  builders reference `var(--…)`, never a literal hex. The shadcn-registry
+  pattern — first-party brand data is the escape from design monoculture.
+- `tests/design-tokens.test.sh` (14) + the dials contract test in lib.test.sh;
+  run-all now **22 suites**, all green (+ 179 node).
+
+## [6.26.0] - 2026-06-22 (R18 — a cheap symbol map for brownfield onboarding)
+
+### Added — `bin/repo-map.js`, wired into `/qualia-map`
+- Aider's repo-map idea, in the framework's zero-dep idiom: a deterministic
+  symbol map of a codebase (top-level exports/functions/classes/types per file,
+  busiest files first) via language-aware regexes for JS/TS, Python, Go, Rust,
+  Ruby, Java, PHP. NO tree-sitter native dependency — the brief named tree-sitter
+  but that fights the framework's zero-dep posture; regex extraction gets the
+  "what's in this repo and where" signal at zero cost.
+- `/qualia-map` now runs it BEFORE the mapper agents (`repo-map.json`), so they
+  onboard from a structural index instead of reading the tree blind — cheaper,
+  better-grounded brownfield scans. `--json`, `--max-files`; skips
+  node_modules/dist/.git/etc.; exit 2 on bad dir. Registered in
+  runtime-manifest + lib install set; `tests/repo-map.test.sh` (14 cases).
+  run-all now **21 suites**.
+
+## [6.25.0] - 2026-06-21 (v7.3 codex-adapter — the last runtime branch moves into the seam)
+
+v7.3 is complete. R4 (emit AGENTS.md alongside CLAUDE.md from one canonical
+source) was already shipped via `bin/compile-instructions.js` — both files
+compile from `templates/instructions.md` through the host adapter, with a
+`--check` drift guard gated by the `instructions` suite. This release finishes R5.
+
+### Changed — R5: agent-CLI invocation is now an adapter fact (no more stray runtime branch)
+- `host-adapters.js` was already the real seam (declarative `HOSTS`, per-host
+  paths/naming/instruction-file). The one genuine `if (codex)` behavior branch
+  still living outside it was in `knowledge-flush.js`: it hardcoded
+  `codex`/`claude` as the CLI and `exec`/`-p` as the invocation. Those are
+  per-host FACTS — moved into the adapter: `agentCli` + `agentExecPrefix`
+  (declarative) → `adapter().agentExec(prompt)` (computed argv), plus
+  `hostForHome(home)` so the home→host mapping has one owner.
+- `knowledge-flush.js` now asks the adapter instead of branching. When a third
+  runtime arrives it's one `HOSTS` entry, not a grep-and-patch. lib.test.sh
+  covers the new facts.
+- Left intentionally: the `qualiaHome()` install-root idiom repeated across
+  bins/hooks treats both hosts IDENTICALLY (it's home resolution, not a behavior
+  branch) — sweeping 20 files for a no-op-difference helper is high-risk,
+  low-value, and would touch hot paths. Noted, not done.
+
+## [6.24.0] - 2026-06-21 (v7.2 verification — gate the framework's own test surface)
+
+v7.2 verification is complete. R7 (`/qualia-eval` lane), R8 (verify-panel +
+adversarial skeptics), and R19 (voice-agent archetype DoD) shipped earlier and
+are confirmed green. This release closes R6.
+
+### Fixed — R6: the framework's own checks can no longer silently regress
+- The cross-platform `tests/runner.js` harness (179 node:test cases, incl. the
+  memory-MCP suite) was **never run by `npm test`** — only the shell suite was.
+  That is exactly why it silently drifted to 21 failures: nothing ran it. Now
+  `npm test` runs BOTH (`test:shell && test:node`), so CI (`run: npm test`)
+  gates the full surface — 20 shell suites + 179 node tests. Added a `test:node`
+  script. Verified CI-safe (179/179 with an empty HOME, no install required).
+- This is R6's real intent for a deterministic/offline framework: a machine gate
+  on the framework's OWN checks. The LLM-prompt-level eval of skills is out of
+  scope for offline CI; `/qualia-eval` (R7) already provides that lane for the AI
+  artifacts projects build.
+
+## [6.23.0] - 2026-06-21 (v7.1 memory loop — recall, vault access control, harness health)
+
+Completes the v7.1 memory work: the read side now exists, the vault has real
+access control, and the cross-platform test harness is green again.
+
+### Added — `/qualia-recall` + `bin/recall.js`: the read side of memory
+- Kills the `/qualia-recall` ghost (referenced in `agents/researcher.md` and
+  `skills/qualia-research` but never built). `recall.js` unifies BOTH stores in
+  one ranked digest: the knowledge layer (delegates to `knowledge.js` so new
+  files stay discoverable) + the qualia-memory vault (grep over `wiki/`).
+  `--json`, `--scope all|knowledge|vault`, `--max`. Zero deps. Registered in
+  `command-surface` ACTIVE_SKILLS + `runtime-manifest`.
+
+### Added — vault access control (`bin/vault-access.js`, `rules/access.md`)
+- The vault's `wiki/_meta/access.md` manifest named `/qualia-recall` as an
+  enforcer, referenced an enforcing rule at `~/.claude/rules/access.md`, and
+  expected readers to honor OWNER_ONLY / CONDITIONAL paths — but **none of those
+  existed**. Now: `vault-access.js` is the single implementation (parse manifest,
+  resolve role, deny non-OWNER reads of OWNER_ONLY/CONDITIONAL paths,
+  fail-closed on unknown role); `rules/access.md` is the always-on enforcing
+  rule; **both** `recall.js` and the always-on memory MCP enforce it through that
+  one module so the security rule can't drift. No-manifest ⇒ no filtering (the
+  wiki is curated-by-design; sensitive stores live outside `wiki/`).
+
+### Fixed — test harness health
+- `tests/runner.js` (cross-platform node:test harness) had drifted to 154/21;
+  re-synced to current bin/hook contracts (MISSING_CONTRACT/evidence,
+  SUSPICIOUS_NAME, set-erp-key stdin, branch-guard v6.10 allowed+recorded) with
+  no assertions weakened. Now **179**, with the new memory-MCP access cases.
+- `tests/recall.test.sh` (18 cases) added; `run-all` now **20 suites**, all green.
+
+### Fixed — vault docs (qualia-memory repo)
+- `CLAUDE.md` named a non-existent `flush.py` for session capture (the real
+  mechanism is the claude-memory-compiler SessionEnd hook) and carried a stale
+  `/home/qualia-new/` path. Corrected. No framework write-back leg was built:
+  the vault's session loop is external and already exists; the framework's
+  knowledge tier is separate by design.
+
+## [6.22.0] - 2026-06-21 (session continuity + ERP project-sync — built by two parallel worktree agents)
+
+Two independent continuity features, built concurrently in isolated git worktrees and integrated together.
+
+### Added — B1: `/qualia` surfaces the latest session report at session start (`bin/last-report.js`)
+- Finds the newest `.planning/reports/report-*.md` (filename date desc, mtime tiebreak) and extracts a tight digest: `{ found, file, date, summary, next, age_days }` — summary from the report's `## What Was Done`, next-step from `## Next Steps`, markdown-flattened and capped. `--json`, `--cwd`, `--now ISO` (deterministic age); exit 0 found / 1 none / 2 bad input.
+- Wired into the `/qualia` router "Get State" step: when a project is loaded, the router prints the last-session digest at the TOP of its output, so the operator — or a teammate picking the project up — instantly sees where work was left off. `tests/last-report.test.sh` (28 assertions).
+
+### Added — B2: full project-sync reconciliation payload for the ERP (`bin/project-sync.js`)
+- A single deterministic snapshot the ERP can reconcile a whole project from: identity + lifecycle/launched_at, `milestones[]` (closed/current/future + per-milestone REQ-ID completion + phases/tasks/deployed_url), current position, `task_rollup`, `accountability` (offroad), `integration` (the trunk-merge model), and a `schema_version`. **Composes** `project-snapshot.js` (reuses its builders) rather than duplicating or bloating that stable endpoint. `--json`/`--write`/`--pretty`; read-only; graceful on missing JOURNEY/REQUIREMENTS. `tests/project-sync.test.sh` (38 assertions).
+- `docs/erp-contract.md`: new "Project Sync Payload" section — every field, the server-side reconciliation steps, and the PR/merge model (branch → main at ship → deploy; main-push accountability). Explicit **Framework-emits vs ERP-backend-ingests** split.
+- **Backend remains (out of this repo):** a `POST /api/v1/project-sync` endpoint + server reconciliation (upsert milestones by num, completion from REQ counts, roll up phases/tasks, store offroad, encode the merge model). The framework emits + documents; it does not POST yet (the ERP team mirrors `project-snapshot.js`'s upload plumbing once the endpoint exists).
+
+run-all now 19 suites; both bins in the manifest + install-set; all suites green.
+
+## [6.21.0] - 2026-06-21 (work-unit goals on both runtimes — Codex /goal + the Claude Code equivalent)
+
+Every defined unit of work should declare one objective + one budget, so it stays anchored and the operator sees burn-vs-budget. The framework had this for Codex (`/goal`) but `rules/codex-goal.md` explicitly told Claude Code to "skip — no equivalent surface." Claude Code DOES have an equivalent (the session task-list + turn budget); this wires it up and broadens goal-setting to every work-unit skill.
+
+### Changed — `rules/codex-goal.md` is now a both-runtimes "work-unit goal" rule
+- One shared helper (`codex-goal.js {scope}`, via the host-adapter-rendered `${QUALIA_BIN}`) produces the objective + token budget from STATE.md/ROADMAP.md.
+- **Codex** path unchanged: native `/goal` / `update_goal`.
+- **Claude Code** path (new): set the goal via the harness **task-list** (a tracked task titled with the objective, in_progress→completed) + state the budget in the banner. Same discipline — one named objective + budget per unit — native surface on each runtime.
+
+### Changed — goal-setting wired into every work-unit skill
+- Existing blocks in `/qualia-plan`, `/qualia-build`, `/qualia-feature` relabeled from "Codex goal (Codex runtime only)" to runtime-neutral **"Set the work-unit goal."**
+- Added to `/qualia-fix` (scope `quick`/`feature`) and `/qualia-update` (scope `feature` — it runs its own lean loop without `/qualia-plan`, so it needs its own goal). `/qualia-milestone` deliberately omitted — it routes into `/qualia-plan`, which sets the goal (no double-set).
+
+No bin or schema change; all 17 suites pass.
+
+## [6.20.0] - 2026-06-21 (scope integrity — the roadmap finishes the project, and the team can't drift off it)
+
+The deepest fix this cycle. Teams were drifting off-plan — inventing milestones, building features with no link to the roadmap — and the root cause was upstream: **`/qualia-new` under-scoped the project** (a v1 slice capped at 5 milestones, overflow dumped into an unplanned "v2"), so the agreed work literally wasn't in the arc and the team was *forced* to improvise. Two layers: make genesis cover the whole project, then bind the team to it. (Layer 1 shipped in the prior commit; this entry covers the full feature.)
+
+### Layer 1 — genesis covers the whole project (commit `feat(genesis)`)
+- **Interview reworked** (`templates/project-discovery.md`): added §9 **capability inventory** (every capability needed for DONE — the whole thing) + §10 **whole-project definition-of-done**; dropped the old §9 "stop at 3–5 chapters" self-cap. Full path 14 → 15 questions, refocused from brand-vibe to functional completeness.
+- **Milestone cap removed** (`agents/roadmapper.md`, `templates/journey.md`, `templates/requirements.md`): the arc spans until the §9 inventory reaches the §10 done-state — as many milestones as needed. `Post-Handoff`/`Out of Scope` holds ONLY explicit client deferrals (§8), never overflow. Handoff optional for internal/ongoing products.
+- **Coverage gate** (`/qualia-new` Step 14): genesis refuses to present a journey that leaves any §9 capability unmapped (0 unmapped before the approval ladder).
+
+### Layer 2 — bind the team to the arc (this commit)
+- **Milestone close gates on requirements** (`bin/state.js`): new `MILESTONE_REQS_INCOMPLETE` — close refuses (strict) / warns (standard) when a REQ-ID mapped to the milestone in REQUIREMENTS.md isn't `Complete`. Stops "finishing a milestone with scope still open". New `state.js reqs-check [--milestone N]` exposes the same check (exit 0/1) for `/qualia-milestone` to show coverage before closing.
+- **Off-road work is recorded, not silent** (`bin/state.js` note path): `transition --to note` gains `--scope in|off --ref {REQ/why}`. Off-road work increments `lifetime.offroad_count` and appends to an `offroad[]` ledger (OWNER + ERP visible), mirroring branch-guard's accountability model.
+- **`/qualia-feature` + `/qualia-fix` scope gate**: before building, both check the active milestone. In-scope → proceed, tagged `--scope in`. Off-road → **strict blocks** (route to `/qualia-scope`/`/qualia-milestone` to fold it into the arc) / **standard records** (`--scope off`, counted). The drift vector the user named is now governed at the source.
+
+### Tests
+- `tests/state.test.sh`: +5 cases — `reqs-check` (complete/incomplete/milestone-filter/untracked), `--scope off` tally + ledger, `--scope in` no-op, `--force` bypass. 96 state assertions green; all 17 suites pass. (Genesis is prose/templates — validated by the skills + refs suites.)
+
+## [6.19.0] - 2026-06-21 (trunk integration — ship is the merge point, report sweeps)
+
+Fixes a real lifecycle gap + doc drift: **no skill ever integrated feature → main.** Branches/PRs accumulated with nothing closing them; `/qualia-ship` deployed *from the feature branch* and said "never push to main," so production ran branch code while `main` lagged ("main is always deployable" was false in practice); and three sources disagreed on the policy (the hard rule said "through review", `branch-guard` 6.10 said "accountability not block", `infrastructure.md` still claimed PR-review was enforced). This completes the 6.10 "accountability over block" turn into a coherent trunk model.
+
+### Changed — `/qualia-ship` integrates to main, deploys from main, closes the branch
+- New §3: commit → fast-forward-integrate the feature branch into `main` (auto-rebase if `main` moved; STOP on conflict) → push. `branch-guard` records the main push (accountability). §4 deploys from `main` HEAD, so the deployed artifact == `main` byte-for-byte. New §4b deletes the integrated branch on a verified deploy. The normal path now leaves **zero lingering branches/PRs**.
+
+### Added — `bin/branch-hygiene.js` + `/qualia-report` sweep (the safety net)
+- `branch-hygiene.js`: read-only clock-out sweep — finds local branches with commits **ahead of `main` that were never shipped** (stranded work) and **stale open PRs** (best-effort via `gh`, skipped when absent). Exit 0 clean / 1 found / 2 not-a-repo; `--json`; library `analyze`. Detects `main` or `master` as base.
+- `/qualia-report` Step 5b runs it so stranded work surfaces to the employee + OWNER at clock-out instead of rotting.
+
+### Fixed — policy drift now single-voiced
+- `rules/infrastructure.md`: the stale "main requires PR reviews (enforced by guards)" line replaced with the real model (integrate-at-ship; main pushes allowed + recorded; report sweeps; keep GitHub branch protection off, or switch ship to an auto-merged PR if you re-enable it).
+- Canonical hard rule (`templates/instructions.md` → recompiled `CLAUDE.md`/`AGENTS.md`): "ship through review" → "`/qualia-ship` integrates it to main." Drift guard green.
+
+### Tests
+- `tests/branch-hygiene.test.sh` (new, 13 cases): not-a-repo, clean, stranded branch (ahead count + json), ff-merged-no-longer-stranded, `master` base detection, `analyze()` lib. run-all now 17 suites; manifest + `lib.test.sh` install set updated.
+
+## [6.18.0] - 2026-06-21 (v7 kernel, step 8 — R7: /qualia-eval lane for AI features)
+
+Qualia gates UI and code — `contract-runner` proves the code exists, `verify-panel` proves it's correct — but it had **no gate for the AI artifacts a project builds**. "The chatbot answers the refund question" / "the RAG answer is grounded" / "the agent stays under 2s" is not checkable by a grep. R7 adds the equivalent gate, layered: cheap deterministic assertions first, model judgment only where a model is required.
+
+### Added — `bin/eval-runner.js` (layered assertion runner, zero-dependency)
+- Runs an eval suite (JSON — no YAML parser pulled in) of cases against captured AI outputs. **Deterministic assertion types** settled with no model: `contains`, `not_contains`, `equals`, `regex`, `not_regex`, `min_length`, `max_length`, `json_valid`, `json_path` (`equals`/`contains`), `max_latency_ms`, `max_cost_usd`. Outputs inline or via `output_file`.
+- **`llm_rubric`** is the only model-dependent type — it carries a `verdict` (pass|fail) the skill fills by spawning a judge BEFORE the runner (same pattern `verify-panel` uses for skeptic votes). An unjudged rubric is PENDING and **fails** the suite — never a silent pass. Asserting a latency/cost budget with no metric recorded also fails (no silent pass).
+- Exit 0 = all cases pass, 1 = failure/unjudged, 2 = bad input. `--write` emits `.planning/evals/eval-{feature}.json`. Library exports `run`, `runAssertion`, `getPath`.
+
+### Added — `/qualia-eval` skill (new active surface)
+- The lane: capture the AI feature's real outputs → spawn one judge per `llm_rubric` (reusing the `qualia-verifier` agent, role-anchored) → `eval-runner.js` settles deterministic assertions + folds in verdicts → gate. Usable standalone (`/qualia-eval suite.json`) or as a phase verify-step gate (`/qualia-eval {N}`), where a FAIL has the same standing as a failing contract. Registered in `command-surface.js` `ACTIVE_SKILLS`.
+
+### Tests
+- `tests/eval-runner.test.sh` (new, 19 cases): deterministic pass/fail, latency budget (incl. missing-metric → fail), `json_valid`/`json_path`, `llm_rubric` pass/fail/pending, `output_file` resolution + graceful missing-file, `--write` artifact, `runAssertion`/`getPath` units, malformed→exit 2. run-all now 16 suites; manifest + `lib.test.sh` install set updated; `qualia-eval` passes the skill smoke + refs suites.
+
+## [6.17.0] - 2026-06-21 (v7 kernel, step 7 — R16: dependency-derived wave width + --parallel knob)
+
+`/qualia-build` spawned EVERY task in a contract "wave" concurrently, with no cap — two failure modes at once: over-serialization (the planner's hand-numbered waves can be deeper than the dependency graph requires) and over-parallelization (a wide wave spawns 9 builders past the 3–5 sweet spot where coordination cost overwhelms the gain — the LangGraph `max_concurrency` lesson). R16 replaces orchestrator guesswork with a deterministic scheduler derived from the task DAG.
+
+### Added — `bin/wave-plan.js` (deterministic build scheduler, zero-dependency)
+- Recomputes **minimal-depth waves** from `depends_on` (topological levels = maximal safe parallelism), then splits each level into **batches capped at `max_concurrency`**. Output is an ordered `batches[]` the orchestrator spawns one at a time. Same contract + cap → same schedule.
+- `max_concurrency`: `--parallel N` → exactly N; **auto** (default) → 1 if <3 tasks ("don't parallelize tiny phases"), else 5.
+- Flags **over-serialization** (a task whose declared wave is deeper than the DAG requires — the schedule runs it earlier) and wide-level capping. Cycle in the DAG → exit 1; library exports `deriveLevels`, `resolveConcurrency`, `plan`.
+
+### Changed — `/qualia-build` consumes the derived schedule
+- **§2** now runs `wave-plan.js .planning/phase-{N}-contract.json [--parallel K] --json` and spawns the emitted batches in order (not the raw contract `wave` numbers, not all-at-once). New `--parallel K` usage knob.
+- **Batch fan-in barrier:** `agent-status.js` (R2) gains a `barrier --tasks T1,T2` mode that gates on an explicit batch (no contract needed) — required because derived waves needn't match the contract's declared wave numbers, so the per-wave barrier would mismatch. The build now barriers per batch, keeping R16 + R2 coherent.
+
+### Tests
+- `tests/wave-plan.test.sh` (new, 23 cases): chain/independent/tiny/diamond DAGs, auto vs `--parallel` cap, wide-level batching, over-serialization flag, cycle→exit 1, `deriveLevels`/`resolveConcurrency` units. `tests/agent-status.test.sh` +3 `barrier --tasks` cases. run-all now 15 suites; manifest + `lib.test.sh` install set updated.
+
+## [6.16.0] - 2026-06-21 (v7 kernel, step 6 — R8: verifier panel + adversarial skeptics)
+
+A single LLM judge is adversarially fragile — the literature puts a lone stray token at ~35% false positives, and self-grading bias hides ~70% of findings. `/qualia-verify` was a single cooperative verifier with an optional second pass. R8 replaces it with a **panel** (one verifier per lens) + **per-finding skeptics** (majority-survives), and — crucially — makes the SURVIVE/KILL and PASS/FAIL decision **deterministic math**, not another LLM judgment.
+
+### Added — `bin/verify-panel.js` (deterministic aggregator, zero-dependency)
+- **`aggregate(panel)`**: dedupes findings across lenses (same `file:line:title` → one finding; highest severity wins, lenses union, votes sum), applies **majority-survives** (a finding is killed only when skeptics are a strict majority calling it not-real — ties and unvoted findings survive: unverified ≠ disproven), and computes category + per-lens scores via the **`rules/grounding.md` formula** (`5 − floor(weighted_sum/8)`). Verdict FAIL iff any surviving CRITICAL/HIGH. Exit 0 = PASS, 1 = FAIL.
+- **`assemble <phase>`**: globs the per-lens `phase-{N}-panel-{lens}.json` files into one `phase-{N}-panel.json` skeleton (votes zeroed) so the orchestrator never hand-builds the panel.
+- `--write` emits `.planning/phase-{N}-verification-panel.{json,md}`. Library exports (`aggregate`, `dedupeFindings`, `survives`, `scoreFromCounts`, `assemble`) for reuse.
+
+### Changed — `/qualia-verify` is now panel-based
+- **§3 Panel:** spawns one `qualia-verifier` per *relevant* lens (correctness always; security/performance/design by what the phase touches — cost scales to risk, not a flat 4×), in parallel, each anchored on the same contract-run + harness-eval evidence as shared ground truth, each emitting structured findings JSON.
+- **§3c Skeptics + aggregation:** assemble → 3 skeptics per CRITICAL/HIGH finding (5 with `--adversarial`/Handoff/security lens), each prompted to *refute* with evidence → tally votes → `verify-panel.js` produces the verdict. MEDIUM/LOW auto-survive (documented cost bound, not a silent cap). The old single-verifier + adversarial-second-pass sections are replaced.
+- **§4:** the phase is PASS only if the panel verdict, harness-eval, AND anti-slop all agree. Reuses the existing `qualia-verifier` agent (lens/skeptic are prompt modes — no new agent registration).
+
+### Tests
+- `tests/verify-panel.test.sh` (new, 28 cases): empty→PASS, surviving CRITICAL→FAIL, skeptic-killed→PASS, tie/no-vote survive, cross-lens dedupe (severity-max + vote-sum + lens-union), grounding-formula scores, MEDIUM/LOW-only→PASS, `--write` artifacts, `assemble` round-trip, malformed→exit 2. Registered in `run-all.sh` (now 14 suites); `lib.test.sh` trust-score install set carries `verify-panel.js`.
+
+## [6.15.0] - 2026-06-21 (v7 kernel, step 5 — R4+R5: single-source the dual-runtime surface)
+
+Dual-runtime drift is the #1 risk of supporting both Claude Code and Codex. `CLAUDE.md` and `AGENTS.md` were hand-maintained twins — and they *had already drifted* (the MVP-first line and the substrate list differed between them). This batch makes that class of bug unmergeable: one canonical source, compiled per host, with a drift guard in CI.
+
+### Added — R4: one canonical instruction source, compiled to both files
+- **`templates/instructions.md`** is now the single source of truth. `CLAUDE.md` and `AGENTS.md` are **generated artifacts** (committed, like a lockfile) carrying a `GENERATED` header.
+- **`bin/compile-instructions.js`** compiles the canonical into both files. `--check` mode is the **drift guard**: it exits non-zero if either committed file is stale, making "edited one twin, forgot the other" impossible to merge. Wired into the test suite + an `npm run compile:instructions` script.
+- Host-specific content uses conditional blocks (`<!--QUALIA-HOST claude-->…<!--/QUALIA-HOST-->`): the Claude file keeps the Pocock budget note, the Codex file keeps the cross-vendor (Cursor/Continue/Aider/Devin) note — the **body is byte-identical**, only the footer differs. The pre-existing drift is resolved (AGENTS.md regained the full MVP-first line + the constitution substrate entry).
+
+### Changed — R5: `host-adapters.js` is now the single per-host contract
+- The adapter is the **one place** anything runtime-specific is declared: `instructionFile`, `configFile`, `agentDir`, `agentExt`, and the Claude→Codex `naming` map (lifted out of a hardcoded swap buried in `renderText`). Nothing else branches on runtime — callers ask the adapter. A third runtime becomes one `HOSTS` entry, not a grep-and-patch.
+- Render pipeline split into composable stages: `applyNaming` (display-string swaps) + `applyPaths` (`${QUALIA_*}` tokens + `.claude→.codex`), with `renderText = applyPaths∘applyNaming` (unchanged public behavior) and `compileInstructions = applyNaming∘stripHostBlocks` (naming + blocks, paths/`{{ROLE}}` left for install).
+- **`install.js`** now routes both instruction files through `adapter(host).instructionFile` and renders `AGENTS.md` with `codexText()` — a **latent bug fix**: CLAUDE.md always got token/path rendering, AGENTS.md never did, so any `${QUALIA_*}`/`.claude/` reference in the Codex file would have shipped unresolved.
+
+### Tests
+- `tests/instructions.test.sh` (new, 25 cases): drift guard passes on HEAD + fails on an uncompiled canonical edit (with restore); CLAUDE/AGENTS bodies identical + host-specific footers preserved; adapter contract facts; `stripHostBlocks` keep/drop per host; `compileInstructions` swaps naming but leaves tokens/`{{ROLE}}`; `renderText` path regression. Registered in `run-all.sh` (now 13 suites). End-to-end install verified: both files render with the role substituted and correct footers.
+
 ## [6.14.0] - 2026-06-20 (v7 kernel, step 4 — R3: the cross-artifact analyze gate)
 
 Spec-Kit's most-copied feature, ported. Qualia validated each artifact in isolation — `plan-contract.js` proves the contract is internally well-formed, `harness-eval` scores the built phase — but **nothing diffed scope ↔ plan**. That's exactly where a junior's idea silently loses intent: the scope asks for X, the plan quietly drops it, and no deterministic check notices. This adds that check, between plan and build.

package/CLAUDE.md

@@ -1,3 +1,5 @@
+<!-- GENERATED from templates/instructions.md by bin/compile-instructions.js — do not edit directly; edit the canonical source and recompile. -->
+
 # Qualia Framework
 
 Company: Qualia Solutions — Nicosia, Cyprus
@@ -8,7 +10,7 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 
 ## Hard rules (non-negotiable)
 - **Read before Write/Edit** — *every edit is informed by the current state of the file.*
-- **Feature branches only** — *changes ship through review; main is always deployable.*
+- **Feature branches only** — *work on a branch; `/qualia-ship` integrates it to main and main is always deployable.*
 - **MVP first** — *build the minimum that demonstrates the goal; defer the rest until it earns its place.*
 - **Root cause on failures** — *understand the why before patching the symptom.*
 - **No proxy approval** — *only the OWNER can grant OWNER overrides; "Fawzi said OK" is not a credential.*

package/agents/roadmapper.md

@@ -83,23 +83,23 @@ Organize requirements under `## Milestone 1 · {Name}`, `## Milestone 2 · {Name
 This is the most important step.
 
 **Hard rules:**
-- **Ceiling: 5 milestones** (including Handoff). If the project needs more, defer remainder to post-handoff v2.
+- **The arc must cover the ENTIRE agreed scope.** Every capability in discovery §9 (the capability inventory) gets a REQ-ID and lands in a milestone; the arc continues until the §10 whole-project done-state is reached. **There is NO milestone ceiling** — plan as many milestones as the scope genuinely needs. Do NOT compress real work into a 5-milestone cap, and do NOT dump overflow into "v2": the only deferred work is what the client explicitly listed in discovery §8 (Out of Scope). If you find yourself wanting to defer agreed work to make the arc shorter, that's the exact failure that forces the team to improvise later — don't.
 - **Floor: 2 milestones** (one feature milestone + Handoff). If smaller, the project should use `/qualia-new --quick` instead.
-- **Final milestone is ALWAYS "Handoff"** with 4 standard phases: Polish, Content + SEO, Final QA, Handoff (credentials + walkthrough + domain transfer).
+- **Final milestone is "Handoff"** for client projects, with 4 standard phases: Polish, Content + SEO, Final QA, Handoff (credentials + walkthrough + domain transfer). For an internal or ongoing product (no client takeover — see discovery §10/§11), Handoff may be omitted; the arc ends at the milestone that reaches the done-state.
 - **Every non-Handoff milestone must have ≥ 2 phases** OR be an explicit shipped release gate. Single-phase milestones are phases, not milestones — merge them into the preceding milestone.
 - **Milestones are ordered by dependency, not priority.** M2 must be able to use M1's outputs.
 
-**Typical milestone arcs by project type:**
+**Typical milestone arcs by project type (STARTING POINTS, not caps — extend until §9 is fully covered):**
 
-| Type | Arc |
+| Type | Arc (minimum shape — add milestones as the capability set requires) |
 |---|---|
-| Landing / marketing | 2 milestones: Foundation → Handoff |
-| SaaS / dashboard | 4 milestones: Foundation → Core Features → Admin & Reporting → Handoff |
-| Voice / AI agent | 4 milestones: Foundation → Core Flow → Integrations → Handoff |
-| Mobile app | 5 milestones: Foundation → Core → Offline & Notifications → Store Prep → Handoff |
-| Multi-tenant platform | 5 milestones: Foundation → Core → Admin → Scale → Handoff |
+| Landing / marketing | Foundation → Handoff |
+| SaaS / dashboard | Foundation → Core Features → Admin & Reporting → … → Handoff |
+| Voice / AI agent | Foundation → Core Flow → Integrations → … → Handoff |
+| Mobile app | Foundation → Core → Offline & Notifications → Store Prep → … → Handoff |
+| Multi-tenant platform | Foundation → Core → Admin → Scale → … → Handoff |
 
-Use the research SUMMARY.md as your starting point. Don't force-fit the template — shape to this specific project.
+These are floors, not ceilings. Use the research SUMMARY.md and the §9 capability inventory as your real input — the table just shows the smallest sensible shape. Don't force-fit it; a project with 30 agreed capabilities will have more milestones than one with 6, and that is correct.
 
 **For each milestone:**
 - **Name** — short and evocative (e.g., "Core Feature Loop", not "Phase 2 Work")
@@ -124,11 +124,13 @@ For each phase in the milestone(s) you're detailing:
 ### 5. Validate Coverage
 
 Before writing, verify:
-- [ ] Every v1 requirement (all milestones excluding Handoff) has a REQ-ID
-- [ ] Every v1 requirement maps to exactly one milestone
+- [ ] **Every capability in discovery §9 has a REQ-ID** (the whole inventory, not a v1 slice)
+- [ ] Every requirement maps to exactly one milestone, and **every §9 capability is covered by some milestone** — nothing agreed is left unplanned
+- [ ] The final milestone reaches the discovery §10 whole-project done-state
+- [ ] The ONLY items in `Post-Handoff (v2)` / `Out of Scope` are the ones the client explicitly deferred in discovery §8 (no overflow from a milestone cap — there is no cap)
 - [ ] Every milestone has ≥ 2 phases (except Handoff which has the fixed 4)
-- [ ] Milestone count is 2-5 total
-- [ ] Final milestone is literally named "Handoff" with the 4 standard phases
+- [ ] Floor met: ≥ 2 milestones total (no upper bound)
+- [ ] Final milestone is "Handoff" with the 4 standard phases (client projects), or the done-state milestone (internal/ongoing products)
 - [ ] No milestone depends on a later milestone
 - [ ] Milestone 1 has full phase-level detail (goals + success criteria) ready for `/qualia-plan 1`
 - [ ] If `full_detail=false` (default): M2..M{N-1} have phase names + one-line goals (sketch, not full detail)

package/bin/agent-status.js

@@ -102,11 +102,15 @@ function expectedTaskIds(contract, wave) {
   return filtered.map((t) => t.id);
 }
 
-// Fan-in barrier: compare the persisted statuses against the task ids the
-// contract expects (optionally scoped to one wave). ok ⇔ every expected task is
+// Fan-in barrier: compare the persisted statuses against the expected task ids.
+// Expected set = an explicit opts.tasks list (used by wave-plan batches, whose
+// derived waves needn't match the contract's declared wave numbers), else the
+// contract task ids optionally scoped to opts.wave. ok ⇔ every expected task is
 // DONE. Anything else (missing/running/blocked/partial) holds the barrier.
 function barrier(root, contract, opts = {}) {
-  const expected = expectedTaskIds(contract, opts.wave);
+  const expected = Array.isArray(opts.tasks) && opts.tasks.length
+    ? opts.tasks
+    : expectedTaskIds(contract, opts.wave);
   const byTask = new Map(listStatuses(root).map((s) => [s.task, s]));
   const tasks = expected.map((id) => {
     const s = byTask.get(id);
@@ -137,6 +141,8 @@ function parseFlags(argv, start) {
     else if (a.startsWith("--cwd=")) flags.cwd = a.slice(6);
     else if (a === "--wave") flags.wave = argv[++i];
     else if (a.startsWith("--wave=")) flags.wave = a.slice(7);
+    else if (a === "--tasks") flags.tasks = argv[++i];
+    else if (a.startsWith("--tasks=")) flags.tasks = a.slice(8);
     else if (a === "--commit") flags.commit = argv[++i];
     else if (a.startsWith("--commit=")) flags.commit = a.slice(9);
     else if (a === "--note") flags.note = argv[++i];
@@ -155,6 +161,7 @@ function usage() {
     "  agent-status.js read <task> [--cwd DIR] [--json]",
     "  agent-status.js list [--cwd DIR] [--json]",
     "  agent-status.js barrier <contract.json> [--wave W] [--cwd DIR] [--json]",
+    "  agent-status.js barrier --tasks T1,T2 [--cwd DIR] [--json]   (batch gate; no contract needed)",
     "  agent-status.js clear [--cwd DIR]",
     "",
     "status ∈ RUNNING | DONE | BLOCKED | PARTIAL",
@@ -204,16 +211,22 @@ function main(argv) {
 
   if (cmd === "barrier") {
     const [contractPath] = flags._;
-    if (!contractPath) { usage(); return 2; }
-    const loaded = pc.readContractFile(contractPath);
-    if (!loaded.ok) {
-      if (flags.json) console.log(JSON.stringify({ ok: false, ...loaded }));
-      else console.error(`${loaded.error}: ${loaded.message}`);
-      return 2;
+    const taskList = flags.tasks ? flags.tasks.split(",").map((s) => s.trim()).filter(Boolean) : null;
+    // --tasks gates on an explicit batch; otherwise the contract supplies the set.
+    let contract = null;
+    if (!taskList) {
+      if (!contractPath) { usage(); return 2; }
+      const loaded = pc.readContractFile(contractPath);
+      if (!loaded.ok) {
+        if (flags.json) console.log(JSON.stringify({ ok: false, ...loaded }));
+        else console.error(`${loaded.error}: ${loaded.message}`);
+        return 2;
+      }
+      contract = loaded.contract;
     }
-    const result = barrier(root, loaded.contract, { wave: flags.wave });
+    const result = barrier(root, contract, { wave: flags.wave, tasks: taskList });
     if (flags.json) { console.log(JSON.stringify(result, null, 2)); return result.ok ? 0 : 1; }
-    const scope = result.wave != null ? `wave ${result.wave}` : "phase";
+    const scope = taskList ? `batch ${taskList.join(",")}` : (result.wave != null ? `wave ${result.wave}` : "phase");
     if (result.ok) {
       console.log(`BARRIER PASS (${scope}): ${result.done}/${result.expected} DONE`);
     } else {

package/bin/batch-plan.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// batch-plan.js — the deterministic core of /qualia-build --batch (R20).
+//
+// The wave model fits feature builds (a handful of dependency-linked tasks); it
+// does NOT fit a 50–500-file mechanical migration (a codemod). This splits a
+// flat file list into worktree-isolated, FILE-DISJOINT batches — each a small
+// worker with tiny context that opens its own commit — then groups them into
+// concurrency-capped waves that fan in through one staging branch. Map-reduce
+// over files. Zero-dep; the orchestration (spawning workers, merging) lives in
+// the /qualia-build skill — this owns the split so it's deterministic + testable.
+//
+// Usage:
+//   batch-plan.js <file> [<file> …]        # files as args
+//   batch-plan.js --from LIST              # newline-delimited file (- = stdin)
+//   …  --batch-size N (default 20)  --max-workers K (default 5)
+//      --staging BRANCH (default batch/staging)  --json
+//
+// Exit: 0 ok (even 0 files), 2 bad invocation. Zero deps.
+
+const fs = require("fs");
+
+function parseArgs(argv) {
+  const o = { files: [], batchSize: 20, maxWorkers: 5, staging: "batch/staging", json: false, from: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--batch-size") o.batchSize = Math.max(1, parseInt(argv[++i], 10) || 20);
+    else if (a === "--max-workers") o.maxWorkers = Math.max(1, parseInt(argv[++i], 10) || 5);
+    else if (a === "--staging") o.staging = argv[++i] || o.staging;
+    else if (a === "--from") o.from = argv[++i];
+    else if (a === "--json") o.json = true;
+    else if (a === "-h" || a === "--help") o.help = true;
+    else o.files.push(a);
+  }
+  return o;
+}
+
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+function readList(from) {
+  let raw;
+  if (from === "-") {
+    try { raw = fs.readFileSync(0, "utf8"); } catch { raw = ""; }
+  } else {
+    try { raw = fs.readFileSync(from, "utf8"); } catch {
+      process.stderr.write(`batch-plan.js: cannot read ${from}\n`);
+      process.exit(2);
+    }
+  }
+  return raw.split("\n").map((s) => s.trim()).filter(Boolean);
+}
+
+function buildPlan(files, opts) {
+  // De-dup while preserving order — a file must land in exactly one batch.
+  const seen = new Set();
+  const unique = [];
+  for (const f of files) {
+    if (!seen.has(f)) { seen.add(f); unique.push(f); }
+  }
+  const groups = chunk(unique, opts.batchSize);
+  const pad = String(groups.length).length;
+  const batches = groups.map((batchFiles, i) => {
+    const id = String(i + 1).padStart(pad, "0");
+    return { id, branch: `batch/${opts.staging.replace(/^batch\//, "")}-${id}`, file_count: batchFiles.length, files: batchFiles };
+  });
+  // Batches are file-disjoint → all parallelizable; cap concurrency into waves.
+  const waves = chunk(batches.map((b) => b.id), opts.maxWorkers);
+  return {
+    total_files: unique.length,
+    batch_size: opts.batchSize,
+    max_workers: opts.maxWorkers,
+    batch_count: batches.length,
+    wave_count: waves.length,
+    staging_branch: opts.staging,
+    waves,
+    batches,
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write("batch-plan.js <file…> | --from LIST [--batch-size N] [--max-workers K] [--staging B] [--json]\n");
+    process.exit(0);
+  }
+  let files = opts.files;
+  if (opts.from) files = files.concat(readList(opts.from));
+  const plan = buildPlan(files, opts);
+
+  if (opts.json) {
+    console.log(JSON.stringify(plan, null, 2));
+    process.exit(0);
+  }
+
+  console.log(`batch-plan: ${plan.total_files} files → ${plan.batch_count} batches (≤${plan.batch_size} each) → ${plan.wave_count} waves (≤${plan.max_workers} workers)`);
+  console.log(`staging branch: ${plan.staging_branch}`);
+  for (let w = 0; w < plan.waves.length; w++) {
+    console.log(`\nwave ${w + 1}: ${plan.waves[w].join(", ")}`);
+    for (const id of plan.waves[w]) {
+      const b = plan.batches.find((x) => x.id === id);
+      console.log(`  batch ${id} → ${b.branch} (${b.file_count} files)`);
+    }
+  }
+  if (plan.batch_count === 0) console.log("(no files — nothing to migrate)");
+  process.exit(0);
+}
+
+main();