@chrono-meta/fh-gate 1.1.0 → 1.2.1

package/README.md

@@ -1,12 +1,13 @@
 <p align="center">
-  <img src="docs/banner.png" alt="forge-harness — A forkable Claude Code meta-harness for multi-project teams" width="680">
+  <img src="https://raw.githubusercontent.com/chrono-meta/forge-harness/main/docs/banner.png" alt="forge-harness — A forkable Claude Code meta-harness for multi-project teams" width="680">
 </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">
+  <img src="https://img.shields.io/badge/fh--gate-v1.2.0-3b82f6.svg" alt="fh-gate v1.2.0">
   <a href="https://zenodo.org/records/20397566"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20397566-blue.svg" alt="DOI"></a>
   <img src="https://img.shields.io/badge/Claude_Code-compatible-a855f7.svg" alt="Claude Code">
+  <img src="https://img.shields.io/badge/Codex-beta-f59e0b.svg" alt="Codex-compatible beta">
   <a href="https://www.npmjs.com/package/@chrono-meta/fh-gate"><img src="https://img.shields.io/npm/v/@chrono-meta/fh-gate.svg?color=cb3837" alt="npm"></a>
 </p>
 
@@ -55,6 +56,7 @@ claude
 
 **Plugin only (no clone):**
 ```bash
+claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git  # once
 claude plugin install -s user fh-meta@forge-harness
 cd ~/projects/{your-project} && claude
 ```
@@ -88,18 +90,36 @@ Project B  ──→  connect hub in CLAUDE.md
 FH wraps any coding agent (OpenCode, Codex, etc.) as a **post-generation governance gate**.
 
 ```bash
-npx @chrono-meta/fh-gate                    # auto-detects changed files
-npx @chrono-meta/fh-gate "src/foo.ts" full  # explicit file + full pass
+npx --package @chrono-meta/fh-gate fh-gate                    # default: Claude backend
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-gate   # Codex backend
+FH_BACKEND=auto npx --package @chrono-meta/fh-gate fh-gate "src/foo.ts" full
 # → FH_GATE_VERDICT: PASS | PENDING | BLOCKED | ESCALATE
 ```
 
-**Empirical result (2026-05-31)**: Applied to OpenCode's AI-generated `permission/arity.ts` (163 lines, CI green). Verdict: PENDING — 2 A-grade findings CI didn't catch (short-token overflow in allowlist, executor tools absent from arity table).
+`fh-gate` uses the same FH governance prompt for both runtimes. `FH_BACKEND=claude` runs `claude --print`; `FH_BACKEND=codex` runs `codex exec`; `FH_BACKEND=auto` prefers Codex when both CLIs are present.
+
+For direct skill or agent execution outside Claude Code, use `fh-run`:
+
+```bash
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --skill source-grounding-audit --file docs/foo.md
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --agent fh-commons:quench-challenger --file plugins/fh-meta/skills/foo/SKILL.md
+```
+
+For Codex-primary work, keep using Codex's native goal/session features when available. `fh-goal` is only a portable wrapper for one-off non-interactive runs that should be followed by FH governance:
+
+```bash
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-goal --prompt "Implement X and update tests" --gate quick
+```
+
+The broader FH automation layer still depends on Claude Code for sub-agents, hooks, and slash commands. The portable path is shared documents plus runtime adapters, not separate Codex and Claude forks.
+
+**Empirical result (2026-05-31)**: Applied to OpenCode's AI-generated `permission/arity.ts` (163 lines, CI green). Current gate semantics classify this as BLOCKED: 2 A-grade findings CI didn't catch (short-token overflow in allowlist, executor tools absent from arity table).
 
 Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integration_contract.md)
 
 ---
 
-## 36 skills, 5 agents
+## 35 skill files, 5 agents
 
 <details>
 <summary>Full asset activation check</summary>
