arkgate 3.9.1 → 4.0.0

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/arkgate",
-  "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
+  "description": "ArkGate \u2014 architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "3.9.1",
+  "version": "4.0.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.9.1",
+      "version": "4.0.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/arkrules/ApplicationOrchestration.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json",
+  "schemaVersion": "1.0",
+  "layer": "ApplicationOrchestration",
+  "structure": [
+    {
+      "id": "orchestration-only",
+      "sensor": "orchestration-only",
+      "mode": "advisory",
+      "description": "Application use cases orchestrate; keep domain branching in Domain."
+    }
+  ],
+  "invariants": []
+}

package/templates/arkrules/DomainModel.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json",
+  "schemaVersion": "1.0",
+  "layer": "DomainModel",
+  "structure": [
+    {
+      "id": "always-valid-aggregates",
+      "sensor": "aggregate-private-state",
+      "mode": "advisory",
+      "description": "Aggregates keep state private; mutate through methods."
+    },
+    {
+      "id": "always-valid-factory",
+      "sensor": "always-valid-factory",
+      "mode": "advisory",
+      "description": "Prefer private constructors with static factories for aggregates."
+    },
+    {
+      "id": "events-on-mutation",
+      "sensor": "domain-event-on-mutation",
+      "mode": "advisory",
+      "description": "Domain mutations should guard invariants or publish events."
+    },
+    {
+      "id": "no-anemic-model",
+      "sensor": "no-anemic-model",
+      "mode": "advisory",
+      "description": "Prefer rich domain types over data-only bags (advisory only)."
+    }
+  ],
+  "invariants": []
+}

package/templates/arkrules/PersistenceAdapters.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json",
+  "schemaVersion": "1.0",
+  "layer": "PersistenceAdapters",
+  "structure": [
+    {
+      "id": "thin-adapter",
+      "sensor": "thin-adapter",
+      "mode": "advisory",
+      "description": "Persistence adapters implement ports without domain branching."
+    }
+  ],
+  "invariants": []
+}

package/templates/arkrules/PresentationAdapters.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json",
+  "schemaVersion": "1.0",
+  "layer": "PresentationAdapters",
+  "structure": [
+    {
+      "id": "thin-adapter",
+      "sensor": "thin-adapter",
+      "mode": "advisory",
+      "description": "Adapters stay thin: map I/O and delegate; avoid domain branching + persistence here."
+    }
+  ],
+  "invariants": []
+}

package/templates/skills/ark-adopt.md

@@ -29,6 +29,29 @@ when design smells remain after the contract is honest.
 | **Exploratory** | walk the real monorepo/app layout; reclassify; mine rules; suggest shape |
 
 
