qualia-framework 4.5.0 → 5.3.0

package/hooks/vercel-account-guard.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/vercel-account-guard.js — block deploys from wrong Vercel account.
+//
+// PreToolUse hook on `Bash`. Reads the proposed command from the Claude Code
+// hook payload (stdin JSON: tool_input.command) and exits 2 to BLOCK, 0 to
+// allow. Triggers only when the command matches `vercel --prod` or `vercel deploy`.
+//
+// Allowed teams are read from ~/.claude/.vercel-allowed-teams (one slug per
+// line, mode 0600). Missing config file = fail-open with stderr warning.
+//
+// Cross-platform (Windows/macOS/Linux). No external dependencies.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+function _trace(result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: "vercel-account-guard",
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+// Read hook payload from stdin.
+let command = "";
+try {
+  if (!process.stdin.isTTY) {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw) command = (JSON.parse(raw).tool_input || {}).command || "";
+  }
+} catch {}
+
+if (!command) {
+  _trace("allow", { reason: "no-command" });
+  process.exit(0);
+}
+
+// Only act on vercel deploy commands.
+if (!/vercel\s+(--prod|deploy)/.test(command)) {
+  _trace("allow", { reason: "not-vercel-deploy" });
+  process.exit(0);
+}
+
+// Read allowed teams (one slug per line).
+const teamsFile = path.join(os.homedir(), ".claude", ".vercel-allowed-teams");
+let allowed;
+try {
+  allowed = fs.readFileSync(teamsFile, "utf8").split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+} catch {
+  allowed = [];
+}
+if (allowed.length === 0) {
+  console.error("No .vercel-allowed-teams configured -- skipping account check");
+  _trace("skipped", { reason: "no-config" });
+  process.exit(0);
+}
+
+// Run `vercel whoami` to get the active account (fail-open on error).
+const r = spawnSync("vercel", ["whoami"], {
+  encoding: "utf8", timeout: 5000, shell: process.platform === "win32",
+});
+const actual = ((r.status === 0 && !r.error) ? (r.stdout || "") : "").trim();
+if (!actual) {
+  console.error("vercel whoami failed or empty -- skipping account check");
+  _trace("skipped", { reason: "whoami-unavailable" });
+  process.exit(0);
+}
+
+if (allowed.includes(actual)) {
+  _trace("allow", { actual, allowed_count: allowed.length });
+  process.exit(0);
+}
+
+// Block: wrong account.
+const msg = `BLOCKED: Wrong Vercel account/team. Active: '${actual}'. Allowed: ${allowed.join(", ")}. Run \`vercel switch ${allowed[0]}\` first, or add this team to ~/.claude/.vercel-allowed-teams.`;
+console.error(msg);
+console.log(msg);
+_trace("block", { actual, allowed_count: allowed.length, reason: "wrong-account" });
+process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "4.5.0",
+  "version": "5.3.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -42,6 +42,7 @@
     "tests/",
     "docs/",
     "CLAUDE.md",
+    "AGENTS.md",
     "guide.md"
   ],
   "engines": {

package/rules/design-brand.md

@@ -1,3 +1,7 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
 # Design — Brand register
 
 **When this register applies:** marketing pages, landing pages, campaign sites, portfolios, brand microsites, anything where the design IS the product.

package/rules/design-laws.md

@@ -1,3 +1,7 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
 # Design Laws
 
 The non-negotiable rules every Qualia frontend honors. Both registers (Brand and Product) inherit from this file. Skip nothing.

package/rules/design-product.md

@@ -1,3 +1,7 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
 # Design — Product register
 
 **When this register applies:** app UI, admin consoles, dashboards, internal tools, settings pages, anything where the design SERVES the product.

package/rules/design-rubric.md

@@ -1,3 +1,7 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "*.html", "*.vue", "*.svelte"]
+---
+
 # Design Rubric
 
 Anchored 1-5 scoring across 8 dimensions. Used by the verifier agent to score frontend phases. Used by `/qualia-polish --critique` for read-only audits.

package/rules/grounding.md

