qualia-framework 6.14.0 → 7.0.0

package/docs/erp-contract.md

@@ -77,6 +77,41 @@ many times each employee attempted to use proxy approval.
 ```
 Store by `(type, actor_code)` the same way so Fawzi sees a per-employee main-push tally. `client_report_id` is `QS-MAINPUSH-<actor_code>-<count>` and each post carries an idempotency key.
 
+### POST /api/v1/events (R14 — unified signed event log)
+
+The single endpoint for ALL CLI→ERP events: lifecycle/run events
+(`session_started`, `phase_planned`, `build_wave_started`, `verify_pass`,
+`verify_fail`, …) and, going forward, the policy events above. Emitted by
+`bin/erp-event.js` and queued through `erp-retry.js`.
+
+**Headers (Standard-Webhooks style):**
+```
+Authorization: Bearer <api-key>
+Content-Type: application/json
+Qualia-Event-Id:        <unique id — also the idempotency key>
+Qualia-Event-Timestamp: <unix seconds or ISO 8601>
+Qualia-Signature:       <base64 HMAC-SHA256 of `${id}.${timestamp}.${rawBody}`, keyed by the api-key; omit for unsigned>
+```
+
+**Body (the `FrameworkEvent`):**
+```json
+{
+  "action": "verify_pass",
+  "actor": { "code": "QS-FAWZI-11", "name": "Fawzi", "role": "OWNER" },
+  "targets": [{ "type": "project", "ref": "acme-portal" }],
+  "context": {},
+  "metadata": {},
+  "occurred_at": "2026-06-22T10:00:00.000Z",
+  "erp_project_id": "7b5d3b4e-…"
+}
+```
+
+The HMAC is keyed by the caller's `qlt_` token (the ERP holds only its hash but
+sees the plaintext Bearer per request), so body integrity + replay are verified
+with no extra secret. Server stores to an append-only `framework_events` table,
+idempotent on `Qualia-Event-Id`; unsigned posts are accepted but recorded
+`signature_valid=false`. Accepts `reports:write` or `events:write` scope.
+
 ### POST /api/v1/reports
 
 Upload a session report.
@@ -346,6 +381,151 @@ Snapshot shape:
 }
 ```
 
