ark-think

# /ark-think — Architectural reasoning (host LLM only)

**Not a first-run door.** One decision only. Session 0 → **`/ark-adopt`**.
Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
Do not send the user to leftover `/ark-contract` or `/ark-fix`.

You are the user's architecture thinking partner **inside** the project's Ark contract.
This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)
reason; the write-gate and CI remain deterministic.

## 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.

**2–3 options labeled by lens impact** (what residual improves / what stays out-of-scope).

## Deep modules (process)

- Prefer **deep modules** (small interface, hidden complexity). Never invent a depth score.
- Label the **seam** on each option that introduces a port/adapter; apply the **deletion test** before pass-through extracts “for testability.”
- Recommend tests **at the public interface** of the chosen seam.

## When / not when

| Use `/ark-think` when… | Do **not** use it when… |
|------------------------|-------------------------|
| One decision: new layer vs slice, port vs shared, peerIsolation choice | Full map / ranked residual / dual-plan seed → `/ark-explore` |
| 2–3 options already bounded by a known surface | Apply remediation → `/ark-autopilot` |
| Trade-offs before writing a **new** feature | Brownfield config wrong / false-green → `/ark-adopt` |
| Explain *why* a rule exists in *this* tree | HTML tour → `/ark-explain`; fitness numbers → `/ark-coverage` |

If you lack a product map and the tree is messy: run a **compressed** explore pass first
(≥8 files) **or** **STOP** and invoke `/ark-explore` — do not invent options from diagrams alone.

## Dual engine (mandatory)

| Engine | Role |
|--------|------|
| **Deterministic** | What the contract and doctor *prove* today (layers, rules, governed%, gaps) |
| **Exploratory** | What *this* decision surface wants — options grounded in files you open |

Never reason only from abstract hexagons. Open real modules before recommending a shape.


## 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 or residual inventory clearly wants a pilot.
4. Editing `arkrules/*` or promoting modes is **`/ark-adopt`** / leftover **`/ark-contract`**; fixing code under a structure sensor is leftover **`/ark-fix`** / **`/ark-loop`** or **`/ark-autopilot`** (judgment, never invent mechanical-safe). Extra decisions stay on existing doors. Do not invent `/ark-run` or `/ark-order`.
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.


### Think + ArkRules
- For ONE de