@chrono-meta/fh-gate 1.2.2 → 1.3.0

package/AGENTS.md

@@ -124,7 +124,7 @@ echo "Apply the following skill to the artifact below." | \
 
 | Tier | Definition | Examples |
 |---|---|---|
-| **M1 — Full** | All phases run without CC-native dependencies — no Stop hook, no `.claude/agents/` dispatch, no `/model` | `token-budget-gate`, `asset-placement-gate`, `source-grounding-audit`, `deep-clarify`, `deliberation`, `convergence-loop` |
+| **M1 — Full** | All phases run without CC-native dependencies — no Stop hook, no `.claude/agents/` dispatch, no `/model` | `token-budget-gate`, `asset-placement-gate`, `phantom-quench`, `deep-clarify`, `deliberation`, `convergence-loop` |
 | **M2 — Partial** | Core workflow runs; CC-native phases require manual adaptation or skip | `steel-quench` (Wave 1–3 ✅; quench-challenger agent = manual), `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop` (git scan phase ✅; PR auto-proposal = manual) |
 | **M3 — CC-only** | Requires CC Stop hook or session-scoped agent dispatch; methodology reference only | `goal-quench` (Phase 3 Stop hook), `hub-cc-pr-reviewer` (CC session context), `install-wizard` (settings.json write) |
 
@@ -141,7 +141,7 @@ echo "Apply the following skill to the artifact below." | \
 | At least 1 external Codex user confirms methodology reproduces | ⬜ pending — needs external users |
 | README badge updated (`Codex-compatible` without `beta`) | ⬜ blocked on above |
 
-**Author M1 validation (2026-06-04, internal — does not satisfy the external conditions above):** `source-grounding-audit` (4/4 on a phantom-seeded fixture) and `asset-placement-gate` (correct Drop routing on a duplicate-skill proposal) ran end-to-end via `codex exec -m gpt-5.5 -` with no CC-native dependency, confirming the M1 tier assignments. Limitations observed (CC-native hook noise, no token accounting, etc.) are documented in `docs/codex-compat.md`.
+**Author M1 validation (2026-06-04, internal — does not satisfy the external conditions above):** `phantom-quench` (4/4 on a phantom-seeded fixture) and `asset-placement-gate` (correct Drop routing on a duplicate-skill proposal) ran end-to-end via `codex exec -m gpt-5.5 -` with no CC-native dependency, confirming the M1 tier assignments. Limitations observed (CC-native hook noise, no token accounting, etc.) are documented in `docs/codex-compat.md`.
 
 Tracking: open an issue at `chrono-meta/forge-harness` with label `codex-validation` to report a validated run.
 

package/CATALOG.md

@@ -8,6 +8,11 @@ AI reads this file first when searching past work. Open individual files for det
 
 <!-- Add entries in reverse date order (newest at top) -->
 
+### 2026-06-05 | _audit | sister-asset, gstack, field-harness, garry-tan
+**File:** tracks/_audit/session_2026_06_05_gstack-sister.md (private mirror: fh-be)
+gstack (garrytan, ~66K stars) sister-asset cross-audit — the field/execution-harness counterpart to FH's meta/governance harness, both running on the Claude Code skill substrate. FH governs / gstack executes (composes, not competes). Bidirectional import (frictionless one-command install, opinionated front door, privacy-first telemetry) / propagate (post-ship governance gate, cross-project knowledge compounding, HITL promotion gate) lists recorded.
+- Decision: public index only — bet evidence (B1·ID·SB) + full audit held in private store; external cross-link proposal to garrytan/gstack gated behind 3+ persona × 4-axis audit.
+
 ### 2026-06-04 | forge-harness | #skill, #public-private-split, #leak-prevention, #composability-gate
 **File:** plugins/fh-meta/skills/public-surface-audit/SKILL.md
 New meta-skill: scans git-tracked files for operator-private tokens (real username, absolute home paths, companion-store name, company asset names) that belong only in gitignored files. Closes the surface-sweep gap from the Gap-1 public/private split. Dogfoods its own rule — patterns live in a gitignored source, SKILL.md carries only placeholders.
@@ -94,7 +99,7 @@ Frontier digest anchored on FH's 3-layer identity + Core Axis (WebSearch engine;
 
 ### 2026-05-31 | anti-bias, multi-team, adversarial, token-coverage | steel-quench, sim-conductor, experiment, v2-paper
 **File:** tracks/_meta/fh_multiteam_token_coverage_2026_05_31.md
-Experiment 5 — Multi-Team Adversarial Panel measured on source-grounding-audit SKILL.md. 4 conditions (C1 single / C2 cross-session / C3 +gemini / C4 codex-TTY-fail=C3). Key results: C1→25% coverage, C2→75%, C3→100%. Claude blind spots: 3 findings (25% of total), 1 S-grade. Claude-side cost C2→C3: +0 tokens (H3 validated — Gemini billed to separate quota). Codex CLI present but headless-inoperable. Updated steel-quench/sim-conductor/source-grounding-audit/harness-doctor/harvest-loop with Multi-Team Panel design + human gates + synthesizer cross-session. v2 paper Experiment 5 section drafted with full metrics table.
+Experiment 5 — Multi-Team Adversarial Panel measured on phantom-quench SKILL.md. 4 conditions (C1 single / C2 cross-session / C3 +gemini / C4 codex-TTY-fail=C3). Key results: C1→25% coverage, C2→75%, C3→100%. Claude blind spots: 3 findings (25% of total), 1 S-grade. Claude-side cost C2→C3: +0 tokens (H3 validated — Gemini billed to separate quota). Codex CLI present but headless-inoperable. Updated steel-quench/sim-conductor/phantom-quench/harness-doctor/harvest-loop with Multi-Team Panel design + human gates + synthesizer cross-session. v2 paper Experiment 5 section drafted with full metrics table.
 - Decision: decision rule confirmed — routine→C2 (cross-session), pre-publish→C3+ (zero Claude overhead)
 ### 2026-05-31 | synergy, integration, playbook | opencode, hermes, openhuman, governance, marketing
 **File:** knowledge/shared/harness-core/fh_synergy_playbook.md

package/CHEATSHEET.md

@@ -97,7 +97,7 @@ git config core.hooksPath templates/.git-hooks
 chmod +x templates/.git-hooks/pre-commit
 ```
 
-After running `/steel-quench` and `/source-grounding-audit` in your session, Claude creates the Axes 2+3 pass marker automatically. If it doesn't (e.g., session interrupted), create it manually:
+After running `/steel-quench` and `/phantom-quench` in your session, Claude creates the Axes 2+3 pass marker automatically. If it doesn't (e.g., session interrupted), create it manually:
 
 ```bash
 touch "tracks/_meta/.axes_23_passed_$(git rev-parse --abbrev-ref HEAD | tr '/' '_')_$(date +%Y-%m-%d).marker"
@@ -300,6 +300,31 @@ Standard `/compact` lets the auto-algorithm decide what to preserve. **Wrap-then
 
 > **context-doctor integration**: saying `"context is getting full"` or `"slow"` → context-doctor will propose this pattern automatically.
 
+#### 6.1 — Disk-handoff: survive even a *forced* auto-compact
+
+Wrap-then-Compact (above) only helps when **you** choose the moment. The dangerous case is the
+**unplanned auto-compact at 100%+** — the harness summarizes on its own and your R&D nuance (the back-and-forth
+that produced a decision) gets dropped. The wrap-summary trick can't save you, because there was no wrap.
+
+The fix is to **stop relying on the conversation surviving at all**. Put the recoverable facts **on disk**
+*before* you compact, so a fresh session reads a file — not the lossy summary:
+
+| Step | Action |
+|---|---|
+| 1. Say **"compact"** (or notice ~80%) | Treat it as a trigger, not just a command |
+| 2. Claude writes a **handoff file** first | A single file with: current status · the *one* next action · constraints to preserve · file paths + commit hashes |
+| 3. Claude confirms `"backup written → <path>"` | Now the facts live on disk, independent of any summary |
+| 4. You run `/compact` (or auto-compact fires) | Even a forced 100% compact can only blur dialogue nuance |
+| 5. Next session lands on the handoff file | Conclusions + next step recovered from disk, not memory |
+
+**Where the handoff lives**: a durable, non-gitignored location a fresh session will actually open —
+a `handoff/NEXT_ACTION_<date>.md` in a companion store (Mode D), **or** for everyone else a note committed
+to the working repo / a PR comment. **Never** a gitignored local file (it's wiped on an ephemeral reclaim).
+
+> **Difference from Lever 6**: Wrap-then-Compact curates *what the summary says*; the disk-handoff makes the
+> facts *not depend on the summary existing at all*. Use both — the handoff is the floor that holds when an
+> auto-compact you didn't ask for fires. Say **"compact"** and Claude does step 2 automatically.
+
 ---
 
 ## 11. New technology introduction pipeline
@@ -365,3 +390,102 @@ Claude agents feature
 | "simulate how to use this in FH" | Immediately enter Step 2 |
 | "scan CC new features" | Step 1 (`--cc-scan`) → Step 2 auto-proposal |
 | "apply simulation results" | Immediately enter Step 3 |
+
+---
+
+## 12. Skills & agents — what each does and what to say
+
+> You don't memorize skill names. **Say the plain-language phrase** and Claude routes to the right skill
+> (the same trigger map lives in `CLAUDE.md`). The `/skill` form is the explicit fallback. Skills are
+> independently runnable — `fh-commons` ones work even without the full hub.
+
+### Verification & grounding — *"is this actually right?"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `steel-quench` | All-angle adversarial attack on a design/output, then defense, until zero new blockers | "run the quench", "attack from the root", "shake out the design anxiety" |
+| `phantom-quench` | Back-traces every claim to its declared source; flags **Phantom Claims** (present in the artifact, not in the source). *Old name: `source-grounding-audit`.* | "verify the source", "where did this come from", "grounding audit", "phantom check" |
+| `verify-bidirectional` | Re-checks a decision from the opposite direction + folds your counter-argument into the baseline | "is that right?", "double-check this", "give me the counterargument" |
+| `convergence-loop` *(commons)* | Re-runs a gate until a round adds zero new failures — "truly passed", not "passed once" | "a single pass seems suspicious", "loop until it converges" |
+| `prompt-regression` | After a CLAUDE.md/rule/skill edit, probes for silent behavior regressions vs saved baselines | "did my rule change break anything", "regression-check the harness" |
+| `return-path-gate` | Checks that a skill chain is **closed** (callee's verdict feeds the caller), not fire-and-forget | "is this chain closed", "does the result feed back" |
+
+### Orchestration — *"coordinate the work"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `agent-composer` | Reads the work context and decides which agents to dispatch, when, and in what order | "run these in parallel", "which agents should handle this", "orchestrate agents" |
+| `pipeline-conductor` | Chains the 4 verification pipelines into one gated sequence + a single aggregated report | "run the full quality gate", "end-to-end verification sweep" |
+| `goal-quench` | Adds a token-budget ceiling + quality gate on top of an autonomous `/goal` run | "run this autonomously but cap the budget", "gate the goal run" |
+| `meta-prompt-builder` | Designs *what to say* to each agent (pairs with agent-composer's *what to orchestrate*) | "help me write a prompt", "build a prompt for the agent" |
+| `deliberation` *(commons)* | Innovator → Devil → Mediator 3-role structured debate to a synthesis | "deliberate this", "argue both sides then synthesize" |
+
+### Diagnosis — *"something feels off"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `harness-doctor` | Diagnoses harness structure (L1–L4) on the principle "a good harness gets simpler over time" | "check my Claude setup", "the harness feels complex", "too many skills" |
+| `context-doctor` | Finds the 3 main causes of token waste + prescribes `.claudeignore` / `/clear` timing | "session is slow", "context is getting full", "clean up context" |
+| `install-doctor` | Diagnoses conflicts/duplicates/overwrite risks before installing plugins into a project | "check the install", "verify my setup", "will this overwrite anything" |
+| `mcp-circuit-breaker` *(commons)* | Detects MCP failure loops, trips a breaker to stop retry waste, proposes alternatives | "MCP keeps failing", "same tool error is looping" |
+
+### Harvesting & learning — *"keep what we learned"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `harvest-loop` | End-of-session weekly audit → pattern scan → 3-tier improvement proposals → PR draft | "wrap up this week", "harvest the session", "weekly review" |
+| `field-harvest` | Back-propagates a reusable pattern found in a field project into the hub | "I could reuse this", "pull this pattern into the hub" |
+| `memory-hygiene` | Catches "stale-but-confident" memory that drifted from reality; updates or prunes it | "memory feels bloated", "clean up memory", "is my memory still accurate" |
+| `edit-manifest` | Records a predicted-impact line per edit, closing the predict-vs-verify loop for harvest-loop | "record this edit's predicted impact" *(usually auto, Axis 4 of the gate)* |
+| `contention-layer` | When two skills conflict, harvests the missed validation angle instead of discarding one | "these two skills disagree", "harvest the conflict" |
+
+### Gates & guards — *"safe to ship / publish?"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `token-budget-gate` *(commons)* | Estimates token cost before a multi-step task, then calibrates against actual after | "how expensive is this", "estimate the token budget first" |
+| `asset-placement-gate` | Routes a new skill/agent/plugin to the right place (hub vs project), no role overlap | "where does this go", "should this be shared", "hub or project" |
+| `marketplace-gate` | Scores a repo against 5 listing criteria (README, zero-config, maintenance, dup, safety) | "is this OK to publish", "ready for the marketplace", "pre-publish check" |
+| `public-surface-audit` | Scans git-tracked files for operator-private tokens (real username, corp names, home paths) | "did I leak anything", "scan for private tokens", "is my split clean" |
+| `self-marketing-lint` | Flags self-promotional / hype wording in descriptions (plain-text discipline) | "lint the marketing language", "is this description hyped" |
+
+> **Going public?** Don't run these one at a time — say **"publish"** / **"make this repo public"** and Claude
+> fires the **Pre-Publish Surface Gate** (CLAUDE.md), which runs `public-surface-audit` + `marketplace-gate`
+> Check 5 *before* the irreversible action. Portable checklist: `templates/PRE-PUBLISH-CHECKLIST.md`.
+
+### Discovery — *"what's out there?"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `plugin-recommender` | Searches marketplaces + open source for a task, ranks by quality, gives install commands | "what plugin should I use", "find a tool for Jira tickets", "recommend a plugin" |
+| `cross-ecosystem-synergy-detection` | Finds cross-invocable pairs across your installed plugins/CLIs + a synergy ranking | "are my tools working together", "any synergy / overlap", "can these integrate" |
+| `frontier-digest` | Pulls latest AI/agent/harness trends from HN + arXiv into actionable insights | "latest AI trends", "frontier digest", "what's new out there" |
+
+### Simulation, review & clarification — *"pressure-test the thinking"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `sim-conductor` | Profiles a target → derives personas → parallel-agent audit → M/S/R triage. Areas: A external-user · B internal-audit · C ideation | "external user perspective", "run an internal audit", "simulate this" |
+| `apex-review` | Reviews from a top-level decision-maker's lens, not a practitioner's | "will this hold up for leadership", "CTO-level review", "approval deck" |
+| `deep-clarify` | Turns a vague request into an actionable spec through Socratic questioning | "I'm not sure what to build", "help me clarify the requirements" |
+
+### Setup & onboarding — *"get started / keep it tidy"*
+
+| Skill | What it does | Say this |
+|---|---|---|
+| `install-wizard` | First-install onboarding (zshrc, sentinels, the FH self-gate) | "first-time setup", "run the install wizard" |
+| `hub-cc-pr-reviewer` | Reads a PR diff → 8-matrix baseline-consistency check → review comment + merge call | "review this PR", "check this diff" |
+| `skill-splitter` | Splits an over-large SKILL.md that "does everything" into scoped files | "this skill is bloated", "SKILL.md too large", "split this skill" |
+
+### Agents (sub-agents, dispatched — not slash commands)
+
+| Agent | What it does | When it's used |
+|---|---|---|
+| `challenger` *(hub)* | Frontier-grade adversarial evaluator; adapts attack vectors to artifact type, cites evidence per attack | The heavy adversarial reviewer behind steel-quench / harvest-loop |
+| `quench-challenger` *(commons)* | Devil (6-axis attack) + Innovator (alternative) + Prescriber (one-line fix) synthesis | steel-quench Wave 1 calls it first |
+| `fact-checker` *(fh-meta)* | Greps the hub to confirm an asset/skill exists before you recommend it; catches stale facts | "does this already exist in the hub", duplicate-work suspicion |
+| `hub-persona-auditor` *(fh-meta)* | 3+ persona × 4-axis (resonance/confusion/resistance/supplement) audit of an external-facing draft | Before publishing a briefing / card / guide |
+| `persona-innovator` *(fh-meta)* | Generates naming candidates + frame proposals + external frontier signals | "find naming candidates", harness evolution ideation |
+
+> **Don't see your need?** Describe it plainly — `plugin-recommender` searches beyond FH too. And if a
+> phrase here doesn't route correctly, the explicit `/skill-name` form always works.

package/CLAUDE.md

@@ -133,7 +133,7 @@ No user request is needed — this is a mandatory autonomous step, not a proposa
 
 ```
 FH asset modified → Axis 1 (regression_guard.sh --pr {BRANCH})
-  → Axis 2 (/steel-quench) → Axis 3 (/source-grounding-audit)
+  → Axis 2 (/steel-quench) → Axis 3 (/phantom-quench)
   → marker: tracks/_meta/.axes_23_passed_{branch}_{date}.marker
   → Axis 4 (/edit-manifest RECORD, today's entry in edit_manifest.yaml)
   → All 4 PASS → git commit allowed   |   Any FAIL → fix inline, re-run
@@ -145,7 +145,7 @@ FH asset modified → Axis 1 (regression_guard.sh --pr {BRANCH})
 
 **Substantive carve-out — `knowledge/` · `docs/*.md` · `AGENTS.md`** (Axes 2–3 DO run, despite these not being SKILL/rules/templates): a change to any of these is **not** light if its diff adds a fenced code block (```` ``` ````) or a citation/version claim (`arXiv:` / `DOI` / `http` / a versioned dependency like `x.y.z`). Executable patterns and factual claims need phantom-detection + adversarial review *wherever they live* — `knowledge/` Implementation-Patterns sections carry runnable commands, `docs/` holds published guides, and `AGENTS.md` is the Codex-user entry point, so a phantom skill name or wrong version there is an external-facing error the gate must catch. Prose-only edits (typos, rewording, link fixes) stay light. Detection is mechanical: `git diff` adds a ```` ``` ```` fence or a citation token → run Axes 2–3.
 
-**Unavailable axis**: If steel-quench or source-grounding-audit are not installed, note `Axis N: skipped (skill unavailable)` and proceed. Axis 1 PASS alone is sufficient to unblock a PR when Axes 2–3 are unavailable. Axis 4 (edit-manifest): if the skill is not installed, substitute a manual one-line prediction appended to `tracks/_meta/edit_manifest.yaml` — the record is what matters, not the skill.
+**Unavailable axis**: If steel-quench or phantom-quench are not installed, note `Axis N: skipped (skill unavailable)` and proceed. Axis 1 PASS alone is sufficient to unblock a PR when Axes 2–3 are unavailable. Axis 4 (edit-manifest): if the skill is not installed, substitute a manual one-line prediction appended to `tracks/_meta/edit_manifest.yaml` — the record is what matters, not the skill.
 
 **Axis ownership** (each skill is already complete — orchestrator only coordinates):
 
@@ -153,11 +153,46 @@ FH asset modified → Axis 1 (regression_guard.sh --pr {BRANCH})
 |---|---|---|
 | Backward | `regression_guard.sh` | Critical section loss, broken refs, syntax errors, line reduction |
 | Adversarial | `steel-quench` | Trigger phrase collisions, design attack surface, over-engineered steps |
-| Forward | `source-grounding-audit` | Phantom references, paths that don't exist, stale external links |
+| Forward | `phantom-quench` | Phantom references, paths that don't exist, stale external links |
 | Record | `edit-manifest` RECORD | Logs predicted impact — closes the predict-verify loop for future harvest-loop |
 
 ---
 
+## Pre-Publish Surface Gate (Irreversibility Gate — Publish, not Commit)
+
+**Order invariant: scrub before publish, never publish-then-scrub.** Public exposure is effectively
+irreversible — a repo or package is briefly live the instant it goes public and may be cached or forked
+before any scrub. So the audit must fire **pre-publish**, not after.
+
+**When this gate fires** — *before* any action that makes a repo/package **publicly visible for the
+first time**, especially one **derived from internal/company assets** (operator-IP that originated in a
+private harness): `gh repo create --public`, `gh repo edit --visibility public`, a first push to a new
+public remote, `npm publish`, `twine upload`, a private→public visibility flip.
+
+**Required before the public action** (both must be non-LEAK) — this gate is the **umbrella that invokes
+both**, not a competitor to them; when publish intent is detected, fire *this* gate (it then runs both),
+not marketplace-gate alone:
+1. `/public-surface-audit` — operator-private token scan (real username, corp asset names, home paths)
+2. `/marketplace-gate` Check 5 — broad public safety (API keys, internal domains, license)
+
+> Routing vs the rows below: `/marketplace-gate` alone = "is this ready to **list on a marketplace**?";
+> `/public-surface-audit` alone = reactive "did I leak a token?"; **this gate** = the *act of going
+> public* (visibility flip / first public push / registry publish) — it chains the other two.
+
+**Cheap mechanical pre-flags** (any one → stop and run the gate): author/commit **email = corp domain** ·
+`LICENSE`/`README` contains a **private harness name or internal codename** · **module paths encode
+internal acronyms**.
+
+**Why no hook (honest)**: the irreversible action is `gh repo create --public` / a visibility flip, **not
+`git commit`** — and it usually happens in a **separate repo**, not forge-harness. The FH pre-commit hook
+cannot catch either. This gate is therefore **AI-behavioral** (proactive trigger below) **+ a portable
+checklist** (`templates/PRE-PUBLISH-CHECKLIST.md`) the operator runs on any repo, on any machine.
+
+> Origin: 2026-06-05 `phantom-gate` shipped public, then needed a private→de-company-scrub→re-public
+> round-trip (`fh_signal_2026-06-05_fh-direct`). PSA existed but nothing forced it pre-publish.
+
+---
+
 ## Autonomous Initiative Layer — Context-Triggered Skill Proposals (Active Throughout Session)
 
 At any point during a session, when the following signals are detected, propose the relevant skill in one line.
@@ -182,6 +217,7 @@ Proposal format: `"I see [X]. Want me to run /[skill] to [one-line description]?
 | "where does this go", "asset location", "hub vs project", "placement" | `/asset-placement-gate` |
 | "add to marketplace", "OK to publish", "pre-publish check" | `/marketplace-gate` |
 | "did I leak anything", "public surface audit", "private token scan", "is my split clean", "check tracked files for private tokens" | `/public-surface-audit` |
+| "publish", "make public", "make this repo public", "go public", "gh repo create --public", "flip to public", "first public push", "publish the package", "npm publish", "twine upload" (publish intent — **proactive**, fire *before* the action) | **Pre-Publish Surface Gate** (see above → `/public-surface-audit` + `/marketplace-gate` Check 5 must PASS first) |
 | "look at this again", "is this right", "counterargument", "re-validate" | `/verify-bidirectional` |
 | "MCP failing", "tool keeps erroring", "circuit-breaker", "same error looping" | `/mcp-circuit-breaker` |
 | "token budget", "how expensive", "estimate tokens", "will this cost a lot" | `/token-budget-gate` |
@@ -261,7 +297,7 @@ Tiers: S=light(~5K) · M=standard(~15K, FH default) · L=full(~30K) · XL=max(~6
 
 **Current: Beta → External Validation Achieved** — v1.0 formal release conditions: additional external install evidence + at least 1 external PR.
 
-> Usage modes (A/B/C) + differentiated value (Layer 1/2) details: `.claude/rules/modes_and_value.md`
+> Usage modes (A/B/C) + what-you-get (Layer 1/2) details: `.claude/rules/modes_and_value.md`
 
 ## Auto Project Mapping Protocol
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <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">
+  <img src="https://raw.githubusercontent.com/chrono-meta/forge-harness/main/docs/banner.png" alt="forge-harness — Forge your projects, pass them through, faster." width="680">
 </p>
 
 <p align="center">
@@ -11,14 +11,25 @@
 </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 —<br>shared skills, accumulated context, and a compounding improvement loop.
+  <b>Forge your Claude Code projects — pass them through, they come out faster.</b><br>
+  A practitioner's meta-harness: it raises each project's <b>floor</b> (harness-ify the setup)<br>and <b>ceiling</b> (accelerate the work), then compounds the gains across your whole portfolio.
+</p>
+
+<p align="center">
+  <i>Fork it. Rename it. Make it yours.</i>
 </p>
 
 <p align="center">
   <img src="docs/pillars.svg" alt="FORK · ADAPT · COLLABORATE · EMPOWER" width="680">
 </p>
 
+<p align="center">
+  <a href="ETHOS.md"><b>The principles</b></a> ·
+  <a href="WHY.md"><b>Why it exists</b></a> ·
+  <a href="OUTPUT_EVIDENCE.md"><b>The evidence</b></a> ·
+  <a href="CHEATSHEET.md"><b>How to use it</b></a>
+</p>
+
 ---
 
 | If you're here because… | forge-harness solves it |
@@ -60,6 +71,11 @@ claude plugin install -s user fh-meta@forge-harness
 cd ~/projects/{your-project} && claude
 ```
 
+> 🚪 **New here / just want the skills?** Start with the opinionated front door —
+> [`templates/starter_profile.md`](templates/starter_profile.md): one install command, a curated
+> first-five skills, and a zero-install governance gate (`npx … fh-gate`). The other 28 skills wait
+> until you need them.
+
 ---
 
 ## What it is
@@ -84,6 +100,19 @@ Project B  ──→  connect hub in CLAUDE.md
 
 ---
 
+## Why it works
+
+After a long co-authoring session with your AI, you and it share the same context — and the same blind spots. The reviewer worth having is the one who never saw your reasoning. You can get that by hand: paste the work into a fresh, empty chat. FH just turns that chore into one routine command.
+
+- **sidecar / agent dispatch** → a reviewer with none of your session's context
+- **steel-quench · phantom-quench** → that cold pass, on demand
+
+It's model-agnostic: co-build with one AI, run the cold pass with any other. Whoever was absent from the original session is your cold reviewer — this is not a ranking of models.
+
+**What FH does not claim:** the cold pass is your base model's own ability, not a detection engine FH adds — a plain prompt to a fresh instance does much of the same. FH's value is narrower and honest: it takes a method drawn from real practice and makes running that independent pass routine, instead of a chore you skip. The methodology is copyable; what FH packages is the workflow, not a secret sauce.
+
+---
+
 ## Governance layer for AI-generated code
 
 FH wraps any coding agent (OpenCode, Codex, etc.) as a **post-generation governance gate**.
@@ -100,7 +129,7 @@ FH_BACKEND=auto npx --package @chrono-meta/fh-gate fh-gate "src/foo.ts" full
 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 --skill phantom-quench --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
 ```
 
@@ -118,7 +147,24 @@ Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integ
 
 ---
 
-## 35 skill files, 5 agents
+## The forge
+
+forge-harness treats a project like steel — and the metaphor is literal, not decoration. Work is shaped,
+hardened by attack, and only then does it ship faster, for having survived.
+
+| Movement | What happens | The commands |
+|---|---|---|
+| **Forge** | shape the raw project into a harness — raise its floor | `install-wizard`, "harness-ify this project" |
+| **Quench** | harden it by attack — the cold pass leaves standing only what is sound | `steel-quench` · `phantom-quench` |
+| **Temper** | take the brittleness back out of the hardened asset | *the movement being forged next* |
+| → **Accelerate** | a blade that survived the forge cuts faster | `goal-quench` — *Pass → Accelerate* |
+
+Three movements are shipped; **temper** is the direction ahead — and naming the movement we have *not*
+finished is the point (see [`ETHOS.md`](ETHOS.md#the-forge)). Around the forge, two more signatures keep
+it running: `harvest-loop` (each session's lessons become permanent skills) and `agent-composer`
+(orchestrate the dispatch). The other skills wait until you need them — full list below.
+
+## 33 skills · 5 agents
 
 <details>
 <summary>Full asset activation check</summary>
@@ -126,7 +172,7 @@ Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integ
 | Asset | Role | Triggers |
 |---|---|---|
 | `steel-quench` | Full-spectrum adversarial verification | "Run the quench", "Attack from the root" |
-| `source-grounding-audit` | Phantom claim detection + source back-tracing | "Verify the source", "Grounding audit" |
+| `phantom-quench` | Phantom claim detection + source back-tracing | "Verify the source", "Grounding audit" |
 | `harvest-loop` | End-of-session learning → evolution pipeline | "Harvest the session" |
 | `agent-composer` | Plans optimal agent dispatch | "Run in parallel", "Which agents?" |
 | `sim-conductor` | Meta-simulation orchestrator | "External user perspective" |
@@ -160,7 +206,7 @@ Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integ
 
 | Cluster | Skills |
 |---|---|
-| Verification | `steel-quench` · `source-grounding-audit` · `convergence-loop` · `prompt-regression` · `return-path-gate` |
+| Verification | `steel-quench` · `phantom-quench` · `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` |
@@ -169,6 +215,9 @@ Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integ
 | Content / Simulation | `sim-conductor` · `apex-review` · `meta-prompt-builder` · `deep-clarify` |
 | Setup | `install-wizard` · `hub-cc-pr-reviewer` · `skill-splitter` |
 
+> **Full phrasebook** — every skill + agent with its one-line definition and the plain-language phrase
+> that triggers it: [`CHEATSHEET.md` §12](CHEATSHEET.md#12-skills--agents--what-each-does-and-what-to-say).
+
 </details>
 
 ---
@@ -193,17 +242,21 @@ If you use external CLIs (Gemini, Codex, `gh copilot`) as sidecars, their costs
 
 ---
 
-## Multi-Model Sidecar (v1.3)
+## Multi-Model Sidecar
 
-Run Gemini, Codex, or `gh copilot` as independent peer reviewers alongside Claude.
+Run Gemini, Codex, or `gh copilot` as independent reviewers alongside Claude. The point is **context
+isolation**: a reviewer that did *not* co-create the work is cold to its froth — whoever sits *outside* the
+collaboration tends to catch what the co-author, now an advocate for the shared result, glides past. It's
+symmetric, not a model-ranking: when you co-build with Gemini, a fresh Claude catches its froth; when you
+co-build with Claude, a fresh sidecar catches Claude's.
 
-| Tier | Setup | Defects found |
-|---|---|---|
-| **C1** Single Claude | Default | 25% |
-| **C2** 3 cross-session Claude personas | No extra tools | 75% |
-| **C3** C2 + external CLI | External CLI installed | 100% (+3 Claude blind spots) |
+In one internal case study, layering reviewers surfaced progressively more issues — a single in-session
+pass missed items that cross-session personas caught, and an external-CLI reviewer surfaced a few the
+Claude personas shared a blind spot on. Treat it as a worked example, **not a benchmark**: the gain scales
+with task complexity and how much you co-created the artifact, and an isolated reviewer also adds false
+positives you have to triage. Whether the net is worth it on a given task is an empirical, per-use question.
 
-Claude-side token cost: **zero increase** C2→C3.
+Claude-side token cost does not increase when the extra reviewer is an external CLI — it bills to its own quota.
 
 ---
 

package/docs/codex-compat.md

@@ -15,7 +15,7 @@ cat plugins/fh-meta/skills/<skill>/SKILL.md path/to/artifact \
 - `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.
+- `codex exec` has its own file-read tools, so a skill that back-traces claims to source files (e.g. `phantom-quench`) can verify paths itself — it produced real `file:line` citations in validation.
 
 ## Runtime adapters
 
@@ -48,7 +48,7 @@ Backend defaults:
 
 ```bash
 FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run \
-  --skill source-grounding-audit \
+  --skill phantom-quench \
   --file docs/foo.md
 
 FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run \
@@ -81,8 +81,8 @@ These are **author** runs — they confirm the M1 tier assignments are accurate
 
 | 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" |
+| `phantom-quench` | 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 `phantom-quench` | **Correct** — applied the 4-criteria bar, flagged criterion ④ overlap, routed to **Drop** with "route intent to phantom-quench" |
 
 Both ran end-to-end with no Claude-native dependency. The M1 tier claim holds for the two skills tested.
 

package/docs/pillars.svg

@@ -21,44 +21,41 @@
   <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) ═══ -->
+  <!-- ═══ HARNESS (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 -->
+  <!-- Chain link icon (harness = link) -->
   <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>
+  <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">HARNESS</text>
+  <text x="88" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Harness-ify a project</text>
+  <text x="88" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">— raise its floor</text>
 
-  <!-- ═══ ADAPT (x=176, cx=256) ═══ -->
+  <!-- ═══ FORGE (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>
+  <!-- Hammer icon -->
+  <rect x="247" y="28" width="18" height="7" rx="1.5" fill="none" stroke="#e07d2a" stroke-width="2"/>
+  <line x1="256" y1="35" x2="256" y2="50" stroke="#e07d2a" stroke-width="2.4" stroke-linecap="round"/>
+  <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">FORGE</text>
+  <text x="256" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Temper it through</text>
+  <text x="256" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">adversarial gates</text>
 
-  <!-- ═══ COLLABORATE (x=344, cx=424) ═══ -->
+  <!-- ═══ ACCELERATE (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>
+  <!-- Forward chevrons -->
+  <path d="M414,29 l9,8 l-9,8 M426,29 l9,8 l-9,8" fill="none" stroke="#e07d2a" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="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">ACCELERATE</text>
+  <text x="424" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Pass it through —</text>
+  <text x="424" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">it comes out faster</text>
 
-  <!-- ═══ EMPOWER (x=512, cx=592) ═══ -->
+  <!-- ═══ COMPOUND (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>
+  <!-- Rising bars (compounding gains) -->
+  <rect x="581" y="40" width="6" height="10" fill="#e07d2a"/>
+  <rect x="589" y="34" width="6" height="16" fill="#e07d2a"/>
+  <rect x="597" y="27" width="6" height="23" fill="#e07d2a"/>
+  <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">COMPOUND</text>
+  <text x="592" y="76" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">Gains compound across</text>
+  <text x="592" y="88" text-anchor="middle" font-family="Georgia,'Times New Roman',serif" font-size="9.5" fill="#9e7040">your whole portfolio</text>
 
   <!-- Subtle vertical dividers -->
   <line x1="176" y1="18" x2="176" y2="86" stroke="#c46820" stroke-width="0.5" stroke-opacity="0.35"/>

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

@@ -196,7 +196,7 @@ All backends must produce the same `FH_STATUS` / `FH_GATE_VERDICT` header. Missi
 ### 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 --skill phantom-quench --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
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrono-meta/fh-gate",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "FH runtime adapters — run FH governance, skills, and agents via Claude or Codex with machine-parseable gates.",
   "license": "MIT",
   "keywords": [

package/plugins/fh-meta/skills/agent-composer/SKILL.md

@@ -58,7 +58,7 @@ For each subtask in the composition plan:
 | Subtask type | Strong fit signal | Weak fit signal |
 |---|---|---|
 | Adversarial review | `subagent_type="challenger"`, artifact_type match | general-purpose only |
-| Phantom detection | `source-grounding-audit` | general-purpose only |
+| Phantom detection | `phantom-quench` | general-purpose only |
 | Persona simulation | `hub-persona-auditor`, deep-insight persona | general-purpose only |
 | Code generation | `writes: true` + code tools | `writes: false` or no code tools |
 | Audit-only | `writes: false` (safe) | `writes: true` (risky for audit) |

package/plugins/fh-meta/skills/agent-composer/SKILL_detail.md

@@ -401,10 +401,10 @@ fit_score     = 0.00  → GAP — do not assign
 **Example 3 — Phantom detection subtask**
 
 - Subtask type: `phantom-detection`
-- Candidate agent: `source-grounding-audit` skill (`declared_capabilities=["phantom-detection","source-trace"]`, `writes=false`)
+- Candidate agent: `phantom-quench` skill (`declared_capabilities=["phantom-detection","source-trace"]`, `writes=false`)
 
 ```
-role_match    = 0.40  (role matches "source-grounding-audit" → "phantom-detection")
+role_match    = 0.40  (role matches "phantom-quench" → "phantom-detection")
 tools_overlap = 0.30  (Read+Bash match; required_tools overlap = 1.0)
 writes_compat = 0.20  (audit-only; writes=false → bonus)
 cap_bonus     = 0.10  (declared_capabilities contains "phantom-detection")

package/plugins/fh-meta/skills/edit-manifest/SKILL.md

@@ -57,7 +57,7 @@ append a manifest entry **before** committing.
 
 > **Wiring note**: This Record step is invoked manually or via harvest-loop until the
 > CLAUDE.md 3-axis auto-gate is explicitly extended to call it. The auto-gate currently
-> chains regression_guard → steel-quench → source-grounding-audit; adding edit-manifest
+> chains regression_guard → steel-quench → phantom-quench; adding edit-manifest
 > Record as a pre-step is a proposed extension, not yet wired. Do not assume automatic
 > invocation — call it explicitly after an FH asset edit.