qualia-framework 6.22.0 → 7.0.0

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.22.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",
@@ -34,12 +34,14 @@
     "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: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).

package/skills/qualia-build/SKILL.md

@@ -22,9 +22,40 @@ Execute phase plan. Each task = fresh subagent. Independent tasks run parallel.
 `/qualia-build {N}` — build specific phase
 `/qualia-build {N} --auto` — build + chain into `/qualia-verify {N} --auto` (no human gate)
 `/qualia-build {N} --parallel K` — cap concurrent builders at K (default auto: sequential under 3 tasks, else up to 5)
+`/qualia-build --batch` — the migration lane (R20): map-reduce a large mechanical change over a flat file list, NOT the phase-wave model. See below.
+
+## Batch lane (`--batch`) — large mechanical migrations
+
+The wave model fits a phase (a few dependency-linked tasks). It does NOT fit a
+50–500-file codemod (rename an API, swap a lib, change an import everywhere).
+For that, `--batch` is a map-reduce over files: small, file-disjoint workers in
+isolated worktrees, fanned in through ONE staging branch.
+
+```bash
+# 1. Resolve the target file list (the migration scope), one path per line:
+grep -rl 'oldApi(' src --include='*.ts' > /tmp/targets.txt
+# 2. Deterministic split into file-disjoint batches + concurrency-capped waves:
+node ${QUALIA_BIN}/batch-plan.js --from /tmp/targets.txt --batch-size 20 --max-workers 5 --staging batch/migrate-oldapi --json
+```
+
+`batch-plan.js` emits `batches[]` (each = a branch + its files — disjoint by
+construction) and `waves[]` (batch ids to run concurrently, capped at
+`--max-workers`). Then orchestrate:
+
+1. Create the staging branch from `main`: `git branch {staging_branch}`.
+2. For each wave, spawn one worker per batch **in its own worktree**
+   (`isolation: "worktree"`), each handed ONLY its `files[]` + the single
+   transformation rule. Small context per worker = no drift.
+3. Each worker applies the change to its files and commits to its `batch/…-NN`
+   branch. Workers in a wave are file-disjoint, so no conflicts.
+4. Fan in: merge each batch branch into `{staging_branch}`. Run the full test
+   suite on staging ONCE. Then `/qualia-ship` merges staging → main.
+5. A failed batch is isolated to its branch — re-run just that worker; the rest
+   proceed. Log any batch you drop (no silent partial migrations).
 
 ## Process
 
+
 ### 0. Set the work-unit goal
 
 Per `rules/codex-goal.md` — set the work-unit goal at phase start with scope `phase` (Codex `/goal`; on Claude Code, a tracked task + budget in the banner). One named objective + budget for the whole build.

package/skills/qualia-map/SKILL.md

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

package/skills/qualia-new/SKILL.md

@@ -285,6 +285,20 @@ Then fill the rest of DESIGN.md:
 
 Cross-check the result against `qualia-design/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
 
+**Per-client token registry (R10).** Compile DESIGN.md §2/§3/§4 into a CSS-variable
+registry so every builder inherits the real design system instead of inventing
+one (and the `ABS-HEX-IN-JSX` ban has a target to point at):
+
+```bash
+node ${QUALIA_BIN}/design-tokens.js init --out .planning/design-tokens.json   # starter; edit to the client's brand
+node ${QUALIA_BIN}/design-tokens.js compile .planning/design-tokens.json --out app/styles/tokens.css
+```
+
+`design-tokens.json` is the registry source of truth; `tokens.css` is the
+generated artifact the scaffold imports. Builders reference `var(--color-…)` /
+`var(--font-…)`, never a literal hex. Per `design-dials.md`, a client brand
+registry caps DESIGN_VARIANCE at LOW for color/type. See `design-reference.md`.
+
 ```bash
 git add .planning/DESIGN.md .planning/config.json
 git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"

package/skills/qualia-polish/SKILL.md

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

package/skills/qualia-recall/SKILL.md

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

package/skills/qualia-verify/SKILL.md

@@ -212,6 +212,14 @@ FAIL + gap_cycles >= limit → GAP_CYCLE_LIMIT, escalate.
 FAIL + gap_cycles < limit → `/qualia-plan {N} --gaps`.
 Do NOT edit STATE.md or tracking.json manually; state.js handles both.
 
+**Emit the lifecycle event** (R14 — feeds the ERP live run-tree). Signed, non-blocking, a no-op when ERP is disabled:
+
+```bash
+node ${QUALIA_BIN}/erp-event.js emit {verify_pass|verify_fail} --target project:{project} ${ERP_PROJECT_ID:+--project $ERP_PROJECT_ID}
+```
+
+Use `verify_pass` on PASS, `verify_fail` on FAIL. The same emitter serves other lifecycle points — `session_started` (session start), `phase_planned` (`/qualia-plan`), `build_wave_started` (`/qualia-build`) — all optional and queued through `erp-retry.js`, so they never block the session.
+
 Capture new state for auto-chain routing:
 
 ```bash

package/templates/DESIGN.md

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