+## Project Sync Payload (reconciliation)
+
+`qualia-framework project-sync` builds the **single complete project-sync snapshot** — the one payload the ERP reads to RECONCILE a project's milestones, phases, tasks, and reports in one pass, and to understand the PR/merge model that maps a feature branch to deployed `main`.
+
+It is distinct from the two existing emitters:
+- `POST /api/v1/reports` (report-payload.js) = ONE work session.
+- `POST /api/v1/project-snapshots` (project-snapshot.js) = lean progress rollup for dashboards (`progress_percent`).
+- **project-sync** = the FULL reconciliation surface: every milestone with REQ-ID completion, current position, task rollup, accountability counters, and the trunk/merge model. project-sync **composes** project-snapshot's identity/current/journey/lifetime/quality blocks (no duplication) and enriches them.
+
+```text
+qualia-framework project-sync            # print JSON (compact) to stdout
+qualia-framework project-sync --json     # print JSON (pretty)
+qualia-framework project-sync --write    # persist .planning/snapshots/project-sync-<ts>.json
+```
+
+Exit 0 = built; exit 2 = no `.planning/` (run `/qualia-new`). Read-only, zero dependencies. Graceful when JOURNEY.md / REQUIREMENTS.md / fields are absent (milestones still emit, REQ blocks report `tracked: false`).
+
+### Payload shape
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-06-21T00:00:00.000Z",
+  "source": "qualia-framework",
+  "payload": "project-sync",
+  "framework_version": "6.14.0",
+  "identifiers": {
+    "project_id": "qs-acme-portal",
+    "team_id": "qualia-solutions",
+    "git_remote": "github.com/QualiasolutionsCY/acme-portal",
+    "erp_project_id": "7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef"
+  },
+  "project": {
+    "name": "acme-portal",
+    "client": "Acme",
+    "status": "built",
+    "deployed_url": "https://client.vercel.app",
+    "progress_percent": 42,
+    "lifecycle": "build",
+    "launched_at": "2026-05-01T00:00:00Z"
+  },
+  "current": {
+    "milestone": 2, "milestone_name": "Product",
+    "phase": 2, "phase_name": "Dashboard", "total_phases": 4,
+    "tasks_done": 3, "tasks_total": 5,
+    "verification": "pending", "gap_cycles": 1
+  },
+  "quality": { "harness_eval": { "status": "PASS", "score": 92, "phase": 2, "generated_at": "…", "artifact": "…" } },
+  "total_milestones": 3,
+  "milestones": [
+    {
+      "num": 1, "name": "Foundation", "status": "closed",
+      "phases": 3, "tasks_completed": 12,
+      "requirements": { "tracked": true, "total": 4, "complete": 4, "incomplete": [] },
+      "closed_at": "2026-04-10T18:00:00Z",
+      "deployed_url": "https://m1.vercel.app"
+    },
+    {
+      "num": 2, "name": "Product", "status": "current",
+      "phases": 4, "tasks_completed": 0,
+      "requirements": { "tracked": true, "total": 5, "complete": 3,
+        "incomplete": [ { "id": "CORE-03", "status": "Incomplete" } ] }
+    },
+    {
+      "num": 3, "name": "Handoff", "status": "future",
+      "phases": 0, "tasks_completed": 0,
+      "requirements": { "tracked": false, "total": 0, "complete": 0, "incomplete": [] }
+    }
+  ],
+  "task_rollup": {
+    "tasks_completed": 15, "phases_completed": 4, "milestones_completed": 1,
+    "total_phases_all_milestones": 7, "build_count": 4, "deploy_count": 1,
+    "current_phase_gap_cycles": 1
+  },
+  "accountability": {
+    "offroad_count": 2,
+    "offroad": [ { "at": "2026-06-01T10:00:00Z", "milestone": 2, "ref": "BUG-7", "note": "hotfix login" } ]
+  },
+  "integration": {
+    "model": "trunk",
+    "integrates_at": "/qualia-ship",
+    "protected_branches": ["main", "master"],
+    "main_push_event_type": "employee_main_push",
+    "main_push_events_path": "~/.claude/.main-push-events.json",
+    "note": "Feature branches integrate to main at /qualia-ship (then deploy). Direct pushes to a protected branch are allowed but recorded as employee_main_push policy events for per-employee accountability."
+  },
+  "timestamps": { "session_started_at": "", "last_pushed_at": "", "last_updated": "" }
+}
+```
+
+### Field meanings
+
+| Field | Meaning |
+|-------|---------|
+| `schema_version` | project-sync contract version. The ERP branches on this to evolve the shape safely. **Distinct** from `snapshot_version` (project-snapshot). |
+| `payload` | Always `"project-sync"` — discriminates this from the report / snapshot payloads when they share an endpoint or queue. |
+| `identifiers` | Same resolution block as project-snapshot — `erp_project_id` is the strongest link, then `git_remote`, then `(team_id, project_id)`. |
+| `project.lifecycle` | `build` (milestone journey) or `operate` (post-launch update stream). The ERP stops expecting a handoff for an `operate` project. |
+| `project.launched_at` / `launch_source` | Present once launched; lets the ERP date the build→operate transition. |
+| `current.*` | The active milestone/phase position + verification + flattened `gap_cycles` (number, current phase). |
+| `total_milestones` | Denominator for milestone-completion (from JOURNEY.md, else max known). |
+| `milestones[]` | The reconciliation spine — every known milestone (journey ∪ closed ∪ current), ordered by num. |
+| `milestones[].status` | `closed` \| `current` \| `future`. The ERP marks done / in-progress / pending from this. |
+| `milestones[].phases` | Phase count: `phases_completed` for closed milestones; the current roadmap phase count for the active one; 0 for future. |
+| `milestones[].tasks_completed` | Tasks completed within that milestone (closed summaries carry this; 0 for current/future — use `task_rollup` for cumulative). |
+| `milestones[].requirements` | REQ-ID completion from REQUIREMENTS.md: `tracked` (false ⇒ no REQ rows declared for this milestone, ERP skips the REQ gate), `total`, `complete`, `incomplete[]` (`{id, status}`). |
+| `milestones[].closed_at` / `deployed_url` | Present when the closed-milestone summary carries them. |
+| `task_rollup` | Cumulative counters so the ERP rolls tasks up without replaying every report: lifetime tasks/phases/milestones, `total_phases_all_milestones`, build/deploy counts, current-phase gap cycles. |
+| `accountability.offroad_count` | Count of off-milestone work units (mirrors the branch-guard main-push tally — drift is counted, not hidden). |
+| `accountability.offroad[]` | Last 10 off-road entries: `{at, milestone, ref, note}`. |
+| `integration` | The PR/merge model (see below). |
+
+### How the ERP reconciles from this payload
+
+1. **Resolve the project** via `identifiers` (same precedence as reports/snapshots).
+2. **Milestones** — upsert each `milestones[]` entry by `num`. Set the ERP milestone state from `status` (`closed`→done, `current`→in-progress, `future`→pending). When `requirements.tracked` is true, the milestone is **complete only if** `complete === total`; surface `incomplete[]` REQ-IDs as the remaining work. When `tracked` is false, fall back to `status` alone (no REQ table was declared).
+3. **Phases** — `milestones[].phases` + `current.total_phases` give per-milestone phase counts; `task_rollup.total_phases_all_milestones` is the grand total across the whole journey.
+4. **Tasks** — use `task_rollup.tasks_completed` for the cumulative figure and `milestones[].tasks_completed` for per-closed-milestone attribution. Do **not** sum reports to get this — the rollup is authoritative.
+5. **Reports** — project-sync does not carry session notes; it reconciles *state*, while `/api/v1/reports` carries each *session*. Reconcile both against the same resolved project: reports for the activity feed, project-sync for the milestone/phase/task tree.
+6. **Accountability** — store `offroad_count` per project so off-milestone drift is visible alongside the per-employee `employee_main_push` tally from `/api/v1/policy-events`.
+
+### PR / merge model (what the ERP must understand)
+
+The framework uses **trunk integration**, surfaced in `integration`:
+
+- Work happens on a **feature branch** (`branch-guard` enforces feature-branch-only; `main`/`master` are protected).
+- `/qualia-ship` **integrates the feature branch into `main`** and then deploys (`integrates_at: "/qualia-ship"`). There is no long-lived release branch; `main` is always the deployable trunk.
+- A direct push to a protected branch is **allowed, not blocked** — but `branch-guard` records an `employee_main_push` policy event (`POST /api/v1/policy-events`, keyed by `(type, actor_code)`) for per-employee accountability. The local journal lives at `main_push_events_path` (`~/.claude/.main-push-events.json`) in the install home; project-sync **references** it, it does not read across the home boundary.
+
+So the branch→main→deploy mapping the ERP should encode: **a milestone's `deployed_url` + `status: closed` means its feature work was integrated to `main` and shipped via `/qualia-ship`.** Main-push events are the exception trail, not the normal integration path.
+
+---
+
+## Framework emits (this repo) vs ERP ingests (backend — out of scope here)
+
+**Framework emits (delivered in this repo):**
+- `qualia-framework project-sync [--json|--write]` builds and (optionally) persists the payload above.
+- Deterministic, read-only, zero-dependency; composes project-snapshot; graceful on missing fields.
+- The payload SHAPE and field semantics documented in this section are the contract.
+
+**ERP ingests (backend work — NOT in this repo):**
+- A `POST /api/v1/project-sync` endpoint (or extend project-snapshots to accept `payload: "project-sync"`) that authenticates the Bearer key and validates `schema_version`.
+- Project resolution + the reconciliation logic in "How the ERP reconciles" above — upserting milestones/phases/tasks, marking completion from REQ counts, and storing `offroad_count`.
+- Wiring an upload path (the framework's `project-snapshot.js` already has `uploadSnapshot()`/retry plumbing the ERP team can mirror for project-sync once the endpoint exists). project-sync itself ships **emit + document** only; the HTTP upload + server-side ingest are the backend's to build.
+
 ## Behavior
 
 - When `erp.enabled` is `false`, `/qualia-report` skips the upload and prints an info line so the employee knows the report stayed local.

package/mcp/memory-mcp/server.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+// Qualia Memory MCP — read-only access to the Obsidian wiki at QUALIA_MEMORY_ROOT.
+// Zero dependencies. Implements MCP over stdio (JSON-RPC 2.0, line-delimited).
+//
+// Tools:
+//   memory.search(query, scope?)  — case-insensitive grep over wiki, returns hits with file:line
+//   memory.read(path)             — read a single file under wiki/ as text
+//   memory.list(folder?)          — list folder contents (one level), default = wiki root
+//
+// Safety:
+//   - All paths are resolved under QUALIA_MEMORY_ROOT/wiki and rejected if they escape it.
+//   - No write tools. Memory is curated by humans + qualia-framework SessionEnd hooks only.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const ROOT = process.env.QUALIA_MEMORY_ROOT || path.join(require("os").homedir(), "qualia-memory");
+const WIKI = path.join(ROOT, "wiki");
+
+// ─── Vault access control (shared with bin/recall.js) ─────
+// Honor wiki/_meta/access.md so a non-OWNER MCP client can't read OWNER_ONLY
+// paths. Same single implementation as recall.js; fail-closed if it can't load.
+let accessGuard = null;
+try {
+  accessGuard = require(path.join(__dirname, "..", "..", "bin", "vault-access.js"));
+} catch {
+  /* fall back to OWNER-only access below */
+}
+const ROLE = accessGuard ? accessGuard.resolveRole() : "RESTRICTED";
+function allowed(rel) {
+  return accessGuard ? accessGuard.isWikiPathAllowed(rel, ROLE, WIKI) : ROLE === "OWNER";
+}
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_INFO = { name: "qualia-memory", version: "0.1.0" };
+
+const TOOLS = [
+  {
+    name: "memory.search",
+    description:
+      "Case-insensitive search across the Qualia memory wiki. Returns matches as " +
+      "{ path, line, snippet }. Use this before /qualia-plan or /qualia-build to pull " +
+      "prior decisions, client preferences, and reusable patterns.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search term — plain text, no regex." },
+        scope: {
+          type: "string",
+          description:
+            "Optional subfolder of wiki/ to limit the search (e.g. 'concepts', 'entities', " +
+            "'sessions'). Omit to search the whole wiki.",
+        },
+        max_results: { type: "integer", description: "Cap on hits (default 30).", default: 30 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "memory.read",
+    description: "Read a single wiki page as text. Path is relative to wiki/ root.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative path under wiki/, e.g. 'concepts/llm-wiki.md'." },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "memory.list",
+    description: "List one level of contents (files + subfolders) under a wiki folder.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        folder: {
+          type: "string",
+          description: "Relative path under wiki/. Omit or '' for the wiki root.",
+        },
+      },
+    },
+  },
+];
+
+// ─── Path safety ──────────────────────────────────────────
+// Resolve `rel` under WIKI and refuse anything that escapes (.. tricks, abs paths).
+function safeResolve(rel) {
+  const resolved = path.resolve(WIKI, rel || ".");
+  if (resolved !== WIKI && !resolved.startsWith(WIKI + path.sep)) {
+    throw new Error(`Path escapes wiki root: ${rel}`);
+  }
+  return resolved;
+}
+
+// ─── Tool implementations ────────────────────────────────
+function toolSearch({ query, scope, max_results }) {
+  if (!query || typeof query !== "string") throw new Error("query is required");
+  const cap = Math.max(1, Math.min(200, Number(max_results) || 30));
+  const target = scope ? safeResolve(scope) : WIKI;
+  if (!fs.existsSync(target)) throw new Error(`Scope not found: ${scope}`);
+
+  // grep is universally available on POSIX; -r recursive, -n line numbers, -i case-insensitive.
+  // -F treats query as fixed string (no regex surprises). --include limits to text-ish files.
+  const r = spawnSync(
+    "grep",
+    [
+      "-rniF",
+      "--include=*.md",
+      "--include=*.txt",
+      "--include=*.canvas",
+      "--include=*.base",
+      "--",
+      query,
+      target,
+    ],
+    { encoding: "utf8", maxBuffer: 8 * 1024 * 1024, timeout: 10_000 },
+  );
+
+  if (r.status !== 0 && r.status !== 1) {
+    // status 1 = no matches (normal). Anything else is a real failure.
+    throw new Error(`grep failed: ${r.stderr || "exit " + r.status}`);
+  }
+
+  const hits = (r.stdout || "")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      // grep output: <abs_path>:<lineno>:<text>
+      const firstColon = line.indexOf(":");
+      const secondColon = line.indexOf(":", firstColon + 1);
+      if (firstColon < 0 || secondColon < 0) return null;
+      const abs = line.slice(0, firstColon);
+      const lineno = Number(line.slice(firstColon + 1, secondColon));
+      const snippet = line.slice(secondColon + 1).trim();
+      return {
+        path: path.relative(WIKI, abs),
+        line: lineno,
+        snippet: snippet.length > 240 ? snippet.slice(0, 240) + "…" : snippet,
+      };
+    })
+    .filter(Boolean)
+    .filter((h) => allowed(h.path)) // honor access.md BEFORE capping
+    .slice(0, cap);
+
+  return { query, scope: scope || null, total: hits.length, hits };
+}
+
+function toolRead({ path: rel }) {
+  if (!rel || typeof rel !== "string") throw new Error("path is required");
+  const abs = safeResolve(rel);
+  if (!allowed(path.relative(WIKI, abs))) {
+    throw new Error("That path is OWNER-only. Ask Fawzi if you need this.");
+  }
+  const stat = fs.statSync(abs);
+  if (!stat.isFile()) throw new Error(`Not a file: ${rel}`);
+  // Cap at 256KB so a runaway page doesn't blow the JSON-RPC frame.
+  const MAX = 256 * 1024;
+  let content = fs.readFileSync(abs, "utf8");
+  let truncated = false;
+  if (content.length > MAX) {
+    content = content.slice(0, MAX);
+    truncated = true;
+  }
+  return { path: rel, bytes: stat.size, truncated, content };
+}
+
+function toolList({ folder }) {
+  const target = safeResolve(folder || ".");
+  if (!fs.existsSync(target)) throw new Error(`Folder not found: ${folder || "(root)"}`);
+  const entries = fs.readdirSync(target, { withFileTypes: true });
+  return {
+    folder: path.relative(WIKI, target) || ".",
+    entries: entries
+      // hide OWNER_ONLY / CONDITIONAL entries from non-OWNER listings
+      .filter((e) => allowed(path.relative(WIKI, path.join(target, e.name))))
+      .map((e) => ({ name: e.name, type: e.isDirectory() ? "dir" : "file" }))
+      .sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type === "dir" ? -1 : 1)),
+  };
+}
+
+const TOOL_HANDLERS = {
+  "memory.search": toolSearch,
+  "memory.read": toolRead,
+  "memory.list": toolList,
+};
+
+// ─── MCP / JSON-RPC plumbing ──────────────────────────────
+function rpcResult(id, result) {
+  return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+function rpcError(id, code, message, data) {
+  return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message, ...(data && { data }) } });
+}
+
+function handleRequest(req) {
+  const { id, method, params } = req;
+  try {
+    if (method === "initialize") {
+      return rpcResult(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        serverInfo: SERVER_INFO,
+        capabilities: { tools: {} },
+      });
+    }
+    if (method === "tools/list") {
+      return rpcResult(id, { tools: TOOLS });
+    }
+    if (method === "tools/call") {
+      const { name, arguments: args } = params || {};
+      const handler = TOOL_HANDLERS[name];
+      if (!handler) return rpcError(id, -32601, `Unknown tool: ${name}`);
+      const out = handler(args || {});
+      return rpcResult(id, {
+        content: [{ type: "text", text: JSON.stringify(out, null, 2) }],
+      });
+    }
+    if (method === "notifications/initialized" || method === "notifications/cancelled") {
+      return null; // notifications get no response
+    }
+    return rpcError(id, -32601, `Unknown method: ${method}`);
+  } catch (err) {
+    return rpcError(id, -32000, err.message || String(err));
+  }
+}
+
+// ─── stdio loop ───────────────────────────────────────────
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let nl;
+  while ((nl = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, nl).trim();
+    buffer = buffer.slice(nl + 1);
+    if (!line) continue;
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch (err) {
+      process.stdout.write(rpcError(null, -32700, "Parse error: " + err.message) + "\n");
+      continue;
+    }
+    const out = handleRequest(req);
+    if (out !== null) process.stdout.write(out + "\n");
+  }
+});
+
+process.stdin.on("end", () => process.exit(0));
+
+// Surface root config on startup so misconfigured installs are visible in MCP logs.
+process.stderr.write(`[qualia-memory] wiki root: ${WIKI}\n`);
+if (!fs.existsSync(WIKI)) {
+  process.stderr.write(
+    `[qualia-memory] WARNING: wiki root does not exist. Set QUALIA_MEMORY_ROOT or create ${ROOT}/wiki/.\n`,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.14.0",
+  "version": "7.0.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -23,7 +23,7 @@
   },
   "homepage": "https://github.com/Qualiasolutions/qualia-framework#readme",
   "scripts": {
-    "test": "npm run test:shell",
+    "test": "npm run test:shell && npm run test:node",
     "test:state": "bash tests/state.test.sh",
     "test:hooks": "bash tests/hooks.test.sh",
     "test:bin": "bash tests/bin.test.sh",
@@ -33,12 +33,15 @@
     "test:statusline": "bash tests/statusline.test.sh",
     "test:refs": "bash tests/refs.test.sh",
     "test:published-install": "bash tests/published-install-smoke.test.sh",
-    "test:shell": "bash tests/run-all.sh"
+    "test:shell": "bash tests/run-all.sh",
+    "test:node": "node --test tests/runner.js",
+    "compile:instructions": "node bin/compile-instructions.js"
   },
   "files": [
     "bin/",
     "agents/",
     "hooks/",
+    "mcp/",
     "rules/",
     "qualia-design/",
     "skills/",

package/qualia-design/design-dials.md

@@ -0,0 +1,72 @@
+# Design Dials + Negative-Constraint Pre-Flight
+
+Loaded by `/qualia-polish` (Stage 0) and read when generating any DESIGN.md.
+Two jobs: (1) three tunable **dials** that set a project's aesthetic risk budget,
+(2) a **pre-flight ban-list with positive alternatives** that breaks the model's
+default "AI slop" trajectory *before* code is written — not after, where
+`slop-detect.mjs` catches what slipped through.
+
+> Why pre-flight beats post-hoc: a ban paired with a *positive* alternative
+> ("don't do X — do Y instead") steers generation. A bare ban ("don't do X") is
+> the pink-elephant backfire — the model fixates on X. Always pair.
+
+---
+
+## 1. The three dials
+
+Each dial is `LOW | MEDIUM | HIGH`. Set them in DESIGN.md §0; gate them by
+**register + project type** (see §3). The dials are intent, not enforcement —
+they tell a builder/polish agent how much aesthetic risk the project wants.
+
+| Dial | LOW | MEDIUM | HIGH |
+|---|---|---|---|
+| **DESIGN_VARIANCE** — how far from convention | Conventional, safe, familiar layouts. Respect existing/client tokens exactly. | One signature move per screen; otherwise conventional. | Editorial/experimental layouts, asymmetry, unexpected grids. Earns attention. |
+| **MOTION_INTENSITY** — how much movement | Functional only (focus, state). No decorative motion. `prefers-reduced-motion` honored. | Purposeful entrance/transition on key elements. | Signature motion as identity (Brand register only) — orchestrated, still ≤ budget. |
+| **VISUAL_DENSITY** — information per screen | Generous whitespace, few elements, one idea per screen. | Balanced; grouped sections. | Dense, dashboard-grade; every pixel earns its place. |
+
+A builder reads the resolved values and makes choices *within* that budget. A
+HIGH on every dial is not "better" — it's a different, riskier product.
+
+---
+
+## 2. Pre-flight ban-list (ban → do instead)
+
+Read this BEFORE writing any component or token. Each ban mirrors a
+`slop-detect.mjs` rule (the deterministic post-hoc gate) — this is the
+generation-time half of the same contract, with the positive alternative the
+scanner can't give you.
+
+| Ban (the slop tell) | Do instead |
+|---|---|
+| `Inter` / `system-ui` / `Arial` as the brand face | The project's chosen typeface (DESIGN.md §3) with ≥2 weights; a real type pairing |
+| Purple→blue/pink hero gradient | The brand palette from DESIGN.md §2 (OKLCH); a single committed accent |
+| Gradient *text* | Solid ink at AA contrast; reserve color for one accent moment |
+| Pure `#000` on pure `#fff` | Near-black on warm/cool off-white from the token scale (§2) |
+| Hardcoded hex in JSX | A CSS variable / token (the per-client registry — see design-reference) |
+| Glassmorphism (`backdrop-blur` everywhere) | Solid surfaces with real elevation tokens (DESIGN.md §6) |
+| `card-grid` of identical rounded boxes | A layout with hierarchy — feature one item, vary span/scale |
+| Spring/bounce easing as the default | Calm `ease-out` / project easing tokens (DESIGN.md §7); bounce only as a Brand signature |
+| `outline: none` with no replacement | A visible `:focus-visible` ring (accessibility, non-negotiable) |
+| Generic CTA copy ("Get Started", "Learn More") | Specific, product-true microcopy (rubric dim 7) |
+
+When VISUAL_DENSITY=HIGH the whitespace ban relaxes; when MOTION_INTENSITY=LOW
+the motion alternatives default to "none." The dials tune the list; they never
+unlock a hard accessibility ban (focus ring, alt text, contrast).
+
+---
+
+## 3. Gating by register + project type (don't fight client tokens)
+
+The dials default by what the project IS — a corporate client's app must not get
+HIGH variance that overrides their brand system:
+
+| Project type | VARIANCE | MOTION | DENSITY | Note |
+|---|---|---|---|---|
+| Client app on an existing brand system | LOW | LOW–MED | per product | Respect their tokens; the per-client registry (design-reference) is law. |
+| Internal tool / admin / dashboard | LOW | LOW | HIGH | Clarity over flair; dense is correct. |
+| Greenfield product (Product register) | MEDIUM | MEDIUM | MEDIUM | One signature move; earn the rest. |
+| Marketing / landing / portfolio (Brand register) | HIGH | HIGH | LOW–MED | Attention is the job; signature motion allowed. |
+
+If a client ships a design-token registry, **VARIANCE is capped at LOW for
+color/type** regardless of register — you may be expressive with layout/motion,
+never with their palette or face. See `design-reference.md`.

