qualia-framework 6.14.0 → 7.0.0

package/rules/codex-goal.md

@@ -1,46 +1,48 @@
-# Codex /goal integration
+# Work-unit goal (both runtimes)
 
-When this skill spawns a unit of work on **Codex** (not Claude Code), set the thread goal at the start so Codex's native token-budget + status tracking takes over.
+When a skill begins a defined **unit of work** (a phase build, a feature, a milestone, a fix), set an explicit goal — an objective + a token budget — so the session tracks burn-vs-budget and stays anchored to one outcome. Both runtimes get this; the *surface* differs.
 
-## Runtime detection
-
-You are on Codex when `~/.codex/` exists and `~/.claude/` is absent or stale. The simplest probe:
+The objective + budget come from one shared helper, regardless of runtime:
 
 ```bash
-test -f ~/.codex/AGENTS.md && echo codex || echo claude
+node ${QUALIA_BIN}/codex-goal.js {scope}    # scope ∈ phase · task · feature · quick
 ```
 
-If the answer is `claude`, **skip this entire rule** — Claude Code has no equivalent surface and emitting `/goal` text would just be noise.
+It prints two lines from `.planning/STATE.md` + `ROADMAP.md`:
+
+```
+/goal {objective text}
+# token_budget suggestion: {N}
+```
 
-## How to set the goal
+## Runtime detection
+
+```bash
+test -f ~/.codex/AGENTS.md && [ ! -d ~/.claude ] && echo codex || echo claude
+```
 
-1. Run the helper to produce the objective string + suggested token budget:
+## Codex — native `/goal`
 
-   ```bash
-   node ~/.codex/bin/codex-goal.js {scope}
-   ```
+Codex has a first-class goal surface (`thread_goals`: objective, token_budget, tokens_used, status).
 
-   `{scope}` is one of: `phase` · `task` · `feature` · `quick`. Use the scope of the current skill.
+1. **If the `update_goal` tool is available** (Codex exposes it as a model-callable tool), call it with `objective` = the text after `/goal ` and `token_budget` = the integer suggestion.
+2. **Otherwise** surface the `/goal` line for the user to paste. Don't silently skip — it's a one-second set and the only way Codex's budget telemetry knows what to track.
 
-2. The output is two lines:
+## Claude Code — equivalent via the harness work-list + budget
 
