@chrono-meta/fh-gate 1.1.0 → 1.2.0

package/plugins/fh-meta/skills/harness-doctor/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: harness-doctor
+description: Scans a project's harness structure (.claude/ directory, CLAUDE.md, rules, agents) to diagnose complexity, drift, missing files, and broken references, then suggests improvements. `--lint` flag adds language-pattern scan (self-marketing, cushion words, version brags). Triggered by "harness check", "structure diagnosis", "CLAUDE.md audit".
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+model: sonnet
+complexity_routing:
+  base: sonnet
+  high: opus
+  escalate_when:
+    - cold_start
+    - cross_project
+---
+
+# harness-doctor — Harness Structure Diagnosis + Prescription
+
+"A good harness gets simpler over time. If it's getting more complex, something is wrong."
+
+Diagnoses harness structural health across 5 layers and proposes M/S/R prescriptions:
+
+1. **L1 Structural completeness** — required file existence (CLAUDE.md · .claudeignore · .claude/)
+2. **L2 Complexity** — current state vs. simplification principle (line count · unused files · duplicate definitions)
+3. **L3 Drift** — rule vs. actual pattern mismatch (broken references · stale files · conflicting rules)
+4. **L4 Connection diagnosis** *(FH environment only)* — meta hub ↔ field project reference consistency
+5. **L5 Pattern analysis** *(FH environment only)* — skill activity · call context appropriateness · effect metrics
+
+---
+
+## Execution Steps
+
+### Step 1. Confirm Diagnostic Target
+
+Check current cwd harness file structure and determine if FH environment (tracks/ + knowledge/ + plugins/ all present).
+
+### Step 2. L1 — Structural Completeness
+
+| File | When Missing |
+|---|---|
+| `CLAUDE.md` | **M-tier** — harness entry impossible |
+| `.claudeignore` | S-tier — context-doctor execution recommended |
+| `.claude/` directory | M-tier (when rule files exist) |
+
+### Step 3. L2 — Complexity Diagnosis
+
+| Check | Verdict |
+|---|---|
+| CLAUDE.md ~100 lines | Normal (project) / FH threshold: 500 lines |
+| CLAUDE.md 100~200 lines | S-tier warning |
+| CLAUDE.md 200+ lines | M-tier — separation or reduction needed |
+| 15+ `##` sections in CLAUDE.md | S-tier warning |
+| SKILL.md > 300 lines AND no `SKILL_detail.md` | S-tier — propose `/skill-splitter` (governance-semantic split, not compression) |
+| Rules files unreferenced in CLAUDE.md | R-tier |
+| weekly_audit 14~30 days elapsed | S-tier |
+| weekly_audit 30+ days elapsed | M-tier |
+
+### Step 3-L. Language Lint (`--lint` mode only)
+
+> Activate with `/harness-doctor --lint` or when harvest-loop surfaces a P10-series signal. Skipped in standard runs.
+
+Grep-based scan of SKILL.md, agent `.md`, and doc files for self-marketing language patterns. Outputs replacement suggestions — no automatic edits.
+
+**Detection patterns**:
+
+| Pattern | Examples | Replacement direction |
+|---|---|---|
+| Self-declarations of quality | "industry-leading", "the world's first", "core skill", "best" | Delete — no external evidence |
+| Version / iteration labels | "v0.3", "22nd naming round", "26th iteration", "(added 2026-05-24)" | Remove (git history manages versioning) |
+| Cushion language | "easily", "instantly", "seamlessly", "without burden", "fully automated" | Replace with behavior-based description |
+| Owner self-reference loops | "validated by our team", "proven internally" | Delete or replace with external evidence |
+| Marketing word stacking | 3+ adjectives in one sentence | Reduce to functional description |
+| Spec-only artifacts | SKILL.md or agent file missing `Done When` section | Add observable output criteria |
+
+**Scan targets**:
+```bash
+find {FH_ROOT}/plugins -name "SKILL.md" | sort
+find {FH_ROOT}/.claude/agents -name "*.md" | sort
+find {FH_ROOT}/docs -name "*.md" 2>/dev/null | sort
+```
+
+**Detection commands**:
+```bash
+# version / iteration labels
+grep -n "v[0-9]\+\.[0-9]\|[0-9]\+th\|[0-9]\+th iteration\|prototype [0-9]\+" {file}
+# cushion language
+grep -n "fully\|instantly\|full coverage\|automatically\|conveniently\|easily\|without burden\|seamlessly" {file}
+# self-declaration patterns
+grep -n "core skill\|world's first\|best\|most\|top\|industry-leading" {file}
+```
+
+**Output format** (per file):
+```
+File: {path}
+  L{N}: "{original text}"
+  → Suggested: "{replacement}" (reason: {pattern type})
+  → Or: remove (reason: {pattern type})
+```
+
+**Lint findings** feed into Step 7 report as a separate "Language Quality" section — not mixed into structural M/S/R tiers. Lint findings are advisory: HIGH (spec-only = missing Done When, treat as S-tier) / LOW (language patterns, R-tier).
+
+---
+
+### Step 4. L3 — Drift Diagnosis
+
+| Check | Tier |
+|---|---|
+| Broken local file references in CLAUDE.md | M-tier |
+| .claude/rules files unmodified 90+ days | R-tier |
+| settings.json JSON syntax error | M-tier |
+| Hooks in settings.json (PostToolUse/Stop) that don't fire in Agent View | S-tier or M-tier |
+
+Hook divergence verdict: 0 hooks = Normal · 1+ hooks (session-end/Stop) = S-tier · 1+ hooks (PostToolUse file writes or external API) = M-tier (data loss risk in Agent View).
+
+### Step 5. L4 — Connection Diagnosis *(FH only)*
+
+- Tracks with no sync in 30+ days → R-tier
+- CATALOG.md: 5+ open items in recent 5 sessions → S-tier
+- Field project CLAUDE.md missing → S-tier
+
+### Step 6. L5 — Pattern Analysis *(FH only)*
+
+**L5-A Skill Activity** (grep-based on session records):
+
+| State | Criteria | Tier |
+|---|---|---|
+| ACTIVE | 2+ times in 30 days | Normal |
+| LOW_ACTIVE | 1 time in 30 days | R-tier |
+| INACTIVE_30D | 0 times in 30 days | S-tier |
+| INACTIVE_90D | 0 times in 90 days | M-tier |
+
+**L5-B Call Context Appropriateness**: Keyword grep for known misuse patterns (hub-persona-auditor in code PR context · sim-conductor without onboarding · harness-doctor self-loop). Report as "suspected (false positive possible)" — no LLM call.
+
+**L5-C Effect Metrics**:
+
+| Metric | OK condition | Tier if failing |
+|---|---|---|
+| E1 CLAUDE.md lines | Decrease or ±10 | E1_WARN if +50 lines |
+| E2 Complexity ratio | ≤100 lines/skill | E2_WARN (≤200) / E2_FAIL (>200) |
+| E3 CATALOG open consumption | ≥50% in 30 days | — |
+| E4 harvest signals | ≥3 in 30 days | — |
+| E5 SKILL.md change | Within 14 days | — |
+| E6 Cold audit | Within 30 days | E6_WARN |
+| E7 Evolution-loop observability | Asset edits have edit_manifest predictions | E7_WARN = S-tier |
+
+**HHS** (Harness Health Score): Each OK condition = +1 point (7 max). HHS ≥ 4 = Healthy · 2~3 = Caution · ≤1 = Critical.
+
+> **Detail**: See `SKILL_detail.md §L5-Detail` — bash scripts for L5-A, L5-B, L5-C/E metrics — read when running L5 pattern analysis.
+
+---
+
+## Harness-Defect Taxonomy (frontier cross-check)
+
+| Defect class | FH detectable signals | Tier |
+|---|---|:---:|
+| **Context Drift** | Stale paths in CLAUDE.md (L3) · rules unmodified 90+ days (L3) · CLAUDE.md over threshold (L2) | S |
+| **Schema Misalignment** | Plugin count drift · SKILL.md missing `Done When` (undocumented contract) | M |
+| **State Degradation** | tracks/ no sync 30+ days (L4) · INACTIVE_90D skills (L5-A) · orphaned memory entries | M |
+
+Signal in 2+ classes → escalate one tier.
+
+---
+
+### Step 7. M/S/R Prescription Report Output
+
+```
+## harness-doctor Diagnostic Results
+
+### 🟥 M-tier (Immediate Action)
+### 🟧 S-tier (Strongly Recommended)
+### 🟩 R-tier (Recommended)
+
+---
+## L5 Pattern Analysis
+- Activity (L5-A): [list]
+- Context appropriateness (L5-B): [suspected misuse or "no issues"]
+- Effect metrics (L5-C): E1=[result] / E3=[result] / E5=[result]
+
+---
+## Language Quality (`--lint` mode only)
+- HIGH (spec-only — missing Done When): [list or "none"]
+- LOW (language patterns): [file: L{N}: "{text}" → {suggestion}]
+
+Diagnostic scope: L1~L3 [· L4 · L5 (FH only)] [· --lint]
+```
+
+M-tier 0 → output "Structure healthy. Maintaining simplification trend."
+
+**M-tier Immediate Human Gate**: If 1+ M-tier found → pause, surface options: (a) AI proceeds to Step 8 / (b) human review first / (c) abort. Do not auto-apply prescriptions that could close a self-referential loop.
+
+### Step 8. harvest-loop Integration *(when tracks/_audit/ exists)*
+
+When 1+ M-tier found → propose adding `## Harness Structure Check (harness-doctor)` section to latest weekly_audit file.
+
+### Step 9. Eval-First Quantitative Gate *(v0.x → v1 promotion only)*
+
+**Thresholds** (measured over 5 sim-conductor runs): Tool Selection Accuracy > 0.90 · Multi-Step Coherence > 0.85 · Clarification Rate < 0.30.
+
+### Step 10. Regression Guard *(when SKILL.md / rules / CLAUDE.md modified)*
+
+Verifies that prescription application didn't strip operational content. Run after prescription applied, at pre-merge gate, or when harvest-loop Step 4 detects file changes.
+
+| Check | Tier |
+|:---:|:---:|
+| F1 Frontmatter integrity | M |
+| F2 Critical section preservation (Execution Steps · Done When · Triggers) | M |
+| F3 Code block count not reduced by 4+ | S |
+| F4 Operational keyword preservation (M-tier/S-tier/Wave/Step/Done When) | M if ≥50% drop · S if 20~49% |
+| F5 Cross-reference paths resolve | M |
+| F6 Line reduction ≥30% | S |
+| F7 Bash block syntax (bash -n parse) | M if net increase in bad blocks |
+
+Verdict: ✅ PASS (0M 0S) · ⚠️ REVIEW (0M 1+S) · ❌ BLOCK (1+M).
+
+Implementation: `bash templates/regression_guard.sh` (compare vs main) or `bash templates/regression_guard.sh BASE HEAD`.
+
+> **Detail**: See `SKILL_detail.md §Step-1-3` — bash scripts for Steps 1~6 (L1~L4 diagnostics) — read when running the diagnostic commands.
+
+### Step 11. PR Change Consistency Check *(triggered on "PR" / "push" / branch with FH changes)*
+
+Detect changed files vs main → category-based consistency checks:
+
+| Category | What's checked |
+|---|---|
+| SKILL.md changes | Plugin description count drift · README skill table · CATALOG entry |
+| Agent file changes | README agent count · agent_cards.json count sync |
+| knowledge/shared/ changes | CATALOG coverage |
+| README.md changed | Stale org/version references |
+| AGENTS.md / CLAUDE.md changed | Agent count cross-reference sanity |
+
+Verdict: ✅ CONSISTENT · 🟧 INCONSISTENT (fix before push) · 🟩 REVIEW (intent check).
+
+**Auto-propose** (non-blocking) when "PR", "push", "merge" detected in session.
+
+> **Detail**: See `SKILL_detail.md §Step11` — bash scripts for each consistency check category — read when running PR change verification.
+
+---
+
+## Done When
+
+| Stage | Completion |
+|---|---|
+| Step 7 M/S/R prescription report output | ✅ Diagnosis complete |
+| M-tier 0 + "Structure healthy" output | ✅ Diagnosis complete (no prescription needed) |
+| Step 8 weekly_audit section proposed | ✅ Integration proposal complete |
+| Step 9 Eval-First verdict output (when requested) | ✅ Promotion verdict complete |
+| Step 10 Regression Guard verdict (PASS/REVIEW/BLOCK) | ✅ Post-fix verification complete |
+| Step 11 PR consistency check verdict | ✅ PR pre-push verification complete |
+
+**This skill Done When = "prescription report output complete".** Actual resolution of M/S/R items belongs to user or follow-up work.
+
+Verdict: PASS (M-tier 0, "Structure healthy") | CONDITIONAL_PASS (S/R remain, no M) | FAIL (1+ M-tier found) | ESCALATE (structural ambiguity before prescription can be issued)
+
+**Three-Doctor Loop chain** (auto-propose after prescription report):
+- M-tier + context/token waste → propose `/context-doctor`
+- M-tier + user-facing behavior changes → propose `/sim-conductor Area A`
+- SKILL.md S-tier (> 300 lines, no SKILL_detail.md) → auto-propose `/skill-splitter`: `"I see [skill] SKILL.md is [N] lines with no SKILL_detail.md. Want me to run /skill-splitter?"`
+- Both → propose full Three-Doctor Loop: context-doctor → sim-conductor Area A
+
+---
+
+## Trigger Phrases
+
+- `/harness-doctor` · "harness diagnosis" · "harness structure check" · "CLAUDE.md audit"
+- `/harness-doctor --lint` · "check FH files for marketing language" · "description diet" · "remove marketing language" (→ Step 3-L)
+- "my Claude settings seem off" · "something that used to work doesn't anymore" · "skill isn't triggering"
+- "PR 올려줘" · "PR check" · "변경사항 영향 범위" (→ Step 11)
+
+No auto-firing — only executes when user explicitly invokes. Step 11 exception: propose as one-liner when "PR"/"push"/"merge" detected.
+
+## Failure Fallback
+
+On Claude API / MCP failure → refer to [`references/fallback-guide.md`](../../references/fallback-guide.md).
+
+---
+
+## Three-Doctor Loop Integration
+
+harness-doctor = **current structure diagnostician**. context-doctor = context collapse. sim-conductor = future behavior prediction. Together: diagnose → prescribe → re-diagnose closed loop.