qualia-framework 6.3.0 → 6.5.0

package/skills/zoho-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zoho-workflow
-description: "Zoho Invoice and Mail operations via ERP-first routing. Creates invoices from templates, sends cover emails, manages contacts, reads inbox, and handles payment reminders. Use when the user says 'invoice this client', 'send an email', 'check inbox', 'create a Zoho contact', 'send payment reminder', or mentions invoicing, billing, or Zoho."
+description: "Zoho Invoice + Mail ops via ERP-first routing. Invoices from templates, cover emails, contacts, inbox, payment reminders. Triggers: 'invoice this client', 'send an email', 'check inbox', 'create a Zoho contact', 'payment reminder'."
 tags: [zoho, invoice, email, billing, crm]
 ---
 

package/tests/bin.test.sh

@@ -487,13 +487,14 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 12 hooks installed (block-env-edit removed in v3.2.0;
+# 31. All 13 hooks installed (block-env-edit removed in v3.2.0;
 # git-guardrails + stop-session-log added in v4.2.0;
 # vercel-account-guard + env-empty-guard + supabase-destructive-guard added in v5.0.0;
-# pre-compact removed in v6.2.0; fawzi-approval-guard added in v6.2.11)
+# fawzi-approval-guard added in v6.2.11; pre-compact removed in v6.2.0 and
+# REINTRODUCED in v6.3.2 with sidecar-snapshot mechanism)
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 12 ]; then
-  pass "12 hooks installed in hooks/"
+if [ "$HOOK_COUNT" -eq 13 ]; then
+  pass "13 hooks installed in hooks/ (incl. pre-compact v6.3.2)"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi
@@ -509,8 +510,7 @@ else
   fail_case "settings.json contents"
 fi
 
-# 33. settings.json contains all 12 hooks wired correctly
-#     pre-compact.js was removed in v6.2.0 — verify it's NOT in settings.json.
+# 33. settings.json contains all 13 hooks wired correctly (v6.3.2 reintroduces pre-compact).
 if grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'migration-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'pre-push.js' "$TMP/.claude/settings.json" \
@@ -523,10 +523,10 @@ if grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'fawzi-approval-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'env-empty-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'supabase-destructive-guard.js' "$TMP/.claude/settings.json" \
-   && ! grep -q 'pre-compact.js' "$TMP/.claude/settings.json"; then
-  pass "settings.json has all 12 hooks wired (no pre-compact)"
+   && grep -q 'pre-compact.js' "$TMP/.claude/settings.json"; then
+  pass "settings.json has all 13 hooks wired (incl. pre-compact)"
 else
-  fail_case "settings.json hooks misconfigured (check for stale pre-compact entry)"
+  fail_case "settings.json hooks misconfigured"
 fi
 
 # 34. Lowercase code works (resolveTeamCode normalizes)

package/tests/install-smoke.test.sh

@@ -124,10 +124,10 @@ else
 fi
 
 if [ -d "$HOME_DIR/.claude/hooks" ] \
-  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "12" ] \
+  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "13" ] \
   && [ -f "$HOME_DIR/.claude/hooks/fawzi-approval-guard.js" ] \
-  && [ ! -f "$HOME_DIR/.claude/hooks/pre-compact.js" ]; then
-  pass "packaged install has 12 hooks and no pre-compact"
+  && [ -f "$HOME_DIR/.claude/hooks/pre-compact.js" ]; then
+  pass "packaged install has 13 hooks including pre-compact (v6.3.2 sidecar snapshot)"
 else
   fail_case "packaged hook set mismatch"
 fi

package/tests/lib.test.sh

