@chrono-meta/fh-gate 1.1.0 → 1.2.1

package/CLAUDE.md

@@ -0,0 +1,331 @@
+# forge-harness — Persistent Knowledge Hub
+
+> **This file is the operational ruleset for AI (Claude Code).** For human-facing guidance, see `README.md`. For command reference, see `CHEATSHEET.md`.
+>
+```
+forge-harness/
+├── knowledge/             # Pure knowledge — timeless, for reference
+│   ├── domain/            # Domain-specific knowledge
+│   └── shared/            # Cross-project patterns
+├── tracks/                # Project work history — accumulated over time
+│   └── {project}/         # Per-project directory
+├── CATALOG.md             # Global search index
+└── CLAUDE.md              # This file (Sync/Push protocol)
+```
+
+FH is a 2-layer system: **methodology layer** (model-agnostic — `tracks/`, `knowledge/`, `SKILL.md` docs) + **automation layer** (Claude-native — agents, hooks, slash commands). The methodology layer is designated Codex-compatible beta.
+
+Running Claude Code in this project activates **Control Tower** mode.
+
+## Identity — 3-Layer Mission + Core Axis
+
+The forge-harness hub is not just a repository — it is the **command center for all Claude Code-connected projects in your local environment**.
+
+| Layer | Role | Representative Assets |
+|---|---|---|
+| **① Control Tower** | Coordinates all connected projects and **drives harness-ification across them** — decides *which* projects to harness and *when*, propagates harness assets to each, and feeds their synced learnings into the hub's compounding loop. The *how* (rules · gates · 6-axis) is executed via the Core Axis. Command HQ, not a passive registry. | `.claude/rules/auto_project_mapping.md` (mapping + **Full-Harness Mode**) · `harvest-loop` (compounding loop) · `templates/` (project-harness bundle) · `CATALOG.md` |
+| **② Frontier → Org Propagation** | Proactively applies global AI/harness frontier thinking and **translates it for your organization**. | `knowledge/shared/harness-core/harness_frontier_diagnosis_*.md` · `knowledge/{your-org}/` |
+| **③ AI Collaboration Guide** | Accumulates and distributes best practices for token efficiency and dialogue methodology — "how to ask, delegate, and record". | `CHEATSHEET.md` · `knowledge/shared/dialogue/ai_dialogue_playbook.md` · `MEMORY.md` keyword-triggered loading |
+| **Core Axis** | **Harness Engineering (How)** — the methodology and practice axis that realizes the three layers above. The 6-axis framework is the operating unit. **A harness is a means, not an end** — Field harness: "simpler over time" (complexity = warning signal). Meta-harness: *optimize*, not necessarily simplify — complexity earns its scope; red flags are orphaned, redundant, and decorative units, not complexity itself. | `harness_6axis_framework.md` · `hub_compounding_loop.md` · `claude_code_runtime_flow.md` · `.claude/agents/` (sub-agents) |
+
+## Core Reference Documents (Consult First)
+
+Four foundational assets for hub operations. **Mandatory pre-reference** before new design, protocol proposals, or framework extensions.
+
+| Document | Nature | Role |
+|---|---|---|
+| `knowledge/shared/harness-core/harness_6axis_framework.md` | Top-level meta-framework | 6-axis (structure/context/plan/execute/verify/improve) decision tree |
+| `knowledge/shared/harness-core/hub_compounding_loop.md` | Feedback automation | Weekly/monthly/quarterly cycles. Axis-6 Compounding automation |
+| `knowledge/shared/dialogue/ai_dialogue_playbook.md` | Dialogue principles (should) | Session start, token efficiency, rule hierarchy, amplifier/coach dual mode |
+| `knowledge/shared/dialogue/claude_code_runtime_flow.md` | Runtime behavior (does) | Chronological flow during a session · sub-agent delegation flowchart |
+
+## New Project Onboarding
+
+> Detailed procedure: `.claude/rules/auto_project_mapping.md` (5-step mapping + §6 Full-Harness Mode)
+
+1. `mkdir tracks/{project_name}/` — track name = project root name
+2. Hub common principles outrank project rules (scope hierarchy)
+3. Reference `ai_dialogue_playbook.md` + `claude_code_runtime_flow.md` at top of project CLAUDE.md (Layer ③)
+
+**Light vs full**: steps 1–3 register lightly. For project-local harness assets (session rules + context filter + env card), run **Full-Harness Mode** (`auto_project_mapping.md §6`) — approval-gated, never overwrites. FH self-gate is **not** installed into projects.
+
+## Harness Drift Prevention Principles
+
+The forge-harness hub has a dual identity: **(a) a seed for others** + **(b) your own active work harness**. This is why clearly separating "team assets" from "personal assets" is essential to prevent drift.
+
+| Location | Nature | Update Responsibility |
+|---|---|---|
+| `forge-harness/templates/.claude/rules/*.md` · `forge-harness/knowledge/shared/*` | **Developer's own philosophy + front-end filters** — universal principles, personal assets | Owner (hub session sync) |
+| `{project}/.claude/rules/*.md` (e.g., project-specific guides) | **Team shared rules** — team assets, domain-specific | Team (managed via PR) |
+| `{project}/{domain}/.claude/rules/session.md` (e.g., domain session rules) | **Domain session rules** — team shared, per-domain | Team (managed via PR) |
+
+### PR Direction (One-Way)
+
+```
+✓ Allowed: Improvement discovered while working in forge-harness → PR to {project} rules
+            (Personal improvement → officialized as team asset)
+
+✗ Forbidden: Copying {project} rules into forge-harness
+              (Team asset drift · single source of truth collapse · double maintenance burden)
+```
+
+### AI Contribution Model (PR Proposal Principle)
+
+**Principle (`feedback_no_personal_commit_to_shared_repo`): AI does not commit directly to shared repositories.**
+
+- **Interpretation:** AI is not allowed to independently commit and push code. However, **AI may propose a Pull Request by preparing all change drafts and requesting final approval from the human (user)**.
+- **Implementation:** Skills such as `harvest-loop` follow this principle — they generate skill drafts, prepare commits automatically, and propose PR creation. However, the final decision to submit a PR must always require the user's explicit approval (`y`). This ensures Human-in-the-loop while maximizing AI contribution.
+
+**PR Creation Principle:**
+- AI may commit and push automatically (when changes are approved)
+- **PR creation requires explicit user request** ("create PR", "PR 올려줘", "pull request")
+- **Reason:** Prevents PR fragmentation — logical units should be grouped into meaningful PRs, not atomized per commit
+- Default workflow: commit → push → wait for explicit PR request
+
+## Permission-Denial Guidance (When Auto-Mode Blocks an Action)
+
+When blocked by auto-mode permission denial, **do not stop at the bare denial** — turn the block into a decision the user can act on in one step:
+
+1. **State what was blocked** and why
+2. **Option A — Approval mode**: show exact commands to run after switching; **Option B — Manual review**: list specific files/sections
+3. **Ask which option** — one line, then wait
+
+**Sub-agent variant**: report (what was blocked + ready-to-apply content + exact unblock step) back to orchestrator — never silently fail. Switching modes lifts permission block, not FH gates — the 4-axis gate still applies.
+
+Simplification guard: trivial denials with one obvious fix → state block + single next step inline.
+
+## Active Onboarding Protocol (User Greeting → AI Initiative)
+
+> **Full 4-step detail**: `knowledge/shared/harness-core/fh_detail_protocols.md`
+> **Read this file before Step 1 begins** — duplicate-install detection (Step 1-b) and registry scan (Step 1-c) are only defined there, not in this summary.
+
+**Triggers**: greetings (`hi`/`hello`/`hey`) · start intent (`resume`, `continue`, `where were we`) · new task (`new project`, `new task`) · discovery (`what is this`, `what can you do`, `first time here`)
+
+**4-step summary**: ① Auto-read CLAUDE.md + CATALOG + session card + registry scan → ② One-line proposal (new user / exploratory / returning branches) → ③ 5-skill cascade (plugin-recommender → synergy → .claudeignore → model → verify) → ④ Approval + setup
+
+**Identity marker**: every greeting response (Step ②) opens with 🐿️ on its own line. FH's session-start signal — see `fh_detail_protocols.md` Step 2 for full greeting templates.
+
+**Guards**: explicit task-entry utterance → skip onboarding · once per session · code/debug requests → start working directly · project routing is a suggestion, mention at most once
+
+## New Skill Creation Pre-Commit Gate
+
+All 5 items below must pass before committing a new SKILL.md. If any fails, fix and re-commit.
+
+| Item | Criterion |
+|---|---|
+| **Role duplication check** | Pass `/asset-placement-gate` — no overlap with existing role clusters |
+| **Description diet** | Plain text / 0 self-marketing expressions / 0 emphasis words (⭐, "critical", "groundbreaking") |
+| **Done When defined** | At least 1 explicit completion condition |
+| **Natural language triggers** | At least 3 examples that work without internal vocabulary |
+| **Independently executable** | Confirmed to work without other FH skills (or dependencies are explicitly documented) |
+
+Skills without a Done When definition automatically qualify as harness-doctor L2 M-tier.
+
+---
+
+## FH Improvement 4-Axis Auto-Gate (Self-Verification Orchestrator)
+
+**Whenever the AI modifies FH assets** (SKILL.md · `.claude/rules/*.md` · `templates/` · `CLAUDE.md` · substantive `knowledge/` docs · substantive `docs/*.md` · `AGENTS.md` — see Substantive carve-out below),
+the 4-axis verification chain runs **automatically before the first commit** of that session.
+No user request is needed — this is a mandatory autonomous step, not a proposal.
+
+**Commit gate**: `git commit` on FH asset changes is hard-blocked by `templates/.git-hooks/pre-commit` until all required axes PASS. Hook installation (one-time): `git config core.hooksPath templates/.git-hooks && chmod +x templates/.git-hooks/pre-commit`
+
+```
+FH asset modified → Axis 1 (regression_guard.sh --pr {BRANCH})
+  → Axis 2 (/steel-quench) → Axis 3 (/source-grounding-audit)
+  → 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
+```
+
+**Why automatic**: Each axis catches a different defect class; asking separately means slip-through. **Why hook**: CLAUDE.md rules are advisory — the hook physically blocks commit until marker + manifest exist. **Scope**: active from the moment any FH file is modified in the session.
+
+**Lightweight exception** (Axis 1 + 4 only, skip Axes 2–3): Sessions where **zero SKILL.md / rules / templates files changed** (e.g., CATALOG.md entry, tracks/ update). The hook detects this automatically — no Axes 2+3 marker required for light-only commits. Judgment is file-based, not subjective.
+
+**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.
+
+**Axis ownership** (each skill is already complete — orchestrator only coordinates):
+
+| Axis | Skill | What it catches |
+|---|---|---|
+| 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 |
+| Record | `edit-manifest` RECORD | Logs predicted impact — closes the predict-verify loop for future harvest-loop |
+
+---
+
+## 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.
+Proposal format: `"I see [X]. Want me to run /[skill] to [one-line description]?"`
+
+| Conversation Signal Keywords | Proposed Skill |
+|---|---|
+| "plugin", "what tool should I use", "install", "recommend" (tool exploration) | `/plugin-recommender` |
+| "context is getting long", "token limit", "/clear", "slow", "context" (burden) | `/context-doctor` |
+| "wrap up this week", "review", "audit", "weekly", "retrospective" | `/harvest-loop` |
+| "pull this into FH", "reverse-harvest", "worth keeping", "harvest pattern", "field pattern" | `/field-harvest` |
+| "harness is complex", "too many skills", "check structure", "harness" | `/harness-doctor` |
+| "review this PR", "check diff", "code review" | `/hub-cc-pr-reviewer` |
+| "are these in sync", "synergy", "can these integrate", "any overlap" | `/cross-ecosystem-synergy-detection` |
+| "latest trends", "frontier", "external resources" | `/frontier-digest` |
+| "orchestrate agents", "parallel dispatch", "combine skills", "multiple agents" | `/agent-composer` |
+| "run a simulation", "external user perspective", "internal audit", "quality check" | `/sim-conductor` |
+| "first install", "FH setup", "wizard", "install-wizard" | `/install-wizard` |
+| "connect a project", "map this project", "link to hub" | `auto_project_mapping.md` (mapping) |
+| "harness-ify this project", "full harness setup", "프로젝트 하네스화", "promote to full harness" | `auto_project_mapping.md §6` (Full-Harness Mode) |
+| "check install", "verify setup", "confirm install", "install-doctor" | `/install-doctor` |
+| "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` |
+| "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` |
+| "did my rule change break anything", "regression check", "test harness changes" | `/prompt-regression` |
+| "SKILL.md too large", "split this skill", "skill is bloated", "skill file too long" | `/skill-splitter` |
+| "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` |
+| "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) |
+
+**Guard**: Do not propose a skill that is already running. One signal = one-line proposal (no pressure).
+For per-skill utterance patterns, see the relevant `SKILL.md §Trigger Phrases` section.
+
+### Cadence Rules — Check at Session Start
+
+At session start, determine the last run time from history files and auto-propose if overdue:
+
+| Skill | History File Pattern | Cadence |
+|---|---|---|
+| `/frontier-digest` | `tracks/_meta/frontier_digest_*.md` | Propose at session start if 7+ days since last run |
+| `/harness-doctor` | `tracks/_meta/*harness_doctor*.md` | Propose at session start if 30+ days since last run |
+
+## Agent Dispatch Operation (FH cwd-Based)
+
+Default operation is a **standard interactive session**. Agent dispatch (single or parallel) is used when the task warrants it — not as a default mode. Three execution paths:
+
+| Path | Situation | Method |
+|---|---|---|
+| **Direct edit** | Simple modification of mapped project files | Read/Edit with absolute path (no cwd switch needed) |
+| **Agent dispatch** | Field project work · single independent task | Inject Context Card then dispatch Agent |
+| **Parallel dispatch** | 2+ genuinely independent tasks, explicitly requested | Dispatch parallel Agents |
+
+**Why not Agent View by default**: Agent View introduces worktree isolation (blocks settings.json writes, Stop hook timing differs), session context gaps (session card stale content bug), and path friction — with no benefit unless the user is actively managing multiple agent sessions. Parallel agents via `Agent` tool work identically in a standard session.
+
+**Forbidden responses**: *"I can't do that — I'm not in that project's cwd"* — self-check Agent dispatch first.
+
+Mapped paths: check `auto_project_mapping.md` or `find ~/projects -maxdepth 1 -type d` for actuals.
+
+### Context Card — Required Format for Dispatch
+```
+[Session Context Card]
+Purpose: {task/session purpose}  |  Completed: {what's already done}
+This agent's task: {specific task + target files/paths}  |  Note: {constraints/history}
+```
+Simple file-lookup agents may omit. Agent dispatch works from any mapped project cwd — for FH skills, specify `~/projects/forge-harness/` explicitly.
+
+---
+
+## Cross-Project Skill Bus (Active Throughout Session)
+
+Based on LOCAL_SKILL_REGISTRY (Step 1-c), **propose and connect skills from other projects directly**. Proposal: *"{Project} has `{skill-name}`. Want me to dispatch it via Agent?"*
+
+- **Direct execution** (no project files needed): Read SKILL.md → execute steps directly
+- **Agent dispatch** (project files needed): dispatch via Agent tool + Context Card, absolute path, no cwd switch; 2+ independent tasks → parallel dispatch
+
+**Guard**: FH native skill takes priority over cross-project proposal for the same signal.
+
+## FH Improvement Signal Recording Protocol
+
+> **Full format + template**: `knowledge/shared/harness-core/fh_detail_protocols.md` — read when creating a signal file.
+
+**Triggers**: user confusion/retries · user proposes improvement · AI self-detects skill/rule limitation · new FH-worthy pattern discovered
+
+**Method**: create `tracks/_meta/fh_signal_{YYYY-MM-DD}_{source}.md` (1 file/session, append if same date+source). Structural candidates only — exclude typos and in-session-resolved issues.
+
+## Execution Tier Settings
+
+> **Full tier table + config**: `knowledge/shared/harness-core/fh_detail_protocols.md` — read when selecting a non-default tier.
+
+**Default: standard (~15K tokens).** Temporary change: say "use light mode" or "switch to max" in session.
+Tiers: S=light(~5K) · M=standard(~15K, FH default) · L=full(~30K) · XL=max(~60K+)
+
+---
+
+## Operational Status
+
+**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`
+
+## Auto Project Mapping Protocol
+
+> Detailed procedure: `.claude/rules/auto_project_mapping.md` (5-step mapping + §6 Full-Harness Mode)
+
+When the user requests **"connect a project"** · **"link to hub"** · **"map this project"** · **"scan parent directory and connect"**, follow the `auto_project_mapping.md` protocol. When they request **"harness-ify this project"** · **"full harness setup"** · **"프로젝트 하네스화"** (or accept the post-mapping promotion prompt), run **§6 Full-Harness Mode** — installs project-local harness assets (session rules · context filter · env card) from `templates/`, approval-gated and non-overwriting. (The FH self-gate is FH-internal and is not installed into projects.)
+
+## Searching Past Work
+
+When searching for past work, **read CATALOG.md first**. Use tags and summaries to identify candidate files, then open only those files for detail.
+
+```
+1. Read CATALOG.md → identify candidate files by tag/date
+2. Open candidate files directly → review details
+```
+
+Do not scan session files one by one sequentially.
+
+
+## Session Wrap-up — Card Update Protocol
+
+**Real-time completion tracking (card bug prevention)**: When any S-tier/A-tier/backlog item is completed during a session, **immediately** (before context compression) append to `tracks/_meta/fh_completed_{YYYY-MM-DD}.md`.  
+Format: `- ✅ {item title} — {one-line completion method}`  
+harvest-loop Step 0-b uses this file as its source — relying on LLM memory after compression causes omissions.
+
+**Session close chaining (automatic sequence — not skippable)**:
+```
+Closing phrase detected ("wrap up", "done", "good work", "end session", etc.)
+  → ① Check git diff + unpushed commits (status snapshot)
+  → ② 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
+  → ⑥ Commit card + push
+```
+**Card-last guard**: ①–④ 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.
+
+**Mid-session card writes are drafts**: If a task (e.g., a calibration run) internally updates
+the card, that is a draft. The close chain always re-runs ⑤ to capture post-draft activities.
+Never skip ⑤ because "the card was just updated" — check for delta first.
+
+Card update is NOT a sub-step of harvest-loop — even if harvest-loop is skipped, card update must run.
+
+**Agent View pre-read (mandatory when session ran in Agent View / worktree / background job)**: Before writing the card, read your companion store's handoff files (if you keep one) to recover sub-agent completions that may not be in main session context. Skipping this step in Agent View is the root cause of "card created with stale content" bugs — the main context does not automatically see worktree-completed items.
+
+**Card update obligation** (independent obligation — regardless of harvest-loop completion): Update `reference_next_session_starter.md`.  
+① **Agent View pre-read** (see above) → ② Step 0-b cross-check generates removal list → ③ Remove completed items → ④ Add new priorities → ⑤ Fix stale paths/versions → ⑥ Overwrite → ⑦ Output "BEFORE N items → AFTER M items" diff.  
+"Delta update" not "snapshot" — completed items remaining in next session card is a bug.
+
+## Session Sync / Knowledge Push Protocol
+
+> Detailed procedure: `.claude/rules/sync_push_protocols.md`
+
+When the user requests "sync", "save session", etc., follow the `sync_push_protocols.md` protocol. CATALOG.md format, tag conventions, and track mapping are also referenced in that file.
+
+## Sister Asset Protocol
+
+> Detailed procedure (3 steps · restrictions · branch sync): `.claude/rules/sister_asset_protocol.md`
+
+When a sibling asset on the same topic is discovered (internal team or external frontier), follow `sister_asset_protocol.md`. Keep the detection threshold low — the goal is to close awareness gaps.
+
+## Operations Reference
+
+> CATALOG.md format · tag conventions: `.claude/rules/sync_push_protocols.md`
+> Sub-agent operations · weekly improvement cycle · maturity 3-phase roadmap: `.claude/rules/operations.md`

package/CONTRIBUTING.md

@@ -0,0 +1,198 @@
+# forge-harness Contribution Guide
+
+If you'd like to make forge-harness better, pull requests are welcome.
+
+## What You Can Contribute
+
+| Type | Example |
+|---|---|
+| **New skill** | You've discovered a repeating pattern and want to turn it into a skill |
+| **Improve existing skill** | Bug fix, external environment adaptation, adding triggers |
+| **Add agent** | New persona (`.claude/agents/` or `plugins/.../agents/`) |
+| **Templates** | Common files to add under `templates/` |
+| **Documentation** | README, skill description refinement, typo fixes |
+| **Field pattern harvest** | Proposing a pattern discovered in real use as a skill (see `/field-harvest`) |
+
+## Choosing a Contribution Path — Check First
+
+| Contribution Type | Path | Overhead |
+|---|---|---|
+| Typo fix, 1–3 line improvement, trigger addition | **Lightweight path** — PR rules 1–4 only | Minimal |
+| Add step to existing skill, expand section | **Lightweight path** — PR rules 1–5 | Light |
+| Create new skill or agent | **Full path** — PR rules 1–8 + rc bump checklist | Full |
+| Plugin Level version bump | **Full path** + 3-piece set | Full |
+
+> **Adding a new skill = Full path required**. Improving an existing skill = Lightweight path available.
+
+## PR Rules (Short Version)
+
+1. **New skill** → Create `plugins/fh-meta/skills/{name}/SKILL.md` + add version line to `plugins/fh-meta/CHANGELOG.md`
+2. **New agent** → Register in both `.claude/agents/{name}.md` + `plugins/fh-meta/agents/{name}.md`
+3. **Description must be plain text** — no markdown bold, emphasis words, version mentions, or embedded names (removes self-marketing tone)
+4. **Simplification guard** — verify that existing assets cannot cover the use case before creating something new
+5. **External environment adaptation section** — recommend explicitly noting `Mode A/C` branches in skills and agents
+6. **Plugin version bump 3-piece set** — when bumping Plugin Level version, always update all three simultaneously:
+   - Add `[vX.Y.Z]` entry to `CHANGELOG.md` Plugin Level section
+   - Sync the `version` field in `plugins/fh-meta/.claude-plugin/plugin.json`
+   - Create and push tag with `git tag -a vX.Y.Z -m "..."`
+7. **Run fact-checker before version bump** — use `/fact-checker` to verify 3-way consistency of plugin.json version/skill count, CHANGELOG, README, and SKILL.md files. 0 FAIL items is a prerequisite for any version bump.
+8. **Version policy**: `v0.x` = internal validation phase / `v1.0` = external install validation complete. Claiming v1.0 without external usage evidence is prohibited.
+   - **v1.0 validation criteria**: A user other than the owner must ① clone + install FH → ② trigger a skill using natural language → ③ confirm successful completion. Minimum 1 person. Record tester, date, and environment in the PR body.
+
+## rc Bump Pre-Requisite Checklist
+
+Before any version bump (rc or official release), pass the checklist below **in order**.
+If any item FAILs, **rc bump is blocked** — fix and re-validate.
+
+### 1. Run fact-checker — confirm 0 stale numbers
+
+Run `/fact-checker` skill for 3-way consistency check:
+
+| Validation Target | Check Items |
+|---|---|
+| `plugins/fh-meta/.claude-plugin/plugin.json` | `version` field, `skills` count |
+| `plugins/fh-meta/marketplace.json` | version and skill count in sync |
+| `README.md` (root + plugin) | Stale skill counts or version numbers |
+
+**Pass criterion**: 0 stale items. Even 1 FAIL blocks the rc bump.
+
+### 2. Pass marketplace-gate skill
+
+Run `/marketplace-gate` → All Checks 1–5 must PASS:
+
+| Check | Content |
+|---|---|
+| Check 1 | Skill description is plain text (no markdown bold, version mentions, embedded names) |
+| Check 2 | SKILL.md meets minimum structure (frontmatter + triggers + simplification guard) |
+| Check 3 | No external install conflicts (`install-doctor` result linked) |
+| Check 4 | CHANGELOG.md version line exists |
+| Check 5 | Version policy compliance (`v0.x` = internal validation / `v1.0` = external validation complete) |
+
+1 or more FAILs blocks the rc bump.
+
+### 3. CHANGELOG.md must be updated
+
+The changes for the target bump version must be recorded in `CHANGELOG.md`.
+
+```markdown
+## [vX.Y.Z-rcN] - YYYY-MM-DD
+### Added
+- ...
+### Fixed
+- ...
+```
+
+rc bump without CHANGELOG update is not allowed.
+
+### Checklist Summary
+
+```
+[ ] fact-checker — plugin.json ↔ marketplace.json ↔ README 3-way stale: 0
+[ ] marketplace-gate — Check 1–5 FAIL: 0
+[ ] CHANGELOG.md — entry for this version written
+```
+
+Complete all three before running `git tag` and version bump.
+
+---
+
+## How to Submit a PR
+
+```bash
+# 1. fork or create branch
+git checkout -b feat/my-skill-name
+
+# 2. do the work
+# plugins/fh-meta/skills/my-skill/SKILL.md — write skill
+# CHANGELOG.md — add version line
+
+# 3. create PR
+gh pr create --title "feat(my-skill): one-line description" \
+  --body "## What was added\n\n## Why it's needed\n\n## Test environment"
+```
+
+## Minimum SKILL.md Structure
+
+```markdown
+---
+name: skill-name
+description: One sentence. Plain text only.
+user-invocable: true
+allowed-tools: ["Read", "Bash"]
+model: sonnet
+version: 0.1
+# complexity_routing (optional): only add if this sonnet skill needs conditional Opus escalation
+# complexity_routing:
+#   base: sonnet
+#   high: opus
+#   escalate_when:
+#     - cold_start          # first run with no session context
+#     - cross_project       # work spanning 3+ projects
+#     - adversarial         # devil/steel-quench mode active
+#     - high_stakes         # pre-release or pre-publish validation
+#     - full_revalidation   # full re-validation requested
+#     - destructive         # irreversible operations included (push, delete, deploy, etc.)
+---
+
+# skill-name — one-line description
+
+## Steps
+
+### Step 1. ...
+
+## Trigger Phrases
+
+| Utterance Pattern | Example | Trigger Strength |
+|---|---|---|
+| **Direct call** | `/skill-name` | Immediate |
+| **Natural language A** | "do X for me", "analyze X" | Immediate |
+| **Natural language B** | "check X", "how about X" | Suggest |
+
+**Simplification guard**: Do not re-propose if this task is already in progress.
+
+## External User Environment Adaptation
+
+| Environment | Behavior |
+|---|---|
+| forge-harness clone present | ... |
+| Plugin only (Mode C) | ... |
+```
+
+## External API Call Standard
+
+When a skill calls an external API (your internal tool, task tracker, messaging platform, etc.), always implement 4-state separation.
+
+### State Definitions
+
+| State | Meaning | Handling |
+|---|---|---|
+| `EXECUTED` | API call succeeded + result returned | Normal completion |
+| `SKIPPED_NO_KEY` | Auth key/token not set | Guide user on how to configure |
+| `SKIPPED_EMPTY_INPUT` | No input provided, call unnecessary | Silent skip |
+| `FAILED` | Call attempted but error occurred | Output error details + retry guide |
+
+### Implementation Example (Bash-based skill)
+
+```bash
+API_KEY="${YOUR_API_KEY:-}"
+if [ -z "$API_KEY" ]; then
+  echo "STATUS: SKIPPED_NO_KEY — YOUR_API_KEY not set. Configure it and retry."
+  exit 0
+fi
+
+RESPONSE=$(curl -s -w "\n%{http_code}" -H "X-API-Key: $API_KEY" "$ENDPOINT")
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | head -1)
+
+case $HTTP_CODE in
+  200) echo "STATUS: EXECUTED"; echo "$BODY" ;;
+  401|403) echo "STATUS: SKIPPED_NO_KEY — Key invalid. Check your credentials." ;;
+  *) echo "STATUS: FAILED — HTTP $HTTP_CODE. Network or server error." ;;
+esac
+```
+
+**Principle**: Without explicit state output, users cannot tell whether a skill executed, was skipped, or failed.
+
+## Questions
+
+Leave a comment on the PR or open an issue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chrono-meta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.