@@ -1,3 +1,7 @@
+---
+globs: ["agents/**", "skills/**"]
+---
+
 # Grounding Protocol & Rubrics
 
 Shared quality standards for every Qualia skill and subagent. Reference from every SKILL.md and agent prompt that produces findings, scores, or recommendations.

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-build
-description: "Execute the current phase — spawns builder subagents per task with wave-based parallelization. Fresh context per task."
+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."
 allowed-tools:
   - Bash
   - Read
@@ -15,12 +15,12 @@ allowed-tools:
 
 # /qualia-build — Build a Phase
 
-Execute the phase plan. Each task runs in a fresh subagent context. Independent tasks run in parallel.
+Execute phase plan. Each task = fresh subagent. Independent tasks run parallel.
 
 ## Usage
-`/qualia-build` — build the current planned phase
+`/qualia-build` — build current planned phase
 `/qualia-build {N}` — build specific phase
-`/qualia-build {N} --auto` — build + chain into `/qualia-verify {N} --auto` when done (no human gate between build and verify)
+`/qualia-build {N} --auto` — build + chain into `/qualia-verify {N} --auto` (no human gate)
 
 ## Process
 
@@ -30,11 +30,11 @@ Execute the phase plan. Each task runs in a fresh subagent context. Independent
 cat .planning/phase-{N}-plan.md
 ```
 
-Parse: tasks, waves, file references.
+Parse tasks, waves, file refs.
 
-### 1b. Create Recovery Reference
+### 1b. Recovery Reference
 
-Before executing any tasks, record current HEAD for diagnosis. This is a reference, not an automatic rollback instruction.
+Tag HEAD before executing. Reference only, no auto-rollback.
 
 ```bash
 git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
@@ -44,7 +44,7 @@ git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
 node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
 ```
 
-If a wave fails, stop and inspect `git status` plus the failed task output. Do not run destructive rollback commands automatically. Preserve user work, then either fix forward or ask before reverting specific files.
+Wave fail → stop, inspect status + output. Preserve work; fix forward or ask before reverting.
 ```bash
 git status --short
 git diff --stat
@@ -62,33 +62,32 @@ node ~/.claude/bin/qualia-ui.js banner build {N} "{phase name}"
 node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
 ```
 
-**For each task in the wave — spawn ALL tasks in this wave as separate `Agent()` calls in the SAME response turn so the harness executes them concurrently. Do NOT await one task before spawning the next. Sequential spawning defeats wave parallelism.**
+**Per task in wave: spawn ALL as separate `Agent()` calls in SAME turn (concurrent). Do NOT await one before spawning next.**
 
 ```bash
 node ~/.claude/bin/qualia-ui.js task {task_num} "{task title}"
 ```
 
-**Pre-inline context before spawning** (saves 3-5 Read calls inside each builder subagent — GSD-style dispatch):
+**Pre-inline context** (saves 3-5 Read calls per builder):
 
-1. Parse the task's `Context:` field to get `@file` references
+1. Parse task `Context:` → `@file` refs
 2. Read PROJECT.md
-3. Read DESIGN.md if any file in the task is `.tsx`, `.jsx`, `.css`, `.scss`
-4. Read each `@file` referenced in Context
-5. Inline all of the above into the agent prompt under `<pre-loaded-context>` so the builder starts with full context
+3. Read DESIGN.md if task touches `.tsx`/`.jsx`/`.css`/`.scss`
+4. Read each `@file` from Context
+5. Inline all into prompt under `<pre-loaded-context>`
 
-Spawn a fresh builder subagent:
+Spawn builder:
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/builder.md
-Grounding + rubrics: @~/.claude/rules/grounding.md
+Role: @~/.claude/agents/builder.md
 
 <phase_context>
 # PROJECT.md
-{inlined contents of .planning/PROJECT.md}
+{inlined .planning/PROJECT.md}
 
 # DESIGN.md (if frontend task)
-{inlined contents of .planning/DESIGN.md}
+{inlined .planning/DESIGN.md}
 </phase_context>
 
 <task_context>
@@ -97,40 +96,35 @@ Grounding + rubrics: @~/.claude/rules/grounding.md
 </task_context>
 
 <wave_context>
-Other tasks in Wave {W} (running in parallel, do NOT touch their files):
-- Task {N}: "{title}" — files: {comma-separated Files list}
-- Task {M}: "{title}" — files: {comma-separated Files list}
-(If you are the only task in this wave, omit this block.)
+Parallel tasks Wave {W} (do NOT touch their files):
+- Task {N}: {title} -- files: {files}
+- Task {M}: {title} -- files: {files}
+(Omit if sole task in wave.)
 </wave_context>
 
 <task>
-{paste the single task block from the plan — title, wave, persona, files, depends-on, why, acceptance-criteria, action, validation, context}
+{task block from plan: title, wave, persona, files, depends-on, why, AC, action, validation, context}
 </task>
 
-All files in <phase_context> and <task_context> are already in your working memory — do NOT re-Read them. Only Read files NOT inlined (project code you need to modify).
-
-Execute the task. Commit when done. Return DONE/BLOCKED/PARTIAL per your Output Contract.
+Context tags already loaded. Only Read project code you modify.
+Execute. Commit. Return DONE/BLOCKED/PARTIAL.
 ", subagent_type="qualia-builder", description="Task {N}: {title}")
 ```
 
