qualia-framework 6.9.2 → 6.14.0

package/skills/qualia-update/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: qualia-update
+description: "Ship one update to a LAUNCHED project (operate lifecycle). The post-launch counterpart to /qualia-milestone — a lean plan → build → verify → ship loop with no milestone-journey or forced-handoff machinery. Triggers: 'ship an update', 'make a change to the live site', 'the project is live, I need to add X', 'operate mode', 'post-launch change', 'patch the launched product'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /qualia-update — ship one update to a launched project
+
+The operate-lifecycle counterpart to `/qualia-milestone`. Once a project has
+**launched** (`state.js launch` flips `lifecycle` from `build` to `operate`), it
+is an **update stream**, not a milestone journey: there is no forced
+polish → ship → **handoff** terminal. `/qualia-update` runs one lean change
+cycle and loops. Each completed update bumps `lifetime.updates_completed`.
+
+## Output contract
+
+```
+Command: /qualia-update {change}
+Scope: {files/routes touched}
+Intent: build
+Mutation: planned → active
+Evidence: state.js check, contract-runner output
+Output: shipped update + deployed URL
+Next: /qualia-update (next change) or done
+```
+
+## Process
+
+### 1. Confirm the project is launched
+
+```bash
+node ${QUALIA_BIN}/state.js check
+```
+
+- `lifecycle: "operate"` → proceed.
+- `lifecycle: "build"` and the product is actually live → launch it first:
+  ```bash
+  node ${QUALIA_BIN}/state.js launch --deployed-url {url} --source manual
+  ```
+  (The ERP can also drive this automatically when it detects the project is live.)
+- Still mid-build (never launched, not live) → this is `/qualia-feature` or a
+  normal phase, not an update. Route there instead.
+
+### 2. Scope the change (one update = one coherent change)
+
+Keep it small and shippable. A bug fix, a copy change, a new section, a single
+feature. If it's larger than ~5 files or needs its own milestone arc, it's a new
+`build`-mode milestone — use `/qualia-milestone`, not an update.
+
+### 3. Run the lean loop
+
+Reuse the real lifecycle skills, scoped to this one change:
+
+```
+/qualia-plan {N}     # compile the change into a phase + machine contract
+/qualia-build {N}    # builders execute, atomic commits
+/qualia-verify {N}   # contract-runner evidence + goal-backward check (must PASS)
+```
+
+Verification evidence is mandatory exactly as in build mode — a contract runs and
+its evidence must be clean before PASS. On the final phase, a `verified(pass)`
+in operate routes here again (`next_command: /qualia-update`) and increments
+`lifetime.updates_completed`.
+
+### 4. Ship
+
+```bash
+/qualia-ship        # quality gates → commit → deploy → verify live
+```
+
+No handoff. No "final milestone." The deploy is just this update going live. Then
+`/qualia-report` as usual — the report carries `lifecycle: operate` and the
+updated `updates_completed` so the ERP counts updates, not milestones.
+
+### 5. Loop or stop
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js end "UPDATE SHIPPED" "/qualia-update"
+```
+
+Run `/qualia-update` again for the next change, or stop — an operate project has
+no terminal state to reach.
+
+## Why this exists
+
+Hard-coding "every project ends in Handoff" forced launched products and
+retainers into a state machine that fought them. `/qualia-update` + the `operate`
+lifecycle make "this project is live and keeps shipping" explicit state instead
+of a milestone the team is forced to mislabel. See `templates/journey.md` rule 3.

package/skills/qualia-verify/SKILL.md

@@ -175,7 +175,13 @@ Write the deterministic eval artifact before changing state:
 node ${QUALIA_BIN}/harness-eval.js --phase {N} --run --write
 ```
 
