@chrono-meta/fh-gate 1.4.72 → 1.4.74

package/scripts/gate_pathspec_check.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# gate_pathspec_check.sh — known-pair regression anchor for gate PATH COVERAGE.
+#
+# WHY THIS EXISTS
+# The gate-locality class has now recurred four times: scripts/ (2026-06-26), AGENTS.md
+# inheritance (#111/#117), agent definitions (2026-06-27), and SKILL_detail.md (2026-07-26).
+# Every instance had the same shape: an asset class the canonical rule *declared* covered, which
+# the gate implementation's path term did not actually match — and the miss rendered as PASS,
+# because "no file matched" and "all files passed" are indistinguishable downstream.
+#
+# The 07-26 instance was the sharpest: the term was the literal `SKILL\.md`, and the string
+# `SKILL_detail.md` does not contain `SKILL.md` (the underscore breaks it). 17 files, 208,710 B,
+# 27.7% of the skill-spec surface, 16 of 17 holding fenced code blocks — ungated. It leaked twice
+# for real (371c04f, e661931: single-file edits to a GATE SKILL's own behavioral spec).
+#
+# So this is not a style check. It is the mechanical anchor for the fix, per the FH rule that a
+# harness edit is a draft until a check fails when the mistake recurs.
+#
+# METHOD — known-pair, per CLAUDE.md §Instrument-Calibration. Every case asserts BOTH directions:
+# a known-positive that MUST match and a known-negative that MUST NOT. A checker that only ever
+# confirms positives cannot tell "covers everything" from "matches everything".
+#
+# Usage: bash scripts/gate_pathspec_check.sh          # exit 0 = all pairs hold, 1 = a pair broke
+set -uo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+HOOK="$REPO_ROOT/templates/.git-hooks/pre-commit"
+GUARD="$REPO_ROOT/templates/regression_guard.sh"
+
+fail=0
+pass=0
+
+# Extract a live regex from the implementation instead of restating it here. A copy would drift
+# from the thing it claims to verify — which is the very defect class this file exists to catch.
+extract_term() {  # $1 = file, $2 = variable-assignment marker
+  grep -A2 "^${2}=" "$1" 2>/dev/null | grep -oE '\| grep -E "[^"]+"' | head -1 \
+    | sed -E 's/^\| grep -E "//; s/"$//'
+}
+
+check() {  # $1 = label, $2 = regex, $3 = should-match path, $4 = should-NOT-match path
+  local label="$1" re="$2" pos="$3" neg="$4" ok=1 rc
+  # grep exits 2 on a MALFORMED regex. `if ! grep -q` would negate that 2 into "true" and report
+  # it as "known-positive not covered" — fail-closed in direction, but it misnames the cause, and
+  # a checker that misreports why it failed sends the next reader to fix the wrong thing.
+  echo "$pos" | grep -qE "$re"; rc=$?
+  if [ "$rc" -eq 2 ]; then
+    echo "  ❌ $label — extracted pattern is not a valid regex (instrument error, NOT a coverage result)"
+    echo "     pattern: $re"
+    fail=$((fail + 1)); return
+  fi
+  [ "$rc" -ne 0 ] && { echo "  ❌ $label — known-POSITIVE not covered: $pos"; ok=0; }
+  if echo "$neg" | grep -qE "$re"; then
+    echo "  ❌ $label — known-NEGATIVE wrongly covered: $neg"; ok=0
+  fi
+  if [ "$ok" -eq 1 ]; then
+    echo "  ✅ $label"; pass=$((pass + 1))
+  else
+    fail=$((fail + 1))
+  fi
+}
+
+echo "gate_pathspec_check — known-pair coverage anchors"
+echo
+
+# ── 1. pre-commit HEAVY term ──────────────────────────────────────────────────
+HEAVY_RE="$(extract_term "$HOOK" HEAVY)"
+if [ -z "$HEAVY_RE" ]; then
+  echo "  ❌ could not extract HEAVY term from $HOOK — instrument error, NOT a pass"
+  exit 1
+fi
+# The 07-26 regression: detail files must be HEAVY. Negative: a tracks/ record must not be.
+check "HEAVY covers SKILL_detail.md" "$HEAVY_RE" \
+  "plugins/fh-meta/skills/frontier-digest/SKILL_detail.md" \
+  "tracks/_meta/fh_signal_2026-07-26_ai.md"
+check "HEAVY still covers SKILL.md" "$HEAVY_RE" \
+  "plugins/fh-meta/skills/frontier-digest/SKILL.md" \
+  "README.md"
+# Prior gate-locality instances — anchored so a future edit cannot silently drop them.
+check "HEAVY covers agent definitions (seam #3)" "$HEAVY_RE" \
+  "plugins/fh-meta/agents/challenger.md" \
+  "docs/README.md"
+check "HEAVY covers scripts/*.sh (seam #1)" "$HEAVY_RE" \
+  "scripts/gate_pathspec_check.sh" \
+  "tracks/_audit/session_2026_07_26_agentsmith-sister.md"
+
+# ── 2. regression_guard GUARD_PATHSPEC ────────────────────────────────────────
+# Read the array as the guard itself defines it; match with the same glob semantics git uses.
+# NOTE: no `mapfile` — macOS ships bash 3.2, where it does not exist. This is the documented
+# bash-3.2 portability class; a 4.x-only builtin here would make the anchor itself the thing that
+# breaks on the operator's own machine.
+SPEC=()
+while IFS= read -r line; do
+  [ -n "$line" ] && SPEC+=("$line")
+done < <(sed -n '/^GUARD_PATHSPEC=(/,/^)/p' "$GUARD" | grep -oE "'[^']+'" | tr -d "'")
+if [ "${#SPEC[@]:-0}" -eq 0 ]; then
+  echo "  ❌ could not extract GUARD_PATHSPEC from $GUARD — instrument error, NOT a pass"
+  exit 1
+fi
+spec_matches() {  # $1 = path
+  local p="$1" g
+  for g in "${SPEC[@]}"; do
+    # shellcheck disable=SC2254
+    case "$p" in $g) return 0 ;; esac
+  done
+  return 1
+}
+for pair in \
+  "plugins/fh-meta/skills/frontier-digest/SKILL_detail.md|tracks/_meta/x.md|PATHSPEC covers SKILL_detail.md" \
+  "plugins/fh-meta/skills/frontier-digest/SKILL.md|README.md|PATHSPEC still covers SKILL.md" \
+  "CLAUDE.md|CLAUDE.local.md|PATHSPEC covers CLAUDE.md but not the local override"
+do
+  IFS='|' read -r pos neg label <<< "$pair"
+  ok=1
+  spec_matches "$pos" || { echo "  ❌ $label — known-POSITIVE not covered: $pos"; ok=0; }
+  spec_matches "$neg" && { echo "  ❌ $label — known-NEGATIVE wrongly covered: $neg"; ok=0; }
+  if [ "$ok" -eq 1 ]; then echo "  ✅ $label"; pass=$((pass + 1)); else fail=$((fail + 1)); fi
+done
+
+# ── 3. Canonical-vs-implementation parity ─────────────────────────────────────
+# regression_guard.sh's own comment: "두 목록이 갈리면 갈린 쪽이 조용히 무검사 구간이 된다."
+# Anchor that warning mechanically for the asset class that just broke.
+CANON="$REPO_ROOT/.claude/rules/fh_4axis_gate.md"
+# Scope the match to the ASSET-LIST sentence, not the whole file. A bare whole-file grep would go
+# green on a line that says "SKILL_detail.md is excluded" — i.e. it would certify parity against
+# documentation that contradicts the code. Match the declaration line itself.
+if grep -q 'Whenever the AI modifies FH assets.*SKILL_detail\.md' "$CANON" 2>/dev/null; then
+  echo "  ✅ canonical rule declares SKILL_detail.md (in the asset-list line)"; pass=$((pass + 1))
+else
+  echo "  ❌ canonical rule ($CANON) no longer declares SKILL_detail.md — the two lists diverged,"
+  echo "     which is exactly the silent no-check condition this anchor exists to prevent."
+  fail=$((fail + 1))
+fi
+
+# ── 4. Enumeration sweep — the anti-guessing check ────────────────────────────
+# Every fix above answers "is THIS name covered?" — which only ever closes the names someone
+# thought of. This one inverts it: enumerate what actually EXISTS under plugins/*/skills/ and
+# assert the HEAVY term covers all of it. A new companion-file convention (SKILL_summary.md,
+# a nested docs/ page, a deeper skill directory) then fails HERE, at introduction, instead of
+# waiting for someone to notice the naming gap years later. Reality is the input, not a guess.
+# (Adversarial credit: an Axis-2 sidecar pass argued the name-by-name fixes could not, in
+# principle, close the class — correct, and this is the answer to it.)
+uncovered=""
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  echo "$f" | grep -qE "$HEAVY_RE" || uncovered="$uncovered$f
+"
+done < <(cd "$REPO_ROOT" && find plugins -path '*/skills/*' -name '*.md' -type f 2>/dev/null | sort)
+if [ -z "$uncovered" ]; then
+  echo "  ✅ enumeration: every .md under plugins/*/skills/ is covered by the HEAVY term"
+  pass=$((pass + 1))
+else
+  echo "  ❌ enumeration: files exist under plugins/*/skills/ that NO gate term covers —"
+  printf '%s' "$uncovered" | sed 's/^/       /'
+  echo "     Either widen the gate term, or state in fh_4axis_gate.md why this class is exempt."
+  fail=$((fail + 1))
+fi
+
+echo
+if [ "$fail" -eq 0 ]; then
+  echo "gate_pathspec_check: PASS ($pass pairs)"
+  exit 0
+fi
+echo "gate_pathspec_check: FAIL ($fail broken, $pass ok)"
+echo "A gate path term stopped covering an asset class it is declared to cover."
+echo "Do NOT relax the anchor to make it green — fix the term, or retire the pair deliberately."
+exit 1

