@chrono-meta/fh-gate 1.0.0

package/README.md

@@ -0,0 +1,519 @@
+<p align="center">
+  <img src="docs/banner.png" alt="forge-harness — A forkable Claude Code meta-harness for multi-project teams" width="640">
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/version-v1.3-3b82f6.svg" alt="v1.3">
+  <a href="https://zenodo.org/records/20397566"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20397566.svg" alt="DOI 10.5281/zenodo.20397566"></a>
+  <img src="https://img.shields.io/badge/Claude_Code-compatible-a855f7.svg" alt="Claude Code compatible">
+  <img src="https://img.shields.io/badge/Codex-beta-f59e0b.svg" alt="Codex-compatible beta">
+</p>
+
+<p align="center">
+  <b>Fork it. Rename it. Make it yours.</b><br>
+  A persistent knowledge hub that connects all your Claude Code projects — shared skills, accumulated context, and a compounding improvement loop.
+</p>
+
+---
+
+| If you're here because… | forge-harness solves it |
+|---|---|
+| Context disappears when a session ends | Persistent `tracks/` — resumable from anywhere |
+| You repeat the same setup for every project | Connect once to the hub, share across all projects |
+| Your team's AI know-how lives only in people's heads | Codify it so everyone shares it |
+| You want AI to get *better* as work accumulates | Skills and patterns compound session over session |
+| You're evaluating AI-generated code with no governance layer | `fh-gate` wraps any coding agent as a post-generation gate |
+
+> **Worried about token costs?** New install footprint ≈ 14.5% of 200K context. `context-doctor` diagnoses and reduces this further. → [Token optimization](#token-cost-optimization)
+
+| Where you are now | Jump to |
+|---|---|
+| Starting from scratch | [Get started in 2 minutes](#get-started-in-2-minutes) |
+| Already using it, want more | [33 asset activation check](#already-using-it----33-asset-activation-check) |
+| Wrapping an external coding agent | [Governance layer](#governance-layer-for-ai-generated-code) |
+| Want to spread it to your team | [Operating model Phase 3](#operating-model----3-phase-essence) |
+
+---
+
+> **This document is for humans.** AI operating rules → `CLAUDE.md` · Command reference → `CHEATSHEET.md`
+
+---
+
+## What is this?
+
+An **acceleration hub** for teams already using Claude Code. Connect N projects to one hub — work, learnings, and patterns from each project **mutually reinforce** each other. Build skills and agents once in the hub; share them across every project.
+
+> **Goal**: Get into orbit in the age of AI acceleration without burning out. Minimize setup friction, optimize context, distribute expertise by task complexity, and raise the success rate of every session.
+
+forge-harness is structured as two distinct layers:
+
+| Layer | Contents | AI compatibility |
+|---|---|---|
+| **Methodology layer** (model-agnostic) | `tracks/`, `knowledge/`, `SKILL.md` documents, session protocols | Any AI model |
+| **Automation layer** (Claude-native) | `.claude/agents/`, hooks, slash commands, `CLAUDE.md` rules | Claude Code only |
+
+The **methodology layer** is the portable core — connecting projects to a persistent hub, accumulating learnings in `tracks/`, curating cross-project knowledge in `knowledge/shared/`. Works regardless of which AI you use.
+
+The **automation layer** is what makes the methodology frictionless when running Claude Code: agents dispatch automatically, hooks fire at session boundaries, and slash commands invoke skills without manual prompting.
+
+> **Codex-compatible beta**: Gemini, Codex, and other AI users can apply the methodology layer manually. Automation layer features require Claude Code as host.
+
+---
+
+## Finding your entry path
+
+Teams using AI collaboration tools systematically are already doing **harness engineering**: QA protocols, verification pipelines, structures that make AI behave more consistently. forge-harness is the **OS one layer above** — a system that measures, improves, and evolves the harness itself across multiple projects.
+
+| Layer | What it does | Examples |
+|---|---|---|
+| Harness engineering | Per-project rules, gates, context management | QA protocols, CLAUDE.md rulesets, TC verification pipelines |
+| **Meta harness engineering** | Cross-project system to measure, improve, evolve harnesses | FH skill bus, harness-doctor, steel-quench, field-harvest |
+
+> **FH v1.0 paper** — published 2026-05-30 on [Zenodo](https://zenodo.org/records/20397566) (DOI: 10.5281/zenodo.20397566) · arXiv submission in review. Documents the 2-layer design, 6-axis framework, 4-agent orchestration, and compounding loop with controlled empirical evidence.
+
+> **External validation (2026)** — three independent research findings converge:
+> - VILA-Lab analysis of Claude Code v2.1.88 (512K lines): [98.4% is harness infrastructure, 1.6% AI logic](https://arxiv.org/abs/2604.14228)
+> - "[Code as Agent Harness](https://arxiv.org/abs/2605.18747)" (arXiv, May 2026, 43 authors)
+> - Stanford IRIS Lab: "[Meta-Harness](https://arxiv.org/abs/2603.28052)" (Lee et al., Mar 2026) — outer-loop harness optimization; +7.7pts at 4× fewer tokens
+
+#### FH vs. automated harness tools
+
+The Stanford paper inspired [harness-evolver](https://github.com/raphaelchristi/harness-evolver) — a fully automated 7-stage CODE optimizer. FH independently converged on the same loop architecture from the opposite direction:
+
+| Axis | harness-evolver | forge-harness |
+|---|---|---|
+| **Optimization target** | Harness code (prompts, routing) | Harness knowledge (context, patterns, expertise) |
+| **Evolution** | Auto-merge winners to git | Human-approved at every stage |
+| **Infrastructure** | LangSmith + Python 3.10+ | CLAUDE.md + skills only, zero extra |
+| **Scope** | Single-harness optimization | Multi-project federation, shared skill bus |
+| **Knowledge layer** | No persistent curation | `tracks/` + `knowledge/` grow over time |
+
+They're complementary — FH's approval gates and knowledge layer fill exactly the gaps automated CODE search leaves open.
+
+Count how many apply to you:
+
+- [ ] You have 2 or more Claude Code projects
+- [ ] You lose context when a session ends
+- [ ] You repeat the same patterns and rules across multiple projects
+- [ ] You want to spread AI methodology to your team
+- [ ] You want AI to improve as work accumulates
+
+| Count | Recommended path |
+|:---:|---|
+| **3+** | Standard entry → [Get started in 2 minutes](#get-started-in-2-minutes) |
+| **1–2** | Plugin first → `claude plugin install -s user fh-meta@forge-harness` |
+| **0** | Single-project stage — check back when you reach 2+ projects. `context-doctor` is available standalone now |
+
+---
+
+## Get started in 2 minutes
+
+> **Prerequisite**: Claude Code CLI installed. Verify: `claude --version`
+
+### Step 0. Register the plugin
+
+```bash
+claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
+claude plugin install -s user fh-meta@forge-harness
+```
+
+> If Step 0 fails: run `claude plugin update fh-meta@forge-harness`, or check that your network can reach `github.com`.
+
+Verify: type `/skills` in the CC chat → if `install-wizard` appears, you're done.
+
+### Step 1. Clone the hub
+
+```bash
+git clone https://github.com/chrono-meta/forge-harness.git ~/forge-harness
+cd ~/forge-harness
+```
+
+> **Standard path**: Fork on GitHub first → clone your fork → accumulate `tracks/` and `knowledge/` there → periodically pull upstream updates from forge-harness. Rename it to make it yours.
+
+### Step 2. Say something
+
+```bash
+claude
+```
+
+> ✅ **Expected**: Claude reads `CLAUDE.md`, asks what project to connect or what task to start.
+>
+> ❌ **Generic response?** → Run `pwd` to confirm you're in the `forge-harness` root. If not: `cd ~/forge-harness && claude`
+
+From here:
+- **"Connect a project"** → hub scans `../`, lists projects with `.git`, creates `tracks/{project}/` on confirmation
+- **"My projects are in `~/work/`"** → specify a different root
+
+---
+
+## Governance layer for AI-generated code
+
+FH wraps any coding agent (OpenCode, Codex, etc.) as a **post-generation governance layer** — no runtime adapter needed. FH reads files the agent writes; the protocol is the interface.
+
+```bash
+# After a coding agent completes a task:
+./scripts/fh-gate.sh                   # auto-detects changed files from git diff
+# → steel-quench adversarial pass      # behavioral edges, untested contracts, security
+# → pipeline-conductor --quick         # 4-axis: regression / adversarial / grounding / record
+# → FH_GATE_VERDICT                    # PASS | PENDING | BLOCKED | ESCALATE
+```
+
+**Empirical result (2026-05-31)**: Applied to OpenCode's own AI-generated `permission/arity.ts` (163 lines, 6 tests passing, CI green). Governance verdict: PENDING — 2 A-grade findings CI didn't cover (short-token overflow in allowlist, executor tools absent from arity table). Delta attributable to methodology layer, not the model.
+
+Full spec: `knowledge/shared/harness-core/fh_integration_contract.md` · Usage: `knowledge/shared/harness-core/fh_opencode_governance_wrapper.md`
+
+> **One-line install (coming soon)**: `npx @chrono-meta/fh-gate "src/foo.ts" quick ci` — npm publish in progress.
+
+---
+
+## Real-world case — AI TC generation prompt hardening
+
+> **Context**: An AI-powered test case generation tool was merging TC outputs without quality validation. Prompts contained cushion language, phantom claims, and no priority guardrails.
+
+**Applied**: `steel-quench` (W1–W8 adversarial hardening) + `source-grounding-audit` (phantom claim detection)
+
+| Wave | What was attacked | Result |
+|---|---|---|
+| W1–W2 | Cushion language ("it would be good to…") → forced conditions | Ambiguity eliminated |
+| W4–W5 | No self-check step → Self-Check quality gate added | Quality bypass path closed |
+| W6 | Soft review → Hard gate ("no next step until fix complete") | Incomplete TC merge blocked |
+| W7 | P0 ratio inflation → forced re-review above 30% | Priority inflation prevented |
+| W8 | Phantom Claim Guard — unspecified values/button names banned | Fabricated expected results blocked |
+
+**Outcome**: 4 bugs found and fixed · 8-layer quality gate complete · output noise eliminated
+
+> The self-healing loop: steel-quench attacks the prompt → execution catches bugs the review missed → fixes are verified in the same pass.
+
+---
+
+## Already using it — 33 asset activation check
+
+<details>
+<summary>Expand full asset table (33 skills + 5 agents)</summary>
+
+Check which of the following are **regularly activating** for you:
+
+| Asset | Role | Natural language triggers | Active |
+|---|---|---|:---:|
+| `agent-composer` | Plans optimal agent dispatch | "How should I split this across agents?", "Run in parallel" | □ |
+| `apex-review` | Final quality review from executive perspective | "Will this hold up with decision-makers?" | □ |
+| `verify-bidirectional` | Reverse-verify decisions | "Is that right?", "Double-check this" | □ |
+| `deliberation` *(fh-commons)* | Structured multi-angle argument | "Battle it out", "Review this from multiple angles" | □ |
+| `cross-ecosystem-synergy-detection` | Detect cross-tool synergies | "Are my installed tools working together?" | □ |
+| `plugin-recommender` | Plugin recommendations | "Is there a good tool for this?" | □ |
+| `hub-cc-pr-reviewer` | Automated PR review | "Review this PR", "Is it okay to merge?" | □ |
+| `context-doctor` | Token efficiency + `.claudeignore` | "Session is slow", "Clean up context" | □ |
+| `sim-conductor` | Meta-simulation orchestrator | "External user perspective", "Internal audit" | □ |
+| `steel-quench` | Full-spectrum adversarial verification — attacks output patterns (self-declarations, cushion language, structural flaws) | "Run the quench", "Attack from the root" | □ |
+| `source-grounding-audit` | Source back-tracing — detects Phantom Claims (no source found). Attacks input tracing (where did this come from?) | "Verify the source", "Grounding audit" | □ |
+| `harness-doctor` | Harness structure diagnosis | "Something seems wrong with my Claude setup" | □ |
+| `deep-clarify` | Socratic requirements clarification | "I'm not sure what I need to build", "Clarify this" | □ |
+| `meta-prompt-builder` | Meta prompt design | "Write a prompt for each Wave", "What should I tell the agent?" | □ |
+| `install-doctor` | Diagnose conflicts before/after plugin install | "Is it okay to add this plugin?" | □ |
+| `install-wizard` | Initial environment diagnosis + onboarding | "First-time setup", "Just installed this" | □ |
+| `asset-placement-gate` | New asset belongs in FH or project? | "Should this be shared?", "Hub vs project" | □ |
+| `marketplace-gate` | 5-point fitness gate before listing | "Is it okay to list this?" | □ |
+| `field-harvest` | Back-propagate field patterns to hub | "I could reuse this in other projects" | □ |
+| `hub-persona-auditor` | Pre-publish 4-axis audit | "How will this look to others?" | □ |
+| `fact-checker` | Asset deduplication check | "Isn't there something similar already?" | □ |
+| `persona-innovator` | Naming gap detection + ideation | "What would be a good name for this?" | □ |
+| `contention-layer` | Treat skill conflicts as harvest signals | "These two skills conflict" | □ |
+| `context-bridge-dispatch` | Inject session context cards before parallel dispatch | "Brief the agents first", "Parallel dispatch" | □ |
+| `frontier-digest` | Frontier signals (HN, arXiv) → actionable insights | "AI trend digest", "What's new this week" | □ |
+| `harvest-loop` | End-of-session learning → evolution pipeline | "Harvest the session", "Run the pipeline" | □ |
+| `self-marketing-lint` | Remove self-marketing language from skill descriptions | "Description diet", "Strip the marketing tone" | □ |
+| `pipeline-conductor` | 4-axis quality gate (backward/adversarial/forward/record) | "Run the quality gate", "4-axis check" | □ |
+| `goal-quench` | `/goal` wrapper with token budget gate + pipeline-conductor verification | "Safe goal run", "Goal with budget control" | □ |
+| `edit-manifest` | Predict-verify loop for harness edits | "Log this edit", "Predict what this changes" | □ |
+| `memory-hygiene` | Detect stale memory entries + re-verify live | "Check stale memory", "Memory drift" | □ |
+| `prompt-regression` | Detect behavioral regressions after rule edits | "Did my rule change break anything?" | □ |
+| `convergence-loop` *(fh-commons)* | N-round convergence loops — only "truly passed" after convergence | "Suspicious of single-pass", "Convergence loop" | □ |
+| `token-budget-gate` *(fh-commons)* | Pre-task token cost estimate (GREEN/YELLOW/ORANGE/RED) | "How expensive is this?", "Token budget estimate" | □ |
+| `mcp-circuit-breaker` *(fh-commons)* | Detects MCP tool failure patterns, blocks further calls | "MCP keeps failing", "Tool error loop" | □ |
+| `quench-challenger` *(fh-commons)* | Pressure-tests near-final artifacts from adversarial angles | "Challenge this with a devil", "Quench challenger" | □ |
+
+| Count | Diagnosis |
+|:---:|---|
+| **28–36** | Advanced — focus on `agent-composer` + `sim-conductor` + `steel-quench` + `pipeline-conductor` chained |
+| **10–27** | Activation stage — gradually activate unchecked assets |
+| **0–9** | Early stage — go back to self-diagnosis above |
+
+</details>
+
+---
+
+## How it works
+
+```
+forge-harness (the brain — persistent hub)
+├── knowledge/   →  referenced from all projects
+└── tracks/      →  work records per project
+
+Project A (the execution site)
+  → connect hub in CLAUDE.md → auto-referenced
+
+Project B (the execution site)
+  → connect hub in CLAUDE.md → auto-referenced
+```
+
+- **From the hub**: invoke Claude Code → cross-project judgment with integrated context
+- **From each project**: project-specific work + hub reference
+- **"Hello"** → Claude automatically pulls recent context and today's tasks from the hub *(when running `claude` from the FH cwd)*
+
+```
+Search:  CATALOG.md (tags + summary) → open that file directly
+Store:   End of session → save to tracks/{project}/ → update CATALOG.md
+Return:  New pattern found → save to tracks/{project}/learnings/
+Share:   Common to 2+ projects → write to knowledge/shared/
+```
+
+---
+
+## Core usage
+
+| What you want | What to say |
+|---|---|
+| Start a session | "Hello" → reads hub, guides today's tasks |
+| Save session | "Sync this session to forge-harness" |
+| Search past work | "What did I do around April 13th?" |
+| Connect a new project | "Connect a project" |
+| Run adversarial review | "Run the quench on this" |
+| Run end-of-session harvest | "Harvest the session" |
+
+---
+
+## Agent dispatch
+
+forge-harness includes specialized agents and `agent-composer` to plan their optimal combination.
+
+```
+/agent-composer
+```
+
+Analyzes the current task and proposes which agents to dispatch in what order.
+
+### FH agents
+
+| Agent | Role | Tool restrictions |
+|---|---|---|
+| `plan` | Read-only design agent — analyzes files, maps impact, plans before implementation | Read·Bash·Glob·Grep only |
+| `fact-checker` | Asset deduplication and staleness check | Read·Grep·Glob |
+| `hub-persona-auditor` | 3+ persona audit of externally published assets | Read·Grep·Glob |
+| `persona-innovator` | Naming exploration + frame proposals | Read·Grep·Glob·WebSearch·WebFetch |
+| `quench-challenger` | Steel-quench adversary — pressure-tests near-final artifacts | Read·Grep·Glob |
+
+### Parallel dispatch
+
+Request two agents in a single message to run in parallel:
+
+```
+"Run fact-checker and persona-innovator in parallel.
+  First: check [asset path] for duplicates
+  Second: scan current harness for naming gaps"
+```
+
+> **Validated**: 6 background agents dispatched in parallel from meta-harness cwd → completed in ~3 minutes (~5× faster than sequential).
+
+---
+
+## Multi-Model Sidecar (v1.3)
+
+Each available AI CLI (Gemini, Codex, `gh copilot`) forms an independent review team alongside Claude. Cross-team synthesis surfaces Claude blind spots — issues external teams catch that single-model review misses. The sidecars act as **peer reviewers**, not primary orchestrators; skill invocation and harness automation remain Claude Code-native.
+
+**Coverage tiers (measured on `source-grounding-audit/SKILL.md`):**
+| Tier | Setup | Defects found |
+|---|---|---|
+| **C1** Single Claude persona | Default | 25% |
+| **C2** 3 cross-session Claude personas | No extra tools | 75% |
+| **C3** C2 + external CLI (Gemini/Codex/gh copilot) | External CLI installed | 100% — +3 Claude blind spots |
+
+Claude-side token cost: **zero increase** C2→C3. External CLI billed to its own quota.
+
+Decision rule: routine → C2, pre-publish → C3+.
+
+> **Corporate path**: `gh copilot` as sidecar (GitHub Copilot CLI, separate enterprise license). Requires headless operability — use `gh copilot -- -p "..." --allow-all-tools`. Note: CLI presence ≠ headless capable; verify with `--allow-all-tools` before adding to CI.
+
+---
+
+## Runtime requirements
+
+| Environment | Support | Notes |
+|---|---|---|
+| Claude Code + Anthropic API Key | ✅ Recommended | 200K context · officially supported |
+| claude.ai Pro / Team Plan | ✅ Recommended | 200K context · officially supported |
+| AWS Bedrock (direct API) | ⚠️ Conditional | Possible with sufficient account quota |
+| Bedrock + LiteLLM proxy | ⚠️ Unofficial | Frequent `Input is too long` errors |
+| Internal AI API proxy | ⚠️ Conditional | Depends on `max_input_tokens` config |
+
+---
+
+## Plugin install
+
+```bash
+claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
+claude plugin install -s user fh-meta@forge-harness
+```
+
+Verify: `/skills` or `/agents` in Claude Code chat. Updates aren't automatic — run `claude plugin update fh-meta@forge-harness` periodically.
+
+#### Plugin catalog
+
+| Plugin | Skills | Agents |
+|---|---|---|
+| **fh-meta** (v1.3) | 29 skills — agent-composer · apex-review · asset-placement-gate · contention-layer · context-bridge-dispatch · context-doctor · cross-ecosystem-synergy-detection · deep-clarify · edit-manifest · field-harvest · frontier-digest · goal-quench · harness-doctor · harvest-loop · hub-cc-pr-reviewer · install-doctor · install-wizard · marketplace-gate · memory-hygiene · meta-prompt-builder · pipeline-conductor · plugin-recommender · prompt-regression · self-marketing-lint · sim-conductor · source-grounding-audit · steel-quench · verify-bidirectional · and more | 3 (hub-persona-auditor · fact-checker · persona-innovator) |
+| **fh-commons** (v0.2.0) | 4 skills — convergence-loop · deliberation · mcp-circuit-breaker · token-budget-gate | 1 (quench-challenger) |
+
+#### Mode C (plugin only — no clone)
+
+```bash
+claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
+claude plugin install fh-meta@forge-harness
+cd ~/projects/{your-project} && claude
+```
+
+| Skill / area | Mode A (clone + plugin) | Mode C (plugin only) |
+|---|:---:|:---:|
+| `verify-bidirectional` · `apex-review` | ✅ hub baseline | ⚠️ no `knowledge/` |
+| `cross-ecosystem-synergy-detection` · `plugin-recommender` | ✅ hub cross-ref | ⚠️ your project only |
+| Meta/hub seed accumulation | ✅ `knowledge/shared/` | ❌ |
+
+#### Mode D — agent file copy only
+
+The lightest entry. Copy a single agent file to use immediately:
+
+```bash
+mkdir -p <your-project>/.claude/agents/
+cp <harness-root>/.claude/agents/fact-checker.md <your-project>/.claude/agents/
+```
+
+#### Connecting FH context to existing project CC
+
+```bash
+cp {FH_ROOT}/templates/local_fh_context.md .claude/rules/local_fh_context.md
+echo ".claude/rules/local_fh_context.md" >> .git/info/exclude
+```
+
+After this, `claude` in that project recognizes FH skills, session locations, and how to reference them. Token footprint: ~200 tokens (pointer file only).
+
+---
+
+## Token cost optimization
+
+**Native overhead** — measured: new install standalone ≈ 29K tokens (14.5% of 200K). Top 2 heaviest files: `.claude/rules/*.md` (~20K) and `CLAUDE.md` (~8.7K). `context-doctor` diagnoses and recommends keyword-trigger deferral for infrequently-used rules (saves 5–8K).
+
+**1. `.claudeignore` standard** — copy `templates/.claudeignore` to your project root. Defaults: `node_modules/` · `dist/` · `.next/` · `*.lock` · `*.min.js` · `.env`
+
+**2. Model switching** — `/model sonnet` (coding) · `/model opus` (reasoning) · `/model opusplan` (hybrid)
+
+**3. Agent view parallel execution** — `context-bridge-dispatch` auto-injects session context cards. 2+ independent tasks → parallel by default; 5–6× acceleration.
+
+**4. Automated audits** — terminal-start zshrc hook:
+
+```bash
+export FH_DIR="$HOME/path/to/forge-harness"
+source "$FH_DIR/templates/fh_audit_check.zsh"
+```
+
+---
+
+## Operating model — 3 Phase essence
+
+### Phase 1 — Initial setup (active onboarding)
+
+Greeting from the FH cwd → AI proactively proposes → asks about task → runs 5 skills → setup → hands off to project cwd.
+
+### Phase 2 — Backstage optimization
+
+User works from the **field project cwd**. The hub is not directly invoked but performs lateral optimization: `.claudeignore` applied, model switching active, fh-meta skills naturally activate from description triggers.
+
+### Phase 3 — Threshold return (autonomous proposals)
+
+When work matures and new skills or upgrades are possible, this AI **proactively proposes** returning to meta-harness from the field cwd.
+
+| Trigger | Signal |
+|---|---|
+| New generalizable pattern emerges | First discovery of a pattern worth promoting |
+| 3+ accumulated upgrades | Stabilization signal from the same asset evolving |
+| Sister asset absorption | External PR audit gate passed |
+
+### Command tower pattern (advanced)
+
+| Task type | Recommended location |
+|---|---|
+| Single project coding/debugging | That project's cwd |
+| Meta/audit/simulation | **Meta-harness cwd + Agent** |
+| 2+ projects simultaneously | **Meta-harness cwd + parallel Agent** |
+| field-harvest · PR audit · CATALOG updates | **Meta-harness cwd + Agent** |
+
+---
+
+## Steel-quench convergence — multi-layer defense
+
+| Layer | Mechanism |
+|:---:|---|
+| **L1** | harness-doctor + context-doctor + sim-conductor Area B — isolated third-person evaluation |
+| **L2** | Real user feedback + external PR review — evidence generated outside owner environment |
+| **L3** | steel-quench pre-runs attack angles internally; flaws patched before external devils run |
+| **L4** | Meta-aware adversary — remaining attack surface shrinks per wave |
+
+---
+
+## Research & external validation
+
+> **FH v1.0 paper** — published 2026-05-30 on [Zenodo](https://zenodo.org/records/20397566) (DOI: 10.5281/zenodo.20397566) · arXiv submission in review. Documents the 2-layer design, 6-axis framework, 4-agent orchestration, and compounding loop with controlled empirical evidence.
+
+Three independent research findings converge on the same layer:
+- VILA-Lab analysis of Claude Code v2.1.88 (512K lines): [98.4% is harness infrastructure, 1.6% AI logic](https://arxiv.org/abs/2604.14228)
+- "[Code as Agent Harness](https://arxiv.org/abs/2605.18747)" (arXiv, May 2026, 43 authors)
+- Stanford IRIS Lab: "[Meta-Harness](https://arxiv.org/abs/2603.28052)" (Lee et al., Mar 2026) — outer-loop harness optimization; +7.7pts at 4× fewer tokens
+
+The Stanford paper also inspired [harness-evolver](https://github.com/raphaelchristi/harness-evolver) (fully automated CODE optimizer). FH converged on the same loop architecture from the opposite direction — complementary, not competing. See `knowledge/shared/harness-core/fh_ecosystem_positioning.md`.
+
+---
+
+## Learn more
+
+- `CLAUDE.md` — Sync/Push protocol · AI operating rules
+- `AGENTS.md` — Runtime agent specs
+- `CATALOG.md` — Search index
+- `CHEATSHEET.md` — Full command reference
+- `CONTRIBUTING.md` — How to contribute skills and patterns
+- `knowledge/shared/harness-core/fh_integration_contract.md` — Governance layer spec
+
+---
+
+## Appendix
+
+### Directory structure
+
+```
+forge-harness/
+├── knowledge/             # Pure knowledge — time-independent, for reference
+│   ├── domain/            # Domain-specific knowledge
+│   └── shared/            # Cross-project patterns
+│
+├── tracks/                # Work records per project — time-accumulated
+│   └── {project_name}/
+│       ├── session_*.md   # Session history
+│       └── learnings/     # Accumulated feedback
+│
+├── plugins/               # fh-meta + fh-commons plugins
+├── templates/             # Skeletons to copy for new projects
+├── scripts/               # fh-gate.sh and automation scripts
+├── docs/                  # Diagrams and reference assets
+├── CATALOG.md             # Full search index
+├── CLAUDE.md              # AI operating rules + Sync/Push protocol
+└── CHEATSHEET.md          # Command cheat sheet
+```
+
+### Key terms
+
+| Term | Definition |
+|---|---|
+| **Meta-harness** | A persistent hub connecting work, learnings, and patterns of N Claude Code projects for mutual reinforcement |
+| **Launch pad effect** | Meta-harness as launch pad, not destination — passing through accelerates the starting line |
+| **Shared skill pool** | Common skill/agent pool eliminating reinvention cost across teams and projects |
+| **Environment engineering** | Not making the agent smarter, but making the environment easier for the agent to work in |
+| **Harness engineering** | Per-project structures (rules, gates, context management) that make AI behave more consistently |
+| **Meta harness engineering** | Cross-project system to measure, improve, and evolve harnesses — FH's core layer |

package/bin/fh-gate

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec "$SCRIPT_DIR/scripts/fh-gate.sh" "$@"

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

@@ -0,0 +1,328 @@
+---
+name: fh-integration-contract
+description: FH governance gate interface specification — inputs, verdict format, findings schema, invocation patterns. Bridge layer item 3. Defines how OpenCode, OpenHuman, Hermes, and CI systems call FH gates and receive structured verdicts.
+date: 2026-05-31
+tags: [integration-contract, governance, opencode, hermes, openhuman, bridge-layer, v2-paper]
+---
+
+# FH Integration Contract
+
+## Status
+
+**v1.0 — Binary available.** `scripts/fh-gate.sh` executes governance review end-to-end via `claude --print`.
+CI-ready: machine-parseable verdict + exit codes (0=PASS / 1=PENDING / 2=BLOCKED / 3=ESCALATE / 10=harness error).
+Backward-compatible: `FH_DRY_RUN=1` restores prompt-only (v0.1) behavior.
+
+---
+
+## The Interface in One Diagram
+
+```
+Caller (OpenCode / OpenHuman / Hermes / CI)
+    │
+    │  provides: file list + diff path + gate level + caller ID
+    ▼
+FH governance gate (steel-quench + pipeline-conductor)
+    │
+    │  returns: verdict + findings list + record path
+    ▼
+Caller reads verdict, decides: merge / hold / escalate
+```
+
+---
+
+## Input Specification
+
+### Required
+
+| Input | Form | Description |
+|---|---|---|
+| `FH_TARGET_FILES` | newline-separated file paths (one per line) | Files to review (changed by caller). Use newlines, not spaces — space-separation breaks on paths with spaces. |
+| `FH_CALLER` | string | Identifier of calling system (`opencode` · `hermes` · `openhuman` · `ci`) |
+| `FH_GATE_LEVEL` | `quick` or `full` | `quick` = Axes 2+3 only; `full` = all 4 axes |
+
+### Optional
+
+| Input | Form | Description |
+|---|---|---|
+| `FH_DIFF_PATH` | file path | Pre-generated diff file (skips Step 1 if provided) |
+| `FH_TASK_DESCRIPTION` | string | What the caller was trying to accomplish (context for adversarial pass) |
+| `FH_SECURITY_LENS` | `on` or `off` (default `off`) | Force security-adjacent focus in steel-quench |
+
+### Capture pattern (caller's responsibility)
+
+```bash
+# Caller generates these before invoking FH:
+# Note: newline-separated — do NOT use tr '\n' ' ' (breaks on paths with spaces)
+FH_TARGET_FILES=$(git diff main..HEAD --name-only)
+FH_DIFF_PATH=/tmp/fh_input_${FH_CALLER}_$(date +%Y%m%d_%H%M%S).diff
+git diff main..HEAD > "$FH_DIFF_PATH"
+FH_GATE_LEVEL=quick
+FH_CALLER=opencode
+```
+
+---
+
+## Verdict Specification
+
+### Verdict values
+
+| Verdict | Meaning | Caller action |
+|---|---|---|
+| `PASS` | No findings. Axes all green. | Proceed to merge / ship |
+| `PENDING` | 1+ B-grade findings, or Axis 3/4 weak. No A-grade. | Proceed with awareness; log findings |
+| `BLOCKED` | 1+ A-grade findings. Structural or security-critical. | Do not merge. Surface to developer. Re-run governance after fix. |
+| `ESCALATE` | Ambiguous A-grade or out-of-scope for automated verdict. | Human decision required before merge. |
+
+### Output format
+
+FH writes verdict to stdout as structured text (human-readable + machine-parseable).
+`FH_STATUS` is MANDATORY — it MUST precede the verdict so callers detect harness failures (LLM timeout, token exhaustion) that would otherwise silently appear as PASS.
+
+```
+FH_STATUS: SUCCESS
+FH_GATE_VERDICT: PENDING
+FH_CALLER: opencode
+FH_TIMESTAMP: 2026-05-31T12:00:00Z
+FH_FINDINGS_COUNT: 3
+FH_FINDINGS_A: 2
+FH_FINDINGS_B: 1
+FH_RECORD_PATH: tracks/_meta/governance_log_2026-05-31.yaml
+---
+findings:
+  - grade: A
+    location: "prefix() lines 1-9"
+    title: "Short-token overflow — allowlist pattern may not cover bare commands"
+    evidence: "tokens.slice(0, arity) with arity=3 and len=2 returns 2 tokens; pattern 'git stash *' may not match bare 'git stash'"
+    fix: "Add test: expect(BashArity.prefix(['git', 'stash'])).toEqual(['git', 'stash']); add explicit comment that slice handles overflow"
+  - grade: A
+    location: "ARITY table lines 24-161"
+    title: "npx/opencode/claude absent — overly broad permission patterns"
+    evidence: "All npx <package> commands receive same 'npx *' pattern; security model weakened"
+    fix: "Add: npx: 2, opencode: 2, claude: 2, bunx: 2, uvx: 2"
+```
+
+**Key design decisions** (addressing Gemini Finding 1+2):
+- Findings use YAML block (under `findings:` key) — NOT flat `FINDING_N_KEY: value`. This prevents delimiter ambiguity when `evidence` or `fix` spans multiple lines.
+- `FH_STATUS: SUCCESS|ERROR` is mandatory first field — a missing or `ERROR` status means the harness itself failed (do NOT interpret as PASS).
+
+### Parse recipe (for CI/CD integration)
+
+```bash
+# Parse verdict from FH output (file or stdin)
+FH_OUT=$(cat /tmp/fh_verdict.txt)
+STATUS=$(echo "$FH_OUT" | grep "^FH_STATUS:" | awk '{print $2}')
+VERDICT=$(echo "$FH_OUT" | grep "^FH_GATE_VERDICT:" | awk '{print $2}')
+A_COUNT=$(echo "$FH_OUT" | grep "^FH_FINDINGS_A:" | awk '{print $2}')
+
+# Guard: treat harness failure as BLOCKED (fail-safe)
+if [ "$STATUS" != "SUCCESS" ]; then
+  echo "FH harness error — treating as BLOCKED (fail-safe)"
+  exit 1
+fi
+
+if [ "$VERDICT" = "BLOCKED" ] || [ "${A_COUNT:-0}" -gt "0" ]; then
+  echo "FH governance: BLOCKED — do not merge"
+  exit 1
+fi
+```
+
+---
+
+## Invocation Patterns
+
+### Pattern 1 — Manual invocation from Claude Code session
+
+The primary form until binary is available. Run inside a Claude Code session:
+
+```
+Run FH governance pass (gate level: quick):
+  Target files: $FH_TARGET_FILES
+  Caller: opencode
+  Security lens: on (arity.ts is permission-adjacent)
+
+Steps:
+  1. Read each file in target list
+  2. Run steel-quench adversarial pass — behavioral edge cases, untested contracts, security assumptions
+  3. Run pipeline-conductor --quick — 4-axis verdict
+  4. Output structured verdict in FH_GATE_VERDICT format
+  5. Log to tracks/_meta/governance_log_{date}.yaml
+```
+
+### Pattern 2 — Bash wrapper (approximation, no binary)
+
+```bash
+#!/usr/bin/env bash
+# scripts/fh-gate.sh — FH governance wrapper (methodology layer only)
+# Outputs a governance prompt to stdout for Claude Code to execute
+
+set -euo pipefail
+
+FH_TARGET_FILES="${1:-$(git diff main..HEAD --name-only | tr '\n' ' ')}"
+FH_GATE_LEVEL="${2:-quick}"
+FH_CALLER="${3:-unknown}"
+
+cat <<EOF
+Run FH governance pass on: $FH_TARGET_FILES
+Gate level: $FH_GATE_LEVEL | Caller: $FH_CALLER
+
+Step 1: Read all target files
+Step 2: steel-quench adversarial pass (behavioral edge cases, untested contracts, security assumptions)
+Step 3: pipeline-conductor --$FH_GATE_LEVEL (4-axis: backward / adversarial / forward / record)
+Step 4: Output in FH_GATE_VERDICT format (PASS / PENDING / BLOCKED / ESCALATE)
+Step 5: Write findings to tracks/_meta/governance_log_$(date +%Y-%m-%d).yaml
+EOF
+```
+
+Usage: `./scripts/fh-gate.sh "src/permission/arity.ts" quick opencode`
+
+### Pattern 3 — Stop hook (automated post-session)
+
+Add to project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "bash ~/projects/forge-harness/scripts/fh-gate.sh \"$(git diff main..HEAD --name-only | tr '\\n' ' ')\" quick auto >> /tmp/fh-governance-queue.txt"
+      }]
+    }]
+  }
+}
+```
+
+Check queue on next session start: `cat /tmp/fh-governance-queue.txt`
+
+---
+
+## Caller-Specific Guidance
+
+### OpenCode → FH
+
+OpenCode generates code fast. FH governance runs after generation, before review.
+
+```bash
+# After opencode run completes:
+FH_TARGET_FILES=$(git diff main..HEAD --name-only | tr '\n' ' ')
+FH_SECURITY_LENS=on  # OpenCode touches broad surfaces; security lens default on
+FH_GATE_LEVEL=quick
+```
+
+Full chain: `hermes.opencode` → code generated → `fh-gate.sh` → verdict → `hermes.github-code-review` → PR with governance findings inline.
+
+### Hermes → FH
+
+Hermes dispatches FH governance as a step in multi-agent pipelines:
+
+```
+# In hermes skill workflow:
+After code generation step:
+  → Dispatch FH governance: Read fh-gate.sh, execute with target_files=$CHANGED
+  → If verdict=BLOCKED: halt pipeline, surface findings to user
+  → If verdict=PENDING: attach findings to PR body, continue
+  → If verdict=PASS: proceed to github-code-review step
+```
+
+See `hermes-agent/skills/autonomous-ai-agents/opencode/SKILL.md` for the full Hermes→OpenCode→FH chain.
+
+### OpenHuman → FH
+
+OpenHuman's Memory Tree stores conversation history. FH audit target: memory entries that reference code paths or technical decisions.
+
+```bash
+# FH harvest-loop on OpenHuman memory:
+FH_TARGET_FILES=$(find ~/.openhuman/memory -name "*.md" -newer tracks/_meta/last_harvest.marker)
+FH_GATE_LEVEL=quick
+FH_CALLER=openhuman
+```
+
+FH validates: are memory entries grounded? Do referenced paths still exist? Are technical claims still accurate?
+
+### CI/CD → FH
+
+Post-merge governance for AI-generated modules:
+
+```yaml
+# .github/workflows/fh-governance.yml (future)
+on:
+  pull_request:
+    paths: ['**/*.ts', '**/*.py']
+
+jobs:
+  fh-governance:
+    steps:
+      - uses: actions/checkout@v4
+      - name: FH governance gate
+        run: |
+          CHANGED=$(git diff origin/main..HEAD --name-only | tr '\n' ' ')
+          bash scripts/fh-gate.sh "$CHANGED" quick ci
+```
+
+---
+
+## Record Specification
+
+Every governance pass writes a record entry:
+
+```yaml
+# tracks/_meta/governance_log_YYYY-MM-DD.yaml
+- timestamp: 2026-05-31T12:00:00Z
+  caller: opencode
+  gate_level: quick
+  target_files:
+    - packages/opencode/src/permission/arity.ts
+  verdict: PENDING
+  findings:
+    - grade: A
+      location: "prefix() lines 1-9"
+      title: "Short-token overflow"
+    - grade: A
+      location: "ARITY table lines 24-161"
+      title: "npx/opencode/claude absent"
+    - grade: B
+      location: "ARITY table + generation comment"
+      title: "No maintenance protocol"
+  calibration:
+    predicted_findings: 2
+    actual_findings: 3
+    delta: +1
+```
+
+Record path is included in every verdict output as `FH_RECORD_PATH`. This feeds `harvest-loop` calibration.
+
+---
+
+## What This Contract Does NOT Specify (Bridge Layer v1.0)
+
+The following require the bridge layer and are out of scope for v0.1:
+
+| Feature | Why deferred |
+|---|---|
+| Binary / installable package | FH is methodology layer; no runtime distribution yet |
+| REST API or webhook | Would require a server process — FH is file-based |
+| Streaming verdict updates | Requires runtime; methodology layer is synchronous |
+| Multi-file parallel governance | Possible via agent dispatch today; not formalized here |
+| Verdict caching | No state store beyond `tracks/`; governance runs fresh each time |
+
+The bridge layer (v1.0) will implement these. This contract is the specification they implement against.
+
+---
+
+## Version History
+
+| Version | Date | Change |
+|---|---|---|
+| v0.1 | 2026-05-31 | Initial specification. Bash invocation patterns + structured verdict format. Empirical basis: arity.ts controlled trial. |
+
+---
+
+## References
+
+- `fh_opencode_governance_wrapper.md` — step-by-step usage guide (less formal, more tutorial)
+- `fh_ecosystem_positioning.md` — ecosystem context + synergy map + v2 paper connection
+- `tracks/_meta/fh_opencode_governance_experiment_2026_05_31.md` — empirical basis for verdict format
+- `multi_model_sidecar_strategy.md` — multi-model orchestration (related pattern)
+- FH paper (Zenodo: 10.5281/zenodo.20397566) — harness-as-durable-layer thesis this contract operationalizes

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@chrono-meta/fh-gate",
+  "version": "1.0.0",
+  "description": "FH governance gate — runs structured AI code review via claude --print and returns machine-parseable verdicts (PASS/PENDING/BLOCKED/ESCALATE).",
+  "license": "MIT",
+  "keywords": [
+    "ai-governance",
+    "code-review",
+    "claude",
+    "claude-code",
+    "ci",
+    "harness"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chrono-meta/forge-harness.git"
+  },
+  "bin": {
+    "fh-gate": "./bin/fh-gate"
+  },
+  "scripts": {
+    "prepare": "chmod +x bin/fh-gate scripts/fh-gate.sh"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-code": "*"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-code": {
+      "optional": false
+    }
+  },
+  "files": [
+    "bin/fh-gate",
+    "scripts/fh-gate.sh",
+    "knowledge/shared/harness-core/fh_integration_contract.md",
+    "README.md"
+  ]
+}

package/scripts/fh-gate.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# fh-gate.sh — FH governance gate v1.0
+#
+# Executes governance review end-to-end via claude --print.
+# CI-ready: machine-parseable verdict + exit codes.
+#
+# Usage:
+#   ./scripts/fh-gate.sh [FILES] [LEVEL] [CALLER]
+#   ./scripts/fh-gate.sh                              # auto-detect from git diff
+#   ./scripts/fh-gate.sh "src/foo.ts src/bar.ts"     # explicit files
+#   ./scripts/fh-gate.sh "src/foo.ts" full opencode  # explicit level + caller
+#
+# Exit codes:
+#   0  — PASS      (no findings)
+#   1  — PENDING   (B-grade findings; proceed with awareness)
+#   2  — BLOCKED   (A-grade findings; do not merge)
+#   3  — ESCALATE  (human decision required)
+#   10 — Harness error (claude unavailable, timeout, or FH_STATUS != SUCCESS)
+#   11 — Argument error (invalid level, no files)
+#
+# Environment:
+#   FH_DRY_RUN=1        generate prompt only, skip claude invocation (v0.1 behavior)
+#   FH_MODEL=<model>    claude model to use (default: claude-sonnet-4-6)
+#   FH_TIMEOUT=120      seconds before claude --print is killed (default: 120)
+#   FH_VERBOSE=1        print full claude output to stderr
+#   FH_RECORD_BASE=<p>  directory for governance_log YAML (default: FH_ROOT/tracks/_meta)
+
+set -euo pipefail
+
+VERSION="1.0.0"
+FH_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+_TMPDIR="${TMPDIR:-/tmp}"
+
+EXIT_PASS=0
+EXIT_PENDING=1
+EXIT_BLOCKED=2
+EXIT_ESCALATE=3
+EXIT_HARNESS_ERROR=10
+EXIT_ARG_ERROR=11
+
+TARGET_FILES="${1:-}"
+GATE_LEVEL="${2:-quick}"
+FH_CALLER="${3:-ci}"
+
+FH_DRY_RUN="${FH_DRY_RUN:-0}"
+FH_MODEL="${FH_MODEL:-claude-sonnet-4-6}"
+FH_TIMEOUT="${FH_TIMEOUT:-120}"
+FH_VERBOSE="${FH_VERBOSE:-0}"
+
+# Smart record base: FH repo → tracks/_meta/; standalone npm install → ~/.fh/logs/
+if [[ -z "${FH_RECORD_BASE:-}" ]]; then
+  if [[ -d "${FH_ROOT}/tracks/_meta" ]]; then
+    FH_RECORD_BASE="${FH_ROOT}/tracks/_meta"
+  else
+    FH_RECORD_BASE="${HOME}/.fh/logs"
+    mkdir -p "$FH_RECORD_BASE"
+  fi
+fi
+
+# --- Validation ---
+if [[ "$GATE_LEVEL" != "quick" && "$GATE_LEVEL" != "full" ]]; then
+  echo "ERROR: gate level must be 'quick' or 'full' (got: $GATE_LEVEL)" >&2
+  exit $EXIT_ARG_ERROR
+fi
+
+# Auto-detect files from git diff (B1: configurable base branch)
+FH_BASE_BRANCH="${FH_BASE_BRANCH:-main}"
+if [[ -z "$TARGET_FILES" ]]; then
+  TARGET_FILES=$(git -C "$FH_ROOT" diff "${FH_BASE_BRANCH}..HEAD" --name-only 2>/dev/null | tr '\n' ' ' | xargs || true)
+  if [[ -z "$TARGET_FILES" ]]; then
+    TARGET_FILES=$(git -C "$FH_ROOT" status --short 2>/dev/null | awk '{print $2}' | tr '\n' ' ' | xargs || true)
+  fi
+fi
+
+if [[ -z "$TARGET_FILES" ]]; then
+  echo "ERROR: no files found (git diff returned empty; pass files explicitly)" >&2
+  exit $EXIT_ARG_ERROR
+fi
+
+# Security lens auto-detect
+SECURITY_LENS="off"
+if echo "$TARGET_FILES" | grep -qiE "(permission|auth|token|secret|key|cred|security|vulnerability|csrf|inject|sanitize)"; then
+  SECURITY_LENS="on"
+fi
+
+TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%SZ)
+RECORD_PATH="${FH_RECORD_BASE}/governance_log_$(date +%Y-%m-%d).yaml"
+PROMPT_FILE=$(mktemp "${_TMPDIR}/fh_gate_prompt_XXXXXX.txt")
+OUTPUT_FILE=$(mktemp "${_TMPDIR}/fh_gate_output_XXXXXX.txt")
+ERR_FILE=$(mktemp "${_TMPDIR}/fh_gate_err_XXXXXX.txt")
+
+# Pre-compute values that need transformation (bash 3.2 compat — no ${VAR^^})
+GATE_LEVEL_UPPER=$(echo "$GATE_LEVEL" | tr '[:lower:]' '[:upper:]')
+FILES_LIST=$(echo "$TARGET_FILES" | tr ' ' '\n' | grep -v '^$' | sed 's/^/  - /')
+SECURITY_EXTRA=""
+[ "$SECURITY_LENS" = "on" ] && SECURITY_EXTRA=", permission model gaps"
+
+if [ "$GATE_LEVEL" = "quick" ]; then
+  AXES_BLOCK="  - Axis 2 (Adversarial): findings from Step 2
+  - Axis 3 (Forward): phantom references, broken paths, stale claims"
+else
+  AXES_BLOCK="  - Axis 1 (Backward): regression risk vs prior version
+  - Axis 2 (Adversarial): findings from Step 2
+  - Axis 3 (Forward): phantom references, broken paths, stale claims
+  - Axis 4 (Record): calibration log entry"
+fi
+
+cleanup() { rm -f "$PROMPT_FILE" "$OUTPUT_FILE" "$ERR_FILE"; }
+trap cleanup EXIT
+
+# --- Build prompt ---
+cat > "$PROMPT_FILE" <<PROMPT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+FH GOVERNANCE GATE v${VERSION} — ${GATE_LEVEL_UPPER} PASS
+Caller: ${FH_CALLER} | Timestamp: ${TIMESTAMP}
+Security lens: ${SECURITY_LENS}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Target files:
+${FILES_LIST}
+
+Execute these steps in order:
+
+Step 1 — Read all target files listed above.
+
+Step 2 — Adversarial pass (steel-quench angles):
+  Focus: behavioral edge cases, untested contracts, security assumptions${SECURITY_EXTRA}
+  Find findings and grade each: A=blocking / B=warning / C=note.
+
+Step 3 — pipeline-conductor --${GATE_LEVEL}:
+${AXES_BLOCK}
+
+Step 4 — Output structured verdict. EXACT FORMAT REQUIRED (machine-parsed):
+
+FH_STATUS: SUCCESS
+FH_GATE_VERDICT: [PASS|PENDING|BLOCKED|ESCALATE]
+FH_CALLER: ${FH_CALLER}
+FH_TIMESTAMP: ${TIMESTAMP}
+FH_FINDINGS_COUNT: [N]
+FH_FINDINGS_A: [N]
+FH_FINDINGS_B: [N]
+FH_RECORD_PATH: ${RECORD_PATH}
+---
+findings:
+  - grade: [A|B|C]
+    location: "[file:line or function name]"
+    title: "[one-line description]"
+    evidence: "[what was observed in the file]"
+    fix: "[concrete suggestion]"
+
+Verdict rules:
+  A-grade present → BLOCKED
+  B-grade only    → PENDING
+  No findings     → PASS
+  Ambiguous A     → ESCALATE
+
+FH_STATUS MUST appear first. Missing or ERROR status = harness failure.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PASS=ship | PENDING=proceed with awareness | BLOCKED=fix first | ESCALATE=human decision
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PROMPT
+
+# --- Dry-run: prompt to stdout only (v0.1 behavior) ---
+if [[ "$FH_DRY_RUN" == "1" ]]; then
+  cat "$PROMPT_FILE"
+  exit $EXIT_PASS
+fi
+
+# --- Require claude CLI ---
+if ! command -v claude &>/dev/null; then
+  echo "ERROR: 'claude' CLI not found." >&2
+  echo "  Install: https://claude.ai/code" >&2
+  echo "  Prompt-only mode: FH_DRY_RUN=1 $0 $*" >&2
+  exit $EXIT_HARNESS_ERROR
+fi
+
+# --- Invoke ---
+echo "→ fh-gate v${VERSION} [${GATE_LEVEL_UPPER}] caller=${FH_CALLER} security=${SECURITY_LENS}" >&2
+echo "  files: ${TARGET_FILES}" >&2
+
+# Use gtimeout (macOS coreutils) if available, fall back to timeout, then bare invoke
+_TIMEOUT_CMD=""
+if command -v gtimeout &>/dev/null; then
+  _TIMEOUT_CMD="gtimeout ${FH_TIMEOUT}"
+elif command -v timeout &>/dev/null; then
+  _TIMEOUT_CMD="timeout ${FH_TIMEOUT}"
+fi
+
+if ! ${_TIMEOUT_CMD} claude --print --model "$FH_MODEL" < "$PROMPT_FILE" > "$OUTPUT_FILE" 2>"$ERR_FILE"; then
+  echo "ERROR: claude --print failed or timed out (${FH_TIMEOUT}s)" >&2
+  cat "$ERR_FILE" >&2
+  exit $EXIT_HARNESS_ERROR
+fi
+
+[[ "$FH_VERBOSE" == "1" ]] && cat "$ERR_FILE" >&2
+
+# --- Parse verdict (B3: -m 1 prevents concatenation on repeated header lines) ---
+FH_STATUS=$(grep -m 1 "^FH_STATUS:" "$OUTPUT_FILE" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || true)
+VERDICT=$(grep -m 1 "^FH_GATE_VERDICT:" "$OUTPUT_FILE" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || true)
+
+# Harness failure guard (fail-safe: missing status → BLOCKED)
+if [[ "$FH_STATUS" != "SUCCESS" ]]; then
+  echo "ERROR: FH_STATUS=${FH_STATUS:-MISSING} — harness failure (fail-safe: BLOCKED)" >&2
+  cat "$OUTPUT_FILE" >&2
+  exit $EXIT_HARNESS_ERROR
+fi
+
+# Emit structured output to stdout
+cat "$OUTPUT_FILE"
+
+# B4: Write governance log — structured header only (clean YAML, no raw markdown)
+FINDINGS_A_LOG=$(grep -m 1 "^FH_FINDINGS_A:" "$OUTPUT_FILE" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || echo "0")
+FINDINGS_B_LOG=$(grep -m 1 "^FH_FINDINGS_B:" "$OUTPUT_FILE" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || echo "0")
+FINDINGS_N_LOG=$(grep -m 1 "^FH_FINDINGS_COUNT:" "$OUTPUT_FILE" 2>/dev/null | awk '{print $2}' | tr -d '[:space:]' || echo "0")
+{
+  printf -- "- timestamp: %s\n" "$TIMESTAMP"
+  printf "  caller: %s\n" "$FH_CALLER"
+  printf "  gate_level: %s\n" "$GATE_LEVEL"
+  printf "  verdict: %s\n" "$VERDICT"
+  printf "  findings_total: %s\n" "$FINDINGS_N_LOG"
+  printf "  findings_a: %s\n" "$FINDINGS_A_LOG"
+  printf "  findings_b: %s\n" "$FINDINGS_B_LOG"
+  printf "  files:\n"
+  echo "$TARGET_FILES" | tr ' ' '\n' | grep -v '^$' | sed 's/^/    - /'
+  printf "\n"
+} >> "$RECORD_PATH" || echo "WARN: governance log write failed: $RECORD_PATH" >&2
+
+# Exit code
+case "$VERDICT" in
+  PASS)     echo "→ verdict: PASS" >&2;     exit $EXIT_PASS ;;
+  PENDING)  echo "→ verdict: PENDING" >&2;  exit $EXIT_PENDING ;;
+  BLOCKED)  echo "→ verdict: BLOCKED" >&2;  exit $EXIT_BLOCKED ;;
+  ESCALATE) echo "→ verdict: ESCALATE" >&2; exit $EXIT_ESCALATE ;;
+  *)
+    echo "ERROR: unrecognized verdict '${VERDICT:-EMPTY}' — fail-safe BLOCKED" >&2
+    exit $EXIT_HARNESS_ERROR
+    ;;
+esac