@@ -369,9 +369,16 @@ CS="$FRAMEWORK_DIR/bin/command-surface.js"
 $NODE --check "$CS" >/dev/null 2>&1 && ok "command-surface.js parses" || fail "command-surface.js parse"
 RES=$($NODE -e '
 const cs = require("'"$CS"'");
-console.log(cs.ACTIVE_SKILLS.length === 23 && cs.RETIRED_SKILLS.includes("qualia-debug") && cs.RETIRED_SKILLS.includes("qualia-vibe") ? "SURFACE-OK" : JSON.stringify(cs));
+const active = cs.ACTIVE_SKILLS;
+const retired = cs.RETIRED_SKILLS;
+const ok =
+  Array.isArray(active) && active.length > 0 &&
+  active.includes("qualia-scope") && active.includes("qualia-idk") && active.includes("qualia-secure") &&
+  !active.includes("qualia-debug") && retired.includes("qualia-debug") &&
+  !active.includes("qualia-vibe") && retired.includes("qualia-vibe");
+console.log(ok ? "SURFACE-OK" : JSON.stringify(cs));
 ')
-[ "$RES" = "SURFACE-OK" ] && ok "command-surface defines 23 active skills and retired folds" || fail "command-surface manifest: $RES"
+[ "$RES" = "SURFACE-OK" ] && ok "command-surface manifest: active surface excludes retired folds (qualia-debug/qualia-vibe), count derived from ACTIVE_SKILLS" || fail "command-surface manifest: $RES"
 RES=$($NODE -e '
 const fs = require("fs");
 const path = require("path");
@@ -382,12 +389,12 @@ const dirs = fs.readdirSync(path.join(root, "skills"), { withFileTypes: true })
   .map((d) => d.name)
   .sort();
 const active = [...ACTIVE_SKILLS].sort();
-const extra = dirs.filter((d) => !active.includes(d));
+const known = new Set([...ACTIVE_SKILLS, ...RETIRED_SKILLS]);
+const orphans = dirs.filter((d) => !known.has(d));
 const missing = active.filter((d) => !dirs.includes(d));
-const retiredPresent = RETIRED_SKILLS.filter((d) => dirs.includes(d));
-console.log(!extra.length && !missing.length && !retiredPresent.length ? "SKILL-DIRS-OK" : JSON.stringify({ extra, missing, retiredPresent }));
+console.log(!orphans.length && !missing.length ? "SKILL-DIRS-OK" : JSON.stringify({ orphans, missing }));
 ')
-[ "$RES" = "SKILL-DIRS-OK" ] && ok "skills directory matches active command surface only" || fail "skill directory surface: $RES"
+[ "$RES" = "SKILL-DIRS-OK" ] && ok "every active skill has a folder; no orphan skill folders" || fail "skill directory surface: $RES"
 
 TMP=$(mktmp)
 RES=$(cd "$TMP" && $NODE -e '
@@ -500,7 +507,7 @@ TMP=$(mktmp)
 mkdir -p "$TMP/home/.claude/bin" "$TMP/home/.claude/hooks" "$TMP/home/.claude/knowledge/daily-log" "$TMP/home/.claude/qualia-design" "$TMP/home/.claude/agents" "$TMP/home/.claude/qualia-templates" "$TMP/project"
 echo '{"installed_by":"Test","role":"OWNER","version":"6.3.0","erp":{"enabled":false}}' > "$TMP/home/.claude/.qualia-config.json"
 touch "$TMP/home/.claude/CLAUDE.md" "$TMP/home/.claude/settings.json"
-for f in runtime-manifest.js command-surface.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 harness-eval.js trust-score.js agent-runs.js slop-detect.mjs erp-retry.js work-packet.js report-payload.js project-snapshot.js codex-goal.js planning-hygiene.js; do
+for f in runtime-manifest.js command-surface.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 harness-eval.js trust-score.js agent-runs.js slop-detect.mjs erp-retry.js work-packet.js report-payload.js project-snapshot.js codex-goal.js planning-hygiene.js prune-deprecated.js learning-candidates.js status-snapshot.js security-scan.js; do
   touch "$TMP/home/.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 fawzi-approval-guard.js vercel-account-guard.js env-empty-guard.js supabase-destructive-guard.js; do
@@ -510,7 +517,7 @@ touch "$TMP/home/.claude/knowledge/index.md" "$TMP/home/.claude/knowledge/agents
 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/home/.claude/qualia-design/$f"
 done
-for s in qualia qualia-new qualia-discuss qualia-map qualia-research qualia-plan qualia-build qualia-verify qualia-fix qualia-feature qualia-review qualia-optimize qualia-polish qualia-test qualia-milestone qualia-ship qualia-handoff qualia-report qualia-doctor qualia-road qualia-learn qualia-postmortem zoho-workflow; do
+for s in $($NODE -e 'console.log(require(process.argv[1]).ACTIVE_SKILLS.join(" "))' "$CS"); do
   mkdir -p "$TMP/home/.claude/skills/$s"
   touch "$TMP/home/.claude/skills/$s/SKILL.md"
 done
@@ -615,7 +622,7 @@ 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 command-surface.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 harness-eval.js trust-score.js agent-runs.js slop-detect.mjs erp-retry.js work-packet.js report-payload.js project-snapshot.js codex-goal.js planning-hygiene.js; do
+for f in runtime-manifest.js command-surface.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 harness-eval.js trust-score.js agent-runs.js slop-detect.mjs erp-retry.js work-packet.js report-payload.js project-snapshot.js codex-goal.js planning-hygiene.js prune-deprecated.js learning-candidates.js status-snapshot.js security-scan.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 fawzi-approval-guard.js vercel-account-guard.js env-empty-guard.js supabase-destructive-guard.js; do
@@ -625,7 +632,7 @@ 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 qualia-new qualia-discuss qualia-map qualia-research qualia-plan qualia-build qualia-verify qualia-fix qualia-feature qualia-review qualia-optimize qualia-polish qualia-test qualia-milestone qualia-ship qualia-handoff qualia-report qualia-doctor qualia-road qualia-learn qualia-postmortem zoho-workflow; do
+for s in $($NODE -e 'console.log(require(process.argv[1]).ACTIVE_SKILLS.join(" "))' "$CS"); do
   mkdir -p "$TMP/.claude/skills/$s"
   touch "$TMP/.claude/skills/$s/SKILL.md"
 done

package/tests/published-install-smoke.test.sh

@@ -102,10 +102,10 @@ else
 fi
 
 if [ -d "$HOME_DIR/.claude/hooks" ] \
-  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "12" ] \
+  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "13" ] \
   && [ -f "$HOME_DIR/.claude/hooks/fawzi-approval-guard.js" ] \
-  && [ ! -f "$HOME_DIR/.claude/hooks/pre-compact.js" ]; then
-  pass "public install has 12 hooks and no pre-compact"
+  && [ -f "$HOME_DIR/.claude/hooks/pre-compact.js" ]; then
+  pass "public install has 13 hooks including pre-compact (v6.3.2 sidecar snapshot)"
 else
   fail_case "public install hook set mismatch"
 fi

package/tests/refs.test.sh

@@ -79,27 +79,33 @@ SCAN_FILES=$(
 #   1. `/qualia-foo`       — backticked, the canonical command-doc style
 #   2. <dt>/qualia-foo</dt> — HTML help/onboarding pages
 # We capture name + file:line so we can show context per failure.
-declare -A SEEN_REFS
-declare -A REF_LOCATIONS
-declare -A ACTIVE_SKILL_MAP
-
-while IFS= read -r skill; do
-  [ -n "$skill" ] && ACTIVE_SKILL_MAP["/$skill"]=1
-done < <("$NODE" -e 'const {ACTIVE_SKILLS}=require(process.argv[1]); for (const s of ACTIVE_SKILLS) console.log(s)' "$FRAMEWORK_ROOT/bin/command-surface.js")
+#
+# Storage uses a temp file (one line per "ref<TAB>location") instead of
+# bash 4 associative arrays — macOS ships bash 3.2 (frozen at that version
+# for licensing reasons) which lacks `declare -A`. Temp file is portable
+# and behaves correctly under `set -u`.
+REF_STORE=$(mktemp)
+ACTIVE_SKILLS_LIST=$("$NODE" -e 'const {ACTIVE_SKILLS}=require(process.argv[1]); console.log(ACTIVE_SKILLS.map(s => "/" + s).join(" "))' "$FRAMEWORK_ROOT/bin/command-surface.js")
+trap 'rm -f "$REF_STORE"' EXIT
+
+# is_active "/qualia-foo" → returns 0 if in ACTIVE_SKILLS_LIST.
+is_active() {
+  case " $ACTIVE_SKILLS_LIST " in
+    *" $1 "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
 
 while IFS= read -r file; do
   # Pattern A: backtick-quoted commands. Allow trailing flag/word but only capture base name.
   while IFS=: read -r path lineno line; do
     [ -z "$line" ] && continue
-    # Skip migration-context lines.
     if echo "$line" | grep -qE "$MIGRATION_CONTEXT_REGEX"; then
       continue
     fi
-    # Extract every backticked /qualia-foo on this line.
     matches=$(echo "$line" | grep -oE '`/qualia(-[a-z]+){0,3}`' | sed 's/^`//; s/`$//')
     for ref in $matches; do
-      SEEN_REFS["$ref"]=1
-      REF_LOCATIONS["$ref"]="${REF_LOCATIONS[$ref]:+${REF_LOCATIONS[$ref]}, }$(basename "$path"):$lineno"
+      printf '%s\t%s:%s\n' "$ref" "$(basename "$path")" "$lineno" >> "$REF_STORE"
     done
   done < <(grep -nE '`/qualia(-[a-z]+){0,3}`' "$file" 2>/dev/null)
 
@@ -111,36 +117,37 @@ while IFS= read -r file; do
     fi
     matches=$(echo "$line" | grep -oE '<dt>/qualia(-[a-z]+){0,3}( [^<]*)?</dt>' | sed -E 's|<dt>(/qualia(-[a-z]+){0,3}).*|\1|')
     for ref in $matches; do
-      SEEN_REFS["$ref"]=1
-      REF_LOCATIONS["$ref"]="${REF_LOCATIONS[$ref]:+${REF_LOCATIONS[$ref]}, }$(basename "$path"):$lineno"
+      printf '%s\t%s:%s\n' "$ref" "$(basename "$path")" "$lineno" >> "$REF_STORE"
     done
   done < <(grep -nE '<dt>/qualia' "$file" 2>/dev/null)
 done <<<"$SCAN_FILES"
 
-if [ ${#SEEN_REFS[@]} -eq 0 ]; then
+if [ ! -s "$REF_STORE" ]; then
   fail_case "scan" "no backticked /qualia-* references found across active surfaces (scanner broken?)"
   echo ""
   echo "Results: $PASS passed, $FAIL failed"
   exit 1
 fi
 
-# Sort refs for deterministic output.
-for ref in $(printf '%s\n' "${!SEEN_REFS[@]}" | sort); do
+# Iterate unique refs, deterministic order.
+for ref in $(cut -f1 "$REF_STORE" | sort -u); do
   name="${ref#/}"
   skill_dir="$SKILLS_DIR/$name"
-  locations="${REF_LOCATIONS[$ref]}"
-  if [ "${ACTIVE_SKILL_MAP[$ref]:-}" = "1" ] && [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
+  # Comma-join all locations for this ref.
+  locations=$(awk -v r="$ref" -F'\t' '$1==r {print $2}' "$REF_STORE" | paste -sd, -)
+  if is_active "$ref" && [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
     pass "$ref → active skills/$name/SKILL.md"
     continue
   fi
   fail_case "$ref" "not an active shipped command or missing skills/$name/SKILL.md — referenced by: $locations"
 done
 
-PACKAGE_VERSION="$("$NODE" -e 'console.log(require(process.argv[1]).version)' "$FRAMEWORK_ROOT/package.json" 2>/dev/null || echo "")"
-if [ -n "$PACKAGE_VERSION" ] && grep -q "# Qualia Framework v$PACKAGE_VERSION" "$FRAMEWORK_ROOT/README.md"; then
-  pass "README title matches package.json version ($PACKAGE_VERSION)"
+# README title is version-less by design — version lives in package.json + CHANGELOG.md,
+# not in the README h1, so the orientation block above the fold stays version-stable.
+if grep -qE '^# Qualia Framework( |$)' "$FRAMEWORK_ROOT/README.md"; then
+  pass "README h1 is version-less (version lives in CHANGELOG.md)"
 else
-  fail_case "README version drift" "README.md title must match package.json version $PACKAGE_VERSION"
+  fail_case "README h1 shape" "README.md must open with '# Qualia Framework' (no version suffix)"
 fi
 
 forbidden_surface_patterns=(

package/tests/runner.js

@@ -2578,14 +2578,14 @@ describe("install.js", () => {
     }
   });
 
-  it("12 hooks installed (v6.2.11: proxy approval guard added; v6.2.0: pre-compact removed)", () => {
+  it("13 hooks installed (v6.3.2: pre-compact reintroduced with sidecar-snapshot mechanism)", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
       runInstall("QS-FAWZI-11", tmpHome);
       const hooks = fs.readdirSync(path.join(tmpHome, ".claude", "hooks")).filter(f => f.endsWith(".js"));
-      assert.equal(hooks.length, 12, `expected 12 hooks, got ${hooks.length}: ${hooks.join(", ")}`);
+      assert.equal(hooks.length, 13, `expected 13 hooks, got ${hooks.length}: ${hooks.join(", ")}`);
       assert.ok(hooks.includes("fawzi-approval-guard.js"), "fawzi-approval-guard.js must be installed");
-      assert.ok(!hooks.includes("pre-compact.js"), "pre-compact.js must NOT be installed (removed in v6.2.0)");
+      assert.ok(hooks.includes("pre-compact.js"), "pre-compact.js must be installed (v6.3.2 sidecar-snapshot mechanism)");
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }

package/tests/state.test.sh

@@ -4,9 +4,40 @@
 
 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)"
+# Windows portability — coerce shell-native MSYS paths (/d/a/..., /tmp/...) to
+# Windows-native form (D:/a/..., C:/Users/.../Temp/...) before they get
+# interpolated into Node `$NODE -e` snippets. Without coercion, Node receives
+# the MSYS string literally and resolves it against the current drive, yielding
+# non-existent paths like `D:\tmp\tmp.XXX\.planning\tracking.json`.
+#
+# Mechanism: `cygpath -m` is the canonical MSYS path converter and is present
+# on Git Bash / MSYS2 (Windows GitHub runners use Git Bash for `shell: bash`).
+# `pwd -W` doesn't work because bash's builtin pwd doesn't accept -W, and
+# /usr/bin/pwd's -W support varies by MSYS distribution.
+# On Linux/macOS, cygpath doesn't exist — fall through to plain pwd.
+_pwd_native() {
+  local p
+  p=$(pwd)
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -m "$p" 2>/dev/null || echo "$p"
+  else
+    echo "$p"
+  fi
+}
+_mktemp_native() {
+  local d
+  d=$(mktemp -d) || return 1
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -m "$d" 2>/dev/null || echo "$d"
+  else
+    echo "$d"
+  fi
+}
+
+# Resolve STATE_JS to an ABSOLUTE Windows-native path so `cd` inside subshells
+# doesn't break it.
+STATE_JS="$(cd "$(dirname "$0")/../bin" && _pwd_native)/state.js"
+FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && _pwd_native)"
 STATE_LEDGER_JS="$FRAMEWORK_DIR/bin/state-ledger.js"
 NODE="${NODE:-node}"
 
@@ -23,7 +54,7 @@ trap cleanup EXIT
 # Prints the absolute path to the new tmp dir (does NOT cd).
 make_project() {
   local TMP
-  TMP=$(mktemp -d)
+  TMP=$(_mktemp_native)
   TMP_DIRS+=("$TMP")
   (
     cd "$TMP" || exit 1
@@ -129,7 +160,7 @@ fi
 echo "basic I/O:"
 
 # 1. cmdInit produces valid tracking.json + STATE.md
-TMP=$(mktemp -d); TMP_DIRS+=("$TMP")
+TMP=$(_mktemp_native); TMP_DIRS+=("$TMP")
 (
   cd "$TMP" || exit 1
   $NODE "$STATE_JS" init \
@@ -190,7 +221,7 @@ else
 fi
 
 # 3. cmdCheck with no project → ok:false NO_PROJECT, exit 1
-TMP2=$(mktemp -d); TMP_DIRS+=("$TMP2")
+TMP2=$(_mktemp_native); TMP_DIRS+=("$TMP2")
 OUT=$(cd "$TMP2" && $NODE "$STATE_JS" check 2>&1)
 CHECK_EXIT=$?
 if [ "$CHECK_EXIT" -eq 1 ] \
@@ -1014,7 +1045,7 @@ else
 fi
 
 # 49. First-time init (no existing tracking.json) sets lifetime to zeros
-TMP=$(mktemp -d); TMP_DIRS+=("$TMP")
+TMP=$(_mktemp_native); TMP_DIRS+=("$TMP")
 (cd "$TMP" && $NODE "$STATE_JS" init \
   --project "FreshProject" \
   --phases '[{"name":"P1","goal":"G1"}]' \