arkgate 4.6.0 → 4.6.2

package/templates/agent-skills/ark-upgrade/SKILL.md

@@ -5,13 +5,25 @@ description: Upgrade ArkGate through a content-identity preview, preserve custom
 
 # /ark-upgrade — managed ArkGate upgrade
 
-Upgrade the published `arkgate` package and its managed gates without treating a
-filename, package version, or similar-looking file as proof of ownership. The
-preview is the source of truth: inspect it before applying anything.
+**When:** bump the published `arkgate` package and refresh managed gates.
+**Not when:** session 0 (`/ark-adopt`) or leftover design (`/ark-explore`).
 
-For greenfield onboarding, start with `/ark-architect` (or
-`ark-check --recommend`); for a brownfield repository, use `/ark-adopt` before
-this upgrade flow.
+## Steps
+
+1. Preview: `arkgate upgrade` (no writes).
+2. Apply in this turn: `arkgate upgrade --apply` (needs `--plan-digest` when applying managed files).
+3. Re-run `arkgate-check --doctor`. Customized files stay unless you pass `--accept-conflicts` / `--refresh-skills`.
+
+The preview is the source of truth. Do not treat a filename or package version as proof of ownership.
+
+## Autonomy contract
+
+Invoking this skill **is** the approval. Preview, then `--apply` **in this turn**.
+Stopping at preview is incomplete unless the probe failed or a conflict needs
+`--accept-conflicts` / `--refresh-skills` consent.
+
+For session 0, start with `/ark-adopt` (or `ark-check --recommend`); brownfield
+honesty is `/ark-adopt` before this upgrade flow.
 
 ## Improvement compass (process preflight)
 
@@ -99,7 +111,7 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column 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-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+4. After upgrade, leftover architecture work is **`/ark-autopilot`** (never invent `mechanical-safe`).
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
 
 
@@ -241,9 +253,8 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
    `doctor.deepModuleCoach` honesty. Run `npx arkgate agents-md --check` and
    `npx arkgate status --json`. If MCP was used, restart MCP after package bump and re-bind
    identity. Treat provider-unavailable CI required-check evidence as `unverified`, never as proof
-   that merges are blocked. If new violations appear, hand off to `/ark-fix` for a small set or
-   `/ark-loop` / `/ark-autopilot` for residual debt; do not regenerate a baseline without explicit
-   approval.
+   that merges are blocked.    If new violations appear, hand off to `/ark-autopilot`; do not regenerate a baseline without
+   explicit approval.
 
 ## Active host vs deferred hosts
 

package/templates/skills/ark-adopt.md

@@ -1,15 +1,51 @@
 ---
 name: ark-adopt
-description: Brownfield onboarding — match contract to real product code, classify ungoverned dirs, mine business rules, freeze only real debt, seed Shape dual-plan B for spaghetti residual. Deep source analysis required.
+description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield honesty. Write ark.config, optional advisory ArkRules, baseline, and gates in this turn. CLI validates.
 ---
 
-# /ark-adopt — Bring Ark into an existing codebase
+# /ark-adopt — Mark the path (session 0)
 
