qualia-framework 6.14.0 → 7.0.0

package/skills/qualia-polish/SKILL.md

@@ -94,7 +94,8 @@ Before any work — design or otherwise — pass these gates. Skipping them prod
 
 | Gate | Required check | If fail |
 |---|---|---|
-| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md`, `design-reference.md`, `frontend.md`, `graphics.md` exist and have been read when scope requires them | Read them. |
+| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md`, `design-reference.md`, `design-dials.md`, `frontend.md`, `graphics.md` exist and have been read when scope requires them | Read them. |
+| Dials + pre-flight | `qualia-design/design-dials.md` read; the 3 dials resolved from DESIGN.md §0 (or register defaults); the ban→do-instead list loaded BEFORE any token/component edit | Read it; resolve dials; cite the bans you'll avoid. |
 | PRODUCT | `PRODUCT.md` exists at project root, has `register:` field, and is not placeholder (`[TODO]` markers, < 200 chars) | Run setup: ask 5 questions and generate it. Never synthesize from prompt alone. |
 | DESIGN | `DESIGN.md` exists. If missing on App / Redesign scope, BLOCK and run setup. If missing on Component / Section / Critique / Quick scope, NUDGE and proceed. | Generate from PRODUCT.md + 3 questions. |
 | Slop-detect | `bin/slop-detect.mjs` is callable | Install or pull from framework. |
@@ -103,7 +104,7 @@ Before any work — design or otherwise — pass these gates. Skipping them prod
 State this preflight explicitly before editing:
 
 ```
-POLISH_PREFLIGHT: substrate=pass product=pass design=pass|nudged graphics=loaded|skipped slop_detect=pass mutation=open
+POLISH_PREFLIGHT: substrate=pass product=pass design=pass|nudged dials={VAR}/{MOT}/{DEN} graphics=loaded|skipped slop_detect=pass mutation=open
 ```
 
 ## Process

package/skills/qualia-recall/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: qualia-recall
+description: "Recall curated prior lessons from the Qualia memory substrate — the knowledge layer + the qualia-memory vault, role-filtered. The read side of /qualia-learn. Triggers: 'recall', 'have we done this before', 'what did we learn about X', 'prior art', 'any notes on', 'check the vault'."
+allowed-tools:
+  - Read
+  - Grep
+  - Bash
+---
+
+# /qualia-recall — Recall Knowledge
+
+The **read side** of memory. `/qualia-learn` writes; `/qualia-recall` reads. One
+query, both stores:
+
+1. **Knowledge layer** — `${QUALIA_KNOWLEDGE}/` (patterns, fixes, client prefs)
+2. **qualia-memory vault** — `~/qualia-memory/wiki/` (the team's curated,
+   cross-project Obsidian LLM Wiki)
+
+Use it BEFORE web search or before re-solving a problem — the team may already
+have the answer, already filtered for relevance.
+
+## Usage
+
+- `/qualia-recall {topic}` — recall across both stores
+- `/qualia-recall {topic} --scope vault` — vault only (`knowledge` | `vault` | `all`)
+- `/qualia-recall {topic} --json` — machine output
+
+## Access is role-aware (non-negotiable)
+
+The vault carries an access manifest at `wiki/_meta/access.md`. `recall.js`
+**enforces it deterministically**: when your role (from
+`~/.claude/.qualia-config.json`, or `$QUALIA_ROLE`) is not `OWNER`, OWNER_ONLY
+and CONDITIONAL paths (Finances, Clients, Team, raw sessions, the access manifest
+itself) are filtered out of results — you still get every ALL_ROLES lesson.
+Unknown role ⇒ fail-closed (restricted). See `${QUALIA_RULES}/access.md`.
+
+## Process
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js banner recall 2>/dev/null || true
+```
+
+### 1. Run the recall
+
+```bash
+node ${QUALIA_BIN}/recall.js "{topic}"            # human digest
+# or, to consume programmatically:
+node ${QUALIA_BIN}/recall.js "{topic}" --json
+```
+
+`recall.js` exits 0 even with zero hits, 2 on bad invocation. It delegates the
+knowledge-layer search to `knowledge.js` (so newly-added knowledge files stay
+discoverable) and greps `wiki/` for the vault.
+
+### 2. Read the strongest hits
+
+The digest ranks files by hit count. `Read` the top files (or the specific
+`file:line` for the vault page) to pull the full lesson before acting. For vault
+pages, paths are relative to `~/qualia-memory/wiki/`.
+
+### 3. Apply, then consider learning
+
+If the recall resolved your question, apply it. If you discovered something the
+stores DON'T yet have, close the loop with `/qualia-learn`.
+
+## Command Output Contract
+
+```text
+Command: /qualia-recall {topic}
+Scope: knowledge layer + vault (role-filtered)
+Intent: report
+Mutation: none (read-only)
+Evidence: recall.js across ${QUALIA_KNOWLEDGE}/ + ~/qualia-memory/wiki/
+Output: ranked digest of prior lessons
+Next: Read top hits → apply, or /qualia-learn if it's a new lesson
+```

package/skills/qualia-report/SKILL.md

@@ -123,6 +123,16 @@ if [ "$DRY_RUN" != "true" ] && [ -d .git ]; then
 fi
 ```
 