package/scripts/package_coverage_check.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# package_coverage_check.sh — a shipped document must not point at a file the package omits.
+#
+# WHY (measured 2026-07-28): the npm tarball shipped CLAUDE.md, README, CATALOG and the knowledge/
+# base while omitting much of what they instruct the reader to open — 35 distinct paths existed in
+# the repo, were named by a shipped document, and were absent from the tarball. `CLAUDE.md` told
+# consumers to run `templates/predelete_check.sh` before a destructive op; that file did not ship.
+# A gate you are told to run and cannot run is worse than one you were never told about.
+#
+# This is the ANTI-REGROWTH instrument for that class. Closing the 35 once is worth little: the set
+# regrows every time a doc gains a reference or files[] gains an entry. So the check is mechanical
+# and the exceptions are ENUMERATED, never implicit.
+#
+# SOURCE-TREE ONLY. Inside an installed package the un-shipped files are legitimately absent and
+# package.json's files[] may not even be present in a comparable form, so the check self-skips.
+#
+# Usage:  bash scripts/package_coverage_check.sh
+# Exit:   0 = every referenced path is either shipped or explicitly accepted; 1 = a new phantom.
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT" || exit 1
+
+if [ ! -d .git ] || [ ! -f package.json ]; then
+  echo "SKIP  package-coverage (not a source checkout)"
+  exit 0
+fi
+
+# ── Accepted-absent, with the reason each one is NOT a defect ────────────────────────────────
+# Adding a line here is a decision, not a silencer: each entry states why shipping it would be
+# wrong. If you cannot write that sentence, the file probably belongs in files[].
+#
+#   .claude/registry/LOCAL_SKILL_REGISTRY.md — per-environment, generated by the registry scan.
+#       Its consumers probe it with `ls … 2>/dev/null` and handle absence; shipping one machine's
+#       registry would hand every consumer a false map of skills they do not have.
+#   .claude/regression/probes.md            — per-environment prompt-regression baselines. The
+#       skill explicitly prints NO_CUSTOM_PROBES when absent. Shipping FH's baselines would make
+#       a consumer's regression run compare against someone else's harness.
+#   scripts/sync-to-be.sh                   — operator-private companion-store sync. Never ships.
+#       (The reference that flags it is a TEST FIXTURE in prepush_guard_check.sh which *creates*
+#        a file of that name to exercise the LOW allowlist — not a pointer to this file at all.)
+#   scripts/sync_guard_check.sh             — anchor for that same operator-private mirror sync;
+#       no shipped hook invokes it.
+ACCEPTED_ABSENT=(
+  ".claude/registry/LOCAL_SKILL_REGISTRY.md"
+  ".claude/regression/probes.md"
+  "scripts/sync-to-be.sh"
+  "scripts/sync_guard_check.sh"
+)
+
+out=$(python3 - "${ACCEPTED_ABSENT[@]}" <<'PY'
+import re, os, json, sys
+accepted = set(sys.argv[1:])
+files = json.load(open('package.json'))['files']
+
+def covered(p):
+    return any(p == f or p.startswith(f.rstrip('/') + '/') for f in files)
+
+shipped = []
+for f in files:
+    if os.path.isfile(f):
+        shipped.append(f)
+    elif os.path.isdir(f):
+        for root, _, names in os.walk(f):
+            shipped.extend(os.path.join(root, n) for n in names)
+
+# Only text surfaces can carry a reference a human or agent would follow.
+shipped = [s for s in shipped if s.endswith(('.md', '.sh', '.js', '.json', '.yaml', '.yml'))]
+
+pat = re.compile(
+    r'(?<![\w/.-])((?:scripts|templates|bin|docs|knowledge|plugins|\.claude)'
+    r'/[A-Za-z0-9_./-]+\.(?:sh|py|js|md|yaml|yml|json|defaults))'
+)
+
+phantom = {}
+for s in shipped:
+    try:
+        text = open(s, encoding='utf-8', errors='ignore').read()
+    except OSError:
+        continue
+    for m in set(pat.findall(text)):
+        # Only a path that REALLY EXISTS here but is left out of the tarball is this defect.
+        # A path that exists nowhere is the ordinary phantom-reference class the ref-path
+        # check above already owns; a path outside files[] that is also absent is nothing.
+        if os.path.exists(m) and not covered(m) and m not in accepted:
+            phantom.setdefault(m, set()).add(s)
+
+# Impossible-zero guard: this repo always has shipped docs. Zero scanned means the extractor
+# broke — report that as a failure rather than letting a dead check print a pass
+# (same rule as count_check.sh and the ref-path extractor).
+if not shipped:
+    print("EXTRACTOR_BROKE")
+    raise SystemExit(2)
+
+for p, srcs in sorted(phantom.items(), key=lambda kv: (-len(kv[1]), kv[0])):
+    print(f"{p}\t{len(srcs)}\t{sorted(srcs)[0]}")
+raise SystemExit(1 if phantom else 0)
+PY
+)
+rc=$?
+
+if [ "$rc" -eq 2 ] || [ "$out" = "EXTRACTOR_BROKE" ]; then
+  echo "FAIL  package-coverage: extractor scanned 0 shipped docs — the check broke, it did not pass"
+  exit 1
+fi
+
+if [ "$rc" -ne 0 ]; then
+  echo "FAIL  package-coverage: shipped document(s) point at file(s) the package omits:"
+  printf '%s\n' "$out" | while IFS=$'\t' read -r path n src; do
+    [ -z "$path" ] && continue
+    printf '        %s  (named by %s shipped doc(s), e.g. %s)\n' "$path" "$n" "$src"
+  done
+  echo "      Fix: add the path to package.json files[], OR list it in ACCEPTED_ABSENT here"
+  echo "      with a one-sentence reason why shipping it would be wrong."
+  exit 1
+fi
+
+echo "PASS  package-coverage: every referenced path is shipped or explicitly accepted (${#ACCEPTED_ABSENT[@]} accepted)"
+exit 0