-**Why this ordering (cache-aware):** The role + grounding.md (session-stable) comes FIRST, phase_context (stable across every task in the phase) comes SECOND, task_context (varies per task) comes LAST. This preserves prefix-cache hits across tasks in the same wave — Anthropic prompt caching matches byte-identical prefixes, and a stable prefix of ~2-5k tokens hits at 92% rate (Claude Code benchmark). Sequential pre-inline without this split breaks cache on every task.
-
-**Why pre-inline at all:** without it, the builder's first actions are 3-5 Read tool calls to orient itself. With pre-inline, the builder starts already oriented and spends its context budget on the actual task.
+**Cache ordering:** Role + grounding FIRST, phase_context SECOND, task_context LAST. Stable prefix ~2-5k tokens → 92% cache hit. Pre-inline eliminates 3-5 Read calls per builder.
 
-**After each task completes:**
-- Verify the commit exists: `git log --oneline -1`
-- Show result:
+**After each task:**
+- Verify commit: `git log --oneline -1`
+- Show:
 ```bash
 node ~/.claude/bin/qualia-ui.js done {task_num} "{title}" {commit_hash}
 ```
 
-**After each wave completes:**
-- Move to next wave
-- Show wave summary
+**After each wave:** move to next, show summary.
 
 ### 3. Wave Completion
 
-After all waves complete:
+All waves done:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider
@@ -141,30 +135,30 @@ node ~/.claude/bin/qualia-ui.js ok "Waves: {count}"
 
 ### 4. Handle Failures
 
-If a builder subagent returns a deviation or blocker:
-- **Minor deviation:** Log it, continue
-- **Major deviation:** Show to employee, ask how to proceed
-- **Blocker:** Show the blocker, suggest fix or escalation
+Builder returns deviation/blocker:
+- **Minor:** Log, continue
+- **Major:** Show to employee, ask how to proceed
+- **Blocker:** Show, suggest fix or escalation
 
 ### 5. Update State
 
 ```bash
 node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done} --tasks-total {total} --wave {wave}
 ```
-If state.js returns an error, show it to the employee and stop.
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+Error → show, stop.
+Do NOT edit STATE.md or tracking.json manually; state.js handles both.
 
 ### 6. Route (auto-chain aware)
 
-**If invoked with `--auto`:** immediately invoke `/qualia-verify {N} --auto` inline. No pause, no permission ask. Verify will either chain into the next phase (if PASS), into gap closure (if FAIL and gap cycles remain), or halt with clear escalation (if gap limit reached).
+**`--auto`:** invoke `/qualia-verify {N} --auto` inline. No pause.
 
 ```bash
 node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-verify {N}"
 ```
 
-Then invoke the `qualia-verify` skill inline with the same `--auto` flag.
+Then invoke `qualia-verify` inline with `--auto`.
 
-**Otherwise (default guided mode):** stop and show the next step:
+**Guided mode:** stop, show next step:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"

package/skills/qualia-discuss/SKILL.md

@@ -1,121 +1,104 @@
 ---
 name: qualia-discuss
