@chrono-meta/fh-gate 2.5.1 → 2.7.0

package/README.md

@@ -3,12 +3,13 @@
 </p>
 
 <p align="center">
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e.svg" alt="MIT License"></a>
-  <a href="https://zenodo.org/records/20397566"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20397566-blue.svg" alt="DOI"></a>
+  <a href="https://github.com/walkinglabs/awesome-harness-engineering#coding-agent-harnesses"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Harness Engineering"></a>
   <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="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e.svg" alt="MIT License"></a>
+  <a href="https://zenodo.org/records/20397566"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20397566-blue.svg" alt="DOI"></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>
 
@@ -17,24 +18,48 @@
 </p>
 
 <p align="center">
-  <sub>If this is useful, a ⭐ helps others find it.</sub>
+  <b>Ask it for things. When the asking repeats, it offers to build you the thing.</b>
 </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.
+  You already tell Claude Code the same things over and over — the checks to run, the rules to hold,
+  the shape a change has to have.<br>
+  <b>forge-harness turns that into something reusable</b>: skills, gates and agents that live in your
+  repo and fire on their own.<br>
+  Its skills stay general on purpose and get shaped to your case as you go.
+  <b>When one shape keeps coming back, it offers to ship it</b> as its own skill, or its own harness.
 </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>
+---
+
+## Try it in two minutes — you do not have to read this document
+
+```bash
+claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
+claude plugin install -s user fh-meta@forge-harness
+git clone https://github.com/chrono-meta/forge-harness.git ~/projects/forge-harness
+cd ~/projects/forge-harness && claude
+```
+
+**Then type `hi`.** A numbered menu appears and takes it from there — pick a door, answer a couple of
+questions, and it runs the install wizard for you. Everything below this line is reference for when you
+want it, not homework before you start.
+
+**What it amplifies** — the number of attempts; trial and error moves off you and runs in parallel.
+**What it does not** — the model's ceiling. A harness lifts a model to its own ceiling, not past it.
+**How you can check** — it grades itself in public, five identities, in every
+[release](https://github.com/chrono-meta/forge-harness/releases); the ones that are not green name
+the real run still missing.
+
+---
 
 <p align="center">
-  <i>Fork it. Rename it. Make it yours.</i>
+  <img src="docs/pillars.svg" alt="FORK - ADAPT - COLLABORATE - EMPOWER" width="680">
 </p>
 
 <p align="center">
-  <img src="docs/pillars.svg" alt="FORK · ADAPT · COLLABORATE · EMPOWER" width="680">
+  <b>Quality is the lever; speed is the result.</b> <i>Fork it. Rename it. Make it yours.</i><br>
+  <sub>If this is useful, a star helps others find it.</sub>
 </p>
 
 <p align="center">
@@ -58,7 +83,7 @@
 
 ---
 
-## Get started in 2 minutes
+## Requirements
 
 **Prerequisite**: Claude Code CLI — verify with `claude --version`
 
@@ -75,11 +100,8 @@ the single place a new machine can learn it. That is an improvement over nowhere
 python3 -m pip install --user pyyaml     # verify:  python3 -c 'import yaml; print(yaml.__version__)'
 ```
 
-Why this is called out rather than left implicit: a release once shipped green from a session whose
-`python3` happened to resolve to an **unrelated project's virtualenv** that had PyYAML, while the
-machine's own `python3` did not. The gate was never bypassed — it passed, and the pass simply was not
-portable. Every verdict from that gate now prints the interpreter and PyYAML version it used, so a
-green states what produced it instead of leaving the reader to assume.
+Every verdict from that gate prints the interpreter and PyYAML version it used, so a green
+states what produced it.
 
 </details>
 
@@ -135,11 +157,41 @@ 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) |
+| CI / non-Claude runtime, gates only | `npx --package @chrono-meta/fh-gate 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) |
 
 ---
 
+## Two version numbers, and they measure different things
+
+This repo publishes **two counters**, deliberately. Conflating them is the single most common way to
+misread the project's status, so they are named here rather than only in the canon.
+
+| Counter | Where you see it | What it means |
+|---|---|---|
+| **Package version** (currently **2.7.0**) | npm, the plugin manifests, `git tag v2.x` | *what you install.* Ordinary release numbering: fixes → patch, new assets and gate lanes → minor, a capability **class** appearing or the thing being rebuilt → major |
+| **Identity-maturity release** (currently **identity-v0.4.0**) | the GitHub **Releases** page | *how far along the harness is.* `0.x` carries an incomplete-but-honest status **by design**; **the all-green ship is reserved for `identity-v1.0.0`** — every one of the five identities at 🟢, none 🔵/🟡/🔴 |
+
+🟥 **A high package number does not mean maturity.** `2.7.0` is not "ahead of" `identity-v0.4.0`; they are not on
+the same scale. The maturity track is deliberately allowed to sit at `0.x` while the package ships and
+improves, because the thing `0.x` refuses to do is **lie** — it says out loud that not every identity has
+cleared its bar yet, and each release names exactly which real run is still missing.
+
+⚠️ **Fixed, and the wart is left on the record**: the two counters used to share one `vX.Y.Z` git-tag
+namespace, and only the maturity track had GitHub *Release* objects — so the Releases page showed
+`v0.3.0` as "Latest" while the shipped package was `2.6.0`. Two layers under one name is a defect this
+project keeps finding in its own gates; here it was in its own version numbers. The maturity track now
+carries its own `identity-v*` prefix (first such release: `identity-v0.4.0`, 2026-08-21). 🟥 **Not** by also publishing the package
+track here — that was tried on 2026-08-21 and reverted the same hour: GitHub gives exactly **one**
+"Latest" badge, so two tracks on one page compete for it, and whichever holds it defines what the repo
+says it is. Putting the package number there pushed the maturity claim — the honest core — below it.
+**The Releases page carries the maturity track; what the package shipped is carried by
+[CHANGELOG](plugins/fh-meta/CHANGELOG.md) and the registry.** Existing tags are left alone — renaming them is an irreversible operation on a public surface, and the
+[Destructive-Op gate](knowledge/shared/harness-core/claude_md_gate_details.md) applies to us too.
+
+Full rules for what each grade requires:
+[`ship_readiness_gate.md`](knowledge/shared/harness-core/ship_readiness_gate.md).
+
 ## What it is
 
 forge-harness is structured as **two distinct layers**:
@@ -320,11 +372,26 @@ That is why the column that matters most below is *what it gets*:
 |---|---|---|---|
 | **ⓐ Different family** | the diff + the author's framing | the **implementation** is wrong | a reviewer from another model family (`auto-decorrelation`) |
 | **ⓑ Standpoint** | the diff + **the target harness's own canon** | **whether the rule you cited actually says that** | run the diff from that harness's own repo and rules ([`§7`](knowledge/shared/harness-core/field_verdict_crossfamily_gate.md)) |
-| **ⓒ Isolated grounding** | the sentences the author wrote + the tree as it stands now | the **claim** is wrong | someone who did not write it re-measures what it says |
+| **ⓒ Isolated grounding** | the sentences the author wrote — their claims *and* what they **declared before starting** — + the tree as it stands now | the **claim** is wrong · the delta does not match what was declared | someone who did not write it re-measures what it says; for the pre-declaration, a gate that reads the stated success definition back against the delta |
 | **ⓓ Third-party encounter** | the problem + **someone else's codebase** | **is this already solved** · where your change touches someone else's repo | look at the same problem in an unrelated third repo |
 | **ⓔ First real use** | one real target | the **way you are measuring** is wrong — the instrument's instrument | run it once against one real target and check the result by hand |
 | **ⓕ Revert and observe** | the tree with the wiring deleted | the **anchor** is wrong — the check is decorative | delete the thing it guards and confirm *that specific* check goes red |
 
+> **ⓒ widened on 2026-08-21, and how it widened is the more useful part.** Every commit marker in
+> this repo has been required since 2026-08-09 to carry the author's own pre-declaration — *what
+> counts as success* and *what I will not do* — written before designing. Measured with a control
+> that day: **nothing read it.** Zero lines of consuming code anywhere, while the sibling fields
+> were checked in 21 places; the gate spec did not even name it. On the real corpus, **37 of 98
+> markers carried no such line at all** — including a panel-reviewed one with 28 lanes and every
+> other field filled. The axes all looked *outward* (the diff, the target repo, prior art, the
+> artifact); none looked at the record's own mandatory field. A slot with no consumer always
+> reports "done", because presence is doing the judging.
+>
+> The fix was not a seventh axis. ⓒ already receives *the sentences the author wrote plus the tree
+> as it stands* — which is, word for word, what a pre-declaration check receives. Tense (declared
+> beforehand vs claimed afterwards) is a **posture**, like adversariality, not an axis. Minting a
+> new one would have repeated the exact error the blind reclassification above found.
+
 **You do not run all six every time, and that is the design** — do not multiply them, **choose**:
 
 ```
@@ -353,6 +420,37 @@ with tools**, the boundary blurs — an outside judgment held that "the store is
 Conversely, "a rule another repo retired long ago" **cannot be fetched by any tool** — there is no reason
 to have access to that project's review history in the first place. That is where ⓓ remains.
 
+**Where a rule lives — and why the always-loaded layer does not have to grow forever.**
+
+A harness learns by writing rules down. The obvious place is the always-loaded file every session
+reads, and that file only ever gets longer. Left there, the reasoning ends in a corner: *a harness
+that keeps learning keeps getting more expensive to start.*
+
+It does not, because a rule has **three possible seats**, and the right one is decided by **when the
+rule has to fire**:
+
+| Seat | Fires | Costs | Fits |
+|---|---|---|---|
+| **Always-loaded** | before you act | every session, every turn | rules whose trigger is an *intention* — tone, "don't normalize the unfamiliar", "prove the instrument works here". Nothing can hook an intention, so salience is the only layer |
+| **The gate's own error message** | at the moment you act | **nothing** | rules whose trigger is an *action*. The message that blocks you also teaches the form: `Write, before the design: success = «…». never = «…».` |
+| **The hook** | after you act | nothing | properties of a record — present · typed · attributable · non-vacuous |
+
+The middle seat is the one that usually goes unused, and it is free. It is
+[gate-locality](knowledge/shared/harness-core/gate_locality_principle.md) applied to salience: the actor reads it exactly where the
+action happens, so it does not have to be carried all session to be there when needed.
+
+🟥 **It is a third layer, not a replacement — and the honest limit is that it only fires on failure.**
+Someone who gets it right never sees it. So mechanizing a rule does **not** shrink the resident layer:
+measured on the very change described above, the machine grew by 480 lines and the always-loaded prose
+by **zero**, and that is correct. The prose has to reach the author *before* they design; the hook
+catches its absence *after*. A backstop cannot substitute for salience that must fire earlier.
+
+⚠️ And the threshold that would tell you the resident layer is "too big" is, in this repo, **not
+grounded** — the numbers in our own doctor skill were introduced without a single line justifying the
+cutpoints, and one of them was set to a value the target already exceeded on the day it landed. We are
+re-deriving them rather than trimming toward a number nobody can defend. Cutting resident text toward
+an unjustified target buys fail-open with the savings.
+
 > 🟥 **Limits to read before citing this**: the six-axis table is **n=1** (one artifact · one session ·
 > one author). Whether the axes' non-overlap is structural or an accident of that day is **unmeasured**.
 > And when the author's self-scoring was stripped out — 16 findings handed, **with their provenance

package/README.zh.md

@@ -3,12 +3,13 @@
 </p>
 
 <p align="center">
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e.svg" alt="MIT License"></a>
-  <a href="https://zenodo.org/records/20397566"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20397566-blue.svg" alt="DOI"></a>
+  <a href="https://github.com/walkinglabs/awesome-harness-engineering#coding-agent-harnesses"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Harness Engineering"></a>
   <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="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e.svg" alt="MIT License"></a>
+  <a href="https://zenodo.org/records/20397566"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20397566-blue.svg" alt="DOI"></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>
 
@@ -17,24 +18,44 @@
 </p>
 
 <p align="center">
-  <sub>如果这对你有用，⭐ 一下能帮助更多人发现它。</sub>
+  <b>有需要就交给它。同一个请求反复出现时，它会主动提议把那件事本身做出来。</b>
 </p>
 
 <p align="center">
-  <b>锻造你的 Claude Code 项目 —— 让它通过，它会更快出炉。</b><br>
-  一个实践者的 <b>元框架 (meta-harness)</b> —— 你的项目框架们所栖居的星系。<br>它抬高每个项目的 <b>下限 (floor)</b>（把设置框架化）和 <b>上限 (ceiling)</b>（加速工作），再把这些收益在你的整个项目组合中复利累积。
+  你大概已经在对 Claude Code 反复说同样的话：要跑的检查、要守的规则、一次变更该有的样子。<br>
+  <b>forge-harness 把这些变成可复用的东西</b>：住在你仓库里、会自己触发的技能、闸门和 agent。<br>
+  技能刻意保持通用，在使用过程中按你的场景当场锻造。
+  <b>当同一种形状反复回来，它就提议出货</b> —— 作为独立技能，或独立框架。
 </p>
 
-<p align="center">
-  <b>品质是杠杆，速度是结果。</b> 每一次变更都要挣得通过门禁的资格 ——<br>对抗 (adversarial) · 幽灵 (phantom) · 回归 (regression) —— 而 <i>正是这一点</i>让下一次变更更快。
-</p>
+---
+
+## 两分钟就能试 —— 你不必读完这份文档
+
+```bash
+claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
+claude plugin install -s user fh-meta@forge-harness
+git clone https://github.com/chrono-meta/forge-harness.git ~/projects/forge-harness
+cd ~/projects/forge-harness && claude
+```
+
+**然后输入 `hi`。** 会出现一个带编号的菜单，之后由工具引导你：选一个入口，回答几个问题，
+它会替你运行安装向导。这条线以下是需要时再查的参考资料，而不是开始前的作业。
+
+**它放大什么**：尝试的次数。试错从你身上移开，并行运行。
+**它不放大什么**：模型的天花板。框架只把模型抬到它自己的天花板，不会更高。
+**如何验证**：它公开自己的评级。五个身份，如实记录在每一次
+[发布](https://github.com/chrono-meta/forge-harness/releases)中。未变绿的那些，会指名说出还缺哪一次真实运行。
+
+---
 
 <p align="center">
-  <i>Fork 它。改名。让它成为你的。</i>
+  <img src="docs/pillars.svg" alt="FORK - ADAPT - COLLABORATE - EMPOWER" width="680">
 </p>
 
 <p align="center">
-  <img src="docs/pillars.svg" alt="FORK · ADAPT · COLLABORATE · EMPOWER" width="680">
+  <b>质量是杠杆，速度是结果。</b> <i>Fork 它。改名。让它成为你的。</i><br>
+  <sub>如果这对你有用，⭐ 一下能帮助更多人发现它。</sub>
 </p>
 
 <p align="center">
@@ -130,7 +151,7 @@ cd ~/projects/{your-project} && claude
 |---|---|
 | 单人开发者，一个项目，只想先试试 | [`templates/starter_profile.md`](templates/starter_profile.md) —— 一条命令，一份精选的头五个技能 |
 | 有多个项目，想要那个复利累积的中枢 | 克隆中枢（见上面的快速上手） |
-| CI / 非 Claude 运行时，只要门禁 | `npx @chrono-meta/fh-gate`（零安装的治理门禁） |
+| CI / 非 Claude 运行时，只要门禁 | `npx --package @chrono-meta/fh-gate fh-gate`（零安装的治理门禁） |
 | 比起 `npx`/`npm` 更习惯 `brew` | `brew tap chrono-meta/forge-harness && brew install forge-harness` —— 内容 100% 一致，只是安装体验不同（社区 tap；尚未进入 Homebrew Core，所以不先加 tap 的话 `brew search` 找不到它） |
 
 ---

package/docs/USER_GUIDE.md

@@ -0,0 +1,118 @@
+# forge-harness 사용 가이드
+
+> **이 문서는 「읽는」 문서다.** 명령을 찾으려면 `CHEATSHEET.md`, 과거 작업을 찾으려면
+> `CATALOG.md`, FH 가 무엇이고 왜 작동하는지는 `README.md` 를 봐라. 여기는 **처음 쓰는 사람이
+> 첫 세션을 완주하는 것**만 다룬다.
+
+---
+
+## 0. 먼저 — 지금 내 상태가 무엇인가
+
+FH 는 세 가지 상태로 쓸 수 있고, **되는 일이 다르다.** 아래를 그대로 실행해서 확인해라.
+
+```bash
+ls CLAUDE.md knowledge/ plugins/ 2>/dev/null   # 있으면 → 클론했다 (A/B)
+claude plugin list | grep fh-meta              # 있으면 → 플러그인이 깔렸다
+ls tracks/ 2>/dev/null                         # 디렉토리가 있으면 → 프로젝트가 매핑돼 있다
+```
+
+| 상태 | 무엇이 되나 | 무엇이 안 되나 |
+|---|---|---|
+| **클론 + 플러그인** | 전부 | — |
+| **클론만** | 규칙·지식·게이트(훅) | 슬래시 커맨드(`/harness-doctor` 등) |
+| **플러그인만** | 스킬 호출 | `knowledge/` 정본, 세션 기록(`tracks/`), 자체 게이트 |
+
+셋 다 아니면 `README.md` 의 설치 절을 먼저 보고 오면 된다.
+확신이 안 서면 **`/install-doctor`** 를 부르면 기계가 대신 판정해준다.
+
+---
+
+## 1. 첫 세션 — 실제로 무엇을 타이핑하나
+
+**「안녕」 한 마디면 된다.** 인사가 온보딩 트리거다(어느 언어든).
+
+```
+당신: 안녕
+FH  : 🐿️  Welcome to FH. ① 첫 프로젝트 만들기 · ② 기존 프로젝트 매핑 …
+```
+
+문이 뜨면 **번호를 말하거나 그냥 하고 싶은 일을 문장으로 말하면 된다.** 문은 안내지 강제가 아니다.
+바로 일을 시키고 싶으면 인사를 건너뛰고 작업을 말해도 된다 — 그러면 메뉴는 안 뜬다.
+
+**문이 하는 일**
+
+| 문 | 언제 고르나 |
+|---|---|
+| ① 프로젝트 매핑 | 이미 있는 레포를 FH 가 알게 한다. 여기서부터 대부분 시작한다 |
+| ② 새 프로젝트 | 아직 없는 것을 처음부터 |
+| ③ 가속/진단 | 매핑된 프로젝트에 대해 «개선해줘» · «진단해줘» |
+| ④ 크로스 시너지 | 프로젝트가 2개 이상일 때만 뜬다 |
+| 🔧 FH 자체 개발 | FH 를 고치는 사람에게만 뜬다 |
+| 📖 가이드 · Q&A | 이 문서를 열거나, FH 사용법을 묻는다 |
+
+---
+
+## 2. 알아두면 헷갈리지 않는 것 넷
+
+**ⓐ FH 는 「대신 해주는」 게 아니라 「틀리기 어렵게」 만든다.**
+그래서 가끔 **막는다.** 커밋이 막히면 고장이 아니라 게이트가 일한 것이고, 화면에 **무엇을 하면
+풀리는지**가 같이 뜬다. 그 문구를 그대로 따르면 된다.
+
+**ⓑ 「없음」과 「못 쟀음」을 구별해서 말한다.**
+FH 는 확인 못 한 것을 0 으로 적지 않는다. `UNMEASURED` · `SKIPPED` · `못 쟀다` 같은 말이 보이면
+**그건 실패가 아니라 정직한 공백**이다. 숫자가 안 나온 게 아니라 안 나왔다고 말하는 중이다.
+
+**ⓒ 비가역한 일 앞에서는 반드시 멈춘다.**
+공개 전환 · 삭제 · 히스토리 재작성. 되돌릴 수 있는 일(커밋 등)은 경고만 하고 넘어간다.
+**이 둘의 차이가 FH 설계의 중심**이다.
+
+**ⓓ 기록은 자동으로 쌓인다.**
+`tracks/` 는 gitignored 라 공개 레포에 안 올라간다. 세션이 끝날 때 카드가 갱신되고,
+다음 세션이 그걸 읽고 이어간다. 「지난번에 뭐 했지」라고 물으면 거기서 찾아 답한다.
+
+---
+
+## 3. 자주 막히는 곳 (FAQ)
+
+**Q. 커밋했는데 `🚫 BLOCKED` 가 뜬다.**
+FH 자산(규칙·스킬·스크립트 등)을 고치면 4축 검증 마커를 요구한다. 화면에 **정확히 무엇을 어디에
+쓰라고** 나온다. 우회(`--no-verify`)는 같은 훅에 있는 삭제 방지 게이트까지 같이 끄니 쓰지 마라.
+
+**Q. 슬래시 커맨드가 안 먹는다.**
+플러그인이 안 깔렸거나 옛 버전이다. `claude plugin list` 로 버전을 보고, 레포 `package.json` 의
+버전과 다르면 `claude plugin update fh-meta@forge-harness` 후 재시작해라.
+**등록됐다 ≠ 최신이다** — 이건 실제로 자주 난다.
+
+**Q. 훅이 안 도는 것 같다.**
+`git config core.hooksPath` 가 `templates/.git-hooks` 를 가리켜야 한다. 비어 있으면
+`/install-wizard` 를 다시 돌려라(멱등이다).
+
+**Q. 플러그인만 깔면 뭐가 없나?**
+`knowledge/` 정본 · `tracks/` 세션 기록 · 이 레포 자체 게이트. 스킬은 돈다.
+
+**Q. `tracks/` 는 왜 gitignored 인가?**
+세션 기록엔 로컬 경로·프로젝트 이름 같은 개인 정보가 섞인다. 공개 레포에 안 올라가는 게 기본이고,
+따로 보관하고 싶으면 개인 저장소를 붙이면 된다.
+
+**Q. 「진단해줘」와 「개선해줘」는 뭐가 다른가?**
+같은 문이다(③). FH 가 기존 검사들을 모아 **M/S/R 로 등급 매긴 목록**을 주고, **자동으로 안 고친다.**
+무엇을 할지는 사람이 고른다.
+
+**Q. 토큰이 너무 든다.**
+`/context-doctor` 를 불러라. 무엇이 상주 중이고 무엇을 뺄 수 있는지 진단한다.
+
+---
+
+## 4. 더 읽을 것
+
+| 알고 싶은 것 | 어디 |
+|---|---|
+| 명령·트리거 문구 전체 | `CHEATSHEET.md` |
+| FH 가 무엇이고 왜 작동하나 | `README.md` |
+| 용어 | `knowledge/shared/GLOSSARY.md` |
+| 예전에 무슨 작업을 했나 | `CATALOG.md` |
+| 기여하기 | `docs/CONTRIBUTING.md` |
+
+---
+
+*이 문서가 답을 안 주면 그냥 물어봐라 — FH 는 위 문서들을 근거로 답하고, **없으면 없다고 말한다.***

package/docs/platform_sustainability.md

@@ -0,0 +1,174 @@
+---
+title: FH Platform Sustainability — Plan B + Simplification Criteria
+type: strategy
+date: 2026-05-18
+tags: [sustainability, plan-b, simplification-gate, scenario]
+---
+
+# FH Platform Sustainability
+
+> **Purpose**: Document how forge-harness survives and evolves in scenarios where the Anthropic official ecosystem expands. Describes simplification gate criteria and meta-harness specification principles together.
+
+---
+
+## 1. FH Survival Strategy Per Anthropic Official Ecosystem Expansion Scenario
+
+As Anthropic develops Claude Code, some FH functions may overlap with default features. This section states FH's differentiation points and survival strategy for each scenario.
+
+### Scenario A: Anthropic official skill marketplace launches
+
+**Risk**: If Anthropic operates an official skill marketplace, FH's plugin distribution function could be replaced.
+
+**FH differentiation**:
+- **Organization-specific domain curation**: Generic skills in the official market vs FH's optimized combinations for your organization's specific infrastructure — irreplaceable
+- **Organizational context preservation**: `tracks/` session history and `knowledge/` domain knowledge are organization-specific assets — cannot be transferred to the official market
+- **Federated market role**: FH becomes a sub-channel (specialized marketplace) of the official market → actually strengthens canonical source positioning
+
+**Strategy**: When official market launches, use `marketplace-gate` skill to select FH assets worth registering in the official market → contribute to the official market in reverse.
+
+---
+
+### Scenario B: Claude Code harness diagnostic features built-in
+
+**Risk**: Features similar to `harness-doctor` and `context-doctor` may be added as Claude Code default features.
+
+**FH differentiation**:
+- **Organization context-specific diagnosis**: Default features are generic — FH has organization-specific diagnostic layers (your GHE structure, network policies, etc.)
+- **Three-Doctor Loop**: `harness-doctor` + `context-doctor` + `sim-conductor` closed-loop connection is a system, not a single feature — not replaceable by one default feature
+- **L4~L5 layers**: Field project connection diagnosis (L4) + skill activity, context fit, and effect indicators (L5) are FH-unique layers
+
+**Strategy**: Delegate L1~L3 that overlap with default features to defaults, and FH focuses on L4·L5 organization-specific layers.
+
+---
+
+### Scenario C: Organization-internal marketplace newly created
+
+**Risk**: If an internal official marketplace is created by your organization's leadership, FH's internal distribution role could be replaced.
+
+**FH differentiation → FH becomes canonical source**:
+- FH = the **original input** for the internal marketplace. Verified skills originate from FH → the market is a distribution channel
+- `marketplace-gate` skill already performs pre-registration 5-point suitability gate — can naturally integrate with the internal market quality gate
+- `field-harvest` feeds field patterns back to FH → plays the role of automatic supply pipeline to the internal market
+
+**Strategy**: When internal marketplace is created, position FH as canonical source. Register FH in the internal market as an official source.
+
+---
+
+### Common principle: Replacement vs Complement judgment criteria
+
+| Judgment criterion | Replaced (delegate) | Complement maintained |
+|---|---|---|
+| Generic function | Delegate to default feature + remove from FH | — |
+| Organization-specific function | — | Maintain in FH + layer on top of default feature |
+| Domain knowledge assets (`knowledge/`) | — | FH-unique — irreplaceable |
+| Session history (`tracks/`) | — | FH-unique — irreplaceable |
+| Cross-project synergy combinations | — | FH-unique combination — not possible with single default feature |
+
+> **Core principle**: FH differentiates through **combination, context, and accumulation** rather than feature competition. As default features get stronger, the value of FH's combination layer grows more.
+
+---
+
+## 2. Simplification Gate Criteria
+
+> **Basis**: "A good harness gets simpler over time. If it's getting more complex, something is wrong." — CLAUDE.md throughline
+
+### Required checks before adding new skills (RULE-AUTO-EXPANSION-GATE)
+
+Every time a new skill addition proposal arises, the following checklist must be passed first.
+
+**Checklist** (check in order):
+
+```
+[ ] 1. Is there an existing skill among the current skills that can cover it?
+       → If yes: replace with existing skill SKILL.md improvement. No new creation.
+       → If no: proceed to next check.
+
+[ ] 2. Did it pass `/asset-placement-gate` 4-criteria judgment?
+       → ①(cross-project value) + ④(non-duplicate with existing skills) must pass
+       → If not passed: no new creation.
+
+[ ] 3. Has it been demonstrated as a pattern repeated 3+ times in the field?
+       → 1-2 time pattern: mark as candidate only + ★ 1 → create properly after 3+ accumulation
+       → 3+ time pattern: creation possible.
+
+[ ] 4. Can `/marketplace-gate` Check 1~5 PASS?
+       → If FAIL items exist: revise then re-verify.
+```
+
+All 4 checks must pass to proceed with creation. **If any one fails, no creation**.
+
+### Existing skill deprecation criteria
+
+`harness-doctor` L5-A INACTIVE_90D judgment = Deprecation Gate entry:
+
+| Status | Criteria | Handling |
+|---|---|---|
+| INACTIVE_30D | 0 times within 30 days | `/sim-conductor D skill {name}` — trigger phrase verification |
+| INACTIVE_90D | 0 times within 90 days | Deprecation Gate — consider deprecation/consolidation |
+| Deprecation confirmed | INACTIVE_90D + coverable skill exists | archive + remove corresponding skill SKILL.md |
+
+---
+
+## 3. Meta-Harness Specification Simplification Principle
+
+> **Core proposition**: "The meta-harness gets simpler **within its own specification (meta layer)** — do not evaluate by single project standards."
+
+### Server room vs data center distinction
+
+| Classification | Criteria | Application |
+|---|---|---|
+| **Server room** (single project) | 200-line CLAUDE.md standard | Single project exceeds 200 lines = M-tier |
+| **Data center** (meta-harness) | Meta layer specification standard | **No line/count threshold exists.** `harness-doctor` declares meta CLAUDE.md raw line and section count **"Not a verdict"** and judges by the char-based always-loaded footprint (S > 40k · M > 80k) plus the residency ledger and the doctrine red flags (orphaned · redundant · decorative) |
+
+`harness-doctor` L2 complexity diagnosis automatically applies this separation:
+- Scope is decided **mechanically at the TARGET root** (`tracks/` ∧ `knowledge/` ∧ `plugins/` all present = meta),
+  never from cwd and never self-declared — a bare cwd test misclassifies every field target as meta
+- On a meta target the line-count rows are **disabled outright**, not swapped for a larger number —
+  so `harness-doctor` cannot fire an **M-tier** on FH's own CLAUDE.md off a single-project line
+  standard. The verdict comes instead from the footprint rows, which apply to both scopes and are
+  char-based; those *can* legitimately reach M-tier, and when they do the lever is capability-level
+  (merge or retire a governance unit), never "the file is long"
+
+### Meta-harness self-constraint prohibition
+
+Prohibit the pattern of applying external standards (single project complexity standards) to the meta-harness to self-constrain:
+
+- **Prohibited**: "FH has N skills, it's gotten complex → needs to be reduced" (single project standard applied)
+- **Allowed**: "Among FH skills, some have 0 invocation records within 90 days → those skills enter Deprecation Gate" (meta layer standard applied)
+
+🟥 **Why this section carries no numbers (2026-08-20).** It used to pin "500-line / 16 skills".
+Both went stale (CLAUDE.md is past 1,400 lines; there are 40 skills) and — worse — the 500 was
+**contradicted by the skill it claimed to describe**: `harness-doctor` disables the line-count row for
+meta targets rather than raising it. That live-but-wrong number is not inert: a run once fabricated
+`M-1 · exceeds the FH threshold of 500` and a downstream sidecar reasoned from the invented figure
+(recurrence N=2 — `harness-doctor/SKILL.md` §"Every M/S-tier must cite the row it fired"). The skill's
+own post-mortem grepped **itself** and found 0 hits, so it concluded the threshold was invented from
+nothing — it never grepped the repo, where **this file was the source**. Do not re-pin a number here:
+thresholds belong in the skill that measures them, where a citation can be quoted verbatim.
+
+Judgment standard: **If there are no real-use problems, no simplification pressure**. Simplification is solving real-use problems, not reducing complexity.
+
+---
+
+## 4. External Contribution Facilitation Structure (not one-way)
+
+FH aims for a **bidirectional contribution structure**, not one-way distribution.
+
+### Contribution occurrence examples
+
+| Contribution direction | Example | Channel |
+|---|---|---|
+| FH → field | Skill/agent distribution, session context connection | plugin install, clone |
+| Field → FH | Field pattern feedback (`field-harvest`) | PR |
+| External → FH | External user contributions, cascade β | External PR / autonomous operation |
+
+### cascade β demonstration
+
+- An external user (not the owner) autonomously operated FH skills → caught and merged a bug in a PR
+- Contribution from external project: owner contributed to that project → demonstrated structure where FH facilitates external contributions
+
+**Meaning**: FH looks like a 1-contributor project but it's an **amplifier structure** where contributions to other projects occur through FH.
+
+---
+
+*Reference: `CONTRIBUTING.md` (PR rules) · `plugins/fh-meta/skills/asset-placement-gate/SKILL.md` (new asset judgment) · `plugins/fh-meta/skills/harness-doctor/SKILL.md` (L5 activity check)*

package/knowledge/shared/GLOSSARY.md

@@ -74,4 +74,29 @@
 
 ---
 
-*Updated: 2026-05-26*
+## Notation — `[[wikilink]]` in FH documents
+
+FH documents (this package included) use `[[some_note_name]]` to cite a **provenance note in the
+author's local memory store** — the per-project memory directory a Claude Code session keeps outside
+the repository. Measured 2026-08-20 across the npm-published file set: **156 shipped `.md` files
+carry 98 such references to 59 distinct targets, and none of those targets exist inside the
+package** (hand-verified sample: `CLAUDE.md` cites `[[feedback_not_found_is_not_zero_family]]`,
+which resolves only at the operator's memory path — `git ls-files` returns 0).
+
+**So, for a reader who is not the author, these are not navigable links.** They are *attribution
+markers*: they say "this sentence came from a recorded failure, not from taste", and they name that
+failure so it can be discussed. Read them as footnote labels, not as paths.
+
+🟥 **Do not treat one as a broken reference or try to repair it.** They are deliberately not
+vendored — a memory store is per-operator, session-scoped, and frequently contains project-private
+material, so shipping it would be a residency violation, not a fix. Equally, do not read a
+`[[…]]`-cited claim as *unsourced*: the surrounding text always states the claim in full, and the
+marker is provenance on top of it, never a substitute for it.
+
+The convention is scoped to memory notes. A pointer to a file that **does** ship is written as an
+ordinary path (`knowledge/shared/harness-core/…`), and those are checked mechanically by the
+detail-pointer resolution gate at commit time.
+
+---
+
+*Updated: 2026-08-20*