@claude-flow/cli 3.12.0 → 3.12.2

package/plugins/ruflo-metaharness/skills/harness-drift-from-history/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: harness-drift-from-history
+description: One-command drift detection. Composes audit-list + oia-audit + audit-trend into a single primitive — finds the most recent audit in `metaharness-audit` namespace, runs a fresh audit against the current repo, diffs them via ADR-152 §3.1 similarity, and alerts when structural distance crosses `--threshold`. Iter 53 of ADR-150 deep integration.
+argument-hint: "[--path .] [--baseline-since 7d] [--threshold 0.95] [--dry-run] [--format json|table]"
+allowed-tools: Bash
+---
+
+The natural ops question after running `oia-audit` weekly is "did anything drift?" Before this skill, the answer required a three-step sequence:
+
+```bash
+npx ruflo metaharness audit-list --format json   # → pick a key by hand
+npx ruflo metaharness oia-audit --format json > /tmp/curr.json
+npx ruflo metaharness audit-trend \
+  --baseline-key <picked-key> --current /tmp/curr.json \
+  --alert-on-distance-below 0.95
+```
+
+This skill collapses it into one command:
+
+```bash
+npx ruflo metaharness drift-from-history --threshold 0.95
+```
+
+## What it does
+
+1. Lists records from `metaharness-audit` namespace via audit-list.mjs
+2. Picks the most recent record by `startedAt` (or `--baseline-since 7d` skips anything newer than 7 days)
+3. Runs a fresh `oia-audit` against the current path
+4. Diffs the two via audit-trend, applying `--alert-on-distance-below ${threshold}`
+5. Returns the structured drift report
+
+## Architectural constraint inheritance (ADR-150)
+
+| Constraint | How drift-from-history satisfies it |
+|---|---|
+| Removable | Pure subprocess composition over existing scripts — no new `@metaharness/*` import |
+| Optional | If oia-audit reports `degraded:true`, this skill exits 3 with a degraded payload |
+| Graceful | Empty audit history → exit 2 with hint to seed it; never crashes |
+| CI-gate | Smoke step 17z16 anchors the dispatcher entry + subcommand listing |
+
+## Exit codes
+
+- 0 — similarity ≥ threshold (or threshold not crossed)
+- 1 — drift detected: similarity < threshold (alert fired)
+- 2 — config error (no history, audit-list failed)
+- 3 — upstream metaharness absent (degraded payload returned)
+
+## Example
+
+```bash
+$ npx ruflo metaharness drift-from-history --threshold 0.95
+# drift-from-history
+
+Baseline:        audit-2026-06-16T22-58-47-840Z
+Current:         2026-06-16T23:05:02.231Z
+
+Structural similarity: 1 (near-identical)
+Distance:              0
+
+✓ similarity ≥ 0.95 — OK
+```
+
+## Implementation
+
+[`scripts/drift-from-history.mjs`](../../scripts/drift-from-history.mjs)

package/plugins/ruflo-metaharness/skills/harness-genome/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: harness-genome
+description: 7-section repo readiness report from `metaharness genome <path>`. Returns repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness. Pure-read; degrades gracefully (ADR-150).
+argument-hint: "[--path .] [--alert-on-risk-above 0.5] [--format table|json]"
+allowed-tools: Bash
+---
+
+Companion to `harness-score`. Where score is a 5-dimension numeric
+scorecard, genome is a 7-section categorical/numeric report covering
+repo type, agent topology recommendations, risk score (0-1), MCP
+surface area, test confidence (0-1), and publish readiness (0-1).
+
+## Algorithm
+
+Implementation: [`scripts/genome.mjs`](../../scripts/genome.mjs).
+
+1. Shell out to `npx metaharness genome <path> --json` (60s hard timeout).
+2. Parse the shape: `{ repo_type, agent_topology[], risk_score,
+   mcp_surface, test_confidence, publish_readiness }`.
+3. If `--alert-on-risk-above N`: exit 1 when `risk_score > N`.
+4. Output JSON (default) or markdown.
+
+## Phase-0 baseline (ruflo, measured 2026-06-16)
+
+```
+{
+  "repo_type": "node_mcp_ci",
+  "agent_topology": ["maintainer", "tester", "security", "release"],
+  "risk_score": 0.27,
+  "mcp_surface": "remote",
+  "test_confidence": 0.8,
+  "publish_readiness": 0.9
+}
+```
+
+Ruflo's `risk_score: 0.27` is low (good). `publish_readiness: 0.9` is
+high. The `mcp_surface: "remote"` reflects that ruflo's MCP servers are
+hosted, not bundled.
+
+## When to use
+
+- Pre-mint review: "before scaffolding a custom harness from this repo,
+  should we?" — genome answers it categorically.
+- Drift detection: capture genome snapshots over time, diff via
+  cost-diff-style tooling to spot when `agent_topology` recommendations
+  drift away from a deliberate architecture choice.
+- CI gate: `--alert-on-risk-above 0.5` fails the build when the repo's
+  risk profile crosses a threshold.
+
+## Pairs with
+
+- `harness-score` — numeric readiness
+- `harness-mcp-scan` — static MCP security findings
+- `harness-threat-model` — enterprise-review-grade threat model

