qualia-framework-v2 2.1.0 → 2.1.1

package/agents/builder.md

@@ -49,12 +49,29 @@ git commit -m "{concise description of what was built}"
 
 Stage specific files — never `git add .` or `git add -A`.
 
-## Deviation Rules
+## Scope Discipline
 
-1. **Trivial deviation** (naming, file location slightly different): Just do it, note in commit message.
-2. **Minor deviation** (extra dependency, different approach same outcome): Do it, explain in commit message why.
-3. **Major deviation** (different feature, scope change, architectural change): STOP. Do NOT implement. Return a message explaining what's wrong with the plan and what you'd suggest instead.
-4. **Blocker** (missing dependency, API doesn't exist, auth not set up): STOP. Return a message explaining what's blocking you.
+Before writing or editing any file, check: Is this file listed in the task's **Files** section?
+
+- **Yes** → Proceed.
+- **No, but direct dependency** — the task literally cannot work without this change (e.g., adding an import to a shared types file) → Do it. Note in commit message: `also modified: {file} — {reason}`.
+- **No, it's an improvement/cleanup you noticed** → Do NOT do it. Add a line to your commit message: `[discovered] {file}: {what you noticed}`. The planner picks this up next cycle.
+- **Test files** → Never modify unless the task explicitly includes them.
+
+This is non-negotiable. Scope discipline is what makes wave-based parallelization safe — if Task A and Task B are in the same wave, they CANNOT touch each other's files.
+
+## Deviation Handling
+
+During execution, you may find the plan doesn't perfectly match reality. Classify and act:
+
+| Type | Criteria | Action |
+|------|----------|--------|
+| **Trivial** | Different variable name, slightly different file location, import path difference | Just do it. No need to mention. |
+| **Minor** | Need an extra dependency, different function signature than planned, need a utility function not in plan | Do it. Note in commit message: `deviation: {what and why}` |
+| **Major** | Task would build a different feature than described, architectural approach is wrong, plan assumes something that isn't true about the codebase | STOP. Do not implement. Return: `BLOCKED — major deviation: {description}. The plan assumes X but the codebase actually does Y. Recommend replanning.` |
+| **Blocker** | Missing dependency that can't be installed, API/service doesn't exist, required file from another task doesn't exist yet (wave ordering issue) | STOP. Return: `BLOCKED — dependency missing: {what's needed}. This task likely needs to move to a later wave.` |
+
+Rule of thumb: If you can explain the change in one sentence in a commit message, it's minor. If you'd need to rewrite the task description, it's major.
 
 ## Rules
 

package/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: qualia-planner
 description: Creates executable phase plans with task breakdown, wave assignments, and verification criteria.
-tools: Read, Write, Bash, Glob, Grep
+tools: Read, Write, Bash, Glob, Grep, WebFetch
 ---
 
 # Qualia Planner
@@ -73,6 +73,18 @@ Goal: {what must be true when done}
 - [ ] {truth 3}
 ```
 
+## Task Specificity (Mandatory)
+
+Every task MUST have these three fields with concrete content:
+
+- **Files:** Absolute paths from project root. Not "the auth files" or "relevant components". Specific: `src/app/auth/login/page.tsx`, `src/lib/auth.ts`. If creating a file, state what it exports. If modifying, state what changes.
+- **Action:** At least one concrete instruction — not just "implement auth". Reference specific functions, components, or patterns. "Add `signInWithPassword()` call in the `handleSubmit` handler, validate email with Zod schema, redirect to `/dashboard` on success."
+- **Done when:** Testable, not fuzzy. Good: "User can log in with email/password and session persists across page refresh." Bad: "Auth works." Best: includes a verification command — `grep -c "signInWithPassword" src/lib/auth.ts` returns non-zero.
+
+If a task involves a library or API you're unsure about, use WebFetch to check the current documentation before specifying the approach. Don't guess at APIs.
+
+**Self-check:** Before returning the plan, verify every task has specific file paths, concrete actions, and testable done-when criteria. If any task says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics.
+
 ## Rules
 
 1. **Plans complete within ~50% context.** More plans with smaller scope = consistent quality. 2-3 tasks per plan is ideal.

package/agents/verifier.md

@@ -58,6 +58,32 @@ grep -c "TODO\|FIXME\|placeholder\|not implemented\|stub" {file}
 grep -r "import.*from.*{module}" {consumer_files}
 ```
 
+### Stub Detection (Level 2)
+
+Red flags — these indicate placeholder/stub code:
+```bash
+grep -c "TODO\|FIXME\|PLACEHOLDER\|not implemented\|coming soon" {file}
+grep -c "return null\|return undefined\|return \[\]\|return \{\}" {file}
+grep -c "throw new Error.*not implemented\|throw new Error.*todo" {file}
+grep -c "console\.log.*only\|// stub\|// placeholder\|// temp" {file}
+
+# Empty handlers:
+grep -c "catch {}\|catch (e) {}\|catch (err) {}" {file}
+grep -c "async.*=> {}\|() => {}" {file}
+```
+
+If Level 2 finds more than 2 stub patterns in a single file, mark that criterion as **FAIL** regardless of other checks. Stubs are not implementations.
+
+### Wiring Check (Level 3)
+
+```bash
+# Is the module actually imported somewhere?
+grep -r "import.*from.*{module_name}" --include="*.ts" --include="*.tsx" | grep -v node_modules | grep -v ".planning"
+
+# Are exported functions actually called?
+grep -r "{function_name}" --include="*.ts" --include="*.tsx" | grep -v "export\|function\|const.*=" | grep -v node_modules
+```
+
 ### 3. Run Code Quality Checks
 
 ```bash
@@ -108,6 +134,20 @@ OR
 FAIL — {N} gaps found. Run `/qualia-plan {N} --gaps` to fix.
 ```
 
+## Scoring
+
+Each success criterion from the plan gets a verdict:
+
+- **PASS** — All 3 levels check out. File exists, has real implementation (not stubs), and is imported/used by the system.
+- **PARTIAL** — File exists and has real code, but isn't fully wired (e.g., component exists but isn't rendered in any page, API route exists but no client calls it). This is NOT a pass.
+- **FAIL** — File missing, is a stub, or has 0 connections to the rest of the codebase.
+
+Phase verdict:
+- **ALL PASS** → Phase verified. Update STATE.md status to "verified".
+- **ANY PARTIAL or FAIL** → Phase has gaps. List each gap with: what's wrong, what file, what's needed. Suggest `/qualia-plan {N} --gaps`.
+
+Never round up. A PARTIAL is not a PASS. The goal of verification is to catch the work that LOOKS done but ISN'T.
+
 ## Rules
 
 1. **Never trust summaries.** Always grep the code yourself.

package/hooks/branch-guard.sh

@@ -4,6 +4,11 @@
 BRANCH=$(git branch --show-current 2>/dev/null)
 ROLE=$(grep -m1 "^## Role:" ~/.claude/CLAUDE.md 2>/dev/null | sed 's/^## Role: *//')
 
+if [ -z "$ROLE" ]; then
+  echo "BLOCKED: Cannot determine role — ~/.claude/CLAUDE.md missing or malformed. Defaulting to deny."
+  exit 1
+fi
+
 if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
   if [[ "$ROLE" != "OWNER" ]]; then
     echo "BLOCKED: Employees cannot push to $BRANCH. Create a feature branch first."

package/hooks/pre-push.sh

@@ -12,8 +12,12 @@ if [ -f "$STATE" ] && [ -f "$TRACKING" ]; then
   NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
   # Update tracking.json with current values
-  if command -v python3 &>/dev/null; then
-    python3 -c "
+  if ! command -v python3 &>/dev/null; then
+    echo "WARNING: python3 not found — tracking.json not updated" >&2
+    exit 0
+  fi
+
+  if ! python3 -c "
 import json
 with open('$TRACKING', 'r') as f:
     t = json.load(f)
@@ -23,7 +27,9 @@ t['last_commit'] = '${LAST_COMMIT}'
 t['last_updated'] = '${NOW}'
 with open('$TRACKING', 'w') as f:
     json.dump(t, f, indent=2)
-" 2>/dev/null
-    git add "$TRACKING" 2>/dev/null
+" 2>/tmp/qualia-push-err.txt; then
+    echo "WARNING: Failed to update tracking.json — $(cat /tmp/qualia-push-err.txt)" >&2
+    exit 0
   fi
+  git add "$TRACKING" 2>/dev/null
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework-v2": "./bin/cli.js"
@@ -22,6 +22,9 @@
     "url": "https://github.com/qualia-solutions/qualia-framework-v2"
   },
   "homepage": "https://github.com/qualia-solutions/qualia-framework-v2#readme",
+  "scripts": {
+    "test": "bash tests/hooks.test.sh"
+  },
   "files": [
     "bin/",
     "agents/",
@@ -29,6 +32,7 @@
     "rules/",
     "skills/",
     "templates/",
+    "tests/",
     "CLAUDE.md",
     "guide.md",
     "statusline.sh"

package/skills/qualia/SKILL.md

@@ -22,7 +22,13 @@ echo "---VERIFICATIONS---"
 ls .planning/phase-*-verification.md 2>/dev/null || echo "NO_VERIFICATIONS"
 ```
 
