ark-autopilot

# /ark-autopilot — Apply the path

**When:** the user wants architecture cleaned end-to-end, or leftover design after a map.
**Not when:** map only (`/ark-explore`), session 0 / config lying (`/ark-adopt`), or one new file (`/ark-place`).

## Steps

1. Read `arkgate-check --doctor` (do #1).
2. Fix import-rule debt; if leftover design remains, apply **one** small refactor.
3. Re-run doctor. Never weaken `ark.config.json`.

**This is the apply door.** Invoking it **is** the approval. Run `arkgate-check --doctor` for the next step.

## Autonomy contract

The CLI is a **sensor and gate**. **CLI budget:** one doctor / `--plan`; open files; **write**;
re-check. Forbidden as the result: “4 safe / 4 judgment — approve?”, dumping `--plan` JSON,
or `STOP — invoke /ark-fix` / `/ark-loop` / `/ark-contract`. Do that work **here**.

Apply plan A (`mechanical-safe` **and** judgment). If leftover design work remains, apply
**one** small refactor this turn, then re-doctor. Never batch every Shape bet.

Composes **explore → sensors → dual plan → write**. Validate with ark-check; never weaken the gate.
**Team lock:** do not edit `ark.config.json`, `arkrules/*`, or `.ark-baseline.json` in this
turn unless the user invoked a steward contract session. Feature diffs use
`ark-check --changed --base <merge-ref>`. Growing the baseline is steward-only.

**Not a plan grinder.** Empty `--plan` does **not** mean “architecture is healthy” without
the explore pass and dual-plan section B (pattern / Shape bets).

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

**Guided vibe path:** phase 0 = doctor + compass residual. Shape: one refactor this turn (invoke = OK). Never script “done” while residual lenses remain.

## When / not when

| Use `/ark-autopilot` when… | Do **not** use it when… |
|----------------------------|-------------------------|
| “Make architecture sound” end-to-end | Map only, no apply → `/ark-explore` |
| Brownfield or greenfield with apply | Session 0 / config lying → `/ark-adopt` first, then return |
| User wants A + B planned and **applied** | New file only → `/ark-place` |
| **Apply** leftover design (one Shape refactor) | User said map only |
| Extra skip cluster (`ARKRUN_*` / `ARKORDER_*`) after extra is on | Extra off → `/ark-adopt` (advisory); evaluate one bus → `/ark-runtime` |
| Spaghetti under ENFORCE: Shape work (invoke = apply one pilot) | — |

**Post-green door:** `/ark-explore` shape-focus → dual-plan B, **then this skill applies one
pilot**. Prefer that order when `postGreenPath` / leftover design work is the primary residual.

## Related onboarding

- **Greenfield:** `/ark-adopt` or `ark-check --recommend` / `ark start`.
- **Brownfield:** `/ark-adopt` — match config to reality; do not force a starter preset.
- **Deep map only:** `/ark-explore` — full recon / dual-plan seed without applying.
- **Adoption fitness only:** `/ark-coverage` — governed% + capability gaps (not pattern dual-plan).
- **Default path:** `ark start` → `ark-check --doctor` → **`/ark-autopilot`** (this skill) for guided work.

## Dual engine (mandatory)

| Engine | Role |
|--------|------|
| **Deterministic** | `ark-check` plan/coverage/doctor, mechanical-safe kinds, write/CI gates, exit codes, origin snapshot |
| **Exploratory** | You map **this** product’s real tree: entry points, coupling, false greens, field path, pattern debt |

**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without a
decision-grade explore pass **and** without opening violating files.

**Required:**
1. **Explore pass** (below) **before** claiming a loop strategy — same bar as `/ark-explore`, budgeted.
2. CLI sensors: `--plan --json`, `--coverage --json` / `--doctor` as needed.
3. **Dual plan** always emitted (sections A and B).
4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
5. **“How to fix”** for each A cluster and each B pattern bet.
6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
7. **One-pilot loop for B:** when leftover design / design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
   → apply **only** that pilot **in this turn** → **re-doctor**. Never multi-pilot batch B; residual
   outside the pilot may remain and must not be called “healthy finished.”
8. **Reshape decision memory:** read `doctor.physicalCohesion.reshapeDecisions` before acting on
   mirror facts. Outcome first: a current rejected/deferred verdict means “intentional/deferred
   layout — no pilot”; never reconstruct that dead card from `findings`. When the user accepts,
   defers, or rejects a live card, persist its exact `decisionTarget` with a non-empty reason and
   optional `reviewBy` in `.ark/reshape-decisions.json`; never infer a verdict from golden prose.



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