-   ```
-   /goal {objective text from STATE.md + ROADMAP.md}
-   # token_budget suggestion: {N}
-   ```
+Claude Code has no `/goal` table, but it has a native equivalent: the **session task-list** (the model's todo/task tool) and the turn **token budget**. Use them so the work unit is just as anchored and visible:
 
-3. **If the `update_goal` tool is available** to you (Codex exposes it as a model-callable tool), call it directly with:
-   - `objective` = the text after `/goal ` on line 1
-   - `token_budget` = the integer suggestion on line 2
+1. **Create a tracked task** for the unit with the objective as its title (e.g. *"Phase 3 — checkout + Stripe webhook"*). Mark it `in_progress` at start, `completed` at end. This is the Claude-side "active goal" — it shows in the UI and survives compaction.
+2. **Treat `token_budget` as the unit's context budget.** State it in the opening line (banner) — *"Goal: {objective} · budget ~{N} tok"* — so the operator and the model both see how much room the unit has. If a `+Nk` turn directive is set, prefer that.
+3. For a multi-wave phase, the per-task `.agent-status/` entries (see `/qualia-build`) are the sub-goals under this one.
 
-4. **If `update_goal` is not available**, surface the `/goal` line to the user in your next message and let them paste it. Do not silently skip — the goal-set takes 1 second and is the only way Codex's budget telemetry knows what to track.
+Either way the rule is the same: **one named objective + one budget per work unit, surfaced, not silent.**
 
 ## When NOT to set a goal
 
-- The user is on Claude Code (no `/goal` surface).
-- A goal is already active for this thread (Codex rejects `update_goal` when one exists — call `thread/goal/get` first if you're using the tool API directly).
-- The work is open-ended exploration with no clear objective (e.g. `/qualia`, `/qualia-scope`). Goals are for executing a defined scope.
+- A goal/task is already active for this unit (don't double-set; Codex rejects `update_goal` when one exists — check first).
+- Open-ended exploration with no defined scope (`/qualia`, `/qualia-scope` PROJECT MODE, `/qualia-idk`). Goals are for *executing* a defined scope, not discovering one.
 
 ## Why
 
-Codex's `thread_goals` table tracks `objective`, `token_budget`, `tokens_used`, and a `status` enum (`active | paused | blocked | usage_limited | budget_limited | complete`). Setting the goal lets the user see burn-vs-budget in the TUI without the framework reinventing it. The token-budget number also makes the model self-aware of how much context it has left for the current unit of work.
+A named objective + budget keeps a unit of work from sprawling: the model stays self-aware of how much context remains, the operator sees burn-vs-budget, and the unit has a single definition of done. On Codex this rides `thread_goals`; on Claude Code it rides the task-list + turn budget. Same discipline, native surface on each.

package/rules/infrastructure.md

@@ -49,7 +49,7 @@ Standard services across all Qualia projects. Use these unless the project expli
 - **QualiasolutionsCY** — primary org for all Qualia Solutions projects
 - **SakaniQualia** — org for Sakani-related projects (real estate platform)
 - All repos are private by default
-- Branch protection: main/master require PR reviews (enforced by framework guards)
+- Main integration: feature branches integrate to `main` at **`/qualia-ship`** (ship is the single merge point — it fast-forwards the branch into `main`, deploys from `main`, and deletes the branch). Pushes to `main` are **allowed and recorded** by `branch-guard` (per-employee tally → ERP) — accountability, not a hard block. `/qualia-report` sweeps for branches with unshipped commits + stale PRs at clock-out so nothing lingers. Keep GitHub branch protection on `main` OFF (or with the team allowed to push) for this model; if you re-enable required reviews, switch ship to an auto-merged PR instead.
 
 ## Vercel Teams (admin knowledge)
 - Qualia operates across **3 Vercel teams** — projects are distributed across them

package/skills/qualia/SKILL.md

@@ -33,6 +33,12 @@ ls .planning/phase-*-plan.md 2>/dev/null || echo "NO_PLANS"
 ls .planning/phase-*-verification.md 2>/dev/null || echo "NO_VERIFICATIONS"
 ```
 
+And surface where work was left off last time — the richest "where we left off" signal lives in `.planning/reports/`:
+```bash
+node ${QUALIA_BIN}/last-report.js 2>/dev/null
+```
+Exit 0 → it prints a one-line digest of the newest session report (`Last session ({date}, {age}d ago): {summary} → next: {next}`). Exit 1 → no reports yet (nothing to surface). When a project is loaded and a digest exists, print that line **at the very TOP of your output**, before the banner — so the first thing the operator (or a teammate picking the project up) sees is exactly where the last session ended.
+
 Read conversation context — what has the user been doing, what errors occurred.
 
 ### 2. Classify and Route

package/skills/qualia-build/SKILL.md

@@ -21,12 +21,44 @@ Execute phase plan. Each task = fresh subagent. Independent tasks run parallel.
 `/qualia-build` — build current planned phase
 `/qualia-build {N}` — build specific phase
 `/qualia-build {N} --auto` — build + chain into `/qualia-verify {N} --auto` (no human gate)
+`/qualia-build {N} --parallel K` — cap concurrent builders at K (default auto: sequential under 3 tasks, else up to 5)
+`/qualia-build --batch` — the migration lane (R20): map-reduce a large mechanical change over a flat file list, NOT the phase-wave model. See below.
+
+## Batch lane (`--batch`) — large mechanical migrations
+
+The wave model fits a phase (a few dependency-linked tasks). It does NOT fit a
+50–500-file codemod (rename an API, swap a lib, change an import everywhere).
+For that, `--batch` is a map-reduce over files: small, file-disjoint workers in
+isolated worktrees, fanned in through ONE staging branch.
+
+```bash
+# 1. Resolve the target file list (the migration scope), one path per line:
+grep -rl 'oldApi(' src --include='*.ts' > /tmp/targets.txt
+# 2. Deterministic split into file-disjoint batches + concurrency-capped waves:
+node ${QUALIA_BIN}/batch-plan.js --from /tmp/targets.txt --batch-size 20 --max-workers 5 --staging batch/migrate-oldapi --json
+```
+
+`batch-plan.js` emits `batches[]` (each = a branch + its files — disjoint by
+construction) and `waves[]` (batch ids to run concurrently, capped at
+`--max-workers`). Then orchestrate:
+
+1. Create the staging branch from `main`: `git branch {staging_branch}`.
+2. For each wave, spawn one worker per batch **in its own worktree**
+   (`isolation: "worktree"`), each handed ONLY its `files[]` + the single
+   transformation rule. Small context per worker = no drift.
+3. Each worker applies the change to its files and commits to its `batch/…-NN`
+   branch. Workers in a wave are file-disjoint, so no conflicts.
+4. Fan in: merge each batch branch into `{staging_branch}`. Run the full test
+   suite on staging ONCE. Then `/qualia-ship` merges staging → main.
+5. A failed batch is isolated to its branch — re-run just that worker; the rest
+   proceed. Log any batch you drop (no silent partial migrations).
 
 ## Process
 
-### 0. Codex goal (Codex runtime only)
 
-Per `rules/codex-goal.md` — set the thread goal at phase start with scope `phase`.
+### 0. Set the work-unit goal
+
+Per `rules/codex-goal.md` — set the work-unit goal at phase start with scope `phase` (Codex `/goal`; on Claude Code, a tracked task + budget in the banner). One named objective + budget for the whole build.
 
 ### 1. Load Plan
 
@@ -76,13 +108,15 @@ git diff --stat
 node ${QUALIA_BIN}/qualia-ui.js banner build {N} "{phase name}"
 ```
 
-**For each wave (sequential):**
+**Derive the build schedule from the dependency graph (don't trust hand-numbered waves, don't over-spawn):**
 
 ```bash
-node ${QUALIA_BIN}/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
+node ${QUALIA_BIN}/wave-plan.js .planning/phase-{N}-contract.json {--parallel K if set} --json
 ```
 
-**Per task in wave: spawn ALL as separate `Agent()` calls in SAME turn (concurrent). Do NOT await one before spawning next.**
+`wave-plan.js` recomputes minimal-depth waves from `depends_on` (maximal safe parallelism) and splits each into **batches capped at `max_concurrency`** (auto: 1 if <3 tasks, else 5; `--parallel K` overrides). Spawn **one batch at a time, in order** — every task in a batch is dependency-free of its batch-mates, so they run concurrently; the next batch waits for the fan-in barrier (§ after each wave). Follow the emitted `batches[]`, not the raw contract `wave` numbers.
+
+**Per batch: spawn ALL its tasks as separate `Agent()` calls in the SAME turn (concurrent). Do NOT await one before spawning the next.**
 
 ```bash
 node ${QUALIA_BIN}/qualia-ui.js task {task_num} "{task title}"
@@ -150,15 +184,15 @@ Execute. Commit. Write your DONE/BLOCKED/PARTIAL status. Return DONE/BLOCKED/PAR
 node ${QUALIA_BIN}/qualia-ui.js done {task_num} "{title}" {commit_hash}
 ```
 
-**After each wave — fan-in barrier (deterministic, not "did the model notice"):**
+**After each batch — fan-in barrier (deterministic, not "did the model notice"):**
 
 ```bash
-node ${QUALIA_BIN}/agent-status.js barrier .planning/phase-{N}-contract.json --wave {W}
+node ${QUALIA_BIN}/agent-status.js barrier --tasks {comma-separated task ids in this batch}
 ```
 
-Exit 0 ⇔ every task in the wave wrote `DONE`. Non-zero → the barrier lists which tasks are RUNNING/BLOCKED/PARTIAL/MISSING. Do NOT advance to the next wave until the barrier passes; a BLOCKED/PARTIAL task is a wave failure (§4). `agent-status.js list` shows the live wave view.
+Exit 0 ⇔ every task in the batch wrote `DONE`. Non-zero → the barrier lists which tasks are RUNNING/BLOCKED/PARTIAL/MISSING. Do NOT spawn the next batch until the barrier passes; a BLOCKED/PARTIAL task is a wave failure (§4). `agent-status.js list` shows the live view. (Gating per batch — not per contract wave — keeps the barrier aligned with the `wave-plan.js` schedule, whose derived waves needn't match the contract's declared wave numbers.)
 
-**After each wave:** move to next, show summary.
+**After each batch:** move to the next batch in the schedule, show summary.
 
 ### 3. Wave Completion
 

package/skills/qualia-eval/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: qualia-eval
+description: "Evaluate an AI feature (chat / RAG / voice / agent) against a layered eval suite — deterministic assertions first, then llm-rubric judges — and gate on the result. Qualia gates UI and code; this is the equivalent gate for the AI artifacts a project builds. Triggers: 'eval this agent', 'test the chatbot', 'evaluate the AI feature', 'rag eval', 'does the assistant answer correctly', 'judge the model output', 'qualia-eval'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /qualia-eval — Evaluate an AI Feature
+
+`contract-runner` proves the code exists; `verify-panel` proves the code is correct. Neither can tell you whether the **chatbot actually answers the refund question**. This lane closes that gap with a layered eval suite — cheap deterministic checks first, model judgment only where a model is required — mirroring the contract-runner evidence model.
+
+## Usage
+`/qualia-eval {suite.json}` — run an eval suite for one AI feature
+`/qualia-eval {N}` — run every `.planning/evals/*-suite.json` for phase N (verify-step gate)
+
+## The suite (JSON)
+
+One suite per AI feature. Each case carries a captured `output` (or `output_file`) plus optional `latency_ms` / `cost_usd`, and a list of assertions:
+
+```json
+{
+  "feature": "support-chat",
+  "cases": [
+    { "name": "refund window", "input": "what's your refund policy?",
+      "output": "We refund within 30 days of purchase.",
+      "latency_ms": 1200, "cost_usd": 0.008,
+      "assert": [
+        { "type": "contains", "value": "30 days" },
+        { "type": "not_contains", "value": "I cannot help" },
+        { "type": "max_latency_ms", "value": 2000 },
+        { "type": "llm_rubric", "rubric": "answer is grounded in the policy, no hallucinated terms" }
+      ] } ]
+}
+```
+
+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`. The model-only type is `llm_rubric`.
+
+## Process
+
+### 1. Capture outputs
+
+For each case, run the AI feature on `input` and record the real `output` (+ `latency_ms`/`cost_usd` if measurable) back into the suite. Use the project's own entrypoint — an API route, a script, or the agent SDK. If outputs are already captured (replay fixtures), skip to step 2.
+
+### 2. Judge the rubrics (one judge per llm_rubric, fresh context)
+
+Deterministic assertions need no model — `eval-runner.js` settles them. For each `llm_rubric` assertion, spawn a judge to return a verdict, then write `"verdict": "pass"|"fail"` onto that assertion in the suite. This mirrors how `verify-panel` consumes skeptic votes: the model judges, the runner aggregates.
+
+```
+Agent(prompt="
+Role: @${QUALIA_AGENTS}/verifier.md
+
+JUDGE one rubric against one output. No code to grep — judge the text only.
+Rubric: {rubric}
+Input: {input}
+Output to judge: {output}
+
+Return exactly one line: PASS — {reason}  OR  FAIL — {reason}. Default FAIL if the output does not clearly satisfy the rubric.
+", subagent_type="qualia-verifier", description="Judge rubric — {case name}")
+```
+
+An `llm_rubric` with no verdict is PENDING and **fails** the suite — never silently pass an unjudged rubric.
+
+### 3. Run the deterministic verdict
+
+```bash
+node ${QUALIA_BIN}/eval-runner.js {suite.json} --write
+```
+
+`eval-runner.js` runs every deterministic assertion itself, folds in the rubric verdicts, and exits **0 = all cases pass / 1 = any failure or unjudged rubric**. Artifact: `.planning/evals/eval-{feature}.json`.
+
+### 4. Gate
+
+Exit 0 → the AI feature meets its bar; report PASS with the per-case summary. Exit 1 → list the failing cases + assertions and route to `/qualia-fix` (behavior wrong) or back to the prompt/RAG config. When run as a phase verify-step gate (`/qualia-eval {N}`), a FAIL is a phase FAIL — same standing as a failing contract.
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js end "EVAL COMPLETE" "/qualia-verify {N}"
+```

package/skills/qualia-feature/SKILL.md

@@ -40,9 +40,9 @@ One command for adding a small new capability outside the planned Road. Auto-det
 
 ## Process
 
-### 0. Codex goal (Codex runtime only)
+### 0. Set the work-unit goal
 
-Per `rules/codex-goal.md` — set the thread goal with scope matching the auto-detected bucket (`quick` for inline, `feature` for spawn). Do this AFTER Step 2 (auto-detect scope) so the budget matches the actual work shape.
+Per `rules/codex-goal.md` — set the work-unit goal (Codex `/goal`; on Claude Code, a tracked task + budget) with scope matching the auto-detected bucket (`quick` for inline, `feature` for spawn). Do this AFTER Step 2 (auto-detect scope) so the budget matches the actual work shape.
 
 ### 1. Capture description
 
@@ -50,6 +50,22 @@ If invoked without args, ask: **"What do you want to build?"**
 
 Wait for free-text answer. Don't paraphrase back. Capture the user's exact phrasing — it feeds both the auto-scope classifier and the eventual commit message.
 
+### 1b. Scope gate (anti-drift — keep work on the milestone arc)
+
+Before building, check whether this work belongs to the active milestone. This is what stops feature/fix from drifting off-plan.
+
+```bash
+node ${QUALIA_BIN}/state.js check 2>/dev/null   # → milestone, profile; JOURNEY.md = the arc
+node ${QUALIA_BIN}/state.js reqs-check 2>/dev/null   # current milestone's open REQ-IDs
+```
+
+- **No active project / no milestone** (`.planning/` absent) → not governed; proceed normally (skip to Step 2).
+- **Active milestone**: decide if this work serves it.
+  - **In-scope** (it advances the current milestone's goal or an open REQ-ID) → proceed. Record it tagged to scope in Steps 4/5: add `--scope in --ref {REQ-ID or phase}` to the `state.js transition --to note` call.
+  - **Off-road** (a new capability/feature that isn't in the current milestone): this is exactly the drift the framework guards against. Resolve by profile (`state.js check` → `profile`):
+    - **strict** → STOP. Do not build off-road. Route to `/qualia-scope` to fold it into the arc (a phase/REQ in the current or a future milestone) or `/qualia-milestone` if it's a new milestone. Off-road building is blocked.
+    - **standard** → allowed, but **recorded**: build it, then record with `--scope off --ref "{what + why off-road}"` so the OWNER + ERP see the off-road tally (it is never silent).
+
 ### 2. Auto-detect scope
 
 Classify the description into one of three buckets:
@@ -116,7 +132,7 @@ git commit -m "fix: {description}"
 5. Record in state:
 
 ```bash
-node ${QUALIA_BIN}/state.js transition --to note --notes "{brief description}" --tasks-done 1
+node ${QUALIA_BIN}/state.js transition --to note --notes "{brief description}" --tasks-done 1 {--scope in --ref {REQ/phase}  |  --scope off --ref "{why off-road}" — from the §1b scope gate}
 ```
 
 6. End with:
@@ -184,7 +200,7 @@ node ${QUALIA_BIN}/qualia-ui.js end "FEATURE SHIPPED (spawn)"
 5. Record in state:
 
 ```bash
-node ${QUALIA_BIN}/state.js transition --to note --notes "{description}" --tasks-done 1
+node ${QUALIA_BIN}/state.js transition --to note --notes "{description}" --tasks-done 1 {--scope in --ref {REQ/phase}  |  --scope off --ref "{why off-road}" — from the §1b scope gate}
 ```
 
 ### 6. Execute the refuse path

package/skills/qualia-fix/SKILL.md

@@ -48,6 +48,10 @@ Fix is the practical lane for "this used to work, or should work, and now it doe
 node ${QUALIA_BIN}/qualia-ui.js banner fix
 ```
 
+### 0. Set the work-unit goal
+
+Per `rules/codex-goal.md` — set the work-unit goal (Codex `/goal`; on Claude Code, a tracked task + budget) with scope `quick` for `--quick`, else `feature`. Anchors the fix to one objective + budget so root-cause work doesn't sprawl.
+
 ### 1. Classify The Request
 
 Parse `$ARGUMENTS` into:
@@ -70,6 +74,14 @@ If the request is phase-sized, stop and route:
 node ${QUALIA_BIN}/qualia-ui.js end "ROUTED" "/qualia-plan"
 ```
 
+### 1b. Scope tag (anti-drift)
+
+```bash
+node ${QUALIA_BIN}/state.js check 2>/dev/null   # milestone + profile
+```
+
+Repairing broken behavior in what the current milestone already built is **in-scope** — proceed, and tag the record `--scope in --ref {REQ/phase}` in Step 7. But a "fix" that is really **new off-road behavior** (a capability the milestone never included, dressed as a bug) is drift: in **strict** profile, STOP and route to `/qualia-scope` to fold it into the arc; in **standard**, proceed but record `--scope off --ref "{why off-road}"` so it's counted, never silent. No active milestone → not governed, proceed.
+
 ### 2. Build The Feedback Loop
 
 Use the cheapest check that can prove the bug is real and later prove it is fixed.
@@ -175,7 +187,7 @@ git commit -m "fix: {short symptom/root-cause summary}"
 Record state:
 
 ```bash
-node ${QUALIA_BIN}/state.js transition --to note --notes "{short fix summary}" --tasks-done 1
+node ${QUALIA_BIN}/state.js transition --to note --notes "{short fix summary}" --tasks-done 1 {--scope in --ref {REQ/phase}  |  --scope off --ref "{why off-road}" — from the §1b scope tag}
 ```
 
 ### 8. Output

package/skills/qualia-map/SKILL.md

@@ -49,6 +49,21 @@ If `ALREADY_MAPPED`, ask:
 node ${QUALIA_BIN}/qualia-ui.js banner map
 ```
 
+### 2.5 Cheap symbol map first (ground the scan)
+
+Before spawning the mapper agents, build a zero-dep symbol map so the agents
+read STRUCTURE, not whole files — cheaper and better-grounded onboarding:
+
+```bash
+node ${QUALIA_BIN}/repo-map.js . --json > .planning/codebase/repo-map.json
+node ${QUALIA_BIN}/repo-map.js .            # human view for the operator
+```
+
+It lists every source file's top-level symbols (exports, functions, classes,
+types), busiest files first — the structural backbone. Pass the path of
+`repo-map.json` to each mapper agent as a starting index so they target the
+right files instead of reading the tree blind.
+
 ### 3. Spawn 5 Mapper Agents (parallel)
 
 Each writes one file in `.planning/codebase/`:

package/skills/qualia-milestone/SKILL.md

@@ -30,13 +30,17 @@ Triggered after `/qualia-verify` passes on the LAST phase of the current milesto
 
 ```bash
 node ${QUALIA_BIN}/state.js check
+node ${QUALIA_BIN}/state.js reqs-check   # this milestone's REQ-ID completion
 ```
 
-`state.js close-milestone` enforces two guards:
+`state.js close-milestone` enforces three guards:
 - `MILESTONE_NOT_READY` — any phase not verified
 - `MILESTONE_TOO_SMALL` — milestone has < 2 phases
+- `MILESTONE_REQS_INCOMPLETE` — a REQ-ID mapped to this milestone in REQUIREMENTS.md is not yet `Complete` (strict profile blocks; standard profile proceeds but the unfinished REQs are surfaced as `warnings` to log). This is what stops "finishing a milestone with scope still open."
 
-If either fires (without `--force`), stop and show the error. The user must verify remaining phases first (or add `--force` for explicit bypass on a preview/demo milestone).
+If any fires (without `--force`), stop and show the error. Resolve before closing: verify remaining phases, finish the open requirements, or **explicitly defer** a requirement by moving it to `Out of Scope` in REQUIREMENTS.md (a conscious deferral, not silent). `--force` bypasses all three for retroactive bookkeeping only.
+
+Run `reqs-check` first so the user sees exactly which requirements are still open before the close attempt — Step 4 (mark Complete) should already have flipped the finished ones.
 
 ### 1b. Demo-Extension Branch
 
@@ -59,7 +63,7 @@ If `PROJECT_TYPE=demo` AND `MILESTONE_COUNT=1`, the demo's one milestone is clos
 **If "Client signed — extend to full project":**
 
 1. Update `.planning/PROJECT.md` frontmatter: `project_type: full`.
-2. Run a brief discovery top-up — invoke `/qualia-scope` in PROJECT MODE, but only ask §9-§14 (the full-project-only questions). This adds the milestone arc, compliance, integrations, content ownership, handoff team, and budget shape.
+2. Run a brief discovery top-up — invoke `/qualia-scope` in PROJECT MODE, but only ask §9–§15 (the full-project-only questions). This adds the **capability inventory** (the whole project's scope), the **whole-project definition of done**, shipping order, compliance, integrations, content ownership, handoff team, and budget shape.
 3. Spawn the roadmapper in `extend-to-full` mode (see prompt below). It reads the existing single milestone (now M1), the updated discovery, and produces a full JOURNEY.md with M2..M{N-1} sketches plus the Handoff milestone.
 4. Then proceed with the standard close-milestone flow (Steps 2-9) — M1 closes, M2 opens, the user is asked to continue.
 
@@ -75,11 +79,13 @@ Read your role: @${QUALIA_AGENTS}/roadmapper.md
 
 <task>
 The existing JOURNEY.md has 1 milestone (the demo, now M1 and shipped). Extend it
-into a 2-5 milestone arc to Handoff:
+into the FULL milestone arc to Handoff — as many milestones as the agreed scope
+needs (no cap), covering the entire capability inventory:
 
 - Keep M1 exactly as-is (it shipped).
-- Add M2..M{N-1} based on §9 of project-discovery.md (the milestone-arc question
-  the user answered when converting from demo).
+- Add M2..M{N-1} covering every capability in §9 of project-discovery.md (the
+  capability inventory), ordered per §11 (shipping order). Every §9 capability
+  must land in a milestone — nothing agreed is left unplanned.
 - Append a Handoff milestone (fixed 4 phases: Polish, Content + SEO, Final QA,
   Handoff).
 - Update REQUIREMENTS.md to add REQ-IDs for the new milestones.

package/skills/qualia-new/REFERENCE.md

@@ -59,8 +59,10 @@ Read your role: @${QUALIA_AGENTS}/research-synthesizer.md
 
 Merge the 4 research files at .planning/research/ into .planning/research/SUMMARY.md.
 This is a multi-milestone project -- the SUMMARY must suggest a FULL milestone arc
-(2-5 milestones including Handoff), not just a v1 phase list. Include roadmap
-implications AND handoff implications (what client takeover requires).
+that covers the ENTIRE capability set to its done-state (as many milestones as the
+scope needs, ending in Handoff for client projects -- no milestone cap), not just a
+v1 phase list. Include roadmap implications AND handoff implications (what client
+takeover requires).
 ", subagent_type="qualia-research-synthesizer", description="Synthesize research")
 ```
 
@@ -74,7 +76,7 @@ Read your role: @${QUALIA_AGENTS}/roadmapper.md
 
 <task>
 Create the FULL JOURNEY for this project:
-  - .planning/JOURNEY.md -- all milestones (2-5 including Handoff) with exit criteria
+  - .planning/JOURNEY.md -- all milestones (≥2, no upper cap; ending in Handoff for client projects) covering every capability from discovery §9, with exit criteria
   - .planning/REQUIREMENTS.md -- requirements grouped by milestone
   - .planning/ROADMAP.md -- Milestone 1's phase detail (and ALL milestones if full_detail=true)
 
@@ -115,7 +117,7 @@ The branded journey ladder rendered in Step 11. Use `node ${QUALIA_BIN}/qualia-u
 ```
 ## Proposed Journey
 
-**{N} milestones to handoff** | **{X} requirements mapped** | All v1 requirements covered
+**{N} milestones to handoff** | **{X}/{X} capabilities mapped** | Full §9 inventory covered (0 unmapped)
 
   +-- Milestone 1 . {Name}               [CURRENT]
   |  Why now: {one line}

package/skills/qualia-new/SKILL.md

@@ -58,7 +58,7 @@ Use **AskUserQuestion** (interactive UI — never a plain-text prompt):
 - question: "What kind of project is this? Pick one — it drives everything else."
 - options:
   - "Demo" — one shippable milestone, real backend, no mocks. Built to win a client conversation, extensible via `/qualia-milestone` if they sign. 8-question discovery.
-  - "Full project" — the multi-milestone arc to Handoff. 2-5 milestones planned upfront. 14-question discovery.
+  - "Full project" — the full multi-milestone arc to Handoff, sized to the agreed capability set (no fixed milestone cap — the arc spans to done). 15-question discovery.
   - "Quick prototype" — landing page, throwaway, ≤1 day. Skips research and journey. (Equivalent to `--quick` flag.)
 
 Store the answer as `PROJECT_TYPE=demo` | `PROJECT_TYPE=full` | `PROJECT_TYPE=quick`. It drives every downstream step.
@@ -94,7 +94,7 @@ The shape is locked, now capture the content in one sentence:
 
 > **"What are you building? One sentence — a stranger should understand it."**
 
-Accept whatever the user says, even if broad. **Do NOT start an ad-hoc clarification round here.** Depth comes from the structured discovery interview in Step 4, not from free-form questioning. If the answer is "a SaaS platform" — that's fine, write it down, move on. `/qualia-scope` will refine it through its 8 or 14 structured questions.
+Accept whatever the user says, even if broad. **Do NOT start an ad-hoc clarification round here.** Depth comes from the structured discovery interview in Step 4, not from free-form questioning. If the answer is "a SaaS platform" — that's fine, write it down, move on. `/qualia-scope` will refine it through its 8 or 15 structured questions.
 
 This is the ONLY free-text question in the kickoff flow. Everything else is `AskUserQuestion`.
 
@@ -102,7 +102,7 @@ This is the ONLY free-text question in the kickoff flow. Everything else is `Ask
 
 **Hard rule:** This is the next tool call after Step 3. No ad-hoc clarification, no free-form follow-up, no "let me ask a few quick things first." If the one-line pitch was "a SaaS platform", you invoke `/qualia-scope` NOW — that skill's structured questions are how breadth gets refined into depth.
 
-Invoke `/qualia-scope` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 14 for full project. Pass `PROJECT_TYPE` so the scope skill skips the type question.
+Invoke `/qualia-scope` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 15 for full project. Pass `PROJECT_TYPE` so the scope skill skips the type question.
 
 This step REPLACES the old free-form "deep questioning" loop. The scope skill captures answers verbatim into `.planning/project-discovery.md`, which seeds PROJECT.md, PRODUCT.md, CONTEXT.md, and (for full projects) JOURNEY.md milestone names.
 
@@ -285,6 +285,20 @@ Then fill the rest of DESIGN.md:
 
 Cross-check the result against `qualia-design/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
 
+**Per-client token registry (R10).** Compile DESIGN.md §2/§3/§4 into a CSS-variable
+registry so every builder inherits the real design system instead of inventing
+one (and the `ABS-HEX-IN-JSX` ban has a target to point at):
+
+```bash
+node ${QUALIA_BIN}/design-tokens.js init --out .planning/design-tokens.json   # starter; edit to the client's brand
+node ${QUALIA_BIN}/design-tokens.js compile .planning/design-tokens.json --out app/styles/tokens.css
+```
+
+`design-tokens.json` is the registry source of truth; `tokens.css` is the
+generated artifact the scaffold imports. Builders reference `var(--color-…)` /
+`var(--font-…)`, never a literal hex. Per `design-dials.md`, a client brand
+registry caps DESIGN_VARIANCE at LOW for color/type. See `design-reference.md`.
+
 ```bash
 git add .planning/DESIGN.md .planning/config.json
 git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
@@ -331,13 +345,13 @@ Read `.planning/research/FEATURES.md` and present the feature landscape. Feature
 For each category, use AskUserQuestion:
 
 - header: "{Category name}"
-- question: "Which {category} features belong to v1 (Milestones 1..N-1 excluding Handoff)?"
+- question: "Which {category} features are part of THIS project (the full agreed scope)? Anything selected must land in a milestone — the arc is sized to fit, no cap."
 - multiSelect: true
-- options: each feature from FEATURES.md + "None for v1"
+- options: each feature from FEATURES.md + "None of these"
 
 Track selections:
-- Selected → v1 scope (roadmapper assigns to specific milestones based on dependency order)
-- Unselected table stakes → Post-Handoff v2 (users expect these)
+- Selected → in scope (roadmapper assigns each to a specific milestone by dependency order; the arc grows to cover all of them)
+- Unselected → only goes to Post-Handoff/Out-of-Scope if the user EXPLICITLY defers it (matches discovery §8). Don't silently drop a table-stakes feature into v2 to keep the arc short.
 - Unselected differentiators → Out of Scope
 
 Gather any additional requirements the user wants that research missed.
@@ -350,12 +364,24 @@ node ${QUALIA_BIN}/qualia-ui.js banner roadmap
 
 **Roadmapper output branches on `PROJECT_TYPE`:**
 
-- **Demo** (`PROJECT_TYPE=demo`): roadmapper produces a 1-milestone JOURNEY.md (the demo milestone, 2-4 phases) plus a matching REQUIREMENTS.md and a fully-detailed ROADMAP.md. No "Handoff" milestone is appended — the demo is its own complete artifact. The journey-tree at Step 14 shows a single rung; the "extend to full project" branch is handled later by `/qualia-milestone` if the client signs.
-- **Full project** (`PROJECT_TYPE=full`): roadmapper produces the standard 2-5 milestone arc ending in Handoff. Milestone 1 fully detailed, M2..M{N-1} sketched (unless `--full-detail`).
+- **Demo** (`PROJECT_TYPE=demo`): roadmapper produces a 1-milestone JOURNEY.md (the demo milestone, 2-4 phases) plus a matching REQUIREMENTS.md and a fully-detailed ROADMAP.md. No "Handoff" milestone is appended — the demo is its own complete artifact. The journey-tree at Step 15 shows a single rung; the "extend to full project" branch is handled later by `/qualia-milestone` if the client signs.
+- **Full project** (`PROJECT_TYPE=full`): roadmapper produces the full milestone arc ending in Handoff (client projects), sized to cover the entire capability inventory from discovery §9 — no fixed milestone count. Milestone 1 fully detailed, M2..M{N-1} sketched (unless `--full-detail`).
 
 Spawn the roadmapper with `<project_type>$PROJECT_TYPE</project_type>` in the prompt. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` so the roadmapper writes complete phase detail for ALL milestones (full project only; demo always has full detail because there's only one milestone). See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
 
-### Step 14. Present the Journey (single view)
+### Step 14. Coverage gate (before presenting — the genesis teeth)
+
+Before showing the journey, verify the arc actually covers the whole agreed scope. This is what stops the framework from generating "milestones that don't finish the project."
+
+1. Read the capability inventory: `.planning/project-discovery.md` §9 (full projects).
+2. Read `.planning/REQUIREMENTS.md` traceability.
+3. Confirm **every §9 capability has a REQ-ID mapped to a milestone** (Unmapped = 0), and the only items in `Post-Handoff (v2)` / `Out of Scope` are the ones the client explicitly deferred in §8.
+
+If any §9 capability is unmapped, or agreed work was pushed to v2 to shorten the arc → **do NOT present for approval.** Re-spawn the roadmapper with the gap list and instruction to extend the arc until coverage is complete. Only proceed to the ladder when coverage is 100%.
+
+(Demo projects skip this — they're a single milestone with no §9 inventory.)
+
+### Step 15. Present the Journey (single view)
 
 Render the branded journey ladder:
 
@@ -367,7 +393,7 @@ This shows M1..M{N} as a vertical ladder: shipped milestones get a green dot, cu
 
 Also narrate the one-glance summary. See REFERENCE.md section "Journey ladder format" for the ASCII template.
 
-### Step 15. Approval Gate (single — for the whole journey)
+### Step 16. Approval Gate (single — for the whole journey)
 
 - header: "Journey"
 - question: "Does this journey work for you?"
@@ -397,7 +423,7 @@ node ${QUALIA_BIN}/qualia-ui.js info "Full phase detail for each later milestone
 
 (Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
 
-### Step 16. Environment Setup
+### Step 17. Environment Setup
 
 Supabase project? `supabase link` or create. Vercel project? `vercel link`. Env vars? `.env.local` with placeholders from PROJECT.md stack.
 
@@ -408,7 +434,7 @@ git add .gitignore
 git commit -m "chore: environment setup" 2>/dev/null
 ```
 
-### Step 17. Auto-Apply Gate (or stop here)
+### Step 18. Auto-Apply Gate (or stop here)
 
 If invoked with `--auto`, skip straight into building Milestone 1:
 
@@ -465,10 +491,10 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 1a. **One stack question, then a real scaffold.** Step 5a asks exactly ONE stack-preset question (`landing-page` / `full-app` / `ai-agent` / `internal-tool`) and then instantiates it: copies `scaffold/` into the project (never clobbering existing files), copies `env.required.json` → `.planning/env.required.json`, and copies `phases.md` → `.planning/phases.md`. The project starts from a runnable skeleton, not an empty folder. Skip this step on `--quick`. Record the choice as `config.json.stack_id`.
 2. **AskUserQuestion for every discrete-choice question.** Project type, brownfield gate, design vibe, client type, approval gate, auto-chain — all use the interactive UI. The ONLY free-text question in the kickoff flow is the Step 3 one-line pitch. No plain-text prompts for anything that has a closed set of answers.
 3. **No ad-hoc clarification questioning.** After Step 3 (one-line pitch), the next tool call is `/qualia-scope`. No "let me ask a few quick things first", no "that's too broad, can you clarify". Depth is the scope skill's job — not yours.
-4. **Discovery interview is mandatory.** Step 4 always invokes `/qualia-scope` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
+4. **Discovery interview is mandatory.** Step 4 always invokes `/qualia-scope` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 15 for full project.
 5. **Research runs automatically.** No permission ask. Only `--quick` skips it. Demo path uses `<scope>quick</scope>` (3-call budget per researcher); full project uses standard 8-call budget.
 6. **Demo design philosophy is non-negotiable.** Real backend always (Supabase, real auth), DESIGN.md mandatory, slop-detect hard-block, 1 milestone, focus on real agent/platform functionality + design quality. No mock data, no lorem ipsum, no broken flows. Speed comes from skipping multi-milestone planning, never from skipping design quality, mocking the backend, or cutting corners on the core flow. A demo that uses mock data is not a Qualia demo.
-7. **Demos are 1 milestone, full projects are 2-5.** Demo journeys have no "Handoff" — the demo IS the artifact. Full projects always end in Handoff (fixed 4 phases). The journey-tree adapts to both shapes.
+7. **Demos are 1 milestone; full projects are 2+ (as many as the agreed scope needs — no cap).** Demo journeys have no "Handoff" — the demo IS the artifact. Full client projects end in Handoff (fixed 4 phases); internal/ongoing products may end at their done-state milestone. The journey-tree adapts to any length. A full project's arc must cover every capability from discovery §9 — never trimmed to hit a milestone count.
 8. **The full-project journey includes Handoff.** Every full project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
 9. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
 10. **Milestone 1 is fully detailed (full projects).** M2..M{N-1} are sketched. Detail fills in when each milestone opens. Demos are always fully detailed because they're 1 milestone.

package/skills/qualia-plan/SKILL.md

@@ -27,9 +27,9 @@ Spawn planner to break phase into tasks, validate with checker (max 2 revision c
 
 ## Process
 
-### 0. Codex goal (Codex runtime only)
+### 0. Set the work-unit goal
 
-Per `rules/codex-goal.md` — set the thread goal at plan start with scope `phase`. The objective covers both planning and the subsequent build, so a single goal-set at this stage is enough.
+Per `rules/codex-goal.md` — set the work-unit goal at plan start with scope `phase` (Codex `/goal`; on Claude Code, a tracked task + budget). The objective covers both planning and the subsequent build, so a single goal-set at this stage is enough.
 
 ### 1. Determine Phase & Load Context