-If the eval status is `FAIL`, do not mark the phase PASS. The state machine also refuses PASS when a contract exists but `.planning/evidence/phase-{N}-contract-run.json` is missing/failing, or when the verification report contains `INSUFFICIENT EVIDENCE`.
+Run the zero-token anti-slop scan as a deterministic gate (same role as `migration-guard`/`branch-guard` — the scanner exits non-zero on CRITICAL design tells). A CRITICAL finding is a verification FAIL, not a soft note:
+
+```bash
+node ${QUALIA_BIN}/slop-detect.mjs --severity=critical
+```
+
+If the eval status is `FAIL` or anti-slop exits non-zero, do not mark the phase PASS. The state machine also refuses PASS when a contract exists but `.planning/evidence/phase-{N}-contract-run.json` is missing/failing, or when the verification report contains `INSUFFICIENT EVIDENCE`.
 
 ```bash
 node ${QUALIA_BIN}/state.js transition --to verified --phase {N} --verification {pass|fail} --evidence .planning/evals/harness-eval-*.json

package/templates/journey.md

@@ -102,7 +102,7 @@ M1 ─── M2 ─── M3 ─── ... ─── M{N} (Handoff)
 
 1. **Hard ceiling: 5 milestones.** If the project needs more, defer to a v2 release after handoff.
 2. **Hard floor: 2 milestones.** Anything smaller should use `/qualia-new --quick` instead.
-3. **The final milestone is always Handoff.** Same 4 phases every project. Never negotiable.
+3. **In BUILD mode, the final milestone is Handoff.** This is the convention for a one-shot client build that ends with a handoff. It is **not** a universal law: once a project launches and enters the `operate` lifecycle (`state.js launch`), it becomes an *update stream* with no forced Handoff — it ships updates indefinitely. Don't author a Handoff milestone for a product/retainer that will keep shipping; launch it instead.
 4. **Milestones ≥ 2 phases OR are a shipped release gate.** A 1-phase milestone is a phase, not a milestone.
 5. **Numbering is contiguous.** No skipped milestone numbers.
 6. **Progressive detail is OK.** M1 is fully detailed (ready for `/qualia-plan`). M2..M{N-1} have phase names + one-line goals. Full phase detail gets written by roadmapper when the milestone opens.

package/tests/agent-status.test.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# agent-status.test.sh — bin/agent-status.js (per-task status + fan-in barrier)
+# Run: bash tests/agent-status.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+AS="$BIN_DIR/agent-status.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" haystack="$2" needle="$3"
+  if echo "$haystack" | grep -q "$needle"; then
+    echo "  ✓ $name"; PASS=$((PASS + 1))
+  else
+    echo "  ✗ $name (missing '$needle' in: $haystack)"; FAIL=$((FAIL + 1))
+  fi
+}
+
+# A minimal contract with two tasks in wave 1, one in wave 2.
+write_contract() {
+  cat > "$1" <<'EOF'
+{
+  "version": 1,
+  "tasks": [
+    { "id": "T1", "wave": 1 },
+    { "id": "T2", "wave": 1 },
+    { "id": "T3", "wave": 2 }
+  ]
+}
+EOF
+}
+
+echo "agent-status.test.sh — bin/agent-status.js"
+echo ""
+
+# syntax
+$NODE -c "$AS" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- write / read round-trip ---
+TMP=$(mktemp -d)
+$NODE "$AS" write T1 RUNNING --phase 3 --wave 1 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "write RUNNING → exit 0" 0 $?
+[ -f "$TMP/.agent-status/T1.json" ] && { echo "  ✓ status file created"; PASS=$((PASS+1)); } || { echo "  ✗ status file missing"; FAIL=$((FAIL+1)); }
+OUT=$($NODE "$AS" read T1 --cwd "$TMP" --json 2>&1)
+assert_contains "read shows RUNNING" "$OUT" '"status":"RUNNING"'
+$NODE "$AS" write T1 DONE --commit abc1234 --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" read T1 --cwd "$TMP" --json 2>&1)
+assert_contains "overwrite to DONE" "$OUT" '"status":"DONE"'
+assert_contains "records commit hash" "$OUT" 'abc1234'
+rm -rf "$TMP"
+
+# --- validation: bad task id and bad status are rejected (exit 2) ---
+TMP=$(mktemp -d)
+$NODE "$AS" write nope DONE --cwd "$TMP" >/dev/null 2>&1
+assert_exit "invalid task id → exit 2" 2 $?
+$NODE "$AS" write T1 FINISHED --cwd "$TMP" >/dev/null 2>&1
+assert_exit "invalid status → exit 2" 2 $?
+# traversal attempt in task id is rejected (no file written outside dir)
+$NODE "$AS" write ../evil DONE --cwd "$TMP" >/dev/null 2>&1
+assert_exit "path-traversal task id → exit 2" 2 $?
+rm -rf "$TMP"
+
+# --- barrier: holds until all expected tasks in the wave are DONE ---
+TMP=$(mktemp -d)
+write_contract "$TMP/contract.json"
+
+# Nothing written yet → wave 1 barrier HOLDS (exit 1), T1+T2 MISSING
+OUT=$($NODE "$AS" barrier "$TMP/contract.json" --wave 1 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "empty wave-1 barrier holds" 1 $RC
+assert_contains "barrier reports HOLD" "$OUT" "BARRIER HOLD"
+
+# One DONE, one RUNNING → still holds
+$NODE "$AS" write T1 DONE --commit aaa --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T2 RUNNING --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" barrier "$TMP/contract.json" --wave 1 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "partial wave-1 barrier holds" 1 $?
+
+# Both DONE → wave 1 barrier PASSES (exit 0)
+$NODE "$AS" write T2 DONE --commit bbb --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" barrier "$TMP/contract.json" --wave 1 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "complete wave-1 barrier passes" 0 $RC
+assert_contains "barrier reports PASS" "$OUT" "BARRIER PASS"
+
+# Wave 2 still has T3 MISSING → holds independently
+$NODE "$AS" barrier "$TMP/contract.json" --wave 2 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "wave-2 barrier still holds (T3 missing)" 1 $?
+
+# Whole-phase barrier (no --wave) holds because T3 not done
+$NODE "$AS" barrier "$TMP/contract.json" --cwd "$TMP" >/dev/null 2>&1
+assert_exit "phase barrier holds while T3 open" 1 $?
+
+# Finish T3 → phase barrier passes
+$NODE "$AS" write T3 DONE --commit ccc --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" barrier "$TMP/contract.json" --cwd "$TMP" >/dev/null 2>&1
+assert_exit "phase barrier passes when all done" 0 $?
+
+# A BLOCKED task holds the barrier (BLOCKED != DONE)
+$NODE "$AS" write T3 BLOCKED --note "missing dep" --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" barrier "$TMP/contract.json" --cwd "$TMP" --json 2>&1)
+RC=$?
+assert_exit "BLOCKED task holds barrier" 1 $RC
+assert_contains "barrier json counts blocked" "$OUT" '"blocked": 1'
+rm -rf "$TMP"
+
+# --- list + clear ---
+TMP=$(mktemp -d)
+$NODE "$AS" write T1 DONE --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T2 RUNNING --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" list --cwd "$TMP" 2>&1)
+assert_contains "list shows T1" "$OUT" "T1"
+assert_contains "list shows T2" "$OUT" "T2"
+$NODE "$AS" clear --cwd "$TMP" >/dev/null 2>&1
+[ ! -d "$TMP/.agent-status" ] && { echo "  ✓ clear removes status dir"; PASS=$((PASS+1)); } || { echo "  ✗ clear left status dir"; FAIL=$((FAIL+1)); }
+rm -rf "$TMP"
+
+# --- buildActive library signal (used by R1's pre-write guard) ---
+TMP=$(mktemp -d)
+ACTIVE=$($NODE -e "const a=require('$AS'); a.writeStatus('$TMP',{task:'T1',status:'RUNNING'}); console.log(a.buildActive('$TMP'))" 2>&1)
+assert_contains "buildActive true while RUNNING" "$ACTIVE" "true"
+IDLE=$($NODE -e "const a=require('$AS'); a.writeStatus('$TMP',{task:'T1',status:'DONE'}); console.log(a.buildActive('$TMP'))" 2>&1)
+assert_contains "buildActive false when none RUNNING" "$IDLE" "false"
+rm -rf "$TMP"
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/analyze-gate.test.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+# analyze-gate.test.sh — bin/analyze-gate.js (cross-artifact scope↔plan gate)
+# Run: bash tests/analyze-gate.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+AG="$BIN_DIR/analyze-gate.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 -q "$needle"; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (missing '$needle' in: $hay)"; FAIL=$((FAIL+1)); fi
+}
+
+# A contract whose tasks cover "checkout" + "stripe webhook" + "email receipt".
+write_good_contract() {
+  cat > "$1" <<'EOF'
+{
+  "version": 1,
+  "phase": 2,
+  "goal": "Customers can pay for an order and receive a receipt",
+  "why": "revenue",
+  "success_criteria": ["Checkout charges the card via Stripe", "Customer receives an email receipt"],
+  "tasks": [
+    { "id": "T1", "title": "Stripe checkout charge", "action": "Implement the checkout endpoint that charges the card through the Stripe webhook handler", "acceptance_criteria": ["Checkout charges card via Stripe successfully"] },
+    { "id": "T2", "title": "Email receipt", "action": "Send an email receipt to the customer after a successful charge", "acceptance_criteria": ["Customer receives an email receipt after payment"] }
+  ]
+}
+EOF
+}
+
+write_scope() {
+  cat > "$1" <<'EOF'
+---
+phase: 2
+---
+# Phase 2 Context: Payments
+
+## Acceptance Criteria (testable)
+- AC1 — Checkout charges the card through Stripe
+- AC2 — Customer receives an email receipt
+- AC3 — Failed payments display a retry banner with a refund option
+
+## DoD closure
+- Security: resolved
+EOF
+}
+
+echo "analyze-gate.test.sh — bin/analyze-gate.js"
+echo ""
+
+# syntax
+$NODE -c "$AG" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- clean: every scope AC covered, every success criterion has a task ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+write_good_contract "$TMP/.planning/phase-2-contract.json"
+# scope with only the two covered ACs
+cat > "$TMP/.planning/phase-2-context.md" <<'EOF'
+## Acceptance Criteria (testable)
+- AC1 — Checkout charges the card through Stripe
+- AC2 — Customer receives an email receipt
+EOF
+$NODE "$AG" 2 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "all covered → ANALYZE PASS (exit 0)" 0 $?
+OUT=$($NODE "$AG" 2 --cwd "$TMP" 2>&1)
+assert_contains "reports PASS" "$OUT" "ANALYZE PASS"
+rm -rf "$TMP"
+
+# --- under-covered scope AC (the retry/refund banner is in scope, not in plan) ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+write_good_contract "$TMP/.planning/phase-2-contract.json"
+write_scope "$TMP/.planning/phase-2-context.md"
+OUT=$($NODE "$AG" 2 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "uncovered scope AC → findings (exit 1)" 1 $RC
+assert_contains "flags the uncovered AC" "$OUT" "under-covered"
+assert_contains "names the refund/retry requirement" "$OUT" "retry banner"
+# JSON shape carries the finding type
+OUT=$($NODE "$AG" 2 --cwd "$TMP" --json 2>&1)
+assert_contains "json finding type" "$OUT" '"uncovered-scope-ac"'
+assert_contains "json severity HIGH" "$OUT" '"severity": "HIGH"'
+rm -rf "$TMP"
+
+# --- orphan success criterion (no task covers it) ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+cat > "$TMP/.planning/phase-3-contract.json" <<'EOF'
+{
+  "version": 1,
+  "phase": 3,
+  "goal": "g",
+  "why": "w",
+  "success_criteria": ["Dashboard exports analytics to CSV"],
+  "tasks": [
+    { "id": "T1", "title": "Login form", "action": "Build the login form with password reset", "acceptance_criteria": ["User can log in"] }
+  ]
+}
+EOF
+OUT=$($NODE "$AG" 3 --cwd "$TMP" --json 2>&1)
+RC=$?
+assert_exit "orphan success criterion → exit 1" 1 $RC
+assert_contains "flags orphan success criterion" "$OUT" '"uncovered-success-criterion"'
+rm -rf "$TMP"
+
+# --- glossary violation: plan uses a banned alias ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+cat > "$TMP/.planning/phase-1-contract.json" <<'EOF'
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "Manage the AuthUser session lifecycle",
+  "why": "w",
+  "success_criteria": ["Sessions expire after 24h"],
+  "tasks": [
+    { "id": "T1", "title": "Session expiry", "action": "Expire AuthUser sessions after twentyfour hours of inactivity", "acceptance_criteria": ["Sessions expire after the configured window"] }
+  ]
+}
+EOF
+cat > "$TMP/.planning/CONTEXT.md" <<'EOF'
+# Glossary
+## Language
+### Customer
+The paying account holder.
+**Avoid:** AuthUser vs Customer (unless disambiguated)
+EOF
+OUT=$($NODE "$AG" 1 --cwd "$TMP" --json 2>&1)
+RC=$?
+assert_exit "banned glossary alias → exit 1" 1 $RC
+assert_contains "flags glossary violation" "$OUT" '"glossary-violation"'
+assert_contains "names the banned term" "$OUT" "AuthUser"
+rm -rf "$TMP"
+
+# --- no scope file → scope-coverage skipped, not a failure ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+write_good_contract "$TMP/.planning/phase-2-contract.json"
+# no phase-2-context.md, no CONTEXT.md
+OUT=$($NODE "$AG" 2 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "no scope file → exit 0 (skipped)" 0 $RC
+assert_contains "notes the skip" "$OUT" "scope-coverage check skipped"
+rm -rf "$TMP"
+
+# --- missing contract → invocation error (exit 2) ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+$NODE "$AG" 9 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "missing contract → exit 2" 2 $?
+rm -rf "$TMP"
+
+# --- library: coverage() unit behavior ---
+COV=$($NODE -e "const a=require('$AG'); const t=a.tokenize('Checkout charges the card via Stripe'); const set=new Set(t); console.log(a.coverage('Checkout charges card Stripe', set).covered)" 2>&1)
+assert_contains "coverage true when terms overlap" "$COV" "true"
+COV=$($NODE -e "const a=require('$AG'); console.log(a.coverage('Quantum teleportation export pipeline', new Set(['login','password'])).covered)" 2>&1)
+assert_contains "coverage false when disjoint" "$COV" "false"
+
+# --- library: scope AC parser strips the AC label ---
+ACS=$($NODE -e "const a=require('$AG'); console.log(JSON.stringify(a.parseScopeAcceptanceCriteria('## Acceptance Criteria (testable)\n- AC1 — Checkout works\n- AC2 — Receipt sent\n## Next\n- ignored')))" 2>&1)
+assert_contains "parses AC1 without label" "$ACS" "Checkout works"
+assert_contains "stops at next heading" "$ACS" "Receipt sent"
+if echo "$ACS" | grep -q "ignored"; then echo "  ✗ parser leaked past section"; FAIL=$((FAIL+1)); else echo "  ✓ parser stops at next ## heading"; PASS=$((PASS+1)); fi
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/bin.test.sh

@@ -487,15 +487,16 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 14 hooks installed (block-env-edit removed in v3.2.0;
+# 31. All 15 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;
 # 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;
-# usage-capture added in v6.9.1 — UserPromptSubmit telemetry capture)
+# usage-capture added in v6.9.1 — UserPromptSubmit telemetry capture;
+# task-write-guard added in v6.13 — R1 runtime plan-contract file-scope guard)
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 14 ]; then
-  pass "14 hooks installed in hooks/ (incl. usage-capture v6.9.1)"
+if [ "$HOOK_COUNT" -eq 15 ]; then
+  pass "15 hooks installed in hooks/ (incl. task-write-guard v6.13)"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi