@chrono-meta/fh-gate 1.1.0 → 1.2.1

package/plugins/fh-meta/skills/marketplace-gate/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: marketplace-gate
+description: Evaluates whether a repository meets marketplace listing criteria via a 5-point check and outputs a listing suitability verdict. Checks README completeness, zero-config readiness, maintenance signals, duplication, and public safety.
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Grep", "Glob"]
+model: sonnet
+category: Composability Gate
+---
+
+# marketplace-gate — Marketplace Listing Suitability Gate
+
+Evaluates a repository against 5 listing criteria — README completeness, zero-config readiness, maintenance signals, duplication, and public safety — and outputs a listing suitability verdict.
+
+> While `asset-placement-gate` answers "is this asset suitable for FH?",
+> `marketplace-gate` answers "is this repo ready to be listed in a marketplace?"
+
+## Triggers
+
+- `/marketplace-gate`
+- `/marketplace-gate --target <repo path>`
+- "Can I list this in the marketplace?", "Pre-listing repo check", "Verify before publishing", "Is this ready for marketplace listing?"
+- "Can other teams use this repo?", "Is there a checklist before external distribution?", "Check if this is ready to be public"
+- "Review for open-source release", "Verify before sharing outside the team"
+
+---
+
+## Step 0. Confirm Target Path
+
+Use the path specified by `--target <path>` if provided. Otherwise use current cwd.
+
+```bash
+REPO_PATH="${ARGUMENTS#--target }"
+REPO_PATH="${REPO_PATH:-$(pwd)}"
+echo "Target: $REPO_PATH"
+ls "$REPO_PATH" 2>/dev/null | head -20 || echo "Path not found — please verify the path"
+```
+
+Stop immediately if path is not found.
+
+---
+
+## Step 1. 5-Point Check
+
+### Check 1 — README Completeness
+
+```bash
+README=$(ls "$REPO_PATH"/README* 2>/dev/null | head -1)
+[ -z "$README" ] && echo "FAIL: No README found" && exit
+# Installation command exists
+grep -i "install\|clone\|setup" "$README" | head -3
+# Code block (usage example) exists
+grep -c '```' "$README" 2>/dev/null
+```
+
+| Criterion | Check |
+|---|---|
+| README file exists | ls |
+| Purpose in 1 sentence (first 50 lines) | presence check |
+| Installation path documented | install·clone·setup keywords |
+| At least 1 usage example | code block presence |
+| Version notation | version·v[0-9] pattern |
+
+Result: **PASS** (5/5) / **PARTIAL** (3-4/5) / **FAIL** (≤2/5)
+
+### Check 2 — Immediate Usability (zero-config)
+
+```bash
+# plugin manifest exists
+ls "$REPO_PATH"/.claude-plugin/plugin.json "$REPO_PATH"/package.json 2>/dev/null
+# single-line install command (from README)
+grep -i "claude plugin install\|npm install\|pip install\|brew install" "$README" 2>/dev/null | head -3
+# prerequisites documented
+grep -i "prerequisite\|requirement\|env\|api.key" "$README" -A 2 | head -6
+```
+
+| Criterion | Check |
+|---|---|
+| Single-line install command in README | grep |
+| Prerequisites documented (API key, env var, etc.) | grep |
+| Plugin manifest exists | ls |
+
+Result: **PASS** / **PARTIAL** / **FAIL**
+
+### Check 3 — Maintenance Signals
+
+```bash
+cd "$REPO_PATH" 2>/dev/null || cd "$(pwd)"
+git log -1 --format="Last commit: %ar (%ad)" --date=short 2>/dev/null
+ls CHANGELOG* 2>/dev/null && echo "CHANGELOG found" || echo "No CHANGELOG"
+git tag -l 2>/dev/null | tail -5
+```
+
+| Criterion | Check |
+|---|---|
+| Last commit within 60 days | git log |
+| CHANGELOG or version bump history | ls |
+| git tags exist (version management) | git tag |
+
+Result: **ACTIVE** / **STALE** (60–180 days) / **ABANDONED** (180+ days)
+
+### Check 4 — Duplication / Conflict Detection
+
+```bash
+# list skills in current repo (directory-based)
+find "$REPO_PATH" -name "SKILL.md" 2>/dev/null | xargs -I{} dirname {} | xargs -I{} basename {}
+# compare with existing FH skills (if FH_DIR is set)
+[ -n "$FH_DIR" ] && ls "$FH_DIR/plugins/fh-meta/skills/" 2>/dev/null
+# cross-check registered skills in plugin.json (SoT)
+[ -n "$FH_DIR" ] && python3 -c "
+import json, sys
+with open('$FH_DIR/plugins/fh-meta/.claude-plugin/plugin.json') as f:
+    d = json.load(f)
+skills = [s['name'] for s in d.get('skills', [])]
+print('plugin.json registered skills (' + str(len(skills)) + '):', ', '.join(skills))
+" 2>/dev/null || echo "plugin.json parse failed (FH_DIR not set or path error)"
+```
+
+**Duplication verdict**: If directory-based list and plugin.json list don't match → **STALE** warning.
+
+| Criterion | Check |
+|---|---|
+| No name conflict with existing FH skills | name comparison |
+| No functional duplication | description keyword comparison |
+| plugin.json list matches directory list | cross-check (SoT consistency) |
+
+Result: **CLEAN** / **OVERLAP** (N candidates) / **CONFLICT** (direct conflict)
+
+### Check 5 — Public Safety
+
+```bash
+# detect hardcoded internal domains
+grep -r "<your-ghe-url>\|internal-domain\|sandbox\|internal-api" \
+  "$REPO_PATH" --include="*.md" --include="*.json" --include="*.yaml" -l 2>/dev/null | head -10
+# sensitive information exposure
+grep -r "API_KEY\s*=\|SECRET\s*=\|PASSWORD\s*=" \
+  "$REPO_PATH" --include="*.md" --include="*.json" -l 2>/dev/null | head -5
+# license
+ls "$REPO_PATH"/LICENSE* 2>/dev/null && echo "LICENSE found" || echo "No LICENSE"
+```
+
+| Criterion | Check |
+|---|---|
+| No hardcoded internal domains (or clearly marked as internal-only) | grep |
+| No sensitive information exposed | grep |
+| LICENSE file exists | ls |
+
+Result: **SAFE** / **WARNING** (N items to review) / **BLOCKED** (sensitive info exposed)
+
+---
+
+## Step 2. Verdict Output
+
+```
+marketplace-gate — Listing Suitability Verdict
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Target: {REPO_PATH}
+
+  Check 1 README completeness  : ✅ PASS / ⚠️ PARTIAL / ❌ FAIL
+  Check 2 zero-config          : ✅ PASS / ⚠️ PARTIAL / ❌ FAIL
+  Check 3 Maintenance signals  : ✅ ACTIVE / ⚠️ STALE / ❌ ABANDONED
+  Check 4 Duplication detection: ✅ CLEAN / ⚠️ OVERLAP({N}) / ❌ CONFLICT
+  Check 5 Public safety        : ✅ SAFE / ⚠️ WARNING({N}) / ❌ BLOCKED
+
+  Overall verdict:
+    🟢 Recommended for listing  — 0 FAIL + 0 BLOCKED
+    🟡 Conditional listing      — ≤1 FAIL + 0 BLOCKED
+    🔴 Listing on hold          — 2+ FAIL or 1+ BLOCKED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Follow-up Connections
+
+| Situation | Next skill |
+|---|---|
+| Check 1 FAIL — README needs improvement | `hub-persona-auditor` — external reader perspective audit |
+| Check 4 OVERLAP — confirm duplication | `cross-ecosystem-synergy-detection` — explore synergy potential |
+| Check 5 WARNING — internal assets need cleanup | `harness-doctor` — internal structure consistency diagnosis |
+| After 🟢 verdict — install test | `install-doctor` — pre-install conflict verification |
+
+## Done When
+
+```
+All steps 0–2 completed
++ Full 5-point check results output (Check 1–5 individual verdicts)
++ Overall verdict output (🟢 Recommended / 🟡 Conditional / 🔴 On hold)
+```
+
+**→ Mandatory before 🟢 Recommended verdict: `source-grounding-audit`** — forward axis check on all citations, external URLs, and file path references in the asset being reviewed. A 🟢 verdict without source-grounding-audit is incomplete. If source-grounding-audit finds phantom refs → verdict downgrades to 🟡 Conditional automatically.
+
+> When `agent-composer` receives a "comprehensive marketplace listing audit" request,
+> recommend: Wave 0 `fact-checker` → Wave 1 `marketplace-gate` + `hub-persona-auditor` in parallel.

package/plugins/fh-meta/skills/memory-hygiene/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: memory-hygiene
+description: Detects "stale-but-confident" memory entries — facts that were once verified but have silently drifted. Scans memory/*.md for entries past their staleness threshold and proposes re-verification or archival. Runs automatically as part of harvest-loop Step 0-c and on explicit invocation.
+user-invocable: true
+allowed-tools: ["Read", "Grep", "Glob", "Edit", "Bash"]
+model: sonnet
+---
+
+# memory-hygiene — Stale Memory Detection and Re-Verification
+
+> Addresses the "stale-but-confident" failure mode: verified information that silently drifts
+> while remaining highly ranked in retrieval — identified as a critical harness failure mode
+> in *Scaling the Harness in Agentic AI* (arXiv:2605.26112).
+
+FH is an online-first harness. Its memory entries point to live external resources (GitHub
+repos, arXiv records, Zenodo DOIs, monitoring routines). These drift faster than in
+offline systems — which makes hygiene both more necessary and more tractable (live
+re-verification is possible).
+
+## Trigger Conditions
+
+### Natural Language Triggers
+
+| Phrase | Intent |
+|---|---|
+| "memory check", "check stale memories" | Manual hygiene scan |
+| "are my memories still accurate?" | Full re-verification pass |
+| "clean up memory", "memory audit" | Propose archival candidates |
+| "something in memory might be wrong" | Targeted re-check |
+
+### Automatic Trigger
+
+- **harvest-loop Step 0-c**: Runs automatically as the first step of every full harvest-loop
+- **Cadence guard**: Skip if memory-hygiene ran within the last 7 days
+  (`tracks/_meta/memory_hygiene_*.md` mtime check)
+
+## Staleness Classification
+
+| Type | Staleness Threshold | Re-verification Method |
+|---|---|---|
+| `project` — status/milestone entries | **14 days** | Re-read source file or live resource |
+| `reference` — external URLs, DOIs, GitHub repos | **30 days** | WebFetch or gh CLI check |
+| `feedback` — operating rules | **90 days** | Grep for contradicting evidence in recent sessions |
+| `user` — user profile entries | **180 days** | Flag only, no auto-verification |
+
+## Execution Steps
+
+### Step 1 — Scan memory/*.md
+
+```bash
+ls ~/.claude/projects/*/memory/*.md 2>/dev/null
+# or hub-local:
+ls memory/*.md 2>/dev/null
+```
+
+For each file, extract:
+- `metadata.type` from frontmatter
+- `date:` or any date-like field in frontmatter or body
+- Key factual claims (GitHub URLs, status strings, version numbers, dates)
+
+### Step 2 — Classify by Staleness
+
+Apply thresholds from the table above. Output a staleness roster:
+
+```
+STALE (>threshold):
+  - api-migration-notes.md [feedback, 45d] — procedure may have changed
+  - release-status.md [project, 16d] — status fields need live check
+  - upstream-tracker.md [reference, 32d] — GitHub URL check needed
+
+FRESH (<threshold):
+  - user_role.md [user, 3d] — skip
+  - fh-closed-loop-principle.md [feedback, 7d] — skip
+```
+
+### Step 3 — Re-verify Stale Entries
+
+For each stale entry, run the appropriate re-verification:
+
+**Reference type** (URLs, DOIs, GitHub):
+- Use `gh api` for GitHub resources
+- Use `WebFetch` for DOIs and arXiv records
+- Mark `verified_at: YYYY-MM-DD` in frontmatter if still valid
+- Flag `⚠ DRIFTED` if content has changed materially
+
+**Project type** (status, milestones):
+- Cross-check against `reference_next_session_starter.md` and recent git log
+- Update or flag
+
+**Feedback type** (rules):
+- Grep `tracks/*/` for evidence contradicting the rule in last 30 days
+- If 2+ contradictions found → flag for human review (do not auto-modify)
+
+### Step 4 — Propose Actions (User Gate)
+
+Present findings in this format:
+
+```
+memory-hygiene scan complete: N entries checked
+  VERIFIED (no change needed): N
+  UPDATED (refreshed verified_at): N
+  ⚠ DRIFTED (content changed — needs human review): N
+  📦 ARCHIVE CANDIDATE (no activity in Xd, superseded): N
+
+Proposed changes:
+  1. arxiv-submission-status.md — update status fields [auto-apply?]
+  2. harness-federation-sync-plan.md — CLOSED flag still accurate? [confirm]
+  ...
+
+Apply updates? [y / N per item]
+```
+
+### Step 5 — Record Run
+
+```bash
+# Create hygiene log
+echo "---\ndate: $(date +%Y-%m-%d)\nentries_checked: N\nupdated: N\ndrifted: N\n---" \
+  > tracks/_meta/memory_hygiene_$(date +%Y-%m-%d).md
+```
+
+## Constraints
+
+- **No auto-deletion**: Archive candidates are proposed, not deleted. Human confirmation required.
+- **Feedback type**: Never auto-modify feedback rules — flag only.
+- **Simplification guard**: If 0 stale entries found, output one line "memory-hygiene: all fresh" and exit.
+- **FH online advantage**: Unlike offline harnesses, FH can re-verify external references live.
+  Use this — don't skip external checks.
+
+## Done When
+
+```
+Step 1~5 complete
++ Staleness roster output
++ Re-verification run for all STALE entries
++ User gate presented and responded to (y/N per item)
++ Hygiene log written to tracks/_meta/memory_hygiene_{date}.md
+```
+
+## References
+
+- Theoretical basis: *Scaling the Harness in Agentic AI* (arXiv:2605.26112) §Memory Problems — "stale-but-confident" failure mode
+- Integrates with: `harvest-loop` Step 0-c · `context-doctor` (context layer hygiene)
+- Memory format: `~/.claude/projects/*/memory/MEMORY.md`

package/plugins/fh-meta/skills/meta-prompt-builder/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: meta-prompt-builder
+description: Generates structured prompts to send to each agent in an agent dispatch plan. Triggered by "write the instructions", "what do I say to the agent?", "write the prompt for me", "meta-prompt-builder". Bridges agent-composer (which agents) and prompt content (what to say). Uses Goal/Context/Constraints/Done When structure.
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Glob", "Grep"]
+model: opus
+---
+
+# meta-prompt-builder — Prompt Delegation Skill
+
+When agent-composer decides "what to orchestrate", meta-prompt-builder designs "what to say to each agent."
+Delegates prompt writing itself to AI — interprets Goal / Context / Constraints / Done When structure within the FH context.
+
+## Primary Users
+
+**agent-composer proficients** — People who already have an orchestration plan and want to structure the specific instructions for each agent. Use this when you already know "which agents to use."
+
+Beginners (unsure which agents to use) → start with agent-composer first. meta-prompt-builder is a post-orchestration step.
+
+## Triggers
+
+- `/meta-prompt-builder`
+- Automatically suggested immediately after agent-composer outputs an orchestration plan when user says "how do I instruct each one specifically?"
+- "Write the prompts per Wave", "What should I say to each agent?", "Design the instructions"
+- "I don't know what to tell the agents"
+- "Tell me how to instruct this task so it's handled well"
+- "Write the prompt for me"
+- "Tell me how to request this from Claude"
+- "How should I write the instructions?"
+
+---
+
+## Step 0. Receive Task
+
+Input: natural language task description + (optional) agent-composer orchestration plan
+
+If no input is provided, ask for 4 fields:
+```
+What task are you designing a prompt for?
+ - Goal: What are you trying to achieve?
+ - Context: What project, files, or harness state is involved?
+ - Constraints: What should be avoided? Are there budget or time limits?
+ - Done When: When can you say "it's done"?
+```
+
+### Natural Language Goal → Auto-suggest Recommended Chain
+
+When Goal is provided in natural language (e.g., "I need to report to the team lead"), suggest a recommended chain using the keyword mapping below.
+
+| Goal keyword | Recommended chain | Reason |
+|---|---|---|
+| "report", "team lead", "executive", "CTO", "persuade", "review" | apex-review → (sim-conductor if needed) | Decision-maker simulation then quality validation |
+| "analyze", "diagnose", "something seems off" | harness-doctor → context-doctor | Structural + contextual diagnosis simultaneously |
+| "simulate", "validate", "meta" | sim-conductor (D-code or Area B) | Multi-perspective validation |
+| "install", "setup", "onboarding" | plugin-recommender → install-wizard | Recommend then install |
+| "review", "code check" | sim-conductor D-code → hub-cc-pr-reviewer | Code review chain |
+
+Output format:
+```
+Recommended chain: {Goal keyword} →
+  Wave 1: {Agent A} — {1-line reason}
+  Wave 2: {Agent B} — {1-line reason}
+→ Proceed with this chain? (Y: immediately orchestrate with agent-composer / N: enter 4-field directly)
+```
+
+---
+
+## Step 1. Reinterpret as FH 4-field
+
+Structure the input task according to FH context.
+
+| Field | FH interpretation |
+|---|---|
+| Goal | The harness state change this agent combination must achieve |
+| Context | Harness version + latest sim result M/S tier + target file paths |
+| Constraints | Simplification guard + no self-recursion + no inter-Wave file conflicts |
+| Done When | M-tier 0 items OR specified agent fan-in complete OR N naming candidates produced |
+
+---
+
+## Step 2. Generate Per-Agent Prompt Drafts
+
+Receive agent-composer orchestration plan as input and generate instructions to deliver to each agent per Wave.
+
+Format:
+```
+Wave {N}-{ID}: [{agent name}]
+  Goal: {1 line}
+  Context: {harness state in 3 lines max}
+  Constraints: {prohibited items in 2 lines max}
+  Done When: {evaluation criterion in 1 line}
+  ───────────────────────────────
+  Actual instruction:
+  "{Natural language instruction for the agent — 2–4 sentences}"
+```
+
+When called standalone without an agent-composer plan: collect 4-field directly via Step 0 questions, then generate a single-agent prompt.
+
+---
+
+## Step 3. Quality Self-Validation
+
+Before outputting the generated prompt draft, check against 3 criteria.
+
+1. **Goal achievability**: Is the Goal achievable within the agent's allowed-tools range?
+2. **Done When measurability**: Is Done When a measurable event in the M/S/R framework?
+3. **Context alignment**: Does the Context match the "target" scope defined in the agent's SKILL.md?
+
+Items that fail the check are marked `[WARN]` and the decision is delegated to the user.
+
+**Step 3 bias prevention**: When checking Goal achievability, Read the agent's SKILL.md to directly verify (directly compare allowed-tools list). Since generator and validator are the same LLM, self-validation without external reference repeats bias.
+
+**Done When completeness check**: Even if Done When is measurable in the M/S/R framework, the following 3 must also be stated to pass without WARN:
+1. Measurement subject (which agent's output is the basis)
+2. Measurement timing (absolute basis for this run vs relative to previous run)
+3. Version / baseline (harness-doctor version, sim-conductor Area, etc.)
+
+### Done When Ambiguity Patterns — Automatic WARN Triggers
+
+If Done When contains any of the following patterns, automatically emit `[WARN: Done When not measurable]`.
+
+| Ambiguity type | Example expression | WARN reason |
+|---|---|---|
+| **Subjective completion** | "if it goes well", "if it's done properly", "if it feels right" | No binary judgment criterion |
+| **Speed without numbers** | "quickly done", "finished soon" | No count/time criterion |
+| **Absence description** | "if there are no issues", "if there are no errors" | Cannot count as M/S/R |
+| **Unconditioned completion** | "when it's all done", "when finished" | What state counts as complete is undefined |
+
+Acceptable form examples:
+- "M-tier 0 items" ✅
+- "harness-doctor fan-in complete + S-tier 3 or fewer" ✅
+- "Scenario 1 PASS verdict received" ✅
+
+---
+
+## Integration with Existing FH Assets
+
+| Asset | Integration direction |
+|---|---|
+| **agent-composer** | Input source: orchestration plan → meta-prompt-builder elaborates Wave-by-Wave prompts |
+| **sim-conductor** | Output validation: generated prompts can be quality-validated via D-code mode |
+| **fact-checker** | Wave 0 gating: check if generated prompts overlap or conflict with existing assets |
+| **field-harvest** | Context field input source: field patterns can be reflected in Constraints |
+| **harness-doctor** | Done When cross-validation: verify alignment with harness-doctor checklist |
+
+---
+
+## Meta-Simulation Validation Criteria (required after onboarding)
+
+> **Detail**: See `SKILL_detail.md §Meta-Simulation Validation Criteria` — 3-axis functional/performance measurement (goal achievement / context alignment / constraint validity) + 3 validation scenarios + marketplace-gate onboarding gate — read after onboarding when validating the skill itself, not per-invocation.
+
+---
+
+## Done When
+
+```
+All steps 0–3 completed
++ Per-agent prompt drafts output per Wave (Goal/Context/Constraints/Done When 4-field included)
++ Step 3 quality self-validation complete ([WARN] items delegated to user if present)
++ Generated prompts awaiting user review
+```
+
+## Simplification Guard
+
+- meta-prompt-builder does not execute agents directly. Prompt design only.
+- Requests without Done When must be confirmed before proceeding.
+- Generated prompts are always reviewed by the user before execution.

package/plugins/fh-meta/skills/meta-prompt-builder/SKILL_detail.md

@@ -0,0 +1,37 @@
+---
+name: meta-prompt-builder-detail
+description: On-demand detail for meta-prompt-builder. Holds the onboarding-time Meta-Simulation Validation Criteria (3-axis measurement + validation scenarios + marketplace-gate). Not needed per-invocation; read after onboarding when validating the skill itself.
+load: on-demand
+---
+
+# meta-prompt-builder — Detail (on-demand)
+
+## §Meta-Simulation Validation Criteria
+
+**(required after onboarding)**
+
+Not persona simulation — **functional and performance measurement** along 3 axes:
+
+**Axis 1. Goal achievement rate (functional accuracy)**
+- Inject meta-prompt-builder-generated prompts into actual agents
+- Binary judgment on whether Done When criteria are met
+- Measurement: Done When achieved (1/0) × number of Waves
+
+**Axis 2. Context alignment (context quality)**
+- Grep cross-validation of whether generated Context field matches actual harness state
+- Measurement: false positives (missing paths, stale version references) / total Context items
+
+**Axis 3. Constraint validity (guard effectiveness)**
+- Whether simplification guard violations occur when generated prompts are executed
+- Measurement: violation count (target: 0)
+
+**Validation scenarios**:
+
+- Scenario 1 (core): Compare meta-prompt-builder usage vs direct phrasing
+  - Pass criteria: Achieve same Done When in ≤70% of conversation turns
+- Scenario 2 (edge): Graceful fallback when agent-composer returns "cannot orchestrate"
+  - Pass criteria: "No orchestration plan → redirect to direct 4-field input" transition (no error stop)
+- Scenario 3 (stress): WARN emission rate 100% when Done When is ambiguous
+  - Pass criteria: WARN 100% across 3+ ambiguous expression tests
+
+**Onboarding gate**: marketplace-gate check must pass.