@chrono-meta/fh-gate 1.4.76 → 1.4.78

package/knowledge/shared/harness-core/agents_md_runtime_details.md

@@ -0,0 +1,233 @@
+# AGENTS.md Runtime Details
+
+> **Load: on demand.** `AGENTS.md` is the always-loaded runtime entry point. Read only the section
+> named by its imperative pointer.
+
+## §Architecture-and-output-routing
+
+forge-harness has two distinct layers:
+
+| Layer | Contents | Compatibility |
+|---|---|---|
+| **Methodology** | `tracks/`, `knowledge/`, `SKILL.md` documents, session protocols | Model-agnostic |
+| **Automation** | Plugin agents, hooks, slash commands, `CLAUDE.md` rules | Claude Code-native |
+
+FH agents ship under `plugins/*/agents/` through the plugin channel. `.claude/agents/` is the
+field-project local/override slot, not FH's shipping location. Skills straddle both layers: their
+methodology is portable, while their automatic invocation is Claude-native.
+
+The methodology layer is Codex-compatible beta. Gemini, Codex, and other runtimes can apply it by
+replacing hooks and native dispatch with manual invocation.
+
+Directory names do not determine publication residency:
+
+| Content | Default destination |
+|---|---|
+| Reusable methodology, docs, skills, public guidance, polished external conclusions | Public mirror: `knowledge/`, `plugins/`, `docs/` |
+| Raw signals, operator observations, private validation, handoffs, paper drafts, PR-background reasoning | Private companion store or local-only |
+
+In a workspace pairing a public mirror with a private companion store, preserve repository ownership
+even when both are locally available. Treat observational or operator-specific material as
+private-first and promote only the polished result.
+
+## §Sidecar-routing-and-waiting
+
+A sidecar is a capability-routing layer, not a second harness or co-governor. Gemini/Antigravity is
+suited to breadth and multimodal work. Codex's primary FH role is repo-grounded audit: file reads,
+source-close grep, diff/patch review, gate execution, and phantom/backtrace. A Codex session with
+Browser or Chrome connectors may also take live web-flow automation.
+
+Sidecars are Bash/adapter invocations coordinated inline; they bypass plugin agent dispatch and this
+registry. Route Codex to repo-grounded audit by default, not breadth, discovery, or design-depth work.
+
+After dispatch, wait mechanically:
+
+```bash
+printf '%s' "$prompt" | bash scripts/sidecar_wait.sh out.txt 900 -- codex exec -m gpt-5.5 -
+```
+
+Interpret only the typed verdict:
+
+| Verdict | Meaning |
+|---|---|
+| `SIDECAR_VERDICT=COMPLETE exit=0 bytes=N` | The process completed; read the output file |
+| `SIDECAR_VERDICT=TIMEOUT waited=Ns bytes=N` | The process is still alive; this is not a result |
+| `SIDECAR_VERDICT=EMPTY exit=0` | The completed process returned no content |
+
+A live process and a completed empty process can both show a zero-byte file. Never judge state by
+file inspection. Canonical authority and waiting doctrine:
+`knowledge/shared/harness-core/multi_model_sidecar_strategy.md §Runtime Authority` and
+`plugins/fh-meta/skills/auto-decorrelation/SKILL.md §S-1b`.
+
+## §Mandatory-checklist-procedures
+
+### FH asset changes
+
+Read `.claude/rules/fh_4axis_gate.md` before changing an FH asset. It defines the mandatory
+Backward, Adversarial, Forward, and Record axes, marker fields, lightweight exception, and
+substantive carve-out. The pre-commit hook blocks commits that lack required evidence.
+
+When running `templates/regression_guard.sh`, prefer `REGRESSION_GUARD_RESULT_FILE=<path>` and read
+`result=pass|review|block|skip|error`. Without that environment variable, read the typed
+`REGRESSION_GUARD_RESULT=` stdout line. Exit 0 alone cannot distinguish PASS from SKIP.
+
+### Company residency
+
+Keep raw company source, secrets, hostnames, internal names, stack traces, and unredacted findings
+local. Outbound requests may contain only a sanitized summary. An exception requires explicit
+operator approval plus a gitignored audit note. Canonical procedure:
+`CLAUDE.md §Field-Harness Diagnostic`.
+
+### Author exposure
+
+Before completing a material deliverable, use `agent-composer §Author-Exposure Table`:
+
+| Blind spot | Lens |
+|---|---|
+| Cold entry | `beginner` |
+| Everyday friction | `main-player` |
+| Outside currency | `expert` |
+| Optimistic self-verification | `challenger` plus cross-family evidence |
+| Rebuilding an existing asset | `fact-checker` |
+| Ungrounded numbers or references | `phantom-quench` |
+| Unclear | `challenger` |
+
+Run an agent lens through `fh-run` or a direct `codex exec` reading the agent spec. The result remains
+evidence for the governor to source-close.
+
+### Intent marshaling
+
+For ordinary work requests, read
+`knowledge/shared/harness-core/intent_marshaling_general_work.md` before applying its ladder or when a
+capability gap appears. The required loop is: restate deliverable and doneness; enumerate installed
+and mapped capability with trust tiers; compose and run reversible FH-native work; cite the scan
+before declaring a gap; search the internal registry, then external capability, then synthesize
+in-session; apply the Author-Exposure check to material output.
+
+Marshaling never upgrades trust. Non-FH sibling `ask-tier` capability remains propose-only.
+Send, post, deploy, delete, and payment retain their own gates. Installing external capability routes
+to `plugin-recommender` HITL; persisting a synthesized skill routes to the New-Skill gate.
+
+### Measurement integrity
+
+Read `knowledge/shared/harness-core/measurement-integrity-checklist.md` before relying on a scan,
+checker, or metric. Demonstrate that the instrument separates one known-positive target from one
+known-clean target, and inspect at least one hit before stating a count. Report no-target and
+mid-run failure as `UNMEASURED`. Treat all-pass or all-fail output as an instrument warning.
+
+### Irreversible surfaces
+
+The Pre-Publish and Destructive-Op gates in `CLAUDE.md` fire on intent rather than file paths.
+Read the relevant gate before any publish, delete, or history rewrite. The pre-push hook provides
+only the git-side mechanical backstop.
+
+## §Invocation-patterns
+
+### Single agent
+
+Ask for the required lens directly, for example: "Analyze this SKILL.md for structural flaws before
+I commit it." Claude may description-dispatch `quench-challenger`; a non-Claude runtime invokes the
+agent through the adapter.
+
+### Parallel independent work
+
+Dispatch two or more agents concurrently only when their tasks are independent, such as a
+`fact-checker` duplicate scan and a `persona-innovator` naming-gap scan. The orchestrator integrates
+their evidence after both finish.
+
+### Wave composition
+
+For complex dependent work, use `agent-composer`: Wave 0 reconnaissance, Wave 1 execution, then
+Wave 2 synthesis.
+
+## §Codex-entry-points
+
+Read a skill workflow directly:
+
+```bash
+cat plugins/fh-meta/skills/steel-quench/SKILL.md
+```
+
+Prefer the runtime adapter:
+
+```bash
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run \
+  --skill steel-quench \
+  --file path/to/artifact.md
+
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run \
+  --agent fh-commons:quench-challenger \
+  --file path/to/artifact.md
+```
+
+Direct headless fallback:
+
+```bash
+cat plugins/fh-meta/skills/steel-quench/SKILL.md path/to/artifact.md \
+  | codex exec -m gpt-5.5 -
+```
+
+`codex exec -m gpt-5.5 -` reads stdin headlessly. Interactive `npx @openai/codex` requires a TTY and
+is not the headless substitute.
+
+## §Compatibility-tiers
+
+| Tier | Definition | Examples |
+|---|---|---|
+| **M1 — Full** | No Claude-native dependency | `token-budget-gate`, `asset-placement-gate`, `phantom-quench`, `deep-clarify`, `convergence-loop` |
+| **M2 — Partial** | Core works; native agent/slash-command steps need adaptation | `deliberation`, `steel-quench`, `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop` |
+| **M3 — Claude-only** | Requires a Claude hook or session-scoped dispatch | `goal-quench`, `hub-cc-pr-reviewer`, `install-wizard` |
+
+**Which phase needs adapting** — the operative half of the M2/M3 rows. Without this a tier label
+tells a non-Claude runtime that a skill is "partial" but not *where* to intervene, which is the only
+thing it can act on. (Restored 2026-07-30 during review of the salience split: the rows survived the
+move, these per-skill cues did not, and they existed in no other file.)
+
+| Skill | Runs unchanged | Needs substitution |
+|---|---|---|
+| `steel-quench` | Waves 1–3 | the `quench-challenger` agent step |
+| `harvest-loop` | the git-scan phase | PR auto-proposal |
+| `deliberation` | proposal/synthesis structure | Mediator and Jury agent steps |
+| `goal-quench` (M3) | — | Phase 3 depends on a Claude Stop hook |
+| `hub-cc-pr-reviewer` (M3) | — | needs Claude session context |
+| `install-wizard` (M3) | — | writes `settings.json` |
+
+For M2, replace `Agent(subagent_type=...)` and slash-command steps with `fh-run` or direct
+`codex exec` reading the relevant spec.
+
+Use Codex native goal/session control when available. FH's portable role is the post-goal quality
+gate (`fh-gate`). `fh-goal` is for non-interactive one-shot runs followed automatically by
+`fh-gate`; it does not replace native goal control.
+
+## §Beta-removal
+
+| Condition | Status |
+|---|---|
+| Known-limitations document published at `docs/codex-compat.md` | Done |
+| At least 5 externally validated M1 skill runs from non-authors | Pending |
+| At least 1 external Codex user confirms methodology reproduction | Pending |
+| README badge removes `beta` | Blocked on the external conditions |
+
+Internal author validation does not satisfy the external conditions. The author validated
+`phantom-quench` against a phantom-seeded fixture and `asset-placement-gate` against a duplicate-skill
+proposal on 2026-06-04. See `docs/codex-compat.md` for limitations and validation details.
+
+Report external validation through an issue on `chrono-meta/forge-harness` with the
+`codex-validation` label.
+
+## §Adding-agents
+
+Before adding an agent:
+
+1. Run `asset-placement-gate` and confirm the role does not duplicate an existing asset.
+2. Use a plain description with no self-marketing language.
+3. Define at least one explicit `Done When` condition.
+4. Provide at least three natural-language trigger examples.
+5. Make the agent independently executable or document its dependencies.
+6. Add the canonical spec under the correct `plugins/*/agents/` directory.
+7. Synchronize `AGENTS.md` and `.claude/registry/agent_cards.json`.
+
+Before commit, apply `.claude/rules/fh_4axis_gate.md §FH Improvement 4-Axis Auto-Gate` and read
+`knowledge/shared/rules/operations.md §Sub-agent Operations`. After at least two weeks of use,
+strengthen an agent when accepted invocations are at least 60%; redefine or deprecate it when
+rejected invocations are at least 40%.

