@chrono-meta/fh-gate 1.4.73 → 1.4.75

package/scripts/test_marker_floor_lanes.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# test_marker_floor_lanes.sh — regression fixtures for pre-commit validate_marker_floor lanes.
+#
+# Ships with the 2026-07-10 sonnet-floor lane (Sonnet-Floor Doctrine): each closed hole gets a
+# mechanical regression test (Field-Harness Load-Bearing Change Gate convergence condition).
+# Fixtures assert BOTH directions: the new lane admits exactly its intended shape, and every
+# pre-existing guard still blocks (no degrade-toward-permissive regression).
+#
+# Usage: bash scripts/test_marker_floor_lanes.sh   Exit: 0 = all fixtures behave; 1 = regression.
+
+set -uo pipefail
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+HOOK="$REPO_ROOT/templates/.git-hooks/pre-commit"
+T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
+
+sed -n '/^marker_recreate_hint()/,/^}/p;/^validate_marker_floor()/,/^}/p' "$HOOK" > "$T/fn.sh"
+
+run() { bash -c "source '$T/fn.sh'; validate_marker_floor '$1'" >/dev/null 2>&1; }
+
+FAIL=0
+check() { # $1=fixture $2=expected(PASS|BLOCK) $3=label
+  if run "$1"; then got=PASS; else got=BLOCK; fi
+  if [ "$got" = "$2" ]; then echo "✅ $3 → $got"; else echo "❌ $3 → $got (expected $2)"; FAIL=1; fi
+}
+
+printf 'axis2-engine: inline\naxis2-model: sonnet\nfloor-status: sonnet-floor\naxis2-anchor: regression test 5/5 pass\naxis2-evidence: PASS no-S, 2B applied\n' > "$T/m1"
+printf 'axis2-engine: inline\naxis2-model: sonnet\nfloor-status: sonnet-floor\naxis2-evidence: PASS no-S\n' > "$T/m2"
+printf 'axis2-engine: inline\naxis2-model: haiku\nfloor-status: sonnet-floor\naxis2-anchor: probe 3/3\naxis2-evidence: PASS no-S\n' > "$T/m3"
+printf 'axis2-engine: inline\naxis2-model: sonnet\nfloor-status: at-floor\naxis2-evidence: PASS no-S\n' > "$T/m4"
+printf 'axis2-engine: inline\naxis2-model: haiku\nfloor-status: below-floor\naxis2-evidence: PASS no-S\n' > "$T/m5"
+printf 'axis2-engine: quench-challenger\naxis2-model: opus\nfloor-status: at-floor\naxis2-evidence: 1S/4A fixed\n' > "$T/m6"
+printf 'axis2-engine: inline\naxis2-model: haiku\nfloor-status: below-floor\nbelow-floor-ack: "approved, proceed" — canary-only change\naxis2-evidence: PASS no-S\n' > "$T/m7"
+printf 'axis2-engine: inline\naxis2-model: opus\nfloor-status: bogus-status\naxis2-evidence: PASS\n' > "$T/m8"
+
+check "$T/m1" PASS  "sonnet-floor + anchor + sonnet model (new lane, intended shape)"
+check "$T/m2" BLOCK "sonnet-floor WITHOUT anchor (anchor is the compensating requirement)"
+check "$T/m3" BLOCK "haiku claiming sonnet-floor (lane mislabel)"
+check "$T/m4" BLOCK "sonnet claiming at-floor (2026-06-10 mislabel class — guard intact)"
+check "$T/m5" BLOCK "below-floor without ack (guard intact)"
+check "$T/m6" PASS  "opus at-floor (legacy lane intact)"
+check "$T/m7" PASS  "below-floor with quoted ack (legacy lane intact)"
+check "$T/m8" BLOCK "invalid floor-status (fail-closed on unknown value)"
+
+[ "$FAIL" -eq 0 ] && echo "── all marker-floor lane fixtures behave ──"
+exit "$FAIL"

