@chrono-meta/fh-gate 1.4.41 → 1.4.43

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

@@ -0,0 +1,147 @@
+---
+name: fh-ecosystem-positioning
+description: FH's structural position in the AI agent framework ecosystem vs Hermes, OpenCode, OpenHuman — gap analysis, synergy map, and layered readiness verdict from 3-model adversarial audit (Claude + Gemini + Codex).
+date: 2026-05-31
+tags: [ecosystem, positioning, synergy, opencode, opencode, hermes, openhuman, readiness, v2-paper]
+---
+
+# FH Ecosystem Positioning
+
+## Source
+
+3-model orchestrator-swap adversarial audit (2026-05-31).
+- Orchestrator: Claude Opus (synthesis)
+- Sidecar 1: Gemini (structural + security lens)
+- Sidecar 2: Codex (ecosystem + distribution lens)
+
+Target: FH full structure vs Hermes-type agent frameworks, OpenCode-style coding agents, OpenHuman-style human-in-loop systems.
+
+---
+
+## Gap Analysis — Where FH Falls Short
+
+| Gap | Gemini finding | Codex finding | Convergence |
+|---|---|---|---|
+| **Runtime / Distribution** | — | No standalone binary, no package-manager path; peers (OpenCode, Hermes IDE, OpenHuman) ship signed installers | Codex only |
+| **Execution sandboxing** | No WASM/Docker isolation — destructive bash commands possible inside skill steps | — | Gemini only |
+| **Concurrent state** | File-system bottleneck — no event-bus; parallel agents on same `tracks/` risk state corruption | — | Gemini only |
+| **HITL granularity** | Binary confirm/deny — no capability-based fine-grained delegation (OpenHuman standard) | — | Gemini only |
+| **Gate enforcement** | — | Gates are advisory (instructional thresholds, not mechanical block) | Codex only |
+| **Registry coherence** | — | Count drift: 33 skills, 6 agents vs declared values → fixed in this session | Codex only (fixed) |
+
+**No gap converged across both models** — each lens found distinct weaknesses. This itself is a cross-wave delta finding: Gemini sees architecture risk, Codex sees distribution/ecosystem risk.
+
+---
+
+## Synergy Map — Where Integration Produces N-Fold Value
+
+### 1. FH + OpenCode: Governance Layer on Execution Speed
+
+| Layer | Provider | What it contributes |
+|---|---|---|
+| Execution | OpenCode | High-volume autonomous coding, CLI/desktop distribution, broad language support |
+| Governance | FH | `pipeline-conductor` (4-axis gated sweep) + `steel-quench` (adversarial review) + `phantom-quench` |
+
+**N-fold mechanism**: OpenCode is criticized for "automation-drift" — valid code that doesn't solve the core problem. FH's adversarial + grounding verification layer catches this. The combined result is an autonomous coder that must survive structured critique before the human sees it: "fast coder" → "rigorous engineer."
+
+**Integration path**: Route OpenCode PRs through FH `pipeline-conductor --full` as a post-generation gate. No runtime adapter needed — FH reads any file-based output.
+
+### 2. FH + OpenHuman / Hermes: Memory → Audited Methodology
+
+| System | OpenHuman / Hermes | FH |
+|---|---|---|
+| Provides | Local Memory Tree, persistent conversations, workspace config, cost dashboard, UI/UX | `tracks/`, `knowledge/`, `harvest-loop`, `phantom-quench`, `memory-hygiene` |
+
+**N-fold mechanism**: OpenHuman/Hermes stores memory but treats it as passive recall (context stuffing). FH's harvest-loop + source-grounding turns that memory into *audited institutional process* — patterns are reviewed, grounded, and promoted. Memory becomes methodology, not just storage.
+
+**Integration path**: FH `harvest-loop` runs on the host system's Memory Tree as its audit target. No runtime adapter needed for the methodology layer.
+
+### 3. FH + Hermes IDE: SKILL.md as Portable Instruction Set
+
+**Gemini's framing**: Hermes provides the "seat" (delivery, UI, local context); FH provides the "controls" (vendor-agnostic methodology). Embedding FH's SKILL.md parser into the Hermes sidecar gives **model portability** — switch from Claude to Gemini mid-task without re-teaching the UI how to run a `harness-doctor` audit. FH becomes the "instruction set" for the UI's "processor."
+
+---
+
+## Readiness Verdict (Layered)
+
+**Verdict diverged by lens** — both are correct, different layers:
+
+| Layer | Gemini verdict | Codex verdict | Synthesis |
+|---|---|---|---|
+| Methodology | "Fully-Prepared Hermit" — deep internal maturity, can engage | Strong claim, best-in-class in process integrity | **Peer-ready NOW** |
+| Framework/Runtime | "Externally illiterate" — lacks API, event system, sandbox | "Not peer-level" — no binary, no canonical registry, no distribution | **v0.x — needs bridge layer** |
+
+**The hermit metaphor holds, precisely**: FH has meditated deeply (adversarial review, harvest loops, calibration, sidecar orchestration). It can engage any framework on methodology. It cannot yet *integrate as a framework peer* without forcing the other system to adopt its file-heavy, CLI-centric worldview.
+
+**What "bridge layer" means concretely**:
+1. Host-agnostic CLI adapter — methodology layer runs without Claude Code automation layer
+2. Canonical machine-readable registry — `plugin.json` + actual file counts synchronized, test status, compatibility matrix
+3. Integration contract — OpenCode/OpenHuman calls FH gates, receives structured verdicts, persists reports
+
+---
+
+## Immediate Action (No Bridge Layer Required)
+
+FH + OpenCode governance integration is executable **today** at the methodology layer:
+
+```bash
+# After OpenCode generates a PR:
+# 1. Capture the diff
+git diff main..HEAD > /tmp/opencode_output.diff
+CHANGED=$(git diff main..HEAD --name-only | tr '\n' ' ')
+
+# 2. steel-quench adversarial pass on changed files
+# → finds behavioral edge cases, untested contracts, security assumptions
+
+# 3. pipeline-conductor --quick on changed files
+# → 4-axis gate: backward / adversarial / forward / record
+
+# 4. phantom-quench on any new documentation claims
+# → catches phantom references and stale citations
+```
+
+This requires no OpenCode API integration — FH reads files, OpenCode writes files. The protocol is the interface.
+
+See `fh_opencode_governance_wrapper.md` for the full step-by-step guide and Stop hook automation.
+
+### Empirical result (2026-05-31)
+
+Applied the 3-step governance pass to OpenCode's own AI-generated `permission/arity.ts` (163 lines). CI verdict: DONE (6/6 tests pass). FH governance verdict: PENDING — 2 A-grade findings CI did not cover:
+
+1. Short-token overflow in `prefix()` — allowlist pattern may not cover bare commands previously approved
+2. `npx`, `opencode`, `claude` absent from arity table — `npx <anything>` receives the same broad `"npx *"` pattern, weakening the permission model
+
+The delta is attributable to the methodology layer, not the model. Both passes read identical code.
+
+---
+
+## v2 Paper Connection
+
+The ecosystem positioning audit surfaces a testable claim for v2:
+
+> "A harness-structured workflow integrated as a governance layer on top of a bare coding agent produces qualitatively different outputs from either system alone — not because the model changed, but because the methodology layer enforces structured verification that the agent alone cannot generate."
+
+This is the N-fold synergy claim stated precisely. The controlled experiment design: OpenCode alone vs OpenCode + FH governance on the same task. Measure: findings caught by governance that CI missed, rework cycles prevented.
+
+**Empirical pilot (2026-05-31)**: Applied to OpenCode's own AI-generated `permission/arity.ts`. Governance caught 2 A-grade security-adjacent issues that 6 CI tests missed. Causal attribution is clean: same code, same model, different methodology layer.
+
+**v2 scope**: This experiment, combined with the 3-round orchestrator-swap finding (`multi_model_sidecar_strategy.md`), constitutes novel empirical contribution — not a version update. Proposed framing:
+
+| Experiment | Claim tested | Evidence produced |
+|---|---|---|
+| 3-round orchestrator-swap | Process diverges, results converge; harness is activation condition | Cross-wave delta synthesized across Claude/Gemini/Codex |
+| FH + OpenCode governance | Methodology layer catches what bare coding + CI misses | DONE → PENDING verdict flip on AI-generated code |
+| Tier comparison (pending) | Divergence quality stable across model tiers | Needs replication with all-premium models |
+
+**OpenCode as citation**: The governance experiment uses OpenCode's codebase as the subject. OpenCode should be cited as the target system in the v2 experimental section. Citation candidate: the OpenCode GitHub repository + any associated paper/technical report.
+
+---
+
+## References
+
+- `fh_opencode_governance_wrapper.md` — step-by-step usage guide with empirical findings
+- `fh_synergy_playbook.md` — concrete FH×OpenCode/Hermes/OpenHuman workflow specs that operationalize this positioning
+- `multi_model_sidecar_strategy.md` — orchestrator-swap experiment that generated this audit
+- `README.md §Architecture` — 2-layer design (methodology vs automation)
+- `AGENTS.md` — 6-agent registry (fact-checker added after this audit)
+- FH paper (Zenodo: 10.5281/zenodo.20397566) — harness-as-durable-layer thesis this positioning extends

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

@@ -0,0 +1,163 @@
+---
+name: fh-opencode-governance-wrapper
+description: Step-by-step usage guide for FH + OpenCode governance integration. No API adapter required — FH reads files OpenCode writes. Includes empirical findings from 2026-05-31 controlled trial on arity.ts.
+date: 2026-05-31
+tags: [opencode, governance, usage-guide, synergy, pipeline-conductor, steel-quench, v2-paper]
+---
+
+# FH + OpenCode Governance Wrapper — Usage Guide
+
+## What this is
+
+OpenCode generates code fast. FH catches what fast generation misses.
+
+The integration requires no runtime adapter. OpenCode writes files; FH reads files. The protocol is the interface. You can run this today on any OpenCode output.
+
+---
+
+## The 3-Step Governance Pass
+
+After OpenCode completes a task (or at any checkpoint), run these three steps in order:
+
+### Step 1 — Capture the diff
+
+```bash
+# Capture everything OpenCode changed since the task started
+git diff <start-commit>..HEAD > /tmp/opencode_output.diff
+
+# If you don't know the start commit:
+git diff main..HEAD > /tmp/opencode_output.diff
+
+# List changed files explicitly (needed for Steps 2 and 3):
+CHANGED=$(git diff main..HEAD --name-only | tr '\n' ' ')
+echo "Changed: $CHANGED"
+```
+
+### Step 2 — steel-quench adversarial pass
+
+Run `/steel-quench` (or describe the target to Claude):
+
+```
+Run steel-quench adversarial review on these files: $CHANGED
+Focus: behavioral edge cases, untested contracts, security assumptions.
+Output: 3 most critical findings with severity (A/B/C) and evidence.
+```
+
+steel-quench looks for what tests don't cover: contract boundary violations,
+caller assumption gaps, silent fallbacks that mask errors.
+
+### Step 3 — pipeline-conductor --quick
+
+```
+Run pipeline-conductor --quick on: $CHANGED
+```
+
+4-axis verdict:
+- Axis 1 (Backward): regression risk
+- Axis 2 (Adversarial): structural gaps (from Step 2)
+- Axis 3 (Forward): phantom claims, broken references
+- Axis 4 (Record): calibration log entry
+
+**If verdict is CLEAN or PENDING**: proceed. Log the run.
+**If verdict is BLOCKED**: surface findings to OpenCode, re-run the task with constraints added.
+**If verdict is ESCALATE**: human decision required before merge.
+
+---
+
+## Optional: Step 0 — Pre-task scope gate
+
+Before running OpenCode on a large task, estimate the scope:
+
+```
+Estimate token budget for: <task description>, ~<N> files expected to change.
+```
+
+Use `/token-budget-gate` or the fallback heuristic:
+
+| Scope | Verdict |
+|---|---|
+| < 5 files, no new architecture | GREEN — proceed |
+| 5–20 files or new module | YELLOW — proceed with monitoring |
+| 20+ files or cross-system refactor | ORANGE — confirm scope |
+| Full rewrite | RED — split into smaller tasks first |
+
+---
+
+## Empirical Baseline (2026-05-31)
+
+**Target**: OpenCode's own `packages/opencode/src/permission/arity.ts` (163 lines, AI-generated).
+
+**Baseline (CI + self-evaluation)**: 6 unit tests, all pass. No syntax errors. Verdict: DONE.
+
+**After FH governance pass**:
+
+| Finding | Grade | What CI missed |
+|---|---|---|
+| Short-token overflow in `prefix()` — arity=3 entry with 2-token input builds allowlist pattern that may not cover bare commands | A | Untested path; `git stash` alone may not match `"git stash *"` |
+| `npx`, `opencode`, `claude`, `bunx`, `uvx` absent from arity table — any `npx <package>` receives same broad `"npx *"` pattern | A | Not in test scope; security model weakened |
+| AI-generated dictionary has no maintenance protocol or rule compliance check | B | No cadence, drift risk |
+
+**Verdict flip**: DONE → PENDING. Delta is attributable to methodology layer, not the model.
+
+**Implication**: 3 findings per 163-line AI-generated module that CI treats as done. Extrapolate across a codebase and the governance dividend compounds.
+
+---
+
+## When to run
+
+| Signal | Action |
+|---|---|
+| OpenCode completes a task and opens a PR | Run all 3 steps before merge review |
+| OpenCode generates a new module (AI-authored code) | Run Steps 2+3 — adversarial + 4-axis |
+| OpenCode touches a security-adjacent file (permissions, auth, tokens) | Mandatory — run Steps 2+3 with security lens |
+| OpenCode generates tests | Step 3 (pipeline-conductor) — check if tests actually cover the contract |
+| Long OpenCode session (YELLOW or ORANGE budget) | Run Step 1 at each checkpoint, not just at the end |
+
+---
+
+## Synergy map — what each layer contributes
+
+| Layer | Role | What it catches |
+|---|---|---|
+| **OpenCode** | Fast autonomous coding | Working code at speed |
+| **FH steel-quench** | Adversarial review | Behavioral edge cases, untested contracts, security assumptions — what tests don't cover |
+| **FH pipeline-conductor** | 4-axis structured gate | Regression risk, phantom claims, record keeping — what code review doesn't structure |
+| **Combined** | Governance wrapper | Fast coder + structured critique = rigorous engineer |
+
+The key: OpenCode and FH operate on the same files with no integration layer. The governance wrapper is a *protocol*, not an API.
+
+---
+
+## Full automation (optional)
+
+For teams that want to run governance automatically after every OpenCode session, add a Stop hook:
+
+```json
+// .claude/settings.json (in your project, not forge-harness)
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '[FH governance] Run pipeline-conductor --quick on $(git diff main..HEAD --name-only | tr \"\\n\" \" \")' >> /tmp/fh-pending-governance.txt"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+On session end, check `/tmp/fh-pending-governance.txt` and run the governance pass.
+
+---
+
+## References
+
+- `fh_ecosystem_positioning.md` — ecosystem context, synergy map, v2 paper connection
+- `multi_model_sidecar_strategy.md` — multi-model orchestration (sidecar pattern for adding Gemini/Codex review)
+- `tracks/_meta/fh_opencode_governance_experiment_2026_05_31.md` — full empirical record (local)
+- FH paper (Zenodo: 10.5281/zenodo.20397566) — harness-as-durable-layer thesis

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

@@ -0,0 +1,217 @@
+---
+name: fh-synergy-playbook
+description: Concrete workflow specifications for using FH governance alongside OpenCode, Hermes, and OpenHuman — grounded in empirical results, no unverified claims.
+date: 2026-05-31
+tags: [synergy, integration, opencode, hermes, openhuman, governance, playbook, marketing]
+---
+
+# FH Synergy Playbook — How to Use FH with OpenCode, Hermes, and OpenHuman
+
+This document describes **exact workflows** for combining forge-harness with three AI agent projects. Every outcome stated here is backed by a recorded experiment or a structural guarantee from the software itself. Nothing is promised without evidence.
+
+---
+
+## The Core Pattern (Abstract)
+
+```
+AI agent generates or mutates code
+    ↓
+FH governance pass (before merge)
+    ↓
+Structured verdict: PASS | PENDING | BLOCKED
+    ↓
+Merge (if PASS) or fix-cycle (if PENDING/BLOCKED)
+```
+
+**What FH adds:** a structured verification layer that runs the same criteria every time, regardless of which model generated the code or which CI system is in use. It reads files the agent writes — no API integration, no runtime adapter.
+
+**What FH does NOT do:**
+- It does not fix the code for you (it produces findings, not patches)
+- It does not replace CI (unit tests and FH governance are complementary, not competing)
+- It does not guarantee zero bugs in output — it guarantees that structured verification ran
+
+---
+
+## With OpenCode — AI Code Generation + FH Quality Gate
+
+### The gap FH closes
+
+OpenCode generates code rapidly. Its own CI (unit tests, type checks) validates syntax and basic behavior. What it misses: security-adjacent logic, arity/allowlist edge cases, AI-generated assumptions that pass tests but break real-world usage.
+
+### Workflow
+
+```bash
+# 1. Let OpenCode do its work
+opencode run "implement the feature"
+
+# 2. Capture what changed
+export FH_TARGET_FILES=$(git diff main..HEAD --name-only)
+
+# 3. Run FH governance pass
+./scripts/fh-gate.sh "$FH_TARGET_FILES"
+# → generates structured prompt for steel-quench + pipeline-conductor
+
+# 4. Read the verdict
+# FH_STATUS: SUCCESS
+# FH_GATE_VERDICT: PASS | PENDING | BLOCKED
+# findings: (YAML block — actionable issues with grade A/B/C)
+```
+
+### Evidence
+
+**Controlled trial (2026-05-31):** Applied to `packages/opencode/src/permission/arity.ts` — 163 lines, AI-generated, 6 unit tests all passing, self-evaluation verdict: DONE.
+
+FH governance verdict: **PENDING**.
+
+Findings:
+- **A-grade:** `prefix()` short-token path — permission allowlist may not cover bare commands. Untested execution path.
+- **A-grade:** `npx`, `opencode`, `claude`, `bunx`, `uvx` absent from ARITY table — `npx <anything>` receives the same broad allow pattern, security model weakened.
+- **B-grade:** AI-generated dictionary has no maintenance protocol.
+
+**Causal attribution:** same code, same model (Claude), same CI — different methodology layer. The delta is attributed to the governance pass, not the model.
+
+### When to use
+
+- After any OpenCode session that touches security-sensitive files (`permission/`, `auth/`, `token/`, `key/`)
+- Before merging AI-generated code to main
+- As part of a Stop hook: OpenCode exits → fh-gate.sh auto-triggers → verdict in git notes
+
+---
+
+## With Hermes — Skill Configuration Audit Before Dispatch
+
+### The gap FH closes
+
+Hermes orchestrates agents through skill files. Skill configuration errors (missing validation, unsandboxed context, credential exposure) only surface at runtime — sometimes in production. FH governance catches these before the skill is dispatched.
+
+### Workflow
+
+```bash
+# 1. After adding or modifying a Hermes skill
+SKILL_PATH="skills/autonomous-ai-agents/opencode/SKILL.md"
+
+# 2. Run FH governance on the skill file
+export FH_TARGET_FILES="$SKILL_PATH"
+export FH_CALLER="hermes"
+export FH_GATE_LEVEL="standard"
+./scripts/fh-gate.sh "$FH_TARGET_FILES" "$FH_GATE_LEVEL" "$FH_CALLER"
+
+# 3. Before dispatching the skill, check verdict
+# If PENDING → review findings before allowing live dispatch
+```
+
+### Evidence
+
+**Gemini sidecar review (2026-05-31):** Applied to Hermes `skills/autonomous-ai-agents/opencode/SKILL.md`.
+
+Findings:
+- **A-grade:** No pre-execution plan validation — OpenCode operates directly on `workdir` without a review step before file mutations. Destructive rewrites land unreviewed.
+- **A-grade:** Secret ingestion risk — OpenCode may ingest `.env` files or `.git` history into prompt context, potentially exposing credentials to external LLM providers.
+- **B-grade:** No convergence verification — background sessions can exit with success status while leaving codebase in broken state.
+
+**Filed as:** Hermes issue [#35709](https://github.com/NousResearch/hermes-agent/issues/35709).
+
+### When to use
+
+- Before committing any new Hermes skill that dispatches an external agent
+- During Hermes skill review cycles
+- As part of Hermes CI: run fh-gate.sh on changed skill files in PRs
+
+---
+
+## With OpenHuman — Memory Tree Staleness Audit
+
+### The gap FH closes
+
+OpenHuman's Memory Tree stores persistent context (technical decisions, file paths, architectural claims). These are validated once at write time, then trusted indefinitely. FH's `memory-hygiene` + `phantom-quench` pattern re-verifies memory entries against live state.
+
+### Workflow
+
+```bash
+# 1. Extract memory entries that reference file paths or technical claims
+# (OpenHuman Memory Tree format — paths, decisions, URLs)
+
+# 2. For each entry, verify it still holds
+for entry in memory_entries:
+    verify file paths exist in current codebase
+    verify external URLs still reachable
+    verify technical claims match current code
+
+# 3. Verdict per entry:
+#   GROUNDED  — verified, safe to use
+#   STALE     — entry exists but referenced reality changed (warn, prompt for update)
+#   BROKEN    — hard reference failure (flag for immediate update)
+```
+
+### Evidence
+
+**Structural analysis (2026-05-31):** OpenHuman's `pr-review-shepherd` skill documentation notes that "Composio catalog slugs occasionally drift" — an acknowledgment that the stale-but-confident failure mode exists in the project's own documentation.
+
+**FH's `memory-hygiene` skill** implements this pattern for harness memory with a verified weekly cadence. The same algorithm applies directly to OpenHuman's Memory Tree.
+
+**Filed as:** OpenHuman issue [#3069](https://github.com/tinyhumansai/openhuman/issues/3069).
+
+### When to use
+
+- Weekly, or on session start if >7 days since last audit
+- After major refactors that move or delete files
+- After reversing a significant architectural decision
+
+---
+
+## Expected Outcomes (Honest Estimates)
+
+Based on the controlled trial and sidecar experiments:
+
+| Scenario | Expected FH Verdict | Finding Rate |
+|---|---|---|
+| AI-generated code, CI passing, no prior governance | PENDING (expected) | 1–3 A/B-grade findings per session (empirical: 2A+1B on arity.ts) |
+| Hermes skill configuration, new external agent | PENDING (expected) | 1–2 A-grade findings per skill (empirical: 2A+1B on opencode skill) |
+| Human-written code, existing tests passing | PASS (expected) | 0–1 B-grade; A-grade unlikely but possible |
+| Previously FH-reviewed code, no changes | PASS | Near-zero new findings (compounding effect) |
+
+**Important caveat:** These are estimates from a small sample. Your actual finding rate depends on code quality, domain, and how much adversarial pressure the governance pass applies. The finding rate is not guaranteed — the governance execution is.
+
+---
+
+## The "No Integration Required" Value Proposition
+
+All three workflows above require:
+1. `git diff` to capture changed files
+2. `./scripts/fh-gate.sh` to generate a structured governance prompt
+3. Reading the verdict
+
+No API integration. No OpenCode plugin. No Hermes adapter. No OpenHuman SDK.
+
+FH reads files OpenCode / Hermes / OpenHuman write. The protocol is the interface.
+
+This also means FH governance can be added **at any point in an existing workflow** — no architectural changes required.
+
+---
+
+## Compounding Effect
+
+The first FH governance pass on a codebase finds the most issues. Each subsequent pass finds fewer — not because the tool is degrading, but because the codebase is improving. This is the governance dividend:
+
+```
+Pass 1: PENDING (2 A-grade, 1 B-grade)
+    ↓ fix
+Pass 2: PENDING (0 A-grade, 1 B-grade)
+    ↓ fix
+Pass 3: PASS
+    ↓ future changes re-enter at Pass 1 only for the changed files
+```
+
+Over time, the governance overhead per PR decreases while baseline code quality rises. The tool does not get harder to satisfy — the codebase gets easier to verify.
+
+---
+
+## References
+
+- **Controlled trial (Experiment 2):** `tracks/_meta/fh_opencode_governance_experiment_2026_05_31.md`
+- **Sidecar experiment (Experiment 1):** `knowledge/shared/harness-core/multi_model_sidecar_strategy.md`
+- **Integration contract spec:** `knowledge/shared/harness-core/fh_integration_contract.md`
+- **fh-gate.sh:** `scripts/fh-gate.sh`
+- **OpenCode issue:** github.com/anomalyco/opencode/issues/30057
+- **Hermes issue:** github.com/NousResearch/hermes-agent/issues/35709
+- **OpenHuman issue:** github.com/tinyhumansai/openhuman/issues/3069

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

@@ -0,0 +1,57 @@
+---
+name: gate-locality-principle
+description: A safety gate must live where the actor that needs it actually reads it — a gate defined in a place the enforcing actor never loads is decorative, not enforced.
+type: reference
+date: 2026-06-20
+tags: [governance, gate-locality, multi-runtime, judge-robustness, field-harvest]
+originProjects: [two restricted-env field harnesses]
+---
+
+# Gate-Locality Principle
+
+> **A safety gate must live where the actor that needs it actually reads it.**
+> A gate defined in a place the enforcing actor never loads provides the *appearance* of safety
+> with none of the enforcement. Locality is part of the gate's correctness, not an afterthought.
+
+This is a sibling of the **judge-robustness / mechanical-anchor** spine: judge-robustness says *don't
+let a foolable judge hold the terminal verdict*; gate-locality says *don't put the gate somewhere the
+enforcer can't see it*. Both fail the same way — a control that looks present but cannot actually fire.
+
+## The failure mode (two observed shapes)
+
+| Shape | Where the gate was | Who needed it | Why it didn't fire |
+|---|---|---|---|
+| **Code-locality** | absent from the write path entirely | the function that writes to JIRA | the writeback gate checked confidence but not provenance, so a self-inferred finding auto-posted as if verified |
+| **File-locality** | only in a Claude-only `CLAUDE.md` | a Gemini/Codex orchestrator that auto-loads root `AGENTS.md`, not `CLAUDE.md` | the runtime assumed the commander *role* without inheriting the *gates* |
+
+Both were found 2026-06-20 across **two field harnesses** (Harness-A: a provenance gate missing from a
+write path; Harness-B + Harness-A: orchestration gates that lived only in a Claude-only file). The
+recurrence across two contexts is what lifts this past a
+single anecdote; it is N=2 within one operator's projects, so **cross-operator confirmation is the
+upgrade path** that would harden it from a working principle to a validated one.
+
+## The fix pattern
+
+Move the gate into the artifact the enforcing actor actually reads:
+- **Code path** → put the guard *in the function that performs the irreversible action* (e.g. gate the
+  writeback candidate generator on `provenance == verified`, not in a doc that describes it).
+- **Multi-runtime orchestration** → put orchestration gates in a **model-agnostic** file every
+  runtime loads (`AGENTS.md`), not in a Claude-only `CLAUDE.md`. A non-Claude orchestrator that never
+  reads `CLAUDE.md` otherwise gets the role without the governance.
+
+## Verification (how to know the locality fix worked)
+
+A **blind target-tier sim** is the honest check: feed the enforcing actor ONLY the file/path it
+actually loads (e.g. `AGENTS.md` alone, no `CLAUDE.md`) and present a trap the gate should catch
+(e.g. a high-confidence but unverified finding to auto-write). Pre-fix the actor has no basis to
+refuse; post-fix it refuses, citing the now-local gate. The behavioral delta *is* the proof of
+locality — review alone cannot show it (review reads all files; the runtime does not).
+
+## Relationship to other FH assets
+
+- **steel-quench** carries this as a Wave-1 attack angle ("Gate-locality — is every safety gate
+  readable by the actor that must enforce it?").
+- **judge-robustness / mechanical-anchor** (`[[feedback_judge_robustness_mechanical_anchor]]`) — the
+  sibling principle for *verdict* placement; gate-locality is for *gate* placement.
+- **Non-Model Ground** — multi-runtime orchestration is exactly where gate-locality bites, because
+  different runtimes load different files.