@@ -129,7 +149,7 @@ Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integ
 | `token-budget-gate` *(fh-commons)* | Pre-task token cost estimate | "How expensive is this?" |
 | `mcp-circuit-breaker` *(fh-commons)* | MCP tool failure pattern detection | "MCP keeps failing" |
 | `quench-challenger` *(fh-commons)* | Adversarial pressure-test agent | "Challenge this with a devil" |
-| *(+ 13 more)* | marketplace-gate · contention-layer · context-bridge-dispatch · edit-manifest · fact-checker · goal-quench · hub-persona-auditor · install-doctor · memory-hygiene · persona-innovator · prompt-regression · self-marketing-lint · skill-splitter | |
+| *(+ additional assets)* | marketplace-gate · contention-layer · edit-manifest · fact-checker · goal-quench · hub-persona-auditor · install-doctor · memory-hygiene · persona-innovator · prompt-regression · public-surface-audit · skill-splitter | |
 
 | Active count | Diagnosis |
 |:---:|---|
@@ -137,10 +157,43 @@ Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integ
 | **10–27** | Activation stage — gradually enable unchecked assets |
 | **0–9** | Early stage — start with `install-wizard` |
 
+**Find a skill by what you're trying to do:**
+
+| Cluster | Skills |
+|---|---|
+| Verification | `steel-quench` · `source-grounding-audit` · `convergence-loop` · `prompt-regression` · `return-path-gate` |
+| Orchestration | `agent-composer` · `pipeline-conductor` · `goal-quench` · `deliberation` |
+| Diagnosis | `harness-doctor` · `context-doctor` · `install-doctor` · `mcp-circuit-breaker` |
+| Harvesting / Learning | `harvest-loop` · `field-harvest` · `edit-manifest` · `memory-hygiene` |
+| Gate / Guard | `token-budget-gate` · `asset-placement-gate` · `marketplace-gate` |
+| Discovery | `plugin-recommender` · `cross-ecosystem-synergy-detection` · `frontier-digest` · `verify-bidirectional` |
+| Content / Simulation | `sim-conductor` · `apex-review` · `meta-prompt-builder` · `deep-clarify` |
+| Setup | `install-wizard` · `hub-cc-pr-reviewer` · `skill-splitter` |
+
 </details>
 
 ---
 
+## Model setup
+
+Claude Code does not auto-select models by task complexity — you configure this once.
+
+```bash
+/model opusplan   # recommended for forge-harness
+```
+
+| Command | Who runs what | Best for |
+|---|---|---|
+| `/model sonnet` | Sonnet handles everything | Fast coding, simple tasks |
+| `/model opus` | Opus handles everything | Complex reasoning, architecture |
+| `/model opusplan` | **Opus plans · Sonnet executes** | FH orchestration + sub-agents |
+
+**Why `opusplan` for FH**: CC switches models per-turn based on task weight — Opus activates for plan-mode turns (complex reasoning, decomposition decisions), Sonnet handles execution turns (tool calls, file edits, bash). forge-harness orchestration leans on both: Opus for design decisions in agent-composer / goal-quench / steel-quench, Sonnet for the actual file edits and sub-agent execution contexts. Sub-agent token costs are CC-visible and appear in the session jsonl under `message.model`.
+
+If you use external CLIs (Gemini, Codex, `gh copilot`) as sidecars, their costs are billed to their own quota and not visible in CC's token display.
+
+---
+
 ## Multi-Model Sidecar (v1.3)
 
 Run Gemini, Codex, or `gh copilot` as independent peer reviewers alongside Claude.
@@ -161,7 +214,7 @@ Claude-side token cost: **zero increase** C2→C3.
 > Documents 2-layer design, 6-axis framework, 4-agent orchestration, and compounding loop with empirical evidence.
 
 External convergence:
-- VILA-Lab: [Claude Code v2.1.88 — 98.4% is harness infrastructure](https://arxiv.org/abs/2604.14228)
+- ["Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems"](https://arxiv.org/abs/2604.14228) — arXiv April 2026
 - ["Code as Agent Harness"](https://arxiv.org/abs/2605.18747) — arXiv May 2026
 - Stanford IRIS Lab: ["Meta-Harness"](https://arxiv.org/abs/2603.28052) — +7.7pts at 4× fewer tokens
 

package/bin/fh-goal.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+const { execFileSync } = require('child_process');
+const path = require('path');
+execFileSync(
+  path.join(__dirname, '..', 'scripts', 'fh-goal.sh'),
+  process.argv.slice(2),
+  { stdio: 'inherit' }
+);

package/bin/fh-run.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+const { execFileSync } = require('child_process');
+const path = require('path');
+execFileSync(
+  path.join(__dirname, '..', 'scripts', 'fh-run.sh'),
+  process.argv.slice(2),
+  { stdio: 'inherit' }
+);

package/docs/codex-compat.md

@@ -0,0 +1,123 @@
+# Codex Compatibility — Known Limitations & Validated Patterns
+
+> Status: **beta**. This document is beta-removal condition #2 (see `AGENTS.md` → Codex Compatibility → Beta removal conditions). It lists what works, what breaks, and what to expect when applying forge-harness (FH) methodology through OpenAI Codex (`codex exec`) instead of Claude Code.
+
+FH is a 2-layer system: a **methodology layer** (`tracks/`, `knowledge/`, `SKILL.md` docs) that is model-agnostic, and an **automation layer** (Claude Code hooks, `.claude/agents/`, `/model`, settings.json) that is Claude-native. Codex users run the methodology layer by reading `SKILL.md` files directly; automation steps either run through runtime adapters (`fh-gate`, `fh-run`) or require manual substitution.
+
+## Validated invocation pattern
+
+```bash
+# headless, stdin — codex-cli >= 0.135.0
+cat plugins/fh-meta/skills/<skill>/SKILL.md path/to/artifact \
+  | codex exec -m gpt-5.5 -
+```
+
+- `codex exec -m gpt-5.5 -` reads the combined prompt from stdin and runs headless.
+- `npx @openai/codex` (interactive) requires a TTY and is **not** suitable for piped skill application.
+- Inside a git repository (e.g. a clone of this repo) no extra flag is needed. **Outside** a git repo (e.g. running from `/tmp`), add `--skip-git-repo-check`.
+- `codex exec` has its own file-read tools, so a skill that back-traces claims to source files (e.g. `source-grounding-audit`) can verify paths itself — it produced real `file:line` citations in validation.
+
+## Runtime adapters
+
+### `fh-gate`
+
+`fh-gate` supports both Claude and Codex backends with the same governance prompt and verdict parser:
+
+```bash
+# Default, backward-compatible Claude path
+npx --package @chrono-meta/fh-gate fh-gate "src/foo.ts" quick ci
+
+# Codex as the primary reviewer
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-gate "src/foo.ts" quick ci
+
+# Prefer Codex if installed, otherwise fall back to Claude
+FH_BACKEND=auto npx --package @chrono-meta/fh-gate fh-gate "src/foo.ts" quick ci
+```
+
+Backend defaults:
+
+| `FH_BACKEND` | Command | Default model |
+|---|---|---|
+| `claude` | `claude --print --model "$FH_MODEL"` | `claude-sonnet-4-6` |
+| `codex` | `codex exec -m "$FH_MODEL" -` | `gpt-5.5` |
+| `auto` | `codex` if present, otherwise `claude` | backend default |
+
+### `fh-run`
+
+`fh-run` bridges skill and agent execution that previously assumed Claude Code slash commands or `Agent(...)` dispatch:
+
+```bash
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run \
+  --skill source-grounding-audit \
+  --file docs/foo.md
+
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run \
+  --agent fh-commons:quench-challenger \
+  --file plugins/fh-meta/skills/foo/SKILL.md
+```
+
+Resolution order:
+
+| Unit type | Lookup |
+|---|---|
+| `--skill name` | `plugins/fh-meta/skills/name/SKILL.md`, then `plugins/fh-commons/skills/name/SKILL.md` |
+| `--agent name` | `.claude/agents/name.md`, then `plugins/fh-meta/agents/name.md`, then `plugins/fh-commons/agents/name.md` |
+| `--agent plugin:name` | `plugins/plugin/agents/name.md` first |
+| `--unit path` | explicit file path |
+
+### `fh-goal`
+
+Codex has native goal/session features. Use those directly when they fit. `fh-goal` is not a replacement for Codex goal; it is a non-interactive wrapper for "run backend task, then run FH governance on changed files":
+
+```bash
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-goal \
+  --prompt "Implement X and update tests" \
+  --gate quick
+```
+
+## Author-run M1 validations (2026-06-04)
+
+These are **author** runs — they confirm the M1 tier assignments are accurate and ground the limitations below. They do **not** count toward the external-validation gate (conditions #1 and #3 below), which by definition requires non-author users.
+
+| Skill | Tier | Method | Result |
+|---|---|---|---|
+| `source-grounding-audit` | M1 | Fed a fixture with 2 real + 2 phantom claims (a non-existent skill path, a fabricated "47 M1 skills" count) | **4/4 correct** — both real claims Grounded with `file:line` citations, both phantoms caught (the fabricated count corrected against the actual `AGENTS.md`) |
+| `asset-placement-gate` | M1 | Fed a proposed `phantom-checker` skill that duplicates `source-grounding-audit` | **Correct** — applied the 4-criteria bar, flagged criterion ④ overlap, routed to **Drop** with "route intent to source-grounding-audit" |
+
+Both ran end-to-end with no Claude-native dependency. The M1 tier claim holds for the two skills tested.
+
+## Known limitations
+
+### 1. CC-native hooks fire and fail (noise, not breakage)
+When `codex exec` runs **inside this repo**, FH's Claude-native git/Stop/PostToolUse hooks attempt to fire and emit `hook: Stop Failed` / `hook: PostToolUse Failed` lines interleaved with output. These are **harmless to the skill result** — the skill's verdict is produced correctly — but they are visible noise. Running from a directory **without** FH's `.claude/settings.json` (the normal Codex-user case) avoids them entirely. Filter with `grep -vE "^hook:"` if needed.
+
+### 2. M2 skills need manual agent substitution
+M2 skills (`steel-quench`, `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop`) have a core workflow that runs under Codex, but any step that dispatches `Agent(subagent_type=...)` or a slash command must be replaced by `fh-run` or a direct `codex exec` call reading the sub-agent's `SKILL.md`/agent `.md` — same workflow, different runtime (the "M2 adaptation pattern" in `AGENTS.md`). Example: `steel-quench` Waves 1–3 run; the `quench-challenger` agent step becomes `fh-run --agent fh-commons:quench-challenger`.
+
+### 3. M3 skills do not run automatically under Codex
+M3 skills (`goal-quench` Phase-3 Stop hook, `hub-cc-pr-reviewer` CC session context, `install-wizard` settings.json write) require Claude-Code-native runtime and are **methodology reference only** under Codex unless a dedicated adapter exists. Use Codex's native goal/session features for goal control, and use `fh-gate` after completion for FH quality gating.
+
+### 4. No token accounting
+Codex token usage is billed in the Codex CLI quota and is **not** recorded in any FH session log or orchestrator measurement. Cross-family runs (Gemini/Codex) are invisible to FH's token-budget tooling by construction.
+
+### 5. Cross-family sibling note (Gemini)
+The sibling pattern for Gemini is `gemini -p "$(cat <skill+artifact>)"`. Outside a trusted directory Gemini requires `--skip-trust` (or `GEMINI_CLI_TRUST_WORKSPACE=true`). Gemini's headless output may bracket identifiers (`[ID]:`) where Codex does not — parse tolerantly.
+
+## Per-tier expectation summary
+
+| Tier | Under Codex | Action |
+|---|---|---|
+| **M1** | Runs fully | `cat SKILL.md artifact \| codex exec -m gpt-5.5 -` |
+| **M2** | Core runs; agent/slash steps via adapter | Substitute each dispatch with `fh-run` or a direct `codex exec` on the sub-agent's `.md` |
+| **M3** | Does not run automatically | Use native Codex session features where available; otherwise read as methodology reference or use a dedicated adapter |
+
+## Beta removal — remaining (external-blocked)
+
+| Condition | Status |
+|---|---|
+| Known limitation list published (this doc) | ✅ done (2026-06-04) |
+| 5+ externally validated M1 skill runs (not FH author) | ⬜ pending — needs external Codex users |
+| At least 1 external Codex user confirms methodology reproduces | ⬜ pending — needs external Codex users |
+| README badge updated (`Codex-compatible` without `beta`) | ⬜ blocked on the two above |
+
+To report a validated run, open an issue at `chrono-meta/forge-harness` with label `codex-validation`.

package/docs/pillars.svg

@@ -0,0 +1,70 @@
+<svg viewBox="0 0 680 100" width="680" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#1e1108"/>
+      <stop offset="100%" stop-color="#0d0803"/>
+    </linearGradient>
+    <linearGradient id="cd" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#2c1c0c"/>
+      <stop offset="100%" stop-color="#181005"/>
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="1.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="680" height="100" fill="url(#bg)"/>
+
+  <!-- Top hot-metal accent -->
+  <rect width="680" height="3" fill="#e07d2a" filter="url(#glow)"/>
+  <rect y="3" width="680" height="5" fill="#e07d2a" fill-opacity="0.10"/>
+
+  <!-- ═══ FORK (x=8, cx=88) ═══ -->
+  <rect x="8" y="10" width="160" height="84" rx="5" fill="url(#cd)" stroke="#c46820" stroke-width="0.8"/>
+  <!-- Chain link icon -->
+  <ellipse cx="81" cy="34" rx="10" ry="6" fill="none" stroke="#e07d2a" stroke-width="2" transform="rotate(-35 81 34)"/>
+  <ellipse cx="95" cy="44" rx="10" ry="6" fill="none" stroke="#e07d2a" stroke-width="2" transform="rotate(-35 95 44)"/>
+  <text x="88" y="63" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="13" font-weight="bold" fill="#f5943a" letter-spacing="2">FORK</text>
+  <text x="88" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Fork the harness</text>
+  <text x="88" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">for your team</text>
+
+  <!-- ═══ ADAPT (x=176, cx=256) ═══ -->
+  <rect x="176" y="10" width="160" height="84" rx="5" fill="url(#cd)" stroke="#c46820" stroke-width="0.8"/>
+  <!-- Gear icon (hexagon + inner circle) -->
+  <polygon points="256,25 267,31 267,43 256,49 245,43 245,31" fill="none" stroke="#e07d2a" stroke-width="2" stroke-linejoin="round"/>
+  <circle cx="256" cy="37" r="6" fill="none" stroke="#e07d2a" stroke-width="2"/>
+  <circle cx="256" cy="37" r="1.5" fill="#e07d2a"/>
+  <text x="256" y="63" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="13" font-weight="bold" fill="#f5943a" letter-spacing="2">ADAPT</text>
+  <text x="256" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Rename, configure,</text>
+  <text x="256" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">and extend</text>
+
+  <!-- ═══ COLLABORATE (x=344, cx=424) ═══ -->
+  <rect x="344" y="10" width="160" height="84" rx="5" fill="url(#cd)" stroke="#c46820" stroke-width="0.8"/>
+  <!-- Two people -->
+  <circle cx="416" cy="29" r="7" fill="none" stroke="#e07d2a" stroke-width="1.8"/>
+  <path d="M404,49 C404,39 428,39 428,49" fill="none" stroke="#e07d2a" stroke-width="1.8" stroke-linecap="round"/>
+  <circle cx="432" cy="32" r="6" fill="none" stroke="#e07d2a" stroke-width="1.5"/>
+  <path d="M421,50 C421,42 443,42 443,50" fill="none" stroke="#e07d2a" stroke-width="1.5" stroke-linecap="round"/>
+  <text x="424" y="63" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="11" font-weight="bold" fill="#f5943a" letter-spacing="0.8">COLLABORATE</text>
+  <text x="424" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Multi-project teams.</text>
+  <text x="424" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">One shared backbone.</text>
+
+  <!-- ═══ EMPOWER (x=512, cx=592) ═══ -->
+  <rect x="512" y="10" width="160" height="84" rx="5" fill="url(#cd)" stroke="#c46820" stroke-width="0.8"/>
+  <!-- Shield + checkmark -->
+  <path d="M592,24 L605,30 L605,41 L592,50 L579,41 L579,30 Z" fill="none" stroke="#e07d2a" stroke-width="2" stroke-linejoin="round"/>
+  <path d="M585,37 L590,43 L599,33" fill="none" stroke="#e07d2a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="592" y="63" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="12" font-weight="bold" fill="#f5943a" letter-spacing="1">EMPOWER</text>
+  <text x="592" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Build, ship, and</text>
+  <text x="592" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">iterate faster.</text>
+
+  <!-- Subtle vertical dividers -->
+  <line x1="176" y1="18" x2="176" y2="86" stroke="#c46820" stroke-width="0.5" stroke-opacity="0.35"/>
+  <line x1="344" y1="18" x2="344" y2="86" stroke="#c46820" stroke-width="0.5" stroke-opacity="0.35"/>
+  <line x1="512" y1="18" x2="512" y2="86" stroke="#c46820" stroke-width="0.5" stroke-opacity="0.35"/>
+
+  <!-- Bottom ember line -->
+  <rect y="97" width="680" height="3" fill="#c46820" fill-opacity="0.45"/>
+</svg>

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

@@ -9,7 +9,7 @@ tags: [integration-contract, governance, opencode, hermes, openhuman, bridge-lay
 
 ## Status
 
-**v1.0 — Binary available.** `scripts/fh-gate.sh` executes governance review end-to-end via `claude --print`.
+**v1.2 — Binary available.** `scripts/fh-gate.sh` executes governance review end-to-end via a selectable backend: `claude --print` or `codex exec`.
 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.
 
@@ -45,9 +45,11 @@ Caller reads verdict, decides: merge / hold / escalate
 
 | Input | Form | Description |
 |---|---|---|
-| `FH_DIFF_PATH` | file path | Pre-generated diff file (skips Step 1 if provided) |
+| `FH_DIFF_PATH` | file path | Pre-generated diff file included as additional caller context |
 | `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 |
+| `FH_BACKEND` | `claude`, `codex`, or `auto` (default `claude`) | Runtime backend. `auto` prefers Codex if installed, otherwise Claude |
+| `FH_MODEL` | model id | Overrides backend default (`claude-sonnet-4-6` for Claude, `gpt-5.5` for Codex) |
 
 ### Capture pattern (caller's responsibility)
 
@@ -158,7 +160,7 @@ Steps:
 
 set -euo pipefail
 
-FH_TARGET_FILES="${1:-$(git diff main..HEAD --name-only | tr '\n' ' ')}"
+FH_TARGET_FILES="${FH_TARGET_FILES:-${1:-$(git diff main..HEAD --name-only)}}"
 FH_GATE_LEVEL="${2:-quick}"
 FH_CALLER="${3:-unknown}"
 
@@ -176,6 +178,30 @@ EOF
 
 Usage: `./scripts/fh-gate.sh "src/permission/arity.ts" quick opencode`
 
+### Pattern 2-b — Binary wrapper with runtime backend
+
+```bash
+# Claude backend, backward-compatible default
+npx --package @chrono-meta/fh-gate fh-gate "src/permission/arity.ts" quick ci
+
+# Codex backend as primary reviewer
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-gate "src/permission/arity.ts" quick ci
+
+# Portable wrapper: prefer Codex when installed, otherwise Claude
+FH_BACKEND=auto npx --package @chrono-meta/fh-gate fh-gate "src/permission/arity.ts" quick ci
+```
+
+All backends must produce the same `FH_STATUS` / `FH_GATE_VERDICT` header. Missing or malformed output is a harness failure and must be treated as blocked by the caller.
+
+### Pattern 2-c — Direct skill or agent run
+
+```bash
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --skill source-grounding-audit --file docs/foo.md
+FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --agent fh-commons:quench-challenger --file plugins/fh-meta/skills/foo/SKILL.md
+```
+
+Use `fh-run` when a FH workflow references a Claude Code slash command or `Agent(...)` dispatch and the current orchestrator is Codex.
+
 ### Pattern 3 — Stop hook (automated post-session)
 
 Add to project's `.claude/settings.json`:
@@ -187,7 +213,7 @@ Add to project's `.claude/settings.json`:
       "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"
+        "command": "FH_BACKEND=auto FH_TARGET_FILES=\"$(git diff main..HEAD --name-only)\" bash ~/projects/forge-harness/scripts/fh-gate.sh \"\" quick stop-hook >> /tmp/fh-governance-queue.txt"
       }]
     }]
   }
@@ -206,7 +232,7 @@ 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_TARGET_FILES=$(git diff main..HEAD --name-only)
 FH_SECURITY_LENS=on  # OpenCode touches broad surfaces; security lens default on
 FH_GATE_LEVEL=quick
 ```
@@ -257,52 +283,42 @@ jobs:
       - 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
+          FH_TARGET_FILES="$(git diff origin/main..HEAD --name-only)" \
+            bash scripts/fh-gate.sh "" quick ci
 ```
 
 ---
 
 ## Record Specification
 
-Every governance pass writes a record entry:
+Every binary governance pass writes a compact record entry for calibration and audit indexing. The complete findings block remains in stdout and should be captured by the caller or CI artifact when full detail is required.
 
 ```yaml
 # tracks/_meta/governance_log_YYYY-MM-DD.yaml
 - timestamp: 2026-05-31T12:00:00Z
   caller: opencode
+  backend: codex
+  model: gpt-5.5
   gate_level: quick
-  target_files:
+  verdict: BLOCKED
+  findings_total: 3
+  findings_a: 2
+  findings_b: 1
+  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.
+Record path is included in every verdict output as `FH_RECORD_PATH`. This feeds `harvest-loop` calibration; full finding text should be retained from stdout when needed.
 
 ---
 
-## What This Contract Does NOT Specify (Bridge Layer v1.0)
+## What This Contract Does NOT Specify (Bridge Layer)
 
-The following require the bridge layer and are out of scope for v0.1:
+The following require a bridge/runtime layer beyond the file-based gate:
 
 | Feature | Why deferred |
 |---|---|
 | REST API or webhook | Would require a server process — FH is file-based |
-| 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 |
@@ -318,6 +334,7 @@ The bridge layer (v1.0) will implement these. This contract is the specification
 | v0.1 | 2026-05-31 | Initial specification. Bash invocation patterns + structured verdict format. Empirical basis: arity.ts controlled trial. |
 | v1.0 | 2026-06-01 | Binary available as `@chrono-meta/fh-gate` on npm. JS wrapper + fh-gate.sh CI-ready binary. |
 | v1.1 | 2026-06-03 | Large-scale harness improvements. Banner update. Version alignment. |
+| v1.2 | 2026-06-04 | Selectable Claude/Codex backend, `fh-run`/`fh-goal` runtime adapters, newline-preserving `FH_TARGET_FILES`, and implemented task/diff/security-lens inputs. |
 
 ---
 

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@chrono-meta/fh-gate",
-  "version": "1.1.0",
-  "description": "FH governance gate — runs structured AI code review via claude --print and returns machine-parseable verdicts (PASS/PENDING/BLOCKED/ESCALATE).",
+  "version": "1.2.1",
+  "description": "FH runtime adapters — run FH governance, skills, and agents via Claude or Codex with machine-parseable gates.",
   "license": "MIT",
   "keywords": [
     "ai-governance",
     "code-review",
     "claude",
     "claude-code",
+    "codex",
+    "openai-codex",
     "ci",
     "harness"
   ],
@@ -16,25 +18,47 @@
     "url": "git+https://github.com/chrono-meta/forge-harness.git"
   },
   "bin": {
-    "fh-gate": "bin/fh-gate.js"
+    "fh-gate": "bin/fh-gate.js",
+    "fh-run": "bin/fh-run.js",
+    "fh-goal": "bin/fh-goal.js"
   },
   "scripts": {
-    "prepare": "chmod +x bin/fh-gate.js scripts/fh-gate.sh"
+    "prepare": "chmod +x bin/fh-gate.js bin/fh-run.js bin/fh-goal.js scripts/fh-gate.sh scripts/fh-run.sh scripts/fh-goal.sh"
   },
   "engines": {
     "node": ">=16"
   },
   "peerDependencies": {
-    "@anthropic-ai/claude-code": "*"
+    "@anthropic-ai/claude-code": "*",
+    "@openai/codex": "*"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/claude-code": {
-      "optional": false
+      "optional": true
+    },
+    "@openai/codex": {
+      "optional": true
     }
   },
   "files": [
+    ".claude/agents/challenger.md",
+    "AGENTS.md",
+    "CATALOG.md",
+    "CHEATSHEET.md",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
     "bin/fh-gate.js",
+    "bin/fh-run.js",
+    "bin/fh-goal.js",
+    "docs/codex-compat.md",
+    "docs/pillars.svg",
     "scripts/fh-gate.sh",
+    "scripts/fh-run.sh",
+    "scripts/fh-goal.sh",
+    "plugins/fh-meta/skills",
+    "plugins/fh-meta/agents",
+    "plugins/fh-commons/skills",
+    "plugins/fh-commons/agents",
     "knowledge/shared/harness-core/fh_integration_contract.md",
     "README.md"
   ]

package/plugins/fh-commons/README.md

@@ -0,0 +1,37 @@
+# fh-commons — Contention-Born Skill Habitat
+
+**A different layer of plugin from fh-meta.**
+
+fh-meta = meta-engineering skills for operating, diagnosing, and improving the harness itself  
+fh-commons = general-purpose utility skills born from the contention layer, transplantable to any project
+
+## Placement Criteria
+
+When the `contention-layer` skill harvests contentions and generates new skill candidates:
+
+| Determination | Destination |
+|---|---|
+| Harness engineering in nature | `fh-meta` |
+| Project-general · domain-agnostic | **`fh-commons`** (this plugin) |
+| Domain/team specific | field harvest (decided by the field team) |
+
+## Skill List
+
+| Skill | Description | Contention Parent |
+|---|---|---|
+| `convergence-loop` | General-purpose gate reinforcement that replaces single-pass structures with a convergence loop of up to N rounds | harvest-loop (recurring single-pass-distrust pattern across hub gates) |
+| `deliberation` | Innovator → Devil-Advocate → Mediator 3-layer multi-perspective synthesis. Generates conditional verdicts without binary win/loss | Migrated from fh-meta (2026-05-23 — domain-agnostic general decision structure) |
+
+## The `origin` Field
+
+Commons skills include the following fields in their SKILL.md frontmatter:
+
+```yaml
+# Contention-born (extracted by contention-layer)
+origin: contention-layer
+contention-parents: [skill-A, skill-B]
+
+# Migrated from fh-meta (reclassified as general-purpose)
+origin: fh-meta
+migration: "YYYY-MM-DD — reason for migration"
+```