@chrono-meta/fh-gate 1.4.86 → 1.4.88

package/scripts/test_session_close_chain_lanes.sh

@@ -0,0 +1,349 @@
+#!/usr/bin/env bash
+# test_session_close_chain_lanes.sh — known-pair anchors for the close-chain steps that had NO
+# mechanical lane: ① (status snapshot) · ①-b (open-PR sweep) · ④-log (real-time completion log, the
+# only exit-1 FAIL path besides ⑤) · ④-b (npm freshness + BIDIRECTIONAL entry-point drift) ·
+# and the pre-push SURFACE MATCHING (ordinary push advises · FH_SESSION_CLOSE=1 push blocks).
+#
+# Already anchored elsewhere, deliberately NOT duplicated here:
+#   ②, ⑤ card-last          → scripts/test_session_close_lanes.sh
+#   ⑤-b card-drift probe    → scripts/test_card_drift_probe.sh (incl. the locale-divergence leg)
+#   pre-push stdin/ordering → scripts/test_prepush_stdin_integrity.sh
+#
+# CALIBRATION RULE OBSERVED THROUGHOUT: every lane that asserts an ABSENCE is paired with a
+# known-POSITIVE built from the SAME fixture family, so "passed because the guard worked" is
+# distinguishable from "passed because nothing ran". Exit codes are read DIRECTLY off the
+# subject (never through a pipe — `cmd | tail; echo $?` reads tail's status and has produced
+# false green in this repo four times).
+#
+# ⓘ GAP lanes: places where the subject's CURRENT behaviour is believed WRONG (fail-open, or a
+# spec/code disagreement). They pin the observed behaviour but never fail the suite; if the
+# behaviour changes they announce "GAP CLOSED" so the lane gets promoted instead of silently
+# rotting. They are counted and printed separately — a green summary here does NOT mean the
+# chain is fully guarded.
+#
+# Exit 0 = every asserting lane calibrated · exit 1 = the gate's instrument is wrong.
+
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CHECK="$SCRIPT_DIR/session_close_check.sh"
+HOOK="$ROOT/templates/.git-hooks/pre-push"
+TODAY=$(date +%Y-%m-%d)
+FAILED=0
+PASSED=0
+GAPS=0
+
+[ -f "$CHECK" ] || { echo "FAIL  subject missing: $CHECK"; exit 1; }
+[ -f "$HOOK" ]  || { echo "FAIL  subject missing: $HOOK";  exit 1; }
+
+TMPROOT=$(mktemp -d "${TMPDIR:-/tmp}/fh_close_lanes.XXXXXX")
+trap 'rm -rf "$TMPROOT"' EXIT
+
+_pass() { echo "✅ $1"; PASSED=$((PASSED+1)); }
+_fail() { echo "❌ $1"; FAILED=1; }
+
+# assert a line IS / IS NOT present in captured output
+_line() {  # $1=name $2=pattern $3=expect(0/1) $4=output
+  local hit=0
+  printf '%s\n' "$4" | grep -q -- "$2" && hit=1
+  if [ "$hit" = "$3" ]; then _pass "$1 (hit=$hit, expected=$3)"
+  else _fail "$1 — hit=$hit, expected=$3"; printf '%s\n' "$4" | sed 's/^/       │ /'; fi
+}
+
+_rc() {  # $1=name $2=actual $3=expected
+  if [ "$2" = "$3" ]; then _pass "$1 (exit=$2, expected=$3)"
+  else _fail "$1 — exit=$2, expected=$3"; fi
+}
+
+# GAP lane: pins believed-wrong behaviour without failing the suite.
+_gap() {  # $1=name $2=observed-condition-result(0/1 as evaluated by caller) $3=note
+  if [ "$2" = "1" ]; then
+    echo "ⓘ GAP (still open) $1"
+    echo "       ↳ $3"
+    GAPS=$((GAPS+1))
+  else
+    echo "🎉 GAP CLOSED — $1 : behaviour changed, promote this lane to an asserting one"
+  fi
+}
+
+# ── fixture builders ─────────────────────────────────────────────────────────────
+_repo() {  # $1=dirname ; makes a git repo with one commit dated $2 (default now)
+  local T="$TMPROOT/$1" when="${2:-}"
+  mkdir -p "$T"
+  (
+    cd "$T" || exit 1
+    git init -q . 2>/dev/null
+    git config user.email anchor@local
+    git config user.name anchor
+    echo seed > unrelated.txt
+    # tracks/ is gitignored in the real repo too — without this the fixture's own card+log show up
+    # as untracked paths and ①'s "clean tree" lane can never be built (self-inflicted dirt).
+    printf 'tracks/\nbin/\n' > .gitignore
+    git add -A
+    if [ -n "$when" ]; then
+      GIT_AUTHOR_DATE="$when" GIT_COMMITTER_DATE="$when" git commit -qm seed
+    else
+      git commit -qm seed
+    fi
+  ) >/dev/null 2>&1
+  mkdir -p "$T/tracks/_meta"
+  printf '%s' "$T"
+}
+
+_card() { printf '# card\n' > "$1/tracks/_meta/reference_next_session_starter.md"; }
+# ④ + ⑤ satisfied: completion log first, card LAST (card-last ordering) — so any exit 1 in the
+# ① / ①-b lanes is attributable to the leg under test, not to ambient ④/⑤ noise.
+_artifacts() { printf -- '- ✅ x\n' > "$1/tracks/_meta/fh_completed_${TODAY}.md"; _card "$1"; }
+
+_run() {  # $1=repo ; sets OUT and RC (RC read directly, no pipe)
+  # HERMETIC: stub `gh` to "no open PRs" for every lane that is not specifically testing ①-b.
+  # Without this the ambient environment leaked in — the ①-P lane passed only while this operator
+  # happened to have zero open PRs, and went red the moment a PR was opened mid-session. A lane
+  # that depends on the day's PR count is measuring the environment, not the code.
+  mkdir -p "$1/bin"
+  { printf '#!/usr/bin/env bash\necho "[]"\nexit 0\n'; } > "$1/bin/gh"
+  chmod +x "$1/bin/gh"
+  OUT=$(PATH="$1/bin:$PATH" bash "$CHECK" "$1" 2>/dev/null); RC=$?
+}
+
+echo "══ ① status snapshot ══"
+T=$(_repo one_clean); _artifacts "$T"
+_run "$T"
+_line "①-P  clean tree → ✅ clean line"            '✅ ① working tree clean' 1 "$OUT"
+# Pattern must not match `⚠️  ①-b` — a loose `⚠️  ①` conflated two different steps and made
+# this absence assertion answer a question about the OPEN-PR sweep instead of the status snapshot.
+_line "①-P  clean tree → no ⚠️ ① line (paired)"   '⚠️  ① '                  0 "$OUT"
+_rc   "①-P  clean tree → exit 0" "$RC" 0
+
+T=$(_repo one_dirty); _artifacts "$T"; echo scratch > "$T/uncommitted.txt"
+_run "$T"
+_line "①-N  uncommitted path → ⚠️ fires"           'uncommitted path'        1 "$OUT"
+_line "①-N  uncommitted path → clean line absent"  '✅ ① working tree clean' 0 "$OUT"
+_rc   "①-N  uncommitted is ADVISORY, not blocking" "$RC" 0
+
+# unpushed: needs a real upstream, so build a bare remote
+T=$(_repo one_unpushed); _artifacts "$T"
+(
+  cd "$T" || exit 1
+  git init -q --bare "$TMPROOT/one_unpushed.git" 2>/dev/null
+  git remote add origin "$TMPROOT/one_unpushed.git"
+  git push -q -u origin HEAD 2>/dev/null
+  echo more > second.txt && git add -A && git commit -qm second
+) >/dev/null 2>&1
+_run "$T"
+_line "①-N  unpushed commit → ⚠️ fires"            'unpushed commit'         1 "$OUT"
+_line "①-N  unpushed → clean line absent (paired)" '✅ ① working tree clean' 0 "$OUT"
+
+T="$TMPROOT/one_notrepo"; mkdir -p "$T/tracks/_meta"; _artifacts "$T"
+_run "$T"
+_g=0; printf '%s\n' "$OUT" | grep -q '✅ ① working tree clean' && _g=1
+_gap "①  non-repo reports CLEAN" "$_g" \
+  "git is unavailable/not a repo → DIRTY=0, UNPUSHED=0 → the check reports '✅ working tree clean'. \
+An instrument that could not look is not a clean result (not found ≠ 0). Should say UNSCANNED."
+
+echo
+echo "══ ①-b open-PR sweep ══"
+_ghstub() {  # $1=repo $2=stdout $3=exit
+  mkdir -p "$1/bin"
+  { printf '#!/usr/bin/env bash\ncat <<'"'"'GHEOF'"'"'\n%s\nGHEOF\nexit %s\n' "$2" "$3"; } > "$1/bin/gh"
+  chmod +x "$1/bin/gh"
+}
+_run_with_gh() {  # $1=repo
+  OUT=$(PATH="$1/bin:$PATH" bash "$CHECK" "$1" 2>/dev/null); RC=$?
+}
+
+T=$(_repo b_zero); _artifacts "$T"; _ghstub "$T" '[]' 0
+_run_with_gh "$T"
+_line "①-b-C  no open PRs → no ①-b line (over-fire control)" '①-b' 0 "$OUT"
+
+T=$(_repo b_one); _artifacts "$T"; _ghstub "$T" '[{"number":227}]' 0
+_run_with_gh "$T"
+_line "①-b-P1 one open PR → sweep line fires"    '①-b 1 open PR' 1 "$OUT"
+
+# COUNT CONSISTENCY. gh emits compact single-line JSON when piped (measured 2026-08-02:
+# `[{"number":227},{"number":226},{"number":225}]` on ONE line), so a line-counting `grep -c`
+# reports 1 for any non-zero number of PRs. CLAUDE.md ①-b's own origin note pairs this step with
+# count-consistency, so a sweep that says "1 open PR" while three are open is a real defect, not
+# a cosmetic one — the operator classifies what the sweep names.
+T=$(_repo b_three); _artifacts "$T"
+_ghstub "$T" '[{"number":227},{"number":226},{"number":225}]' 0
+_run_with_gh "$T"
+_line "①-b-P3 three open PRs → sweep says 3"     '①-b 3 open PR' 1 "$OUT"
+
+T=$(_repo b_err); _artifacts "$T"; _ghstub "$T" '' 4
+_run_with_gh "$T"
+_g=0; printf '%s\n' "$OUT" | grep -q '①-b' || _g=1
+_gap "①-b gh ERROR is silent (indistinguishable from zero PRs)" "$_g" \
+  "gh present but failing (auth/offline, exit 4) → stderr discarded, count 0, NO line printed. \
+The sweep 'not run' and the sweep 'found nothing' look identical. Advisory surface, so not \
+fail-closed — but it should print 'sweep UNAVAILABLE' rather than nothing."
+
+echo
+echo "══ ④-log real-time completion log (the exit-1 FAIL path) ══"
+# NOTE the label: this is NOT CLAUDE.md's ④ (memory hygiene, deliberately unmechanized — see
+# CLAUDE.md §Session Wrap-up). The block was renamed 2026-08-02 because a green "④" implied memory
+# hygiene had been verified when nothing checked it. These lanes follow the renamed label; if they
+# ever go green against the OLD string again, the grep has stopped matching and the pair below is
+# passing vacuously.
+# The card is present and NEWEST in both ④ lanes on purpose: otherwise an exit 1 could be ⑤'s,
+# and the lane would not discriminate which invariant fired (instrument-discrimination rule).
+T=$(_repo four_missing); _card "$T"          # commit today, fh_completed absent
+_run "$T"
+_line "④-N  commits today + no fh_completed → ❌ fires" "❌ ④-log commits landed today" 1 "$OUT"
+_line "④-N  ⑤ still holds (failure attributable to ④)" '✅ ⑤ card is the newest'    1 "$OUT"
+_rc   "④-N  → exit 1 (BLOCKS a close push)" "$RC" 1
+
+T=$(_repo four_present)
+printf -- '- ✅ something — done\n' > "$T/tracks/_meta/fh_completed_${TODAY}.md"
+_card "$T"                                    # card written LAST → card-last holds
+_run "$T"
+_line "④-P  fh_completed present → no ❌ ④-log" '❌ ④-log'              0 "$OUT"
+_line "④-P  ⑤ ✅ present (known-positive)"    '✅ ⑤ card is the newest' 1 "$OUT"
+_rc   "④-P  → exit 0" "$RC" 0
+
+T=$(_repo four_old "3 days ago"); _card "$T"  # no commits today, no fh_completed
+_run "$T"
+_line "④-C  no commits today → no ④ line at all (over-fire control)" '④-log' 0 "$OUT"
+_rc   "④-C  → exit 0" "$RC" 0
+
+T="$TMPROOT/four_notrepo"; mkdir -p "$T/tracks/_meta"; _card "$T"
+_run "$T"
+_g=0; { printf '%s\n' "$OUT" | grep -q '❌ ④' || true; } ; printf '%s\n' "$OUT" | grep -q '❌ ④' || _g=1
+_gap "④  instrument-down degrades to PASS on a BLOCKING leg" "$_g" \
+  "No git → COMMITS_TODAY=0 → the ④ requirement silently evaporates and the check exits 0. \
+④ is one of only two legs that can block a close push; its trigger failing open means the block \
+is only as reliable as git being readable. Should distinguish 'no commits' from 'could not count'."
+
+echo
+echo "══ ④-b npm freshness + BIDIRECTIONAL entry-point drift ══"
+_tagged() {  # $1=name  $2..=paths to change AFTER the tag
+  local name="$1"; shift
+  local T="$TMPROOT/$name" p
+  mkdir -p "$T"
+  (
+    cd "$T" || exit 1
+    git init -q . 2>/dev/null
+    git config user.email anchor@local && git config user.name anchor
+    echo '{"name":"fx","version":"1.0.0"}' > package.json
+    echo base > CLAUDE.md; echo base > AGENTS.md
+    mkdir -p docs knowledge/shared/harness-core knowledge/shared/learnings
+    echo base > docs/codex-compat.md
+    echo base > knowledge/shared/harness-core/x.md
+    echo base > knowledge/shared/learnings/log.yaml
+    git add -A && git commit -qm base && git tag v1.0.0
+    for p in "$@"; do mkdir -p "$(dirname "$p")"; echo changed >> "$p"; done
+    git add -A && git commit -qm change
+  ) >/dev/null 2>&1
+  mkdir -p "$T/tracks/_meta"
+  printf -- '- ✅ x\n' > "$T/tracks/_meta/fh_completed_${TODAY}.md"
+  _card "$T"
+  printf '%s' "$T"
+}
+SHIP='④-b npm-shipped assets changed'
+DRIFT_CC='drift candidate (CC→Codex)'
+DRIFT_CX='drift candidate (Codex→CC)'
+
+T=$(_tagged bb_cc CLAUDE.md); _run "$T"
+_line "④-b-1 CLAUDE.md changed → republish reminder" "$SHIP"      1 "$OUT"
+_line "④-b-1 → CC→Codex drift fires"                 "$DRIFT_CC"  1 "$OUT"
+_line "④-b-1 → Codex→CC does NOT fire (paired)"      "$DRIFT_CX"  0 "$OUT"
+_rc   "④-b-1 drift is ADVISORY (exit 0)" "$RC" 0
+
+T=$(_tagged bb_cx AGENTS.md); _run "$T"
+_line "④-b-2 AGENTS.md changed → republish reminder" "$SHIP"      1 "$OUT"
+_line "④-b-2 → Codex→CC drift fires (the 07-19 miss)" "$DRIFT_CX" 1 "$OUT"
+_line "④-b-2 → CC→Codex does NOT fire (paired)"      "$DRIFT_CC"  0 "$OUT"
+
+T=$(_tagged bb_cx2 docs/codex-compat.md); _run "$T"
+_line "④-b-3 docs/codex-compat.md → Codex→CC fires" "$DRIFT_CX"   1 "$OUT"
+_line "④-b-3 → CC→Codex does NOT fire (paired)"     "$DRIFT_CC"   0 "$OUT"
+
+T=$(_tagged bb_kn knowledge/shared/harness-core/x.md); _run "$T"
+_line "④-b-4 shipped knowledge/ counts as a CC entry point" "$DRIFT_CC" 1 "$OUT"
+
+T=$(_tagged bb_both CLAUDE.md AGENTS.md); _run "$T"
+_line "④-b-5 both sides changed → republish reminder still"  "$SHIP"     1 "$OUT"
+_line "④-b-5 both sides → CC→Codex silent (over-fire ctrl)"  "$DRIFT_CC" 0 "$OUT"
+_line "④-b-5 both sides → Codex→CC silent (over-fire ctrl)"  "$DRIFT_CX" 0 "$OUT"
+
+T=$(_tagged bb_unshipped knowledge/shared/learnings/log.yaml); _run "$T"
+_line "④-b-6 UNshipped path → no republish reminder" "$SHIP"     0 "$OUT"
+_line "④-b-6 UNshipped path → no drift candidate"    "$DRIFT_CC" 0 "$OUT"
+_line "④-b-6 UNshipped path → ④-b is not silent-broken (control below)" '④-b' 0 "$OUT"
+
+# no-tag fixture: identical CLAUDE.md change, but no version tag exists
+T="$TMPROOT/bb_notag"; mkdir -p "$T"
+(
+  cd "$T" || exit 1
+  git init -q . 2>/dev/null
+  git config user.email anchor@local && git config user.name anchor
+  echo '{"name":"fx","version":"1.0.0"}' > package.json
+  echo base > CLAUDE.md && git add -A && git commit -qm base
+  echo changed >> CLAUDE.md && git add -A && git commit -qm change
+) >/dev/null 2>&1
+mkdir -p "$T/tracks/_meta"; printf -- '- ✅ x\n' > "$T/tracks/_meta/fh_completed_${TODAY}.md"; _card "$T"
+_run "$T"
+_g=0; printf '%s\n' "$OUT" | grep -q '④-b' || _g=1
+_gap "④-b whole step vanishes when no version tag is reachable" "$_g" \
+  "LAST_TAG empty → the republish reminder AND both drift candidates are skipped silently. \
+CLAUDE.md ④-b conditions the drift check on 'npm-shipped assets changed', not on a tag existing; \
+a shallow/tagless clone or a pre-first-release state therefore runs a close with the entry-point \
+drift check simply absent, and nothing says so."
+
+echo
+echo "══ pre-push SURFACE MATCHING (advise vs block) ══"
+# A stubbed session_close_check lets these lanes control _SC_RC exactly, which is the variable
+# under test. The real script's verdict logic is anchored above; what is anchored HERE is that
+# the hook routes verdict → advisory or block by surface, and nothing else.
+_hookfx() {  # $1=name $2=stub exit code  → echoes repo path
+  local T="$TMPROOT/$1"
+  mkdir -p "$T/scripts"
+  (
+    cd "$T" || exit 1
+    git init -q . 2>/dev/null
+    git config user.email anchor@local && git config user.name anchor
+    printf '#!/usr/bin/env bash\necho "❌ ⑤ card-last violated — synthetic"\nexit %s\n' "$2" \
+      > scripts/session_close_check.sh
+    chmod +x scripts/session_close_check.sh
+    git add -A && git commit -qm seed
+  ) >/dev/null 2>&1
+  cp "$HOOK" "$T/pre-push-under-test"
+  printf '%s' "$T"
+}
+_hookrun() {  # $1=repo $2=FH_SESSION_CLOSE value ("" = unset)
+  local T="$1" v="$2" sha
+  sha=$(git -C "$T" rev-parse HEAD)
+  # ordinary NEW-BRANCH push: local_sha real, remote_sha zero → not a delete, not a force,
+  # not the integration branch → the hook must fall through to exit 0 unless a leg blocks.
+  OUT=$(cd "$T" && printf 'refs/heads/feat/x %s refs/heads/feat/x %s\n' "$sha" "0000000000000000000000000000000000000000" \
+        | env ${v:+FH_SESSION_CLOSE=$v} bash ./pre-push-under-test origin https://example.invalid/x.git 2>&1)
+  RC=$?   # command substitution: this is the pipeline's status under pipefail, i.e. the HOOK's
+}
+
+T=$(_hookfx hook_adv 1); _hookrun "$T" ""
+_rc   "PP-1 ordinary push + violation → exit 0 (ADVISORY)" "$RC" 0
+_line "PP-1 → the ❌ line is surfaced, not swallowed"  '❌ ⑤ card-last violated' 1 "$OUT"
+_line "PP-1 → says it is advisory + names the enforcing form" 'FH_SESSION_CLOSE=1' 1 "$OUT"
+
+T=$(_hookfx hook_block 1); _hookrun "$T" 1
+_rc   "PP-2 close push + violation → exit 1 (BLOCKS)" "$RC" 1
+_line "PP-2 → prints the enforcing banner" '⛔ FH Session-Close Check' 1 "$OUT"
+
+T=$(_hookfx hook_ok 0); _hookrun "$T" 1
+_rc   "PP-3 close push + CLEAN → exit 0 (blocks on the VERDICT, not on the flag)" "$RC" 0
+_line "PP-3 → prints the consistent line" '✅ FH Session-Close Check' 1 "$OUT"
+
+T=$(_hookfx hook_ok2 0); _hookrun "$T" ""
+_rc   "PP-4 ordinary push + CLEAN → exit 0" "$RC" 0
+_line "PP-4 → no advisory noise on a healthy push" 'close invariant(s) violated' 0 "$OUT"
+
+echo
+echo "──────────────────────────────────────────────"
+if [ "$FAILED" -ne 0 ]; then
+  echo "CLOSE-CHAIN LANES: FAIL — the close-chain instrument is miscalibrated (do not trust its verdict)"
+  echo "  asserting lanes passed: $PASSED · open gaps: $GAPS"
+  exit 1
+fi
+echo "CLOSE-CHAIN LANES: PASS ($PASSED asserting lanes) · $GAPS KNOWN GAP(S) still open (see ⓘ above)"
+echo "  A green line here covers ① ①-b ④ ④-b and the pre-push advise/block split — NOT the gaps."
+exit 0

package/scripts/test_wizard_snippet_merge_lanes.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# test_wizard_snippet_merge_lanes.sh — lanes for the SessionStart snippet → settings.json merge.
+#
+# SUBJECT: the python block in plugins/fh-meta/skills/install-wizard/SKILL_detail.md
+# §Step4-Baseline-Bash that reads templates/settings.SessionStart.snippet.json and merges its
+# `project_settings_json` entry into the user's .claude/settings.json.
+#
+# The subject is EXTRACTED FROM THE SHIPPED FILE at run time, never retyped. A retyped copy is the
+# divergent-copy class this repo has already paid for: the lane would keep validating the OLD merge
+# while the shipped one drifted, and stay green throughout. Extraction failure is a FAIL, not a skip.
+#
+# WHY THIS MATTERS MORE THAN AN ORDINARY PARSER LANE: the hook being registered here is
+# fh_node_check.sh — the one thing that tells an operator at turn 0 that their machine's floors are
+# missing. If the registration silently does not happen, the detector that would have said so is the
+# detector that did not get installed. That loop has to be broken from outside, and the lanes below
+# measure whether anything does.
+#
+# CALIBRATION: every absence lane names its known-positive and builds it in the same run.
+# ⓘ GAP lanes pin behaviour believed wrong without failing the suite.
+# Exit 0 = calibrated · 1 = the instrument (or the extraction) is wrong.
+
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+WIZ="$ROOT/plugins/fh-meta/skills/install-wizard/SKILL_detail.md"
+DOC="$ROOT/plugins/fh-meta/skills/install-doctor/SKILL.md"
+SNIPPET="$ROOT/templates/settings.SessionStart.snippet.json"
+
+TMPROOT=$(mktemp -d "${TMPDIR:-/tmp}/fh_snippet_lanes.XXXXXX")
+trap 'rm -rf "$TMPROOT"' EXIT
+FAILED=0; PASSED=0; GAPS=0
+_pass() { echo "✅ $1"; PASSED=$((PASSED+1)); }
+_fail() { echo "❌ $1"; FAILED=1; }
+_rc()   { if [ "$2" = "$3" ]; then _pass "$1 (exit=$2, expected=$3)"; else _fail "$1 — exit=$2, expected=$3"; fi; }
+_eq()   { if [ "$2" = "$3" ]; then _pass "$1 ($2)"; else _fail "$1 — got [$2], expected [$3]"; fi; }
+_gap()  { if [ "$2" = "1" ]; then echo "ⓘ GAP (still open) $1"; echo "       ↳ $3"; GAPS=$((GAPS+1));
+          else echo "🎉 GAP CLOSED — $1 : behaviour changed, promote this lane"; fi; }
+
+for f in "$WIZ" "$DOC" "$SNIPPET"; do
+  [ -f "$f" ] || { echo "❌ subject missing: $f"; exit 1; }
+done
+
+echo "══ extraction (the instrument itself) ══"
+MERGE="$TMPROOT/merge.py"
+awk '/^python3 - "\$FH_DIR" <<.PY.$/{f=1;next} f&&/^PY$/{exit} f' "$WIZ" > "$MERGE"
+N=$(wc -l < "$MERGE" | tr -d ' ')
+if [ "$N" -lt 10 ]; then
+  _fail "EX-1 could not extract the merge block from SKILL_detail.md (got $N lines) — NOT a pass"
+  echo "──────────────────────────────────────────────"; echo "SNIPPET MERGE LANES: FAIL (extraction)"; exit 1
+fi
+_pass "EX-1 merge block extracted from the shipped SKILL_detail.md ($N lines)"
+grep -q 'project_settings_json' "$MERGE" && _pass "EX-2 extracted block reads project_settings_json" \
+  || _fail "EX-2 extracted block does not mention project_settings_json — wrong region captured"
+
+DOCPY="$TMPROOT/doctor.py"
+# NOTE the leading-whitespace tolerance: this block is indented inside an `if` in the SKILL, and a
+# ^-anchored pattern extracted 0 lines. That failure surfaced as a red lane rather than a green
+# vacuous one only because EX-3 treats an empty extraction as FAIL — keep it that way.
+awk '/^[[:space:]]*python3 - "\$FH" <<.PY.$/{f=1;next} f&&/^[[:space:]]*PY$/{exit} f' "$DOC" > "$DOCPY"
+DN=$(wc -l < "$DOCPY" | tr -d ' ')
+[ "$DN" -ge 5 ] && _pass "EX-3 install-doctor registration check extracted ($DN lines)" \
+  || _fail "EX-3 could not extract install-doctor's registration check (got $DN lines) — NOT a pass"
+
+# ── fixture ─────────────────────────────────────────────────────────────────────
+_hub() {  # $1=name $2=snippet-content ("@SHIPPED" = the real tracked file) → echoes path
+  local h="$TMPROOT/$1"
+  mkdir -p "$h/templates" "$h/.claude"
+  if [ "$2" = "@SHIPPED" ]; then cp "$SNIPPET" "$h/templates/settings.SessionStart.snippet.json"
+  else printf '%s' "$2" > "$h/templates/settings.SessionStart.snippet.json"; fi
+  printf '%s' "$h"
+}
+_merge() { OUT=$(python3 "$MERGE" "$1" 2>&1); RC=$?; }   # RC read directly off python, no pipe
+_registered() {  # 1 = fh_node_check present in the written settings.json
+  [ -f "$1/.claude/settings.json" ] && grep -q 'fh_node_check' "$1/.claude/settings.json" && echo 1 || echo 0
+}
+_claims_ok() { printf '%s\n' "$OUT" | grep -q 'hook registered' && echo 1 || echo 0; }
+
+echo
+echo "══ the happy path (known-positive for every absence lane below) ══"
+H=$(_hub good @SHIPPED); _merge "$H"
+_rc  "MG-P  shipped snippet → exit 0" "$RC" 0
+_eq  "MG-P  → fh_node_check actually present in settings.json" "$(_registered "$H")" 1
+_eq  "MG-P  → success line printed" "$(_claims_ok)" 1
+
+# the documented merge promise (SKILL_detail.md: 'Merge at HOOK level, not group level') —
+# a foreign hook sharing a group with the FH one must survive.
+H=$(_hub coexist @SHIPPED)
+cat > "$H/.claude/settings.json" <<'J'
+{"hooks":{"SessionStart":[{"matcher":"","hooks":[
+ {"type":"command","command":"bash my_telemetry.sh"},
+ {"type":"command","command":"bash $CLAUDE_PROJECT_DIR/scripts/fh_node_check.sh"}]}]}}
+J
+_merge "$H"
+grep -q 'my_telemetry' "$H/.claude/settings.json" && _pass "MG-P2 foreign hook in the FH group survives the merge" \
+  || _fail "MG-P2 foreign hook was dropped — the documented hook-level merge is not happening"
+_eq  "MG-P2 → and fh_node_check is (re)registered" "$(_registered "$H")" 1
+DUP=$(grep -c 'fh_node_check' "$H/.claude/settings.json")
+_eq  "MG-P2 → old FH entry replaced, not duplicated" "$DUP" 1
+
+echo
+echo "══ malformed snippet: fails loudly, writes nothing ══"
+# These four are the F10 question as posed (malformed / truncated / empty). The merge turns out to
+# be fail-CLOSED here — worth pinning precisely so a future 'robustness' refactor that swallows the
+# exception is caught as the regression it would be.
+SHIPPED_TXT=$(cat "$SNIPPET")
+i=0
+for name in empty notjson truncated missingkey; do
+  i=$((i+1))
+  case "$name" in
+    empty)      body="" ;;
+    notjson)    body="oops not json at all" ;;
+    truncated)  body=$(printf '%s' "$SHIPPED_TXT" | head -c 400) ;;
+    missingkey) body='{"hooks":{"SessionStart":[]}}' ;;
+  esac
+  H=$(_hub "bad_$name" "$body"); _merge "$H"
+  _rc "MG-N$i $name snippet → non-zero exit" "$RC" 1
+  _eq "MG-N$i $name → nothing registered (paired with MG-P)" "$(_registered "$H")" 0
+  _eq "MG-N$i $name → no success line" "$(_claims_ok)" 0
+done
+
+echo
+echo "══ malformed EXISTING settings.json: the user's file is not destroyed ══"
+H=$(_hub badtarget @SHIPPED); printf '{ oops' > "$H/.claude/settings.json"
+_merge "$H"
+_rc  "MG-T  unparsable target → non-zero exit" "$RC" 1
+_eq  "MG-T  → the user's file is left byte-identical" "$(cat "$H/.claude/settings.json")" '{ oops'
+[ -f "$H/.claude/settings.json.prewizard" ] \
+  && _fail "MG-T  → a .prewizard backup of an unread file was written (misleading artifact)" \
+  || _pass "MG-T  → no misleading backup artifact left behind"
+
+echo
+echo "══ ⓘ GAP lanes ══"
+
+# GAP 1 — the ONLY validation is what `kept + entry` incidentally requires: that entry is a list.
+# Any list-shaped value is written to the user's real settings.json and reported as success. The
+# success message is not conditioned on what was actually written.
+BADSCHEMA_HITS=0; BADSCHEMA_TOTAL=0; DETAIL=""
+for name in emptylist nocommand wrongscript juststring; do
+  case "$name" in
+    emptylist)   body='{"project_settings_json":{"hooks":{"SessionStart":[]}}}' ;;
+    nocommand)   body='{"project_settings_json":{"hooks":{"SessionStart":[{"matcher":"","hooks":[{"type":"command"}]}]}}}' ;;
+    wrongscript) body='{"project_settings_json":{"hooks":{"SessionStart":[{"matcher":"","hooks":[{"type":"command","command":"bash /some/other/script.sh"}]}]}}}' ;;
+    juststring)  body='{"project_settings_json":{"hooks":{"SessionStart":["not even an object"]}}}' ;;
+  esac
+  H=$(_hub "schema_$name" "$body"); _merge "$H"
+  BADSCHEMA_TOTAL=$((BADSCHEMA_TOTAL+1))
+  if [ "$RC" = 0 ] && [ "$(_claims_ok)" = 1 ] && [ "$(_registered "$H")" = 0 ]; then
+    BADSCHEMA_HITS=$((BADSCHEMA_HITS+1)); DETAIL="$DETAIL $name"
+  fi
+done
+_g=0; [ "$BADSCHEMA_HITS" -gt 0 ] && _g=1
+_gap "valid-JSON / invalid-SCHEMA snippet → written, reported as success, node hook absent" "$_g" \
+  "$BADSCHEMA_HITS of $BADSCHEMA_TOTAL cases:$DETAIL. exit 0 and 'node-check SessionStart hook \
+registered ->' are printed while fh_node_check is NOT in the file that was just written. The success \
+message is unconditional — it does not re-read what it wrote. One-line fix: after the write, assert \
+fh_node_check appears in the serialized result, else exit non-zero."
+
+# GAP 2 — the corruption from GAP 1 is LATENT: the bad value lands in the user's settings.json and
+# detonates on the NEXT wizard run, in the kept-loop, far from where it was introduced.
+H=$(_hub latent '{"project_settings_json":{"hooks":{"SessionStart":["not even an object"]}}}')
+_merge "$H"; FIRST_RC=$RC
+_merge "$H"; SECOND_RC=$RC
+_g=0; { [ "$FIRST_RC" = 0 ] && [ "$SECOND_RC" != 0 ]; } && _g=1
+_gap "the bad write detonates on the NEXT run, not the run that made it" "$_g" \
+  "run1 exit=$FIRST_RC (reported success), run2 exit=$SECOND_RC (AttributeError in the kept-loop: \
+g.get on a str). The user's settings.json is now un-mergeable and the traceback points at the \
+survivor filter, not at the snippet that caused it."
+
+# GAP 3 — INSTRUMENT COVERAGE, measured not asserted. Build the exact post-failure state (companion
+# hook registered, node hook absent) and run install-doctor's registration check on it. The
+# known-positive is in the same run: the companion line must fire, proving the check executed.
+H="$TMPROOT/doctor_state"; mkdir -p "$H/.claude"
+cat > "$H/.claude/settings.local.json" <<'J'
+{"hooks":{"SessionStart":[{"matcher":"","hooks":[
+ {"type":"command","command":"bash $CLAUDE_PROJECT_DIR/scripts/fh_session_load.sh"}]}]}}
+J
+printf '{}' > "$H/.claude/settings.json"
+DOUT=$(python3 "$DOCPY" "$H" 2>&1); DRC=$?
+if printf '%s\n' "$DOUT" | grep -q 'companion-load SessionStart registered'; then
+  _pass "DR-P  install-doctor's check RAN on this fixture (known-positive: companion line fired, exit=$DRC)"
+else
+  _fail "DR-P  install-doctor's check did not fire at all — the GAP lane below would pass vacuously"
+fi
+_g=0; printf '%s\n' "$DOUT" | grep -qi 'node_check\|node check' || _g=1
+_gap "nothing downstream verifies that fh_node_check is registered" "$_g" \
+  "The node hook is absent from this fixture and install-doctor's registration check says nothing \
+about it — it only greps for fh_session_load. install-doctor's ① checks the git hook FILES, not the \
+SessionStart REGISTRATION of the script that reports on them. So the wizard's unconditional success \
+message (GAP 1) is never contradicted by anything, and the check whose job is announcing an unwired \
+machine can itself be unwired silently."
+
+echo
+echo "──────────────────────────────────────────────"
+if [ "$FAILED" -ne 0 ]; then
+  echo "SNIPPET MERGE LANES: FAIL — instrument miscalibrated (do not trust its verdict)"
+  echo "  asserting lanes passed: $PASSED · open gaps: $GAPS"
+  exit 1
+fi
+echo "SNIPPET MERGE LANES: PASS ($PASSED asserting lanes) · $GAPS KNOWN GAP(S) open (see ⓘ above)"
+echo "  Green covers: happy path, hook-level merge promise, malformed-snippet fail-closed,"
+echo "  unparsable-target preservation. Green does NOT cover the three gaps above."
+exit 0

package/templates/.claude/rules/session.md

@@ -79,7 +79,10 @@ EOF
 
 ### Automatic Response to Issues
 
-<!-- [CUSTOMIZE] Adjust report tool/path to match your project -->
+<!-- [CUSTOMIZE] DOMAIN-SCOPED — delete this whole section if the project has no test-report
+     artifact to analyse. The old wording here said "adjust report tool/path", which assumes the
+     tool exists and reads as a config note rather than a delete instruction; the same measurement
+     that found the two sections below inert found this one inert for the same reason. -->
 
 #### Automatic Check Trigger
 
@@ -98,9 +101,27 @@ When the user mentions a problem, **automatically** locate and analyze the lates
 
 ### Code Writing Principles
 
-<!-- [CUSTOMIZE] Adjust to match your project's coding conventions. The 5 principles below are universal and valid for any project. -->
-
-Be conscious of all 5 principles **before** writing code — directly reduces back-and-forth where Claude rushes to create something and the user has to correct it.
+<!-- [CUSTOMIZE] Adjust to match your project's coding conventions.
+     THREE of the five below are universal (#1 #2 #5). TWO are DOMAIN-SCOPED and belong only to
+     UI/mobile-QA projects (#3 locator stability, #4 flakiness) — DELETE them outright if this
+     project has no UI automation. Do not keep them "just in case": measured 2026-08-03 across
+     THREE repos that inherited this file. One (a bash/python wiki engine) carried both for its
+     entire 11-day life before being pruned; the other two are byte-identical to this template
+     right now and still carry them.
+     If you delete a section, also fix any sentence that counts them — the wiki engine shipped
+     "all 5 principles" over three for an hour before an outside reviewer caught it.
+     What the fix here does and does NOT do, measured as a before/after pair (Sonnet, reps=3).
+     The gain depends on how explicitly the asker names what the project lacks:
+       * question naming no-UI/no-mobile only  -> before: #3 3/3, #4 **1/3**;  after: both 3/3
+       * question also naming no-test-reports  -> before: 8 of 9 cells;        after: 9 of 9
+     So the honest claim is narrow: the old wording is mostly adequate for someone who spells out
+     every absence, and loses a section for someone who does not. Both numbers are recorded because
+     citing only the first would overstate this edit.
+     THE FIELD CAUSE IS STILL OPEN, and it is a different moment: the wiki engine did not prune
+     either section, which means nobody was asked. `light-harness init` copies this file whole,
+     with no pruning step. A marker only works on a reader who has stopped to read it. -->
+
+Be conscious of every principle below **before** writing code — directly reduces back-and-forth where Claude rushes to create something and the user has to correct it.
 
 #### 1. Reference Existing Code (Consistency First)
 
@@ -116,7 +137,7 @@ Be conscious of all 5 principles **before** writing code — directly reduces ba
 
 #### 3. Locator and Identifier Stability (UI code only)
 
-<!-- [CUSTOMIZE] Can be removed for non-mobile QA / non-web QA projects -->
+<!-- [CUSTOMIZE] DOMAIN-SCOPED — delete this whole section for non-UI projects (see the note above #1) -->
 
 - Do not depend on dynamically generated attributes (auto-generated id, timestamps in content-desc)
 - Avoid absolute XPath — fragile to structural changes
@@ -125,6 +146,8 @@ Be conscious of all 5 principles **before** writing code — directly reduces ba
 
 #### 4. Flakiness Risk Management
 
+<!-- [CUSTOMIZE] DOMAIN-SCOPED — delete this whole section for projects without UI automation -->
+
 - **No `time.sleep`** — use explicit waits (implicit/explicit wait) + condition-based polling
 - No unbounded waits without a timeout
 - Allow tolerance in screenshot-based assertions

package/templates/.git-hooks/pre-commit

@@ -706,8 +706,15 @@ run_universal_guards
 # not a reversible-surface concern — it disables the commit gate itself.
 GATE_IMPL=$(echo "$STAGED" \
   | grep -E '(templates/\.git-hooks/pre-commit|templates/regression_guard\.sh|\.claude/rules/fh_4axis_gate\.md|scripts/gate_pathspec_check\.sh)' || true)
-if [ -n "$GATE_IMPL" ]; then
-  echo "[Gate] gate implementation staged — path-coverage known-pair anchor..."
+# CLAUDE.md carries a canonical asset list that gate_pathspec_check §5 verifies, so editing it must
+# RUN the anchor. It is deliberately NOT added to GATE_IMPL: that variable also feeds $LOADBEARING,
+# which demands a cross-family acknowledgment line in the marker. Enrolling every CLAUDE.md prose
+# edit into cross-family review is a different job from path coverage, and over-blocking is how an
+# override becomes muscle memory (CLAUDE.md §Destructive-Op — the same reasoning that keeps the
+# session-close check advisory on ordinary pushes). Separate trigger, same anchor.
+ASSETLIST_IMPL=$(echo "$STAGED" | grep -E '^CLAUDE\.md$' || true)
+if [ -n "$GATE_IMPL" ] || [ -n "$ASSETLIST_IMPL" ]; then
+  echo "[Gate] gate implementation or asset list staged — path-coverage known-pair anchor..."
   PSCHECK="$REPO_ROOT/scripts/gate_pathspec_check.sh"
   if [ ! -f "$PSCHECK" ]; then
     echo "  ❌ FAIL — scripts/gate_pathspec_check.sh missing while a gate file is being changed."