qualia-framework 6.2.9 → 6.2.10

package/tests/lib.test.sh

@@ -149,6 +149,123 @@ console.log(d2.drift ? "DRIFT-DETECTED" : "FAIL2");
 ' | tail -1 > /tmp/qfdrift.out
 [ "$(cat /tmp/qfdrift.out)" = "DRIFT-DETECTED" ] && ok "drift detection" || fail "drift detection: $(cat /tmp/qfdrift.out)"
 
+# CLI validate
+TMP=$(mktmp)
+cat > "$TMP/contract.json" <<JSON
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "contract cli",
+  "why": "prove validator is executable",
+  "generated_at": "2026-05-23T00:00:00Z",
+  "generated_by": "manual",
+  "source_plan_hash": "",
+  "success_criteria": ["contract validates"],
+  "tasks": [{
+    "id": "T1",
+    "title": "Create evidence",
+    "wave": 1,
+    "depends_on": [],
+    "files_modify": [],
+    "files_create": ["out.txt"],
+    "files_delete": [],
+    "acceptance_criteria": ["out.txt exists"],
+    "action": "Create out.txt",
+    "context_files": [],
+    "verification": [{ "type": "file-exists", "path": "out.txt" }]
+  }]
+}
+JSON
+OUT=$($NODE "$PC" validate "$TMP/contract.json" 2>&1)
+[ "$OUT" = "VALID $TMP/contract.json" ] && ok "plan-contract CLI validates contract" || fail "plan-contract CLI validate: $OUT"
+
+# ─── contract-runner ───────────────────────────────────────
+
+CR="$FRAMEWORK_DIR/bin/contract-runner.js"
+$NODE --check "$CR" >/dev/null 2>&1 && ok "contract-runner.js parses" || fail "contract-runner.js parse"
+
+TMP=$(mktmp)
+mkdir -p "$TMP/src" "$TMP/.planning"
+echo "export const wired = true;" > "$TMP/src/feature.ts"
+cat > "$TMP/.planning/phase-1-contract.json" <<JSON
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "runner pass",
+  "why": "prove checks execute",
+  "generated_at": "2026-05-23T00:00:00Z",
+  "generated_by": "manual",
+  "source_plan_hash": "",
+  "success_criteria": ["all checks pass"],
+  "tasks": [{
+    "id": "T1",
+    "title": "Check feature",
+    "wave": 1,
+    "depends_on": [],
+    "files_modify": ["src/feature.ts"],
+    "files_create": [],
+    "files_delete": [],
+    "acceptance_criteria": ["feature exists and is wired"],
+    "action": "Validate feature",
+    "context_files": [],
+    "verification": [
+      { "type": "file-exists", "path": "src/feature.ts", "must_contain": "wired" },
+      { "type": "grep-match", "path": "src/feature.ts", "pattern": "wired\\\\s*=\\\\s*true", "expect": "present" },
+      { "type": "command-exit", "command": "printf", "args": ["contract-ok"], "expected_exit": 0, "expect_stdout_match": "contract-ok" },
+      { "type": "behavioral", "description": "evidence file includes wired flag", "evidence_required": [{ "path": "src/feature.ts", "description": "feature evidence", "matcher": "wired" }] }
+    ]
+  }]
+}
+JSON
+OUT=$(cd "$TMP" && $NODE "$CR" .planning/phase-1-contract.json 2>&1)
+if echo "$OUT" | grep -q "PASS phase 1: 4 check" && [ -f "$TMP/.planning/evidence/phase-1-contract-run.json" ]; then
+  ok "contract-runner executes passing contract and writes evidence"
+else
+  fail "contract-runner pass/evidence: $OUT"
+fi
+
+OUT=$(cd "$TMP" && $NODE "$CR" .planning/phase-1-contract.json --json 2>/dev/null)
+if echo "$OUT" | grep -q '"ok": true' && echo "$OUT" | grep -q '"checked": 4'; then
+  ok "contract-runner --json reports checked count"
+else
+  fail "contract-runner json output: $OUT"
+fi
+
+TMP=$(mktmp)
+mkdir -p "$TMP/.planning"
+cat > "$TMP/.planning/phase-1-contract.json" <<JSON
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "runner fail",
+  "why": "prove failures block",
+  "generated_at": "2026-05-23T00:00:00Z",
+  "generated_by": "manual",
+  "source_plan_hash": "",
+  "success_criteria": ["failure is detected"],
+  "tasks": [{
+    "id": "T1",
+    "title": "Missing file",
+    "wave": 1,
+    "depends_on": [],
+    "files_modify": [],
+    "files_create": [],
+    "files_delete": [],
+    "acceptance_criteria": ["missing file fails"],
+    "action": "Validate missing file",
+    "context_files": [],
+    "verification": [{ "type": "file-exists", "path": "missing.txt" }]
+  }]
+}
+JSON
+OUT=$(cd "$TMP" && $NODE "$CR" .planning/phase-1-contract.json 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] && echo "$OUT" | grep -q "missing file"; then
+  ok "contract-runner fails closed on failed check"
+else
+  fail "contract-runner failed-check behavior: exit=$EXIT out=$OUT"
+fi
+
 # ─── agent-runs ──────────────────────────────────────────
 
 AR="$FRAMEWORK_DIR/bin/agent-runs.js"
