ark-adopt

# /ark-adopt — Mark the path (session 0)

**When:** empty tree, or the rules file does not match the real folders (session 0).
**Not when:** a single new file (`/ark-place`) or leftover design after the path is honest (`/ark-explore` then `/ark-autopilot`).

## Steps

1. Read `arkgate-check --doctor` (one light, one next action).
2. Write `ark.config.json` (and a baseline only for genuine debt) in this turn.
3. Re-run doctor. Day-to-day new files: `/ark-place`.

## Checklist

- Existing tree: propose **SharedKernel** (types/constants) + **CompositionRoot** (wiring) + `src/**/domain/**`. Never dump bare `src/lib/**` into Application.
- Generate `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
- Future houses: mark unused layer globs `reserved` / `allowEmpty` so `--strict-config` does not fail.
- When the product map or glossary names a house, write `layers[].description` as
  app-context copy (what this folder is *in the product*). Compact starter may omit.
  Do not invent captions. Do not invent `/ark-describe`.
- CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
- Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
  **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).
  Absence is silent and valid. Compact starter stays extras-off. Skills never enforce.

Invoking this skill **is** the approval. Write the architecture config in this turn.
Greenfield: scaffold like `--recommend`. Brownfield: match **product
reality**, freeze only genuine debt. A green check over a wrong config is a **false green**.

## Autonomy contract

The CLI is a **sensor and gate**, never the deliverable. **CLI budget:** one
`ark-check --recommend` or `--coverage` / `--doctor`; then write; then `ark-check`.
Forbidden as the result: preview-only adopt, “approve?”, or `STOP — invoke /ark-architect`
/ `/ark-contract`. Do that work **here**.

**Still never:** weaken `ark.config.json`; invent `mechanical-safe` kinds; claim finished
while leftover design work remains.

**Team lock:** this door **is** a contract session (law-only). Do not mix product source
into the same diff. After writes, validate with
`ark-check --contract-diff --contract-session --base <merge-ref> --author <steward>`.
If `stewards` is set, loosen and baseline-grow require a listed author. Feature work
uses `/ark-place` / `/ark-autopilot` and must not touch the constitution.

**Several hands → ask for stewards.** Read `doctor.stewardNudge` (or the human
**Stewards (advisory)** line). Act when `needsStewards` **or** `drift` is true.
**Ask once** before writing `stewards[]`. Identity is a **GitHub handle or email**
(`pedroknigge` or the GitHub noreply mail), not git `user.name`. Empty list: use
`proposed` (CODEOWNERS first, else git handles/emails; bots and display names stripped).
Drift: CODEOWNERS handles in `missingFromList`, or “team grew” (author count > steward
count) — ask who else owns the law. If the user says yes or names handles or emails,
write them in this turn. If they say the list is still right, leave it. Never invent
or auto-remove stewards.

**Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
spaghetti leftover design work. Always end with dual-plan **B** seeds (or handoff explore)
when design smells remain after the contract is honest.

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

**Spaghetti → honest contract.** SoC/DIP false-green STOP paths in plain language; residual lenses stay Incomplete until mapped.

## Domain glossary (process)

When present, prefer the consumer **domain glossary** for layer names, slice folders, intent names, and pilot wording:

| Detect (no requirement) |
|-------------------------|
| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |

- Prefer glossary terms over inventing parallel vocabulary.
- Call out conflicts between glossary language and code reality (process judgment).
- **Missing glossary is normal** — continue without warning spam. Never treat glossary prose as enforcement.
- When the glossary (or product map) names a house, that name is the `layers[].description` source — write it; do not invent a parallel caption.

## Layer captions (process)

When the **product map** (anti-wrapper) or **glossary** names a house, write
`layers[].description` on that layer in this turn. One sentence of **app context**
(what this folder is *in the product* — e.g. "Purchase requests — from asked to
received."), not architecture jargon. Compact starter / `ark start` may omit the
field. Absence is silent — never fail `--strict-config` for a missing caption.
Do **not** invent captions. Do not invent `/ark-describe`.

## When / not when

| Use `/ark-adopt` when… | Do **not** use it when… |
|------------------------|-------------------------|
| Session 0: empty tree or existing repo needs an honest path | Map-only without writing config → `/ark-explore` |
| False-green / concentrated edge needs config truth | Feature file only → `/ark-place` |
| Mine loose business rules into Domain / a