qualia-framework 6.14.0 → 6.22.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,136 @@ 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.
 
+## [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/branch-hygiene.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// branch-hygiene.js — the clock-out safety net for trunk integration.
+//
+// WHY: /qualia-ship integrates feature→main on every successful deploy, so the
+// normal path leaves nothing open. But work that was BUILT and never SHIPPED
+// strands on a local branch ahead of main, and the occasional review PR can
+// linger. This surfaces both at /qualia-report so nothing rots silently.
+//
+// Detects:
+//   - local branches with commits ahead of main that aren't merged (stranded work)
+//   - open PRs (best-effort via `gh`; skipped silently when gh is absent/unauth)
+//
+// Read-only. Never blocks (report never blocks) — exit 0 = clean,
+// 1 = stranded branches and/or stale PRs found, 2 = not a git repo.
+// Zero npm dependencies.
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+function git(args, cwd) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return { ok: r.status === 0, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+}
+
+function mainBranch(cwd) {
+  // Prefer an existing local main, else master, else the remote HEAD target.
+  for (const b of ["main", "master"]) {
+    if (git(["rev-parse", "--verify", "--quiet", b], cwd).ok) return b;
+  }
+  const head = git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], cwd);
+  if (head.ok && head.out) return head.out.replace(/^origin\//, "");
+  return "main";
+}
+
+function strandedBranches(cwd, base) {
+  const heads = git(["for-each-ref", "--format=%(refname:short)", "refs/heads/"], cwd);
+  if (!heads.ok) return [];
+  const out = [];
+  for (const b of heads.out.split(/\r?\n/).filter(Boolean)) {
+    if (b === base) continue;
+    // commits on b not in base — unmerged work.
+    const count = git(["rev-list", "--count", `${base}..${b}`], cwd);
+    const ahead = count.ok ? Number(count.out) : 0;
+    if (ahead > 0) {
+      const last = git(["log", "-1", "--format=%cI", b], cwd);
+      out.push({ branch: b, ahead, last_commit: last.ok ? last.out : null });
+    }
+  }
+  return out.sort((a, b) => b.ahead - a.ahead);
+}
+
+// Best-effort open-PR list via gh. Absent/unauth/non-GitHub → [] (never an error).
+function openPRs(cwd, staleDays, nowIso) {
+  const r = spawnSync("gh", ["pr", "list", "--state", "open", "--json", "number,title,headRefName,createdAt", "--limit", "100"],
+    { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (r.status !== 0 || !r.stdout) return [];
+  let prs;
+  try { prs = JSON.parse(r.stdout); } catch { return []; }
+  const now = nowIso ? Date.parse(nowIso) : null;
+  return prs.map((p) => {
+    let ageDays = null;
+    if (now != null && p.createdAt) ageDays = Math.floor((now - Date.parse(p.createdAt)) / 86400000);
+    return { number: p.number, title: p.title, branch: p.headRefName, age_days: ageDays, stale: ageDays != null && ageDays >= staleDays };
+  });
+}
+
+function analyze(cwd, opts = {}) {
+  const root = path.resolve(cwd || process.cwd());
+  if (!git(["rev-parse", "--is-inside-work-tree"], root).ok) {
+    return { ok: false, error: "NOT_A_GIT_REPO" };
+  }
+  const base = mainBranch(root);
+  const stranded = strandedBranches(root, base);
+  const prs = openPRs(root, opts.staleDays || 7, opts.now);
+  const stalePrs = prs.filter((p) => p.stale);
+  return {
+    ok: stranded.length === 0 && stalePrs.length === 0,
+    base,
+    stranded,
+    open_prs: prs,
+    stale_prs: stalePrs,
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else if (a === "--stale-days") args.staleDays = Number(argv[++i]);
+    else if (a.startsWith("--stale-days=")) args.staleDays = Number(a.slice(13));
+    else if (a === "--now") args.now = argv[++i]; // ISO; tests inject determinism
+    else if (a.startsWith("--now=")) args.now = a.slice(6);
+  }
+  return args;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const result = analyze(args.cwd, { staleDays: args.staleDays, now: args.now });
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : (result.error ? 2 : 1);
+  }
+
+  if (result.error === "NOT_A_GIT_REPO") {
+    console.error("branch-hygiene: not a git repository");
+    return 2;
+  }
+  if (result.ok) {
+    console.log(`Branch hygiene clean — no work stranded off ${result.base}, no stale PRs.`);
+    return 0;
+  }
+  if (result.stranded.length) {
+    console.log(`⚠ ${result.stranded.length} branch(es) with unshipped commits ahead of ${result.base}:`);
+    for (const s of result.stranded) {
+      console.log(`  - ${s.branch} (+${s.ahead} commit${s.ahead === 1 ? "" : "s"}) — /qualia-ship it or merge, or delete if abandoned`);
+    }
+  }
+  if (result.stale_prs.length) {
+    console.log(`⚠ ${result.stale_prs.length} stale open PR(s):`);
+    for (const p of result.stale_prs) console.log(`  - #${p.number} ${p.title} (${p.age_days}d, ${p.branch})`);
+  }
+  return 1;
+}
+
+module.exports = { analyze, strandedBranches, mainBranch };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/command-surface.js

@@ -14,6 +14,7 @@ const ACTIVE_SKILLS = [
   "qualia-plan",
   "qualia-build",
   "qualia-verify",
+  "qualia-eval",
   "qualia-fix",
   "qualia-feature",
   "qualia-review",

package/bin/compile-instructions.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// compile-instructions.js — single-source the agent-instruction files.
+//
+// CLAUDE.md and AGENTS.md used to be hand-maintained twins, which guarantees
+// drift (and they HAD drifted — the MVP-first line and the substrate list
+// differed). Now both are compiled from one canonical source,
+// templates/instructions.md, via the host adapter. Editors touch the canonical;
+// the per-host files are generated artifacts (committed, like a lockfile).
+//
+//   node bin/compile-instructions.js          # regenerate CLAUDE.md + AGENTS.md
+//   node bin/compile-instructions.js --check  # fail (exit 1) if either is stale
+//
+// The --check mode is the drift guard the test suite runs: it makes "edited one
+// twin, forgot the other" impossible to merge.
+
+const fs = require("fs");
+const path = require("path");
+const { adapter, compileInstructions } = require("./host-adapters.js");
+
+const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+const CANONICAL = path.join(FRAMEWORK_DIR, "templates", "instructions.md");
+
+const HEADER =
+  "<!-- GENERATED from templates/instructions.md by bin/compile-instructions.js — do not edit directly; edit the canonical source and recompile. -->";
+
+// host → output filename, declared by the adapter (single source of per-host facts).
+const TARGETS = ["claude", "codex"];
+
+function expectedFor(canonical, host) {
+  return `${HEADER}\n\n${compileInstructions(canonical, host)}`;
+}
+
+function targets() {
+  return TARGETS.map((host) => ({
+    host,
+    file: adapter(host).instructionFile,
+    pathAbs: path.join(FRAMEWORK_DIR, adapter(host).instructionFile),
+  }));
+}
+
+function main(argv) {
+  const check = argv.includes("--check");
+  let canonical;
+  try {
+    canonical = fs.readFileSync(CANONICAL, "utf8");
+  } catch (e) {
+    console.error(`ERROR: cannot read canonical source ${CANONICAL}: ${e.message}`);
+    return 2;
+  }
+
+  const drift = [];
+  for (const t of targets()) {
+    const expected = expectedFor(canonical, t.host);
+    if (check) {
+      let actual = null;
+      try { actual = fs.readFileSync(t.pathAbs, "utf8"); } catch {}
+      if (actual !== expected) {
+        drift.push(t.file);
+        console.error(`DRIFT: ${t.file} is out of sync with templates/instructions.md`);
+      }
+    } else {
+      fs.writeFileSync(t.pathAbs, expected, "utf8");
+      console.log(`wrote ${t.file} (from templates/instructions.md, host=${t.host})`);
+    }
+  }
+
+  if (check) {
+    if (drift.length) {
+      console.error(`\n${drift.length} file(s) stale. Run: node bin/compile-instructions.js`);
+      return 1;
+    }
+    console.log("CLAUDE.md + AGENTS.md are in sync with templates/instructions.md");
+    return 0;
+  }
+  return 0;
+}
+
+module.exports = { expectedFor, targets, HEADER, CANONICAL };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}