@chrono-meta/fh-gate 1.2.2 → 1.4.0

package/AGENTS.md

@@ -19,11 +19,14 @@ CLAUDE.md governs *how* the session runs. AGENTS.md defines *what each agent doe
 
 ## Agent Registry
 
-forge-harness ships 5 tracked agents across `.claude/agents/` and plugin `agents/` directories. Four serve general harness operations; one (`quench-challenger`) is steel-quench-dedicated.
+forge-harness ships 8 tracked agents across plugin `agents/` directories. The **user-mastery spectrum** (`beginner` · `main-player` · `expert`) plus `challenger` (adversarial axis) supply multi-persona review; `fact-checker`, `hub-persona-auditor`, and `persona-innovator` serve general harness operations; `quench-challenger` is steel-quench-dedicated.
 
 | Agent | File | Role | Invoked by |
 |---|---|---|---|
-| `challenger` | `.claude/agents/challenger.md` | Frontier-grade adversarial evaluator — adapts attack vectors to artifact type, enforces evidence citation, models its own information asymmetry | `steel-quench`, `harvest-loop`, `sim-conductor`, or direct dispatch |
+| `beginner` | `plugins/fh-meta/agents/beginner.md` | First-contact cold-read standpoint (spectrum entry tier) — onboarding friction a fluent author cannot feel; constructive, not adversarial | `sim-conductor` Area A, `marketplace-gate`, `install-wizard`, or direct dispatch |
+| `main-player` | `plugins/fh-meta/agents/main-player.md` | Engaged-user standpoint (spectrum core tier) — intelligently scopes Light/Midcore/Heavy; Heavy = classic power-user edge/limit lens | `sim-conductor` Area A/D-code, or direct dispatch |
+| `expert` | `plugins/fh-meta/agents/expert.md` | Domain-authority standpoint (spectrum frontier tier) — web-grounded accuracy + SOTA currency, citation-enforced | `sim-conductor` Area E/D, paper review, or direct dispatch |
+| `challenger` | `plugins/fh-meta/agents/challenger.md` | Frontier-grade adversarial evaluator — adapts attack vectors to artifact type, enforces evidence citation, models its own information asymmetry; U1 absorbs the skeptic "why not just X?" lens | `steel-quench`, `harvest-loop`, `sim-conductor`, or direct dispatch |
 | `fact-checker` | `plugins/fh-meta/agents/fact-checker.md` | Pre-recommendation deduplication — greps hub assets for existing skills/agents/patterns before main agent commits to a new recommendation; catches stale facts and duplicate work | Main agent before any new asset creation or recommendation |
 | `hub-persona-auditor` | `plugins/fh-meta/agents/hub-persona-auditor.md` | Pre-publication audit of external-facing assets — 3+ persona simulation, 4-axis review (resonance/confusion/resistance/supplement), 3-tier revision proposals | `hub-cc-pr-reviewer`, `sim-conductor`, or direct dispatch |
 | `quench-challenger` | `plugins/fh-commons/agents/quench-challenger.md` | Steel-quench dedicated adversary — 3-DNA synthesis of Devil + Innovator + Prescriber; every attack paired with a concrete fix direction | `steel-quench` Wave 1 (primary), `install-doctor`, `marketplace-gate` |
@@ -124,7 +127,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 +144,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` |
@@ -190,6 +226,8 @@ Proposal format: `"I see [X]. Want me to run /[skill] to [one-line description]?
 | "review for the team", "CTO review", "decision-maker", "share with leadership", "approval deck" | `/apex-review` |
 | "run full pipeline", "verify everything", "end-to-end sweep", "chain all verifications" | `/pipeline-conductor` |
 | "help me write a prompt", "build a prompt", "improve this prompt", "prompt template" | `/meta-prompt-builder` |
+| "/goal", "run this autonomously", "big multi-step task", "orchestrate this goal", or **any heavy autonomous/multi-agent run** (proactive — propose *before* running; it is expensive, so the proposal is mandatory, not the auto-run) | `/goal-quench` (budget gate + quality gate) |
+| "I don't know what to build", "how should I approach this", "organize this for me", "clarify this", "정리해줘" (ambiguous request before dispatch) | `/deep-clarify` |
 | "memory feels bloated", "clean up memory", "memory too large", "memory hygiene" | `/memory-hygiene` |
 | "ready to PR", "about to push", "merge this", "PR 올려줘", FH asset changed in session | 4-axis auto-gate (see above — runs automatically, no proposal needed) |
 
@@ -261,7 +299,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
 
@@ -294,10 +332,15 @@ Closing phrase detected ("wrap up", "done", "good work", "end session", etc.)
   → ② If FH assets changed: harvest-loop
   → ③ Sync local/gitignored session state to your durable companion store, if you keep one
   → ④ Memory hygiene — update stale entries + record new session findings
-  → ⑤ Card update ← ABSOLUTE LAST: must capture ①–④ outcomes
+  → ④-b npm freshness — if any npm-shipped asset changed this session (the `package.json` `files[]`
+       surface: skills · agents · README · AGENTS.md · CLAUDE.md · CHEATSHEET), **propose an npm
+       republish**: version bump + Pre-Publish Surface Gate (`/public-surface-audit` + `/marketplace-gate`
+       Check 5) + `npm publish`. The npm-served README and shipped skills/agents freeze at publish time,
+       so updating FH assets without republishing leaves the package stale. **Propose, don't auto-publish.**
+  → ⑤ Card update ← ABSOLUTE LAST: must capture ①–④-b outcomes
   → ⑥ Commit card + push
 ```
-**Card-last guard**: ①–④ must ALL complete before ⑤ runs. Any new information produced
+**Card-last guard**: ①–④-b must ALL complete before ⑤ runs. Any new information produced
 during ①–④ (new commits, model changes, new findings) feeds INTO ⑤ — card is never
 written mid-sequence and then left open for more work to accumulate after it.
 

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. Quality is the lever — speed is the result." width="680">
 </p>
 
 <p align="center">
@@ -11,14 +11,29 @@
 </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">
+  <b>Quality is the lever; speed is the result.</b> Every change earns its way through the gates —<br>adversarial · phantom · regression — and <i>that</i> is what makes the next change faster.
+</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 +75,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 +104,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 +133,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 +151,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 +176,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 +210,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 +219,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>
 
 ---
@@ -178,32 +231,38 @@ Full spec: [`fh_integration_contract.md`](knowledge/shared/harness-core/fh_integ
 Claude Code does not auto-select models by task complexity — you configure this once.
 
 ```bash
-/model opusplan   # recommended for forge-harness
+/model opus   # recommended for forge-harness — pin Opus so gate/verification turns never silently drop
 ```
 
 | 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 |
+| `/model opus` | Opus handles everything | **FH default** — verification, governance, agent reasoning |
+| `/model opusplan` | Opus *plans* · Sonnet executes *(when Opus engages)* | Cost-conscious routine coding — see caveat |
+| `/model sonnet` | Sonnet handles everything | Fast, simple tasks (no FH gates) |
+
+**Why `/model opus` for FH**: FH is a *quality* harness — its value lives in verification turns (steel-quench, phantom-quench, the 4-axis gate, agent reasoning) that must not silently run on a weaker model. `opusplan`'s Opus engagement is **not guaranteed**: in a measured 10-turn run it used Opus on **0** turns (CC classifies few turns as "plan-mode"), so the reasoning FH leans on quietly ran on Sonnet — pinning `/model opus` removed that variance (22/22 turns Opus in the follow-up). **Sub-agent dispatch** model is set by the dispatch's own `model` parameter; the session model/plan-mode does **not** propagate Opus to sub-agents, so pin Opus there too for adversarial/verification agents. Use `opusplan` only when the task is mostly routine edits and you accept that Opus may not engage.
 
-**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`.
+> **By role**: editing the harness itself → `/model opus` (full). Running FH on a field project → `/model opus` for any gated/verification work; `opusplan` is an acceptable cost tradeoff for routine coding, with the caveat above. Sub-agent token costs are CC-visible 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)
+## 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.