@@ -233,6 +350,179 @@ console.log("removed:" + r.removed);
 ')
 [ "$RES" = "removed:1" ] && ok "prune --before removes old records" || fail "prune: $RES"
 
+# ─── state-ledger ────────────────────────────────────────
+
+SL="$FRAMEWORK_DIR/bin/state-ledger.js"
+$NODE --check "$SL" >/dev/null 2>&1 && ok "state-ledger.js parses" || fail "state-ledger.js parse"
+
+HA="$FRAMEWORK_DIR/bin/host-adapters.js"
+$NODE --check "$HA" >/dev/null 2>&1 && ok "host-adapters.js parses" || fail "host-adapters.js parse"
+RES=$($NODE -e '
+const { renderText } = require("'"$HA"'");
+const c = renderText("node ${QUALIA_BIN}/state.js @${QUALIA_AGENTS}/planner.md", "codex");
+const d = renderText("node ${QUALIA_BIN}/state.js @${QUALIA_AGENTS}/planner.md", "claude");
+console.log(c.includes(".codex/bin/state.js") && c.includes(".codex/agents/planner.md") && d.includes(".claude/bin/state.js") ? "HOST-RENDER-OK" : c + "\n" + d);
+')
+[ "$RES" = "HOST-RENDER-OK" ] && ok "host-adapters renders Qualia path tokens per host" || fail "host-adapters render: $RES"
+
+TMP=$(mktmp)
+RES=$(cd "$TMP" && $NODE -e '
+const ledger = require("'"$SL"'");
+const fs = require("fs");
+fs.mkdirSync(".planning", { recursive: true });
+ledger.append(process.cwd(), {
+  action: "init",
+  status_after: "setup",
+  phase_after: 1,
+  state_raw_after: "state-1",
+  tracking_raw_after: "{\"status\":\"setup\"}"
+});
+ledger.append(process.cwd(), {
+  action: "transition",
+  status_before: "setup",
+  status_after: "planned",
+  phase_before: 1,
+  phase_after: 1,
+  state_raw_before: "state-1",
+  state_raw_after: "state-2",
+  tracking_raw_before: "{\"status\":\"setup\"}",
+  tracking_raw_after: "{\"status\":\"planned\"}",
+  evidence_refs: [".planning/phase-1-plan.md"]
+});
+const v = ledger.validate(process.cwd());
+const lines = fs.readFileSync(ledger.ledgerPath(process.cwd()), "utf8").trim().split(/\n/);
+console.log(v.ok && v.count === 2 && lines.length === 2 ? "CHAIN-OK" : JSON.stringify(v));
+')
+[ "$RES" = "CHAIN-OK" ] && ok "state-ledger appends and validates hash chain" || fail "state-ledger chain: $RES"
+
+RES=$(cd "$TMP" && $NODE -e '
+const ledger = require("'"$SL"'");
+const fs = require("fs");
+const file = ledger.ledgerPath(process.cwd());
+const lines = fs.readFileSync(file, "utf8").trim().split(/\n/);
+const first = JSON.parse(lines[0]);
+first.status_after = "tampered";
+lines[0] = JSON.stringify(first);
+fs.writeFileSync(file, lines.join("\n") + "\n");
+const v = ledger.validate(process.cwd());
+console.log(!v.ok && v.errors.some(e => /event_hash/.test(e)) ? "TAMPER-DETECTED" : JSON.stringify(v));
+')
+[ "$RES" = "TAMPER-DETECTED" ] && ok "state-ledger detects tampered event" || fail "state-ledger tamper: $RES"
+
+# ─── trust-score ─────────────────────────────────────────
+
+PH="$FRAMEWORK_DIR/bin/planning-hygiene.js"
+$NODE --check "$PH" >/dev/null 2>&1 && ok "planning-hygiene.js parses" || fail "planning-hygiene.js parse"
+
+TMP=$(mktmp)
+mkdir -p "$TMP/.planning"
+touch "$TMP/.planning/PROJECT.md"
+touch "$TMP/.planning/phase-1-plan.md"
+OUT=$(cd "$TMP" && $NODE "$PH" scan 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "clean"; then
+  ok "planning-hygiene clean project passes"
+else
+  fail "planning-hygiene clean project: exit=$EXIT out=$OUT"
+fi
+
+TMP=$(mktmp)
+mkdir -p "$TMP/.planning"
+echo debug > "$TMP/.planning/DEBUG-2026-05-23-0100.md"
+echo fix > "$TMP/.planning/FIX-2026-05-23-0101.md"
+echo review > "$TMP/.planning/REVIEW.md"
+echo image > "$TMP/.planning/vibe-after.png"
+OUT=$(cd "$TMP" && $NODE "$PH" scan --json 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+  && echo "$OUT" | grep -q '"status": "needs_organizing"' \
+  && echo "$OUT" | grep -q 'reports/debug/DEBUG-2026-05-23-0100.md' \
+  && echo "$OUT" | grep -q 'reports/fix/FIX-2026-05-23-0101.md' \
+  && echo "$OUT" | grep -q 'reports/review/REVIEW.md' \
+  && echo "$OUT" | grep -q 'assets/vibe/vibe-after.png'; then
+  ok "planning-hygiene routes loose artifacts"
+else
+  fail "planning-hygiene loose routing: exit=$EXIT out=$OUT"
+fi
+
+OUT=$(cd "$TMP" && $NODE "$PH" organize --write 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+  && [ -f "$TMP/.planning/reports/debug/DEBUG-2026-05-23-0100.md" ] \
+  && [ -f "$TMP/.planning/reports/fix/FIX-2026-05-23-0101.md" ] \
+  && [ -f "$TMP/.planning/reports/review/REVIEW.md" ] \
+  && [ -f "$TMP/.planning/assets/vibe/vibe-after.png" ]; then
+  ok "planning-hygiene organize moves loose artifacts"
+else
+  fail "planning-hygiene organize: exit=$EXIT out=$OUT"
+fi
+
+TS="$FRAMEWORK_DIR/bin/trust-score.js"
+$NODE --check "$TS" >/dev/null 2>&1 && ok "trust-score.js parses" || fail "trust-score.js parse"
+
+TMP=$(mktmp)
+OUT=$(HOME="$TMP" $NODE "$TS" --json 2>/dev/null)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] && echo "$OUT" | grep -q '"status": "FAIL"'; then
+  ok "trust-score fails closed when no install exists"
+else
+  fail "trust-score no-install behavior: exit=$EXIT out=$OUT"
+fi
+
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/bin" "$TMP/.claude/hooks" "$TMP/.claude/knowledge/daily-log" "$TMP/.claude/qualia-design" "$TMP/.claude/agents" "$TMP/.claude/qualia-templates" "$TMP/project/.planning"
+echo '{"installed_by":"Test","role":"OWNER","erp":{"enabled":false}}' > "$TMP/.claude/.qualia-config.json"
+touch "$TMP/.claude/CLAUDE.md" "$TMP/.claude/settings.json"
+for f in runtime-manifest.js host-adapters.js state.js qualia-ui.js statusline.js knowledge.js knowledge-flush.js state-ledger.js plan-contract.js contract-runner.js trust-score.js agent-runs.js slop-detect.mjs erp-retry.js report-payload.js project-snapshot.js codex-goal.js planning-hygiene.js; do
+  touch "$TMP/.claude/bin/$f"
+done
+for h in session-start.js auto-update.js branch-guard.js pre-push.js pre-deploy-gate.js migration-guard.js git-guardrails.js stop-session-log.js vercel-account-guard.js env-empty-guard.js supabase-destructive-guard.js; do
+  touch "$TMP/.claude/hooks/$h"
+done
+touch "$TMP/.claude/knowledge/index.md" "$TMP/.claude/knowledge/agents.md"
+for f in design-laws.md design-rubric.md design-brand.md design-product.md design-reference.md frontend.md graphics.md; do
+  touch "$TMP/.claude/qualia-design/$f"
+done
+for s in qualia-doctor qualia-road qualia-resume qualia-pause qualia-report qualia-polish qualia-vibe; do
+  mkdir -p "$TMP/.claude/skills/$s"
+  touch "$TMP/.claude/skills/$s/SKILL.md"
+done
+touch "$TMP/.claude/agents/visual-evaluator.md" "$TMP/.claude/qualia-guide.md" "$TMP/.claude/qualia-templates/help.html"
+cat > "$TMP/project/.planning/STATE.md" <<'EOF'
+Phase: 1 of 1 — Trust
+Status: planned
+EOF
+echo '{"phase":1,"status":"planned"}' > "$TMP/project/.planning/tracking.json"
+cat > "$TMP/project/.planning/phase-1-plan.md" <<'EOF'
+---
+goal: trust
+---
+# Plan
+## Task 1
+**Acceptance Criteria:**
+- ok
+## Success Criteria
+- [ ] ok
+EOF
+$NODE -e '
+const ledger = require("'"$SL"'");
+ledger.append("'"$TMP"'/project", {
+  action: "init",
+  status_after: "planned",
+  phase_after: 1,
+  state_raw_after: "Phase: 1 of 1\nStatus: planned\n",
+  tracking_raw_after: "{\"phase\":1,\"status\":\"planned\"}"
+});
+' >/dev/null
+OUT=$(cd "$TMP/project" && HOME="$TMP" $NODE "$TS" --json 2>/dev/null)
+if echo "$OUT" | grep -q '"status": "DEGRADED"' \
+   && echo "$OUT" | grep -q '"score": 88' \
+   && echo "$OUT" | grep -q 'JSON contract missing'; then
+  ok "trust-score reports 88 degraded when only contract is missing"
+else
+  fail "trust-score degraded contract score: $OUT"
+fi
+
 echo ""
 echo "lib.test.sh: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]

package/tests/runner.js

@@ -2801,6 +2801,9 @@ describe("install.js", () => {
       assert.ok(fs.existsSync(rulesDir));
       const files = fs.readdirSync(rulesDir);
       assert.ok(files.length > 0);
+      assert.ok(fs.existsSync(path.join(rulesDir, "command-output.md")));
+      assert.match(fs.readFileSync(path.join(rulesDir, "command-output.md"), "utf8"), /alwaysApply: true/);
+      assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "qualia-design", "graphics.md")));
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }

package/tests/skills.test.sh

@@ -106,7 +106,7 @@ for skill_dir in "$SKILLS_DIR"/*/; do
 
   # Cache-aware spawn audit (per rules/grounding.md):
   # Every spawn to a CUSTOM (qualia-*) agent must anchor the prompt with
-  # `@~/.claude/agents/{name}.md` (either `Role: @...` or `Read your role:
+  # `@${QUALIA_AGENTS}/{name}.md` (either `Role: @...` or `Read your role:
   # @...` — both forms accepted). The role file is session-stable; placing
   # it first lets Anthropic's prompt cache reuse the prefix across spawns
   # (documented 81-90% cost reduction). If task-specific content lands
@@ -125,14 +125,14 @@ for skill_dir in "$SKILLS_DIR"/*/; do
     custom_spawn_count=$((custom_spawn_count + $(grep -c 'subagent_type="qualia-' "$ref_md")))
   fi
   if [ "${custom_spawn_count:-0}" -gt 0 ]; then
-    role_count=$(grep -cE '@~/\.claude/agents/' "$skill_md")
+    role_count=$(grep -cF '@${QUALIA_AGENTS}/' "$skill_md")
     if [ -f "$ref_md" ]; then
-      role_count=$((role_count + $(grep -cE '@~/\.claude/agents/' "$ref_md")))
+      role_count=$((role_count + $(grep -cF '@${QUALIA_AGENTS}/' "$ref_md")))
     fi
     if [ "${role_count:-0}" -ge "$custom_spawn_count" ]; then
       pass "$name: spawn audit ($custom_spawn_count custom spawn(s), all role-anchored for cache)"
     else
-      fail_case "$name: spawn audit" "$custom_spawn_count custom spawn(s) but only ${role_count:-0} '@~/.claude/agents/' anchors — prompt cache will miss"
+      fail_case "$name: spawn audit" "$custom_spawn_count custom spawn(s) but only ${role_count:-0} '@\${QUALIA_AGENTS}/' anchors — prompt cache will miss"
     fi
   fi
 done

package/tests/state.test.sh

@@ -6,6 +6,8 @@ PASS=0
 FAIL=0
 # Resolve STATE_JS to an ABSOLUTE path so `cd` inside subshells doesn't break it.
 STATE_JS="$(cd "$(dirname "$0")/../bin" && pwd)/state.js"
+FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+STATE_LEDGER_JS="$FRAMEWORK_DIR/bin/state-ledger.js"
 NODE="${NODE:-node}"
 
 # Track tmp dirs we create so we can clean them up on exit
@@ -98,11 +100,18 @@ INIT_EXIT=$?
 if [ "$INIT_EXIT" -eq 0 ] \
    && [ -f "$TMP/.planning/tracking.json" ] \
    && [ -f "$TMP/.planning/STATE.md" ] \
+   && [ -f "$TMP/.planning/qualia/state.jsonl" ] \
    && grep -q '"ok": true' /tmp/qualia-state-test.out \
    && grep -q '"action": "init"' /tmp/qualia-state-test.out; then
-  pass "cmdInit creates tracking.json + STATE.md"
+  pass "cmdInit creates tracking.json + STATE.md + ledger"
 else
-  fail_case "cmdInit creates tracking.json + STATE.md" "exit=$INIT_EXIT"
+  fail_case "cmdInit creates tracking.json + STATE.md + ledger" "exit=$INIT_EXIT"
+fi
+
+if (cd "$TMP" && $NODE "$STATE_LEDGER_JS" validate 2>&1 | grep -q '"ok": true'); then
+  pass "cmdInit writes valid state ledger"
+else
+  fail_case "cmdInit state ledger validates"
 fi
 
 # tracking.json content sanity
@@ -175,13 +184,22 @@ EXIT=$?
 if [ "$EXIT" -eq 0 ] \
    && echo "$OUT" | grep -q '"ok": true' \
    && echo "$OUT" | grep -q '"status": "built"' \
+   && echo "$OUT" | grep -q '"ledger_event_id":' \
    && grep -q '"tasks_done": 5' "$TMP/.planning/tracking.json" \
    && grep -q '"tasks_total": 5' "$TMP/.planning/tracking.json"; then
-  pass "planned → built records tasks_done/tasks_total"
+  pass "planned → built records tasks_done/tasks_total + ledger id"
 else
   fail_case "planned → built" "exit=$EXIT"
 fi
 
+LEDGER_COUNT=$(wc -l < "$TMP/.planning/qualia/state.jsonl" | tr -d ' ')
+if [ "$LEDGER_COUNT" -ge 3 ] \
+   && (cd "$TMP" && $NODE "$STATE_LEDGER_JS" validate 2>&1 | grep -q '"ok": true'); then
+  pass "state ledger records init + transitions as valid chain"
+else
+  fail_case "state ledger transition chain" "count=$LEDGER_COUNT"
+fi
+
 # 6. built → verified(pass) auto-advances to phase 2, resets status to setup
 touch "$TMP/.planning/phase-1-verification.md"
 OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass 2>&1)
@@ -618,6 +636,50 @@ else
   fail_case "validate well-formed plan" "exit=$EXIT out=$OUT"
 fi
 
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" validate-plan --phase 1 --require-contract 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q 'JSON contract missing'; then
+  pass "validate-plan --require-contract fails when JSON contract is missing"
+else
+  fail_case "validate-plan --require-contract missing contract" "exit=$EXIT out=$OUT"
+fi
+
+HASH=$(cd "$TMP" && $NODE -e "const pc=require('$FRAMEWORK_DIR/bin/plan-contract.js'); const fs=require('fs'); process.stdout.write(pc.hashPlan(fs.readFileSync('.planning/phase-1-plan.md','utf8')))")
+cat > "$TMP/.planning/phase-1-contract.json" <<JSON
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "test",
+  "why": "validate require-contract",
+  "generated_at": "2026-05-23T00:00:00Z",
+  "generated_by": "manual",
+  "source_plan_hash": "$HASH",
+  "success_criteria": ["ok"],
+  "tasks": [{
+    "id": "T1",
+    "title": "Task",
+    "wave": 1,
+    "depends_on": [],
+    "files_modify": [],
+    "files_create": [],
+    "files_delete": [],
+    "acceptance_criteria": ["ok"],
+    "action": "Do task",
+    "context_files": [],
+    "verification": [{ "type": "file-exists", "path": ".planning/phase-1-plan.md" }]
+  }]
+}
+JSON
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" validate-plan --phase 1 --require-contract 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"contract_status": "valid"'; then
+  pass "validate-plan --require-contract accepts valid JSON contract"
+else
+  fail_case "validate-plan --require-contract valid contract" "exit=$EXIT out=$OUT"
+fi
+
 # 33. validate-plan rejects empty plan
 TMP=$(make_project)
 echo "" > "$TMP/.planning/phase-1-plan.md"