package/plugins/ruflo-metaharness/skills/harness-mcp-scan/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: harness-mcp-scan
+description: Static security scan of a harness's declared MCP surface via `harness mcp-scan <path>`. Reads `.mcp/servers.json` + `.harness/claims.json`. Pure-read, no dispatch. Exits 1 on findings at or above `--fail-on` severity.
+argument-hint: "[--path .] [--fail-on low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+Calls `harness mcp-scan` to enumerate every declared MCP server + tool
+and flag policy / permission / dependency issues. Never executes any
+tool; pure static analysis.
+
+## Algorithm
+
+Implementation: [`scripts/mcp-scan.mjs`](../../scripts/mcp-scan.mjs).
+
+1. Shell `npx -p metaharness@latest harness mcp-scan <path> --json`.
+2. Parse `findings[]` with `{ severity, id, server, tool, message }`.
+3. `--fail-on <severity>`: exit 1 when any finding is at or above that
+   level. Default `high`.
+4. Output JSON (default) or markdown table.
+
+## Severity rank
+
+| Severity | Rank |
+|---|---:|
+| low | 1 |
+| medium | 2 |
+| high | 3 |
+
+`--fail-on high` (default) only fails on HIGH; `--fail-on medium` also
+fails on MEDIUM; `--fail-on low` fails on any finding.
+
+## CI integration
+
+```yaml
+- name: MCP static scan
+  run: node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --fail-on high
+```
+
+The exit code is the only thing CI watches; the JSON output goes to
+artifacts for human review.
+
+## Graceful degradation
+
+When `harness` binary is unavailable (no network, blocked registry),
+emits structured `{ degraded: true, reason: 'metaharness-not-available' }`
+and exits 0. Ruflo continues — ADR-150 architectural constraint.

package/plugins/ruflo-metaharness/skills/harness-mint/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: harness-mint
+description: Scaffold a custom AI agent harness via `metaharness new <name> --template <id> --host <id>`. Defaults to DRY-RUN (no writes) unless --confirm is passed. Refuses to write to the calling repo root or anywhere inside it. Honors ADR-150 architectural constraint + ruflo's "destructive-action confirmation" pattern.
+argument-hint: "--name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]"
+allowed-tools: Bash
+---
+
+The one write-capable skill in the plugin. Every other skill is
+pure-read. This one calls `metaharness new`, which writes a new
+directory tree.
+
+## Safety (load-bearing)
+
+1. **Dry-run by default.** Without `--confirm`, the script prints what
+   it would do and exits 0 without touching disk.
+2. **Refuses project root.** If `--target` resolves to the current
+   working directory OR any path inside it, the script errors out with
+   exit 2. Target must be an absolute path OUTSIDE the calling repo
+   (default is a fresh `/tmp/ruflo-mint-<ts>-<name>/` dir).
+3. **Refuses existing target.** Won't overwrite — must scaffold into a
+   non-existent dir.
+4. **Subprocess + 60s timeout.** No library import, no in-process
+   execution. The mint stays sandboxed from ruflo's runtime.
+
+## Algorithm
+
+Implementation: [`scripts/mint.mjs`](../../scripts/mint.mjs).
+
+1. Validate `--name`, `--template`. Default `--host` to `claude-code`.
+2. Resolve `--target` (default: temp dir).
+3. Run safety checks (no project-root writes; target must not exist).
+4. Without `--confirm`: emit dry-run plan, exit 0.
+5. With `--confirm`: shell `npx metaharness new <name> --template <id>
+   --host <id> --target <abs> --yes`.
+
+## Templates
+
+`minimal`, `vertical:coding`, `vertical:devops`, `vertical:support`,
+`vertical:legal`, `vertical:research`, `vertical:trading`, `vertical:health`,
+`vertical:education`, `vertical:sales`, `vertical:business`,
+`vertical:crm`, `vertical:marketing`, `vertical:advertising`,
+`vertical:ai`, `vertical:agentics`, `vertical:ruview`, `vertical:gaming`,
+`vertical:repo-maintainer`, `vertical:exotic`.
+
+## Hosts
+
+`claude-code`, `codex`, `pi-dev`, `hermes`, `openclaw`, `rvm`,
+`copilot`, `opencode`, `github-actions`.
+
+## Example dry-run
+
+```
+$ node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code
+# harness-mint (dry-run)
+
+- action: metaharness new
+- name: my-harness
+- template: vertical:coding
+- host: claude-code
+- target: /tmp/ruflo-mint-1718560000-my-harness
+- confirm: false
+- willWrite: false
+
+Re-run with `--confirm` to actually scaffold.
+```
+
+## Why dry-run by default
+
+Ruflo's behavioral rules say "executing actions with care" — destructive
+or repo-touching actions need confirmation. The dry-run output makes the
+WHAT visible before the WHEN. A human sees `target`, decides, then
+adds `--confirm` if happy.