package/knowledge/shared/harness-core/multi_model_sidecar_strategy.md

@@ -716,7 +716,7 @@ Missing any layer = compression risk. (Path conventions adapt per project — se
 ## References
 
 - `README.md §Architecture — 2-layer design` — sidecar note in Automation layer section
-- `AGENTS.md §2-Layer Architecture Context` — sidecar note distinguishing Bash invocation from agent dispatch
+- `knowledge/shared/harness-core/agents_md_runtime_details.md §Sidecar-routing-and-waiting` — sidecar note distinguishing adapter invocation from agent dispatch
 - FH paper (Zenodo DOI: 10.5281/zenodo.20397566, arXiv: submit/7657304) — harness-as-durable-layer thesis
 - A sister-harness `sidecar-orchestrator` SKILL.md (2026-06-01) — gh copilot + corporate endpoint + 3-tier fallback + 3-layer persistence
 - arXiv:2605.26302 AgingBench — compression aging defense rationale

package/knowledge/shared/learnings/subagent_invocations_log.yaml

@@ -580,3 +580,17 @@
     withheld by a "standing session instruction"; the operator pointed out they never said that — it is
     session-level SYSTEM configuration, and the wording blurred the source. Corrected in the markers and
     here. The operator then explicitly requested the agent, which satisfies the configured exception.
+- date: 2026-07-30
+  agent: fh-meta:challenger
+  task: "Axis-2 adversarial review of the per-node floor check + install-wizard SessionStart gap (5 rounds + 1 confirmation)"
+  mode: isolated Agent, opus, same-family (no cross-family sidecar reachable — disclosed in the marker, not silently passed)
+  outcome: accepted
+  evidence: "S-grade 6 → 5 → 4 → 2 → 0, CONVERGED. Caught, among others: a false 'tracked settings.json survives a clone' claim; two of this repo's own gate scripts already red; a group-level hook merge that deleted a user's own hook; a broken machine going permanently silent after one report; foreign (husky) hooks counted as FH floors; and a Mode D applicability gate that silenced the exact incident that started the work."
+  note: "Its standing prescription — write the known-pair lanes BEFORE the fix — was adopted at round 4 and ended three consecutive rounds of fix-induced regressions (0 in rounds 4, 5, confirmation). One prescription was REJECTED with measured grounds (widening the package-coverage predicate: 25 new hits, 24 artifacts), and the challenger then correctly showed my rejection rationale was itself circular; the file now labels that check UNQUANTIFIED."
+- date: 2026-07-30
+  agent: general-purpose (Sonnet-pinned target-tier sim)
+  task: "Blind fresh-session simulation: would a new machine end up correctly wired if the user opens with a task, not a greeting?"
+  mode: isolated Agent, sonnet, run BEFORE the fixes
+  outcome: accepted
+  evidence: "Two findings, both closed. (1) The node check was unreachable on the fresh-machine case because it lived in a gitignored registration — drove the split into scripts/fh_node_check.sh + a tracked snippet. (2) The wizard wrote a literal '<your-store>' placeholder and reported success, leaving a dead hook — the real BE_DIR is now baked in at write time."
+  note: "Sonnet tier was the right instrument here: both findings are about instructions being followed literally, which is exactly where a weaker tier diverges from an author's intent."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrono-meta/fh-gate",
-  "version": "1.4.76",
+  "version": "1.4.78",
   "description": "FH runtime adapters — run FH governance, skills, and agents via Claude or Codex with machine-parseable gates.",
   "license": "MIT",
   "keywords": [
@@ -106,6 +106,7 @@
     "scripts/test_memory_link_check.sh",
     "scripts/memory_nearcheck.py",
     "scripts/sidecar_wait.sh",
+    "scripts/test_sidecar_wait_stdin.sh",
     "scripts/test_session_close_lanes.sh",
     "scripts/test_card_drift_probe.sh",
     "scripts/universal_guard_check.sh",
@@ -124,6 +125,11 @@
     "README.md",
     "README.ko.md",
     "README.zh.md",
-    "README.ja.md"
+    "README.ja.md",
+    "scripts/fh_node_check.sh",
+    "templates/settings.SessionStart.snippet.json",
+    "scripts/test_node_check_lanes.sh",
+    "scripts/sidecar_calibrate.sh",
+    "scripts/test_sidecar_calibrate_lanes.sh"
   ]
 }

