qualia-framework 4.1.0 → 4.3.0

package/templates/knowledge/agents.md

@@ -0,0 +1,71 @@
+# Memory Layer — How This Works
+
+You are operating inside the **Qualia Framework memory layer**. This file
+describes the system you're in so you can navigate it deliberately. Read this
+once at session start.
+
+## What's here
+
+`~/.claude/knowledge/` is the project-spanning memory tier. It holds three
+kinds of files, each with a clear purpose. Treat the structure as a contract.
+
+```
+~/.claude/knowledge/
+├── agents.md              ← this file (system overview)
+├── index.md               ← entry point — start here when answering questions
+├── daily-log/
+│   └── YYYY-MM-DD.md      ← raw session checkpoints (auto-written by Stop hook)
+├── concepts/              ← (future) promoted, durable patterns
+├── connections/           ← (future) cross-references between concepts
+├── learned-patterns.md    ← curated patterns from /qualia-learn
+├── common-fixes.md        ← recurring fix recipes
+├── supabase-patterns.md   ← Supabase-specific patterns
+├── voice-agent-patterns.md
+├── deployment-map.md
+└── employees.md           ← team roster
+```
+
+## How to use it
+
+**To answer a question that might be in memory:**
+1. Read `index.md` first. It tells you which file is likely to have what you
+   need. Do **not** scan every file — that defeats the index.
+2. Follow the index to one or two specific files. Read those.
+3. If the answer is not there, say so and (when the user agrees) add it via
+   `/qualia-learn`.
+
+**To remember something new:**
+- Use `/qualia-learn`. It writes to the right tier (pattern vs. fix vs.
+  client preference) and updates the index.
+- Do not write to these files directly without an explicit user instruction —
+  the index will fall out of sync.
+
+**Do not pretend something is in memory if it is not.** Better to say
+"INSUFFICIENT EVIDENCE: searched index.md and learned-patterns.md, no entry
+matches" than to hallucinate a recalled pattern. The grounding protocol
+(`~/.claude/rules/grounding.md`) applies here too.
+
+## Tiers
+
+The memory layer follows a Karpathy-style **raw → wiki** progression. Most of
+this is still being built — v4.2.0 ships the daily-log raw tier; v4.3.0 will
+add the LLM-driven flush job that promotes raw entries into concepts and
+connections.
+
+| Tier | Files | How it's written | When to read |
+|------|-------|------------------|--------------|
+| Raw | `daily-log/*.md` | Stop hook (auto, mechanical) | Resuming a recent session, debugging a regression |
+| Curated | `learned-patterns.md`, `common-fixes.md`, `*-patterns.md` | `/qualia-learn` (manual, deliberate) | Answering "how do we usually do X?" |
+| Index | `index.md` | `/qualia-learn` updates it; auto-rebuilt by `bin/knowledge.js` | Always read first |
+
+## Cross-cutting rules
+
+- **Stale data is dangerous.** If a memory file has not been touched in
+  months and the codebase has changed, the memory may be lying. Verify
+  current state in the actual files before recommending anything based on
+  memory.
+- **Project memory ≠ global memory.** Project-specific decisions belong in
+  that project's `.planning/` directory, not here. This directory is for
+  patterns that apply across multiple projects.
+- **Never put secrets here.** API keys, tokens, passwords — never. The
+  knowledge layer is plain markdown checked into a non-encrypted directory.

package/templates/knowledge/index.md