package/plugins/ruflo-metaharness/skills/harness-oia-audit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: harness-oia-audit
+description: Composite Phase-2 audit worker (ADR-150). Bundles harness oia-manifest + threat-model + mcp-scan into one timestamped audit record stored in the `metaharness-audit` memory namespace. Designed for cron-scheduled drift detection.
+argument-hint: "[--path .] [--dry-run] [--alert-on-worst clean|low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+The 13th worker (ADR-150 Phase 2) — runs three MetaHarness static
+surfaces in one shot, computes a composite worst-severity signal, and
+persists the audit record to memory so drift over time is visible.
+
+## Algorithm
+
+Implementation: [`scripts/oia-audit.mjs`](../../scripts/oia-audit.mjs).
+
+1. Run `harness oia-manifest <path>` — Open Infrastructure Architecture
+   layer alignment (L1-L9).
+2. Run `harness threat-model <path>` — categorized MCP-surface threat
+   report with `worst: clean|low|medium|high`.
+3. Run `harness mcp-scan <path>` — per-server/tool policy + permissions
+   + dep findings.
+4. Composite worst = `max(threatModel.worst, max(mcpScan.findings.severity))`.
+5. Persist payload to memory namespace `metaharness-audit` with key
+   `audit-<iso-timestamp>` (unless `--dry-run`).
+6. `--alert-on-worst <severity>`: exit 1 if composite worst ≥ threshold.
+
+## Graceful degradation
+
+When ALL three components report `metaharness-not-available`, the script
+emits the standard degraded payload and exits 0. When only some are
+degraded, each individual component carries its own `degraded: true`
+flag in the audit record — the audit still runs and persists what it
+could gather.
+
+## CI / cron integration
+
+Designed for weekly cron in `.github/workflows/`:
+
+```yaml
+on:
+  schedule:
+    - cron: '17 4 * * 0'  # Sundays at 04:17 UTC
+jobs:
+  oia-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: node plugins/ruflo-metaharness/scripts/oia-audit.mjs --alert-on-worst high
+```
+
+`--alert-on-worst high` fails the job on any HIGH-severity finding;
+drift below HIGH is logged but doesn't block.
+
+## Memory namespace
+
+Each audit run stores under `metaharness-audit:audit-<iso-ts>`. To list
+recent audits:
+
+```bash
+npx @claude-flow/cli@latest memory list --namespace metaharness-audit --limit 10
+```
+
+To diff two audits (drift detection):
+
+```bash
+A=$(npx ... memory retrieve --key audit-2026-06-01... --namespace metaharness-audit)
+B=$(npx ... memory retrieve --key audit-2026-06-15... --namespace metaharness-audit)
+# Compare composite.worst, components.threatModel.worst, etc.
+```
+
+A future ADR can wire this into a dedicated `cost-diff`-style diff
+viewer specifically for audit drift.
+
+## Pairs with
+
+- `harness-threat-model` — the underlying threat-model component
+- `harness-mcp-scan` — the underlying MCP-scan component
+- `harness-score` + `harness-genome` — readiness metrics (orthogonal to audit)