package/scripts/test_memory_link_check.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# test_memory_link_check.sh — known-pair anchor for scripts/memory_link_check.py.
+#
+# WHY: the checker's --fix-separators path WRITES to personal knowledge files. Everything it gets
+# wrong, it gets wrong silently and in bulk. Two of its rules were found only by attacking it:
+#   * a first draft rewrote links inside FENCED blocks — i.e. it "corrected" the examples that
+#     document the convention, which is the probe-damages-the-remedy class;
+#   * a first measurement counted cross-store links as broken, overstating the defect by 44%.
+# Both are pinned below, alongside the classes.
+#
+# Lanes
+#   C1  the five classes separate on a fixture (ok / separator / cross-store-absent / placeholder / dangling)
+#   F1  a link inside a fenced block is COUNTED but never REWRITTEN
+#   F2  a link inside inline backticks IS rewritten (this corpus styles real links that way —
+#       measured 2026-07-28: 25 such links repaired, 0 fenced changes in the same run)
+#   F3  aliased links [[target|alias]] keep their alias
+#   F4  re-running the fixer changes nothing (idempotent)
+#   G1  an empty store reports an extractor failure, never a clean graph
+#
+# Exit 0 = 6/6.
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CHK="$ROOT/scripts/memory_link_check.py"
+[ -f "$CHK" ] || { echo "FAIL: $CHK missing"; exit 1; }
+
+pass=0; fail=0
+ok()  { printf '  ✅ %s\n' "$1"; pass=$((pass+1)); }
+bad() { printf '  ❌ %s\n' "$1"; fail=$((fail+1)); }
+
+TD="$(mktemp -d)"; trap 'rm -rf "$TD"' EXIT
+mkdir -p "$TD/store"
+printf -- '---\nname: real_target\n---\nbody\n' > "$TD/store/real_target.md"
+cat > "$TD/store/src.md" <<'EOF'
+---
+name: src
+---
+plain ok: [[real_target]]
+plain separator: [[real-target]]
+alias: [[real-target|shown as this]]
+inline: `[[real-target]]`
+dangling: [[nothing_here]]
+placeholder: [[link]]
+
+```
+fenced example — must NOT be rewritten: [[real-target]]
+```
+EOF
+
+_run() { python3 "$CHK" --memory "$TD/store" "$@" 2>/dev/null; }
+
+out=$(_run)
+# FIRST match only. `dangling` appears twice in the report — once as a count row and once as a
+# section header ("dangling (nothing on disk...)") — so an unbounded match returned two lines and
+# the numeric comparison silently failed against a correct tool. Instrument fault, fixed here.
+_n() { printf '%s\n' "$out" | awk -v k="$1" '$1==k && $2 ~ /^[0-9]+$/ {print $2; exit}'; }
+if [ "$(_n ok)" = "1" ] && [ "$(_n placeholder)" = "1" ] && [ "$(_n dangling)" = "1" ] && [ "$(_n separator)" -ge 4 ]; then
+  ok "C1 classes separate (ok=$(_n ok) separator=$(_n separator) placeholder=$(_n placeholder) dangling=$(_n dangling))"
+else
+  bad "C1 class counts wrong"; printf '%s\n' "$out" | sed 's/^/     /'
+fi
+
+_run --fix-separators --quiet >/dev/null
+body=$(cat "$TD/store/src.md")
+
+if printf '%s' "$body" | sed -n '/```/,/```/p' | grep -q '\[\[real-target\]\]'; then
+  ok "F1 fenced example left untouched (the documentation of the rule survives the fixer)"
+else
+  bad "F1 the fixer rewrote a link inside a fenced block — it corrected its own example"
+fi
+
+if printf '%s' "$body" | grep -q 'inline: `\[\[real_target\]\]`'; then
+  ok "F2 inline-backticked link repaired (this store's citation style is a real link)"
+else
+  bad "F2 inline-backticked link was not repaired"
+fi
+
+if printf '%s' "$body" | grep -q '\[\[real_target|shown as this\]\]'; then
+  ok "F3 alias preserved through the rewrite"
+else
+  bad "F3 alias lost or target not rewritten"
+fi
+
+before=$(cat "$TD/store/src.md")
+_run --fix-separators --quiet >/dev/null
+if [ "$before" = "$(cat "$TD/store/src.md")" ]; then
+  ok "F4 idempotent on re-run"
+else
+  bad "F4 a second run changed the file again"
+fi
+
+mkdir -p "$TD/empty"
+if python3 "$CHK" --memory "$TD/empty" >/dev/null 2>&1; then
+  bad "G1 an empty store exited 0 — a scan that cannot see its subject reported a clean graph"
+else
+  ok "G1 empty store fails as an extractor error, not a pass"
+fi
+
+
+# H1/A1 — cross-family findings, both confirmed by execution before acceptance.
+#   H1 (agy): an anchor-form link `[[target#section]]` was COUNTED as repairable but the rewrite
+#             enumerated closing forms by hand and never matched it — so it was flagged on every
+#             run (idempotence broken) and the summary reported more fixes than it made.
+#   A1 (gpt-5.5): two notes sharing a normalized name let the fixer reroute an edge to whichever
+#             sorted first, and the wrong link then resolves exactly, so no later run flags it.
+printf -- '---\nname: my_topic\n---\nbody\n' > "$TD/store/my_topic.md"
+printf -- '---\nname: anchored\n---\nanchor: [[my-topic#section-1]]\nplain: [[my-topic]]\n' > "$TD/store/anchored.md"
+_run --fix-separators --quiet >/dev/null
+if grep -q '\[\[my_topic#section-1\]\]' "$TD/store/anchored.md"; then
+  ok "H1 anchor-form link rewritten (target only, #section preserved)"
+else
+  bad "H1 [[target#anchor]] left unrewritten — flagged forever, and the fix count over-reports"
+fi
+# Idempotence here is a STABLE count, not zero: the fenced example is counted every run and
+# deliberately never rewritten, so zero is unreachable by design. Asserting zero was an instrument
+# error in this anchor's first draft — it scored a correct tool as failing.
+before_n=$(out=$(_run); printf '%s\n' "$out" | awk '$1=="separator" && $2 ~ /^[0-9]+$/ {print $2; exit}')
+_run --fix-separators --quiet >/dev/null
+after_n=$(out=$(_run); printf '%s\n' "$out" | awk '$1=="separator" && $2 ~ /^[0-9]+$/ {print $2; exit}')
+if [ "$before_n" = "$after_n" ]; then
+  ok "H1b idempotent with anchor forms present (count stable at $after_n — the fenced example)"
+else
+  bad "H1b count moved $before_n → $after_n across a second fix pass"
+fi
+printf -- 'A\n' > "$TD/store/collide-x.md"; printf -- 'B\n' > "$TD/store/collide_x.md"
+out=$(_run)
+if printf '%s\n' "$out" | grep -q 'ambiguous'; then
+  ok "A1 colliding normalized names surface as a reported class"
+else
+  bad "A1 no ambiguous class — a colliding pair can still be auto-rerouted"
+fi
+
+echo "----"
+echo "memory-link-check anchor: $pass passed, $fail failed"
+[ "$fail" -eq 0 ] || exit 1