-### 2. Route
+### Task Routing (size-based)
+
+- Single file change, config tweak, typo fix, bug with known cause → `/qualia-quick`
+- One feature, 1-5 files, clear scope, under 2 hours → `/qualia-task`
+- Multi-feature, 5+ files, needs architecture decisions, or part of a roadmap phase → `/qualia-plan`
+
+### 2. Route (state-based)
 
 | Condition | Command |
 |-----------|---------|

package/skills/qualia-plan/SKILL.md

@@ -82,3 +82,16 @@ Update tracking.json: status → "planned"
 ```
   → Run: /qualia-build {N}
 ```
+
+### Gap Closure Mode (`--gaps`)
+
+When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
+
+1. Read `.planning/phase-{N}-verification.md` — extract ONLY the FAIL items
+2. For each FAIL item, create a targeted fix task:
+   - **Files:** The specific files that failed verification
+   - **Action:** The specific fix needed (not "fix auth" — "add session persistence check in `src/lib/auth.ts` signIn function")
+   - **Done when:** The exact verification criterion that previously failed, restated
+3. Do NOT re-plan passing items. Do NOT add new features. Gap plans are surgical.
+4. Write to `.planning/phase-{N}-gaps-plan.md` (separate from original plan)
+5. All gap tasks are Wave 1 (parallel) unless they share files

package/skills/qualia-quick/SKILL.md

@@ -5,7 +5,7 @@ description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips
 
 # /qualia-quick — Quick Task
 
-For tasks under 30 minutes that don't need full phase planning. Bug fixes, small features, tweaks.
+For tasks under 1 hour that don't need full phase planning. Single file changes, bug fixes, config tweaks, typo fixes.
 
 ## Process
 

package/skills/qualia-task/SKILL.md

@@ -12,7 +12,7 @@ Build one thing properly. Fresh builder context, atomic commit, but no phase pla
 `/qualia-task {description}` — build it directly
 
 ## When to Use
-- Too big for a quick fix, too small for a full phase
+- One feature, 1-5 files, clear scope, 1-3 hours of work
 - Adding a single feature, component, API route, or integration
 - Refactoring one module
 - Building something specific someone asked for
@@ -29,12 +29,12 @@ Then use AskUserQuestion:
 question: "How complex is this task?"
 header: "Scope"
 options:
-  - label: "Small (30min-1hr)"
+  - label: "Small (1-2hrs)"
     description: "Single file or component, straightforward implementation"
-  - label: "Medium (1-3hrs)"
+  - label: "Medium (2-3hrs)"
     description: "Multiple files, some integration work, needs testing"
   - label: "Large (3hrs+)"