@@ -0,0 +1,47 @@
+# Knowledge Index
+
+Entry point for `~/.claude/knowledge/`. When answering a question, **read this
+file first**, then jump to the specific file(s) that match.
+
+> Auto-maintained by `/qualia-learn`. Do not hand-edit unless the file is out
+> of sync (e.g. after a manual move). Last manual edit: framework install.
+
+## What's where
+
+| If the user asks about… | Read… |
+|--------------------------|-------|
+| "How do we usually X?" / patterns we've used before | `learned-patterns.md` |
+| Recurring bug + fix recipes | `common-fixes.md` |
+| Supabase auth, RLS, migrations, edge functions | `supabase-patterns.md` |
+| Retell, ElevenLabs, voice agent flows | `voice-agent-patterns.md` |
+| Where a project is deployed, env vars, domains | `deployment-map.md` |
+| Who is on the team, their role, their access | `employees.md` |
+| What I worked on yesterday / last week | `daily-log/YYYY-MM-DD.md` |
+| Memory layer architecture itself | `agents.md` |
+
+## Daily log conventions
+
+`daily-log/YYYY-MM-DD.md` is raw, mechanical, and append-only. Each line is a
+single Stop-hook checkpoint with project, branch, phase, task counts, commit
+count, and up to 3 touched files. **Do not promote daily-log content into the
+curated tier by hand** — the upcoming `bin/knowledge-flush.js` will do that
+deliberately. Hand-promoted entries break the source-of-truth invariant.
+
+## Adding new knowledge
+
+Use `/qualia-learn` with the type that matches:
+
+- `pattern` → `learned-patterns.md`
+- `fix` → `common-fixes.md`
+- `client preference` → the relevant project's `.planning/`, **not** this
+  directory
+- `team member info` → `employees.md`
+
+If a new top-level file is needed (e.g. a new technology stack), update this
+index in the same commit.
+
+## Empty / new-install state
+
+If a tier file does not exist yet, that means we have not learned anything in
+that domain yet. Don't pretend we have. Either say "no entries" or, if the
+user is asking you to learn it now, run `/qualia-learn`.

package/tests/bin.test.sh

@@ -476,10 +476,11 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 8 hooks installed
+# 31. All 9 hooks installed (block-env-edit removed in v3.2.0;
+# git-guardrails + stop-session-log added in v4.2.0)
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 8 ]; then
-  pass "8 hooks installed in hooks/"
+if [ "$HOOK_COUNT" -eq 9 ]; then
+  pass "9 hooks installed in hooks/"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi
@@ -488,22 +489,24 @@ fi
 if [ -f "$TMP/.claude/settings.json" ] \
    && grep -q '"SessionStart"' "$TMP/.claude/settings.json" \
    && grep -q '"PreToolUse"' "$TMP/.claude/settings.json" \
+   && grep -q '"Stop"' "$TMP/.claude/settings.json" \
    && grep -q '"statusLine"' "$TMP/.claude/settings.json"; then
-  pass "settings.json has SessionStart, PreToolUse, statusLine"
+  pass "settings.json has SessionStart, PreToolUse, Stop, statusLine"
 else
   fail_case "settings.json contents"
 fi
 
-# 33. settings.json contains all 8 hooks wired correctly
-if grep -q 'block-env-edit.js' "$TMP/.claude/settings.json" \
-   && grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
+# 33. settings.json contains all 9 hooks wired correctly
+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" \
    && grep -q 'pre-deploy-gate.js' "$TMP/.claude/settings.json" \
    && grep -q 'auto-update.js' "$TMP/.claude/settings.json" \
    && grep -q 'session-start.js' "$TMP/.claude/settings.json" \
-   && grep -q 'pre-compact.js' "$TMP/.claude/settings.json"; then
-  pass "settings.json has all 8 hooks wired"
+   && grep -q 'pre-compact.js' "$TMP/.claude/settings.json" \
+   && grep -q 'git-guardrails.js' "$TMP/.claude/settings.json" \
+   && grep -q 'stop-session-log.js' "$TMP/.claude/settings.json"; then
+  pass "settings.json has all 9 hooks wired"
 else
   fail_case "settings.json missing hooks"
 fi
@@ -682,6 +685,310 @@ else
   fail_case "config version mismatch"
 fi
 