+
+## 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`.
+
+
+### Adopt + ArkRules
+- After classify: emit or refresh `arkRules` for matched layers (exact names; generic mold for unknowns).
+- Mine rules → inventory + propose invariants/structure; land via `/ark-contract`.
+- Freeze baseline is **[Layer]** debt; inventory residual is **[ArkRules]** — report both.
+
 ## Subagent fan-out (optional, host-dependent)
 
 When the user asks to go faster **or** the work naturally splits (multiple packages,
@@ -85,7 +108,10 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    add layers/patterns via `/ark-contract`.
 4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
    - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
-   - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used.
+   - **ArkRules inventory (AR13):** run `ark-check --rules-inventory --json` for deterministic candidates
+     (validation-in-controller, magic constants, anemic entities). Counts are **not a score**.
+   - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
+     land structure/invariant entries under `arkrules/<Layer>.json` via `/ark-contract` (ADR 0015 routing).
    - Apply config through `/ark-contract` discipline; move pure rules into Domain when safe; validate with ark-check.
    - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
@@ -126,6 +152,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-architect.md

@@ -30,6 +30,28 @@ package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
 The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
 
+
+## 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`.
+
+
+### Architect + ArkRules
+- Preset/init should emit lean `arkRules` + templates for phase-1 layers (exact names).
+- Explain to the user: layers = boundaries; arkrules = habits inside Domain/App/adapters (opt-in, start advisory).
+
 ## Subagent fan-out (optional, host-dependent)
 
 If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
@@ -135,6 +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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-autopilot.md

@@ -1,6 +1,6 @@
 ---
 name: ark-autopilot
-description: Guided end-to-end path — doctor next action when unsure. Explore first; dual plan A (edges) + B (shape); mechanical-safe only by default; B with user OK, one pilot at a time. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
+description: Guided end-to-end path for layers and opt-in ArkRules — doctor next action when unsure. Explore first; dual plan A (edges) + B (shape); mechanical-safe only by default; B with user OK, one pilot at a time. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
 ---
 
 # /ark-autopilot — Guided end-to-end architecture path
@@ -64,6 +64,31 @@ decision-grade explore pass **and** without opening violating files.
    optional `reviewBy` in `.ark/reshape-decisions.json`; never infer a verdict from golden prose.
 
 
+
+## 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`.
+
+
+### Autopilot + ArkRules
+- After explore/doctor: if inventory has high-confidence candidates **or** user wants domain rules, include **[ArkRules] plan A/B**:
+  - A: mechanical-safe remains inter-layer only; structure/invariant fixes are **judgment**.
+  - B: one pilot = one rule (declare in `arkrules/<Layer>.json` → implement → test title/symbol → re-doctor).
+- Never promote advisory→enforced without coverage evidence (`canPromoteInvariant` / policy-delta).
+- End report must list what was **layer-edge** work vs **intra-layer rule** work.
+
 ## Subagent fan-out (optional, host-dependent)
 
 When the user asks to go faster **or** the work naturally splits (multiple packages,
@@ -200,6 +225,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-contract.md

@@ -1,6 +1,6 @@
 ---
 name: ark-contract
-description: Safely edit ark.config.json (layers, rules, forbiddenGlobals, intent prefixes) and land business rules into the Ark manifest. Validated with strict ark-check. Deep source evidence required.
+description: Safely edit ark.config.json layers/rules and arkrules/* (structure + invariants); land business rules under the dual plane. Validated with strict ark-check. Deep source evidence required.
 ---
 
 # /ark-contract — Change the architecture contract (safely)
@@ -26,6 +26,29 @@ Also used to **land mined business rules** into the executable manifest (`ark.co
 The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
 
+
+## 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`.
+
+
+### Contract + ArkRules
+- You own **both** `layers/rules` and `arkRules`/`arkrules/*.json`.
+- Report diffs in two blocks: **[Layer] config** and **[ArkRules] files**.
+- Promotion ladder: advisory→enforced only with coverage; demote = hash-ack weakening.
+
 ## Subagent fan-out (optional, host-dependent)
 
 If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
@@ -54,6 +77,8 @@ the same files or weaken the gate.
 - `include` / `exclude`
 - `layers[]` (`name`, `patterns`, `optional`, `forbiddenGlobals`, `intentPrefixes`, layer `exclude`)
 - `rules[]` (from/to/allowed)
+- **`arkRules` map + `arkrules/<Layer>.json`** (ADR 0012/0014) — structure sensors + invariant catalog;
+  promote advisory→enforced only with coverage evidence; demote/delete requires hash-bound policy ack
 - Never: disable the check, delete CI gates, or add blanket `allowed: true` for a bad edge without a facade design
 
 ## Steps
@@ -93,6 +118,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-coverage.md

@@ -42,6 +42,28 @@ Shape ladder by default. If the tree is design-weak under ENFORCE, **handoff** t
 If you did not open source files, the skill is **not complete**.  
 Full recon + pattern planning: `/ark-explore`.
 
+
+## 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`.
+
+
+### Coverage + ArkRules
+- Fitness report: governed% / gates / baseline = **[Layer]**; `rulesUnderContract` inventoried/under-contract/frozen = **[ArkRules]** (counts, never a score).
+- Capability gap: “no arkRules map” is optional adoption opportunity, not a failed gate.
+
 ## Subagent fan-out (optional, host-dependent)
 
 When the user asks to go faster **or** the work naturally splits (multiple packages,
@@ -71,6 +93,13 @@ Never say “your architecture is guarded” while `goal.met` is false, governed
 or false-green doctor gaps are open. Never say “architecture is healthy finished” solely
 because governed% is 100% and plan is empty.
 
+**Honesty hard lines (doctor JSON):**
+- `coverageHonesty.worseThanNoGate` / weak coverage (~&lt;50%): green is **worse than no gate**.
+- `baseline.honesty.dirtyBaselineRisk`: green-via-freeze may hide false-positive debt.
+- `writePath.honesty.softWriteHost` (Cursor / Codex / OpenCode): write path is **advisory /
+  best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
+- Do not invent hard write guarantees for soft hosts.
+
 ## Related onboarding
 
 - **Greenfield:** low governed% → `/ark-architect` or `ark-check --recommend`.
@@ -121,6 +150,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-explain.md

@@ -26,6 +26,28 @@ Your job is to **teach with this repo's real data** and leave a shareable visual
 The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
 
+
+## 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`.
+
+
+### Explain + ArkRules
+- HTML/plain tour: section **Layers** and section **ArkRules** (structure + invariants + residual).
+- Never merge them into one “architecture score.”
+
 ## Subagent fan-out (optional, host-dependent)
 
 If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
@@ -147,6 +169,7 @@ End with **exactly** these headings (markdown `###`):
 - **Sensor:** commands/tools run (include report + browser-open command when used)
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome (include `ark-report.html` path; note if browser open was attempted)
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-explore.md

@@ -1,6 +1,6 @@
 ---
 name: ark-explore
-description: Specialized map skill — decision-grade recon + dual-plan seed (no apply). Primary post-green door when design-weak. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
+description: Specialized map skill — decision-grade recon of layers + ArkRules opportunities + dual-plan seed (no apply). Primary post-green door when design-weak. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
 ---
 
 # /ark-explore — Recon the real project (map only)
@@ -67,6 +67,30 @@ that still matters (dogfood gaps, soft starters, identity drift, **semantic fals
 **design-weak under ENFORCE**, coupling that blocks evolution). If residual is truly none,
 say so in one line and hand off `stop`.
 
+
+## 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`.
+
+
+### Explore + ArkRules
+- Always run sensors for **both** planes when present: coverage/doctor **and** `--rules-inventory` if `arkRules` exists or brownfield may hide spaghetti rules.
+- Ranked table kinds may include `arkrules-opportunity` and `invariant-gap`.
+- 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/*`.
+
 ## Output mode (pick one — do not invent a fourth)
 
 | Mode | When | Deliverable |
@@ -247,7 +271,10 @@ Canonical productized template also in `docs/brownfield-adoption.md` §6.
 
 **Q04 pilot loop:** when doctor/plan JSON is available, use **`pilotLoop.nextPilot`** as the
 **single** next extraction card (one pilot at a time → re-doctor). Do not open five B bets
-in parallel. After the pilot lands, re-run doctor; success = reduced evidence on pilot paths.
+in parallel. When `pilotLoop.queuedBets > 0`, those bets stay **queued**, not concurrent.
+`multiPilotBatchForbidden` / `autoApplyForbidden` (alias `autoApplyPlanBForbidden`) are hard
+lines — never silent codemod of plan B. After the pilot lands, re-run doctor; success =
+reduced evidence on pilot paths.
 
 ```text
 ### Extraction card
@@ -313,6 +340,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-fix.md

@@ -40,6 +40,28 @@ Next: re-run ark-check; shrink baseline if applicable
 | **Exploratory** | Why this edge exists in *this* product; better home; manifiesto if the rule is business |
 
 
+
+## 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`.
+
+
+### Fix + ArkRules
+- Classify each violation: `LAYER_*` / capability → **[Layer]**; `ARKRULE_*` / `INVARIANT_*` → **[ArkRules]**.
+- Structure sensor fixes are judgment (ports, factories, private state) — not mechanical-safe.
+
 ## Subagent fan-out (optional, host-dependent)
 
 When the user asks to go faster **or** the work naturally splits (multiple packages,
@@ -135,6 +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:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-loop.md

@@ -41,6 +41,28 @@ Pattern bets always have `neverMechanicalSafe: true` — extraction cards only
 | **Exploratory** | Read sources; detect concentrated edges / false-green / wrong layer home before grinding |
 
 
+
+## 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,
@@ -141,6 +163,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-place.md

@@ -35,6 +35,28 @@ not a stalling question.
 The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
 
+
+## 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
@@ -56,6 +78,9 @@ the same files or weaken the gate.
    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).
@@ -82,6 +107,10 @@ the same files or weaken the gate.
 
 - 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
 
@@ -114,6 +143,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-runtime.md

@@ -25,6 +25,10 @@ one feature at a time.
 The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
 
+## 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

package/templates/skills/ark-think.md

@@ -1,6 +1,6 @@
 ---
 name: ark-think
-description: Host-side architectural reasoning — 2–3 enforceable options from real code + contract for ONE decision. Not full recon (use /ark-explore). No gate bypass. No package LLM call.
+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)
@@ -30,6 +30,28 @@ If you lack a product map and the tree is messy: run a **compressed** explore pa
 
 Never reason only from abstract hexagons. Open real modules before recommending a shape.
 
+
+## 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,
@@ -91,6 +113,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)
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`