-    description: "Significant feature, multiple components, consider /qualia-plan instead"
+    description: "Significant feature, multiple components — use /qualia-plan instead"
 ```
 
 If "Large" — suggest `/qualia-plan` instead. Ask if they want to proceed anyway.

package/tests/hooks.test.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# Qualia Framework v2 — Hook Tests
+# Run: bash tests/hooks.test.sh
+
+PASS=0
+FAIL=0
+HOOKS_DIR="$(dirname "$0")/../hooks"
+
+assert_exit() {
+  local name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    echo "  ✓ $name"
+    PASS=$((PASS + 1))
+  else
+    echo "  ✗ $name (expected exit $expected, got $actual)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== Hook Tests ==="
+echo ""
+
+# --- block-env-edit.sh ---
+echo "block-env-edit:"
+
+echo '{"tool_input":{"file_path":".env.local"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+assert_exit "blocks .env.local" 2 $?
+
+echo '{"tool_input":{"file_path":".env.production"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+assert_exit "blocks .env.production" 2 $?
+
+echo '{"tool_input":{"file_path":".env"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+assert_exit "blocks .env" 2 $?
+
+echo '{"tool_input":{"file_path":"src/app.tsx"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+assert_exit "allows src/app.tsx" 0 $?
+
+echo '{"tool_input":{"file_path":"components/Footer.tsx"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+assert_exit "allows components/Footer.tsx" 0 $?
+
+# --- migration-guard.sh ---
+echo ""
+echo "migration-guard:"
+
+echo '{"tool_input":{"file_path":"migrations/001.sql","content":"DROP TABLE users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+assert_exit "blocks DROP TABLE without IF EXISTS" 2 $?
+
+echo '{"tool_input":{"file_path":"migrations/001.sql","content":"DROP TABLE IF EXISTS old_users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+assert_exit "allows DROP TABLE IF EXISTS" 0 $?
+
+echo '{"tool_input":{"file_path":"migrations/002.sql","content":"DELETE FROM users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+assert_exit "blocks DELETE without WHERE" 2 $?
+
+echo '{"tool_input":{"file_path":"migrations/003.sql","content":"TRUNCATE TABLE sessions;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+assert_exit "blocks TRUNCATE" 2 $?
+
+echo '{"tool_input":{"file_path":"migrations/004.sql","content":"CREATE TABLE users (id uuid);"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+assert_exit "blocks CREATE TABLE without RLS" 2 $?
+
+echo '{"tool_input":{"file_path":"migrations/005.sql","content":"ALTER TABLE users ADD COLUMN email text;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+assert_exit "allows safe ALTER TABLE" 0 $?
+
+echo '{"tool_input":{"file_path":"src/app.tsx","content":"DROP TABLE users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+assert_exit "skips non-migration files" 0 $?
+
+# --- branch-guard.sh ---
+echo ""
+echo "branch-guard:"
+
+if [ -f "$HOOKS_DIR/branch-guard.sh" ]; then
+  echo "  ✓ branch-guard.sh exists"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ branch-guard.sh missing"
+  FAIL=$((FAIL + 1))
+fi
+
+if grep -q 'ROLE' "$HOOKS_DIR/branch-guard.sh"; then
+  echo "  ✓ checks ROLE variable"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ missing ROLE check"
+  FAIL=$((FAIL + 1))
+fi
+
+if grep -q 'z "$ROLE"' "$HOOKS_DIR/branch-guard.sh"; then
+  echo "  ✓ defaults to deny on missing ROLE"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ missing empty-ROLE deny"
+  FAIL=$((FAIL + 1))
+fi
+
+# --- pre-push.sh ---
+echo ""
+echo "pre-push:"
+
+if grep -q 'command -v python3' "$HOOKS_DIR/pre-push.sh"; then
+  echo "  ✓ checks for python3 availability"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ missing python3 check"
+  FAIL=$((FAIL + 1))
+fi
+
+if grep -q 'qualia-push-err' "$HOOKS_DIR/pre-push.sh"; then
+  echo "  ✓ captures python3 errors"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ missing python3 error capture"
+  FAIL=$((FAIL + 1))
+fi
+
+# --- pre-deploy-gate.sh ---
+echo ""
+echo "pre-deploy-gate:"
+
+if [ -f "$HOOKS_DIR/pre-deploy-gate.sh" ]; then
+  echo "  ✓ pre-deploy-gate.sh exists"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ pre-deploy-gate.sh missing"
+  FAIL=$((FAIL + 1))
+fi
+
+if grep -q 'tsc --noEmit' "$HOOKS_DIR/pre-deploy-gate.sh"; then
+  echo "  ✓ runs TypeScript check"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ missing TypeScript check"
+  FAIL=$((FAIL + 1))
+fi
+
+if grep -q 'service_role' "$HOOKS_DIR/pre-deploy-gate.sh"; then
+  echo "  ✓ checks for service_role leaks"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ missing service_role check"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1