@chrono-meta/fh-gate 1.4.86 → 1.4.87

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."