package/scripts/test_session_close_lanes.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# test_session_close_lanes.sh — known-pair anchor for session_close_check.sh ② (harvest-loop
+# obligation) and ⑤ (card-last invariant).
+#
+# WHY (2026-07-28): ② used to be an UNSATISFIABLE warning — it fired whenever an FH asset was
+# touched today and the script had no way to observe whether harvest-loop ran, so no session could
+# ever discharge it. A line that fires on every healthy close is noise, and noise trains the runner
+# to skim past the ❌ lines that matter. The repair gave it a mechanical discharge (a harvest-loop
+# decision recorded in TODAY's fh_completed file). This file is that repair's regression anchor:
+# the fix is only real if the ⚠️ still fires when NOTHING is recorded, and stops firing when it is.
+#
+# Lanes (each is a decision the gate must get right, not a smoke test):
+#   ②-N   FH asset touched today, no harvest-loop line anywhere  → ⚠️  MUST fire
+#   ②-P1  same, plus "harvest-loop 실행 완료"                     → ✅  must NOT fire
+#   ②-P2  same, plus an explicit SKIP note                        → ✅  must NOT fire
+#         (CLAUDE.md ② accepts "harvest-loop (or an explicit skip note)" — a recorded skip is
+#          a discharged obligation, not an evaded one)
+#   ②-C   no FH asset touched today                               → neither line appears at all
+#         (over-firing is a defect in its own right — the whole reason this repair exists)
+#   ⑤-N   a close artifact newer than the card                    → ❌ card-last MUST fire (exit 1)
+#   ⑤-P   card is the newest artifact                             → ✅ card-last holds
+#
+# Exit 0 = 7/7 lanes calibrated · exit 1 = the gate's instrument is wrong (do not trust its verdict)
+
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK="$SCRIPT_DIR/session_close_check.sh"
+TODAY=$(date +%Y-%m-%d)
+FAILED=0
+
+if [ ! -f "$CHECK" ]; then
+  echo "FAIL  session-close lanes: subject $CHECK missing"
+  exit 1
+fi
+
+# Builds a throwaway repo whose HEAD commit touches (or does not touch) an FH asset path.
+_fixture() {  # $1=touch_fh_asset(0/1)  $2=completed-file body (empty = no file)
+  local touch_fh="$1" body="$2" T
+  T=$(mktemp -d)
+  ( cd "$T" \
+    && git init -q . \
+    && git config user.email anchor@local && git config user.name anchor \
+    && if [ "$touch_fh" = 1 ]; then echo x > CLAUDE.md; else echo x > unrelated.txt; fi \
+    && git add -A && git commit -qm "fixture" ) >/dev/null 2>&1
+  mkdir -p "$T/tracks/_meta"
+  [ -n "$body" ] && printf '%s\n' "$body" > "$T/tracks/_meta/fh_completed_${TODAY}.md"
+  printf '# card\n' > "$T/tracks/_meta/reference_next_session_starter.md"
+  printf '%s' "$T"
+}
+
+_lane() {  # $1=name  $2=grep-pattern  $3=expect(0/1)  $4=fixture dir
+  local name="$1" pat="$2" expect="$3" T="$4" out hit
+  out=$(bash "$CHECK" "$T" 2>/dev/null)
+  hit=0
+  printf '%s\n' "$out" | grep -q "$pat" && hit=1
+  rm -rf "$T"
+  if [ "$hit" = "$expect" ]; then
+    echo "✅ $name (hit=$hit, expected=$expect)"
+  else
+    echo "❌ $name — hit=$hit, expected=$expect"
+    printf '%s\n' "$out" | sed 's/^/     /'
+    FAILED=1
+  fi
+}
+
+WARN2='⚠️  ② FH assets changed today'
+OK2='✅ ② FH assets changed today'
+
+_lane "②-N  no harvest-loop decision recorded → warns" "$WARN2" 1 "$(_fixture 1 '- 항목 하나')"
+_lane "②-P1 harvest-loop run recorded → silent"        "$WARN2" 0 "$(_fixture 1 '- harvest-loop 실행 완료')"
+_lane "②-P2 explicit skip note → silent"               "$WARN2" 0 "$(_fixture 1 '- harvest-loop: skipped — 3-repo session, deferred')"
+_lane "②-P1 run recorded → prints the ✅ form"          "$OK2"   1 "$(_fixture 1 '- harvest-loop 실행 완료')"
+_lane "②-C  no FH asset touched → no ② line at all"    ' ② '    0 "$(_fixture 0 '- 항목 하나')"
+
+# ⑤ card-last: an artifact newer than the card is the bug class the invariant exists to catch.
+T=$(_fixture 1 '- harvest-loop 실행 완료')
+touch "$T/tracks/_meta/fh_completed_${TODAY}.md"   # make it strictly newer than the card
+if bash "$CHECK" "$T" >/dev/null 2>&1; then
+  echo "❌ ⑤-N  artifact newer than card → expected exit 1, got 0 (card-last not enforced)"
+  FAILED=1
+else
+  echo "✅ ⑤-N  artifact newer than card → exit 1 (card-last enforced)"
+fi
+touch "$T/tracks/_meta/reference_next_session_starter.md"   # card becomes newest
+if bash "$CHECK" "$T" >/dev/null 2>&1; then
+  echo "✅ ⑤-P  card newest → exit 0"
+else
+  echo "❌ ⑤-P  card newest → expected exit 0, got 1 (over-blocking: trains --no-verify)"
+  bash "$CHECK" "$T" 2>&1 | sed 's/^/     /'
+  FAILED=1
+fi
+rm -rf "$T"
+
+if [ "$FAILED" -ne 0 ]; then
+  echo "SESSION-CLOSE LANES: FAIL — the gate's instrument is miscalibrated"
+  exit 1
+fi
+echo "SESSION-CLOSE LANES: PASS (7/7)"
+exit 0

