arkgate 4.6.6 → 4.7.0

package/templates/skills/ark-place.md

@@ -19,6 +19,9 @@ description: "Where does new code go? Names the layer, directory, and naming for
 - `filePath` is known before the call. Description alone is not a path.
 - 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
+  via `/ark-adopt`. Skills never enforce.
 
 ## Autonomy contract
 
@@ -62,6 +65,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` |
 
 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, …).
@@ -104,19 +108,32 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 |-------|------------------|----------------|-----------------|
 | **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+`) + companion `@arkgate/runtime` | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
 
 **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 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. 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.
 
 
 ### Place + ArkRules
 - Choose layer from contract **and** check structure sensors for that layer (private state, factory, thin adapter).
 - Scaffold to satisfy **[ArkRules]** when present; state which sensors apply.
 
+### 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()`.
+- Domain-role files stay kernel-free (`ARKRUN_KERNEL_IN_DOMAIN`). Import from `@arkgate/runtime` (or `/nestjs`), never a removed `arkgate/runtime` shim.
+- 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.
+- In-memory stores are **not** production durability. Doctor `arkRun` is `notAScore`.
+- Absence of the extra: place with **[Layer]** + **[ArkRules]** only. Enable advisory extra via `/ark-adopt`; evaluate a hand-rolled bus via `/ark-runtime`. Do not invent `/ark-run`.
+- Skills never enforce.
+
 ## Subagent fan-out (optional, host-dependent)
 
 If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
@@ -148,6 +165,10 @@ the same files or weaken the gate.
      that matches the direction (driven/persistence vs driving/http).
    - Reacts to events, long-running coordination (saga/workflow), scheduled
      jobs, projections → the event/workflow layers if the config declares them.
+     When `arkRun` is on, wire those through the kernel (register + declarations),
+     not a homemade emitter.
+   - Kernel-managed application service when `arkRun` is on → composition-root factory
+     + `register({ uses, reactsTo, raises, sends })`; never `new` of the admitted type.
    - **`vertical-slice` contract:** put co-located feature code under
      `src/features/<slice>/…` (never import a sibling slice); shared primitives
      under `src/shared/`; infra under `src/lib/`; shell under `src/app/`.
@@ -175,6 +196,9 @@ the same files or weaken the gate.
   (not place one new artifact): place only the new file under the golden/contract home, then
   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).
 
 ## Operating rules
 
@@ -207,7 +231,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]** (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-runtime.md

@@ -1,25 +1,36 @@
 ---
 name: ark-runtime
-description: Evaluate the experimental Ark runtime kernel against hand-rolled event bus, outbox, audit, saga, projection, policy, or NestJS code. Finds one candidate, wires one, verifies.
+description: Evaluate and wire the experimental ArkRun companion (@arkgate/runtime) against hand-rolled event bus, outbox, saga, projection, policy, or NestJS code. One candidate. Extra on via /ark-adopt; new files via /ark-place. Skills never enforce.
 ---
 
-# /ark-runtime — Evaluate the runtime kernel (experimental opt-in)
+# /ark-runtime — Evaluate and wire ArkRun (experimental opt-in)
 
-The runtime kernel is currently **experimental** and is not required for ArkGate enforcement or
-presented as production-ready. Use this skill only when the user explicitly wants to evaluate it.
+The ArkRun companion (`@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
+does when the `arkRun` extra is on. Do **not** invent `/ark-run`.
 
-The separate `@arkgate/runtime` source package contains the experimental runtime kernel
-(`createArkKernel`) with an event bus, event contracts, outbox, audit trail,
-policy engine, workflow/saga coordination, projections, observability hooks,
-and NestJS adapters. The stable `arkgate` package is the architecture gate; it does not bundle
-the runtime implementation. This skill migrates hand-rolled versions of those to the kernel,
-one feature at a time.
+**When:** evaluate a hand-rolled bus / outbox / saga / projection / policy / Nest adapter against
+the companion, or wire an extra that is already on (composition 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`).
+
+## Extra vs companion (mandatory)
+
+| Piece | What it is | What it is not |
+|-------|------------|----------------|
+| **ArkRun extra** (`arkRun` on `ark.config.json`, schema `1.2+`) | Gate contract: kernel usage + complete declarations | A score; Layers / ArkRules replacement; merge teeth while `advisory` |
+| **Companion** `@arkgate/runtime` | Kernel you construct with `createStrictArkKernel` (one instance per call) | Bundled in the `arkgate` tarball; a process-wide `getKernel()`; shipped cloud broker SDKs |
+
+Absence of the extra is **silent** — Layers and ArkRules verdicts stay identical. Doctor / status
+`arkRun` is always `notAScore`. Never invent 0–10 scores or pass/fail from this skill.
 
 ## Improvement compass note
 
 This skill is **experimental runtime** only. Do **not** treat runtime adoption as residual on the
 resilience lens unless the user explicitly opts into the experimental kernel. Prefer doctor compass
 for static architecture residual; hand static residual to `/ark-explore` / `/ark-autopilot`.
+Doctor `arkRun` residual is a finding-id count (`ARKRUN_*`), never a compass score.
 
 ## Dual engine (mandatory)
 
@@ -41,7 +52,7 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
 
 ## Out of scope for ArkRules
 
-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.
+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]`**.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -62,23 +73,45 @@ the same files or weaken the gate.
    - policy/authorization checks scattered across use cases
    Also check whether `@nestjs/common` is present → the `@arkgate/runtime/nestjs`
    adapters apply.
-2. **Pick ONE target** — the smallest, most self-contained candidate (fewest
+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`.
+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.
-3. **Resolve availability** — run `npm view @arkgate/runtime dist-tags --json`. If an
+   rest as follow-ups in the report. New files after the extra is on go through **`/ark-place`**.
+4. **Resolve availability** — run `npm view @arkgate/runtime dist-tags --json`. If an
    `experimental` tag exists, install that exact companion. Otherwise continue only from an
    ArkGate source checkout: run `npm run build:runtime` at its root and install its local
    `packages/runtime` folder into the target. Outside a source checkout, stop and report that the
    runtime is unavailable; never fall back to the deprecated root shims as if they contained it.
-4. **Migrate** — import from `@arkgate/runtime` or `@arkgate/runtime/nestjs`, and read the
+   Import from `@arkgate/runtime` (or `@arkgate/runtime/nestjs`) — never a removed `arkgate/runtime`
+   shim.
+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. Wire the kernel at the composition root; keep the domain
-   ignorant of it (handlers/ports, not kernel imports inside domain code —
-   the architecture check enforces this; Claude/Grok hooks can block it earlier). Note: the kernel bounds in-memory
-   history by default (`maxHistorySize` 1000); mention this if the hand-rolled
-   version retained everything.
-5. **Delete the hand-rolled version** once call sites are moved — the point is
+   writing code.
+   - Call `createStrictArkKernel` (or an admission sibling: `createArkKernel`, `*FromConfig`) **only**
+     inside `arkRun.compositionRoots`. 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`).
+   - On `register()`, declare `uses` / `reactsTo` / `raises` / `sends`. `extendedInfo` is
+     tooling-only and is **not** a gate verdict. 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.
+   - Send on kernel transport: `local` / `localBlocking` / `broker`. `ephemeral` defaults **true**.
+     Broker adapters are ports you inject — this package does not ship cloud SDKs. Unbound
+     `broker` falls back in-process local. Do not import `EventEmitter` or a homemade bus in
+     `managedLayers` (`ARKRUN_TRANSPORT_BYPASS`).
+   - Optional inspector: `startInspector()` on `127.0.0.1`, refuses `NODE_ENV=production`, no
+     public bind. Snapshots / `requestGraph` (process or technical + Mermaid) are tooling, not a
+     score. `getDependencyInformationPackage()` never includes factories, live instances, or
+     input DTOs.
+   - In-memory stores lose state on restart — **not** production durability. Note bounded history
+     (`maxHistorySize` 1000) if the hand-rolled version retained everything.
+6. **Delete the hand-rolled version** 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 (a misclassified load-bearing
@@ -87,6 +120,8 @@ 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`).
+- 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.
 - Runtime companion unavailable from npm and no ArkGate source checkout: **STOP** and report the distribution boundary.
 - Inventory finds nothing: stop; do not introduce kernel speculatively.
 
@@ -96,20 +131,26 @@ the same files or weaken the gate.
   introduce the runtime kernel 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 `ARKRUN_*`.
+- Never a process-wide kernel singleton. Never shipped cloud broker SDKs.
+- Never claim in-memory stores are production-durable.
 - Plain-language reporting: one sentence per concept ("outbox = events are
   saved in the same transaction as your data, then published — so you never
   publish something that didn't commit").
 
 ## Related onboarding
 
-- Adopt static gates and application shape **first** (`/ark-adopt`).
-- Runtime kernel is optional and separate from enthusiast onboarding.
+- Adopt static gates and application shape **first** (`/ark-adopt`). Brownfield: same door —
+  advisory extra only until the team promotes; absence is valid.
+- Runtime kernel is optional and separate from enthusiast onboarding. Do not put `arkRun` 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, and any behavior differences (e.g. bounded history).
+candidates ranked, behavior differences (e.g. bounded history), and **`[ArkRun]`** residual
+(`ARKRUN_*` / doctor `arkRun`, `notAScore`) separately from Layers / ArkRules.
 
 ## Completion contract (skill incomplete if missing)
 
@@ -119,6 +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:** **`[ArkRun]`** residual (or `n/a` if extra absent) — do not mix with `[Layer]` / `[ArkRules]`
 - **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>`