qualia-framework 6.9.2 → 6.22.0

package/tests/wave-plan.test.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# wave-plan.test.sh — bin/wave-plan.js (dependency-derived build schedule, R16)
+# Run: bash tests/wave-plan.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+WP="$BIN_DIR/wave-plan.js"
+
+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
+}
+assert_contains() {
+  local name="$1" hay="$2" needle="$3"
+  if echo "$hay" | grep -qF "$needle"; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (missing '$needle' in: $hay)"; FAIL=$((FAIL+1)); fi
+}
+assert_eq() {
+  local name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (expected '$expected', got '$actual')"; FAIL=$((FAIL+1)); fi
+}
+
+echo "wave-plan.test.sh — bin/wave-plan.js"
+echo ""
+
+$NODE -c "$WP" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- chain DAG: T1→T2→T3 → 3 sequential waves of 1 ---
+TMP=$(mktemp -d)
+cat > "$TMP/c.json" <<'EOF'
+{ "phase": 1, "tasks": [
+  {"id":"T1","wave":1,"depends_on":[]},
+  {"id":"T2","wave":2,"depends_on":["T1"]},
+  {"id":"T3","wave":3,"depends_on":["T2"]}
+] }
+EOF
+OUT=$($NODE "$WP" "$TMP/c.json" --json 2>&1)
+assert_exit "chain → exit 0" 0 $?
+assert_contains "chain has 3 batches" "$OUT" '"batch_count": 3'
+rm -rf "$TMP"
+
+# --- 6 independent tasks, auto cap 5 → 2 batches (5 + 1), all wave 1 ---
+TMP=$(mktemp -d)
+cat > "$TMP/c.json" <<'EOF'
+{ "phase": 2, "tasks": [
+  {"id":"T1","wave":1,"depends_on":[]},
+  {"id":"T2","wave":1,"depends_on":[]},
+  {"id":"T3","wave":1,"depends_on":[]},
+  {"id":"T4","wave":1,"depends_on":[]},
+  {"id":"T5","wave":1,"depends_on":[]},
+  {"id":"T6","wave":1,"depends_on":[]}
+] }
+EOF
+OUT=$($NODE "$WP" "$TMP/c.json" --json 2>&1)
+assert_contains "6 independent → max_concurrency 5" "$OUT" '"max_concurrency": 5'
+assert_contains "6 independent → 2 batches" "$OUT" '"batch_count": 2'
+assert_contains "6 independent → 1 derived level" "$OUT" '"derived_levels": 1'
+assert_contains "wide-level note emitted" "$OUT" "capped to batches of 5"
+rm -rf "$TMP"
+
+# --- tiny phase (<3 tasks) → auto sequential (cap 1) ---
+TMP=$(mktemp -d)
+cat > "$TMP/c.json" <<'EOF'
+{ "phase": 3, "tasks": [
+  {"id":"T1","wave":1,"depends_on":[]},
+  {"id":"T2","wave":1,"depends_on":[]}
+] }
+EOF
+OUT=$($NODE "$WP" "$TMP/c.json" --json 2>&1)
+assert_contains "2 tasks → cap 1 (sequential)" "$OUT" '"max_concurrency": 1'
+assert_contains "2 tasks → 2 batches" "$OUT" '"batch_count": 2'
+rm -rf "$TMP"
+
+# --- --parallel override ---
+TMP=$(mktemp -d)
+cat > "$TMP/c.json" <<'EOF'
+{ "phase": 4, "tasks": [
+  {"id":"T1","wave":1,"depends_on":[]},
+  {"id":"T2","wave":1,"depends_on":[]},
+  {"id":"T3","wave":1,"depends_on":[]},
+  {"id":"T4","wave":1,"depends_on":[]}
+] }
+EOF
+OUT=$($NODE "$WP" "$TMP/c.json" --parallel 2 --json 2>&1)
+assert_contains "--parallel 2 sets cap" "$OUT" '"max_concurrency": 2'
+assert_contains "--parallel 2 → 2 batches of 2" "$OUT" '"batch_count": 2'
+# invalid --parallel
+$NODE "$WP" "$TMP/c.json" --parallel 0 >/dev/null 2>&1
+assert_exit "--parallel 0 → invocation error (exit 2)" 2 $?
+rm -rf "$TMP"
+
+# --- over-serialization: independent task declared in a deeper wave ---
+TMP=$(mktemp -d)
+cat > "$TMP/c.json" <<'EOF'
+{ "phase": 5, "tasks": [
+  {"id":"T1","wave":1,"depends_on":[]},
+  {"id":"T2","wave":2,"depends_on":[]}
+] }
+EOF
+OUT=$($NODE "$WP" "$TMP/c.json" --json 2>&1)
+assert_contains "flags over-serialization" "$OUT" "deeper wave than the dependency graph requires"
+# both are actually level 1 (no deps) → 1 derived level
+assert_contains "both tasks derive to one level" "$OUT" '"derived_levels": 1'
+rm -rf "$TMP"
+
+# --- diamond DAG: T1; T2,T3 dep T1; T4 dep T2,T3 → 3 levels ---
+TMP=$(mktemp -d)
+cat > "$TMP/c.json" <<'EOF'
+{ "phase": 6, "tasks": [
+  {"id":"T1","wave":1,"depends_on":[]},
+  {"id":"T2","wave":2,"depends_on":["T1"]},
+  {"id":"T3","wave":2,"depends_on":["T1"]},
+  {"id":"T4","wave":3,"depends_on":["T2","T3"]}
+] }
+EOF
+OUT=$($NODE "$WP" "$TMP/c.json" --json 2>&1)
+assert_contains "diamond → 3 derived levels" "$OUT" '"derived_levels": 3'
+# middle level T2,T3 share a batch
+assert_contains "diamond middle batch has T2+T3" "$OUT" '"T2",'
+rm -rf "$TMP"
+
+# --- cycle → exit 1 ---
+TMP=$(mktemp -d)
+cat > "$TMP/c.json" <<'EOF'
+{ "phase": 7, "tasks": [
+  {"id":"T1","wave":1,"depends_on":["T2"]},
+  {"id":"T2","wave":1,"depends_on":["T1"]}
+] }
+EOF
+$NODE "$WP" "$TMP/c.json" >/dev/null 2>&1
+assert_exit "cycle → exit 1" 1 $?
+OUT=$($NODE "$WP" "$TMP/c.json" --json 2>&1)
+assert_contains "cycle reported" "$OUT" '"error": "CYCLE"'
+rm -rf "$TMP"
+
+# --- library: resolveConcurrency + deriveLevels units ---
+assert_eq "resolveConcurrency(2,auto)=1" "1" "$($NODE -e "console.log(require('$WP').resolveConcurrency(2))")"
+assert_eq "resolveConcurrency(5,auto)=5" "5" "$($NODE -e "console.log(require('$WP').resolveConcurrency(5))")"
+assert_eq "resolveConcurrency(99,parallel=3)=3" "3" "$($NODE -e "console.log(require('$WP').resolveConcurrency(99,3))")"
+LV=$($NODE -e "const w=require('$WP'); const r=w.deriveLevels([{id:'T1',depends_on:[]},{id:'T2',depends_on:['T1']}]); console.log(r.levels.get('T2'))" 2>&1)
+assert_eq "deriveLevels T2 after T1 = 2" "2" "$LV"
+
+# --- missing contract → exit 2 ---
+$NODE "$WP" /nonexistent.json >/dev/null 2>&1
+assert_exit "missing contract → exit 2" 2 $?
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/skills/qualia-discuss/SKILL.md