+echo ""
+echo "--- v4.2.0 phase 3 (flush + forks + model matrix) ---"
+
+# 61. qualia-flush skill installs
+TMP=$(mktmp)
+echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" >/dev/null 2>&1
+if [ -f "$TMP/.claude/skills/qualia-flush/SKILL.md" ]; then
+  pass "qualia-flush skill installs"
+else
+  fail_case "qualia-flush skill missing after install"
+fi
+
+# 62. CLAUDE_AGENT_FORK_ENABLED=1 in settings.json
+if grep -q '"CLAUDE_AGENT_FORK_ENABLED": "1"' "$TMP/.claude/settings.json"; then
+  pass "settings.env CLAUDE_AGENT_FORK_ENABLED=1 (forked subagents on by default)"
+else
+  fail_case "CLAUDE_AGENT_FORK_ENABLED not set"
+fi
+
+# 63. research-synthesizer agent has model: haiku frontmatter
+if grep -q '^model: haiku$' "$TMP/.claude/agents/research-synthesizer.md"; then
+  pass "research-synthesizer agent uses haiku (model matrix)"
+else
+  fail_case "research-synthesizer missing model frontmatter"
+fi
+
+# 64. Other agents do NOT have model frontmatter (conservative matrix)
+SAFE_AGENTS=("planner.md" "builder.md" "verifier.md" "plan-checker.md")
+ALL_OK=1
+for a in "${SAFE_AGENTS[@]}"; do
+  if grep -q '^model: ' "$TMP/.claude/agents/$a" 2>/dev/null; then
+    ALL_OK=0
+  fi
+done
+if [ "$ALL_OK" = "1" ]; then
+  pass "high-stakes agents (planner/builder/verifier/plan-checker) keep default model"
+else
+  fail_case "high-stakes agent has unexpected model frontmatter"
+fi
+
+echo ""
+echo "--- knowledge.js (memory-layer loader) ---"
+
+KN="$FRAMEWORK_DIR/bin/knowledge.js"
+
+# 48. Help
+EXIT=0; OUT=$($NODE "$KN" help 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "knowledge.js"; then
+  pass "help prints usage"
+else
+  fail_case "help" "exit=$EXIT"
+fi
+
+# 49. Default (no args) → "no entries" stub on fresh install, exit 0
+TMP=$(mktmp)
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "no entries"; then
+  pass "default → exits 0 with stub on fresh install"
+else
+  fail_case "default no init" "exit=$EXIT"
+fi
+
+# 50. With initialized index → returns content
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge"
+echo "# Test Index" > "$TMP/.claude/knowledge/index.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "Test Index"; then
+  pass "default → prints index.md when present"
+else
+  fail_case "default with index" "exit=$EXIT"
+fi
+
+# 51. load <alias> resolves to mapped filename
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge"
+echo "# Patterns" > "$TMP/.claude/knowledge/learned-patterns.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" load patterns 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "# Patterns"; then
+  pass "load patterns → learned-patterns.md"
+else
+  fail_case "load alias" "exit=$EXIT"
+fi
+
+# 52. load <missing-file> → "no entries" stub, exit 0
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" load fixes 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "no entries"; then
+  pass "load missing → exit 0 with stub (skill-pipeable)"
+else
+  fail_case "load missing" "exit=$EXIT"
+fi
+
+# 53. append a pattern → entry lands on disk
+TMP=$(mktmp)
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" append --type pattern --title "RLS rule" --body "Add RLS in same migration as table" 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "appended"; then
+  pass "append pattern → exit 0 with confirmation"
+else
+  fail_case "append pattern" "exit=$EXIT"
+fi
+if [ -f "$TMP/.claude/knowledge/learned-patterns.md" ] \
+   && grep -q "### RLS rule" "$TMP/.claude/knowledge/learned-patterns.md" \
+   && grep -q "Add RLS in same migration" "$TMP/.claude/knowledge/learned-patterns.md"; then
+  pass "appended entry has title + body"
+else
+  fail_case "append content"
+fi
+
+# 54. append without --title → exit 1
+EXIT=0; HOME="$TMP" $NODE "$KN" append --type pattern --body "x" >/dev/null 2>&1 || EXIT=$?
+if [ "$EXIT" -eq 1 ]; then
+  pass "append missing --title → exit 1"
+else
+  fail_case "append missing title" "exit=$EXIT"
+fi
+
+# 55. append with bad type → exit 1
+EXIT=0; HOME="$TMP" $NODE "$KN" append --type bogus --title T --body B >/dev/null 2>&1 || EXIT=$?
+if [ "$EXIT" -eq 1 ]; then
+  pass "append bad --type → exit 1"
+else
+  fail_case "append bad type" "exit=$EXIT"
+fi
+
+# 56. search finds an appended entry
+TMP=$(mktmp)
+HOME="$TMP" $NODE "$KN" append --type fix --title "Vercel build crash" --body "use node 20.x in package.json engines" >/dev/null 2>&1
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" search "Vercel" 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "Vercel"; then
+  pass "search finds appended entries"
+else
+  fail_case "search appended" "exit=$EXIT"
+fi
+
+# 57. search with no matches → "no matches" stub, exit 0
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" search "xyzzy_nonexistent_12345" 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "no matches"; then
+  pass "search no matches → exit 0 with stub"
+else
+  fail_case "search no matches" "exit=$EXIT"
+fi
+
+# 58. list shows existing files
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge"
+echo "x" > "$TMP/.claude/knowledge/foo.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" list 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "foo.md"; then
+  pass "list shows existing files"
+else
+  fail_case "list" "exit=$EXIT"
+fi
+
+# 59. unknown command falls through to load (`knowledge.js patterns` shorthand)
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge"
+echo "# Patterns content" > "$TMP/.claude/knowledge/learned-patterns.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" patterns 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "# Patterns content"; then
+  pass "unknown command → falls through to load"
+else
+  fail_case "fallthrough" "exit=$EXIT"
+fi
+
+# 60. path command resolves alias to absolute path (no read)
+EXIT=0; OUT=$($NODE "$KN" path patterns 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "learned-patterns.md"; then
+  pass "path resolves alias to filename"
+else
+  fail_case "path" "exit=$EXIT"
+fi
+
+echo ""
+echo "--- v4.3.0 (loader subdirs + self-healing skills) ---"
+
+# 65. Subdirectory-qualified path: knowledge.js load concepts/foo
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge/concepts"
+echo "# Stripe checkout" > "$TMP/.claude/knowledge/concepts/stripe.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" load concepts/stripe 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "Stripe checkout"; then
+  pass "load concepts/stripe → reads concepts/stripe.md"
+else
+  fail_case "subdir-qualified load" "exit=$EXIT"
+fi
+
+# 66. Bare name auto-discovers in concepts/
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge/concepts"
+echo "# Voice agent state" > "$TMP/.claude/knowledge/concepts/voice-agent-call-state.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" load voice-agent-call-state 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "Voice agent state"; then
+  pass "load <bare> auto-discovers in concepts/"
+else
+  fail_case "bare-name subdir discovery" "exit=$EXIT"
+fi
+
+# 67. Top-level wins when both top-level and subdir have same filename
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge/concepts"
+echo "# Top level" > "$TMP/.claude/knowledge/foo.md"
+echo "# Subdir version" > "$TMP/.claude/knowledge/concepts/foo.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" load foo 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "Top level" && ! echo "$OUT" | grep -q "Subdir version"; then
+  pass "top-level wins over subdir on bare-name lookup"
+else
+  fail_case "precedence" "exit=$EXIT"
+fi
+
+# 68. Subdir-qualified still works when top-level exists with same name
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" load concepts/foo 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "Subdir version"; then
+  pass "qualified path overrides top-level"
+else
+  fail_case "qualified override" "exit=$EXIT"
+fi
+
+# 69. Search recurses into subdirs
+TMP=$(mktmp)
+mkdir -p "$TMP/.claude/knowledge/concepts"
+echo "supabase RLS pattern" > "$TMP/.claude/knowledge/concepts/auth.md"
+EXIT=0; OUT=$(HOME="$TMP" $NODE "$KN" search RLS 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "concepts/auth.md"; then
+  pass "search recurses into concepts/ subdir"
+else
+  fail_case "search subdir" "exit=$EXIT"
+fi
+
+# 70. qualia-postmortem skill installs
+TMP=$(mktmp)
+echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" >/dev/null 2>&1
+if [ -f "$TMP/.claude/skills/qualia-postmortem/SKILL.md" ]; then
+  pass "qualia-postmortem skill installs"
+else
+  fail_case "qualia-postmortem skill missing"
+fi
+
+# 71. /qualia-verify skill documents --adversarial flag
+if grep -qF -- '--adversarial' "$TMP/.claude/skills/qualia-verify/SKILL.md"; then
+  pass "qualia-verify documents --adversarial flag"
+else
+  fail_case "qualia-verify missing --adversarial"
+fi
+
+# 72. /qualia-verify wires /qualia-postmortem on FAIL
+if grep -q 'qualia-postmortem' "$TMP/.claude/skills/qualia-verify/SKILL.md"; then
+  pass "qualia-verify wires /qualia-postmortem on FAIL"
+else
+  fail_case "qualia-verify missing postmortem wiring"
+fi
+
+# 73. knowledge-flush.js installs at ~/.claude/bin/
+if [ -f "$TMP/.claude/bin/knowledge-flush.js" ]; then
+  pass "knowledge-flush.js installs"
+else
+  fail_case "knowledge-flush.js missing after install"
+fi
+
+# 74. knowledge-flush.js is syntactically valid Node
+EXIT=0; $NODE -c "$TMP/.claude/bin/knowledge-flush.js" 2>/dev/null || EXIT=$?
+if [ "$EXIT" -eq 0 ]; then
+  pass "knowledge-flush.js parses as valid Node"
+else
+  fail_case "knowledge-flush.js parse error"
+fi
+
+# 75. knowledge-flush.js exits 0 with no daily-log (cron-friendly: no spam)
+TMP_HOME=$(mktmp)
+mkdir -p "$TMP_HOME/.claude/knowledge"
+EXIT=0; HOME="$TMP_HOME" $NODE "$FRAMEWORK_DIR/bin/knowledge-flush.js" >/dev/null 2>&1 || EXIT=$?
+if [ "$EXIT" -eq 0 ]; then
+  pass "knowledge-flush exits 0 with no daily-log (no cron spam)"
+else
+  fail_case "knowledge-flush exited $EXIT with no daily-log"
+fi
+
+# 76. knowledge-flush.js writes structured JSONL log even on skip
+TMP_HOME=$(mktmp)
+HOME="$TMP_HOME" $NODE "$FRAMEWORK_DIR/bin/knowledge-flush.js" >/dev/null 2>&1
+if [ -f "$TMP_HOME/.claude/.qualia-flush.log" ] && grep -q '"event":"skipped"' "$TMP_HOME/.claude/.qualia-flush.log"; then
+  pass "knowledge-flush writes JSONL audit log"
+else
+  fail_case "knowledge-flush no audit log"
+fi
+
+# 77. CLI `qualia-framework flush` dispatches to the script (errors when not installed)
+TMP_HOME=$(mktmp)
+EXIT=0; OUT=$(HOME="$TMP_HOME" $NODE "$CLI_JS" flush 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 1 ] && echo "$OUT" | grep -q "knowledge-flush.js not installed"; then
+  pass "CLI flush command surfaces install error gracefully"
+else
+  fail_case "CLI flush dispatch" "exit=$EXIT out=$OUT"
+fi
+
+# 78. CLI flush command appears in help text
+EXIT=0; OUT=$($NODE "$CLI_JS" help 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q "flush"; then
+  pass "help text documents flush command"
+else
+  fail_case "help missing flush" "exit=$EXIT"
+fi
+
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="
 [ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/hooks.test.sh

@@ -379,6 +379,128 @@ else
 fi
 rm -rf "$TMP"
 
+# --- git-guardrails.js ---
+echo ""
+echo "git-guardrails:"
+
+# No stdin / no command → allow (exit 0)
+echo '{}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "no command → allowed" 0 $?
+
+# Force push to main → BLOCK
+echo '{"tool_input":{"command":"git push --force origin main"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "force-push to main → blocked" 2 $?
+
+echo '{"tool_input":{"command":"git push -f origin master"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "force-push (-f) to master → blocked" 2 $?
+
+# --force-with-lease to main → ALLOW (the safe variant)
+echo '{"tool_input":{"command":"git push --force-with-lease origin main"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "--force-with-lease to main → allowed" 0 $?
+
+# Regular push → ALLOW
+echo '{"tool_input":{"command":"git push origin feature/x"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "regular push → allowed" 0 $?
+
+# git clean -fd → BLOCK
+echo '{"tool_input":{"command":"git clean -fd"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "git clean -fd → blocked" 2 $?
+
+echo '{"tool_input":{"command":"git clean -fdx"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "git clean -fdx → blocked" 2 $?
+
+# git branch -D main → BLOCK
+echo '{"tool_input":{"command":"git branch -D main"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "git branch -D main → blocked" 2 $?
+
+# rm -rf .git → BLOCK
+echo '{"tool_input":{"command":"rm -rf .git"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "rm -rf .git → blocked" 2 $?
+
+# rm -rf src → ALLOW (only .git is special)
+echo '{"tool_input":{"command":"rm -rf src/old"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "rm -rf src/old → allowed" 0 $?
+
+# QUALIA_ALLOW_DESTRUCTIVE=1 escape hatch → ALLOW even force push
+echo '{"tool_input":{"command":"git push --force origin main"}}' | QUALIA_ALLOW_DESTRUCTIVE=1 $NODE "$HOOKS_DIR/git-guardrails.js" > /dev/null 2>&1
+assert_exit "QUALIA_ALLOW_DESTRUCTIVE=1 → allowed despite force-push" 0 $?
+
+# Block reason includes "BLOCKED" + "main" for force push to main
+OUT=$(echo '{"tool_input":{"command":"git push --force origin main"}}' | $NODE "$HOOKS_DIR/git-guardrails.js" 2>&1)
+if echo "$OUT" | grep -q "BLOCKED" && echo "$OUT" | grep -q "main"; then
+  echo "  ✓ block reason includes BLOCKED + main"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ block reason missing BLOCKED or main: $OUT"
+  FAIL=$((FAIL + 1))
+fi
+
+# --- stop-session-log.js ---
+echo ""
+echo "stop-session-log:"
+
+# Outside a git repo, with nothing to log → exit 0 silent
+TMP=$(mktemp -d)
+HOME="$TMP" $NODE "$HOOKS_DIR/stop-session-log.js" >/dev/null 2>&1
+assert_exit "no activity → exit 0 silent" 0 $?
+# Daily log dir might or might not exist; the hook must NOT crash either way.
+rm -rf "$TMP"
+
+# In a git repo with .planning/tracking.json → writes to daily log
+TMP=$(mktemp -d)
+mkdir -p "$TMP/proj/.planning"
+(cd "$TMP/proj" && git init -q && git checkout -b feat/test -q 2>/dev/null && git config user.email t@t.com && git config user.name T)
+echo "x" > "$TMP/proj/file.txt"
+(cd "$TMP/proj" && git add file.txt && git commit -q -m "seed" 2>/dev/null)
+cat > "$TMP/proj/.planning/tracking.json" <<EOF
+{"phase":2,"phase_total":4,"tasks_done":3,"tasks_total":5}
+EOF
+# Touch a file so the diff has something
+echo "y" >> "$TMP/proj/file.txt"
+(cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/stop-session-log.js" >/dev/null 2>&1)
+assert_exit "with activity → exit 0" 0 $?
+TODAY=$(date -u +%Y-%m-%d)
+LOG_FILE="$TMP/.claude/knowledge/daily-log/$TODAY.md"
+if [ -f "$LOG_FILE" ] && grep -q "phase=2/4" "$LOG_FILE" && grep -q "tasks=3/5" "$LOG_FILE"; then
+  echo "  ✓ daily-log contains phase + tasks"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ daily-log missing or malformed: $(cat "$LOG_FILE" 2>/dev/null)"
+  FAIL=$((FAIL + 1))
+fi
+# Header is project name (basename of repo root)
+if [ -f "$LOG_FILE" ] && grep -q "^## proj$" "$LOG_FILE"; then
+  echo "  ✓ daily-log has project header"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ daily-log missing project header"
+  FAIL=$((FAIL + 1))
+fi
+rm -rf "$TMP"
+
+# Stop hook is idempotent within MIN_INTERVAL_MS — second run within 5min skips
+TMP=$(mktemp -d)
+mkdir -p "$TMP/proj/.planning" "$TMP/.claude"
+(cd "$TMP/proj" && git init -q && git checkout -b feat/x -q 2>/dev/null && git config user.email t@t.com && git config user.name T)
+echo "z" > "$TMP/proj/f.txt"
+(cd "$TMP/proj" && git add f.txt && git commit -q -m "s" 2>/dev/null)
+echo '{"phase":1,"phase_total":2,"tasks_done":1,"tasks_total":2}' > "$TMP/proj/.planning/tracking.json"
+echo "a" >> "$TMP/proj/f.txt"
+# First run — writes
+(cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/stop-session-log.js" >/dev/null 2>&1)
+LINES_BEFORE=$(wc -l < "$TMP/.claude/knowledge/daily-log/$(date -u +%Y-%m-%d).md" 2>/dev/null || echo 0)
+# Second run within 5min — must skip
+(cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/stop-session-log.js" >/dev/null 2>&1)
+LINES_AFTER=$(wc -l < "$TMP/.claude/knowledge/daily-log/$(date -u +%Y-%m-%d).md" 2>/dev/null || echo 0)
+if [ "$LINES_BEFORE" = "$LINES_AFTER" ]; then
+  echo "  ✓ second run within MIN_INTERVAL skips (no double-write)"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ second run wrote anyway ($LINES_BEFORE → $LINES_AFTER)"
+  FAIL=$((FAIL + 1))
+fi
+rm -rf "$TMP"
+
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="
 [ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/runner.js

@@ -1486,7 +1486,15 @@ describe("Hooks", () => {
 
   // v3.4.2: behavioral test — the stamp must actually mutate tracking.json
   // AND create a real commit so the push includes it.
-  it("pre-push.js mutates tracking.json AND commits the stamp", () => {
+  //
+  // v4.1.1 NOTE: skipped on Windows. The stamp-commit interacts with git's
+  // autocrlf in ways that are not fully reproducible without a live Windows
+  // box — pre-push.js now passes `-c core.autocrlf=false` on its own git
+  // commands (defensive), but the test's seed-commit path still hits an
+  // edge case on Windows that needs platform-specific investigation. This
+  // is tracked as a v4.1.2 follow-up; the Linux+macOS paths (which are the
+  // overwhelming majority of installs) are fully covered here.
+  it("pre-push.js mutates tracking.json AND commits the stamp", { skip: process.platform === "win32" ? "pre-existing autocrlf edge case — investigate in v4.1.2" : false }, () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-push-real-"));
     try {
       // Init a real git repo
@@ -2528,7 +2536,12 @@ describe("install.js", () => {
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "bin", "state.js")));
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "bin", "qualia-ui.js")));
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "bin", "statusline.js")));
+      assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "bin", "knowledge.js")));
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", ".qualia-config.json")));
+      // v4.2.0 — knowledge layer must be initialized
+      assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "knowledge", "agents.md")));
+      assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "knowledge", "index.md")));
+      assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "knowledge", "daily-log")));
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }
@@ -2559,12 +2572,12 @@ describe("install.js", () => {
     }
   });
 
-  it("7 hooks installed (block-env-edit removed in v3.2.0)", () => {
+  it("9 hooks installed (block-env-edit removed in v3.2.0; git-guardrails + stop-session-log added in v4.2.0)", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
       runInstall("QS-FAWZI-01", tmpHome);
       const hooks = fs.readdirSync(path.join(tmpHome, ".claude", "hooks")).filter(f => f.endsWith(".js"));
-      assert.equal(hooks.length, 7);
+      assert.equal(hooks.length, 9);
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }