arkgate 4.8.13 → 4.8.14

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

@@ -0,0 +1,200 @@
+---
+name: ark-order
+description: Wire the optional ArkOrder extra (arkgate/order). One candidate. Extra on via /ark-adopt.
+---
+
+# /ark-order — Evaluate and wire ArkOrder (optional)
+
+**Contener · Guiar · Ordenar.** In plain words: contain the write, guide the next
+step, order leftover mess. This door is **Ordenar**: the extra for the few big product
+choices (billing plan, not seat counts). Ordering leftover folders is `/ark-explore`
+then `/ark-autopilot`. Skills never enforce — CLI / hooks / CI do.
+
+Layers stop a bad import. ArkOrder stops rewriting a big product choice as if it
+were a seat count. Change those choices through a valve, not a generic update.
+
+The ArkOrder extra (`arkgate/order`) is **optional**. It is **not** required for
+ArkGate enforcement and is **not** production durability. Use this skill when the
+user wants to evaluate or wire the extra. **This skill never enforces.** Do **not**
+invent `/ark-run`. `@arkgate/order` is not a package — import `arkgate/order` from
+the same `arkgate` tarball.
+
+**When:** evaluate a hand-rolled “PATCH the plan like a seat count” / generic update
+of a slow product choice, or wire an extra that is already on (plane root, named
+keys, valve).
+**Not when:** session 0 / extra not chosen (`/ark-adopt`); one new file (`/ark-place`);
+skip-violation grind (`/ark-autopilot`); wire the runtime kernel (`/ark-runtime`).
+
+## When / not when
+
+| Use `/ark-order` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| Wire one ArkOrder candidate after the extra is on | Extra not chosen → `/ark-adopt` |
+| Evaluate a generic update of a named product choice | New plane-root file only → `/ark-place` |
+| Valve: first `release()`, later `proposeRelease` then `apply` | Skip cluster grind → `/ark-autopilot`; one kernel candidate → `/ark-runtime` |
+
+## Contener · Guiar · Ordenar
+
+| Star | This door | Hand off |
+|------|-----------|----------|
+| **Contener** | `/ark-adopt` path · `/ark-place` new file · `/ark-upgrade` pin | Map → `/ark-explore` · apply → `/ark-autopilot` |
+| **Guiar** | `/ark-explore` map · `/ark-autopilot` apply · `/ark-runtime` wire ArkRun · `/ark-explain` tour · `/ark-coverage` fitness | Session 0 → `/ark-adopt` · this door for the big-choice plane |
+| **Ordenar** | **This skill** — wire ArkOrder | Extra off → `/ark-adopt` · new plane-root file → `/ark-place` · skip grind → `/ark-autopilot` |
+
+**Handoff, do not invent a door.** Extra off → `/ark-adopt`. New file → `/ark-place`.
+Skip cluster → `/ark-autopilot`. One kernel candidate → `/ark-runtime`.
+
+## Extra vs plane (mandatory)
+
+| Piece | What it is | What it is not |
+|-------|------------|----------------|
+| **ArkOrder extra** (`arkOrder` on `ark.config.json`, schema `1.3+`) | Gate contract: plane usage + named slow keys | A score; Layers / ArkRules / ArkRun replacement; merge teeth while `advisory` |
+| **Plane** `arkgate/order` | Library you construct with `createOrderPlane` (one instance per call) | A process-wide singleton; a second npm package; production durability |
+
+Absence of the extra is **silent** — Layers and ArkRules verdicts stay identical. Doctor / status
+`arkOrder` is always `notAScore`. Never invent 0–10 scores or pass/fail from this skill.
+
+## Improvement compass note
+
+This skill is **optional order-plane** only. Do **not** treat ArkOrder adoption as residual on
+the resilience lens unless the user explicitly opts into the extra. Prefer doctor compass
+for static architecture residual; hand static residual to `/ark-explore` / `/ark-autopilot`.
+Doctor `arkOrder` residual is a finding-id count (`ARKORDER_*`), never a compass score.
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | CLI / MCP / contract sensors — exit codes, plan kinds, coverage numbers, install status |
+| **Exploratory** | You open **this** repo's real files and product surface before concluding |
+
+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
+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.
+
+## Out of scope for ArkRules and ArkRun
+
+This skill is **order-plane only**. Do not mix ArkRules structure/invariants here; do **not**
+turn this skill into an ArkRun skill. Hand off first extras to `/ark-adopt`, new files to
+`/ark-place`, skip clusters to `/ark-autopilot`, one kernel candidate to `/ark-runtime`.
+Label plane residual **`[ArkOrder]`** so it never blurs with **`[Layer]`**, **`[ArkRules]`**,
+or **`[ArkRun]`**.
+
+## 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.
+
+## Steps
+
+1. **Inventory** — grep the codebase for hand-rolled equivalents:
+   - a use-case that `update` / `patch` / `set` a slow product choice (plan, cycle, tenancy)
+     the same way it writes a seat count or invoice
+   - Prisma / pg / SQL writes of those names from Application / Features
+   - a second `release()` after the first freeze (should be `proposeRelease` then `apply`)
+   - membership ids (`projectId`, `orgId`) treated as slow keys
+   - recomputable statuses (`paid`, `overdue`, `atCapacity`, `approved`) stored as if they
+     were named choices
+   Also check whether the billing gallery pattern applies:
+   [examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing)
+   (GitHub tree, not in the npm tarball). Copy billing, **rename the three keys**.
+2. **Read the extra** — open `ark.config.json`. If `arkOrder` is absent and the user wants the extra,
+   **STOP — do not continue this skill as complete.** Handoff **`/ark-adopt`** to write **advisory**
+   `arkOrder` (schema `1.3+`; real `planeRoots`, existing `managedLayers`, `maxXiKeys` default 7,
+   **`xiKeys`** the 3–5 slow names). Do not invent the extra here. If the extra is present, note
+   `mode`, `planeRoots`, managed layers, `maxXiKeys`, and `xiKeys`; doctor `arkOrder` is `notAScore`.
+3. **Pick ONE target** — the smallest, most self-contained candidate (fewest call sites).
+   Migrating everything at once is how adoptions die. List the rest as follow-ups in the report.
+   New files after the extra is on go through **`/ark-place`**.
+4. **Resolve availability** — `npm install arkgate` already ships `arkgate/order`.
+   Import `createOrderPlane` from `arkgate/order`. Same npm package. Not a second install.
+5. **Wire through the plane** — read
+   [ArkOrder](https://github.com/pedroknigge/arkgate/blob/main/docs/arkorder.md)
+   (first-contact breath first; valve tables below the fold).
+   - Call `createOrderPlane` **only** inside `arkOrder.planeRoots`. Each call is a new instance —
+     no process-wide singleton.
+   - Keep Domain-role layers plane-free (`ARKORDER_KERNEL_IN_DOMAIN`).
+   - First freeze: `release()`. Later change of a named choice is `proposeRelease` then `apply`
+     — not a second `release()` (`ARKORDER_UNVALVED_RELEASE`), not `update` / `patch` / `set`
+     (`ARKORDER_GENERIC_UPDATE`).
+   - Name **`xiKeys`** (3–5 slow product decisions). Membership ids and recomputable statuses
+     are not keys: derive a status on read or fold it from ingest. A use-case that persists
+     those keys is `ARKORDER_XI_FIELD_WRITE`. Invoices and seats still flow through `ingest`.
+   - Before writing a name, drop the candidate and ask: can current state reconstruct it
+     uniquely? If it is recomputable or ingest determines it, derive it. The check remains
+     silent on semantic entailment.
+   - `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity
+     pack as data; in-memory `ReleaseStore` (`createMemoryReleaseStore`); `ingestTravelAction`.
+     ArkRun `decisionTape` is still **`[ArkRun]`** — do not turn the tape into this skill.
+   - In-memory stores lose state on restart — **not** production durability. Branding ArkOrder
+     is not a durability claim. Doctor / status `arkOrder` is `notAScore`.
+6. **Delete the hand-rolled generic update** once call sites are moved — the point is
+   less code, not a second parallel system. Deleting code is a destructive move:
+   confirm with the user before removing the old implementation, and never delete
+   something the inventory only *suspects* is dead.
+
+## Critical handoffs
+
+- No static gates yet: **STOP — do not continue this skill as complete.** Run `/ark-adopt` first
+  (`ark-check --recommend`).
+- Extra absent and the user wants it: **STOP — do not continue this skill as complete.**
+  **`/ark-adopt`** writes advisory `arkOrder`.
+- Skip cluster (`ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE`
+  / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE`) after
+  the extra is on: **`/ark-autopilot`** — this skill still wires one candidate.
+- New plane-root file after the extra is on: **`/ark-place`**.
+- One kernel / bus candidate: **`/ark-runtime`** — do not mix planes.
+- `arkgate` not installed and no local checkout: **STOP** and report the distribution boundary.
+- Inventory finds nothing: stop; do not introduce the plane speculatively.
+
+## Operating rules
+
+- If the inventory finds NO hand-rolled equivalents, say so and stop — do not
+  introduce ArkOrder speculatively. Static enforcement alone is a complete, valid use of Ark.
+- Keep the migration diff reviewable: one feature per invocation.
+- Skills never enforce; never weaken `ark.config.json` to skip `ARKORDER_*`.
+- Never a process-wide plane singleton. Never a second npm package.
+- Never claim in-memory stores are production-durable.
+- Never force the extra on. Compact starter / `ark start` stays extras-off.
+- Plain-language reporting: one sentence per concept ("the billing plan is a
+  named choice — change it through the valve, not a generic update").
+- ξ / Haken / slaving stay **below the fold**. First contact uses the one-minute breath.
+
+## Related onboarding
+
+- Adopt static gates and application shape **first** (`/ark-adopt` or `ark-check --recommend`).
+  Brownfield: same door — advisory extra only until the team promotes; absence is valid.
+- ArkOrder is optional and separate from enthusiast onboarding. Do not put `arkOrder` on the
+  compact starter.
+
+## Verify and report
+
+Run the project's tests plus `ark-check --root . --config ark.config.json
+--strict-config`. Report: what was migrated, lines deleted vs added, remaining
+candidates ranked, behavior differences, and **`[ArkOrder]`** residual
+(`ARKORDER_*` / doctor `arkOrder`, `notAScore`) separately from Layers / ArkRules / ArkRun.
+
+## Completion contract (skill incomplete if missing)
+
+End with **exactly** these headings (markdown `###`):
+
+### Completion
+- **Sensor:** commands/tools run
+- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
+- **Result:** one-line outcome
+- **Planes:** **`[ArkOrder]`** residual (or `n/a` if extra absent) — do not mix with `[Layer]` / `[ArkRules]` / `[ArkRun]`
+- **Compass:** `n/a` (order skill; static residual → explore/autopilot) | top residual if doctor was run
+- **Handoff:** `/ark-…` / CLI / `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/agent-skills/ark-place/SKILL.md

@@ -5,6 +5,10 @@ description: "Where does new code go? Names the folder from the rules file and w
 
 # /ark-place — Where does this code go?
 
+**Contener · Guiar · Ordenar.** In plain words: contain the write, guide the next
+step, order leftover mess. This door is **Contener**: write the new file in the
+right house. Skills never enforce — CLI / hooks / CI do.
+
 **When:** you are adding a new file or artifact and need the layer, folder, and name.
 **Not when:** session 0 / config is missing or lying (`/ark-adopt`) or an existing violation cluster (`/ark-autopilot`).
 
@@ -78,7 +82,7 @@ a caption or `/ark-describe`.
 | New artifact: where + **write** under the config | Existing violation cluster → `/ark-autopilot` |
 | Naming / directory for a known kind | Session 0 / config missing or lying → `/ark-adopt` (then come back) |
 | Kernel-managed artifact when `arkRun` is already on | Extra not chosen yet → `/ark-adopt` (advisory `arkRun`); evaluate / migrate a hand-rolled bus → `/ark-runtime` |
-| Plane-root artifact when `arkOrder` is already on | Extra not chosen yet → `/ark-adopt` (advisory `arkOrder`); skip cluster grind → `/ark-autopilot` |
+| Plane-root artifact when `arkOrder` is already on | Extra not chosen yet → `/ark-adopt` (advisory `arkOrder`); evaluate / wire one plane candidate → `/ark-order`; skip cluster grind → `/ark-autopilot` |
 
 The user describes something they need to build (a saga, a background job, an
 event handler, a repository, an HTTP client, a use case, a projection, …).
@@ -132,7 +136,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 4. Missing layer home: add it via **`/ark-adopt`** in this session if needed, then write the file; never invent `mechanical-safe`.
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
 6. Absence of `arkRun` is **valid**. Do not introduce the kernel speculatively. Skills never enforce this extra.
-7. Absence of `arkOrder` is **valid**. When on: Domain stays plane-free; first freeze ξ with `release()`; later ξ is `proposeRelease` then `apply`; never `update`/`patch`/`set` the pattern. Import `createOrderPlane` from `arkgate/order` (same npm package). No `/ark-order` skill.
+7. Absence of `arkOrder` is **valid**. When on: Domain stays plane-free; first freeze ξ with `release()`; later ξ is `proposeRelease` then `apply`; never `update`/`patch`/`set` the pattern. Import `createOrderPlane` from `arkgate/order` (same npm package). Evaluate / wire one candidate via **`/ark-order`**.
 
 
 ### Place + ArkRules
@@ -158,8 +162,8 @@ When `arkOrder` is present on the architecture config:
 - Call the factory only inside `arkOrder.planeRoots`. Empty roots in `enforced` mode is `ARKORDER_MISSING_PLANE`.
 - Named slow keys live in `arkOrder.xiKeys`. A managed-layer Prisma/pg write of those keys is `ARKORDER_XI_FIELD_WRITE` — absorb with `ingest` or change the pattern with `proposeRelease` then `apply`.
 - A recomputable status is not a new `xiKeys` entry or a `proposeRelease`: place it as a read projection or an ingest fold. If slow-key naming remains unresolved, return to `/ark-adopt` and run the elimination test before writing the config.
-- Skip clusters (`ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE`): place this artifact, then grind via `/ark-autopilot`. Extra not on → `/ark-adopt`. Do not invent `/ark-order`.
-- Absence of the extra is valid. Do not invent `/ark-order`. Skills never enforce.
+- Skip clusters (`ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE`): place this artifact, then grind via `/ark-autopilot`. Extra not on → `/ark-adopt`. Evaluate / wire one candidate → `/ark-order`.
+- Absence of the extra is valid. Skills never enforce.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -229,11 +233,10 @@ the same files or weaken the gate.
   hand off **one** pilot via `pilotLoop.nextPilot` / `/ark-explore` shape-focus — never multi-pilot
   batch reshape from this skill.
 - If `arkRun` is on and the user is grinding skip violations (`new` of managed types, homemade
-  bus) across many files: place this artifact through the kernel, then leftover `/ark-fix` /
-  `/ark-autopilot`. Extra not on → `/ark-adopt` (advisory) or `/ark-runtime` (evaluate).
+  bus) across many files: place this artifact through the kernel, then `/ark-autopilot`. Extra not on → `/ark-adopt` (advisory) or `/ark-runtime` (evaluate).
 - If `arkOrder` is on and the user is grinding skip violations (`ARKORDER_*`) across many files:
-  place this artifact on a plane root, then leftover `/ark-fix` / `/ark-autopilot`. Extra not on
-  → `/ark-adopt` (advisory). Do not invent `/ark-order`.
+  place this artifact on a plane root, then `/ark-autopilot`. Extra not on
+  → `/ark-adopt` (advisory). Evaluate / wire one candidate → `/ark-order`.
 
 ## Operating rules
 

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

@@ -5,6 +5,10 @@ description: Wire the optional ArkRun extra (arkgate/runtime). One candidate. Ex
 
 # /ark-runtime — Evaluate and wire ArkRun (experimental opt-in)
 
+**Contener · Guiar · Ordenar.** In plain words: contain the write, guide the next
+step, order leftover mess. This door is **Guiar**: wire the optional runtime so work
+keeps moving. Skills never enforce — CLI / hooks / CI do.
+
 The ArkRun kernel (`arkgate/runtime`) is currently **experimental**. It is **not** required
 for ArkGate enforcement and is **not** production durability. Use this skill when the user wants
 to evaluate or wire the kernel. **This skill never enforces** — the write / CI / ESLint plane
@@ -13,7 +17,15 @@ does when the `arkRun` extra is on. Do **not** invent `/ark-run`. `@arkgate/runt
 **When:** evaluate a hand-rolled bus / outbox / saga / projection / policy / Nest adapter against
 the kernel, or wire an extra that is already on (kernel root, declarations, transport).
 **Not when:** session 0 / extra not chosen (`/ark-adopt`); one new file (`/ark-place`); skip-violation
-grind (`/ark-autopilot` / leftover `/ark-fix`).
+grind (`/ark-autopilot`); wire the order plane (`/ark-order`).
+
+## When / not when
+
+| Use `/ark-runtime` when… | Do **not** use it when… |
+|--------------------------|-------------------------|
+| Wire one ArkRun candidate after the extra is on | Extra not chosen → `/ark-adopt` |
+| Evaluate a hand-rolled bus / outbox / saga | New kernel-managed file only → `/ark-place` |
+| Declarations / transport / Nest adapter | Skip cluster grind → `/ark-autopilot`; one order-plane candidate → `/ark-order` |
 
 ## Extra vs kernel (mandatory)
 
@@ -52,7 +64,7 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
 
 ## Out of scope for ArkRules and ArkOrder
 
-This skill is **runtime-kernel only**. Do not mix ArkRules structure/invariants here; do **not** turn this skill into an ArkOrder skill. Hand off first extras to `/ark-adopt`, new files to `/ark-place`, skip clusters to `/ark-autopilot`. Label kernel-usage residual **`[ArkRun]`** so it never blurs with **`[Layer]`**, **`[ArkRules]`**, or **`[ArkOrder]`**.
+This skill is **runtime-kernel only**. Do not mix ArkRules structure/invariants here; do **not** turn this skill into an ArkOrder skill. Hand off first extras to `/ark-adopt`, new files to `/ark-place`, skip clusters to `/ark-autopilot`, one order-plane candidate to `/ark-order`. Label kernel-usage residual **`[ArkRun]`** so it never blurs with **`[Layer]`**, **`[ArkRules]`**, or **`[ArkOrder]`**.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -119,9 +131,10 @@ the same files or weaken the gate.
 
 ## Critical handoffs
 
-- No static gates yet: **STOP — do not continue this skill as complete.** Run `/ark-adopt` first (`ark-check --recommend` / leftover `/ark-architect`).
+- No static gates yet: **STOP — do not continue this skill as complete.** Run `/ark-adopt` first (`ark-check --recommend`).
 - Extra absent and the user wants it: **STOP — do not continue this skill as complete.** **`/ark-adopt`** writes advisory `arkRun`.
-- Skip cluster (`new` of managed types, homemade bus, kernel in Domain) after the extra is on: leftover **`/ark-fix`** / **`/ark-loop`** or **`/ark-autopilot`** — this skill still wires one candidate.
+- Skip cluster (`new` of managed types, homemade bus, kernel in Domain) after the extra is on: **`/ark-autopilot`** — this skill still wires one candidate.
+- One order-plane candidate: **`/ark-order`** — do not mix planes.
 - `arkgate` not installed and no local checkout: **STOP** and report the distribution boundary.
 - Inventory finds nothing: stop; do not introduce kernel speculatively.
 

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

@@ -1,54 +1,24 @@
 ---
 name: ark-think
-description: 2–3 options for one import-rule or ArkRules decision. Not a full map (use /ark-explore).
+description: Shortcut to /ark-explore for one import-rule or ArkRules decision (2–3 options).
 ---
 
-# /ark-think — Architectural reasoning (host LLM only)
+# /ark-think — Shortcut to /ark-explore
 
-**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.
+**Not a first-class door.** One-release redirect. One bounded decision with 2–3
+enforceable options is **`/ark-explore`** (section **One decision**). Do that job now.
+Contener · Guiar · Ordenar — this leftover name is not a star.
 
 ## 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.
+| Use this leftover name when… | Prefer instead |
+|------------------------------|----------------|
+| One decision: 2–3 options already bounded | **`/ark-explore`** (one decision) |
+| Full map / ranked residual / dual-plan seed | **`/ark-explore`** (recon) |
+| Apply the chosen option | **`/ark-autopilot`** |
+| Session 0 / false-green | **`/ark-adopt`** |
+| One kernel candidate | **`/ark-runtime`** |
+| One order-plane candidate | **`/ark-order`** |
 
 ## Dual engine (mandatory)
 
@@ -57,8 +27,7 @@ If you lack a product map and the tree is messy: run a **compressed** explore pa
 | **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.
-
+The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
 ## MCP workspace binding (mandatory)
 
@@ -69,92 +38,25 @@ 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 + 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 decision, consider options on **both** planes when relevant: e.g. new layer wall **vs** structure sensor **vs** invariant catalog entry.
-- Every option must state enforceability: which plane holds it after the change.
-
-### Think + extras
-- Extra decisions stay enforceable on existing doors (`/ark-adopt` session 0, `/ark-place` new file, `/ark-autopilot` grind, `/ark-runtime` one kernel candidate). No new skill name. Do not invent `/ark-run` or `/ark-order`.
-
 ## Subagent fan-out (optional, host-dependent)
 
-When the user asks to go faster **or** the work naturally splits (multiple packages,
-feature dirs, plan clusters), you **may** dispatch **subagents**:
+If the host supports **parallel subagents**, fan out read-only scouts; otherwise
+**fall back to sequential**. Never weaken the gate.
 
-| Host capability | Behavior |
-|-----------------|----------|
-| **Parallel subagents supported** (e.g. multi-agent / `spawn_subagent` / concurrent Agent tools) | Launch **2–N** agents in **one wave** with **disjoint path scopes**. Prefer **read-only** explore agents for mapping; at most **one writer** unless the host gives isolated worktrees. Parent merges findings, then runs `ark-check` once. |
-| **Not supported** (single agent only) | **Fall back to sequential** — same checklist, one cluster/step at a time. Never claim parallel work you did not run. |
+## Related onboarding
 
-**Rules:**
-1. Give each subagent a **tight brief**: paths in scope, sensor commands allowed, deliverable shape (paths opened + findings JSON or bullets).
-2. **No shared mutable files** across parallel writers.
-3. STOP handoffs and dual-engine rules still apply in every agent.
-4. Parent owns the **### Completion** block (union of **Opened**, single **Handoff**).
-5. Do **not** use subagents to weaken the gate or invent `mechanical-safe` kinds.
+- **Greenfield:** `/ark-adopt` or `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt`.
+- **One decision:** `/ark-explore` (this leftover name redirects there).
 
 ## Steps
 
-1. **Load the contract** — `ark.config.json`; when MCP is available, call `ark_identity` with
-   the exact project root followed by `ark_manifest` with the same root plus returned project
-   id. The `ark://manifest` resource is compatibility-only and always
-   unverified/non-authoritative. Use `ark-check --coverage --json` / `--doctor` for honesty
-   about governed% and false-green.
-2. **Touch the decision surface** — README skim + **≥5 source files** on the feature/package/boundary
-   under discussion. Name paths in the answer.
-3. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,
-   ddd-bounded-contexts, feature-sliced, monorepo, …). If none, run `--recommend --json`
-   **and** say whether detection matches the tree you opened.
-4. **Name concurrent patterns** on the decision surface (if ≥2): which is **golden** vs legacy.
-5. **Reason within bounds** — propose **2–3 options** that **stay enforceable** by the gate.
-   Prefer concrete paths and import rules over abstract diagrams.
-6. **Explore alternatives** — for each option: coupling, testability, **AI-agent safety**,
-   migration cost, **pilot + kill-switch** if the option adds a layer or wall.
-7. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
-   judgment auto-apply, codemod engines, or skipping write-gate/CI.
-8. **Hand off** — placement `/ark-place`; first extra `/ark-adopt`; grind `/ark-autopilot`;
-   map-only `/ark-explore`; leftover config `/ark-contract`; leftover cluster `/ark-fix` /
-   `/ark-loop`. Extra decisions stay on those doors. Do not invent `/ark-run` or `/ark-order`.
-   When the user needs action not advice: **STOP — do not continue this skill as complete** — invoke the handoff skill.
-
-## Output format
-
-- **Context:** product + contract + what you opened (paths) + phase if known (Align/Stabilize/Shape)
-- **Options:** 2–3 alternatives with trade-offs (coupling, testability, agent safety, enforceability)
-- **Recommendation:** one option + why it is enforceable **today**
-- **Pilot / kill-switch:** if the choice changes shape or adds a layer
-- **Risks if we pick wrong:** one sentence user-visible impact
-- **Next command:** exact `ark-check` / skill to run next
-
-## Related
-
-- Greenfield shape: `/ark-architect`
-- Brownfield: `/ark-adopt`
-- Full recon / dual-plan seed: `/ark-explore`
-- Explain existing: `/ark-explain`
+1. Execute **`/ark-explore`** one-decision: open ≥5 files, name 2–3 enforceable options, recommend one.
+2. Hand off apply → `/ark-autopilot`; new file → `/ark-place`.
 
 ## Completion contract (skill incomplete if missing)
 
-End with **exactly** these headings (markdown `###`):
+Skill incomplete if missing any field below.
 
 ### Completion
 - **Sensor:** commands/tools run
@@ -162,9 +64,5 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
-- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
-- **Handoff:** `/ark-…` / CLI / `none`
+- **Handoff:** `/ark-explore` / `/ark-autopilot` / `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/agent-skills/ark-upgrade/SKILL.md

@@ -5,9 +5,20 @@ description: Upgrade ArkGate. Preview first, keep customized files, then apply.
 
 # /ark-upgrade — managed ArkGate upgrade
 
+**Contener · Guiar · Ordenar.** In plain words: contain the write, guide the next
+step, order leftover mess. This door is **Contener**: keep the pin current.
+Skills never enforce — CLI / hooks / CI do.
+
 **When:** bump the published `arkgate` package and refresh managed gates.
 **Not when:** session 0 (`/ark-adopt`) or leftover design (`/ark-explore`).
 
+## When / not when
+
+| Use `/ark-upgrade` when… | Do **not** use it when… |
+|--------------------------|-------------------------|
+| Bump the pin and refresh managed gates | Session 0 / path missing → `/ark-adopt` |
+| Preview then `--apply` in this turn | Leftover design / map → `/ark-explore`; apply Shape → `/ark-autopilot` |
+
 ## Steps
 
 1. Preview: `arkgate upgrade` (no writes). Default is **hosts keep** — do not retire other hosts’ skills.
@@ -133,7 +144,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
 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`.
-6. Schema `1.3` extras stay off unless already on. Pin teaches `arkgate/runtime` (same tarball), not the deprecated companion. Do not invent `/ark-run` or `/ark-order`.
+6. Schema `1.3` extras stay off unless already on. Pin teaches `arkgate/runtime` and `arkgate/order` (same tarball), not a second install. Wire after upgrade via `/ark-runtime` / `/ark-order`. Do not invent `/ark-run`.
 
 
 ### Upgrade + ArkRules
@@ -143,7 +154,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ### Upgrade + extras
 - Schema `1.3` extras (`arkRun` / `arkOrder`) stay off unless already on. Do not turn extras on during upgrade.
 - Pin teaches `arkgate/runtime` (same tarball). `@arkgate/runtime` is deprecated. Do not send agents to `packages/runtime/README.md` as the kernel guide.
-- After 4.8.2, customized skills may lag — opt-in `--refresh-skills` with consent so the frozen 13 names pick up four-plane deepen. No new skill names.
+- After 4.8.2, customized skills may lag — opt-in `--refresh-skills` with consent so the closed catalog picks up four-plane deepen + `/ark-order`. Add a name only with a live ROADMAP item.
 
 ## Safety contract
 

package/templates/skills/ark-adopt.md

@@ -5,6 +5,10 @@ description: Session 0 — write the rules file (ark.config.json) to match the r
 
 # /ark-adopt — Mark the path (session 0)
 
+**Contener · Guiar · Ordenar.** In plain words: contain the write, guide the next
+step, order leftover mess. This door is **Contener**: write the path so the tree
+has honest houses. Skills never enforce — CLI / hooks / CI do.
+
 **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`).
 
@@ -111,7 +115,7 @@ Do **not** invent captions. Do not invent `/ark-describe`.
 | 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 |
 | Turn **advisory** ArkRun on (`arkRun` extra, schema `1.2+`; **`kernelRoots` preferred**) | Evaluate / wire a hand-rolled bus → `/ark-runtime`; new kernel-managed file → `/ark-place` |
-| Turn **advisory** ArkOrder on (`arkOrder` extra, schema `1.3+`, `planeRoots`) | New plane-root file after extra is on → `/ark-place`; grind skip clusters → `/ark-autopilot` |
+| Turn **advisory** ArkOrder on (`arkOrder` extra, schema `1.3+`, `planeRoots`) | Wire one plane candidate after extra is on → `/ark-order`; new plane-root file → `/ark-place`; grind skip clusters → `/ark-autopilot` |
 
 ## Dual engine (mandatory)
 
@@ -149,7 +153,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 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`.
 6. Absence of `arkRun` is **valid**. Write it only when the user wants the extra. Skills never enforce.
-7. Absence of `arkOrder` is **valid**. Write it only when the user wants the extra. Do not invent `/ark-order`. Skills never enforce.
+7. Absence of `arkOrder` is **valid**. Write it only when the user wants the extra. After the extra is honest: handoff **`/ark-order`** to wire one candidate. Skills never enforce.
 
 
 ### Adopt + ArkRules
@@ -191,9 +195,9 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 - A use-case that `prisma.*.update({ plan })` while `plan` is in `xiKeys` is **[ArkOrder]** `ARKORDER_XI_FIELD_WRITE`. Invoices and seats still flow through `ingest`.
 
 - Do **not** put `arkOrder` on the compact starter / `ark start` scaffold. Domain stays plane-free. Import `createOrderPlane` from `arkgate/order` (same npm package).
-- Absence is valid and **silent** — never force the extra. Do not invent `/ark-order`.
+- Absence is valid and **silent** — never force the extra.
 - Demoting enforced → advisory or deleting the extra is policy-delta **weakening**.
-- After the extra is honest: handoff `/ark-place` for new plane-root files; grind skip via `/ark-autopilot`. Skills never enforce.
+- After the extra is honest: handoff **`/ark-order`** to wire one candidate, `/ark-place` for new plane-root files; grind skip via `/ark-autopilot`. Skills never enforce.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -301,7 +305,7 @@ proposals applied or deferred, **phase**, **top Shape / design-weak opportunitie
 - Force runtime kernel over existing Nest/DI.
 - Put `arkRun` or `arkOrder` on the compact starter / `ark start` scaffold.
 - Claim in-memory kernel stores are production durability.
-- Invent `/ark-run` or `/ark-order`.
+- Invent `/ark-run`. Use `/ark-order` after this door turns the extra on.
 - Invent `layers[].description` filler or a `/ark-describe` skill.
 - Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
 - End adopt with only “baseline written” when design-weak residual is visible in files you opened.