@@ -1,222 +0,0 @@
----
-name: qualia-discuss
-description: "Alignment interview — PROJECT MODE before /qualia-new, PHASE MODE before /qualia-plan N. Triggers: 'discuss', 'kickoff interview', 'grill me', 'stress test this plan', 'I'm not sure how to approach this'."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - AskUserQuestion
----
-
-> **RETIRED (v6.7, A4 collapse).** Folded into `/qualia-scope`: PROJECT MODE = this kickoff interview, PHASE MODE = the pre-plan grill, picked by qualia-scope's mode router. This file is no longer installed as a slash command. Kept for history.
-
-# /qualia-discuss — Alignment Interview
-
-Two modes. The skill picks one based on whether an arg is passed.
-
-| Arg | Mode | When | Output |
-|-----|------|------|--------|
-| (none) | **PROJECT MODE** | Kickoff, before `/qualia-new`. Non-technical, audience-facing. | `.planning/project-discovery.md` |
-| `N` (e.g. `2`) | **PHASE MODE** | Before `/qualia-plan N`. Technical, aggressive grilling. | `.planning/phase-{N}-context.md` |
-
-## Mode routing
-
-```bash
-if [ -z "$1" ] || ! [[ "$1" =~ ^[0-9]+$ ]]; then
-  MODE="project"
-else
-  MODE="phase"
-  PHASE_N="$1"
-fi
-```
-
-If `MODE=project` → jump to **PROJECT MODE** section below.
-If `MODE=phase` → jump to **PHASE MODE** section below.
-
----
-
-# PROJECT MODE — Kickoff Interview (no args)
-
-The non-technical conversation that runs at the very start of `/qualia-new`, BEFORE any roadmapping or research. Captures what the client wants, who it's for, brand voice, and constraints — in the client's own words.
-
-Hard rule: **never go technical here.** No "Should we use Supabase or Postgres?". The technical decisions happen in PHASE MODE, per phase. This mode is for the human shape of the project.
-
-## When PROJECT MODE runs
-
-- Triggered automatically by `/qualia-new` after Step 0 banner, BEFORE journey generation.
-- Or invoked manually (e.g. on a brownfield project that already has code but no discovery doc).
-
-## Process — PROJECT MODE
-
-### P1. Detect project type (or accept it from `/qualia-new`)
-
-If `/qualia-new` already asked the Demo vs Full gate (it does this as Step 1, the literal first question), it passes the type in as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full` via env or arg — **skip the gate, do not re-ask.**
-
-Only ask the gate yourself when invoked standalone (not via `/qualia-new`). When you do, use **AskUserQuestion** (interactive UI — never plain text):
-
-- header: "Project shape"
-- question: "Is this a demo (single shippable milestone, sales conversation) or a full project (multi-milestone arc to Handoff)?"
-- options: ["Demo", "Full project"]
-
-This is the only fork. Demo runs §1-§8 of the discovery template. Full project runs all 14 questions.
-
-### P2. Banner and open
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner discuss-project
-```
-
-Say: **"Eight quick questions for the demo path"** or **"Fourteen questions to shape the full project — we'll move fast"** depending on type.
-
-### P3. One question at a time, copy from `templates/project-discovery.md`
-
-For each question §1..§8 (demo) or §1..§14 (full), ask in plain language. Format:
-
-```
-**Question {N}/{total}:** {question text from template}
-
-({one-line clarifier showing the kind of answer that helps)
-```
-
-NO "my recommendation" line in PROJECT MODE — this is open discovery, not technical grilling. Wait for the user's answer. Don't paraphrase back; capture verbatim. If the answer is too thin, ask one follow-up max, then move on.
-
-Allowed `[Enter]` defaults exist on §2, §3, §5 only (inferred from project type). All other questions require an answer.
-
-### P4. Write `.planning/project-discovery.md`
-
-Fill the template at `${QUALIA_TEMPLATES}/project-discovery.md` with the user's verbatim answers. Set frontmatter `project_type` and `discovered_at`.
-
-### P5. Hand back to `/qualia-new`
-
-```bash
-git add .planning/project-discovery.md
-git commit -m "docs: project discovery interview ($PROJECT_TYPE)"
-node ${QUALIA_BIN}/qualia-ui.js ok "Discovery captured — back to /qualia-new"
-```
-
-If invoked standalone (not from `/qualia-new`), end with:
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"
-```
-
-If invoked inline by `/qualia-new`, return control silently — `/qualia-new` continues from Step 2.
-
-## Rules — PROJECT MODE
-
-1. **Never technical.** No stack questions, no architecture forks. Those are PHASE MODE.
-2. **Verbatim capture.** Don't translate the client's words into framework-speak. The client's exact phrasing is the input to PRODUCT.md voice and CONTEXT.md glossary.
-3. **One question, one answer, move on.** No batching. No drilling deeper than one follow-up.
-4. **Demo stops at §8.** Don't ask demo clients milestone-arc questions — they don't have an arc yet.
-5. **Anti-references are required.** If the user can't name three sites this should NOT look like, the design will end up generic. Push back once, then capture whatever they give you.
-
----
-
-# PHASE MODE — Pre-Plan Grilling (`/qualia-discuss N`)
-
-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 PHASE MODE runs
-- Regulated domains (legal, medical, financial) where wrong choices have legal cost
-- Phases with architectural forks ("auth via middleware or RLS?")
-- Phases with external dependencies you want to lock first
-- User says "wait, let's think about this one"
-
-## The four grilling rules (PHASE MODE)
-
-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.
-
-## Process — PHASE MODE
-
-### 1. Load substrate
-
-```bash
-node ${QUALIA_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
-```
-
-If `.planning/CONTEXT.md` is missing, copy `${QUALIA_TEMPLATES}/CONTEXT.md` to `.planning/CONTEXT.md` first.
-If `.planning/decisions/` is missing, create it. Copy `${QUALIA_TEMPLATES}/decisions/ADR-template.md` next to it for reference.
-
-### 2. Open the conversation
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
-```
-
-Then state the goal in one sentence and the open questions you found in priority order (highest-stakes / hardest-to-reverse first).
-
-### 3. Grill, one question at a time
-
-Format:
-
-```
-**Question {N}/{total}:** {the question}
-
-**My recommendation:** {your proposed answer + 1-sentence why}
-
-**Trade-offs:** {what gets harder if we go this way}
-```
-
-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
-
-### 4. Build the locked-decisions list (with IDs — machine-parseable downstream)
-
-For each resolved decision, capture as a row with a stable ID `D-NN` (zero-padded, sequential within the phase). The planner's Decision Coverage Audit checks every `D-NN` is implemented; the plan-checker BLOCKS if any is missing.
-
-**Locked Decision row format:**
-
-| ID | Decision | Rationale | Source |
-|----|----------|-----------|--------|
-| D-01 | Use Supabase RLS for authorization, not middleware | Compliance requires database-level checks | discuss session 2026-05-09 |
-| D-02 | Store session tokens server-side, not in JWT | OWASP guidance + revocation requirement | ADR-0007 |
-
-Also track:
-- **Discretion items** — planner decides based on best practice (no IDs needed).
-- **Deferred ideas** — explicitly NOT this phase. The plan-checker will REVISE if any of these appears in a task.
-- **Risk flags** — watch during build (no IDs).
-- **Open questions** — still unresolved. Cannot lock until resolved.
-
-When you reference a decision later (in commit messages, task Why fields, ADRs), use its ID — `D-03` is shorter than the full decision text and cross-checkable.
-
-### 5. Decision gate
-
-When the tree is fully traversed:
-
-- header: "Ready to lock?"
-- question: "Lock these decisions and move to /qualia-plan {N}?"
-- options: "Lock it in" / "Keep exploring"
-
-Loop until "Lock it in".
-
-### 6. Write phase-{N}-context.md
-
-Fill `${QUALIA_TEMPLATES}/phase-context.md` with concrete content. Reference any ADRs written, any CONTEXT.md terms added.
-
-### 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 ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
-```
-
-## Rules — PHASE MODE
-
-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.