-Goal: contract reflects **product reality**, most code governed, only genuine debt frozen
-with a burn-down. A green check over a wrong contract is a **false green**.
+**When:** empty tree, or the architecture config 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`.
+
+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 “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+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)
@@ -47,10 +83,10 @@ When present, prefer the consumer **domain glossary** for layer names, slice fol
 
 | Use `/ark-adopt` when… | Do **not** use it when… |
 |------------------------|-------------------------|
-| Existing messy repo; contract ≠ folders | Empty greenfield shape → `/ark-architect` |
-| False-green / concentrated edge needs contract truth | Map-only without writing config/baseline → `/ark-explore` |
-| Mine loose business rules into Domain / intents | Single violation fix → `/ark-fix` |
-| Freeze **real** debt after contract is honest | Grind plan A only → `/ark-loop`; full apply loop → `/ark-autopilot` |
+| 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 / advisory ArkRules | Apply leftover design after the path is honest → `/ark-autopilot` |
+| Freeze **real** debt after the config is honest | User said map only |
 
 ## Dual engine (mandatory)
 
@@ -83,13 +119,13 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column 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-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+4. Editing `arkrules/*` or promoting modes is **this skill** (session 0) or **`/ark-autopilot`** later; never invent `mechanical-safe`.
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
 
 
 ### Adopt + ArkRules
 - After classify: emit or refresh `arkRules` for matched layers (exact names; generic mold for unknowns).
-- Mine rules → inventory + propose invariants/structure; land via `/ark-contract`.
+- Mine rules → inventory + write advisory invariants/structure into `arkrules/<Layer>.json` **in this turn**.
 - Freeze baseline is **[Layer]** debt; inventory residual is **[ArkRules]** — report both.
 
 ## Subagent fan-out (optional, host-dependent)
@@ -111,10 +147,10 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 
 ## Related onboarding
 
-- **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
-- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Greenfield:** this skill + `ark-check --recommend` / `ark start` — write the scaffold here.
+- **Brownfield:** this skill — match config to reality; do not force a starter preset.
 - **Deep map only:** `/ark-explore`.
-- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+- **Default path:** `ark start` → **`/ark-adopt`** → `/ark-place` / `/ark-autopilot`.
 
 ## Anti-wrapper rule (mandatory)
 
@@ -125,7 +161,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 2. **Product map** — what ships, which apps/packages, entry routes/CLIs.
 3. **Read real source** in largest ungoverned dirs and top import edges (min **12 files**
    across **≥4 dirs**).
-4. **“Así te lo re-soluciono”** — concrete layer globs, file moves, manifest/intent proposals.
+4. **“How to fix”** — concrete layer globs, file moves, manifest/intent proposals.
 5. **Suggestive burn-down** — ranked next steps after adopt (not only “baseline done”).
 6. Never freeze a concentrated edge without investigating contract smell / false-green.
 
@@ -143,19 +179,19 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    **ApplicationOrchestration**, not Presentation — do not reclassify API shells as UI.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
    Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
-   If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge: invoke /ark-contract with source evidence** (do not freeze a wrong contract or grind N freezes).
+   If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge:** rewrite `ark.config.json` **in this turn** with source evidence (do not freeze a wrong config or grind N freezes).
    Empty Domain/Persistence + I/O under Application → false-green.
-   **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
+   **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the config **in this turn** before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
 3. **Classify ungoverned** — use coverage `suggestions` **plus** dirs you discovered by reading;
-   add layers/patterns via `/ark-contract`.
+   add layers/patterns **here** (write `ark.config.json`).
 4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
    - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
    - **ArkRules inventory (AR13):** run `ark-check --rules-inventory --json` for deterministic candidates
      (validation-in-controller, magic constants, anemic entities). Counts are **not a score**.
    - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
-     land structure/invariant entries under `arkrules/<Layer>.json` via `/ark-contract` (ADR 0015 routing).
-   - Apply config through `/ark-contract` discipline; move pure rules into Domain when safe; validate with ark-check.
-   - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
+     land structure/invariant entries under `arkrules/<Layer>.json` **in this turn** (ADR 0015 routing).
+   - Write the config; move pure rules into Domain when safe; validate with ark-check.
+   - Deliver section **How to fix the architecture config** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
 6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
 7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
@@ -164,13 +200,13 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
      domain logic in UI, or semantic false-green: emit **dual-plan B** (3–5 bets) with pilot,
      success signal, kill-switch, and extraction cards for I/O moves — same bar as `/ark-explore` §G.
    - Do **not** claim “adopt complete / healthy” solely because the check is green.
-   - Prefer handoff `/ark-autopilot` for B execution with user ok, or `/ark-explore` shape-focus
+   - Prefer handoff `/ark-autopilot` to apply one Shape refactor, or `/ark-explore` shape-focus
      if the user only wanted a plan.
 
 ## Operating modes
 
 Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
-**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
+**Guard on the contract ≠ Shape done.** Say leftover design work remains when B residual remains.
 
 ## Verify
 

package/templates/skills/ark-architect.md

@@ -1,43 +1,24 @@
 ---
 name: ark-architect
-description: Choose the application shape, adopt phase-1 layers, scaffold directories, and verify honestly — for enthusiasts before codegen. Autonomous.
+description: Shortcut to /ark-adopt for greenfield shape. Deprecated as a first-class door. Do adopt’s job.
 ---
 
-# /ark-architect — Choose your application shape and adopt Ark
+# /ark-architect — Shortcut to /ark-adopt
 
-## Improvement compass (process preflight)
+**Not a first-run door.** This leftover name is a shortcut. Session 0 is **`/ark-adopt`**.
+Do that job now. Do not send the user to `/ark-contract` or `/ark-fix`.
 
-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.
+## Autonomy contract
 
-**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.
-
-**Greenfield that is AI-easy day one:** golden norm + thin layers so the next agent turn stays ordered.
+Invoking this skill **is** the approval to mark the path. Write `ark.config.json` and
+phase-1 dirs in this turn. Then `ark-check`.
 
 ## When / not when
 
-| Use `/ark-architect` when… | Do **not** use it when… |
-|----------------------------|-------------------------|
-| Greenfield / thin tree; pick shape + phase-1 layers | Existing spaghetti brownfield → `/ark-adopt` (+ `/ark-explore` first if map missing) |
-| Enthusiast before heavy codegen | Enforcement residual on mature tree → `/ark-autopilot` |
-
-The user is building something new or early in Ark adoption. They may not know
-layered architecture jargon. Your job: translate **what they want to build**
-(application shape, not framework name) into an Ark preset, a phase-1 layer plan,
-conventional directories, and a passing honest check — without weakening the gate.
-
-Commands below are written as `ark-check` / `ark`; run each through the project's
-package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
+| Use this leftover name when… | Prefer instead |
+|------------------------------|----------------|
+| Muscle memory / old docs say architect | **`/ark-adopt`** (greenfield + brownfield) |
+| Empty tree needs a shape | Same — adopt writes the recommend result |
 
 ## Dual engine (mandatory)
 
@@ -48,8 +29,6 @@ package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
 
 The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
-
-
 ## MCP workspace binding (mandatory)
 
 Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
@@ -59,128 +38,31 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
 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 + ArkRules (mandatory, except /ark-runtime)
-
-ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
-
-| 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` |
-
-**Rules for every report / answer:**
-1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column 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-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
-5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+Then call **`ark_recommend`** with the same bound `project` envelope (or `ark-check --recommend`).
 
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
-### Architect + ArkRules
-- Preset/init should emit lean `arkRules` + templates for phase-1 layers (exact names).
-- Explain to the user: layers = boundaries; arkrules = habits inside Domain/App/adapters (opt-in, start advisory).
+Label findings **`[Layer]`** vs **`[ArkRules]`**. Absence of `arkRules` is valid.
 
 ## Subagent fan-out (optional, host-dependent)
 
-If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
-dirs to sample), fan out read-only scouts; otherwise **fall back to sequential**.
-Parent merges and still emits the **### Completion** contract. Never parallel-write
-the same files or weaken the gate.
+If the host supports **parallel subagents**, fan out read-only scouts; otherwise
+**fall back to sequential**. Never weaken the gate.
 
-## Relationship to other skills
+## Related onboarding
 
-| Skill | When |
-|-------|------|
-| **/ark-architect** | **Before** — greenfield or fresh config; pick shape + phase 1 |
-| /ark-adopt | **After** — messy existing repo |
-| /ark-contract | **During** — evolve config safely |
-| /ark-place | **During** — one new file |
-| /ark-explain | **After** — understand what exists |
+- **Greenfield:** this shortcut → **`/ark-adopt`** + `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt` — do not force a starter preset.
 
 ## Steps
 
