@chrono-meta/fh-gate 1.4.85 → 1.4.87

package/scripts/test_tag_version_lanes.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# test_tag_version_lanes.sh — known-pair anchor for the pre-push tag/version consistency guard.
+#
+# WHY (measured 2026-08-02): a release tag was pushed onto the WRONG commit. `git pull --ff-only`
+# had failed with a diverging-branches error that went unread, so `main` was still the pre-release
+# tree; the tag landed there and `npm publish` was then attempted from that same tree. The ONLY
+# thing that stopped the publish was npm's own "cannot publish over 1.4.84" collision check.
+# Publishing does not un-happen — being saved by the registry's bookkeeping is luck, not a floor.
+#
+# Built at N=1 on purpose. This repo's escalation rule ("1-2 occurrences -> prose, N>=3 -> mechanize")
+# is scoped to REVERSIBLE surfaces; a wrong tag on a public repo plus a publish from the wrong tree
+# is the irreversible class, where the Surface-Class Degrade Invariant says fail-CLOSED immediately.
+#
+# The lanes drive the REAL hook through its real stdin contract (`<local_ref> <local_sha>
+# <remote_ref> <remote_sha>`), not a re-spelling of its predicate — a hand-copied condition is a
+# divergent normalizer and drifts lenient.
+#
+# Exit 0 = the guard discriminates · 1 = it would let a mismatched tag through, or block a good one.
+
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$SCRIPT_DIR/.." && pwd)"
+HOOK="$REPO/templates/.git-hooks/pre-push"
+FAILED=0; PASS=0
+chk() { if [ "$1" -eq 0 ]; then PASS=$((PASS+1)); echo "  ✅ $2"; else FAILED=1; echo "  ❌ $2"; fi; }
+
+[ -f "$HOOK" ] || { echo "FAIL  tag-version lanes: subject $HOOK missing"; exit 1; }
+ZERO=0000000000000000000000000000000000000000
+
+# A throwaway repo so the lanes never depend on this repo's live history.
+T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
+( cd "$T" && git init -q . && git config user.email a@b && git config user.name a
+  printf '{\n  "name": "x",\n  "version": "1.0.0"\n}\n' > package.json
+  git add -A && git commit -qm v100
+  printf '{\n  "name": "x",\n  "version": "1.1.0"\n}\n' > package.json
+  git add -A && git commit -qm v110
+  printf 'no manifest here\n' > README.md && rm -f package.json
+  git add -A && git commit -qm nomanifest ) >/dev/null 2>&1
+
+C_100=$(cd "$T" && git rev-parse HEAD~2)
+C_110=$(cd "$T" && git rev-parse HEAD~1)
+C_NONE=$(cd "$T" && git rev-parse HEAD)
+
+# Drive the hook exactly as git does. Run it INSIDE the scratch repo so its rev-parse/cat-file
+# resolve against that history. Only the tag verdict is under test here, so a non-zero exit from an
+# unrelated guard would be a false red — assert on the MESSAGE, and on rc only for the clean lane.
+run() { # $1=tag  $2=sha   -> prints hook output
+  printf '%s %s %s %s\n' "refs/tags/$1" "$2" "refs/tags/$1" "$ZERO" \
+    | ( cd "$T" && bash "$HOOK" origin 2>&1 )
+}
+says_mismatch() { printf '%s' "$1" | grep -q "TAG/VERSION MISMATCH"; }
+blocks()        { printf '%s' "$1" | grep -q "FH Tag/Version Consistency"; }
+
+echo "── the measured failure, reproduced ──"
+out=$(run v1.1.0 "$C_100")
+says_mismatch "$out" ; chk $? "known-POSITIVE: v1.1.0 on a commit whose package.json says 1.0.0 → MISMATCH"
+blocks "$out"        ; chk $? "…and it BLOCKS (detection wired to a blocker, not just printed)"
+
+echo "── the good case must not be blocked (over-blocking trains the override) ──"
+out=$(run v1.1.0 "$C_110")
+if says_mismatch "$out"; then chk 1 "known-NEGATIVE: matching tag/version is silent"; else chk 0 "known-NEGATIVE: matching tag/version is silent"; fi
+if blocks "$out"; then chk 1 "…and does not block"; else chk 0 "…and does not block"; fi
+
+echo "── scope: not every tag is a release tag ──"
+out=$(run v1.0.0 "$C_NONE")
+if says_mismatch "$out"; then chk 1 "no package.json at that commit → not applicable, not a block"; else chk 0 "no package.json at that commit → not applicable, not a block"; fi
+out=$(run sprint-42 "$C_100")
+if says_mismatch "$out"; then chk 1 "non-version tag name (sprint-42) is out of scope"; else chk 0 "non-version tag name (sprint-42) is out of scope"; fi
+
+echo "── the override channel exists and is explicit ──"
+grep -q 'TAG_VERSION_OK' "$HOOK" ; chk $? "TAG_VERSION_OK override present (mirrors MAIN_PUSH_OK / DESTRUCTIVE_OP_OK)"
+out=$(printf '%s %s %s %s\n' "refs/tags/v1.1.0" "$C_100" "refs/tags/v1.1.0" "$ZERO" \
+      | ( cd "$T" && TAG_VERSION_OK=1 bash "$HOOK" origin 2>&1 ))
+if blocks "$out"; then chk 1 "override actually lets the push through"; else chk 0 "override actually lets the push through"; fi
+
+echo ""
+if [ "$FAILED" -ne 0 ]; then echo "TAG-VERSION LANES: FAIL"; exit 1; fi
+echo "TAG-VERSION LANES: PASS ($PASS/$PASS)"
+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."

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