-description: "Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input."
+description: "Aggressive alignment interview before planning a phase — asks ONE question at a time, proposes a recommended answer with each, walks every branch of the decision tree until resolved. Updates .planning/CONTEXT.md inline as terms crystallize and writes ADRs for hard-to-reverse decisions. Output: .planning/phase-{N}-context.md (locked input the planner honors). Use BEFORE /qualia-plan for high-stakes phases (regulatory, auth, payments, multi-tenant, architectural forks), or when the user says 'discuss', 'grill me', 'stress test this plan', 'wait let's think about this one', 'I'm not sure how to approach this'."
 allowed-tools:
   - Bash
   - Read
   - Write
   - Edit
+  - Grep
+  - Glob
   - AskUserQuestion
 ---
 
-# /qualia-discuss — Phase Context Capture
+# /qualia-discuss — Alignment Interview Before Planning
 
-Before a complex phase gets planned, surface the decisions and trade-offs that must inform planning. Output: `.planning/phase-{N}-context.md` that the planner reads as locked input.
-
-## When to Use
+Surface and lock the decisions, trade-offs, and constraints that must inform a phase plan. Output: `.planning/phase-{N}-context.md` (locked input). Side effects: `.planning/CONTEXT.md` gains new terms; `.planning/decisions/` may gain ADRs.
 
+## When to use
 - Regulated domains (legal, medical, financial) where wrong choices have legal cost
-- Phases with architectural forks (e.g., "auth via middleware or RLS?")
+- Phases with architectural forks ("auth via middleware or RLS?")
 - Phases with external dependencies you want to lock first
-- Anytime the user says "wait, let's think about this one"
+- User says "wait, let's think about this one"
 
-## Process
+## The four grilling rules
 
-### 1. Determine Phase
+1. **One question at a time.** Wait for the answer before asking the next. Never batch.
+2. **Propose your recommended answer first.** Format every question as `Question / Recommendation / Trade-offs`. The user accepts, edits, or rejects — way faster than open interview.
+3. **If the codebase can answer, explore instead of asking.** Don't make the user say what `git grep` could tell you.
+4. **Walk every branch.** When the user picks A over B, the next question is the one that A makes load-bearing. Resolve dependencies one-by-one until the tree is fully traversed.
 
-```bash
-node ~/.claude/bin/state.js check 2>/dev/null
-```
-
-If a phase number was passed as argument, use it. Otherwise use the current phase from STATE.md.
+## Process
 
-### 2. Load Context
+### 1. Load substrate
 
 ```bash
-cat .planning/PROJECT.md 2>/dev/null
-cat .planning/ROADMAP.md 2>/dev/null
+node ~/.claude/bin/state.js check 2>/dev/null
+cat .planning/PROJECT.md .planning/ROADMAP.md .planning/CONTEXT.md 2>/dev/null
+ls .planning/decisions/ 2>/dev/null
 cat .planning/research/SUMMARY.md 2>/dev/null
 ```
 
-Identify:
-- Phase goal from ROADMAP.md
-- Requirements covered by this phase
-- Research flags for this phase (from SUMMARY.md)
+If `.planning/CONTEXT.md` is missing, copy `~/.claude/qualia-templates/CONTEXT.md` to `.planning/CONTEXT.md` first.
+If `.planning/decisions/` is missing, create it. Copy `~/.claude/qualia-templates/decisions/ADR-template.md` next to it for reference.
 
-### 3. Open the Conversation
+### 2. Open the conversation
 
-Print the banner:
 ```bash
 node ~/.claude/bin/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
 ```
 
-Ask inline (free text, not AskUserQuestion):
-
-**"We're about to plan {phase name}. The goal is: {goal from ROADMAP.md}. Before I hand this to the planner, what decisions, trade-offs, or constraints should be locked in?"**
+Then state the goal in one sentence and the open questions you found in priority order (highest-stakes / hardest-to-reverse first).
 
-Wait for their response.
+### 3. Grill, one question at a time
 
-### 4. Follow the Thread
+Format:
 
-Based on their answer, dig into specifics:
+```
+**Question {N}/{total}:** {the question}
 
-- If they mention a technology → "Why that one specifically?"
-- If they mention a constraint → "What happens if we don't honor this?"
-- If they mention a trade-off → "Which side do you want to land on, and why?"
-- If they mention a concern → "What's the worst case?"
+**My recommendation:** {your proposed answer + 1-sentence why}
 
-Use `AskUserQuestion` when there are clear interpretation forks. Free text otherwise.
+**Trade-offs:** {what gets harder if we go this way}
+```
 