-1. **Bind and detect the shape** — complete the mandatory `ark_identity` preflight first, then
-   call MCP tool **`ark_recommend`** with the bound `project` envelope (or run the workspace-local
-   `ark-check --recommend --json`). Never use an unverified recommendation. Read `archetype`, `preset`, `confidence`,
-   `adoptInOrder.phase1`, `analogy`, `why`, `evidence`, and `requiresConfirmation`.
-   Ask at most **two** questions only if `requiresConfirmation` is true (or for compatibility
-   with older ArkGate output, `confidence < 0.5`):
-   - "Will this app save data between sessions?"
-   - "Is this one app or several in one repository?"
-
-2. **Present in plain English** — name the application shape (e.g. "product with
-   UI and stored data"), not the framework. One analogy. List **phase-1 layers only**.
-
-3. **Map to Ark** — if `ark.config.json` is missing, run
-   `ark init --archetype <archetype> --yes` (maps playbook id → preset + gates),
-   or `ark-check --apply-policy-pack enthusiast-<preset>` for the enthusiast variant.
-   Optional team record: `ark-check --recommend --write-plan` → `ark-adoption-plan.json`.
-   If a config already exists, use `/ark-contract` to align it — do not regenerate
-   unasked. On a messy brownfield tree: **STOP — do not continue this skill as complete.** Invoke **/ark-adopt** instead of forcing greenfield shape.
-
-4. **Scaffold phase 1** — create conventional directories from the preset/playbook
-   (`src/domain`, `src/application`, …). Add a one-line README per folder explaining
-   what belongs there. Match the nearest sibling file style if code already exists.
-   Flat layouts (`src/` + `lib/` + `api/` at the repo root) are common in Vite and
-   serverless projects — use `/ark-contract` to map them to layers instead of forcing
-   everything under `src/**/domain/**` only.
-
-5. **Install gates** when the user uses AI coding tools and gates are missing:
-   `ark-check --install-agent-gates`.
-
-6. **Verify honestly** — run `ark-check --doctor` and `ark-check --coverage --json`.
-   Report `governed.percent`. Say explicitly what is **not** governed yet
-   (ungoverned directories, empty layers).
-
-7. **Deliver to the user**
-   - ASCII diagram (≤3 boxes for phase 1, inner → outer)
-   - Table: "when you build X, put it in Y"
-   - Three rules the agent must not break (no domain→database imports, no raw
-     `publish()`, no weakening `ark.config.json` to pass)
-   - Optional book refs from `books` in the recommendation JSON under "go deeper"
-   - **Gallery starter** — point the user at the matching clonable example:
-
-     | Archetype | Example directory |
-     |-----------|-------------------|
-     | `crud-product` | `examples/crud-product-starter/` |
-     | `api-backend` | `examples/api-backend-starter/` |
-     | `worker-pipeline` | `examples/worker-pipeline-starter/` |
-     | `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
-     | `vertical-slice-product` | `examples/vertical-slice-starter/` |
-     | `ddd-bounded-contexts` | `examples/ddd-context-starter/` |
-
-     Say they can copy that folder as a baseline (`npm install && npm run check`).
-     For a runnable API with break exercises, mention `examples/hexagonal-order-api/`.
-     Full enthusiast track: `docs/enthusiast/README.md`.
-
-## Operating rules
-
-- Never weaken `ark.config.json`, the baseline, CI, or agent settings to pass.
-- Never invent layers outside the 11-layer profile or named presets
-  (`hexagonal`, `layered`, `feature-sliced`, `monorepo`, `ui-surface`,
-  `vertical-slice`, `ddd-bounded-contexts`).
-- Flag unrecognized dirs (`utils/`, `lib/`) — user must classify via `/ark-contract`.
-- Default to smallest viable phase 1; unlock phase 2 only when the user describes need.
-- All user-facing copy is **English**.
-
-## Merge cards (physical cohesion reshape — judgment only)
-
-When `doctor.physicalCohesion` reports a mirrored concept and the user asks whether files
-should be **merged**, treat it as domain modeling, never deduplication (field fact: zero
-structural clones among 123 same-concept files). Produce a **merge card** per candidate group:
-which files, the domain concept they express, 2–3 shapes the merged module could take, and what
-each shape costs — **no default action, no auto-merge, never a codemod**. Physical **moves**
-belong to `/ark-loop`'s pilot loop; your job here is the judgment about what the concept IS.
-
-## Verify and report
-
-End with `ark-check --root . --config ark.config.json --strict-config` when the
-tree is ready. Report: archetype + preset, directories created, governed %, and
-the next command if anything remains ungoverned.
+1. Bind MCP (`ark_identity` then `ark_recommend`) or run `ark-check --recommend`.
+2. Execute **`/ark-adopt`** autonomy: write the config, dirs, optional advisory ArkRules, gates.
+3. `ark-check --strict-config`. Handoff `/ark-place` for new files.
 
 ## Completion contract (skill incomplete if missing)
 
-End with **exactly** these headings (markdown `###`):
+Skill incomplete if missing any field below.
 
 ### Completion
 - **Sensor:** commands/tools run
@@ -188,8 +70,5 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
-- **Handoff:** `/ark-…` / CLI / `none`
+- **Handoff:** `/ark-adopt` / `/ark-place` / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
-
-If a **STOP** handoff applies and you continued as if done, set **Incomplete?** to `yes`.
-**Skill incomplete if missing** any of the bullets above.

package/templates/skills/ark-autopilot.md

@@ -1,17 +1,34 @@
 ---
 name: ark-autopilot
-description: Guided end-to-end path for layers and opt-in ArkRules — doctor next action when unsure. Explore first; dual plan A (edges) + B (shape); mechanical-safe only by default; B with user OK, one pilot at a time. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
+description: Apply Ark end-to-end — explore first; dual plan A (edges) + B (shape); write mechanical-safe and judgment in this turn; one Shape refactor. Empty plan A is not healthy if leftover design remains. CLI is a sensor; you edit files.
 ---
 
-# /ark-autopilot — Guided end-to-end architecture path
+# /ark-autopilot — Apply the path
 
-**This is the full guided co-pilot** after the compact router. Prefer it when the user wants
-architecture cleaned end-to-end, not when they only need a map (`/ark-explore`) or a single
-edge fix (`/ark-fix`). Doctor remains the control plane: re-check status after each major step.
+**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`).
 
-Composes **explore → sensors → dual plan → loop**. Safe default: auto-apply only
-`mechanical-safe`; when the user says full apply / apply everything, also execute **judgment**
-fixes you design from reading source (still validate with ark-check, never weaken the gate).
+## 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. Doctor remains the control plane.
+
+## 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).
@@ -33,25 +50,25 @@ 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 only with user OK. Never script “done” while residual lenses remain.
+**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 | Only fitness numbers → `/ark-coverage` |
-| User wants A + B planned and A executed | Single edge fix → `/ark-fix`; plan A only → `/ark-loop` |
-| **Apply half of post-green Shape path** (after explore map / when user wants full apply) | Skipping explore when doctor primary is Shape map-first |
-| Spaghetti under ENFORCE: Shape work with user ok on B | Contract false-green first → `/ark-adopt` / `/ark-contract` STOP paths |
+| 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 |
+| Spaghetti under ENFORCE: Shape work (invoke = apply one pilot) | — |
 
-**Post-green door:** doctor’s single door is `/ark-explore` shape-focus → dual-plan B, **then** this skill only
-to apply B with OK. Prefer that order when `postGreenPath` / design-weak is the primary residual.
+**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-architect` or `ark-check --recommend` / `ark start`.
-- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **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.
@@ -71,10 +88,10 @@ decision-grade explore pass **and** without opening violating files.
 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. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
+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 design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
-   → apply **only** that pilot with user OK → **re-doctor**. Never multi-pilot batch B; residual
+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
@@ -106,7 +123,7 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column 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-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+4. Editing `arkrules/*` or promoting modes and fixing structure sensors is **this skill** (judgment, never invent `mechanical-safe`).
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
 
 
@@ -143,14 +160,14 @@ Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot rep
 Include explore **§G** when spaghetti / design-weak signals fire.
 
 1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
-   **ENFORCE·design-weak** risk).
+   leftover design work risk).
 2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
 3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
 4. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a` + internal norm.
 5. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
 6. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
 7. **False-green soft block** — doctor/coverage: empty Domain/Persistence while Application owns I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …). Doctor gap id: `contract-false-green-io-under-application`. If so:
-   **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
+   **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the architecture config **in this turn** (same job as `/ark-adopt`) before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
 8. **Seed dual plan B** — 2–5 pattern / Shape bets ranked (impact × effort × enforceability). Each B row needs pilot + success signal; I/O bets need an **extraction card** (explore §G).
 
 Min bar: **≥12 source files** across **≥4 meaningful directories** (not only files in `steps[]`).  
@@ -160,16 +177,16 @@ Standalone long report: `/ark-explore`. Adoption fitness only: `/ark-coverage`.
 
 | Section | Source | Question | Auto-apply? |
 |---------|--------|----------|-------------|
-| **A. Remediation** | `--plan --json` + opened step files | What must change so the **gate** is honest? | Only `mechanical-safe` by default |
+| **A. Remediation** | `--plan --json` + opened step files | What must change so the **gate** is honest? | Write `mechanical-safe` **and** judgment |
 | **B. Pattern / Shape** | Explore §B/§G (not coverage alone) | What **design** must improve even if A is empty? | **Never** as mechanical-safe |
 
 **Section A** — group by edge; treat `peerIsolation` / cross-slice as **judgment**.  
 **Section B** examples: choose golden pattern + pilot migrate-on-touch, peerIsolation, move rules out of UI, write-path repair, split god modules, Domain placement / intents, facade SQL → port/adapter (extraction card). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + **success signal** + **pilot** (+ kill-switch if new layer).
 
-B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.  
+B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied`.  
 When A is empty and B is non-empty: status is **`goal.met on edges · Shape residual open`** — never “done” without listing B.
-Prefer CLI `patternBets[]` / `designSmells[]` when present; apply B only with explicit user ok using
-**extraction cards** (`docs/brownfield-adoption.md` §6) — never mechanical-safe, never silent.
+Prefer CLI `patternBets[]` / `designSmells[]` when present; apply **one** B pilot this turn using
+**extraction cards** (`docs/brownfield-adoption.md` §6) — never mechanical-safe, never silent, never multi-pilot.
 If B will take multiple PRs, offer (do not require) persisting a short Shape plan under the
 repo so the next agent session continues the same pilot — still never auto-apply B.
 
@@ -190,7 +207,7 @@ Status lights from doctor — not settings you choose. Rank residual honestly:
 | **Suggest** | Thin/new tree; contract not control plane | Finish `ark start` → re-doctor; do not skill-shop |
 | **Adapt** | Contract/tree disagree or debt open | Explore + adopt/loop/contract; do not claim guarded |
 | **Enforce** | Honest coverage + clean checked **edges** | Confirm gates + CI; emit dual-plan B only if residual found |
-| **Enforce · leftover design work** | Imports clean; design still messy | **Primary Shape door:** explore shape-focus → dual-plan **B** → apply **one** small refactor with user OK. Empty plan A ≠ done. Never mechanical-safe B. False-done forbidden. |
+| **Enforce · leftover design work** | Imports clean; design still messy | **Primary Shape door:** explore shape-focus → dual-plan **B** → apply **one** small refactor. Empty plan A ≠ done. Never mechanical-safe B. False-done forbidden. |
 
 - **Setup (Suggest):** no config → `ark start` (start freezes origin after config, before gates).
 - **Align (Adapt):** open debt, low honesty, or false-green → explore + adopt/loop; do not claim “guarded”.
@@ -206,12 +223,12 @@ Status lights from doctor — not settings you choose. Rank residual honestly:
 3. **Sensors** — `--plan --json`, doctor/coverage as needed.
 4. **Emit dual plan** — A from plan steps (files opened); B from explore (3–5 bets).
 5. **Concentrated edge?** — if one edge dominates A:
-   **STOP — do not continue this skill as complete.** **STOP — concentrated edge: invoke /ark-contract with source evidence** (do not freeze a wrong contract or grind N freezes).
+   **STOP — do not continue this skill as complete.** **STOP — concentrated edge:** rewrite `ark.config.json` **in this turn** with source evidence (do not freeze a wrong config or grind N freezes).
 6. **Worktree preferred** — discardable git worktree when possible.
 7. **Mechanical-safe (A only)** — kinds from `/ark-loop` table; one step, validate, rollback.
-8. **Judgment (A)** — default: propose with full “así te lo re-soluciono”. If user authorized full apply: implement, validate, rollback on fail.
-9. **Pattern bets (B)** — propose; apply only with explicit user go + correct skill (`/ark-contract`, refactor, install gates, etc.). Never weaken the gate to clear B.
-10. **Manifiesto** — loose business rules → Domain placement + `intentPrefixes` / intents via `/ark-contract` discipline.
+8. **Judgment (A)** — implement with full “así te lo re-soluciono”; validate; rollback on fail.
+9. **Pattern bets (B)** — apply **one** extraction-card pilot this turn; leave the rest queued. Never weaken the gate to clear B.
+10. **Manifiesto** — loose business rules → Domain placement + `intentPrefixes` / intents; write config here if the path is still dishonest.
 11. **Final report** — re-`--report`; evolution vs origin; A applied vs open; B proposed/deferred; gates on.
 12. **Strict check** — `ark-check --strict-config` (dead preset globs are advisory; real violations still fail).
 13. **Core ratchet (when green)** — if plan `goal.met` and doctor still **ADAPT** only because