arkgate 4.8.0 → 4.8.2

package/templates/skills/ark-explore.md

@@ -139,21 +139,24 @@ 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)
+## Dual plane — layers + extras (mandatory, except /ark-runtime)
 
-ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+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 | `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) | `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 a two-column table with those headers).
+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 applying structure fixes is **`/ark-adopt`** / **`/ark-autopilot`** — explore does not write (never invent `mechanical-safe`).
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+6. Never write `arkRun` or `arkOrder` from this skill. When extras are present, label residual **`[ArkRun]`** / **`[ArkOrder]`**. Do not invent `/ark-run` or `/ark-order`.
 
 
 ### Explore + ArkRules
@@ -162,6 +165,10 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 - Dual-plan **B** may include: place advisory structure rules, extract one inventory candidate to Domain + `arkrules` entry, promote one covered invariant.
 - Field path: note whether starters emit `arkrules/*`.
 
+### Explore + extras
+- Map extras when present; never write `arkRun` / `arkOrder`. Extra off → residual `n/a` / silent.
+- Field path may name `examples/arkorder-billing/` (ArkOrder fixture — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
+
 ## Output mode (pick one — do not invent a fourth)
 
 | Mode | When | Deliverable |
@@ -289,6 +296,7 @@ When `examples/`, `templates/`, gallery starters, eval fixtures, or docs claim
 3. Diff **rule strength** across archetypes (missing denies = soft false-green for consumers).
 4. Note import style vs package surface docs (`arkgate` root barrel vs preferred subpath).
 5. Flag **false promises**: demo fails under its own check, or green with a hollow contract.
+6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name `examples/arkorder-billing/`. Never write extras from this skill.
 
 If the repo is a **pure app** (no examples): state **Field path: internal** and do one of:
 - Name the **norm for new code** that the residual implies (e.g. “no new `platform/db` in routes”), or
@@ -431,7 +439,7 @@ End with **exactly** these headings (markdown `###`):
 - **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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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`

package/templates/skills/ark-fix.md

@@ -46,9 +46,9 @@ 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)
+## Dual plane — layers + extras (mandatory, except /ark-runtime)
 
-Label findings **`[Layer]`** vs **`[ArkRules]`**. Structure sensor fixes are judgment.
+Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. Absence of extras is valid and silent. Extra skip clusters (`ARKRUN_*` / `ARKORDER_*`) are **`/ark-autopilot`**. Do not invent `/ark-run` or `/ark-order`. Skills never enforce.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -83,7 +83,7 @@ Skill incomplete if missing any field below.
 - **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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-autopilot` / `/ark-adopt` / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`

package/templates/skills/ark-loop.md

@@ -41,9 +41,9 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
 
 Atomic multi-file work uses **`ark_prepare_change`** with the same matched `project` envelope.
 
-## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+## Dual plane — layers + extras (mandatory, except /ark-runtime)
 
-Label findings **`[Layer]`** vs **`[ArkRules]`**. Never invent `mechanical-safe` kinds.
+Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. Absence of extras is valid and silent. Extra skip clusters (`ARKRUN_*` / `ARKORDER_*`) are **`/ark-autopilot`**. Never invent `mechanical-safe` kinds. Do not invent `/ark-run` or `/ark-order`. Skills never enforce.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -79,7 +79,7 @@ Skill incomplete if missing any field below.
 - **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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-autopilot` / `/ark-explore` / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`

package/templates/skills/ark-place.md

@@ -20,8 +20,12 @@ description: "Where does new code go? Names the folder from the rules file and w
 - Golden pattern is load-bearing when present. Adopt generates it.
 - Do not default a repository to Presentation.
 - When `arkRun` is on: scaffold through the kernel (no `new` of managed types; declare
-  `uses` / `reactsTo` / `raises` / `sends`). Extra off → do not introduce the kernel. Enable it
+  `uses` / `reactsTo` / `raises` / `sends`; factory only in `arkRun.kernelRoots`,
+  `compositionRoots` alias). Extra off → do not introduce the kernel. Enable it
   via `/ark-adopt`. Skills never enforce.
+- When `arkOrder` is on: factory only in `arkOrder.planeRoots`; Domain stays plane-free;
+  freeze ξ with `release()`. Extra off → do not introduce the plane. Enable it via
+  `/ark-adopt`. Skills never enforce.
 
 ## Autonomy contract
 
@@ -66,6 +70,7 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 | 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` |
 
 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, …).
@@ -108,7 +113,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 |-------|------------------|----------------|-----------------|
 | **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 | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime` | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
+| **ArkRun** (extra) | Kernel usage + complete declarations | `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) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
 
 **Rules for every report / answer:**
@@ -128,7 +133,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ### Place + ArkRun
 When `arkRun` is present on the architecture config:
 - Scaffold kernel-managed artifacts **through the kernel**, not `new` of an admitted type (`ARKRUN_DIRECT_NEW`).
-- Call `createStrictArkKernel` (or an admission sibling) only inside `arkRun.compositionRoots`. Each call is a new instance — no process-wide `getKernel()`.
+- Call `createStrictArkKernel` (or an admission sibling) only inside `arkRun.kernelRoots` (`compositionRoots` is a legacy alias — still valid). Each call is a new instance — no process-wide `getKernel()`.
 - Domain-role files stay kernel-free (`ARKRUN_KERNEL_IN_DOMAIN`). Import from `arkgate/runtime` (or `arkgate/nestjs`). `@arkgate/runtime` is deprecated.
 - List `uses` / `reactsTo` / `raises` / `sends` when `requireDeclarations` is on. Adding an existing call-site literal to the declaration list is the only mechanical-safe ArkRun edit; inventing a new emit / handle / depend is judgment.
 - Do not import a homemade bus (`EventEmitter`, queue clients) in `managedLayers` — send on the kernel transport (`local` / `localBlocking` / `broker`; `ephemeral` defaults true). No shipped cloud SDKs.
@@ -141,6 +146,7 @@ When `arkOrder` is present on the architecture config:
 - Import `createOrderPlane` from `arkgate/order` (same npm package). Domain-role files stay plane-free.
 - Freeze ξ with `release()`; derive s with `project()`; field `ingest()` never mints a pattern; `proposeRelease()` needs a non-empty blast. There is no `update`/`patch`/`set`.
 - Call the factory only inside `arkOrder.planeRoots`. Empty roots in `enforced` mode is `ARKORDER_MISSING_PLANE`.
+- Skip clusters (`ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI`): 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.
 
 ## Subagent fan-out (optional, host-dependent)
@@ -208,6 +214,9 @@ the same files or weaken the gate.
 - 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).
+- 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`.
 
 ## Operating rules
 

package/templates/skills/ark-runtime.md

@@ -11,7 +11,7 @@ to evaluate or wire the kernel. **This skill never enforces** — the write / CI
 does when the `arkRun` extra is on. Do **not** invent `/ark-run`. `@arkgate/runtime` is deprecated.
 
 **When:** evaluate a hand-rolled bus / outbox / saga / projection / policy / Nest adapter against
-the kernel, or wire an extra that is already on (composition root, declarations, transport).
+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`).
 
@@ -50,9 +50,9 @@ 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.
 
-## Out of scope for ArkRules
+## Out of scope for ArkRules and ArkOrder
 
-This skill is **runtime-kernel only**. Do not mix ArkRules structure/invariants here; hand off to `/ark-contract` / `/ark-adopt` / `/ark-explore` for static contract planes. Label kernel-usage residual **`[ArkRun]`** so it never blurs with **`[Layer]`** or **`[ArkRules]`**.
+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]`**.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -75,20 +75,22 @@ the same files or weaken the gate.
    adapters apply.
 2. **Read the extra** — open `ark.config.json`. If `arkRun` is absent and the user wants the extra,
    **STOP — do not continue this skill as complete.** Handoff **`/ark-adopt`** to write **advisory**
-   `arkRun` (schema `1.2+`; `compositionRoots`, `managedLayers`, `requireDeclarations`). Do not
-   invent the extra here. If the extra is present, note `mode`, roots, managed layers, and
-   `requireDeclarations`; doctor `arkRun` is `notAScore`.
+   `arkRun` (schema `1.2+`; **`kernelRoots` preferred**, `compositionRoots` alias, `managedLayers`,
+   `requireDeclarations`). Do not invent the extra here. If the extra is present, note `mode`,
+   `kernelRoots` (or alias `compositionRoots`), managed layers, and `requireDeclarations`; doctor
+   `arkRun` 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/runtime`.
    Import from `arkgate/runtime` (or `arkgate/nestjs`). `@arkgate/runtime` is deprecated.
 5. **Wire through the kernel** — read the
-   [runtime package guide](https://github.com/pedroknigge/arkgate/blob/main/packages/runtime/README.md)
-   plus the [experimental surface policy](https://github.com/pedroknigge/arkgate/blob/main/docs/package-surface.md#experimental-opt-in-surfaces) before
-   writing code.
+   [experimental opt-in surfaces](https://github.com/pedroknigge/arkgate/blob/main/docs/package-surface.md#experimental-opt-in-surfaces)
+   (primary kernel guide; import `arkgate/runtime` from the same `arkgate` tarball). Optional
+   durability non-claim: [production-hardening.md](https://github.com/pedroknigge/arkgate/blob/main/docs/production-hardening.md).
+   Do **not** treat `packages/runtime/README.md` (deprecated companion leftover) as the kernel guide.
    - Call `createStrictArkKernel` (or an admission sibling: `createArkKernel`, `*FromConfig`) **only**
-     inside `arkRun.compositionRoots`. Each call is a new instance — no process-wide singleton.
+     inside `arkRun.kernelRoots` (`compositionRoots` is a legacy alias — still valid). Each call is a new instance — no process-wide singleton.
    - Keep Domain-role layers kernel-free (`ARKRUN_KERNEL_IN_DOMAIN`).
    - Resolve managed types from the kernel; do not construct admitted types with `new`
      (`ARKRUN_DIRECT_NEW`).
@@ -155,7 +157,7 @@ End with **exactly** these headings (markdown `###`):
 - **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:** **`[ArkRun]`** residual (or `n/a` if extra absent) — do not mix with `[Layer]` / `[ArkRules]`
+- **Planes:** **`[ArkRun]`** residual (or `n/a` if extra absent) — do not mix with `[Layer]` / `[ArkRules]` / `[ArkOrder]`
 - **Compass:** `n/a` (runtime skill; static residual → explore/fix) | top residual if doctor was run
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`

package/templates/skills/ark-think.md

@@ -69,20 +69,22 @@ 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)
+## Dual plane — layers + extras (mandatory, except /ark-runtime)
 
-ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+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 | `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) | `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 a two-column table with those headers).
+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-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+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`.
 
 
@@ -90,6 +92,9 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 - 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,
@@ -126,8 +131,9 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
    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`; config `/ark-contract`; bulk debt `/ark-loop` /
-   `/ark-autopilot`; map-only `/ark-explore`; violations `/ark-fix`.
+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
@@ -154,7 +160,7 @@ End with **exactly** these headings (markdown `###`):
 - **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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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`

package/templates/skills/ark-upgrade.md

@@ -116,27 +116,35 @@ a stale MCP is non-authoritative: `ark_identity` diagnoses it and project tools
 `PROCESS_PACKAGE_STALE` until restart. Prefer project-local CLI meanwhile. A modern stale global
 `ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry.
 
-## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+## Dual plane — layers + extras (mandatory, except /ark-runtime)
 
-ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+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 | `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) | `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 a two-column table with those headers).
+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. 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`.
 
 
 ### Upgrade + ArkRules
 - Refresh skills + note if templates gained ArkRules deepen; do not force consumers to adopt `arkRules`.
 - After upgrade: doctor `rulesUnderContract` if map exists; dual-truth note if `--no-install` left package pin old.
 
+### 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.
+
 ## Safety contract
 
 - Always invoke the **project-local** CLI (`npx arkgate` /
@@ -305,7 +313,7 @@ End with exactly this structure:
 - **Active host:** host and verified status
 - **Deferred hosts:** `none` or host plus future action
 - **Result:** old → new version and managed-upgrade outcome
-- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-…`, CLI action, or `none`
 - **Incomplete?** `no` or `yes — <missing work>`