qualia-framework 6.14.0 → 6.22.0

package/skills/qualia-ship/SKILL.md

@@ -121,17 +121,37 @@ if [ $SEC_FAIL -ne 0 ]; then
 fi
 ```
 
-### 3. Git
+### 3. Integrate to main (ship IS the merge point)
+
+Ship is the one place feature work lands on `main`, so `main` is always exactly what's in production and no branch lingers. Commit, then fast-forward-integrate into `main` and push. `branch-guard` records the main push (accountability, not a block — see `rules/infrastructure.md`).
 
 ```bash
 git add {specific changed files}
 git commit -m "ship: {project name} production deploy"
-git push
+
+BR=$(git branch --show-current)
+if [ "$BR" != "main" ] && [ "$BR" != "master" ]; then
+  git checkout main
+  git pull --ff-only origin main 2>/dev/null || true   # sync with remote first
+  if git merge --ff-only "$BR"; then
+    : # clean fast-forward
+  else
+    # main moved since the branch started — rebase the feature, then ff.
+    git checkout "$BR" && git rebase main || {
+      node ${QUALIA_BIN}/qualia-ui.js fail "Rebase conflict integrating $BR → main. Resolve, then re-run /qualia-ship."
+      exit 1
+    }
+    git checkout main && git merge --ff-only "$BR"
+  fi
+fi
+git push origin HEAD
 ```
 
-Employee stays on feature branch. Never push to main.
+If anything in this block fails (conflict, push rejected), STOP and surface it — do not deploy a half-integrated tree.
+
+### 4. Deploy (from main)
 
-### 4. Deploy
+Deploy runs on `main` HEAD — what you just integrated — so the deployed artifact and `main` are byte-identical.
 
 ```bash
 vercel --prod              # Website/AI agent
@@ -141,6 +161,16 @@ supabase functions deploy  # Edge functions
 wrangler deploy            # Cloudflare Workers
 ```
 
+### 4b. Close the branch
+
+On a verified successful deploy, delete the integrated feature branch so nothing lingers (skip if you shipped directly from `main`):
+
+```bash
+if [ -n "$BR" ] && [ "$BR" != "main" ] && [ "$BR" != "master" ]; then
+  git branch -d "$BR" 2>/dev/null && git push origin --delete "$BR" 2>/dev/null || true
+fi
+```
+
 ### 5. Post-Deploy Verification
 
 Read the deployed URL from `tracking.json.deployed_url` or from an explicit user-provided URL. Do NOT use a `{domain}` placeholder — that expects the LLM to hallucinate the URL, which is exactly the kind of silent fail the state guard above prevents.

package/skills/qualia-update/SKILL.md

@@ -54,6 +54,10 @@ 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.
 
+### 2b. Set the work-unit goal
+
+Per `rules/codex-goal.md` — set the work-unit goal with scope `feature` (Codex `/goal`; on Claude Code, a tracked task + budget). An update runs its own lean loop without `/qualia-plan`, so set the objective + budget here so the change stays one coherent, bounded unit.
+
 ### 3. Run the lean loop
 
 Reuse the real lifecycle skills, scoped to this one change:

package/skills/qualia-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-verify
-description: "Goal-backward verification of a built phase — fresh verifier agent greps code against acceptance criteria, scores design rubric, optional adversarial second pass. Triggers: 'verify this phase', 'check if it works', 'run verification', 'did the build pass'."
+description: "Goal-backward verification of a built phase — a parallel verifier PANEL (one lens each) greps code against acceptance criteria, per-finding adversarial skeptics vote majority-survives, and verify-panel.js aggregates a deterministic verdict. Triggers: 'verify this phase', 'check if it works', 'run verification', 'did the build pass'."
 allowed-tools:
   - Bash
   - Read
@@ -19,7 +19,7 @@ Spawn verifier to check phase goal. Does NOT trust build summaries; greps codeba
 `/qualia-verify` — verify current built phase
 `/qualia-verify {N}` — verify specific phase
 `/qualia-verify {N} --auto` — verify + auto-chain: PASS → next phase/milestone; FAIL → gap closure; gap limit → halt
-`/qualia-verify {N} --adversarial` — second verifier in fresh context with adversarial prompt. Union findings. Recommended for high-stakes phases (Handoff, payment/auth/migration).
+`/qualia-verify {N} --adversarial` — deepen the panel: 5 skeptics per finding instead of 3. Recommended for high-stakes phases (Handoff, payment/auth/migration).
 
 ## Process
 
@@ -44,25 +44,39 @@ node ${QUALIA_BIN}/contract-runner.js .planning/phase-{N}-contract.json
 
 If it fails, the phase cannot PASS. Still spawn the verifier to explain the failure and identify the smallest gap-closure tasks. If it passes, pass the evidence file into the verifier prompt.
 
-### 3. Spawn Verifier (Fresh Context)
+### 3. Spawn Verifier Panel (parallel lenses, fresh context each)
+
+A single LLM judge is adversarially fragile (a lone stray token flips ~35% of verdicts). Replace single-pass review with a **panel**: one verifier per *relevant* lens, spawned in parallel (separate `Agent()` calls in the SAME turn), each scoped to one concern and anchored on the SAME machine evidence (contract-run + harness-eval) as shared ground truth.
 
 ```bash
 node ${QUALIA_BIN}/qualia-ui.js banner verify {N} "{phase name}"
-node ${QUALIA_BIN}/qualia-ui.js spawn verifier "Goal-backward check..."
 ```
 
+Pick lenses by what the phase touches (scale cost to risk — don't run all four on a one-file change):
+- **correctness** — always.
+- **security** — if the plan touches `auth|payment|rls|service_role|migration|secret|upload`.
+- **performance** — if it touches data fetching, network-in-loop, large lists, or `--perf` is set.
+- **design** — if it touches `.tsx/.jsx/.css/.scss` or `app/|components/|pages/`.
+
+For each chosen lens `L`, spawn (all in one turn, then wait for all):
+
 ```
 Agent(prompt="
 Role: @${QUALIA_AGENTS}/verifier.md
 
+LENS: {L}. Review ONLY through the {L} lens — concerns owned by other lenses have their own reviewer; do not duplicate them.
+
 Project: @.planning/PROJECT.md
 Plan + AC + validation: @.planning/phase-{N}-plan.md
 Machine contract: @.planning/phase-{N}-contract.json
-Contract evidence: @.planning/evidence/phase-{N}-contract-run.json
+Contract evidence (shared ground truth — do not re-derive): @.planning/evidence/phase-{N}-contract-run.json
 {Re-verify → previous gaps: @.planning/phase-{N}-verification.md}
 
-Verify phase. Every finding needs file:line evidence. Severity Rubric for all labels. Output: .planning/phase-{N}-verification.md
-", subagent_type="qualia-verifier", description="Verify phase {N}")
+Verify the {L} concerns of this phase. Every finding needs file:line evidence and a Severity Rubric label.
+Write your findings as a JSON array to .planning/phase-{N}-panel-{L}.json:
+  [{\"file\":\"path\",\"line\":N,\"severity\":\"CRITICAL|HIGH|MEDIUM|LOW\",\"title\":\"one-line claim\"}]
+Empty array [] if the {L} lens is clean. Also append a human '## {L} lens' section to .planning/phase-{N}-verification.md.
+", subagent_type="qualia-verifier", description="Verify phase {N} — {L} lens")
 ```
 
 ### 3b. Browser QA (if phase touched frontend)
@@ -89,34 +103,41 @@ Drive dev server, test routes phase touched. Append '## Browser QA' to verificat
 
 Wait for both verifier + QA before step 3. Playwright MCP unavailable → QA returns BLOCKED (note, not phase failure).
 
-### 3c. Adversarial Second Opinion (--adversarial flag, optional)
+### 3c. Skeptic Pass + Deterministic Aggregation
 
-`--adversarial` in args, OR milestone is `Handoff`, OR plan touches `auth|payment|migration|rls|service_role` → spawn SECOND verifier in fresh context. Mitigates self-grading bias (~70% fewer findings without adversarial pass).
+The panel FINDS; skeptics decide what's REAL; `verify-panel.js` decides the verdict — math, not a vibe.
+
+**1. Assemble** the per-lens finding files into one panel skeleton (votes zeroed):
 
 ```bash
-node ${QUALIA_BIN}/qualia-ui.js spawn verifier "Adversarial pass — find what's wrong"
+node ${QUALIA_BIN}/verify-panel.js assemble {N}   # → .planning/phase-{N}-panel.json
 ```
 
+**2. Skeptic vote** on each CRITICAL/HIGH finding (MEDIUM/LOW auto-survive — they don't flip the C/H verdict; skipping skeptics on them is the documented cost bound, not a silent cap). For each such finding spawn **3 skeptics** (5 if `--adversarial`, Handoff milestone, or the finding's lens is `security`), each in fresh context, each prompted to REFUTE:
+
 ```
 Agent(prompt="
 Role: @${QUALIA_AGENTS}/verifier.md
 
-ADVERSARIAL reviewer. Find what's WRONG. Assume cooperative verifier missed something. Same Severity Rubric + evidence-citation req. Bias toward edge cases:
-  - Untested error paths?
-  - Crash-inducing input?
-  - Unhandled concurrent access?
-  - Downstream breaks if contract changes?
-  - Security assumption (auth, RLS, secrets) implicit not enforced?
+SKEPTIC. A panel verifier claims this finding. Try to REFUTE it: is it actually reachable on a real path, or already handled elsewhere, or a false positive? Default to refuted ONLY with evidence — uncertainty is NOT refutation.
 
-Project: @.planning/PROJECT.md
-Plan: @.planning/phase-{N}-plan.md
-Cooperative report (find what they MISSED): @.planning/phase-{N}-verification.md
+Finding: {severity} — {title}
+Location: {file}:{line}
+Evidence to re-check yourself: @{file}
+
+Return exactly one line: REAL — {file:line reason}   OR   NOT_REAL — {file:line reason}
+", subagent_type="qualia-verifier", description="Skeptic {i}/3 — {title}")
+```
 
-Append '## Adversarial Findings' to verification file. Empty section fine if nothing found.
-", subagent_type="qualia-verifier", description="Adversarial verify phase {N}")
+Tally each finding's votes into `.planning/phase-{N}-panel.json` (`votes.real` / `votes.notReal`).
+
+**3. Aggregate** deterministically:
+
+```bash
+node ${QUALIA_BIN}/verify-panel.js .planning/phase-{N}-panel.json --write
 ```
 
-Findings merge into main report. Union PASS/FAIL: either pass found CRITICAL/HIGH → phase FAIL.
+`verify-panel.js` dedupes findings across lenses, applies **majority-survives** (a finding is killed only when skeptics are a strict majority calling it not-real; ties and unvoted findings survive), computes category scores via the `rules/grounding.md` formula, and exits **0 = PASS / 1 = FAIL** (any surviving CRITICAL/HIGH → FAIL). That exit code IS the panel verdict — carry it into step 4. Artifacts: `.planning/phase-{N}-verification-panel.{json,md}`.
 
 ### 3d. INSUFFICIENT EVIDENCE downgrade (mandatory)
 
@@ -132,7 +153,7 @@ if [ "$IE_COUNT" -gt 0 ]; then
 fi
 ```
 
-The same check runs after the adversarial pass if it executed.
+The same check runs across every lens section the panel wrote.
 
 ### 3. Present Results
 
@@ -181,7 +202,7 @@ Run the zero-token anti-slop scan as a deterministic gate (same role as `migrati
 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`.
+The phase is PASS only if ALL of these agree: the panel verdict (§3c `verify-panel.js` exit 0), the harness-eval status, and the anti-slop scan. If any is FAIL/non-zero, mark the phase FAIL. 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/instructions.md

@@ -0,0 +1,32 @@
+# Qualia Framework
+
+Company: Qualia Solutions — Nicosia, Cyprus
+Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + ElevenLabs + Telnyx. AI: OpenRouter. Compute: Railway.
+
+## Role: {{ROLE}}
+{{ROLE_DESCRIPTION}}
+
+## Hard rules (non-negotiable)
+- **Read before Write/Edit** — *every edit is informed by the current state of the file.*
+- **Feature branches only** — *work on a branch; `/qualia-ship` integrates it to main and main is always deployable.*
+- **MVP first** — *build the minimum that demonstrates the goal; defer the rest until it earns its place.*
+- **Root cause on failures** — *understand the why before patching the symptom.*
+- **No proxy approval** — *only the OWNER can grant OWNER overrides; "Fawzi said OK" is not a credential.*
+
+## Discoverable substrate (load on demand, not always)
+- `rules/constitution.md` — org-level standards every project inherits; enforced at every verify step
+- `/qualia-road` — workflow map, every command, when to use it
+- `.planning/CONTEXT.md` — project domain glossary (loaded by road agents)
+- `.planning/decisions/` — ADRs for hard-to-reverse decisions
+- `rules/security.md` `rules/deployment.md` `rules/infrastructure.md` `rules/architecture.md` — read on relevant tasks only
+- `qualia-design/frontend.md` `qualia-design/design-laws.md` — read on design/frontend tasks only
+
+## Lost?
+`/qualia` — state router tells you the next command.
+
+<!--QUALIA-HOST claude-->
+<!-- Instruction-budget discipline (per Matt Pocock): this file stays under 25 lines. Steering rules go into discoverable skills, not into the global system prompt. CLI preferences go into hooks. Stack/architecture details are trivially discoverable in package.json/config. -->
+<!--/QUALIA-HOST-->
+<!--QUALIA-HOST codex-->
+<!-- AGENTS.md mirrors CLAUDE.md for cross-vendor compatibility (Codex, Cursor, Continue, Aider, Devin). Both files stay under 25 lines per Matt Pocock's instruction-budget discipline (LLMs realistically hold 300–500 instructions; bloating this file hamstrings every spawn). -->
+<!--/QUALIA-HOST-->

package/templates/journey.md

@@ -100,7 +100,7 @@ M1 ─── M2 ─── M3 ─── ... ─── M{N} (Handoff)
 
 ## Rules for This Journey
 
-1. **Hard ceiling: 5 milestones.** If the project needs more, defer to a v2 release after handoff.
+1. **No milestone ceiling — the arc spans the whole agreed scope.** Plan as many milestones as the capability inventory (discovery §9) needs to reach the §10 done-state. Do NOT compress real work to hit a number, and do NOT defer agreed work to a "v2" — the only deferrals are what the client explicitly marked Out of Scope (discovery §8). An arc that stops short of the agreed scope is the root cause of teams improvising off-plan later.
 2. **Hard floor: 2 milestones.** Anything smaller should use `/qualia-new --quick` instead.
 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.

package/templates/project-discovery.md

@@ -6,9 +6,9 @@ discovery_mode: project
 
 # Project Discovery, {Project Name}
 
-The non-technical kickoff interview output. `/qualia-scope` writes this in PROJECT MODE before `/qualia-new` generates JOURNEY.md. Captures intent, audience, brand, and constraints in the user's own words.
+The non-technical kickoff interview output. `/qualia-scope` writes this in PROJECT MODE before `/qualia-new` generates JOURNEY.md. Captures intent, audience, brand, constraints — and, for full projects, the **complete capability set that defines the project as DONE** so the roadmap can span the whole arc, not a v1 slice.
 
-Demo path: 8 questions. Full-project path: 14 questions.
+Demo path: §1–§8 (8 questions). Full-project path: §1–§15 (adds the completeness pass + delivery questions).
 
 ## 1. The one-line pitch
 
@@ -36,48 +36,55 @@ Demo path: 8 questions. Full-project path: 14 questions.
 
 ## 7. Hard constraints
 
-> {Anything that is non-negotiable: stack, deadline, compliance, integrations, budget.}
+> {Anything non-negotiable: stack, deadline, compliance, integrations, budget.}
 
-## 8. Out of scope
+## 8. Out of scope (explicitly deferred)
 
-> {What is intentionally NOT in this project, even if it would be obvious to add.}
+> {What is intentionally NOT in this project — work the client has consciously deferred, even if obvious to add. This is the ONLY place work leaves the arc; anything not listed here is in-scope and must land in a milestone.}
 
 ---
 
-The remaining six questions only run for `project_type: full`. Demo mode stops here.
+The remaining questions only run for `project_type: full`. Demo mode stops here.
 
-## 9. Milestone arc, in the client's words
+## 9. Capability inventory — the WHOLE project
 
-> {After the demo, what's the next chapter? After that, what's the chapter after? Stop at three to five chapters total. The last chapter is always Handoff.}
+> {List EVERY capability this project must have to be considered finished — not a v1 slice, the whole thing. One bullet per capability, plain language. Push for completeness: "what else does it need before you'd call it done?" Keep asking until the client says "that's everything." This list becomes the REQ-IDs and milestones — anything missing here is what the team is later forced to improvise, so it is the most important answer in the interview.}
 
-## 10. Compliance and legal
+## 10. Definition of done — for the entire project
+
+> {Describe the end state where there is no more agreed work. What is true when the project is finished and the team stops? This anchors the final milestone (Handoff for client projects) and tells the roadmapper how far the arc must reach.}
+
+## 11. Shipping order
+
+> {Roughly what order should the capabilities in §9 ship in? Group them into chapters if natural. We shape milestones from this — as many as the scope needs, no artificial cap. For client projects the last chapter is Handoff; for an internal or ongoing product it may have no Handoff.}
+
+## 12. Compliance and legal
 
 > {Anything regulated: payments, medical, legal, finance, accessibility commitments, data residency.}
 
-## 11. Integrations
+## 13. Integrations
 
 > {Third-party systems this must talk to, in priority order.}
 
-## 12. Content and copy
+## 14. Content and copy
 
 > {Who writes the copy and where does it live, today and after handoff?}
 
-## 13. Team and roles after handoff
+## 15. Ownership, team, and delivery shape
 
-> {Who maintains this after we ship? What can they do, what can't they do?}
-
-## 14. Budget and timeline shape
-
-> {Fixed deadline, fixed scope, or fixed budget? Pick one — the other two flex.}
+> {Who maintains this after we ship — what can they do, what can't they? And: fixed deadline, fixed scope, or fixed budget? Pick one — the other two flex.}
 
 ---
 
 ## How this feeds `/qualia-new`
 
-- §1-§5 seed PROJECT.md (one-line pitch, what we're building) and PRODUCT.md (users, register, voice, anti-references).
+- §1–§5 seed PROJECT.md (one-line pitch, what we're building) and PRODUCT.md (users, register, voice, anti-references).
 - §6 becomes the first row of the success-criteria table in ROADMAP.md.
-- §7-§8 populate PROJECT.md's "Out of Scope" and the constraints section.
-- §9 (full only) seeds JOURNEY.md milestone names + "why now" lines.
-- §10-§14 (full only) feed research scoping and the Handoff milestone checklist.
-
-Demo projects skip §9-§14 because they ARE one milestone — the journey is just that milestone plus an implicit "client signs, we extend" branch handled by `/qualia-milestone`.
+- §7 populates PROJECT.md's constraints section.
+- §8 populates PROJECT.md's "Out of Scope" — the explicit, client-agreed deferrals (the roadmapper must NOT defer anything else here).
+- **§9 (full only) is the capability inventory → every item becomes a REQ-ID in REQUIREMENTS.md, assigned to exactly one milestone. The roadmapper must cover ALL of §9 across the arc — no overflow into an unplanned "v2".**
+- **§10 (full only) defines the arc's endpoint → the roadmapper builds milestones until the whole capability set reaches this done-state.**
+- §11 (full only) seeds JOURNEY.md milestone order + "why now" lines (no milestone cap — the arc is as long as §9 requires).
+- §12–§15 (full only) feed research scoping, integrations, and the Handoff milestone checklist.
+
+Demo projects skip §9–§15 because they ARE one milestone — the journey is just that milestone plus an implicit "client signs, we extend" branch handled by `/qualia-milestone`.

package/templates/requirements.md

@@ -75,17 +75,17 @@ Fixed scope for every project. Do not reassign these elsewhere.
 
 ## Post-Handoff (v2)
 
-Features acknowledged but deferred past initial handoff. Not in current journey.
+**Only** capabilities the client EXPLICITLY deferred in discovery §8 (Out of Scope) belong here. This is NOT an overflow bucket for a milestone cap — there is no cap; everything in the capability inventory (discovery §9) must be a REQ-ID mapped to a milestone above. If a capability is agreed but absent from the arc, that's a roadmap bug, not a v2 item.
 
 ### {Category}
 
-- **{CAT}-XX**: {capability}
+- **{CAT}-XX**: {capability} — deferred by client (discovery §8)
 
 ---
 
 ## Out of Scope
 
-Explicit exclusions with reasoning. Prevents scope creep.
+Explicit exclusions with reasoning, drawn from discovery §8. Prevents scope creep.
 
 | Feature | Reason |
 |---------|--------|
@@ -95,16 +95,16 @@ Explicit exclusions with reasoning. Prevents scope creep.
 
 ## Traceability
 
-Populated during roadmap creation. Every v1 requirement maps to exactly one milestone + phase.
+Populated during roadmap creation. Every capability from discovery §9 maps to exactly one milestone + phase. Coverage of the full inventory — not a v1 slice — is the gate.
 
 | Requirement | Milestone | Phase | Status |
 |-------------|-----------|-------|--------|
 | {CAT}-01 | M1: {name} | Phase {N} | Pending |
 
-**Coverage:**
-- v1 requirements (all feature milestones + Handoff): {X} total
+**Coverage (must be 100% of the §9 capability inventory):**
+- Agreed capabilities (discovery §9, whole project): {X} total
 - Mapped to milestones + phases: {Y}
-- Unmapped: {Z}
+- Unmapped: {Z}  ← MUST be 0 before the journey-approval gate passes
 
 ---
 

package/tests/agent-status.test.sh

@@ -114,6 +114,21 @@ assert_exit "BLOCKED task holds barrier" 1 $RC
 assert_contains "barrier json counts blocked" "$OUT" '"blocked": 1'
 rm -rf "$TMP"
 
+# --- barrier --tasks (explicit batch gate, no contract needed; R16 wave-plan) ---
+TMP=$(mktemp -d)
+$NODE "$AS" write T1 DONE --commit a --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T2 RUNNING --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T5 DONE --commit b --cwd "$TMP" >/dev/null 2>&1
+# batch {T1,T5} both DONE → pass, with no contract file present
+$NODE "$AS" barrier --tasks T1,T5 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "barrier --tasks all DONE → pass (no contract)" 0 $?
+# batch {T1,T2} → T2 RUNNING → hold
+$NODE "$AS" barrier --tasks T1,T2 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "barrier --tasks with a RUNNING member → hold" 1 $?
+OUT=$($NODE "$AS" barrier --tasks T1,T2 --cwd "$TMP" 2>&1)
+assert_contains "barrier --tasks scope label" "$OUT" "batch T1,T2"
+rm -rf "$TMP"
+
 # --- list + clear ---
 TMP=$(mktemp -d)
 $NODE "$AS" write T1 DONE --cwd "$TMP" >/dev/null 2>&1

package/tests/branch-hygiene.test.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# branch-hygiene.test.sh — bin/branch-hygiene.js (clock-out stranded-branch sweep)
+# Run: bash tests/branch-hygiene.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+BH="$BIN_DIR/branch-hygiene.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
+}
+
+# fresh repo on main with one commit; prints the dir (caller rm -rf)
+setup_repo() {
+  local tmp
+  tmp=$(mktemp -d)
+  (cd "$tmp" \
+    && git init -q \
+    && git checkout -q -b main 2>/dev/null \
+    && git config user.email t@t.com && git config user.name T \
+    && echo seed > seed.txt && git add seed.txt && git commit -q -m seed)
+  echo "$tmp"
+}
+
+echo "branch-hygiene.test.sh — bin/branch-hygiene.js"
+echo ""
+
+$NODE -c "$BH" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- not a git repo → exit 2 ---
+TMP=$(mktemp -d)
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "not a git repo → exit 2" 2 $?
+rm -rf "$TMP"
+
+# --- clean: only main → exit 0 ---
+TMP=$(setup_repo)
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "clean repo (main only) → exit 0" 0 $?
+OUT=$(cd "$TMP" && $NODE "$BH" 2>&1)
+assert_contains "reports clean" "$OUT" "clean"
+rm -rf "$TMP"
+
+# --- stranded feature branch ahead of main → exit 1, listed ---
+TMP=$(setup_repo)
+(cd "$TMP" && git checkout -q -b feat/stranded && echo work > w.txt && git add w.txt && git commit -q -m "wip work")
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "branch ahead of main → exit 1" 1 $?
+OUT=$(cd "$TMP" && $NODE "$BH" 2>&1)
+assert_contains "lists the stranded branch" "$OUT" "feat/stranded"
+assert_contains "shows commits ahead" "$OUT" "+1 commit"
+# json shape
+OUT=$(cd "$TMP" && $NODE "$BH" --json 2>&1)
+assert_contains "json stranded entry" "$OUT" '"branch": "feat/stranded"'
+assert_contains "json ahead count" "$OUT" '"ahead": 1'
+rm -rf "$TMP"
+
+# --- once integrated (ff-merged) into main → no longer stranded → exit 0 ---
+TMP=$(setup_repo)
+(cd "$TMP" && git checkout -q -b feat/done && echo x > x.txt && git add x.txt && git commit -q -m "done work")
+(cd "$TMP" && git checkout -q main && git merge -q --ff-only feat/done)
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "ff-merged branch no longer stranded → exit 0" 0 $?
+rm -rf "$TMP"
+
+# --- master as the base branch is detected ---
+TMP=$(mktemp -d)
+(cd "$TMP" && git init -q && git checkout -q -b master 2>/dev/null && git config user.email t@t.com && git config user.name T && echo s > s.txt && git add s.txt && git commit -q -m s)
+(cd "$TMP" && git checkout -q -b feature && echo y > y.txt && git add y.txt && git commit -q -m y)
+OUT=$(cd "$TMP" && $NODE "$BH" --json 2>&1)
+assert_contains "detects master as base" "$OUT" '"base": "master"'
+assert_contains "stranded vs master" "$OUT" '"branch": "feature"'
+rm -rf "$TMP"
+
+# --- library: analyze() returns structured result ---
+TMP=$(setup_repo)
+(cd "$TMP" && git checkout -q -b b1 && echo a>a && git add a && git commit -q -m a)
+RES=$($NODE -e "console.log(JSON.stringify(require('$BH').analyze('$TMP').stranded.length))" 2>&1)
+assert_contains "analyze() finds 1 stranded" "$RES" "1"
+rm -rf "$TMP"
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1