package/plugins/ruflo-metaharness/skills/harness-score/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: harness-score
+description: 5-dimension harness readiness scorecard from `metaharness score <path>`. Returns harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady. Pure-read; subprocess invocation; degrades gracefully when MetaHarness is absent (ADR-150 architectural constraint).
+argument-hint: "[--path .] [--alert-on-fit-below 70] [--format table|json]"
+allowed-tools: Bash
+---
+
+Surfaces the upstream `metaharness score` CLI as a ruflo skill. Use when
+Claude Code needs to assess whether a repo is ready for harness adoption
+before recommending the user run `npx ruflo init` or `harness-mint`.
+
+## Algorithm
+
+Implementation: [`scripts/score.mjs`](../../scripts/score.mjs).
+
+1. Shell out to `npx metaharness score <path> --json` (single subprocess,
+   60s hard timeout).
+2. Parse the JSON shape: `{ harnessFit, compileConfidence, taskCoverage,
+   toolSafety, memoryUsefulness, estCostPerRunUsd, recommendedMode,
+   archetype, template, scaffoldReady, hardConstraints }`.
+3. If `--alert-on-fit-below N`: exit 1 when `harnessFit < N`.
+4. Output JSON (default) or markdown table.
+
+## Phase-0 baseline (ruflo's own scorecard, measured 2026-06-16)
+
+| Dimension | Value |
+|---|---:|
+| harnessFit | 82/100 |
+| compileConfidence | 100 |
+| taskCoverage | 79 |
+| toolSafety | 100 |
+| memoryUsefulness | 40 |
+| estCostPerRunUsd | $0.048 |
+| recommendedMode | CLI + MCP |
+| archetype | typescript-sdk-harness |
+| template | vertical:coding |
+| scaffoldReady | true |
+
+Ruflo passes its own readiness check. `memoryUsefulness: 40` is the
+weakest dimension — track this as a leading indicator for future memory
+work in the AgentDB layer.
+
+## CI integration
+
+```bash
+node plugins/ruflo-metaharness/scripts/score.mjs --alert-on-fit-below 70 --format json
+```
+
+Exit 1 fails the build. Pair with `harness-genome` for the full
+7-section view.
+
+## Graceful degradation (ADR-150 architectural constraint rule #3)
+
+When `metaharness` is not installed and `npx` can't fetch it (offline,
+no network, registry unreachable), the script emits:
+
+```json
+{
+  "degraded": true,
+  "reason": "metaharness-not-available",
+  "hint": "Install metaharness manually with `npm i -D metaharness` or run `npx metaharness@latest --version` to verify network access."
+}
+```
+
+and exits 0. Ruflo continues to function — this is the architectural
+constraint in action.