package/qualia-design/design-reference.md

@@ -178,3 +178,27 @@ When building reusable components:
 - Explicit variants: `<Alert.Destructive>` instead of `<Alert isDestructive>`
 - Children over render props: `children` for composition, not `renderHeader`/`renderFooter`
 - React 19: use `use()` instead of `useContext()`, skip `forwardRef` (ref is a regular prop)
+
+## Per-Client Token Registry (R10)
+
+The proven escape from AI design monoculture: ground generation in a real design
+system — first-party brand tokens as CSS custom properties — not each builder's
+invented palette.
+
+- **Source of truth:** `.planning/design-tokens.json` (the client's brand —
+  colors in OKLCH, type stack, radius, spacing). Generated by `/qualia-new` and
+  edited to the client.
+- **Artifact:** `app/styles/tokens.css` (or the stack's equivalent), compiled by
+  `bin/design-tokens.js compile`. A `:root { --color-…; --font-…; … }` block.
+- **The contract for builders:** reference `var(--color-accent)` /
+  `var(--font-sans)` — NEVER a literal hex (`ABS-HEX-IN-JSX` slop ban). The
+  registry is the only place brand values live; swap the JSON, recompile, the
+  whole app re-skins.
+- **Dial gating:** a client brand registry caps `DESIGN_VARIANCE` at LOW for
+  color/type (`design-dials.md` §3) — be expressive with layout/motion, never
+  with their palette or face.
+
+```bash
+node bin/design-tokens.js init --out .planning/design-tokens.json
+node bin/design-tokens.js compile .planning/design-tokens.json --out app/styles/tokens.css
+```

package/rules/access.md

@@ -0,0 +1,42 @@
+# Vault Access (security-critical)
+
+Governs every read of the `~/qualia-memory/` vault — by `/qualia-recall`, by any
+skill or agent that greps the vault, and by direct `Read`/`Grep`/`Bash` calls.
+The single source of truth for *which* paths are sensitive is the vault's own
+manifest at `~/qualia-memory/wiki/_meta/access.md`. This rule says how to honor it.
+
+## The rule
+
+Role is read from `~/.claude/.qualia-config.json` (`role` field). When
+`role != OWNER`, paths the manifest lists as **OWNER_ONLY** or **CONDITIONAL**
+MUST NOT be read, grepped, listed, or summarized:
+
+- `Finances/` — live invoicing, VAT, outstanding balances
+- `Clients/*.md` — rates, contacts, Zoho IDs, billing addresses
+- `Team/*.md` — compensation / performance context
+- `raw/sessions/` — verbatim session logs (commercial + internal decisions)
+- `memory/` — personal AI context layer
+- `wiki/_meta/access.md` — the manifest itself (prevents trivial bypass)
+- CONDITIONAL (DEFAULT DENY for non-OWNER): `Projects/*.md`, `wiki/sessions/qa/`
+
+**ALL_ROLES** paths (`wiki/concepts/`, `wiki/entities/`, `wiki/analysis/`,
+`Research/`, navigational pages, etc.) are open to every authenticated user.
+
+When following `[[wikilinks]]` out of ALL_ROLES content INTO an OWNER_ONLY path,
+**stop at the boundary** — do not follow the link.
+
+On refusal, say plainly: *"That path is OWNER-only. Ask Fawzi if you need this."*
+
+## Deterministic enforcement (don't rely on this prose alone)
+
+`${QUALIA_BIN}/recall.js` enforces the manifest in code: it parses
+`wiki/_meta/access.md`, resolves the role, and filters OWNER_ONLY / CONDITIONAL
+vault hits for non-OWNER callers (fail-closed on unknown role). **Prefer
+`/qualia-recall` (or `recall.js`) over hand-rolled `grep ~/qualia-memory`** — the
+tool can't forget the policy the way a prompt can. "A rule worth enforcing is
+worth a gate" (constitution).
+
+## When this rule applies
+
+Always-on for any session that may touch `~/qualia-memory/`. If the vault does not
+exist on the machine, this rule is inert. OWNER role ⇒ full access (no filtering).