qualia-framework 6.3.0 → 6.5.0

package/hooks/pre-compact.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-compact.js — snapshot in-flight session context to
+// .planning/.compaction-snapshot.md so /qualia-resume (or the next session)
+// can surface what was active when compaction wiped the conversation.
+//
+// PreCompact hook (fires before Claude Code compacts the context window).
+//
+// Why this hook returned in v6.3.2:
+//   v6.2.0 removed the original pre-compact.js because it created BOT COMMITS
+//   to stamp STATE.md / tracking.json. That was the wrong mechanism —
+//   state.js's atomic write + journal already gives crash safety. This v2
+//   hook does NOT touch git, does NOT touch tracking.json, does NOT write
+//   through state.js. It only writes to a sidecar file that survives
+//   compaction and tells the next session "here's what was in flight".
+//
+// Design constraints (same shape as stop-session-log.js):
+//   • NEVER block — exit 0 always, even on internal failure.
+//   • Fast — under 200ms, no network, no LLM call.
+//   • No PII / secrets — file paths, commit subjects, phase numbers only.
+//   • Idempotent — overwrites the sidecar on every fire; we only care
+//     about the LATEST pre-compaction state.
+//   • No git commits, no state.js mutations.
+//
+// Sidecar format (.planning/.compaction-snapshot.md):
+//   # Pre-compaction snapshot — {ISO timestamp}
+//   ## State
+//   Phase: 2 of 4 — built
+//   ## Work in flight
+//   - 3 modified files (uncommitted)
+//   - foo.ts, bar.ts, baz.test.ts
+//   ## Recent commits (last 5)
+//   - abc1234 feat: implement signin
+//   - def5678 test: signin happy path
+//   ## Active planning artifacts
+//   - .planning/phase-2-plan.md (modified 14m ago)
+//   - .planning/phase-2-verification.md (modified 3h ago)
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(require("os").homedir(), ".claude");
+}
+
+function _trace(result, extra) {
+  try {
+    const traceDir = path.join(qualiaHome(), ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    fs.appendFileSync(
+      path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`),
+      JSON.stringify({
+        hook: "pre-compact",
+        result,
+        timestamp: new Date().toISOString(),
+        duration_ms: Date.now() - _traceStart,
+        ...extra,
+      }) + "\n",
+    );
+  } catch {}
+}
+
+function git(args, opts = {}) {
+  try {
+    const r = spawnSync("git", args, {
+      encoding: "utf8",
+      timeout: 2000,
+      shell: process.platform === "win32",
+      ...opts,
+    });
+    if (r.status !== 0) return "";
+    return (r.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function safeStatM(p) {
+  try { return fs.statSync(p).mtimeMs; } catch { return 0; }
+}
+
+function humanAge(ms) {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s ago`;
+  if (ms < 3600_000) return `${Math.round(ms / 60_000)}m ago`;
+  if (ms < 86_400_000) return `${Math.round(ms / 3600_000)}h ago`;
+  return `${Math.round(ms / 86_400_000)}d ago`;
+}
+
+try {
+  const cwd = process.cwd();
+  const repoRoot = git(["rev-parse", "--show-toplevel"], { cwd }) || cwd;
+  const planningDir = path.join(repoRoot, ".planning");
+
+  // Skip if not a Qualia project (no .planning/ dir) — nothing to snapshot.
+  if (!fs.existsSync(planningDir)) {
+    _trace("skip", { reason: "no-planning-dir" });
+    process.exit(0);
+  }
+
+  const now = Date.now();
+  const tracking = readJson(path.join(planningDir, "tracking.json")) || {};
+  const stateText = (() => {
+    try { return fs.readFileSync(path.join(planningDir, "STATE.md"), "utf8"); }
+    catch { return ""; }
+  })();
+
+  // State header line (one line from STATE.md, or fall back to tracking.json).
+  const stateLine = (() => {
+    const phaseLine = stateText.split("\n").find((l) => /^Phase:/i.test(l));
+    const statusLine = stateText.split("\n").find((l) => /^Status:/i.test(l));
+    if (phaseLine || statusLine) return [phaseLine, statusLine].filter(Boolean).join(" — ");
+    const p = tracking.phase || "?";
+    const total = tracking.total_phases || tracking.phase_total || "?";
+    const status = tracking.status || "?";
+    return `Phase: ${p} of ${total} — ${status}`;
+  })();
+
+  // Work in flight: uncommitted modified files.
+  const modified = (() => {
+    const out = git(["diff", "--name-only", "HEAD"], { cwd: repoRoot });
+    return out ? out.split("\n").filter(Boolean) : [];
+  })();
+  const staged = (() => {
+    const out = git(["diff", "--name-only", "--cached"], { cwd: repoRoot });
+    return out ? out.split("\n").filter(Boolean) : [];
+  })();
+  const inFlight = [...new Set([...modified, ...staged])].slice(0, 10);
+
+  // Recent commits — last 5, single-line.
+  const recentCommits = (() => {
+    const out = git(["log", "--pretty=%h %s", "-5"], { cwd: repoRoot });
+    return out ? out.split("\n").filter(Boolean) : [];
+  })();
+
+  // Active planning artifacts: phase-*-* files modified in last 24h.
+  const activePlanning = (() => {
+    try {
+      const files = fs.readdirSync(planningDir).filter((f) => /^phase-\d+/.test(f) && f.endsWith(".md"));
+      const day = 24 * 3600_000;
+      return files
+        .map((f) => ({ name: f, age: now - safeStatM(path.join(planningDir, f)) }))
+        .filter((x) => x.age < day)
+        .sort((a, b) => a.age - b.age)
+        .slice(0, 5);
+    } catch { return []; }
+  })();
+
+  // Open deviations / verification FAILs in current phase.
+  const phaseNum = tracking.phase || 0;
+  const verifyFails = (() => {
+    if (!phaseNum) return [];
+    const vPath = path.join(planningDir, `phase-${phaseNum}-verification.md`);
+    if (!fs.existsSync(vPath)) return [];
+    try {
+      const v = fs.readFileSync(vPath, "utf8");
+      const fails = (v.match(/^[^\n]*\bFAIL\b[^\n]*$/gm) || []).slice(0, 5);
+      const insufficient = (v.match(/^[^\n]*INSUFFICIENT EVIDENCE[^\n]*$/gm) || []).slice(0, 3);
+      return [...fails, ...insufficient];
+    } catch { return []; }
+  })();
+
+  // Compose snapshot. Markdown so the next session can render it as-is.
+  const ts = new Date().toISOString();
+  const lines = [
+    `# Pre-compaction snapshot — ${ts}`,
+    "",
+    "_Written by `hooks/pre-compact.js` immediately before Claude Code compacted the context window. `/qualia-resume` and session-start surface this so the next session sees what was active._",
+    "",
+    "## State",
+    stateLine || "(no state info)",
+    "",
+  ];
+
+  lines.push("## Work in flight");
+  if (inFlight.length === 0) {
+    lines.push("(no uncommitted changes)");
+  } else {
+    lines.push(`${inFlight.length} file(s):`);
+    for (const f of inFlight) lines.push(`- ${f}`);
+  }
+  lines.push("");
+
+  lines.push("## Recent commits");
+  if (recentCommits.length === 0) {
+    lines.push("(no commit history)");
+  } else {
+    for (const c of recentCommits) lines.push(`- ${c}`);
+  }
+  lines.push("");
+
+  lines.push("## Active planning artifacts (modified in last 24h)");
+  if (activePlanning.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const p of activePlanning) lines.push(`- ${p.name} — ${humanAge(p.age)}`);
+  }
+  lines.push("");
+
+  if (verifyFails.length > 0) {
+    lines.push("## Open verification issues");
+    for (const f of verifyFails) lines.push(`- ${f.trim()}`);
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("_Sidecar file. Not committed to git. Read by `/qualia-resume` and `session-start` to restore in-flight context after compaction._");
+
+  fs.writeFileSync(path.join(planningDir, ".compaction-snapshot.md"), lines.join("\n") + "\n");
+  _trace("snapshot", {
+    in_flight: inFlight.length,
+    commits: recentCommits.length,
+    active_planning: activePlanning.length,
+    verify_fails: verifyFails.length,
+  });
+  process.exit(0);
+} catch (err) {
+  _trace("error", { error: err && err.message ? err.message : String(err) });
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.3.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

@@ -1,6 +1,6 @@
 ---
 name: qualia
-description: "Smart router — reads project state (state.js), classifies the situation mechanically, and either returns the exact next command or performs the lightweight diagnosis previously split across helper commands. Use whenever you type /qualia, 'what next', 'next', 'what now', 'what should I do next', 'what command now', 'resume', 'pause', or 'I don't know what is going on'."
+description: "Mechanical state-driven router — reads state.js, returns the exact next command. Cheap and instant. Triggers: '/qualia', 'what next', 'what now'. For deeper situational confusion use /qualia-idk."
 allowed-tools:
   - Bash
   - Read
@@ -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"

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-build
-description: "Executes a planned phase by spawning fresh builder subagents per task with wave-based parallelization. Each task gets isolated context, commits atomically, and runs its own validation. Use when the user says 'build this phase', 'execute the plan', 'start building', 'run the build', 'qualia-build', or after /qualia-plan approves a phase plan."
+description: "Execute a planned phase — fresh builder subagents per task, wave-based parallelization, atomic commits, per-task validation. Triggers: 'build this phase', 'execute the plan', 'start building', 'qualia-build'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-discuss
-description: "Alignment interview. Two modes. PROJECT MODE (default, no args) is the non-technical kickoff before /qualia-new — 8 questions for demo projects, 14 for full projects, output is .planning/project-discovery.md. PHASE MODE (with N arg, e.g. /qualia-discuss 2) is the technical aggressive grilling before /qualia-plan N — one question at a time with recommended answer, output is .planning/phase-{N}-context.md. Trigger phrases: 'discuss', 'kickoff interview', 'grill me', 'stress test this plan', 'wait let's think about this one', 'I'm not sure how to approach this'."
+description: "Alignment interview — PROJECT MODE before /qualia-new, PHASE MODE before /qualia-plan N. Triggers: 'discuss', 'kickoff interview', 'grill me', 'stress test this plan', 'I'm not sure how to approach this'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-doctor
-description: "Employee-facing framework health check. Wraps `qualia-framework doctor`, checks install targets, project state, contract coverage, planning-folder hygiene, hooks, memory, ERP queue health, and gives safe repair commands. Trigger on 'doctor', 'health check', 'framework broken', 'is Qualia installed correctly', 'Codex not picking up Qualia', 'hooks not running', 'memory broken', 'ERP queue stuck', '.planning messy'."
+description: "Framework health check — install, project state, contracts, hooks, memory, ERP queue. Suggests safe repair commands. Triggers: 'doctor', 'health check', 'framework broken', 'hooks not running', 'ERP queue stuck'."
 allowed-tools:
   - Bash
   - Read