qualia-framework 6.4.0 → 6.5.0

package/CLAUDE.md

@@ -14,6 +14,7 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 - **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

package/bin/command-surface.js

@@ -8,6 +8,7 @@
 const ACTIVE_SKILLS = [
   "qualia",
   "qualia-new",
+  "qualia-scope",
   "qualia-discuss",
   "qualia-map",
   "qualia-research",

package/bin/qualia-ui.js

@@ -82,6 +82,7 @@ const ACTIONS = {
   auto:       { label: "AUTO MODE",        glyph: "⚡" },
   research:   { label: "RESEARCH",         glyph: "◱" },
   roadmap:    { label: "ROADMAP",          glyph: "◐" },
+  scope:      { label: "SCOPING",          glyph: "⬡" },
 };
 
 // ─── State Reading ───────────────────────────────────────

package/bin/state.js

@@ -219,6 +219,9 @@ function ensureLifetime(t) {
   if (typeof t.milestone_name !== "string") t.milestone_name = "";
   if (!Array.isArray(t.milestones)) t.milestones = [];
   if (typeof t.report_seq !== "number") t.report_seq = 0;
+  // Seniority profile (backward compat): old tracking.json files predate this
+  // field. Anything other than the exact string 'standard' defaults to 'strict'.
+  if (t.profile !== "standard" && t.profile !== "strict") t.profile = "strict";
   if (!t.lifetime || typeof t.lifetime !== "object") {
     t.lifetime = {
       tasks_completed: 0,
@@ -343,6 +346,9 @@ function parseStateMd(content) {
     phase_name: phaseMatch ? phaseMatch[3].trim() : "",
     status: get("Status").toLowerCase().replace(/\s+/g, "_") || "setup",
     assigned_to: get("Assigned to") || "",
+    // Seniority profile: 'standard' lets a senior waive a gate; anything else
+    // (including missing or typo'd values) coerces to 'strict' — the safe default.
+    profile: get("Profile").toLowerCase() === "standard" ? "standard" : "strict",
     phases,
     schema_errors,
   };
@@ -377,6 +383,7 @@ See: .planning/PROJECT.md
 Phase: ${s.phase} of ${s.total_phases} — ${s.phase_name}
 Status: ${s.status}
 Assigned to: ${s.assigned_to}
+Profile: ${s.profile || "strict"}
 Last activity: ${now} — ${s.last_activity || "State updated"}
 
 Progress: [${bar}] ${phaseFrac}%
@@ -572,16 +579,105 @@ function nextCommand(status, phase, totalPhases, verification) {
 
 // ─── Commands ────────────────────────────────────────────
 
+// ─── Seniority profile gate contract ────────────────────
+// The effective profile resolves as: $QUALIA_PROFILE (env wins) → STATE.md
+// Profile: line → tracking.json profile → 'strict' (default). Any value other
+// than the exact string 'standard' coerces to 'strict' — the safe gate.
+//
+// Gate semantics (the contract; enforcement lives in the CONSUMING skill,
+// qualia-scope — state.js only stores and surfaces the field, it does NOT
+// enforce gates here or in cmdTransition):
+//   strict   = hard gates, no waivers. The Definition-of-Done gate cannot be
+//              exited until every area is covered and no [NEEDS CLARIFICATION]
+//              markers remain.
+//   standard = gates advisory. A senior may exit the gate early with a reason
+//              logged as an ADR in .planning/decisions/.
+function resolveProfile(s, t) {
+  const raw =
+    process.env.QUALIA_PROFILE ||
+    (s && s.profile) ||
+    (t && t.profile) ||
+    "strict";
+  return String(raw).toLowerCase() === "standard" ? "standard" : "strict";
+}
+
 function cmdCheck(opts) {
   const t = readTracking();
   const s = parseStateMd(readState());
-  if (!t || !s) {
+  // True NO_PROJECT only when BOTH the durable tracking AND the dashboard are
+  // absent. Either alone is a recoverable half-state.
+  if (!t && !s) {
     return output({
       ok: false,
       error: "NO_PROJECT",
       message: "No .planning/ found. Run /qualia-new to start.",
     });
   }
+  // STATE.md missing/corrupt but tracking.json intact. STATE.md is a derivable
+  // view — tracking.json already carries phase/status/milestone (the statusline
+  // reads them straight from it). Reconstruct and route to repair instead of
+  // falsely reporting NO_PROJECT. Critically, exit 0: cmdCheck feeds the
+  // /qualia router, which runs it inside a PARALLEL Bash batch. A non-zero exit
+  // makes the harness cancel the sibling commands ("Cancelled: parallel tool
+  // call ... errored"), so a recoverable state must never exit non-zero.
+  if (t && !s) {
+    ensureLifetime(t);
+    const phase = Number(t.phase || 1) || 1;
+    return output({
+      ok: true,
+      phase,
+      phase_name: t.phase_name || "",
+      total_phases: Number(t.total_phases || 0) || 0,
+      status: String(t.status || "setup"),
+      assigned_to: t.assigned_to || "",
+      profile: resolveProfile(null, t),
+      milestone: t.milestone || 1,
+      milestone_name: t.milestone_name || "",
+      milestones: t.milestones || [],
+      lifetime: t.lifetime,
+      verification: t.verification || "pending",
+      gap_cycles: (t.gap_cycles || {})[String(phase)] || 0,
+      gap_cycle_limit: getGapCycleLimit(),
+      tasks_done: t.tasks_done || 0,
+      tasks_total: t.tasks_total || 0,
+      deployed_url: t.deployed_url || "",
+      next_command: "state.js fix",
+      warning:
+        "STATE.md missing or unparseable — reconstructed from tracking.json. " +
+        "Run `state.js fix` to rewrite it canonically, then continue.",
+      recovered_from: "tracking.json",
+    });
+  }
+  // tracking.json missing but STATE.md present (the inverse half-state). The
+  // rest of cmdCheck needs tracking for lifetime/milestone/verification, so
+  // route to repair (`state.js fix` rebuilds tracking from STATE.md) rather
+  // than crash on a null tracking object. Exit 0 for the same batch reason.
+  if (!t && s) {
+    return output({
+      ok: true,
+      phase: s.phase,
+      phase_name: s.phase_name,
+      total_phases: s.total_phases,
+      status: s.status,
+      assigned_to: s.assigned_to,
+      profile: resolveProfile(s, null),
+      milestone: 1,
+      milestone_name: "",
+      milestones: [],
+      lifetime: undefined,
+      verification: "pending",
+      gap_cycles: 0,
+      gap_cycle_limit: getGapCycleLimit(),
+      tasks_done: 0,
+      tasks_total: 0,
+      deployed_url: "",
+      next_command: "state.js fix",
+      warning:
+        "tracking.json missing — reconstructed from STATE.md. " +
+        "Run `state.js fix` to rebuild tracking, then continue.",
+      recovered_from: "STATE.md",
+    });
+  }
   ensureLifetime(t);
   output({
     ok: true,
@@ -590,6 +686,7 @@ function cmdCheck(opts) {
     total_phases: s.total_phases,
     status: s.status,
     assigned_to: s.assigned_to,
+    profile: resolveProfile(s, t),
     milestone: t.milestone || 1,
     milestone_name: t.milestone_name || "",
     milestones: t.milestones || [],
@@ -940,6 +1037,12 @@ function cmdInit(opts) {
   const prev = readTracking();
   const prevLife = prev ? ensureLifetime(prev) : null;
 
+  // Seniority profile: explicit --profile standard opts in; otherwise preserve
+  // the prior project's profile on re-init, defaulting to the safe 'strict'.
+  // Any value other than the exact string 'standard' coerces to 'strict'.
+  const profileSource = opts.profile || (prevLife ? prevLife.profile : "strict");
+  const profile = profileSource === "standard" ? "standard" : "strict";
+
   // Build state
   const s = {
     phase: 1,
@@ -947,6 +1050,7 @@ function cmdInit(opts) {
     phase_name: phases[0].name,
     status: "setup",
     assigned_to: opts.assigned_to || "",
+    profile,
     last_activity: `Project initialized`,
     phases: phases.map((p, i) => ({
       num: i + 1,
@@ -994,6 +1098,7 @@ function cmdInit(opts) {
     phase_name: phases[0].name,
     total_phases: totalPhases,
     status: "setup",
+    profile,
     wave: 0,
     tasks_done: 0,
     tasks_total: 0,

package/guide.md

@@ -99,6 +99,13 @@ Hard rules (enforced by `state.js` and the roadmapper):
 5. **`/qualia` is your friend** — lost on "what's my next command?" The router reads state and returns the next move.
 6. **`/qualia-idk` is your deeper friend** — confused about *the situation itself*. Reads conversation + planning + code, then returns guidance plus a paste-ready Qualia command sequence.
 
+## Profiles
+
+A project runs under one profile, set via `$QUALIA_PROFILE` (defaults to `strict`). `state.js check` surfaces the active profile in its output.
+
+- **`strict`** (default for the team) — hard gates, no waivers. Every gate must pass before the road advances.
+- **`standard`** — gates are advisory. A senior may exit a Definition-of-Done gate early, provided the reason is logged to `.planning/decisions/`.
+
 ## When You're Stuck
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -45,7 +45,13 @@
     "templates/",
     "references/",
     "tests/",
-    "docs/",
+    "docs/agent-runs.md",
+    "docs/erp-contract.md",
+    "docs/plan-contract.md",
+    "docs/playwright-loop-pilot-results.md",
+    "docs/release.md",
+    "docs/changelog-v6.html",
+    "docs/onboarding.html",
     "CLAUDE.md",
     "AGENTS.md",
     "guide.md"

package/references/archetypes/ai-agent.md

@@ -0,0 +1,89 @@
+---
+archetype: ai-agent
+stack: Next.js 16 (Vercel, app + API) · Supabase (Postgres + pgvector) · Railway (workers) · OpenRouter · Tailwind + shadcn/ui
+updated: 2026-05-28
+---
+
+# Archetype: `ai-agent`
+
+> LLM / chat / agent products on Supabase + Vercel, with Railway for any long-running or scheduled compute. The roadmapper loads this file when the operator picks `ai-agent`. Voice (`voice-agent`) extends this archetype with a latency + call-testing milestone — see the bottom note.
+
+## How this file is used
+
+Same contract as every archetype: `qualia-scope` grills the **Grill variables**, the **Definition of Done** is the fixed coverage, the **Road** is the default 0→100. The differentiator here is **M3 — the eval gate**: an agent isn't "done" because it replies; it's done when it passes measurable cases.
+
+## Grill variables (what `qualia-scope` must extract)
+
+- **Job to be done** — one sentence. What does the agent *do*, for whom, replacing what manual work?
+- **Conversation shape** — single-turn tool, multi-turn chat, or autonomous task agent?
+- **Knowledge** — does it need the client's data (RAG)? Sources, freshness, volume → drives pgvector + ingestion.
+- **Tools / actions** — what can it *do* beyond talk (book, query, email, write to a system)? Each tool is a vertical slice.
+- **Model & routing** — quality vs cost tier; which OpenRouter models; fallback chain.
+- **Surface** — embedded widget, standalone app, API, or channel (WhatsApp/Slack)? Auth model.
+- **Compute shape** — purely request/response (Vercel only) or long-running/scheduled/queue work (→ Railway worker)?
+- **Guardrails** — what must it refuse? PII handling? Human escalation path?
+- **Success metric** — how is "good" measured? (This becomes the eval suite. If they can't answer, the project has no finish line — surface it now.)
+- **Cost ceiling** — per-conversation and monthly budget → drives guardrails.
+
+## Production Definition of Done
+
+**Foundation & data** — Supabase with **RLS on every table** (conversations, messages, users, embeddings); auth; pgvector if RAG. Migrations in version control.
+
+**Agent core** — LLM via **OpenRouter** with model fallback; system prompts **versioned in source**, never hardcoded inline; streaming responses; context-window management.
+
+**RAG (if applicable)** — ingestion pipeline; retrieval quality checked, not assumed; source attribution.
+
+**Tools/actions** — each action validated server-side; failure + timeout handling; idempotency where it writes.
+
+**Evals** — pass/fail suite over real cases before "done"; covers the success metric and the refusal/guardrail cases. **This is the ship gate.**
+
+**Guardrails & cost** — input validation; refusal/safety behavior; graceful fallback on model failure; per-request + daily cost ceilings; token + latency logging.
+
+**Compute (if Railway)** — health checks (`/health`); structured logging; restart policy; staging→prod env separation; secrets in Railway variables, never logged.
+
+**App quality** — auth flows; rate limiting; the **non-AI-looking** UI pass; responsive; loading/empty/error/streaming states.
+
+**Security & compliance** — `service_role` server-only; secrets in env; security headers; MFA on accounts; GDPR posture (EU) — consent, retention, data export/delete.
+
+**Observability** — Sentry + structured logging + analytics.
+
+**Deploy & handoff** — Vercel prod (+ Railway prod if worker); env separation; post-deploy smoke including **real agent calls**; credentials + walkthrough + archive + ERP report.
+
+## The Road (default 0→100)
+
+### M1 — Foundation & Data
+- Init: Next.js 16 (Vercel) for app + API routes; Supabase project (auth, RLS on every table); Railway service scaffolded *only if* the grill found long-running/scheduled work.
+- Schema: conversations, messages, users; pgvector tables if RAG.
+- OpenRouter wired with a model + fallback; secrets in env.
+- **Exit:** authenticated user can hit a stubbed endpoint; RLS verified by logging in as two users; deploys to preview.
+
+### M2 — Core Agent Loop (vertical slice: input → model → response → persist)
+- Streaming chat UI; system prompt in source control; conversation persistence.
+- Orchestration: tool-calling scaffold; RAG retrieval if applicable; context management.
+- Cost guardrails + token/latency logging from the first call.
+- **Exit:** a real end-to-end conversation works, persists, and its cost/latency is logged.
+
+### M3 — Evals & Guardrails (THE GATE)
+- Eval harness with pass/fail cases mapped to the success metric — not vibes.
+- Guardrails: input validation, refusal/safety, fallback on model failure, human-escalation path.
+- Each tool/action: server-side validation, timeout + failure handling, idempotency on writes.
+- Railway health checks + logging if a worker exists.
+- **Exit:** eval suite green; every guardrail case handled. *No ship before this milestone closes.*
+
+### M4 — App Surface & Polish
+- Auth flows, user management, rate limiting.
+- The non-AI-looking design pass (DESIGN.md, anti-slop), responsive, all async states incl. streaming.
+- **Exit:** product looks and feels built, not generated; passes design-laws.
+
+### M5 — Handoff (always last)
+- Security review + secrets/env audit; GDPR posture (consent, retention, export/delete).
+- Prod deploy (Vercel + Railway envs separated); post-deploy smoke including **real agent calls**, not just HTTP 200.
+- Credentials handover, walkthrough, archive, `/qualia-report` to ERP.
+- **Exit:** all DoD lines covered or waived with reason; client can operate it.
+
+## Why M3 exists (the 0→100 insight)
+
+The reason agents "finish but aren't done" is that M2 *feels* like completion — it talks, it's demo-able. But demo-able ≠ reliable. **M3 is the milestone the old flow never had**: it converts "it replied" into "it passes." If the grill couldn't extract a success metric, M3 has no cases to run — which is the framework telling you the project was never properly scoped. That's the feature, not a bug.
+
+## Voice extension (`voice-agent`)
+Add a milestone between M3 and M4: **latency budget <800ms end-to-end** (the bar where callers stop noticing it's AI; >1.2s feels like legacy IVR), **end-to-end call testing with pass/fail** through the full Retell + ElevenLabs + Telnyx stack (not just prompt review), turn-taking / barge-in verified, transcript logging + PII redaction, recording-consent disclosure.

package/references/archetypes/voice-agent.md

@@ -0,0 +1,60 @@
+---
+archetype: voice-agent
+extends: ai-agent
+stack: Retell (orchestration) · ElevenLabs (voice) · Telnyx (telephony) · OpenRouter (LLM) · Supabase · Vercel/Railway
+updated: 2026-05-29
+---
+
+# Archetype: `voice-agent`
+
+> Real-time voice agents (inbound/outbound calls) on Retell + ElevenLabs + Telnyx. **Extends `ai-agent`** — every `ai-agent` Definition-of-Done line still applies (OpenRouter routing, versioned prompts, the eval gate, cost guardrails, RLS, observability, security). This file adds the voice-specific bars, where latency and real call testing are the difference between "demo" and "shippable." Used by `qualia-scope` when the operator picks `voice-agent`.
+
+## How this file is used
+
+Same contract: `qualia-scope` grills the **Grill variables**, the **Definition of Done** is the per-increment bar, the **Road** is the default 0→100. Inherits `ai-agent` + `rules/constitution.md`. The new gate is **M-Voice**: real end-to-end calls with pass/fail, not transcript review.
+
+## Grill variables (added on top of `ai-agent`)
+
+- **Call direction** — inbound, outbound, or both? Volume/concurrency expected?
+- **The one job** — appointment reminder, intake, qualification, support triage? (Start with one; a vague "assistant" fails.)
+- **Call flow** — the happy path + the branches (no-answer, voicemail, wrong person, transfer-to-human).
+- **Voice & persona** — language(s), accent, ElevenLabs voice, tone, named or anonymous.
+- **Latency tolerance** — confirm the <800ms target fits the use case; identify the slowest dependency (LLM, tool call, DB).
+- **Tools mid-call** — what must it look up or write *during* the call (calendar, CRM, order status)? Each is a latency risk.
+- **Escalation** — when and how does it hand to a human? Warm transfer or callback?
+- **Telephony** — Telnyx numbers, regions, caller-ID, recording laws per region.
+- **Compliance** — recording-consent disclosure, PII handling, GDPR retention (EU). Regulated domain (health/finance)?
+- **Success metric** — answered-rate, completion-rate, transfer-rate, CSAT? (Becomes the eval + call-test pass criteria.)
+
+## Production Definition of Done (added on top of `ai-agent`)
+
+**Latency** — **<800ms end-to-end** turn latency is the bar where callers stop noticing it's AI; >1.2s feels like legacy IVR. Measured on real calls, not assumed. Slowest dependency identified and budgeted.
+
+**Call quality** — turn-taking / barge-in / interruption handled without breaking flow; no dead air on tool calls (filler/await behavior); graceful handling of no-answer, voicemail, silence, wrong person.
+
+**End-to-end call testing (THE GATE)** — automated test calls through the full Retell + ElevenLabs + Telnyx stack with measurable pass/fail against the success metric. Transcript review is *not* sufficient — the audio path is part of the product.
+
+**Escalation** — human handoff path tested (transfer or callback); failure modes (LLM/tool/telephony down) degrade safely, never trap the caller.
+
+**Observability & compliance** — full transcript + recording logging; PII redaction; recording-consent disclosure at call start; GDPR retention policy; per-region recording-law compliance.
+
+**Cost** — per-minute + per-call cost tracked (voice + LLM + telephony stack); daily ceiling.
+
+## The Road (default 0→100)
+
+Follows `ai-agent` M1–M3 (Foundation/Data → Core Loop → Evals & Guardrails), then inserts the voice gate before the app surface:
+
+### M-Voice — Voice Path & Call Testing (inserted after ai-agent M3, before polish)
+- Retell agent wired to ElevenLabs voice + Telnyx numbers; LLM via OpenRouter.
+- Call flow built: happy path + branches (no-answer, voicemail, wrong person, transfer).
+- Mid-call tools with no-dead-air behavior; barge-in/turn-taking verified.
+- **Latency measured on real calls to the <800ms budget**; slowest dependency optimized.
+- **End-to-end automated call tests** with pass/fail on the success metric.
+- Transcript + recording logging; consent disclosure; PII redaction.
+- **Exit:** real test calls pass the metric at target latency; every branch + escalation handled; compliance wired. *No ship before this closes.*
+
+### Then — App Surface & Handoff
+- `ai-agent` M4/M5: dashboard (call logs, transcripts, metrics), the non-AI-looking UI, security/GDPR review, prod deploy (Vercel + Railway envs), smoke including **real calls**, handoff or rolling-release.
+
+## Why M-Voice exists
+A voice agent that reads well in a transcript can still be unusable on a call — 1.5s pauses, talking over the caller, dead air during a lookup. Text evals (ai-agent M3) prove the *reasoning*; M-Voice proves the *experience*. Both gates, or it isn't done.

package/references/archetypes/web-app.md

@@ -0,0 +1,67 @@
+---
+archetype: web-app
+extends: website
+stack: Next.js 16 (App Router) · Tailwind + shadcn/ui · Supabase (auth + Postgres + RLS) · Vercel
+updated: 2026-05-29
+---
+
+# Archetype: `web-app`
+
+> Authenticated products with user accounts, roles, and a dashboard on Vercel + Supabase. **Extends `website`** — every `website` Definition-of-Done line still applies (design, performance, SEO where relevant, a11y, observability, deploy, handoff). This file adds the auth, data, and app-quality bars. Used by `qualia-scope` when the operator picks `web-app`, or when a `website` grows gated content / accounts.
+
+## How this file is used
+
+Same contract as every archetype: `qualia-scope` grills the **Grill variables**, the **Definition of Done** is the per-increment bar, the **Road** is the default 0→100. Inherits `website` + `rules/constitution.md`; relaxes nothing.
+
+## Grill variables (added on top of `website`)
+
+- **Who are the users?** — roles (admin / staff / client / public) and what each can see and do. Drives the RLS model.
+- **Auth model** — email/password, magic link, OAuth providers, SSO? Email verification required? Password reset flow?
+- **Authorization source** — what claims gate access? (Must live in `app_metadata`, never `user_metadata` — constitution.)
+- **Tenancy** — single-tenant, per-user, or multi-tenant/workspace? (Multi-tenant changes every RLS policy — surface it now.)
+- **Core entities & relationships** — the domain model. Each entity → a CONTEXT.md glossary term.
+- **Write surfaces** — what users create/edit/delete; which writes need confirmation, soft-delete, or audit.
+- **Real-time / collaboration** — does anything need live updates (presence, notifications)?
+- **Billing** — free, one-off, subscription? Provider? (If yes, billing is its own increment set.)
+- **Notifications** — email (Resend), in-app, both? Triggered by what events?
+
+## Production Definition of Done (added on top of `website`)
+
+**Auth & access** — Supabase auth with the chosen model; email verification + password reset wired; **RLS enabled on every table** with policies derived from `app_metadata` claims; role-based routing enforced in middleware *and* at the data layer (never trust the client). Verified by logging in as each role and confirming isolation.
+
+**RLS correctness (constitution)** — every UPDATE policy has a matching SELECT; views use `security_invoker = true`; storage upsert grants INSERT+SELECT+UPDATE; sessions revoked before user delete.
+
+**Data** — domain schema in `supabase/migrations/`; FK relationships normalized; soft-delete + audit where the grill flagged it; no N+1 on list views.
+
+**App quality** — every async surface has loading / empty / error states; forms validate client *and* server (Zod or equivalent); destructive actions confirm; optimistic UI where latency matters; rate limiting on mutating + public endpoints.
+
+**Security** — `service_role` server-only; secrets in env; security headers (HSTS); MFA on Supabase/Vercel accounts; CSRF/permission checks on every mutation.
+
+**Billing (if applicable)** — provider integrated; webhooks idempotent; plan/entitlement state authoritative server-side; failed-payment + cancellation flows handled.
+
+## The Road (default 0→100)
+
+### M1 — Foundation, Auth & Data
+- Init stack + Vercel link + CI; Supabase project; **RLS on every table from the first migration** (not retrofitted).
+- Auth model: signup, login, verification, reset; role claims in `app_metadata`; role-based middleware.
+- Domain schema + relationships; seed data.
+- **Exit:** each role logs in and sees only what it should — verified as two+ users; deploys to preview.
+
+### M2 — Core Capabilities (one vertical slice per capability)
+- Each capability cuts through UI + server action + RLS + validation + states + test. Independently shippable.
+- **Exit:** the primary user job works end-to-end with all async states; writes validated both sides.
+
+### M3 — App Hardening
+- Rate limiting, audit/soft-delete, notifications, real-time (if scoped); billing increments (if scoped).
+- Performance pass (list virtualization, query aggregation, no N+1); error/empty states audited.
+- **Exit:** mutation paths secured + rate-limited; perf budget met; billing flows (if any) handle failure.
+
+### M4 — Polish, SEO-where-relevant & Handoff
+- Design pass to `website` anti-slop bar; a11y WCAG 2.2 AA; SEO on public routes only (`noindex` the app).
+- Legal pages; analytics + Sentry; security pass (RLS, headers, env, MFA); custom domain; prod deploy + smoke.
+- Credentials, walkthrough, archive, ERP report (or rolling-release for an internal product).
+- **Exit:** all DoD lines covered or waived with reason.
+
+## Notes
+- Internal/living products (like the ERP) run as **rolling releases** — no terminal Handoff. Each shipped increment still clears this DoD. Handoff applies only to client-delivered web-apps.
+- LLM features → escalate to `ai-agent` (adds OpenRouter routing, evals, cost guardrails on top of this).

package/references/archetypes/website.md

@@ -0,0 +1,78 @@
+---
+archetype: website
+stack: Next.js 16 (App Router) · Tailwind + shadcn/ui · Supabase · Vercel
+updated: 2026-05-28
+---
+
+# Archetype: `website`
+
+> Marketing / brochure / content sites on Vercel + Supabase. The roadmapper loads this file when the operator picks `website`. The grill (`qualia-scope`) reads the **Grill variables** below; the **Definition of Done** is the fixed coverage the roadmap must satisfy; the **Road** is the default 0→100 shape.
+
+## How this file is used
+
+1. `qualia-scope` grills the operator through the **Grill variables** — depth on each, recommended-answer-with-why, writing answers to the spec and terms to `.planning/CONTEXT.md`.
+2. The grill is **DoD-aware**: it raises every Definition-of-Done area even if the operator never mentioned it (auth? legal pages? CMS or static?).
+3. The roadmapper maps the filled spec onto the **Road**, dropping inapplicable DoD lines *with a logged reason* and expanding applicable ones into vertical slices.
+4. `qualia-verify` at each milestone close checks DoD coverage, not just per-task acceptance.
+
+## Grill variables (what `qualia-scope` must extract)
+
+- **Purpose & primary CTA** — what one action defines success (book, buy, subscribe, contact)?
+- **Page inventory** — exact routes. Static or dynamic?
+- **Content source** — hardcoded, Markdown/MDX, or Supabase-backed CMS? Who edits it after handoff?
+- **Brand direction** — reference sites, typography intent, color, tone. (Drives DESIGN.md — the anti-slop bar.)
+- **Auth?** — most brochure sites: none. If gated content/portal → escalate to `web-app` archetype.
+- **Forms & data capture** — contact, lead, newsletter. Where does the data go? Notifications?
+- **Integrations** — analytics, CRM, payment, booking, email (Resend), maps.
+- **Languages / i18n**, **legal jurisdiction** (drives which legal pages), **domain** status.
+
+## Production Definition of Done
+
+**Design (anti-slop)** — chosen typeface with personality (not default Inter); deliberate spacing/radius scale; passes `qualia-design/design-laws.md`; responsive across breakpoints; dark mode if brand calls for it; real content, no lorem.
+
+**Performance** — LCP ≤2.5s · INP ≤200ms · CLS ≤0.1 at field-data p75; image optimization (next/image); JS/page-weight budget agreed up front; Lighthouse in CI.
+
+**SEO** — Metadata API per route; `metadataBase` in root layout; JSON-LD; sitemap.xml; robots.txt; canonicals; OG images; `X-Robots-Tag: noindex` on preview hosts.
+
+**Accessibility** — WCAG 2.2 AA (EU default).
+
+**Data (only if forms/CMS)** — Supabase table(s); **RLS enabled** with insert-only public policy on form tables, read policy on published content; rate limit on public POST.
+
+**Security** — SSL enforced; secrets in env (`vercel env pull`), never client; `service_role` server-only; security headers (HSTS); MFA on Vercel/Supabase accounts.
+
+**Observability** — analytics + Sentry + structured logging from day one.
+
+**Content & legal** — real copy; privacy, terms, cookie notice (GDPR).
+
+**Deploy & handoff** — Vercel production; custom domain + DNS; post-deploy smoke (HTTP 200, console clean, API <500ms); credentials + walkthrough + archive + ERP report.
+
+## The Road (default 0→100)
+
+### M1 — Foundation & Design System
+Vertical slices establishing the visual language before any page is "real".
+- Init: Next.js 16 App Router + TS + Tailwind + shadcn; repo + CI; Vercel project linked; preview deploys on.
+- DESIGN.md from brand grill: real typography, color scale, spacing/radius, motion rules, explicit anti-slop negative rules.
+- Layout shell: nav, footer, responsive grid, dark mode, base components.
+- **Exit:** design system renders on a preview URL; passes design-laws baseline; tokens documented.
+
+### M2 — Pages & Content (one vertical slice per page-type)
+- Each page-type as a slice: layout + real content + loading/empty/error states.
+- CMS path (if chosen): Supabase schema + RLS read policies + editor wiring.
+- Forms: UI + validation (client + server) → Supabase table (RLS insert + rate limit) → notification (Resend).
+- **Exit:** every route has real content and states; forms persist and notify; no lorem anywhere.
+
+### M3 — Performance, SEO & Accessibility
+- Perf pass to budget (LCP/INP/CLS, image optimization, bundle); Lighthouse in CI.
+- SEO: metadata per route, metadataBase, JSON-LD, sitemap, robots, OG images, canonicals.
+- A11y: WCAG 2.2 AA audit + fixes; responsive QA across breakpoints.
+- **Exit:** budgets met on field-like data; SEO + a11y checklists green.
+
+### M4 — Handoff (always last)
+- Legal pages (privacy/terms/cookie); analytics + Sentry live; security pass (RLS, headers, env, MFA).
+- Custom domain + DNS; production deploy; post-deploy smoke.
+- Credentials handover, client walkthrough, repo archive, `/qualia-report` to ERP.
+- **Exit:** all DoD lines covered or explicitly waived with reason; client can operate it.
+
+## Notes
+- Gated content, user accounts, or a dashboard → this is no longer a `website`. Use `web-app` (adds auth + RLS-everywhere + app-quality DoD).
+- The Road is a default, not a cage. The roadmapper may merge M2/M3 for a 3-page site or split M2 for a 30-page one — but every DoD line still needs an owner.

package/rules/constitution.md

@@ -0,0 +1,42 @@
+---
+title: Qualia Constitution
+scope: org-level — inherited by every Qualia project
+updated: 2026-05-29
+---
+
+# Qualia Constitution
+
+> The top of the standards hierarchy. **Every Qualia project inherits these standards**, and they are **enforced at every increment's verify step** (`qualia-verify`, milestone close). Archetype Definitions of Done in `references/archetypes/*.md` *extend* this file — they add archetype-specific bars, never relax these. A senior should be able to read this in two minutes.
+
+## Supabase security (non-negotiable)
+
+- [ ] **RLS on every table**, with explicit policies. Verify by querying the table as two different users — each must see only their own rows.
+- [ ] **Authorize on `app_metadata`, never `user_metadata`.** `user_metadata` is user-editable and must never gate access.
+- [ ] **`service_role` key is server-only.** Never prefixed `NEXT_PUBLIC_`, never imported into a client component.
+- [ ] **Postgres views set `security_invoker = true`** — otherwise the view runs as its owner and bypasses the caller's RLS.
+- [ ] **Every `UPDATE` policy has a matching `SELECT` policy.** Without it, updates fail silently.
+- [ ] **Storage upsert needs `INSERT` + `SELECT` + `UPDATE`** policies on the bucket.
+- [ ] **Revoke a user's sessions before deleting the user** — deletion alone leaves issued JWTs valid until expiry.
+
+## Schema flow
+
+- [ ] **Local container → staging branch → production.** No manual schema edits on remote DBs.
+- [ ] **All schema changes are migrations** in `supabase/migrations/`, applied through CI — never hand-applied to a remote.
+
+## Gates over prompts
+
+Dangerous-command and architectural rules are enforced as **deterministic hooks**, not prose the model may forget. The framework already ships:
+
+- [ ] **`migration-guard`** — blocks schema edits that bypass `supabase/migrations/`.
+- [ ] **`supabase-destructive-guard`** — blocks destructive operations on remote DBs.
+- [ ] **`branch-guard`** — enforces feature-branch-only; main stays deployable.
+
+A rule worth enforcing is worth a hook. Add one rather than relying on instructions alone.
+
+## Context grounding
+
+- [ ] **Bundled, version-matched docs are the source of truth for stack APIs** — over model memory. When in doubt about a Supabase / Next.js / vendor API, read the pinned docs, don't recall from weights.
+
+---
+
+*This file contains only verified org standards. Archetype DoDs extend it; they do not override it.*

package/skills/qualia/SKILL.md

@@ -20,6 +20,8 @@ Read project state. Classify your situation. Tell you the exact next command.
 node ${QUALIA_BIN}/state.js check 2>/dev/null
 ```
 
+The JSON carries a `profile` field (`strict` or `standard`; env `$QUALIA_PROFILE` wins). `strict` = hard gates, no waivers; `standard` = gates advisory, a senior may waive with a reason logged to `.planning/decisions/`. Surface it when a gate is involved.
+
 Also gather context:
 ```bash
 test -f .continue-here.md && echo "HANDOFF_EXISTS" && head -20 .continue-here.md || echo "NO_HANDOFF"