@@ -54,6 +54,7 @@ DEL_OTHER=""      # refs/tags/* refs/notes/* etc. being deleted
 FORCED_REFS=""
 UNCLASSIFIED=""   # force-check impossible (remote tip not fetched)
 DIRECT_MAIN=""    # non-delete update pushed straight at the integration branch (PR-only policy)
+TAG_MISMATCH=""   # vX.Y.Z tag whose commit's package.json disagrees (irreversible-adjacent)
 SEP=$'\n'   # ranges are newline-separated and evaluated ONE REF AT A TIME: concatenating
             # them into one arg string let `--not` from ref A flip polarity for ref B, so a
             # multi-ref push could return an empty or wrong commit set (R6 audit 2026-07-26).
@@ -184,6 +185,40 @@ while read -r local_ref local_sha remote_ref remote_sha; do
         fi ;;
     esac
   fi
+  # TAG/VERSION CONSISTENCY — a `vX.Y.Z` tag must point at a commit whose package.json says X.Y.Z.
+  # WHY (measured 2026-08-02): a release tag was pushed onto the WRONG commit because `git pull`
+  # had failed with a diverging-branches error that went unread, so `main` was still the pre-release
+  # tree. `npm publish` was then attempted from that same tree — and the ONLY thing that stopped it
+  # was npm's own "cannot publish over 1.4.84" collision check. Publishing is irreversible; being
+  # saved by the registry's bookkeeping is luck, not a floor.
+  # This is N=1 and it is built anyway: the repetition rule ("1-2 occurrences -> prose") is scoped to
+  # REVERSIBLE surfaces. A wrong tag on a public repo plus a publish from the wrong tree is the
+  # irreversible class, where this repo's own Surface-Class Degrade Invariant says fail-CLOSED now.
+  # Scope is deliberately narrow: only a NEW `refs/tags/v<digits>` push, only when package.json
+  # exists at that commit. Absent package.json -> not applicable (a tag in a non-npm repo is fine);
+  # unreadable package.json at a commit that HAS one -> BLOCK (cannot decide != allowed).
+  if [ "$local_sha" != "$ZERO" ] && [ "${remote_sha:-$ZERO}" = "$ZERO" ]; then
+    case "$remote_ref" in
+      refs/tags/v[0-9]*)
+        _tv="${remote_ref#refs/tags/v}"
+        _commit=$(git rev-parse "${local_sha}^{commit}" 2>/dev/null)
+        if [ -z "$_commit" ]; then
+          echo "  ⛔ TAG/VERSION: $remote_ref does not resolve to a commit — cannot verify, refusing"
+          TAG_MISMATCH="$TAG_MISMATCH $remote_ref"
+        elif git cat-file -e "${_commit}:package.json" 2>/dev/null; then
+          _pv=$(git show "${_commit}:package.json" 2>/dev/null \
+                | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+          if [ -z "$_pv" ]; then
+            echo "  ⛔ TAG/VERSION: package.json exists at ${_commit} but its version is unreadable — refusing"
+            TAG_MISMATCH="$TAG_MISMATCH $remote_ref"
+          elif [ "$_pv" != "$_tv" ]; then
+            echo "  ⛔ TAG/VERSION MISMATCH: $remote_ref points at ${_commit}, whose package.json says $_pv"
+            TAG_MISMATCH="$TAG_MISMATCH $remote_ref"
+          fi
+        fi ;;
+    esac
+  fi
+
   # PR-only policy: a non-delete update aimed straight at the integration branch.
   # Detected INSIDE this loop because this is the only place git's ref list is readable.
   if [ "$local_sha" != "$ZERO" ]; then
@@ -403,6 +438,27 @@ fi
 # instead of a bare server rejection, and it keeps working if the server setting is ever relaxed.
 # It is deliberately NOT the hard floor — a client-side hook is bypassable by `--no-verify`.
 # Scope: blocks the PUSH, not the merge — `gh pr merge` operates server-side and is unaffected.
+if [ -n "$TAG_MISMATCH" ] && [ "${TAG_VERSION_OK:-0}" != "1" ]; then
+  echo ""
+  echo "══════════════════════════════════════════════"
+  echo " ⛔ FH Tag/Version Consistency (pre-push)"
+  echo "══════════════════════════════════════════════"
+  echo "  Tag(s) whose commit disagrees with package.json:$TAG_MISMATCH"
+  echo ""
+  echo "  A release tag is the thing a human and a script both trust to answer \"what shipped\"."
+  echo "  Measured 2026-08-02: a tag went onto the pre-release commit because a failed \`git pull\`"
+  echo "  went unread, and \`npm publish\` was then attempted from that same tree. Only npm's own"
+  echo "  version-collision check stopped it. Publishing does not un-happen; that was luck."
+  echo ""
+  echo "  Fix:  git fetch origin && git switch main && git pull --ff-only"
+  echo "        git tag -d <tag> && git push origin :refs/tags/<tag>   # if already pushed"
+  echo "        # then re-tag on the commit whose package.json really carries that version"
+  echo ""
+  echo "  Deliberate exception (explicit, logged — mirrors MAIN_PUSH_OK / DESTRUCTIVE_OP_OK):"
+  echo "      TAG_VERSION_OK=1 git push …"
+  exit 1
+fi
+
 if [ -n "$DIRECT_MAIN" ] && [ "${MAIN_PUSH_OK:-0}" != "1" ]; then
   echo ""
   echo "══════════════════════════════════════════════"

package/templates/subagent-tally-hook.json

@@ -0,0 +1,17 @@
+{
+  "_readme": "FH dispatch-tally hook. Merge the `hooks.SubagentStop` block below into your .claude/settings.json (that file is gitignored, which is why this template exists). It feeds session_close_check.sh ④-e, which blocks a close push when sub-agents were dispatched and the day's invocation-log entries are zero. The hook TALLIES ONLY — it never writes a log entry, because a fabricated outcome/evidence field would poison the 60/40 promotion gate worse than a missing one.",
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'HUB=\"${CLAUDE_PROJECT_DIR:-$HOME/projects/forge-harness}\"; T=\"$HUB/tracks/_meta/.subagent_dispatch_tally\"; mkdir -p \"$(dirname \"$T\")\" 2>/dev/null; printf \"%s\\n\" \"$(date +%Y-%m-%d)\" >> \"$T\" 2>/dev/null; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}