package/plugins/ruflo-metaharness/skills/harness-similarity/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: harness-similarity
+description: ADR-152 — weighted similarity between two harness fingerprints (genome + score JSON). Returns overall score in [0,1] plus per-component breakdown (cosine over 9 numerics, categorical agreement over 4 enums, jaccard over agent_topology). Unblocks ADR-151 §3.2 Recommender, §3.3 Drift Detection, §3.5 Plugin Compat. Pure-TS, no `@metaharness/*` dep — preserves ADR-150's four architectural constraints.
+argument-hint: "(--a a.json --b b.json | --a-key X --b-key Y) [--per-dimension] [--alert-below 0.5] [--format json|table]"
+allowed-tools: Bash
+---
+
+Surfaces the production similarity function from [`scripts/_similarity.mjs`](../../scripts/_similarity.mjs) as a callable skill. Use when an agent needs to:
+
+- decide whether to fork an existing harness vs scaffold a new one
+- rank candidate templates against a target repo's genome
+- diff two harnesses produced by different teams to find duplicate work
+- generate the confidence number that ADR-151 §3.2's Recommender wraps
+
+## Algorithm (from ADR-152 §Decision)
+
+```
+overall = 0.60·cosine + 0.25·categorical + 0.15·jaccard
+```
+
+- **cosine** — over a 9-dim numerical vector of normalized scorecard + genome dims
+- **categorical** — fraction of 4 enum fields that match (`repo_type`, `archetype`, `template`, `recommendedMode`)
+- **jaccard** — `|A ∩ B| / |A ∪ B|` over the `agent_topology[]` array
+
+The 3-component design is load-bearing: numerical cosine alone is too coarse (the iter-35 spike showed LEGAL vs DEVOPS at cosine=0.97 despite being unrelated verticals). Categorical + jaccard pull the composite to the correct ordering.
+
+## Reference outputs (iter-35 spike fixtures)
+
+| Pair | overall | cosine | categorical | jaccard |
+|---|---:|---:|---:|---:|
+| `LEGAL` × `LEGAL` (self) | 1.0000 | 1.0000 | 1.0000 | 1.0000 |
+| `LEGAL` × `SUPPORT` | 0.8296 | 0.9987 | 0.7500 | 0.2857 |
+| `LEGAL` × `DEVOPS` | 0.5840 | 0.9734 | 0.0000 | 0.0000 |
+
+Both invariants from ADR-152 §"Smallest demonstrable spike" hold:
+1. `similarity(X, X) === 1` exactly
+2. `similarity(LEGAL, DEVOPS) < similarity(LEGAL, SUPPORT)` (vertical affinity)
+
+## Architectural constraint inheritance (ADR-150)
+
+- **Removable** — pure-TS function, zero static `@metaharness/*` imports.
+- **Optional** — no new dep in `package.json`.
+- **Graceful** — malformed inputs emit `{ degraded: true, reason }` with exit code 2; never throws.
+- **CI-gate** — smoke step 17y locks the contract: module exports, spike fixtures reproduce, CLI dispatcher entry registered, MCP tool registered.
+
+## Usage
+
+```bash
+# File inputs
+npx ruflo metaharness similarity --a a.json --b b.json
+
+# Memory inputs (records persisted by oia-audit.mjs)
+npx ruflo metaharness similarity --a-key harness-X --b-key harness-Y
+
+# Per-dimension breakdown (used by ADR-151 §3.2 Recommender)
+npx ruflo metaharness similarity --a a.json --b b.json --per-dimension
+
+# Alert when too-dissimilar (used by ADR-151 §3.3 Drift Detection)
+npx ruflo metaharness similarity --a a.json --b b.json --alert-below 0.5
+```
+
+## Implementation
+
+Production module: [`scripts/_similarity.mjs`](../../scripts/_similarity.mjs)
+CLI skill: [`scripts/similarity.mjs`](../../scripts/similarity.mjs)
+MCP tool: `mcp__claude-flow__metaharness_similarity` (registered in `v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts`)
+Spike anchor: [`scripts/_spike-similarity.mjs`](../../scripts/_spike-similarity.mjs) (regression suite — invariants locked here)

package/plugins/ruflo-metaharness/skills/harness-threat-model/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: harness-threat-model
+description: Enterprise-review-grade threat model from `harness threat-model <path>`. Categorizes MCP-surface threats; emits `worst: 'clean'|'low'|'medium'|'high'` + per-threat findings. Pure-read.
+argument-hint: "[--path .] [--fail-on clean|low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+The companion to `harness-mcp-scan` for enterprise security reviews.
+Where mcp-scan is a per-server static lint, threat-model produces a
+categorized report suitable for sharing with an InfoSec team.
+
+## Algorithm
+
+Implementation: [`scripts/threat-model.mjs`](../../scripts/threat-model.mjs).
+
+1. Shell `npx -p metaharness@latest harness threat-model <path> --json`.
+2. Parse `{ worst, findings[] }`.
+3. `--fail-on <severity>`: exit 1 when `worst >= fail-on`. Default `high`.
+
+## Severity rank
+
+| Severity | Rank |
+|---|---:|
+| clean | 0 |
+| low | 1 |
+| medium | 2 |
+| high | 3 |
+
+## When to use
+
+- Pre-launch review: include the JSON output in the release-readiness
+  packet sent to security.
+- Periodic audit: schedule via the planned `oia-audit` background
+  worker (ADR-150 Phase 2) to detect MCP-surface drift.
+
+## Graceful degradation
+
+Same pattern as the other skills: when `harness` is absent, emit
+`{ degraded: true }` and exit 0. ADR-150 architectural constraint.