package/plugins/fh-commons/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fh-commons",
-  "version": "1.4.76",
+  "version": "1.4.78",
   "engines": {
     "claudeCode": ">=1.0.0"
   },

package/plugins/fh-meta/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fh-meta",
-  "version": "1.4.76",
+  "version": "1.4.78",
   "engines": {
     "claudeCode": ">=1.0.0"
   },

package/plugins/fh-meta/skills/install-doctor/SKILL.md

@@ -48,6 +48,94 @@ claude --version 2>/dev/null || echo "Claude Code not installed"
 
 **⚠️ When Bedrock routing confirmed**: Request AWS quota increase (TPM/RPM increase) or raise LiteLLM `max_input_tokens`, then retry. Fundamental solution is switching to direct Anthropic API access.
 
+### Node floor check — run on EVERY machine, not once per user
+
+A user's context (companion store, memory, session card) travels between machines; **the machine's
+own setup does not**. A rich context makes a fresh laptop read as "already configured", so the two
+mechanical floors below must be checked per node — this is the check `scripts/fh_node_check.sh`
+points at when it reports a missing floor at turn 0.
+
+```bash
+# HUB_DIR — the same variable the hook scripts use. Do NOT invent a second name (an earlier draft
+# read FH_DIR, which nothing sets, so an operator with HUB_DIR set would have been silently told
+# about a different repo).
+FH="${HUB_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+# ① git-side floor. Probe the EXECUTABLE HOOK, not the config key — `core.hooksPath` unset is a
+#    normal, working install when hooks sit in .git/hooks, and a set-but-empty path is a broken
+#    install that the key alone reports as fine. Both directions are wrong; the file is the truth.
+#    Resolve the directory with `git rev-parse --git-path` rather than assembling "$FH/.git/hooks":
+#    in a LINKED WORKTREE `.git` is a file, so the assembled path does not exist and every hook
+#    reads as missing (verified: a worktree with working hooks reported ❌❌ under the old form).
+#    Same resolution the script uses — one predicate, not two.
+# --path-format needs git >= 2.31; on older git fall back to the RELATIVE --git-path form resolved
+# against the toplevel, never to a hand-built "$FH/.git/hooks" (which is the worktree bug above).
+HD="$(git -C "$FH" rev-parse --path-format=absolute --git-path hooks 2>/dev/null)"
+if [ -z "$HD" ]; then
+  _rel="$(git -C "$FH" rev-parse --git-path hooks 2>/dev/null || echo .git/hooks)"
+  case "$_rel" in /*) HD="$_rel" ;; *) HD="$(git -C "$FH" rev-parse --show-toplevel 2>/dev/null || echo "$FH")/$_rel" ;; esac
+fi
+for h in pre-commit pre-push; do
+  if [ -x "$HD/$h" ]; then echo "✅ $h executable ($HD)"
+  else echo "❌ $h MISSING or not executable at $HD — that gate is not running on this node"; fi
+done
+
+# ② turn-0 load floor (Mode D only): the companion-load hook. Its registration lives in the
+#    GITIGNORED settings.local.json, so it does NOT survive a re-clone — hence a per-node check.
+#    Parse the JSON and match the SCRIPT NAME inside hooks.SessionStart — not a bare grep for the
+#    key. settings.json also carries a SessionStart entry (fh_node_check), so keying on the key
+#    alone passes on a machine where the companion load is absent; and a plain substring grep also
+#    hits commented-out lines, other hook events, and permission strings. Same predicate the script
+#    uses — two predicates reading one state differently is how a result leaks silently.
+#    Applicability gate FIRST, and keyed the same way the script keys it: a Mode D user is one with
+#    an exported BE_DIR, or a CLAUDE.local.md that MENTIONS a companion binding — NOT one who merely
+#    HAS a CLAUDE.local.md (that is Claude Code's standard local-override file; anyone may keep one),
+#    and NOT one who has a settings.local.json (gitignored, so a fresh clone lacks it — and a fresh
+#    clone with a full companion store is the exact case this must not silence). The vocabulary
+#    covers every backend the wizard documents (vault · gbrain · *-be repo), because an FH-flavoured
+#    regex would silence two first-class backends. It is a MENTION test, not semantic: "I do not use
+#    a companion store" also matches, and that over-match costs one informational line — the cheap
+#    direction, since the expensive direction is silence.
+if { [ -n "${BE_DIR:-}" ] && [ -d "$BE_DIR" ]; } \
+   || { [ -f "$FH/CLAUDE.local.md" ] && grep -qiE 'BE_DIR|companion[ -]store|컴패니언|vault|gbrain|obsidian' "$FH/CLAUDE.local.md"; }; then
+  python3 - "$FH" <<'PY'
+import json, os, sys
+hub = sys.argv[1]
+for p in (os.path.join(hub, ".claude", "settings.local.json"),
+          os.path.expanduser("~/.claude/settings.json")):
+    try: groups = json.load(open(p)).get("hooks", {}).get("SessionStart", [])
+    except Exception: continue
+    if any("fh_session_load" in h.get("command", "")
+           for g in groups for h in g.get("hooks", [])):
+        print("✅ companion-load SessionStart registered"); sys.exit(0)
+print("❌ companion-load SessionStart MISSING — freshness + env-delta do not fire at turn 0")
+PY
+else
+  echo "N/A  companion-load SessionStart (not a Mode D setup — no companion store configured)"
+fi
+```
+
+**Bootstrap note — honest scope**: `scripts/fh_node_check.sh` (the check that *reports* a missing
+floor at turn 0) ships with the clone, but its **registration does not**: every
+`.claude/settings*.json` path in this repo is gitignored (confirm with `git check-ignore -v
+.claude/settings.json` — don't trust a line number, they move), so no SessionStart entry can be
+tracked. The tracked artifact is `templates/settings.SessionStart.snippet.json`; `/install-wizard`
+merges it. A user who never runs the wizard still gets no turn-0 signal — that residual is reduced,
+not closed, and this check item is the backstop for it.
+
+**Emission model** (so the output is read correctly): a **missing floor is reported every session**
+until it is fixed — it is a persistent condition, not an event. A healthy machine is silent. So
+seeing this banner twice is not a bug, and seeing it once then never again means it was an *event*
+line (identity change / infra delta), not a floor complaint.
+
+**Fix for either ❌**: re-run `/install-wizard` (it registers both — `install-wizard/SKILL_detail.md`
+§Mode-D-Companion-Setup step 3 and the 4-axis gate block), or apply the two commands it uses directly.
+
+**Why this is a check item and not a note** (measured 2026-07-30): a second machine held the full
+companion store and memory, yet ran with **both** SessionStart hooks absent. Nothing surfaced it —
+the miss was found by accident. A weak tier is where this bites hardest: a mechanized floor is
+tier-independent, while the prose it replaces is exactly what a weaker model drops first.
+
 ---
 
 ## Step 1. Existing Asset Inventory

package/plugins/fh-meta/skills/install-wizard/SKILL.md

@@ -88,7 +88,7 @@ All 3 → Proceed in order: Step 0-B (token injection) → Step 0 (environment c
 
 **Mode D detected (FH developer/researcher)**: Guide companion-store setup before Step 1. **Ask the backend first** — the store is a role (durable private home for artifacts), not a fixed `*-be` git repo: Obsidian vault / gbrain-ingest / `*-be` git repo (default) all qualify. Do not assume the repo path.
 
-**Set the store up as a queryable WIKI, not an empty folder** — the store earns its value when the agent can *read it well*, so the scaffold includes: an `INDEX.md` wiki-home (**the `CATALOG.md` read-first pattern applied to the store** — named INDEX to avoid two CATALOG.md across the public + private repos; section map + **read-time-derived** pointers, never hand-maintained placeholders that rot) · session-start read wiring the AI **idempotently adds** to `CLAUDE.local.md` (grep-guarded against duplication: read INDEX → open result/signal files newer than the session card, not only handoffs) · the Raw/Wiki/Conversation ingest axis (`sync_push_protocols.md`). The git `*-be` form is the **default within the no-existing-store branch** (it stays an ask-first choice — see the backend question; SKILL.md does not override the detail file's neutral ordering), recommended *there* because for a non-visual user *observability is the agent querying the wiki* (INDEX + session-start read) — git-versioned, agent-native (grep/Read), no cloud egress; FH's answer to its weak Observability layer. Obsidian (graph-view = the visual observability surface) and cloud are equal options when the user already runs one. **Salience caveat**: the session-start read is prose in `CLAUDE.local.md` (no SessionStart hook) — on a weak tier it may silently not fire; accepted, revisit if a target-tier sim measures a miss.
+**Set the store up as a queryable WIKI, not an empty folder** — the store earns its value when the agent can *read it well*, so the scaffold includes: an `INDEX.md` wiki-home (**the `CATALOG.md` read-first pattern applied to the store** — named INDEX to avoid two CATALOG.md across the public + private repos; section map + **read-time-derived** pointers, never hand-maintained placeholders that rot) · session-start read wiring the AI **idempotently adds** to `CLAUDE.local.md` (grep-guarded against duplication: read INDEX → open result/signal files newer than the session card, not only handoffs) · the Raw/Wiki/Conversation ingest axis (`sync_push_protocols.md`). The git `*-be` form is the **default within the no-existing-store branch** (it stays an ask-first choice — see the backend question; SKILL.md does not override the detail file's neutral ordering), recommended *there* because for a non-visual user *observability is the agent querying the wiki* (INDEX + session-start read) — git-versioned, agent-native (grep/Read), no cloud egress; FH's answer to its weak Observability layer. Obsidian (graph-view = the visual observability surface) and cloud are equal options when the user already runs one. **Mechanical floor (corrected 2026-07-30)**: the `CLAUDE.local.md` read is prose, so the wizard **also registers the `SessionStart` hooks** (`fh_session_load.sh` companion freshness + `fh_env_delta_scan.sh` env-delta) into the gitignored `settings.local.json` — see `SKILL_detail.md §Mode-D-Companion-Setup` step 3. The earlier text here claimed no such hook existed and marked the gap "accepted"; both were wrong, and a clean second-machine install measured the miss (turn-0 load skipped on a task-first entry, on Opus). Prose is the layer **over** the floor, never the floor.
 
 **Beyond Mode D (not forced)**: a non-developer user who accumulates their own context into FH and keeps no separate local store benefits too — but since accumulation is unobservable at *first* install, surface this offer only on a **re-run where FH-written artifacts already exist** (e.g. non-empty `tracks/*/session_*.md`), not preemptively at first setup. A user with a local store, or with no FH artifacts, is not prompted.
 

package/plugins/fh-meta/skills/install-wizard/SKILL_detail.md

@@ -93,8 +93,71 @@ IDX
 WIRING="At session start: read \$BE_DIR/INDEX.md first; then ls -t paper-signals/ handoff/ digests/ and open anything newer than the session card (card=pointer, store commit=truth) — not only handoffs."
 grep -qF "read \$BE_DIR/INDEX.md first" "$HUB_DIR/CLAUDE.local.md" 2>/dev/null \
   || printf '\n## Companion-store session-start read\n%s\n' "$WIRING" >> "$HUB_DIR/CLAUDE.local.md"
+
+# 3. MECHANICAL FLOOR over that prose — register the SessionStart hooks (REQUIRED, not optional).
+#    WHY: step 2 writes an INSTRUCTION into CLAUDE.local.md. An instruction is salience: on task-first
+#    entry (the user's first message is a task, so the onboarding menu is correctly suppressed) or on a
+#    weaker tier, it silently does not fire and the session runs on stale local state. The two hooks
+#    below fire BEFORE turn 0 regardless of what the user types.
+#      - fh_session_load.sh   → companion freshness (this section's own load)
+#      - fh_env_delta_scan.sh → undeployed-sibling-repo discovery (CLAUDE.md claim ②; rated
+#                               PARTIAL/THEATER by the 2026-07-06 three-family audit while prose-only)
+#    Registration lives in the GITIGNORED .claude/settings.local.json — BE_DIR is an operator-private
+#    path and must never land in the project-shared settings.json. Idempotent: re-running replaces, never dups.
+#    Measured miss 2026-07-30 (n=2, a freshly installed second machine): neither hook was registered,
+#    so the Mode D load ran only because the operator happened to open with a greeting. A task-first
+#    first message would have skipped it entirely — on Opus, not merely on a weak tier.
+if [ -n "${BE_DIR:-}" ] && [ -d "$HUB_DIR/scripts" ]; then
+  # The real $BE_DIR is passed IN and baked into the command — never a "<your-store>" placeholder
+  # for the user to swap later. A placeholder written into a config file is a hook that reports
+  # "registered" and then silently resolves to a nonexistent path; the Sonnet target-tier sim
+  # (2026-07-30) named exactly this failure — the script prints success, the operator stops, the
+  # hook is dead. If a value must be substituted, substitute it at write time or do not write.
+  python3 - "$HUB_DIR" "$BE_DIR" <<'PY'
+import json, os, sys, collections
+hub, be = sys.argv[1], sys.argv[2]
+p = os.path.join(hub, ".claude", "settings.local.json")
+d = collections.OrderedDict()
+if os.path.exists(p):
+    with open(p) as fh:
+        d = json.load(fh, object_pairs_hook=collections.OrderedDict)
+cmd = lambda s: {"type": "command",
+                 "command": f'BE_DIR="{be}" bash "$CLAUDE_PROJECT_DIR/scripts/{s}"',
+                 "timeout": 20}
+if os.path.exists(p):   # back up before rewriting someone's config; a traceback mid-write truncates
+    import shutil; shutil.copy2(p, p + ".prewizard")
+hooks = d.setdefault("hooks", collections.OrderedDict())
+# Filter at HOOK level, not GROUP level: a user hook sharing a group with an FH hook would otherwise
+# be deleted with the group (cross-family review 2026-07-30 reproduced that loss).
+FH_HOOKS = ("fh_session_load.sh", "fh_env_delta_scan.sh")
+existing = []
+for g in hooks.get("SessionStart", []):
+    survivors = [h for h in g.get("hooks", [])
+                 if not any(n in h.get("command", "") for n in FH_HOOKS)]
+    if survivors:
+        g = dict(g); g["hooks"] = survivors; existing.append(g)
+hooks["SessionStart"] = existing + [
+    {"matcher": "", "hooks": [cmd("fh_session_load.sh"), cmd("fh_env_delta_scan.sh")]}]
+with open(p, "w") as fh:
+    json.dump(d, fh, indent=2, ensure_ascii=False); fh.write("\n")
+print("SessionStart hooks registered ->", p, "(backup: .prewizard)")
+PY
+  # VERIFY by running it once — a registration that was never executed is not a floor.
+  # Expected: a "companion-store freshness" line on stdout. If it prints nothing, BE_DIR is wrong.
+  BE_DIR="$BE_DIR" bash "$HUB_DIR/scripts/fh_session_load.sh" | head -3
+fi
 ```
 
+> **Known-pair check before calling this done** (per `measurement-integrity-checklist.md
+> §Instrument-Calibration`) — **run both legs, do not copy this verdict**:
+> - **known-positive** — `BE_DIR` set → a `companion-store freshness` line prints.
+> - **known-negative** — `BE_DIR` unset → **no companion block prints** and the script exits 0.
+>   It is *not* fully silent: the frontier-digest section runs above the Mode-D guard and speaks to
+>   every user about their own local digest. That is intended. An earlier draft of this note claimed
+>   the negative leg was silent and made that a ship-blocker; running it showed 171 bytes of correct
+>   frontier output — the note was written without executing the check it prescribed.
+> If the negative leg prints anything referencing the **companion store**, do not ship.
+
 - **Raw / Wiki / Conversation ingest axis** (`sync_push_protocols.md`): classify each artifact by
   processing stage — Raw (unprocessed capture) → stays raw; Wiki (distilled + `[[linked]]`) → the
   compounding layer; Conversation (dialogue/decision log). The Raw→Wiki distill is where linking earns
@@ -102,9 +165,16 @@ grep -qF "read \$BE_DIR/INDEX.md first" "$HUB_DIR/CLAUDE.local.md" 2>/dev/null \
 - **Backend note**: for an **Obsidian** backend the graph view is the *visual* observability surface
   (free for that backend); for the recommended **git `*-be`** form, observability is the agent querying
   INDEX + sections (no visualization needed). gbrain ingests the same markdown.
-- **Salience caveat**: the CLAUDE.local.md session-start read is prose (no SessionStart hook) — on a weak
-  tier it may silently not fire. Accepted limitation (mirrors `operational_adaptation.md §Guards`);
-  revisit if a target-tier sim measures a miss.
+- **Salience → mechanical (corrected 2026-07-30)**: this used to read *"the session-start read is prose
+  (no SessionStart hook) — accepted limitation; revisit if a target-tier sim measures a miss."* **Both
+  halves were wrong by then.** The hook exists (`scripts/fh_session_load.sh`, shipped 2026-07-05), and
+  the revisit-trigger has fired: a freshly installed second machine ran with **neither** SessionStart
+  hook registered, on Opus — the load fired only because that session happened to open with a greeting
+  instead of a task. So step 3 above **registers the hooks**; the CLAUDE.local.md prose stays as the
+  human-readable layer *over* that floor, never as the floor itself.
+  **Residual (named, not closed)**: registration lives in the gitignored `settings.local.json`, so a
+  user who re-clones the hub without re-running the wizard silently loses it again — the honest
+  backstop is `install-doctor`'s check item, not the wizard alone.
 
 
 ---
@@ -446,6 +516,50 @@ source "$FH_DIR/templates/fh_audit_check.zsh"
 EOF
 fi
 
+# Node floor check hook — ALL users, not Mode D only. Source of truth = the tracked snippet
+# templates/settings.SessionStart.snippet.json (`project_settings_json` key). Registration itself
+# cannot be tracked (every .claude/settings*.json path is gitignored), so the wizard is what wires it
+# — which is exactly why this must not be skipped: without it, a user on a fresh machine gets no
+# turn-0 signal that their floors are missing.
+# NPM-INSTALL PRECONDITION: this block reads the snippet from disk, so both it and
+# scripts/fh_node_check.sh must be in package.json `files[]`. They are (added 2026-07-30 after
+# scripts/package_coverage_check.sh caught the omission — without it an npm-installed wizard hit
+# FileNotFoundError here and registered nothing while reporting success upstream).
+python3 - "$FH_DIR" <<'PY'
+import json, os, sys, collections
+hub = sys.argv[1]
+snippet = os.path.join(hub, "templates", "settings.SessionStart.snippet.json")
+target = os.path.join(hub, ".claude", "settings.json")
+entry = json.load(open(snippet))["project_settings_json"]["hooks"]["SessionStart"]
+d = collections.OrderedDict()
+if os.path.exists(target):
+    d = json.load(open(target), object_pairs_hook=collections.OrderedDict)
+    import shutil; shutil.copy2(target, target + ".prewizard")   # back up before rewriting
+hooks = d.setdefault("hooks", collections.OrderedDict())
+# Merge at HOOK level, not group level. A group-level filter drops the whole group when a user's own
+# hook shares a group with the FH one — the common shape when someone hand-edits or appends to an
+# older wizard's output. (Cross-family review 2026-07-30 reproduced the loss: a group holding
+# [my_telemetry.sh, fh_session_load.sh] lost my_telemetry.sh entirely.)
+kept = []
+for g in hooks.get("SessionStart", []):
+    survivors = [h for h in g.get("hooks", []) if "fh_node_check" not in h.get("command", "")]
+    if survivors:
+        g = dict(g); g["hooks"] = survivors; kept.append(g)
+hooks["SessionStart"] = kept + entry
+os.makedirs(os.path.dirname(target), exist_ok=True)
+with open(target, "w") as fh:
+    json.dump(d, fh, indent=2, ensure_ascii=False); fh.write("\n")
+print("node-check SessionStart hook registered ->", target)
+PY
+chmod +x "$FH_DIR/scripts/fh_node_check.sh" 2>/dev/null
+# VERIFY against a THROWAWAY state file (FH_NODE_STATE). Verifying against the real state would
+# consume the user's one-shot event report, so their actual first session goes quiet and the notice
+# is buried in install output instead (cross-family review 2026-07-30).
+# known-pair: healthy machine → run 1 prints an event line, run 2 is SILENT.
+#             missing floor  → prints EVERY run (a floor gap is a condition, not an event).
+_T="$(mktemp)"; FH_NODE_STATE="$_T" bash "$FH_DIR/scripts/fh_node_check.sh"
+FH_NODE_STATE="$_T" bash "$FH_DIR/scripts/fh_node_check.sh"; rm -f "$_T"
+
 # 4-axis verification gate (Mode D / FH-self-development only — OPT-IN, double-confirm required)
 # SCOPE (state this before asking): this gates commits IN YOUR FH CLONE ($FH_DIR) — git commit there is
 #   blocked until the 4-axis markers pass. It is FH-internal infra (hardcodes hub paths/markers) and is