@chrono-meta/fh-gate 1.1.0 → 1.2.0

package/plugins/fh-meta/skills/asset-placement-gate/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: asset-placement-gate
+description: Routes a proposed skill, plugin, or agent to its correct home — forge-harness (FH) meta-skill, project-local agent, or drop — by applying a 4-criteria meta-skill bar followed by a project-local value test.
+user-invocable: true
+allowed-tools: ["Read", "Grep", "Glob"]
+model: sonnet
+---
+
+# asset-placement-gate
+
+Routes new skills, agents, and plugins to the correct location when proposed.
+
+## Triggers
+- "Should I make this an FH skill?"
+- "Where should I put this agent?"
+- When a new FH asset creation is proposed
+- `/asset-placement-gate {asset name or description}`
+
+### Natural Language Triggers (example user phrases)
+
+When unsure where to place a new asset or skill:
+
+| Example phrase | Intent |
+|---|---|
+| "Should I put this in a separate file?" | Asset necessity + placement decision |
+| "Can this pattern be shared across projects?" | FH cross-project value assessment |
+| "Is this only for our project, or can others use it too?" | cross-project vs local routing |
+| "What if I turn this into a skill and use it across projects?" | FH 4-criteria trigger |
+| "Where should I put this agent if I want to share it?" | Placement routing needed |
+| "Should I extract this to a separate file, or leave it?" | Asset necessity + placement decision |
+| "I'd like to manage this as a shared resource" | Cross-project shared management review |
+| "Decide whether this stays local or is available to other teams too" | cross-project vs local routing |
+| "I don't know where to save this" | Placement routing needed |
+| "Should this become a shared asset?" | FH 4-criteria trigger |
+
+### Execution Order (summary)
+
+1. Request full file path from user (or accept natural language description)
+2. Load asset content via `Read` (if path provided)
+3. Evaluate Step 1 4-criteria in order (LLM makes the judgment directly)
+4. ① + ④ both pass + at least one of ②③ passes → output **"FH suitable"**
+   Otherwise, proceed to Step 2 local assessment → if fails, output **"Project-local agent or no asset needed"**
+
+---
+
+## Step 0. Parse Input + Fetch Asset
+
+Immediately after trigger, acquire asset content in the following order.
+
+1. **Path provided** (contains `.md` or starts with `/`): Read the file.
+   - If read fails: "File not found. Please verify the path or provide a direct description." — then stop.
+2. **Description provided** (natural language): Check whether all 3 fields can be identified:
+   - **Purpose**: What this asset does (1 line)
+   - **Trigger**: In what situation is it invoked?
+   - **Expected callers**: Which project / which users will use it?
+
+   All 3 identifiable → use as asset description.
+   Any 1 unclear → stop with this question:
+   > **The asset description is insufficient. Please provide:**
+   > 1. Purpose of this asset (one line)
+   > 2. In what situation is it invoked?
+   > 3. Which project/users will primarily use it?
+3. **No input**: Stop with the question below.
+   > **Which asset should I evaluate?**
+   > Enter a file path (e.g., `.claude/agents/jira-create.md`) or a description.
+
+After acquiring the asset content, **Claude directly** applies Step 1 4-criteria (no external calls).
+
+## Done When
+
+```
+All steps 0–3 completed
++ Step 3 routing result output (location: FH meta-skill / local agent / drop)
++ Next action specified (write SKILL.md / create .claude/agents/ / none)
+```
+
+---
+
+## Step 1. FH Meta-Skill 4-Criteria Evaluation
+
+| # | Criterion | Evaluation Question |
+|:-:|---|---|
+| ① | Cross-project value | Is this asset equally useful in other projects without depending on a specific project? |
+| ② | Orchestration / judgment layer | Is it just a list of MCP/Bash calls, or a judgment layer that synthesizes multiple signals? |
+| ③ | Not replaceable by built-ins | Can this be equally achieved with direct MCP calls or basic bash? (If yes, fails this criterion) |
+| ④ | No overlap with existing FH skills | Does it not overlap 90%+ with existing FH skills? |
+
+**FH suitable** → ① + ④ both pass + at least one of ②③ passes.
+**Fail** → ① or ④ fails → immediate fail. Or both ②③ fail → proceed to Step 2.
+
+---
+
+## Step 2. Project-Local Agent Value Assessment
+
+For assets that failed Step 1:
+
+| # | Criterion | Evaluation Question |
+|:-:|---|---|
+| A | Project-specific knowledge | Does it encode paths, conventions, or domain rules specific to a project? |
+| B | Repeated workflow pattern | Is it a workflow performed repeatedly within that project? |
+| C | Differentiation from built-ins | Does it provide local-context-based convenience such as automatic convention application or step integration? |
+
+**Local agent suitable** → A satisfied + at least one of B·C.
+→ Recommend creating `{project}/.claude/agents/{name}.md`.
+
+**Drop** → A not satisfied or both B·C not satisfied.
+→ Equivalent to built-in capability. No asset needed.
+
+---
+
+## Step 3. Routing Result Output
+
+```
+[asset-placement-gate verdict]
+
+Asset: {asset name}
+Description: {one-line summary}
+
+── FH 4-criteria ──────────────────
+① Cross-project value     : O / X
+② Orchestration/judgment  : O / X
+③ Not replaceable         : O / X
+④ No overlap with existing : O / X  ← required gate with ① (immediate fail if either fails)
+→ FH suitable: Pass / Fail  (① + ④ required + at least one of ②③)
+
+── Project-local assessment ──────  (if FH failed)
+A. Project-specific knowledge : O / X
+B. Repeated workflow pattern  : O / X
+C. Differentiation from built-ins : O / X
+→ Local agent: Suitable / Drop
+
+── Conclusion ────────────────────
+Location: [FH meta-skill | {project} local agent | Drop]
+Next action: [Write SKILL.md | Create .claude/agents/ | None]
+```

