@chrono-meta/fh-gate 1.4.97 → 1.4.99

package/README.md

@@ -8,12 +8,18 @@
   <img src="https://img.shields.io/badge/Claude_Code-compatible-a855f7.svg" alt="Claude Code">
   <a href="https://github.com/chrono-meta/forge-harness/issues/72"><img src="https://img.shields.io/badge/Codex-beta_·_help_validate-f59e0b.svg" alt="Codex-compatible beta — help validate (issue #72)"></a>
   <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>
+  <a href="https://github.com/chrono-meta/homebrew-forge-harness"><img src="https://img.shields.io/badge/homebrew-tap-FBB040.svg" alt="Homebrew tap"></a>
+  <a href="https://github.com/chrono-meta/forge-harness/stargazers"><img src="https://img.shields.io/github/stars/chrono-meta/forge-harness?style=social" alt="GitHub stars"></a>
 </p>
 
 <p align="center">
   <b>English</b> · <a href="README.ko.md">한국어</a> · <a href="README.zh.md">中文</a> · <a href="README.ja.md">日本語</a>
 </p>
 
+<p align="center">
+  <sub>If this is useful, a ⭐ helps others find it.</sub>
+</p>
+
 <p align="center">
   <b>Forge your Claude Code projects — pass them through, they come out faster.</b><br>
   A practitioner's <b>meta-harness</b> — the galaxy your project harnesses live in.<br>It raises each project's <b>floor</b> (harness-ify the setup) and <b>ceiling</b> (accelerate the work), then compounds the gains across your whole portfolio.
@@ -61,7 +67,9 @@
 The consent-registry gate parses YAML, and it **fails closed** when it cannot — correctly, since an
 unvalidated consent record must not read as a clean one. But that fail-closed turns the whole of
 `npm test` (and `prepublishOnly`) red on a machine without PyYAML, and until 2026-08-12 the