+### Step 5b — Branch hygiene sweep (clock-out safety net)
+
+Ship integrates every deploy into `main`, but work that was built and never shipped strands on a branch, and review PRs can linger. Surface both before the employee leaves — informational, never blocks:
+
+```bash
+node ${QUALIA_BIN}/branch-hygiene.js
+```
+
+Exit 1 → it lists branches with unshipped commits ahead of `main` (run `/qualia-ship` or merge them, or delete if abandoned) and any stale open PRs. Exit 0 → nothing stranded. Include the summary in the closing message so the OWNER sees it in the report.
+
 ### Step 6 — Upload to ERP
 
 The full payload-builder + 3-attempt-retry logic lives unchanged from v4 — see the **ERP Upload** section below for the canonical implementation. Behavior summary:

package/skills/qualia-scope/SKILL.md

@@ -45,7 +45,7 @@ The non-technical conversation at the start of `/qualia-new`, BEFORE roadmapping
 
 ### P1. Project type (or accept it from `/qualia-new`)
 
-If `/qualia-new` already asked the Demo vs Full gate (its literal first question), it passes `PROJECT_TYPE=demo` | `PROJECT_TYPE=full` via env/arg — **skip the gate, do not re-ask.** Only ask it when invoked standalone, via **AskUserQuestion** (header "Project shape"): "Demo (single shippable milestone, sales conversation)" vs "Full project (multi-milestone arc to Handoff)". Demo runs §1–§8 of the discovery template; Full runs all 14.
+If `/qualia-new` already asked the Demo vs Full gate (its literal first question), it passes `PROJECT_TYPE=demo` | `PROJECT_TYPE=full` via env/arg — **skip the gate, do not re-ask.** Only ask it when invoked standalone, via **AskUserQuestion** (header "Project shape"): "Demo (single shippable milestone, sales conversation)" vs "Full project (multi-milestone arc to Handoff)". Demo runs §1–§8 of the discovery template; Full runs §1–§15 (adds the capability-completeness pass + delivery questions).
 
 ### P2. Open
 
@@ -53,11 +53,11 @@ If `/qualia-new` already asked the Demo vs Full gate (its literal first question
 node ${QUALIA_BIN}/qualia-ui.js banner scope 2>/dev/null || true
 ```
 
-Say **"Eight quick questions for the demo path"** or **"Fourteen questions to shape the full project — we'll move fast."**
+Say **"Eight quick questions for the demo path"** or **"Fifteen questions to shape the full project — we'll move fast. The middle ones map out everything the project needs to be DONE."**
 
 ### P3. One question at a time, from `templates/project-discovery.md`
 
-For each §1..§8 (demo) or §1..§14 (full), ask in plain language:
+For each §1..§8 (demo) or §1..§15 (full), ask in plain language:
 
 ```
 **Question {N}/{total}:** {question text from the template}

package/skills/qualia-ship/SKILL.md

@@ -121,17 +121,37 @@ if [ $SEC_FAIL -ne 0 ]; then
 fi
 ```
 
-### 3. Git
+### 3. Integrate to main (ship IS the merge point)
+
+Ship is the one place feature work lands on `main`, so `main` is always exactly what's in production and no branch lingers. Commit, then fast-forward-integrate into `main` and push. `branch-guard` records the main push (accountability, not a block — see `rules/infrastructure.md`).
 
 ```bash
 git add {specific changed files}
 git commit -m "ship: {project name} production deploy"
-git push
+
+BR=$(git branch --show-current)
+if [ "$BR" != "main" ] && [ "$BR" != "master" ]; then
+  git checkout main
+  git pull --ff-only origin main 2>/dev/null || true   # sync with remote first
+  if git merge --ff-only "$BR"; then
+    : # clean fast-forward
+  else
+    # main moved since the branch started — rebase the feature, then ff.
+    git checkout "$BR" && git rebase main || {
+      node ${QUALIA_BIN}/qualia-ui.js fail "Rebase conflict integrating $BR → main. Resolve, then re-run /qualia-ship."
+      exit 1
+    }
+    git checkout main && git merge --ff-only "$BR"
+  fi
+fi
+git push origin HEAD
 ```
 
-Employee stays on feature branch. Never push to main.
+If anything in this block fails (conflict, push rejected), STOP and surface it — do not deploy a half-integrated tree.
+
+### 4. Deploy (from main)
 
-### 4. Deploy
+Deploy runs on `main` HEAD — what you just integrated — so the deployed artifact and `main` are byte-identical.
 
 ```bash
 vercel --prod              # Website/AI agent
@@ -141,6 +161,16 @@ supabase functions deploy  # Edge functions
 wrangler deploy            # Cloudflare Workers
 ```
 
+### 4b. Close the branch
+
+On a verified successful deploy, delete the integrated feature branch so nothing lingers (skip if you shipped directly from `main`):
+
+```bash
+if [ -n "$BR" ] && [ "$BR" != "main" ] && [ "$BR" != "master" ]; then
+  git branch -d "$BR" 2>/dev/null && git push origin --delete "$BR" 2>/dev/null || true
+fi
+```
+
 ### 5. Post-Deploy Verification
 
 Read the deployed URL from `tracking.json.deployed_url` or from an explicit user-provided URL. Do NOT use a `{domain}` placeholder — that expects the LLM to hallucinate the URL, which is exactly the kind of silent fail the state guard above prevents.

package/skills/qualia-update/SKILL.md

@@ -54,6 +54,10 @@ Keep it small and shippable. A bug fix, a copy change, a new section, a single
 feature. If it's larger than ~5 files or needs its own milestone arc, it's a new
 `build`-mode milestone — use `/qualia-milestone`, not an update.
 
+### 2b. Set the work-unit goal
+
+Per `rules/codex-goal.md` — set the work-unit goal with scope `feature` (Codex `/goal`; on Claude Code, a tracked task + budget). An update runs its own lean loop without `/qualia-plan`, so set the objective + budget here so the change stays one coherent, bounded unit.
+
 ### 3. Run the lean loop
 
 Reuse the real lifecycle skills, scoped to this one change:

package/skills/qualia-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-verify
-description: "Goal-backward verification of a built phase — fresh verifier agent greps code against acceptance criteria, scores design rubric, optional adversarial second pass. Triggers: 'verify this phase', 'check if it works', 'run verification', 'did the build pass'."
+description: "Goal-backward verification of a built phase — a parallel verifier PANEL (one lens each) greps code against acceptance criteria, per-finding adversarial skeptics vote majority-survives, and verify-panel.js aggregates a deterministic verdict. Triggers: 'verify this phase', 'check if it works', 'run verification', 'did the build pass'."
 allowed-tools:
   - Bash
   - Read
@@ -19,7 +19,7 @@ Spawn verifier to check phase goal. Does NOT trust build summaries; greps codeba
 `/qualia-verify` — verify current built phase
 `/qualia-verify {N}` — verify specific phase
 `/qualia-verify {N} --auto` — verify + auto-chain: PASS → next phase/milestone; FAIL → gap closure; gap limit → halt
-`/qualia-verify {N} --adversarial` — second verifier in fresh context with adversarial prompt. Union findings. Recommended for high-stakes phases (Handoff, payment/auth/migration).
+`/qualia-verify {N} --adversarial` — deepen the panel: 5 skeptics per finding instead of 3. Recommended for high-stakes phases (Handoff, payment/auth/migration).
 
 ## Process
 
@@ -44,25 +44,39 @@ node ${QUALIA_BIN}/contract-runner.js .planning/phase-{N}-contract.json
 
 If it fails, the phase cannot PASS. Still spawn the verifier to explain the failure and identify the smallest gap-closure tasks. If it passes, pass the evidence file into the verifier prompt.
 
-### 3. Spawn Verifier (Fresh Context)
+### 3. Spawn Verifier Panel (parallel lenses, fresh context each)
+
+A single LLM judge is adversarially fragile (a lone stray token flips ~35% of verdicts). Replace single-pass review with a **panel**: one verifier per *relevant* lens, spawned in parallel (separate `Agent()` calls in the SAME turn), each scoped to one concern and anchored on the SAME machine evidence (contract-run + harness-eval) as shared ground truth.
 
 ```bash
 node ${QUALIA_BIN}/qualia-ui.js banner verify {N} "{phase name}"
-node ${QUALIA_BIN}/qualia-ui.js spawn verifier "Goal-backward check..."
 ```
 
+Pick lenses by what the phase touches (scale cost to risk — don't run all four on a one-file change):
+- **correctness** — always.
+- **security** — if the plan touches `auth|payment|rls|service_role|migration|secret|upload`.
+- **performance** — if it touches data fetching, network-in-loop, large lists, or `--perf` is set.
+- **design** — if it touches `.tsx/.jsx/.css/.scss` or `app/|components/|pages/`.
+
+For each chosen lens `L`, spawn (all in one turn, then wait for all):
+
 ```
 Agent(prompt="
 Role: @${QUALIA_AGENTS}/verifier.md
 
+LENS: {L}. Review ONLY through the {L} lens — concerns owned by other lenses have their own reviewer; do not duplicate them.
+
 Project: @.planning/PROJECT.md
 Plan + AC + validation: @.planning/phase-{N}-plan.md
 Machine contract: @.planning/phase-{N}-contract.json
-Contract evidence: @.planning/evidence/phase-{N}-contract-run.json
+Contract evidence (shared ground truth — do not re-derive): @.planning/evidence/phase-{N}-contract-run.json
 {Re-verify → previous gaps: @.planning/phase-{N}-verification.md}
 
-Verify phase. Every finding needs file:line evidence. Severity Rubric for all labels. Output: .planning/phase-{N}-verification.md
-", subagent_type="qualia-verifier", description="Verify phase {N}")
+Verify the {L} concerns of this phase. Every finding needs file:line evidence and a Severity Rubric label.
+Write your findings as a JSON array to .planning/phase-{N}-panel-{L}.json:
+  [{\"file\":\"path\",\"line\":N,\"severity\":\"CRITICAL|HIGH|MEDIUM|LOW\",\"title\":\"one-line claim\"}]
+Empty array [] if the {L} lens is clean. Also append a human '## {L} lens' section to .planning/phase-{N}-verification.md.
+", subagent_type="qualia-verifier", description="Verify phase {N} — {L} lens")
 ```
 
 ### 3b. Browser QA (if phase touched frontend)
@@ -89,34 +103,41 @@ Drive dev server, test routes phase touched. Append '## Browser QA' to verificat
 
 Wait for both verifier + QA before step 3. Playwright MCP unavailable → QA returns BLOCKED (note, not phase failure).
 
-### 3c. Adversarial Second Opinion (--adversarial flag, optional)
+### 3c. Skeptic Pass + Deterministic Aggregation
+
+The panel FINDS; skeptics decide what's REAL; `verify-panel.js` decides the verdict — math, not a vibe.
 
-`--adversarial` in args, OR milestone is `Handoff`, OR plan touches `auth|payment|migration|rls|service_role` → spawn SECOND verifier in fresh context. Mitigates self-grading bias (~70% fewer findings without adversarial pass).
+**1. Assemble** the per-lens finding files into one panel skeleton (votes zeroed):
 
 ```bash
-node ${QUALIA_BIN}/qualia-ui.js spawn verifier "Adversarial pass — find what's wrong"
+node ${QUALIA_BIN}/verify-panel.js assemble {N}   # → .planning/phase-{N}-panel.json
 ```
 
+**2. Skeptic vote** on each CRITICAL/HIGH finding (MEDIUM/LOW auto-survive — they don't flip the C/H verdict; skipping skeptics on them is the documented cost bound, not a silent cap). For each such finding spawn **3 skeptics** (5 if `--adversarial`, Handoff milestone, or the finding's lens is `security`), each in fresh context, each prompted to REFUTE:
+
 ```
 Agent(prompt="
 Role: @${QUALIA_AGENTS}/verifier.md
 
-ADVERSARIAL reviewer. Find what's WRONG. Assume cooperative verifier missed something. Same Severity Rubric + evidence-citation req. Bias toward edge cases:
-  - Untested error paths?
-  - Crash-inducing input?
-  - Unhandled concurrent access?
-  - Downstream breaks if contract changes?
-  - Security assumption (auth, RLS, secrets) implicit not enforced?
+SKEPTIC. A panel verifier claims this finding. Try to REFUTE it: is it actually reachable on a real path, or already handled elsewhere, or a false positive? Default to refuted ONLY with evidence — uncertainty is NOT refutation.
 
-Project: @.planning/PROJECT.md
-Plan: @.planning/phase-{N}-plan.md
-Cooperative report (find what they MISSED): @.planning/phase-{N}-verification.md
+Finding: {severity} — {title}
+Location: {file}:{line}
+Evidence to re-check yourself: @{file}
+
+Return exactly one line: REAL — {file:line reason}   OR   NOT_REAL — {file:line reason}
+", subagent_type="qualia-verifier", description="Skeptic {i}/3 — {title}")
+```
+
+Tally each finding's votes into `.planning/phase-{N}-panel.json` (`votes.real` / `votes.notReal`).
+
+**3. Aggregate** deterministically:
 
-Append '## Adversarial Findings' to verification file. Empty section fine if nothing found.
-", subagent_type="qualia-verifier", description="Adversarial verify phase {N}")
+```bash
+node ${QUALIA_BIN}/verify-panel.js .planning/phase-{N}-panel.json --write
 ```
 
-Findings merge into main report. Union PASS/FAIL: either pass found CRITICAL/HIGH → phase FAIL.
+`verify-panel.js` dedupes findings across lenses, applies **majority-survives** (a finding is killed only when skeptics are a strict majority calling it not-real; ties and unvoted findings survive), computes category scores via the `rules/grounding.md` formula, and exits **0 = PASS / 1 = FAIL** (any surviving CRITICAL/HIGH → FAIL). That exit code IS the panel verdict — carry it into step 4. Artifacts: `.planning/phase-{N}-verification-panel.{json,md}`.
 
 ### 3d. INSUFFICIENT EVIDENCE downgrade (mandatory)
 
@@ -132,7 +153,7 @@ if [ "$IE_COUNT" -gt 0 ]; then
 fi
 ```
 
-The same check runs after the adversarial pass if it executed.
+The same check runs across every lens section the panel wrote.
 
 ### 3. Present Results
 
@@ -181,7 +202,7 @@ Run the zero-token anti-slop scan as a deterministic gate (same role as `migrati
 node ${QUALIA_BIN}/slop-detect.mjs --severity=critical
 ```
 
-If the eval status is `FAIL` or anti-slop exits non-zero, do not mark the phase PASS. The state machine also refuses PASS when a contract exists but `.planning/evidence/phase-{N}-contract-run.json` is missing/failing, or when the verification report contains `INSUFFICIENT EVIDENCE`.
+The phase is PASS only if ALL of these agree: the panel verdict (§3c `verify-panel.js` exit 0), the harness-eval status, and the anti-slop scan. If any is FAIL/non-zero, mark the phase FAIL. The state machine also refuses PASS when a contract exists but `.planning/evidence/phase-{N}-contract-run.json` is missing/failing, or when the verification report contains `INSUFFICIENT EVIDENCE`.
 
 ```bash
 node ${QUALIA_BIN}/state.js transition --to verified --phase {N} --verification {pass|fail} --evidence .planning/evals/harness-eval-*.json
@@ -191,6 +212,14 @@ FAIL + gap_cycles >= limit → GAP_CYCLE_LIMIT, escalate.
 FAIL + gap_cycles < limit → `/qualia-plan {N} --gaps`.
 Do NOT edit STATE.md or tracking.json manually; state.js handles both.
 
+**Emit the lifecycle event** (R14 — feeds the ERP live run-tree). Signed, non-blocking, a no-op when ERP is disabled:
+
+```bash
+node ${QUALIA_BIN}/erp-event.js emit {verify_pass|verify_fail} --target project:{project} ${ERP_PROJECT_ID:+--project $ERP_PROJECT_ID}
+```
+
+Use `verify_pass` on PASS, `verify_fail` on FAIL. The same emitter serves other lifecycle points — `session_started` (session start), `phase_planned` (`/qualia-plan`), `build_wave_started` (`/qualia-build`) — all optional and queued through `erp-retry.js`, so they never block the session.
+
 Capture new state for auto-chain routing:
 
 ```bash

package/templates/DESIGN.md

@@ -4,6 +4,21 @@
 > `/qualia-new` generates the skeleton. Update as visual decisions firm up.
 > Required pair: `PRODUCT.md` (sets the brief). This file (`DESIGN.md`) realizes it visually.
 
+## 0. Dials (aesthetic risk budget — set before §1)
+
+```
+DESIGN_VARIANCE:   {LOW · MEDIUM · HIGH}   # how far from convention
+MOTION_INTENSITY:  {LOW · MEDIUM · HIGH}   # how much movement
+VISUAL_DENSITY:    {LOW · MEDIUM · HIGH}   # information per screen
+```
+
+Defaults flow from register + project type — see `qualia-design/design-dials.md`
+(the dial table + the gating rules). A client app on an existing brand system
+caps VARIANCE at LOW for color/type; a marketing site runs HIGH. Builders and
+`/qualia-polish` read these and make choices *within* the budget. The same file
+carries the **pre-flight ban→do-instead list** every agent reads before writing
+components.
+
 ## 1. Direction (mandatory commit, before any color or font)
 
 ```

package/templates/instructions.md

@@ -0,0 +1,32 @@
+# Qualia Framework
+
+Company: Qualia Solutions — Nicosia, Cyprus
+Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + ElevenLabs + Telnyx. AI: OpenRouter. Compute: Railway.
+
+## Role: {{ROLE}}
+{{ROLE_DESCRIPTION}}
+
+## Hard rules (non-negotiable)
+- **Read before Write/Edit** — *every edit is informed by the current state of the file.*
+- **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)
+- `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` — 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.
+
+<!--QUALIA-HOST claude-->
+<!-- Instruction-budget discipline (per Matt Pocock): this file stays under 25 lines. Steering rules go into discoverable skills, not into the global system prompt. CLI preferences go into hooks. Stack/architecture details are trivially discoverable in package.json/config. -->
+<!--/QUALIA-HOST-->
+<!--QUALIA-HOST codex-->
+<!-- AGENTS.md mirrors CLAUDE.md for cross-vendor compatibility (Codex, Cursor, Continue, Aider, Devin). Both files stay under 25 lines per Matt Pocock's instruction-budget discipline (LLMs realistically hold 300–500 instructions; bloating this file hamstrings every spawn). -->
+<!--/QUALIA-HOST-->

package/templates/journey.md

@@ -100,7 +100,7 @@ M1 ─── M2 ─── M3 ─── ... ─── M{N} (Handoff)
 
 ## Rules for This Journey
 
-1. **Hard ceiling: 5 milestones.** If the project needs more, defer to a v2 release after handoff.
+1. **No milestone ceiling — the arc spans the whole agreed scope.** Plan as many milestones as the capability inventory (discovery §9) needs to reach the §10 done-state. Do NOT compress real work to hit a number, and do NOT defer agreed work to a "v2" — the only deferrals are what the client explicitly marked Out of Scope (discovery §8). An arc that stops short of the agreed scope is the root cause of teams improvising off-plan later.
 2. **Hard floor: 2 milestones.** Anything smaller should use `/qualia-new --quick` instead.
 3. **In BUILD mode, the final milestone is Handoff.** This is the convention for a one-shot client build that ends with a handoff. It is **not** a universal law: once a project launches and enters the `operate` lifecycle (`state.js launch`), it becomes an *update stream* with no forced Handoff — it ships updates indefinitely. Don't author a Handoff milestone for a product/retainer that will keep shipping; launch it instead.
 4. **Milestones ≥ 2 phases OR are a shipped release gate.** A 1-phase milestone is a phase, not a milestone.

package/templates/project-discovery.md

@@ -6,9 +6,9 @@ discovery_mode: project
 
 # Project Discovery, {Project Name}
 
-The non-technical kickoff interview output. `/qualia-scope` writes this in PROJECT MODE before `/qualia-new` generates JOURNEY.md. Captures intent, audience, brand, and constraints in the user's own words.
+The non-technical kickoff interview output. `/qualia-scope` writes this in PROJECT MODE before `/qualia-new` generates JOURNEY.md. Captures intent, audience, brand, constraints — and, for full projects, the **complete capability set that defines the project as DONE** so the roadmap can span the whole arc, not a v1 slice.
 
-Demo path: 8 questions. Full-project path: 14 questions.
+Demo path: §1–§8 (8 questions). Full-project path: §1–§15 (adds the completeness pass + delivery questions).
 
 ## 1. The one-line pitch
 
@@ -36,48 +36,55 @@ Demo path: 8 questions. Full-project path: 14 questions.
 
 ## 7. Hard constraints
 
-> {Anything that is non-negotiable: stack, deadline, compliance, integrations, budget.}
+> {Anything non-negotiable: stack, deadline, compliance, integrations, budget.}
 
-## 8. Out of scope
+## 8. Out of scope (explicitly deferred)
 
-> {What is intentionally NOT in this project, even if it would be obvious to add.}
+> {What is intentionally NOT in this project — work the client has consciously deferred, even if obvious to add. This is the ONLY place work leaves the arc; anything not listed here is in-scope and must land in a milestone.}
 
 ---
 
-The remaining six questions only run for `project_type: full`. Demo mode stops here.
+The remaining questions only run for `project_type: full`. Demo mode stops here.
 
-## 9. Milestone arc, in the client's words
+## 9. Capability inventory — the WHOLE project
 
-> {After the demo, what's the next chapter? After that, what's the chapter after? Stop at three to five chapters total. The last chapter is always Handoff.}
+> {List EVERY capability this project must have to be considered finished — not a v1 slice, the whole thing. One bullet per capability, plain language. Push for completeness: "what else does it need before you'd call it done?" Keep asking until the client says "that's everything." This list becomes the REQ-IDs and milestones — anything missing here is what the team is later forced to improvise, so it is the most important answer in the interview.}
 
-## 10. Compliance and legal
+## 10. Definition of done — for the entire project
+
+> {Describe the end state where there is no more agreed work. What is true when the project is finished and the team stops? This anchors the final milestone (Handoff for client projects) and tells the roadmapper how far the arc must reach.}
+
+## 11. Shipping order
+
+> {Roughly what order should the capabilities in §9 ship in? Group them into chapters if natural. We shape milestones from this — as many as the scope needs, no artificial cap. For client projects the last chapter is Handoff; for an internal or ongoing product it may have no Handoff.}
+
+## 12. Compliance and legal
 
 > {Anything regulated: payments, medical, legal, finance, accessibility commitments, data residency.}
 
-## 11. Integrations
+## 13. Integrations
 
 > {Third-party systems this must talk to, in priority order.}
 
-## 12. Content and copy
+## 14. Content and copy
 
 > {Who writes the copy and where does it live, today and after handoff?}
 
-## 13. Team and roles after handoff
+## 15. Ownership, team, and delivery shape
 
-> {Who maintains this after we ship? What can they do, what can't they do?}
-
-## 14. Budget and timeline shape
-
-> {Fixed deadline, fixed scope, or fixed budget? Pick one — the other two flex.}
+> {Who maintains this after we ship — what can they do, what can't they? And: fixed deadline, fixed scope, or fixed budget? Pick one — the other two flex.}
 
 ---
 
 ## How this feeds `/qualia-new`
 
-- §1-§5 seed PROJECT.md (one-line pitch, what we're building) and PRODUCT.md (users, register, voice, anti-references).
+- §1–§5 seed PROJECT.md (one-line pitch, what we're building) and PRODUCT.md (users, register, voice, anti-references).
 - §6 becomes the first row of the success-criteria table in ROADMAP.md.
-- §7-§8 populate PROJECT.md's "Out of Scope" and the constraints section.
-- §9 (full only) seeds JOURNEY.md milestone names + "why now" lines.
-- §10-§14 (full only) feed research scoping and the Handoff milestone checklist.
-
-Demo projects skip §9-§14 because they ARE one milestone — the journey is just that milestone plus an implicit "client signs, we extend" branch handled by `/qualia-milestone`.
+- §7 populates PROJECT.md's constraints section.
+- §8 populates PROJECT.md's "Out of Scope" — the explicit, client-agreed deferrals (the roadmapper must NOT defer anything else here).
+- **§9 (full only) is the capability inventory → every item becomes a REQ-ID in REQUIREMENTS.md, assigned to exactly one milestone. The roadmapper must cover ALL of §9 across the arc — no overflow into an unplanned "v2".**
+- **§10 (full only) defines the arc's endpoint → the roadmapper builds milestones until the whole capability set reaches this done-state.**
+- §11 (full only) seeds JOURNEY.md milestone order + "why now" lines (no milestone cap — the arc is as long as §9 requires).
+- §12–§15 (full only) feed research scoping, integrations, and the Handoff milestone checklist.
+
+Demo projects skip §9–§15 because they ARE one milestone — the journey is just that milestone plus an implicit "client signs, we extend" branch handled by `/qualia-milestone`.

package/templates/requirements.md

@@ -75,17 +75,17 @@ Fixed scope for every project. Do not reassign these elsewhere.
 
 ## Post-Handoff (v2)
 
-Features acknowledged but deferred past initial handoff. Not in current journey.
+**Only** capabilities the client EXPLICITLY deferred in discovery §8 (Out of Scope) belong here. This is NOT an overflow bucket for a milestone cap — there is no cap; everything in the capability inventory (discovery §9) must be a REQ-ID mapped to a milestone above. If a capability is agreed but absent from the arc, that's a roadmap bug, not a v2 item.
 
 ### {Category}
 
-- **{CAT}-XX**: {capability}
+- **{CAT}-XX**: {capability} — deferred by client (discovery §8)
 
 ---
 
 ## Out of Scope
 
-Explicit exclusions with reasoning. Prevents scope creep.
+Explicit exclusions with reasoning, drawn from discovery §8. Prevents scope creep.
 
 | Feature | Reason |
 |---------|--------|
@@ -95,16 +95,16 @@ Explicit exclusions with reasoning. Prevents scope creep.
 
 ## Traceability
 
-Populated during roadmap creation. Every v1 requirement maps to exactly one milestone + phase.
+Populated during roadmap creation. Every capability from discovery §9 maps to exactly one milestone + phase. Coverage of the full inventory — not a v1 slice — is the gate.
 
 | Requirement | Milestone | Phase | Status |
 |-------------|-----------|-------|--------|
 | {CAT}-01 | M1: {name} | Phase {N} | Pending |
 
-**Coverage:**
-- v1 requirements (all feature milestones + Handoff): {X} total
+**Coverage (must be 100% of the §9 capability inventory):**
+- Agreed capabilities (discovery §9, whole project): {X} total
 - Mapped to milestones + phases: {Y}
-- Unmapped: {Z}
+- Unmapped: {Z}  ← MUST be 0 before the journey-approval gate passes
 
 ---
 

package/tests/agent-status.test.sh

@@ -114,6 +114,21 @@ assert_exit "BLOCKED task holds barrier" 1 $RC
 assert_contains "barrier json counts blocked" "$OUT" '"blocked": 1'
 rm -rf "$TMP"
 
+# --- barrier --tasks (explicit batch gate, no contract needed; R16 wave-plan) ---
+TMP=$(mktemp -d)
+$NODE "$AS" write T1 DONE --commit a --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T2 RUNNING --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T5 DONE --commit b --cwd "$TMP" >/dev/null 2>&1
+# batch {T1,T5} both DONE → pass, with no contract file present
+$NODE "$AS" barrier --tasks T1,T5 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "barrier --tasks all DONE → pass (no contract)" 0 $?
+# batch {T1,T2} → T2 RUNNING → hold
+$NODE "$AS" barrier --tasks T1,T2 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "barrier --tasks with a RUNNING member → hold" 1 $?
+OUT=$($NODE "$AS" barrier --tasks T1,T2 --cwd "$TMP" 2>&1)
+assert_contains "barrier --tasks scope label" "$OUT" "batch T1,T2"
+rm -rf "$TMP"
+
 # --- list + clear ---
 TMP=$(mktemp -d)
 $NODE "$AS" write T1 DONE --cwd "$TMP" >/dev/null 2>&1