package/plugins/fh-meta/skills/contention-layer/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: contention-layer
+description: When two skills or agents produce conflicting verdicts on the same output, reads the conflict as a signal rather than an error and harvests new skill candidates. Routes skills born from contention to fh-meta if they are meta-layer, to commons plugin if project-agnostic, or to field harvest if domain-specific. Triggered by "two skills conflict", "they produce different conclusions", "contention-layer", "contention harvest".
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Grep", "Write"]
+model: sonnet
+category: Ecosystem Growth
+---
+
+# contention-layer — Contention Harvest + New Skill Routing
+
+When two skills conflict, **harvest the signal** instead of discarding one. Find the validation angle that neither skill addressed, and onboard new skill candidates into the FH ecosystem according to their routing path.
+
+> Philosophical basis: Cognitive dissonance in humans is not a failure but a core asset — the ability to hold contradictions created culture. In the FH ecosystem, conflict is the signal from which new skills are born.
+
+## Triggers
+
+```
+/contention-layer                    # analyze current conflict situation
+/contention-layer --skills A B       # specify two skills for contention analysis
+```
+
+Phrase triggers: "two skills conflict" · "weird when used together" · "they produce different conclusions" · "contention harvest" · "contention"
+
+## Step 1. Collect Conflict Points
+
+Record clearly which skills conflicted on which output, and in which direction.
+
+```
+Conflicting skill A: {skill name} — verdict: {conclusion}
+Conflicting skill B: {skill name} — verdict: {conclusion}
+Conflicting output: {TC / diagnostic report / design document / ...}
+Conflict point: {which item, by which criteria difference}
+```
+
+**Conflict type classification**:
+- `Criteria conflict`: Same item evaluated by different criteria (e.g., coverage 50% = Pass vs Fail)
+- `Scope conflict`: A includes, B excludes a certain domain
+- `Order conflict`: Same goal approached with different preconditions
+- `Philosophy conflict`: The measurement purpose itself differs (e.g., risk reduction vs coverage maximization)
+
+## Step 2. Contention Essence — Harvest Gate
+
+Determine whether the conflict will be resolved by **exclusion** or converted to **harvest**.
+
+```
+Question 1: Did the two skills produce different verdicts because they had different validation angles?
+  → Yes: Harvest candidate ✅
+  → No (bug / malfunction): Exclude → escalate to install-doctor
+
+Question 2: If that tension is resolved, can it be absorbed into one of the existing skills?
+  → Possible: Recommend improving existing skill (no new skill needed)
+  → Not possible (new angle): New skill candidate ✅
+
+Question 3: Can the candidate skill be transplanted to any project without a specific domain?
+  → Transplantable: Route to commons plugin ✅
+  → Domain-specific: Field harvest signal
+```
+
+Harvest Gate pass criteria: Question 1 ✅ + Question 2 not possible ✅ = new skill birth verdict
+
+## Step 3. Placement Routing
+
+| Skill nature | Routing path | Criterion |
+|---|---|---|
+| Harness engineering · install/audit/validation/onboarding | `fh-meta` candidate | Skills that operate/diagnose FH itself |
+| Project-independent · transplantable anywhere · domain-agnostic | `commons` plugin | Universal utilities like validation angles or analysis frameworks |
+| Specific domain/team/language/tech-stack | `field harvest` signal | Field team decision domain — not included in FH |
+
+```
+Routing conclusion:
+  New skill name candidate: {name}
+  Routing path: {fh-meta / commons / field}
+  Rationale: {1-line nature verdict}
+```
+
+## Step 4. Generate SKILL.md Draft
+
+After confirming routing path, auto-generate a new skill SKILL.md skeleton.
+
+```markdown
+---
+name: {slug}
+description: {one line — include trigger keywords, no marketing language}
+user-invocable: true
+allowed-tools: [...]
+model: sonnet
+category: {category}
+origin: contention-layer  # contention birth history
+contention-parents: [{skill A}, {skill B}]
+---
+
+# {skill name} — {subtitle}
+
+{One sentence capturing the validation angle discovered from contention}
+
+## Triggers
+...
+
+## Step 1. ...
+```
+
+After generating skeleton: **"I will place this draft at {path}. Shall I proceed?"** — confirmation gate.
+
+## Output Format
+
+```
+[Contention Harvest Report]
+Conflicting skills: {A} vs {B}
+Conflict type: {Criteria / Scope / Order / Philosophy}
+Harvest Gate: Pass / Fail
+  └ Reason: {1 line}
+New skill candidate: {name or none}
+Routing path: {fh-meta / commons / field / n/a}
+Next action: {generate draft / exclude / recommend improving existing skill}
+```
+
+## Done When
+
+```
+All steps 1–4 completed
++ [Contention Harvest Report] output (Harvest Gate Pass/Fail stated)
++ If new skill candidate exists: SKILL.md skeleton generated + user confirmation gate complete
++ If no new skill candidate: "Exclude / recommend improving existing skill" stated and exit
+```
+
+Verdict: PASS (Harvest Gate Pass — new skill skeleton generated or no candidates confirmed) | CONDITIONAL_PASS (candidates found, user confirmation pending) | FAIL (Harvest Gate Fail — collision unresolvable, no new skill justified) | ESCALATE (role boundary ambiguous, requires human judgment)

package/plugins/fh-meta/skills/context-bridge-dispatch/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: context-bridge-dispatch
+description: >-
+  DEPRECATED — merged into agent-composer Step 3-a (2026-06-02).
+  Context Card injection (N≤2 standard / N≥3 Registry mode) + coordination-overhead budget + Focus Mode
+  are now part of agent-composer Step 3. Invoke /agent-composer for parallel dispatch.
+user-invocable: false
+allowed-tools: []
+model: sonnet
+deprecated: true
+deprecated_reason: absorbed into agent-composer Step 3-a
+deprecated_date: 2026-06-02
+successor: agent-composer
+---
+
+# context-bridge-dispatch — DEPRECATED
+
+> **Merged into `agent-composer` Step 3-a (2026-06-02).**
+> Context Card injection, Registry mode, coordination-overhead budget, and Focus Mode are now part of agent-composer Step 3.
+> Use `/agent-composer` for all parallel dispatch with context injection.
+
+## Content preserved at
+
+`plugins/fh-meta/skills/agent-composer/SKILL.md §Step 3-a`
+
+> **Detail**: See `SKILL_detail.md §Archive` — full original content preserved — read only for historical reference.
+
+## Done When
+
+Deprecated — no active execution path. Done When: skill is never directly invoked; all dispatch routes through `/agent-composer` Step 3-a (the successor). This entry satisfies the harness-doctor L2 M-tier requirement for missing Done When (CLAUDE.md §New Skill Creation Pre-Commit Gate).

package/plugins/fh-meta/skills/context-bridge-dispatch/SKILL_detail.md

@@ -0,0 +1,144 @@
+---
+name: context-bridge-dispatch-detail
+description: Archived original body of the deprecated context-bridge-dispatch skill
+load: on-demand
+---
+
+## §Archive
+
+# context-bridge-dispatch — Parallel Agent Context Bridge (archived)
+
+In agent dispatch, sub-agents can read files but do not have access to the live conversation context of the main session. This skill generates a session context card before dispatch and injects it into each agent prompt.
+
+## Triggers
+
+| Phrase pattern | Situation |
+|---|---|
+| "do it in parallel" / "agent view" + 2+ tasks | Auto-triggered |
+| "create a context bridge" | Explicit call |
+| `/context-bridge-dispatch` | Explicit call |
+| Immediately before dispatching 2+ agents | Auto-injected |
+
+## Context Card Format
+
+**N≤2 (standard)**:
+```
+[Session Context Card]
+Purpose: {the goal of this session / task}
+Completed: {what has already been decided or implemented — risk of duplication if agent doesn't know}
+This agent's task: {the specific task for this agent}
+Note: {constraints, directions, or history the agent must know before acting}
+```
+
+**N≥3 (Registry mode — DACS-inspired)**:
+```
+[Session Context Card]
+Purpose: {session goal}
+Completed: {done items + file paths}
+This agent's task: {specific task}
+Note: {constraints}
+
+[Agent Registry]
+Agent-1 ({role}): {≤1 sentence — what it's doing, key files}
+Agent-2 ({role}): {≤1 sentence}
+... (all agents except this one)
+```
+
+Registry entries keep other agents visible (≤200 tokens total) without flooding context.
+Each agent gets its own full card + compressed view of the parallel picture.
+
+## Step 1. Extract Session Context
+
+Summarize the 3 key items from the current conversation:
+- **Purpose**: Core goal of this session / request
+- **Completed**: What has already been built or decided (include file paths and commits)
+- **Note**: Constraints that could lead an agent in the wrong direction if unknown
+
+## Step 2. Identify Agent List + Generate Individual Cards
+
+For each of the N agents to dispatch:
+- Common Context Card (Step 1 summary)
+- Agent-specific item (`This agent's task` field customized per agent)
+
+**N≥3 — Registry mode**: additionally generate one Registry entry per agent:
+```
+Agent-X ({role}): {what it's doing in ≤1 sentence} | files: {key paths}
+```
+Each agent's card includes the Registry entries for all *other* agents (omit its own).
+Keep total Registry section ≤200 tokens. If an agent's task is simple (read-only lookup), its registry entry can be a single phrase.
+
+## Step 3. Execute Parallel Dispatch
+
+Prepend the Context Card to each agent's prompt and dispatch as a single message.
+
+```
+[Session Context Card]
+...
+
+{Agent's original task instruction}
+```
+
+## Focus Mode (on-demand, N≥3)
+
+When an agent's result is incomplete and it signals it needs another agent's full output:
+1. Orchestrator identifies the target agent (a_i) whose full context is needed
+2. Re-dispatch the requesting agent with: full Context Card of a_i + Registry-compressed entries for all others
+3. Use only when genuinely needed — adds one round-trip latency
+
+Trigger signal from agent: `"Need full context from Agent-X to proceed"` or equivalent explicit statement.
+
+## Coordination-Overhead Budget
+
+Centralized multi-agent coordination is not free: external reporting cites orchestrator-worker coordination adding ~+285% token overhead (see the digest Provenance), and coordination cost dominates once a wave exceeds ~4 agents. Apply the following before each dispatch wave.
+
+| Rule | Constraint |
+|---|---|
+| **Parallel fan-out cap** | 3–4 agents per dispatch wave. This is the upper bound for the 2+ parallel dispatch in the Simplification Guard — do not flat-fan-out past 4. |
+| **Capability-aware routing** | Route each subtask to the agent whose declared capability fits, reading `.claude/registry/agent_cards.json` as the routing source (`role` + `allowed_tools` + `writes`). Do not dispatch a `writes: false` audit agent (e.g. `fact-checker`, `hub-persona-auditor`) for a task needing edits. |
+| **Escalation** | If a task genuinely needs >4 parallel agents, decompose hierarchically (supervisor → sub-waves) rather than flat fan-out. |
+
+Source: `../../../../knowledge/shared/harness-core/harness_frontier_diagnosis_2026-06-02.md`
+
+## Step 4. Aggregate Results
+
+After all agents complete, consolidate results in the main session and report to the user.
+
+## Simplification Guard
+
+- Simple file lookup agents unrelated to context (e.g., "read file A") → card may be omitted
+- Single agent dispatch → card injection optional
+- 2+ parallel dispatch → card injection required
+
+## Why This Is Necessary
+
+Agents are spawned in an isolated environment (sub-agent sandbox). They can read what is recorded in files, but decisions made during the current main session conversation — direction changes, completed implementations, design intent — do not exist for the agent unless saved to a file.
+
+Problems this disconnection causes:
+- Attempting to redo already completed work
+- Working in the old direction without knowing the current session's direction change
+- Making wrong decisions without knowing the constraints
+
+Context Bridge corrects this asymmetry.
+
+## Done When
+
+```
+All steps 1–4 completed
++ Context Card injected at the front of each agent prompt
++ Results aggregated and reported after all agents complete
+```
+
+## Connected Skills
+
+| Situation | Connection |
+|---|---|
+| Context collapse risk after a long session | `/context-doctor` |
+| Task of promoting field patterns to FH | `/field-harvest` |
+| When agent orchestration itself is complex | `agent-composer` |
+| N≥3 agents / long-running orchestration (context drifts post-dispatch) | See sister asset: DACS (arXiv:2604.07911) — Registry+Focus dynamic isolation |
+
+## Design Basis
+
+Registry mode and Focus mode patterns absorbed from **DACS** (arXiv:2604.07911, Nickson Patel, 2026-04-09).
+DACS validated: steering accuracy 98.4% vs 21% baseline at N=10; context efficiency 3.53×.
+Cross-audit + import/propagate analysis: `tracks/_audit/session_2026-06-02_dacs-sister.md`