ark-coverage

# /ark-coverage — Ark adoption fitness (not full recon)

**Not a first-run door.** Fitness numbers only (governed files, gates, baseline).
Session 0 → **`/ark-adopt`**. Leftover design → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
Do not send the user to leftover `/ark-contract` or `/ark-fix`.

You audit **how this repo uses ArkGate** (coverage, gates, baseline, host write path) and
what adoption gaps remain. Work autonomously. End with a ranked fitness report.

**This is not `/ark-explore`.** You do **not** produce a multi-pattern dual-plan or spaghetti
Shape ladder by default. If the tree is design-weak under ENFORCE, **handoff** to explore.

## Improvement compass (process preflight)

When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
0–10 scores or Excellent/Good ranks.

**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.

**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
are not “architecture finished.”

**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
new files; place before write (`/ark-place` / prepare-write).

**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.

**Fitness numbers + handoff** when residual lenses are non-empty — never call coverage “done architecture.”

## When / not when

| Use `/ark-coverage` when… | Do **not** use it when… |
|---------------------------|-------------------------|
| “How adopted is Ark?” governed%, gates, baseline, skills stale | Full product map / what-next architecture → `/ark-explore` |
| Capability gaps (CI, write path, ESLint, optional layers) | Apply fixes end-to-end → `/ark-autopilot` |
| Ranked *adoption* opportunities (install, ratchet, contract classify) | Spaghetti pattern plan / golden pattern → `/ark-explore` dual-plan seed |
| Quick honesty before a release checklist | One design trade-off → `/ark-think` |

## Dual engine (mandatory)

| Engine | Deliverable |
|--------|-------------|
| **Deterministic** | governed%, layers, gates, baseline, doctor gaps, summary edges |
| **Exploratory** | Enough source to prove ungoverned clusters / false-green are real (not JSON-only) |

**Forbidden:** only `ark-check --coverage/--doctor/--json` paraphrase with no source evidence.

**Required before you finish:**
1. CLI sensor: `--coverage --json`, `--doctor`, normal `--json` for `summary`.
2. **Product surface** — name the app/package(s) in one line (not a full recon).
3. **Read real source** in the top ungoverned / high-risk clusters (minimum **10 files**
   across at least **4 directories**). Prefer domain, features, adapters, routes — not only config.
4. **“How to fix”** for adoption gaps (globs, install, baseline, intents).
5. If plan A is empty but you see design-weak / concurrent patterns / god modules:
   list them briefly and **STOP — do not continue this skill as complete** for pattern work —
   **handoff `/ark-explore` (dual-plan seed or shape-focus)**. Do not invent a second explore report here.

If you did not open source files, the skill is **not complete**.  
Full recon + pattern planning: `/ark-explore`.


## MCP workspace binding (mandatory)

Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
restart/retargeting is required. `ark://manifest` never satisfies this preflight.

## Dual plane — layers + extras (mandatory, except /ark-runtime)

ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; you **always label** findings so they never blur. Absence of an extra is silent and valid. Skills never enforce. ArkOrder is an extra **inside** the `arkgate` package (`arkgate/order`), not a second install.

| Plane | What it protects | Where it lives | Sensors / tools |
|-------|------------------|----------------|-----------------|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
| **ArkRun** (extra) | Kernel usage + complete declarations; information package `decisionTape` `{ xiHash, event, residual }` | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
| **ArkOrder** (extra) | Operational pattern (ξ vs s). Valve: first `release()`, later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb \| escalate_up \| hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore` | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |

**Rules for every report / answer:**
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them