@chrono-meta/fh-gate 1.4.73 → 1.4.74

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/goal-quench-hook-setup.md

@@ -0,0 +1,152 @@
+# goal-quench Stop Hook Setup
+
+Add the following to your project's `.claude/settings.json` to enable the goal-quench Stop hook:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'f=\".claude/goal-quench.active\"; [ -f \"$f\" ] && echo \"\\n[goal-quench] /goal finished. Running quality verification...\" && cp \"$f\" \".claude/goal-quench.pending\" && rm -f \"$f\" || true'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Add to your project's `.gitignore`:
+
+```
+.claude/goal-quench.active
+.claude/goal-quench.pending
+```
+
+## How it works
+
+1. `/goal-quench` (Phase 1) writes `.claude/goal-quench.active` with scope + budget info
+2. User runs `/goal [condition]`
+3. When `/goal` finishes → Stop hook fires → detects `.active` → copies to `.pending` → removes `.active`
+4. Next Claude response: detects `.pending` → auto-runs `pipeline-conductor --quick` → cleans up
+
+## Merge with existing settings.json
+
+If you already have a `settings.json`, merge the `hooks.Stop` array:
+
+```json
+{
+  "permissions": { ... your existing permissions ... },
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "... your existing stop hook command if any ..." }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'f=\".claude/goal-quench.active\"; [ -f \"$f\" ] && echo \"\\n[goal-quench] /goal finished. Running quality verification...\" && cp \"$f\" \".claude/goal-quench.pending\" && rm -f \"$f\" || true'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Manual Apply (forge-harness)
+
+A pre-merged `settings.json` for the forge-harness repo is available at:
+
+```
+templates/goal-quench-settings-merged.json
+```
+
+To apply it manually (one command, run from the forge-harness repo root):
+
+```bash
+cp templates/goal-quench-settings-merged.json .claude/settings.json
+```
+
+This file preserves all existing `permissions` and `enabledPlugins` from the current `.claude/settings.json` and adds the `hooks.Stop` section.
+
+Note: `.claude/settings.json` is gitignored (local-only file), so this copy must be done manually on each machine.
+
+## Verification Steps
+
+After applying the hook, verify the full pipeline with these steps:
+
+### Step 1 — Start a goal-quench session
+
+Run the goal-quench skill to write the `.active` file:
+
+```
+/goal-quench
+```
+
+This should create `.claude/goal-quench.active` with scope + budget metadata.
+
+Confirm:
+
+```bash
+ls -la .claude/goal-quench.active
+cat .claude/goal-quench.active
+```
+
+### Step 2 — Run a goal
+
+```
+/goal <your completion condition here>
+```
+
+Example: `/goal all acceptance tests pass`
+
+### Step 3 — Verify Stop hook fired
+
+When the `/goal` task finishes (Claude stops responding), check that:
+
+```bash
+# .active should be gone
+ls .claude/goal-quench.active 2>/dev/null && echo "ERROR: .active still exists" || echo "OK: .active removed"
+
+# .pending should exist
+ls .claude/goal-quench.pending && echo "OK: .pending created" || echo "ERROR: .pending missing"
+
+# .pending content
+cat .claude/goal-quench.pending
+```
+
+### Step 4 — Verify auto-trigger in next response
+
+Send any message to Claude in the same session. The next response should:
+1. Detect `.claude/goal-quench.pending`
+2. Auto-run `pipeline-conductor --quick` (or equivalent quality verification)
+3. Remove `.pending` after completion
+
+If the skill is not installed, Claude will report the pending file and ask how to proceed.
+
+### Step 5 — Cleanup check
+
+After the verification round completes:
+
+```bash
+ls .claude/goal-quench.* 2>/dev/null || echo "OK: all state files cleaned up"
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `.active` not created after `/goal-quench` | Skill not writing the file | Check SKILL.md `goal-quench` for file write step |
+| `.active` still present after session stop | Hook not installed / not firing | Re-run `cp templates/goal-quench-settings-merged.json .claude/settings.json`, restart Claude Code |
+| `.pending` created but no auto-trigger | pipeline-conductor not installed | Install or implement the skill; Claude will report the pending state |
+| Hook fires on every stop (not just goal-quench) | Expected — `[ -f "$f" ]` guard prevents false triggers when `.active` absent |