-### 5. Capture Locked Decisions
+Wait for response. Then:
+- Update `.planning/CONTEXT.md` inline if a term crystallized (add definition + `Avoid:` line for rejected synonyms)
+- Write an ADR in `.planning/decisions/ADR-{NNNN}-{slug}.md` ONLY when the decision is hard-to-reverse, surprising-without-context, AND involves real trade-offs (use the template — keep it scarce)
+- Drill deeper if the answer opens new branches
 
-Build up a list of **locked decisions** — things the planner MUST honor. Each decision has:
-- The choice (what)
-- The rationale (why)
-- The source (who/when)
+### 4. Build the locked-decisions list
 
-Also capture:
-- **Discretion items** — things the planner can decide freely
-- **Deferred ideas** — good ideas that are NOT in this phase
-- **Risk flags** — things to watch during building
-- **Open questions** — things that still need resolution
+For each resolved decision, capture: choice (what) / rationale (why) / source (who/when).
+Also track: **Discretion items** (planner decides) / **Deferred ideas** (NOT this phase) / **Risk flags** (watch during build) / **Open questions** (still unresolved).
 
-### 6. Decision Gate
+### 5. Decision gate
 
-When you have enough context:
+When the tree is fully traversed:
 
 - header: "Ready to lock?"
-- question: "Ready to lock these decisions and move to /qualia-plan {N}?"
-- options:
-  - "Lock it in" — Write phase-{N}-context.md and done
-  - "Keep exploring" — I have more to say
+- question: "Lock these decisions and move to /qualia-plan {N}?"
+- options: "Lock it in" / "Keep exploring"
 
 Loop until "Lock it in".
 
-### 7. Write phase-{N}-context.md
-
-Use the template at `~/.claude/qualia-templates/phase-context.md`. Fill every section with concrete content.
+### 6. Write phase-{N}-context.md
 
-```bash
-# Write the file to .planning/phase-{N}-context.md
-```
-
-### 8. Commit
-
-```bash
-git add .planning/phase-{N}-context.md
-git commit -m "docs(phase-{N}): capture phase context before planning"
-```
+Fill `~/.claude/qualia-templates/phase-context.md` with concrete content. Reference any ADRs written, any CONTEXT.md terms added.
 
-### 9. Route to Next
+### 7. Commit and route
 
 ```bash
+git add .planning/phase-{N}-context.md .planning/CONTEXT.md .planning/decisions/
+git commit -m "docs(phase-{N}): lock context, glossary terms, ADRs"
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
 ```
 
 ## Rules
 
-1. **One session, one phase.** Don't try to discuss phases 1 and 2 in the same invocation.
-2. **Locked decisions are NON-NEGOTIABLE.** The planner will honor them exactly. If you lock something you're not sure about, that's a mistake.
-3. **Don't redo research.** If the user asks a research question you don't know, suggest `/qualia-research {N}` instead.
-4. **Short context files are fine.** If the phase is simple, a 30-line context.md is better than a forced 200-line one.
+1. **One session, one phase.** Don't discuss phases 1 and 2 in the same invocation.
+2. **Locked decisions are NON-NEGOTIABLE.** The planner honors them exactly. Don't lock what you're unsure of — defer it instead.
+3. **Don't redo research.** If a question requires research you don't have, suggest `/qualia-research {N}` and pause.
+4. **CONTEXT.md is precious — keep entries terse.** One sentence each. It's loaded into every spawn; bloat costs tokens.
+5. **ADRs are scarce on purpose.** Three criteria all required. If any is missing, put it in CONTEXT.md or the phase-context.md instead.
+6. **Short context files are fine.** A 30-line context for a simple phase beats a forced 200-line one.

package/skills/qualia-handoff/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: qualia-handoff
+disable-model-invocation: true
 description: "Client delivery — produces the 4 mandatory Handoff deliverables (production URL, documentation, client assets archive, ERP finalization). Triggered at the end of the Handoff milestone."
 allowed-tools:
   - Bash