package/scripts/tier_census_grep.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# tier_census_grep.sh — word-boundary tier-reference census helper (Sonnet-Floor Doctrine).
+#
+# WHY (origin: fh_signal_2026-07-10_session — Sonnet full-loop probe): the naive census pattern
+# `opus|sonnet|haiku|floor|tier|model:` false-positives heavily ("frontier" matches `tier`,
+# "floors" prose, method-sense "model"). The probe self-corrected, but per the doctrine's own
+# prescription ladder (step 1: mechanize) the discipline belongs in a script, not re-derived
+# per session. Built 2026-07-10 on operator instruction (evidence-threshold overridden by
+# explicit "complete it" — recorded, not silent).
+#
+# WHAT: emits candidate tier-reference hits with word-boundary patterns, one line per hit
+# (file:line:text), for the auditor to CLASSIFY per sonnet_floor_doctrine.md's table
+# (trust-floor / availability-gate / advisory / N-A). The script finds candidates; the
+# classification stays a judged step with the doctrine table as its anchor.
+#
+# Sense-filter hints (printed, not auto-applied — de-noising must never hide a real gate):
+#   - "frontier|multi-tier|C-tier|A/B-tier" → usually N/A (different axis: content/data tiers)
+#   - "hub model|mental model|data model"   → usually N/A (methodology sense of "model")
+#   - execution tier S/M/L/XL               → N/A (token budget, not model tier — fh_detail_protocols)
+#
+# Usage: bash scripts/tier_census_grep.sh <file> [file...]     Exit: 0 always (census, not gate)
+
+set -uo pipefail
+
+if [ $# -eq 0 ]; then
+  echo "usage: bash scripts/tier_census_grep.sh <file> [file...]" >&2
+  exit 0
+fi
+
+PATTERN='\b(opus|sonnet|haiku|fable)\b|\bfloor(-status|-tier|s)?\b|\btiers?\b|(^|[^a-zA-Z])model:'
+
+for f in "$@"; do
+  if [ ! -f "$f" ]; then
+    echo "── $f: NOT FOUND (phantom input — check the path) ──"
+    continue
+  fi
+  echo "── census candidates: $f ──"
+  # -P where available (GNU/pcre); BSD grep on macOS supports -E word boundaries via [[:<:]] —
+  # portable route: grep -nEi with \b works on GNU; on BSD use perl fallback.
+  if echo x | grep -P 'x' >/dev/null 2>&1; then
+    grep -nPi "$PATTERN" "$f" || echo "   (0 candidates)"
+  else
+    # 0-hit에도 "(0 candidates)"를 찍는다 — GNU 분기와 출력 대칭 (pmh-parity 포트가 잡은 갭, 역이식 2026-07-10)
+    hits=$(perl -ne 'print "$.:$_" if /\b(opus|sonnet|haiku|fable)\b|\bfloor(-status|-tier|s)?\b|\btiers?\b|(^|[^a-zA-Z])model:/i' "$f")
+    if [ -n "$hits" ]; then printf '%s\n' "$hits"; else echo "   (0 candidates)"; fi
+  fi
+done
+
+cat <<'HINTS'
+── classify each hit per sonnet_floor_doctrine.md (trust-floor / availability-gate / advisory / N-A) ──
+   N/A sense hints (verify, don't auto-drop): frontier·C-tier·A/B-tier (content-tier axis) ·
+   "hub/mental/data model" (methodology sense) · S/M/L/XL execution tier (token budget, not model).
+HINTS
+exit 0

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

@@ -0,0 +1,153 @@
+<!--
+session.md — Claude Code Session Rules Template
+
+Purpose of this file:
+- Define Claude's session operating rules (how to behave)
+- Behavioral guidelines applied across the entire project
+- Commit to Git and share with the team
+- Edited and managed directly by the user
+
+Difference from MEMORY.md:
+- MEMORY.md: Stores data/experience learned during conversation (auto-managed by Claude)
+- session.md: Defines procedures/rules for Claude to follow (edited directly by the user)
+
+Usage:
+- Copy this file to your project's .claude/rules/session.md
+- Add, remove, or modify sections to fit your project
+- Change sections marked with [CUSTOMIZE] comments to match your project
+-->
+
+### Automatic Actions at Session Start
+
+#### Root Memory (Knowledge Hub) Connection
+
+At the start of a conversation ("hello", "let's start", "load root memory"), perform the following:
+
+1. Read `{FH_ROOT}/CATALOG.md`
+   - Understand recent work context
+   - Check today's tasks (todo/plan)
+
+2. Load project memory index
+   - Check `.claude/projects/.../memory/MEMORY.md`
+   - Prioritize loading memory most relevant to current work
+   - Proceed naturally without notifying the user that memory was loaded
+
+#### Exceptions
+- If the user explicitly requests not to use memory
+- For simple one-off questions, load is optional
+
+---
+
+### Session Backup Before Tests
+
+<!-- [CUSTOMIZE] Adjust trigger conditions to match your test framework -->
+
+#### Automatic Backup Trigger
+
+At any point when tests could be run, **automatically** perform a session backup:
+
+1. **When I recommend running tests** — **immediately before** the recommendation message
+2. **When the user signals intent to start tests** — **before** running the test command
+
+#### Why Backup
+- Sessions can be forcibly terminated when tests start
+- Prevents loss of conversation context, analysis results, and change history
+
+#### How to Backup
+
+```bash
+cat > .claude/session_backup_$(date +%Y%m%d_%H%M%S).md << 'EOF'
+# Session Backup - [Task Title]
+
+## Problem
+- [Issue currently being resolved]
+
+## Changes Made
+- [filename:line]
+- [before/after]
+
+## Next Steps
+- [Things to verify after tests]
+EOF
+```
+
+#### Important
+- Perform **automatically** even without an explicit user request
+- Never recommend tests without first creating a backup
+
+---
+
+### Automatic Response to Issues
+
+<!-- [CUSTOMIZE] Adjust report tool/path to match your project -->
+
+#### Automatic Check Trigger
+
+When the user mentions a problem, **automatically** locate and analyze the latest test report:
+
+1. **Trigger keywords**
+   - "something broke", "got an error", "it failed", "not working"
+   - "issue occurred", "test failed", "broken", "failed"
+
+2. **Analyze and report**
+   - Names of failing test cases
+   - Error messages and stack traces
+   - Summarize in a concise format
+
+---
+
+### 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.
+
+#### 1. Reference Existing Code (Consistency First)
+
+- **Reference targets**: Code with similar functionality or in the same layer within the project
+- **No introducing new patterns** — follow existing patterns first; only abstract when the same pattern repeats 3+ times and needs consolidation
+- **Follow framework Core/Base class patterns** — if the project has `.claude/rules/`, that hierarchy takes precedence
+
+#### 2. Independence and Regression Prevention
+
+- Verify that new code **does not break existing tests or functionality**
+- Manage side effects (shared state, global variables, file locks)
+- Use `git grep` before changes to understand the impact surface — check for unexpected callers
+
+#### 3. Locator and Identifier Stability (UI code only)
+
+<!-- [CUSTOMIZE] Can be removed for non-mobile QA / non-web QA projects -->
+
+- Do not depend on dynamically generated attributes (auto-generated id, timestamps in content-desc)
+- Avoid absolute XPath — fragile to structural changes
+- Consider i18n for text-based identifiers (multilingual projects)
+- If the project has `.claude/rules/LOCATOR_*` guides, those take precedence
+
+#### 4. Flakiness Risk Management
+
+- **No `time.sleep`** — use explicit waits (implicit/explicit wait) + condition-based polling
+- No unbounded waits without a timeout
+- Allow tolerance in screenshot-based assertions
+- Minimize assumptions about device/environment state (keyboard visibility, previous screen state, etc.)
+
+#### 5. Mandatory grep Before Design (Prevent Missing Own Assets)
+
+**Before** designing a new feature or pattern:
+
+1. grep for similar implementations in the project — reuse if already present
+2. grep learnings from sibling projects in the hub (e.g., `{FH_ROOT}/`) — prevent reinventing solutions already solved elsewhere
+3. Re-read the project's CLAUDE.md and rules/*.md — check for overlooked constraints
+
+Starting design with zero cited references is a warning signal for **missing own assets**. Always present at least 1 grep result before beginning design.
+
+---
+
+### Rule Hierarchy and Priority
+
+<!-- [CUSTOMIZE] Define rule sources and priority for your project -->
+
+**Priority when conflicts arise:**
+1. **Framework rules** — code patterns (non-negotiable)
+2. **Test design philosophy** — "what to test" (QA Identity, etc.)
+3. **Learned feedback** — rules based on user experience
+4. **Operational rules** — session backup, report analysis, and other work processes

package/templates/contrib_session.md

@@ -0,0 +1,34 @@
+---
+name: {session title — include the date}
+description: {one-line main achievement or pattern}
+type: contrib-session
+date: YYYY-MM-DD
+tags: [{related}, {tags}]
+contributor: {your-handle}
+---
+
+# {Session title}
+
+<!--
+Consent note: placing this file under tracks/_contrib/ is your consent to publish it.
+De-identify before opening the PR: no employer/internal-project/colleague names, no home paths,
+no internal domains, no credentials. The PR gate re-checks, but you scrub first.
+-->
+
+## Context
+
+{What project/situation this came from — de-identified. What problem you were working on.}
+
+## What happened / what was found
+
+{The work, the pattern, the failure, the fix. Concrete enough to be reusable — file/command level
+where possible, minus anything private.}
+
+## Why it matters beyond my project
+
+{The reusable claim: when would another operator hit this? What does this generalize to?}
+
+## Decisions / open questions
+
+- Decision: {key call made and why}
+- Open: {what remains unresolved — only if applicable}

package/templates/degrade_direction_scan.sh

@@ -150,9 +150,24 @@ for f in "${FILES[@]}"; do
     # S5 — the pipefail-fallback disarm: `... | grep -c ... || echo 0` appends a SECOND line under
     #   `set -o pipefail`, so the later `-gt` integer test becomes a bash error (= false) and the guard
     #   passes silently, with the error going only to stderr. Measured class, 2026-07-26.
+    #
+    # NARROWED 2026-07-28 after hand-verifying all 9 hits this repo produced: 9/9 were false
+    # positives, i.e. the probe was pure noise for its own class, and 100% FP trains dismissal of
+    # the one hit that will matter. Two distinct causes, both mechanically reproduced:
+    #   (a) `a || b || echo 0` was read as a pipeline — the old regex could anchor its `\|` on the
+    #       SECOND bar of the first `||`. No pipe exists, so no second line can ever be produced.
+    #       (Every `_mtime() { stat -c %Y … || stat -f %m … || echo 0; }` in the tree was flagged.)
+    #   (b) a real pipeline whose failing stage emits NOTHING (`… | jq -r … || echo 0`) — the
+    #       fallback then supplies the only line, which is exactly the intended behavior.
+    # The disarm needs BOTH a real pipe AND a final stage that emits regardless of upstream failure
+    # — a counter (`grep -c`, `wc`). That is the measured shape: `find … | grep -c . || echo 0`
+    # yields "9\n0" and the `-gt` guard goes silent. Verified as a known pair (both directions) in
+    # scripts/test_degrade_scan_shell_probes.sh; narrowing without that anchor would just trade a
+    # noisy probe for a blind one.
     while IFS= read -r m; do
-      emit "$f" "${m%%:*}" "S5:pipefail-fallback(sh)" "\`|| echo 0\` fallback on a pipeline — under \`set -o pipefail\` this yields a multi-line value whose integer comparison errors out and silently passes the guard; split the pipeline and sanitize to an integer"
-    done < <(grep -nE '\|[^|]+\|\|[[:space:]]*echo[[:space:]]+[\"'"'"']?0' "$f" 2>/dev/null \
+      emit "$f" "${m%%:*}" "S5:pipefail-fallback(sh)" "\`|| echo 0\` fallback on a pipeline ending in a counter (grep -c/wc) — that stage emits even when an upstream stage fails, so under \`set -o pipefail\` the value gains a SECOND line, the integer comparison errors out, and the guard passes silently; split the pipeline and sanitize to an integer"
+    done < <(grep -nE '[^|]\|[[:space:]]*([a-z]+[[:space:]]+)*(grep[^|]*-c|wc)[^|]*\|\|[[:space:]]*echo[[:space:]]+[\"'"'"']?0' "$f" 2>/dev/null \
+             | grep -vE '^[0-9]+:[[:space:]]*#' \
              | grep -vE '#[[:space:]]*noqa[:[:space:]]*degrade')
   fi