package/templates/starter_profile.md

@@ -0,0 +1,83 @@
+# FH Starter Profile — Mode C (plugin only, no clone)
+
+> **The one opinionated front door.** FH has 33 skills and a full hub you can clone — but you
+> don't need any of that to get value today. This profile is the *single strong default*: one
+> install command, a curated first-five skills, and a zero-install governance gate. Pick up the
+> rest later if you want it.
+>
+> This is **Mode C** (see `knowledge/shared/rules/modes_and_value.md`): you install the plugin/skills only,
+> you do **not** clone the hub. That trade-off is spelled out under *What Mode C does not include*.
+
+---
+
+## 1. Install — one command
+
+**Prerequisite**: Claude Code CLI (`claude --version`).
+
+```bash
+claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
+claude plugin install -s user fh-meta@forge-harness
+```
+
+That's it — no clone, no shell hooks, no machine setup. Open Claude Code in *your own* project and
+the skills are available as slash commands.
+
+```bash
+cd ~/your-project && claude
+```
+
+## 2. Governance gate — zero install (no plugin needed either)
+
+The core FH value — **"pass → accelerate"**: code that clears the gate ships faster. You can run it
+on any file with nothing installed but `npx`:
+
+```bash
+npx --package @chrono-meta/fh-gate fh-gate                    # default: Claude backend
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-gate   # Codex backend
+# → FH_GATE_VERDICT: PASS | PENDING | BLOCKED | ESCALATE
+```
+
+This wraps any coding agent (Claude, Codex) as a post-generation governance gate. It is the single
+highest-leverage thing to try first if you only do one thing.
+
+## 3. The opinionated first five (start here, ignore the other 28)
+
+A new user dropped into 33 skills stalls. These five cover the common path; reach for the rest only
+when a real need shows up.
+
+| Skill | Run it when | One line |
+|---|---|---|
+| `/plugin-recommender` | "what tools should I even use?" | Discovery — classifies tools, checks token cost |
+| `/context-doctor` | session feels slow / token-heavy | Generates `.claudeignore`, flags large files, `/clear` timing |
+| `/harness-doctor` | "is my setup sane?" | L1–L4 structure diagnosis + prescription |
+| `/goal-quench` | before executing a risky/long task | Gated execution — the acceleration gate in skill form |
+| `/frontier-digest` | "what's new out there?" | External/frontier trend cross-reference |
+
+Natural language works too — you don't need to memorize slash commands. "manage my context",
+"recommend a plugin", "check my harness structure" route to the same skills.
+
+## 4. What Mode C does *not* include (honest boundary)
+
+Plugin-only install gives you **Layer 2 (the skills)**. It does **not** give you **Layer 1**, which
+only activates when you clone the hub (Mode A/B):
+
+- **No active onboarding cascade** — no greeting-triggered 5-skill auto-run. You invoke skills yourself.
+- **No acceleration baseline** — no zshrc notification hook, no sentinels, no weekly-audit schedule,
+  no 4-axis pre-commit gate. Those are hub-internal infra and are deliberately not shipped to Mode C.
+- **No automatic harness signals** — history accumulation happens on *your* project side; FH won't
+  prompt you. (FH absorbs Mode-C contributions through issue monitoring + PR cadence, not a daemon.)
+
+If you later want Layer 1, clone the hub and run `/install-wizard` — the full path. The README's
+"Get started in 2 minutes" covers it.
+
+## 5. Want to go further?
+
+- **Clone the hub** (Mode A/B) → persistent cross-project knowledge, `tracks/`, the compounding loop.
+- **Contribute back** → a Mode-C PR is exactly the external validation FH is looking for. Open an
+  issue or PR on `chrono-meta/forge-harness`.
+
+---
+
+*Design note: this profile follows the frictionless-distribution + opinionated-front-door pattern
+seen in field harnesses like [gstack](https://github.com/garrytan/gstack) — a single strong default
+as the public entry point, full meta-flexibility kept behind it.*

package/templates/temper_check.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# temper_check.sh — Wave-T (Temper) step T-1: complexity delta of a quench.
+# Measures how much complexity a steel-quench ADDED to a markdown asset
+# (pre-quench baseline → post-convergence). It is a MEASUREMENT, not a detector
+# (don't-overbuild guard: no judgment engine here — T-3 verdict is human/LLM).
+#
+# Usage:  temper_check.sh <repo> <file-rel-path> <pre-quench-ref> [<post-ref>]
+#   <post-ref> default = working tree.
+# See plugins/fh-meta/skills/steel-quench/SKILL.md §Wave-T.
+set -euo pipefail
+
+repo="${1:?repo path}"; file="${2:?file rel path}"; pre="${3:?pre-quench ref}"; post="${4:-}"
+
+metrics() {  # reads text on stdin → "lines sections steps tables fences crossrefs"
+  local t prose; t="$(cat)"
+  # sections/steps/tables count PROSE only — lines inside ``` fences are code
+  # (bash comments `# ...` would otherwise inflate Δsections; found run #4, install-wizard)
+  prose="$(printf '%s\n' "$t" | awk '/^[[:space:]]*```/{f=!f;next} !f')"
+  local lines sections steps tables fences crossrefs
+  lines=$(printf '%s\n' "$t" | wc -l | tr -d ' ')
+  sections=$(printf '%s\n' "$prose" | grep -cE '^#{1,6} ' || true)
+  steps=$(printf '%s\n' "$prose" | grep -cE '^[[:space:]]*([0-9]+\.|[-*] )' || true)
+  tables=$(printf '%s\n' "$prose" | grep -cE '^\|' || true)
+  fences=$(( $(printf '%s\n' "$t" | grep -c '```' || true) / 2 ))
+  crossrefs=$(printf '%s\n' "$t" | grep -oE '\]\(|\[\[' | wc -l | tr -d ' ')
+  echo "$lines $sections $steps $tables $fences $crossrefs"
+}
+
+pre_txt=$(git -C "$repo" show "$pre:$file")
+if [ -n "$post" ]; then post_txt=$(git -C "$repo" show "$post:$file"); else post_txt=$(cat "$repo/$file"); fi
+
+read -r l0 s0 p0 t0 f0 x0 <<<"$(printf '%s' "$pre_txt"  | metrics)"
+read -r l1 s1 p1 t1 f1 x1 <<<"$(printf '%s' "$post_txt" | metrics)"
+
+printf '\n=== Wave-T complexity delta — %s ===\n' "$file"
+printf 'baseline: %s   post: %s\n\n' "$pre" "${post:-<working>}"
+printf '%-12s %6s %6s %8s\n' metric pre post Δ
+for row in "lines $l0 $l1" "sections $s0 $s1" "steps $p0 $p1" "tables $t0 $t1" "fences $f0 $f1" "cross-refs $x0 $x1"; do
+  set -- $row; printf '%-12s %6s %6s %+8d\n' "$1" "$2" "$3" "$(( $3 - $2 ))"
+done
+
+dx=$(( x1 - x0 )); dp=$(( p1 - p0 ))
+printf '\n-- T-3 heuristic flags (review, not auto-reject) --\n'
+[ "$dx" -gt "$dp" ] && printf '  ⚠ Δcross-refs(%+d) > Δsteps(%+d): quench added wiring, not function?\n' "$dx" "$dp" || true
+[ "$(( s1 - s0 ))" -gt 0 ] && printf '  ⚠ %+d new section(s): confirm each fixes a flaw, not just defends a Wave finding\n' "$(( s1 - s0 ))" || true
+printf '\nNext: run harness-doctor on post asset for absolute tier (T-2), then record τ verdict (PASS / FAIL + named construct)\n'