-requirement was written down **nowhere**:
+requirement was written down **nowhere**. It is written here now — and, as of this edit, *only*
+here: it is still absent from `package.json`, the cheatsheet and every other doc, so this block is
+the single place a new machine can learn it. That is an improvement over nowhere, not a fix:
 
 ```bash
 python3 -m pip install --user pyyaml     # verify:  python3 -c 'import yaml; print(yaml.__version__)'
@@ -128,6 +136,7 @@ cd ~/projects/{your-project} && claude
 | Solo dev, one project, just trying it | [`templates/starter_profile.md`](templates/starter_profile.md) — one command, curated first-five skills |
 | Multiple projects, want the compounding hub | Clone the hub (quickstart above) |
 | CI / non-Claude runtime, gates only | `npx @chrono-meta/fh-gate` (zero-install governance gate) |
+| Prefer `brew` over `npx`/`npm` | `brew tap chrono-meta/forge-harness && brew install forge-harness` — same 100%-parity content, different install UX (community tap; not yet in Homebrew Core, so `brew search` won't find it without the tap first) |
 
 ---
 
@@ -176,35 +185,146 @@ them evolve together instead of scattering.
 This galaxy is more than a container. FH can run a field harness **in simulation inside its own
 sandbox** — expensive per run, cheaper in total, because the trial-and-error pools in one place and
 compounds — and when the simulation holds, it **emits** the project as an independent, specialized
-harness. That is the goal it is built toward. In practice it works in four ways:
+harness. **That last step is the goal it is built toward, not a shipped feature** — the incubation
+chamber has emitted once, and the run that produced it did not go through the full flow. Read the
+simulate-and-emit sentence as direction of travel; everything before it is in use today.
 
-**① Assemble** — FH runs a *cluster* of harnesses at optimized token cost and hands you the right one for
-the project. You don't wire up skills one by one; you get a **harness** — its plugins, skills, and agents
-included — assembled to fit.
+### The five identities — what FH is for
 
-**② Forge** *(the quality gate)* — every change earns its way through adversarial · phantom · regression
-gates. This is not "check more." It is a **responsibility router**: as automation rises, human sign-offs
-get fewer but heavier, so the gate spends your attention only where a change is *irreversible*. Quality is
-the lever; the speed is the result.
+These are not five modules, and they are not five shipped features either. They are the **shapes the
+skills clump into** — the name of something that was already there, spread across the skills and agents
+rather than layered on top of them. They sit at a different level from the problem table at the top of
+this page: that table is *symptoms you might arrive with*, this is *what the hub is organized around*.
 
-**③ Sidecar** — capability itself stays on the frontier. FH dispatches across multiple LLMs (Claude,
-Codex, Gemini, local) so raw power is never tied to one model or one generation. The point is *not*
-patching each model's weak spots — that scaffolding dies as models improve. It is **riding the frontier's
-evolution**: shed what the substrate now does natively, absorb what it ships next. Decorrelation is
-today's trust lever (a cross-family panel beats a single model's ceiling); co-evolution is the structure.
-
-**④ Self-evolving loop** — the harness gets better without being rebuilt, in two directions: **outward**,
-where each session's lessons compound into the hub so the next project starts faster, and **inward**,
-where it catches and repairs *its own* defects (the 4-axis gate, bidirectional verify, per-user
-adaptation).
+| | Identity | What a person gets |
+|---|---|---|
+| **①** | **Multi-harness cluster** | One task rides several harnesses, and governance is computed *between* them |
+| **②** | **Project incubator** | A new harness comes out **walking where it was born**, not as an empty scaffold |
+| **③** | **Governance gate** | What must not ship is blocked **mechanically**, not by remembering to check |
+| **④** | **Frontier → org propagation** | What arrives from outside lands all the way *inside* the organization |
+| **⑤** | **Amplifier** | A short intent gets forged all the way to the finished artifact |
+
+**They are not equally finished, and you should not read the table as five working features.** Maturity is
+tracked per identity on a four-step scale — `aspirational → partial → RC (stood up in the lab) → REALIZED
+(walked outside)` — with a dated line of evidence for each. Those grades are deliberately **not** copied
+here: a grade kept in two files goes stale in one, and this page exists in four languages, so a copy here
+would be four copies. Before you rely on any row above, read the current grades — that is one file:
+[`ship_readiness_gate.md`](knowledge/shared/harness-core/ship_readiness_gate.md). The short version if you
+only want one sentence, as of **2026-08-15**: **③ and ⑤ are graded green — demonstrated outside the lab;
+①, ② and ④ are release candidates — built and calibrated, not yet shown to walk in someone else's hands.**
+If that sentence and the gate file disagree, the gate file is right and this line is stale.
+
+Two properties cut across all five, and neither is a feature you switch on:
+
+- **It rides the frontier instead of patching it.** FH dispatches across families (Claude, Codex, Gemini,
+  local) — but the point is *not* papering over each model's weak spots, because that scaffolding dies as
+  models improve. It is co-evolution: shed what the substrate now does natively, absorb what it ships
+  next. **Decorrelation** is today's trust lever, and it is the load-bearing word on this page:
+  deliberately making two checks fail *differently* — a reviewer from another model family, a run against
+  a real target, an outside audit of your own record — so that what one is blind to, another is not.
+  A cross-family panel beats a single model's ceiling for exactly that reason, not because it is bigger.
+- **It evolves in two directions.** *Outward*, each session's lessons compound into the hub so the next
+  project starts further along. *Inward*, it catches and repairs **its own** defects — the same gates,
+  turned on the harness itself.
 
 The whole thing is a division of labor: **raw capability is the model's; assembly, trust, and evolution
 are the harness's.**
 
-> **Self-healing here isn't a claim — it's in the commit log.** This very README's voice rules were fixed
-> mid-session by FH catching its own drift: a tone miss → diagnosis → a cross-family challenger that
-> attacked *its own first fix* → re-fix → floor-tier re-verification → memory update. A harness repairing
-> its own defect, on the record — not a slogan.
+---
+
+## How it is built — process → engines → identity
+
+The five identities above are the surface. Two layers sit under them, and naming all three is what keeps
+"what FH does" from collapsing into one undifferentiated pile:
+
+```
+five identities   what a person can actually use          (surface — what you get)
+      ↑ backed by
+four engines      the capability that makes it possible   (capability — what it can do)
+      ↑ produced by
+three-stage       the ORDER those engines are forged in   (process — how it gets made)
+  process
+```
+
+**The four engines.** Each one is what some identity above is standing on. They were not invented for this
+page: the readiness gate had already been scoring every identity against these same four capabilities in a
+column of its own ([`ship_readiness_gate.md`](knowledge/shared/harness-core/ship_readiness_gate.md)), so
+naming them was recognition rather than taxonomy-building.
+
+| Engine | What it is | Identities it backs |
+|---|---|---|
+| `judgment-circuit` | what counts as success, which way to lean under uncertainty, what is out of scope, what never happens | ⑤ Amplifier · ② Incubator |
+| `ship-gate` | mechanical blocking before an irreversible surface — commit, publish, delete, rewrite | ③ Governance gate |
+| `context-continuity` | not losing the thread across compaction, sub-agents, machines, sessions | ① Cluster · ② Incubator |
+| `external-grounding` | reaching outside the repo *before* asserting novelty or settling a design | ④ Frontier → org |
+
+They are written by name, never by number — the table order here and the prose order elsewhere differ, so
+"engine ④" decodes to two different engines depending on which you read.
+
+`judgment-circuit` is the one that gets misread most, so state it flatly: **it is a coordinate system for
+deciding, not a statement of who the harness is.** The four items in its row are the whole of it. Do not
+shorten it to "the harness's soul" in English either — that word reads as *persona*, and the largest
+finding of the measurement behind this engine (105 runs, comparing prompts with and without an identity
+declaration) was precisely that the two are different things: adding *"you are a ~"* came out a **net loss**
+on the weakest model tested, and taking it out recovered ground. A one-word rename re-fuses exactly what
+that measurement separated. The figure itself is deliberately not quoted here — the source records it
+without a scale, and an unscaled number on a front page is decoration; it is in
+[`ship_readiness_gate.md`](knowledge/shared/harness-core/ship_readiness_gate.md) with its context. Nor is
+a judgment circuit built in one sitting: FH hands a new harness a **seed draft**, and it fills in as that
+harness is actually used.
+
+**The three-stage process** — this is an *order of investment*, not a menu:
+
+```
+① Circuit before design   the judgment circuit goes in FIRST — success · leaning · out-of-scope ·
+                          never-do — not written up afterwards as a record of what you did
+
+② Decorrelate in the      split the work into checks that fail DIFFERENTLY and run them at once.
+   middle, to accelerate  Choose which differences matter — a second reviewer of the same kind is
+                          not decorrelation, it is the same blind spot twice. Parallelism has no
+                          direction of its own; the judgment circuit from ① is what picks.
+                          This is a way of WORKING, not the end-of-line check in ③.
+
+③ Burn it down at the     the four axes below. Adversarial review is ONE of them, not all of them
+   end, on four axes
+```
+
+**The four verification axes** — where "we reviewed it" usually turns out to mean only the first of them.
+Read the middle column to pick one, and the right column to see what it catches:
+
+| Axis | Reach for it when… | What it catches | Typical instrument |
+|---|---|---|---|
+| **ⓐ Different family** | the change decides something — a PASS/FAIL, a gate, a safety rule | the **implementation** is wrong | a reviewer from another model family (`auto-decorrelation`) |
+| **ⓑ First real use** | you are about to trust a number, a count, or a scan's output | the **way you are measuring** is wrong | run it once against one real target and look at the result by hand |
+| **ⓒ Record grounding** | you wrote down claims, figures or citations others will act on | the **claim** is wrong | someone who did not write it re-measures what it says |
+| **ⓓ Revert and observe** | you added a test, a guard or a check and believe it protects you | the **anchor** is wrong — the check is decorative | delete the thing it guards and confirm *that specific* check goes red |
+
+**You do not run all four every time, and that is the design.** A one-line fix earns none of them; a change
+that returns a verdict earns ⓐ; a published number earns ⓑ and ⓒ; a new guard earns ⓓ; an irreversible
+surface — publish, delete, history rewrite — earns whichever of the four its failure mode exposes, and the
+benefit of the doubt goes to running one more. Multiplying reviewers is not the same as adding an axis.
+
+One further axis sits outside this four because it changes *whose* ground truth you stand on rather than
+*what* you check: **standpoint** — when a change crosses into another harness, run the diff from the
+target's own repo and rules, not from your reading of them
+([`field_verdict_crossfamily_gate.md §7`](knowledge/shared/harness-core/field_verdict_crossfamily_gate.md)).
+
+> **Honest note — this is not a clean stack, and that is the point.** Stage ① and stage ③ are made of the
+> same material as the engines, so the lower layer uses the upper one. The contradiction resolves on
+> *subject*: the **engines** are what FH applies to your work, while the **process** is the order FH uses
+> when forging its own engines. If the method had been borrowed from outside it would be unrelated to the
+> engines; the overlap is the fingerprint of dogfooding. Full canon, including the sample limits behind
+> each claim: [`fh_three_layer_canon.md`](knowledge/shared/harness-core/fh_three_layer_canon.md).
+
+> **Self-healing here isn't a claim — check it.** `git log` in this repo is the record, and the shape
+> repeats: a miss is caught, the fix is attacked, and the attack often lands on the fix rather than on the
+> original. One you can open by hash — `cb74ea4`, where a register-consistency rule was added to
+> `CLAUDE.md §Voice/Tone` after the harness drifted register mid-session. A second, in the same change
+> that added this section: a checker whose whole job is finding tests nothing runs was caught reporting a
+> green count off a script's *own comment*, and then the guard written to fix that turned out to have no
+> test that would fail if it were deleted — found by a different model family, not by the author, and
+> closed with a fixture that does fail. Commit hashes on feature branches do not survive squash-merge, so
+> that one is cited by its shape rather than by an ID that would rot.
 
 ---
 
@@ -230,6 +350,10 @@ npx --package @chrono-meta/fh-gate fh-gate                    # default: Claude
 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
+
+# or, via Homebrew (same content, no npx prefix needed after install):
+brew tap chrono-meta/forge-harness && brew install forge-harness
+fh-gate
 ```
 
 `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 — note that `auto` is fallback *selection*: it runs ONE leg. `FH_BACKEND=cross` runs BOTH families and unions their findings (a finding only one family saw is still a finding, so it unions rather than votes); the verdict is the most severe across legs. It costs ~2x, so it is for load-bearing verdict/gate/irreversible-surface changes, not a default. The output always declares which legs actually ran (`FH_GATE_LEGS:`, `FH_GATE_DECORRELATED:`) — on a machine with only one family, `cross` degrades to that single leg and says so, because a single-family result that reads as cross-checked is worse than an honest one.
@@ -334,13 +458,21 @@ two more signatures keep it running: `harvest-loop` (each session's lessons beco
 | `mcp-circuit-breaker` *(fh-commons)* | MCP tool failure pattern detection | "MCP keeps failing" |
 | `ko-tech-writer` *(fh-commons)* | Korean technical-writing pipeline (register calibration, translationese removal, honesty layering, perceptual QA) | "기술문서 써줘", "번역투 고쳐줘" |
 | `quench-challenger` *(fh-commons)* | Adversarial pressure-test agent | "Challenge this with a devil" |
-| *(+ 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 · salience-splitter | |
+| `auto-decorrelation` | Recruits a different-model-family reviewer for load-bearing changes | "Decorrelate this verification" |
+| `video-ingest` | Video → agent context, routed by capability and length | "What does this video show?" |
+| `fh` | Renders the hub map on demand, without a greeting | "fh" |
+| *(+ remaining skills)* | marketplace-gate · contention-layer · deliberation · edit-manifest · goal-quench · install-doctor · memory-hygiene · prompt-regression · public-surface-audit · return-path-gate · salience-splitter | |
+| **8 agents** | `challenger` · `quench-challenger` (adversarial) · `beginner` · `main-player` · `expert` (the user-mastery spectrum — cold read, daily use, domain authority) · `fact-checker` · `hub-persona-auditor` · `persona-innovator` | dispatched by the skills above, or by name |
 
 | Active count | Diagnosis |
 |:---:|---|
-| **28+** | Advanced — chain agent-composer + sim-conductor + steel-quench + pipeline-conductor |
-| **10–27** | Activation stage — gradually enable unchecked assets |
-| **0–9** | Early stage — start with `install-wizard` |
+| **~half the surface or more** | Advanced — chain agent-composer + sim-conductor + steel-quench + pipeline-conductor |
+| **a handful up to that** | Activation stage — gradually enable unchecked assets |
+| **almost none** | Early stage — start with `install-wizard` |
+
+> These bands are a rough self-check, not a measurement — no artifact defines the thresholds, and the
+> earlier fixed numbers were calibrated against a smaller roster, so they quietly drifted as the roster
+> grew. Using more skills is also not the goal; using the ones your work actually needs is.
 
 **Find a skill by what you're trying to do:**
 
@@ -376,7 +508,7 @@ Claude Code does not auto-select models by task complexity — you configure thi
 | `/model opus` | Opus handles everything | Harness-editing sessions (Mode D) · maximum depth on every turn |
 | `/model opusplan` | Opus *plans* · Sonnet executes *(when Opus engages)* | Cost-conscious routine coding — see caveat |
 
-**Why default Sonnet now works**: measured (see §Model setup evidence note below), *operating* FH is
+**Why default Sonnet now works**: measured (see *Measured, not asserted* below), *operating* FH is
 nearly model-flat — the rules in context do most of the work. What still needs a stronger model is a
 small set of depth-sensitive turns, and FH handles those itself: **some skills and agents declare a
 model-tier floor** (e.g. `quench-challenger` floors at opus) and are dispatched as sub-agents at the
@@ -397,8 +529,13 @@ dispatch's own `model` parameter; the session model/plan-mode does **not** propa
 > does not. Sub-agent token costs are CC-visible in the session jsonl under `message.model`.
 
 **Measured, not asserted** (worked examples): on a blind rule-application battery, *operating* FH is
-near model-flat — **every Claude tier measured scores 94–100%** (Fable, Opus 4.8, Sonnet 4.6 and 5,
-Haiku 4.5); the few lost points are format discipline, never a trap or gate-class miss. The tiers
+near model-flat — on a 30-point blind battery (2026-06-10) the four tiers run scored **94–100%**
+(top-tier anchor / Opus 4.8 / Sonnet 4.6 / Haiku 4.5 = 100 / 100 / 97 / 94), and a 2026-07-03
+replication re-anchored Opus 4.8, **Sonnet 5** and Haiku 4.5 at 16/16 each. Two honesty notes rather
+than one round number: the source artifact deliberately leaves the top tier unnamed, so this page does
+not name it either; and the **current** top tier has not been run on this battery — the doctrine below
+is what carries forward, not the scores. The few lost points are format discipline, never a trap or
+gate-class miss. The tiers
 separate only on above-rubric *design* increments (developing the harness, not running it) — which is
 why the default is Sonnet with **tier-floored dispatch** covering the depth-sensitive turns, and a
 pinned stronger model is recommended only for harness-editing sessions.
@@ -460,7 +597,7 @@ Claude-side token cost does not increase when the extra reviewer is an external
 
 > **FH papers** — the methodology below is documented, not just asserted:
 > - **v1.0 — methodology** · [Zenodo](https://zenodo.org/records/20397566) (DOI 10.5281/zenodo.20397566). 2-layer design, 6-axis framework, 4-agent orchestration, and the compounding loop, with empirical evidence.
-> - **cs.SE companion — governance-gate methodology** · **published** [Zenodo](https://zenodo.org/records/20680081) (DOI 10.5281/zenodo.20680081 · latest v1.1 10.5281/zenodo.20740038 · CC-BY-4.0) · arXiv submitted (cs.SE, in moderation).
+> - **cs.SE companion — governance-gate methodology** · **published** [Zenodo](https://zenodo.org/records/20680081) (DOI 10.5281/zenodo.20680081 · latest v1.1 10.5281/zenodo.20740038 · CC-BY-4.0) · arXiv submitted (cs.SE); the moderation outcome is not tracked in this repo, so treat "submitted" as the last state this page can vouch for, not as current.
 > - **cs.AI companion — "Governance Dividend"** · in preparation.
 
 External convergence: