arkgate 4.2.1 → 4.3.0

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

@@ -0,0 +1,180 @@
+---
+name: ark-loop
+description: Drive ark-check --plan to zero active violations. Read real source, auto-apply only mechanical-safe kinds, design judgment from the product tree. CLI validates — you edit code.
+---
+
+# /ark-loop — Apply the plan safely
+
+Read Ark’s classified **plan**, work toward **goal.met**, one small step at a time,
+validating every change with `ark-check` and rolling back regressions.
+
+Deterministic kinds stay **tight**. Your job is still **exploratory on the files**: open
+importers/targets, see if the plan step is a symptom of wrong shape / false Domain / I/O
+under Application — escalate to `/ark-contract` or `/ark-explore` when the wall is structural.
+
+## When / not when
+
+| Use `/ark-loop` when… | Do **not** use it when… |
+|-----------------------|-------------------------|
+| Plan A has steps; drive to `goal.met` | Plan A empty — **stop**; residual Shape → `/ark-explore` / `/ark-autopilot` B |
+| Mechanical-safe + approved judgment only | Full product recon first → explore inside `/ark-autopilot` |
+| User already has a plan and wants the apply loop | Brownfield contract false-green → `/ark-adopt` |
+
+**Empty plan is not success for the product** — only for *edge remediation*. If `goal.met` and
+(`goal.designWeak` or non-empty `patternBets` from `--plan --json`): do **not** invent
+mechanical-safe kinds; hand off `/ark-explore` shape-focus or `/ark-autopilot` for dual-plan B.
+Pattern bets always have `neverMechanicalSafe: true` — extraction cards only
+(`docs/brownfield-adoption.md` §6).
+
+## Related onboarding
+
+- **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Map / opportunities:** `/ark-explore`.
+- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | Only the four `mechanical-safe` kinds auto-apply; plan tags; gate re-check |
+| **Exploratory** | Read sources; detect concentrated edges / false-green / wrong layer home before grinding |
+
+
+
+## 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.
+
+## 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`.
+
+
+### Loop + ArkRules
+- Drive plan to zero **active** debt on the plane the user cares about; keep **[Layer]** and **[ArkRules]** queues separate.
+- One pilot at a time for ArkRules extraction cards (`pilotLoop` / inventory).
+
+## 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**:
+
+| 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. |
+
+**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.
+
+## Anti-wrapper rule (mandatory)
+
+**Forbidden:** re-printing plan JSON without opening sources, or inventing new “safe” kinds.
+
+**Required:**
+1. `--plan --json` as sensor.
+2. For each step you touch: **read** `file` and `target` source (and enough callers to know the edge).
+3. **“Así te lo re-soluciono”** — exact edit before applying.
+4. After each apply: full gate re-run; rollback if targeted violation remains or new ones appear.
+5. If one edge dominates: **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).
+6. If empty cores + I/O under Application: **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`.
+
+## mechanical-safe only (auto)
+
+| `remediationKind` | What to do |
+|-------------------|------------|
+| `type-only-import-move` | Move type to owning layer; re-export for back-compat |
+| `pure-type-file-relocate` | Relocate pure-type file to owning layer (or rename out of false Domain globs) |
+| `import-type-from-pure-type-module` | Convert value import of pure-type module to `import type` |
+| `import-type-of-type-exports` | Convert value-syntax named import/export of type-only exports from a mixed module to `import type` / `export type` |
+| *(none for port-proof)* | **W6** `port-proof-inject-binding` is **judgment** (arity change) — propose inject; do not auto-apply |
+
+Never auto: free value uses of imports, multi-import files, dynamic import/require, forbidden globals, cycles, port-proof inject, multi-file adapter scaffolding without proof.
+
+## Mechanical-edit hygiene (Y04 — outcome gate)
+
+- Header injection must **merge into the existing doc comment**; the kept result has one `/**`, not stacked headers.
+- Route completion or movement must **preserve the original typed `defineRoute<…>(opts, handler)` call**; reconstruct that call instead of extracting untyped opts/handler constants that drop generics or contextual typing.
+- A convention-only `*-data.ts` stub is not a fix: move the real code or **leave the placeholder file uncreated**; never write `import "server-only"; export {}` as an empty naming token.
+- Keep the edit only when the **previously clean file stays typecheck-clean**. Otherwise roll it back and treat the change as judgment.
+
+## Reshape pilots (X04 — physical cohesion, advisory)
+
+When `ark-check --doctor --json` carries `doctor.physicalCohesion.reshapePilot.nextPilot`,
+you may run **that one pilot** — never more:
+
+1. Read `physicalCohesion.reshapeDecisions` first. A current rejected/deferred target has no live
+   card: respect the explicit record and do not reconstruct it from raw facts. Read a live card's
+   `pilotTarget`, `decisionTarget`, `moveSample`/`movesTotal`, `successSignal`, `killSwitch`, `doNot[]`.
+2. Moves are **proposed only** — enumerate the full move set for the pilot anchor, express it as
+   an architecture change map, and validate through the atomic preflight (`ark_prepare_change`
+   with the matched `project` envelope / the write gate) **before** any file moves. A move the preflight rejects is a finding, not a
+   thing to force.
+3. Never move anything under `app/` or `pages/` (fixed by framework convention). Never merge
+   files here — merges are judgment cards for `/ark-architect` / `/ark-fix`.
+4. After the move set: full gate re-run + re-doctor. Success = the concept's cluster count drops
+   and the verdict stays green; otherwise use the kill switch (revert the move set, nothing else).
+5. Re-doctor decides whether a next card exists. One pilot per loop iteration, always.
+6. If the user accepts, defers, or rejects the target, persist that explicit verdict in
+   `.ark/reshape-decisions.json` using the card's exact `decisionTarget`, a reason, and optional
+   `reviewBy`. `accepted` keeps this execution path; `deferred`/`rejected` stop repeat pressure.
+   Never infer a decision from `.ark/golden-pattern.json` prose.
+
+## Steps
+
+1. **Plan** — `ark-check --plan --json` (+ `--baseline` if used). If `goal.met`: stop **A**;
+   if design-weak residual is visible, hand off explore/autopilot B — do not claim architecture done.
+2. **Worktree** — prefer discardable git worktree.
+3. **Apply mechanical-safe** one-by-one with validate/rollback.
+4. **Judgment** — propose with source-based design; apply only if user approved (or parent autopilot said full apply).
+5. **Re-plan** after each round until dry, `goal.met`, or only judgment left without approval.
+6. **Report** — auto-applied / proposed / deferred with paths; never claim clean if skipped.
+
+## Operating rules
+
+- Never weaken the gate (no rule disables, no fresh baselining of new debt).
+- Concentrated single edge → stop and hand to `/ark-contract` with code evidence.
+- When unsure behavior preservation → judgment, not mechanical-safe.
+
+## Done criteria
+
+- Gate confirms each kept edit.
+- Honest residual list with **Así te lo re-soluciono** for anything left.
+- If residual steps hide domain/business rules in the wrong layer, call out **manifiesto** work (`intentPrefixes` / Domain placement) via `/ark-contract` or `/ark-adopt`.
+
+## 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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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

@@ -0,0 +1,162 @@
+---
+name: ark-place
+description: "Where does new code go? Names the layer, directory, and naming for a new artifact from the contract, and scaffolds it there. Autonomous."
+---
+
+# /ark-place — Where does this code go?
+
+## When / not when
+
+| Use `/ark-place` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| New artifact: where + scaffold under contract | Existing violation fix → `/ark-fix` |
+| Naming / directory for a known kind | Contract layers wrong → `/ark-contract`; full shape choice greenfield → `/ark-architect` |
+
+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, …).
+Your job: name the layer it belongs to, the directory, the naming convention,
+and — if they asked to build it — scaffold it there correctly.
+
+**No artifact given?** If the skill is invoked with nothing to place, don't error
+and don't guess — the artifact is the one thing only the user knows. Read the
+contract (step 1) and print the placement map from it: one row per declared layer
+with what belongs there, its directory, and which layers it may/may not import,
+plus the not-yet-adopted `suggestedLayers` as a footnote. Then ask what they want
+to place. That map is derived entirely from the repo, so producing it is real work,
+not a stalling question.
+
+## 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.
+
+## 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`.
+
+
+### 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.
+
+## 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. **Read the contract, not your intuition.** If the `ark` MCP server is available, complete
+   the mandatory `ark_identity` preflight first, then call **`ark_place`** with the target file
+   path and bound `project` envelope — it returns the layer,
+   its forbidden globals, and exactly which layers the file may / must not import,
+   straight from the contract (no guessing). When present, also honor optional
+   **`goldenPattern`** (from `.ark/golden-pattern.json`) for **NEW code only** —
+   advisory layout norm; never overrides the gate and never clears design-weak.
+   Absent golden is normal. Otherwise load `ark.config.json`; after the matched preflight,
+   `ark_manifest` with the same bound envelope includes `suggestedLayers` with conventional
+   directories for layers not yet adopted. The `ark://manifest` resource is compatibility-only and always
+   unverified/non-authoritative. The project's `AGENTS.md` placement table, if present, is
+   authoritative too.
+2. **Classify the artifact** by what it does, not what it's called:
+   - Pure business rules/entities/value objects → domain-model layer.
+   - When Domain ArkRules require private state / factories (`aggregate-private-state`,
+     `always-valid-factory`), scaffold private fields + static factory — do not emit public
+     mutable aggregates.
+   - Orchestrates a use case, no I/O of its own → application layer.
+   - Talks to a database, queue, API, filesystem → an adapter layer on the side
+     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.
+   - **`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/`.
+   - **`ddd-bounded-contexts` contract:** put code under
+     `src/contexts/<context>/{domain,application,infrastructure,presentation}/`;
+     shared kernel only under `src/shared/kernel/`. Cross-context imports at the
+     same technical layer are peerIsolation violations.
+3. **Answer concretely**: layer name, target directory (from the layer's
+   `patterns`), intent-name prefix if the layer declares `intentPrefixes`, and
+   which layers it may/may not import (from `rules`).
+4. **If the layer isn't adopted yet** (suggested but no directory): say so,
+   give the conventional directory from `suggestedLayers`, and offer
+   `/ark-contract` to adopt it — don't silently drop the code into a
+   wrong-but-existing layer.
+5. **If asked to create it**: scaffold the file(s) in place, following the
+   nearest existing sibling's style, and any port/adapter split the rules force.
+
+## Critical handoffs
+
+- If the user needs bulk adoption / wrong contract, not a single artifact: **STOP — do not continue this skill as complete.** **STOP — wrong skill: invoke /ark-adopt or /ark-contract** instead of ad-hoc multi-file grinding without a plan.
+- If contract lacks a home for the artifact: **STOP — do not continue this skill as complete.** Adopt the layer via `/ark-contract` first.
+- If doctor is **ENFORCE · design-weak** and the user is asking to reshape existing structure
+  (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.
+
+## Operating rules
+
+- Never ask "which layer do you prefer?" — the contract decides; you translate.
+  Only surface a question when the artifact genuinely spans two legal designs
+  with different trade-offs, and then recommend one.
+- Explain the placement in one plain-language sentence ("this goes in
+  `src/domain` because it's a business rule that shouldn't know about the
+  database") — assume the user may be new to layered architecture.
+
+## Related onboarding
+
+- Run **after** shape adoption: `/ark-architect` or `ark init --archetype` on greenfield;
+  `/ark-adopt` on brownfield.
+- `ark-check --recommend` / MCP `ark_recommend` picks phase-1 dirs; gallery starters in
+  `examples/*-starter/` show correct placement per archetype.
+- Related demos: `docs/demos/` (write-gate self-correction, brownfield, autopilot).
+
+## Verify and report
+
+If you created files, run `ark-check --root . --config ark.config.json
+--strict-config` and make it pass. Report: placement + why, files created (if
+any), and the import rules the new code must respect going forward.
+
+## 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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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-runtime/SKILL.md

@@ -0,0 +1,120 @@
+---
+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.
+---
+
+# /ark-runtime — Evaluate the runtime kernel (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 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.
+
+## 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
+
+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.
+
+## 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:
+   - event bus / emitter used for domain events (`EventEmitter`, homemade
+     pub/sub, ad-hoc handler registries)
+   - outbox tables or "save event + publish later" code
+   - audit/history logs written manually
+   - saga/workflow orchestration (multi-step processes with compensation)
+   - read-model/projection builders
+   - 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
+   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
+   `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
+   [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
+   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
+   emitter must not be removed on a guess).
+
+## Critical handoffs
+
+- No static gates yet: **STOP — do not continue this skill as complete.** Run `/ark-architect` or `/ark-adopt` first.
+- 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.
+
+## Operating rules
+
+- If the inventory finds NO hand-rolled equivalents, say so and stop — do not
+  introduce the runtime kernel speculatively. Static enforcement alone is a
+  complete, valid use of Ark.
+- Keep the migration diff reviewable: one feature per invocation.
+- 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-architect`, `/ark-adopt`).
+- Runtime kernel is optional and separate from enthusiast onboarding.
+
+## 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).
+
+## 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
+- **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-think/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: ark-think
+description: Host-side architectural reasoning — 2–3 enforceable options on layer and/or ArkRules planes for ONE decision. Not full recon (use /ark-explore). No gate bypass. No package LLM call.
+---
+
+# /ark-think — Architectural reasoning (host LLM only)
+
+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.
+
+## 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-fix` / `/ark-loop` / `/ark-autopilot` |
+| Trade-offs before writing a **new** feature | Brownfield contract wrong / false-green → `/ark-adopt` then `/ark-contract` |
+| 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.
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **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.
+
+
+## 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.
+
+## 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`.
+
+
+### 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.
+
+## 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**:
+
+| 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. |
+
+**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.
+
+## 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`; config `/ark-contract`; bulk debt `/ark-loop` /
+   `/ark-autopilot`; map-only `/ark-explore`; violations `/ark-fix`.
+   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`
+
+## 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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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.