arkgate 3.7.0 → 3.8.0

package/schemas/ark.analysis-result.schema.json

@@ -1,21 +1,155 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/arkgate@2/schemas/ark.analysis-result.schema.json",
+  "$id": "https://unpkg.com/arkgate@3/schemas/ark.analysis-result.schema.json",
   "title": "ArkGate analysis result",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "schemaVersion",
+    "mode",
     "valid",
+    "completeness",
+    "completenessReasons",
     "diagnostics"
   ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "completeness": {
+            "enum": [
+              "partial",
+              "unavailable"
+            ]
+          }
+        },
+        "required": [
+          "completeness"
+        ]
+      },
+      "then": {
+        "properties": {
+          "valid": {
+            "const": false
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "mode": {
+            "const": "resolved-candidate-facts"
+          },
+          "completeness": {
+            "enum": [
+              "complete",
+              "partial"
+            ]
+          }
+        },
+        "required": [
+          "mode",
+          "completeness"
+        ]
+      },
+      "then": {
+        "required": [
+          "policyHash",
+          "resolverIdentity",
+          "factsHash",
+          "candidateTreeHash"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "completeness": {
+            "const": "complete"
+          }
+        },
+        "required": [
+          "completeness"
+        ]
+      },
+      "then": {
+        "properties": {
+          "completenessReasons": {
+            "maxItems": 0
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "completenessReasons": {
+            "minItems": 1
+          }
+        }
+      }
+    }
+  ],
   "properties": {
     "schemaVersion": {
-      "const": "1.1"
+      "const": "1.3"
+    },
+    "mode": {
+      "enum": [
+        "lexical-compatibility",
+        "resolved-candidate-facts"
+      ]
     },
     "valid": {
       "type": "boolean"
     },
+    "completeness": {
+      "enum": [
+        "complete",
+        "partial",
+        "unavailable"
+      ]
+    },
+    "completenessReasons": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "minLength": 1
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1
+          },
+          "file": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "policyHash": {
+      "type": "string",
+      "minLength": 1
+    },
+    "resolverIdentity": {
+      "type": "string",
+      "minLength": 1
+    },
+    "factsHash": {
+      "type": "string",
+      "minLength": 1
+    },
+    "candidateTreeHash": {
+      "type": "string",
+      "minLength": 1
+    },
     "diagnostics": {
       "type": "array",
       "items": {
@@ -81,6 +215,29 @@
               },
               "typeOnly": {
                 "type": "boolean"
+              },
+              "targetTypeOnlyExports": {
+                "type": "boolean"
+              },
+              "sourcePureTypeModule": {
+                "type": "boolean"
+              },
+              "namedBindingsTypeOnly": {
+                "type": "boolean"
+              },
+              "portProofEligible": {
+                "type": "boolean"
+              },
+              "peerIsolation": {
+                "type": "boolean"
+              },
+              "capability": {
+                "type": "string",
+                "minLength": 1
+              },
+              "edgeKind": {
+                "type": "string",
+                "minLength": 1
               }
             }
           },

package/schemas/ark.design-delta.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://unpkg.com/arkgate@3/schemas/ark.design-delta.schema.json","title":"ArkGate design delta","type":"object","additionalProperties":false,"required":["schemaVersion","mode","complete","valid","base","candidate","supportedSmellIds","touchedPaths","changes","baseFindingCount","candidateFindingCount","historicalResidualCount"],"properties":{"schemaVersion":{"const":"1.0"},"mode":{"enum":["git-base","write-candidate"]},"complete":{"type":"boolean"},"valid":{"type":"boolean"},"base":{"$ref":"#/$defs/identity"},"candidate":{"$ref":"#/$defs/identity"},"supportedSmellIds":{"type":"array","items":{"const":"domain-logic-in-ui"},"minItems":1,"uniqueItems":true},"touchedPaths":{"type":"array","items":{"type":"string","minLength":1},"uniqueItems":true},"changes":{"type":"array","items":{"$ref":"#/$defs/change"}},"baseFindingCount":{"type":"integer","minimum":0},"candidateFindingCount":{"type":"integer","minimum":0},"historicalResidualCount":{"type":"integer","minimum":0},"error":{"type":"string","minLength":1}},"$defs":{"identity":{"type":"object","additionalProperties":false,"required":["kind","value"],"properties":{"kind":{"enum":["git-tree","candidate-tree"]},"value":{"type":"string","minLength":1},"commit":{"type":"string","minLength":1}}},"evidence":{"type":"object","additionalProperties":false,"required":["kind","path","magnitude"],"properties":{"kind":{"type":"string","minLength":1},"path":{"type":"string","minLength":1},"line":{"type":"integer","minimum":1},"symbol":{"type":"string","minLength":1},"detail":{"type":"string","minLength":1},"magnitude":{"type":"number","minimum":0}}},"finding":{"type":"object","required":["smellId","fingerprint","identity","evidence","repairHint"],"properties":{"smellId":{"enum":["io-under-application","handler-in-persistence","god-module","domain-logic-in-ui","facade-sql-in-routes","mixed-pattern-cluster","soft-contract"]},"fingerprint":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"identity":{"type":"string","minLength":1},"evidence":{"$ref":"#/$defs/evidence"},"repairHint":{"type":"string","minLength":1}}},"change":{"type":"object","unevaluatedProperties":false,"allOf":[{"$ref":"#/$defs/finding"},{"type":"object","required":["classification","baseMagnitude","candidateMagnitude"],"properties":{"classification":{"enum":["new","worsened"]},"baseMagnitude":{"type":"number","minimum":0},"candidateMagnitude":{"type":"number","minimum":0}}}]}}}

package/schemas/ark.enforcement-state.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@3/schemas/ark.enforcement-state.schema.json",
+  "title": "ArkGate enforcement state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "activeHost",
+    "localWrite",
+    "advisoryMcp",
+    "ciMerge"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.1" },
+    "activeHost": {
+      "enum": ["claude", "grok", "cursor", "codex", "unknown"]
+    },
+    "localWrite": { "$ref": "#/$defs/boundary" },
+    "advisoryMcp": { "$ref": "#/$defs/boundary" },
+    "ciMerge": { "$ref": "#/$defs/boundary" }
+  },
+  "$defs": {
+    "verification": {
+      "anyOf": [{ "type": "boolean" }, { "const": "unverified" }]
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["field", "source", "value"],
+      "properties": {
+        "field": {
+          "enum": ["configured", "installed", "active", "runtimeObserved", "operationCoverage", "bypassable", "required", "hard"]
+        },
+        "source": { "type": "string", "minLength": 1 },
+        "value": { "$ref": "#/$defs/verification" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "field": { "enum": ["configured", "installed", "runtimeObserved", "hard"] } },
+            "required": ["field"]
+          },
+          "then": { "properties": { "value": { "type": "boolean" } } }
+        }
+      ]
+    },
+    "boundary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "supported",
+        "analyzed",
+        "configured",
+        "installed",
+        "active",
+        "runtimeObserved",
+        "operation",
+        "operationCoverage",
+        "bypassable",
+        "required",
+        "hard",
+        "evidence"
+      ],
+      "properties": {
+        "supported": { "type": "boolean" },
+        "analyzed": { "type": "boolean" },
+        "configured": { "type": "boolean" },
+        "installed": { "type": "boolean" },
+        "active": { "$ref": "#/$defs/verification" },
+        "runtimeObserved": { "type": "boolean" },
+        "operation": { "type": ["string", "null"] },
+        "operationCoverage": { "$ref": "#/$defs/verification" },
+        "bypassable": { "$ref": "#/$defs/verification" },
+        "required": { "$ref": "#/$defs/verification" },
+        "hard": { "type": "boolean" },
+        "evidence": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/evidence" }
+        }
+      }
+    }
+  }
+}

package/schemas/ark.resolved-candidate-facts.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://unpkg.com/arkgate@3/schemas/ark.resolved-candidate-facts.schema.json","title":"ArkGate resolved candidate facts","type":"object","additionalProperties":false,"required":["schemaVersion","completeness","completenessReasons","resolverIdentity","compilerIdentity","compilerOptionsHash","tsconfigHash","candidateTreeHash","evidenceRequirementsHash","files","dependencies","capabilityUses","ambientUses","publishCalls","intentReferences","safetyUses","factsHash"],"properties":{"schemaVersion":{"const":"1.0"},"completeness":{"enum":["complete","partial","unavailable"]},"completenessReasons":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"file":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"}}}},"resolverIdentity":{"type":"string","minLength":1},"compilerIdentity":{"type":"string","minLength":1},"compilerOptionsHash":{"type":"string","minLength":1},"tsconfigHash":{"type":"string","minLength":1},"candidateTreeHash":{"type":"string","minLength":1},"evidenceRequirementsHash":{"type":"string","minLength":1},"projectPackageName":{"type":"string","minLength":1},"files":{"type":"array","uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["path","contentHash","parseStatus","parseDiagnosticCount","exportsOnlyTypes","typeOnlyExportNames","hasTopLevelSideEffects"],"properties":{"path":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"contentHash":{"type":"string","minLength":1},"parseStatus":{"enum":["parsed","invalid"]},"parseDiagnosticCount":{"type":"integer","minimum":0},"exportsOnlyTypes":{"type":"boolean"},"typeOnlyExportNames":{"type":"array","items":{"type":"string","minLength":1}},"hasTopLevelSideEffects":{"type":"boolean"}},"allOf":[{"if":{"properties":{"parseStatus":{"const":"parsed"}}},"then":{"properties":{"parseDiagnosticCount":{"const":0}}}},{"if":{"properties":{"parseStatus":{"const":"invalid"}}},"then":{"properties":{"parseDiagnosticCount":{"minimum":1}}}}]}},"dependencies":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","kind","typeOnly","line","resolution"],"properties":{"from":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"specifier":{"type":"string","minLength":1},"kind":{"enum":["import","export","dynamic-import","require"]},"typeOnly":{"type":"boolean"},"line":{"type":"integer","minimum":1},"resolution":{"enum":["resolved-project","resolved-external","unresolved","dynamic"]},"target":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"namedBindings":{"type":"array","items":{"type":"string","minLength":1}},"targetTypeOnlyExports":{"type":"boolean"},"sourcePureTypeModule":{"type":"boolean"},"namedBindingsTypeOnly":{"type":"boolean"},"portProofEligible":{"type":"boolean"}},"allOf":[{"if":{"properties":{"resolution":{"const":"resolved-project"}}},"then":{"required":["target"]},"else":{"not":{"required":["target"]}}},{"if":{"properties":{"resolution":{"const":"dynamic"}}},"else":{"required":["specifier"]}}]}},"capabilityUses":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["file","line","symbol","capability","source"],"properties":{"file":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"line":{"type":"integer","minimum":1},"symbol":{"type":"string","minLength":1},"capability":{"enum":["network","filesystem","clock","randomness","environment","process","persistence"]},"source":{"enum":["ambient-global","import-based"]}}}},"ambientUses":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["file","line","symbol"],"properties":{"file":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"line":{"type":"integer","minimum":1},"symbol":{"type":"string","minLength":1}}}},"publishCalls":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["file","line","objectHasIntent","arkPublishCandidate","hasSource"],"properties":{"file":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"line":{"type":"integer","minimum":1},"rawIntentName":{"type":"string","minLength":1},"objectHasIntent":{"type":"boolean"},"arkPublishCandidate":{"type":"boolean"},"hasSource":{"type":"boolean"},"sourceIntent":{"type":"string","minLength":1}}}},"intentReferences":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["file","line","intent"],"properties":{"file":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"line":{"type":"integer","minimum":1},"intent":{"type":"string","minLength":1}}}},"safetyUses":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["file","line","kind"],"properties":{"file":{"type":"string","minLength":1,"pattern":"^(?!/)(?![A-Za-z]:/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*[\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"},"line":{"type":"integer","minimum":1},"kind":{"enum":["ts-suppression","any-cast","dynamic-import","dynamic-require","in-memory-store"]},"symbol":{"type":"string","minLength":1}},"allOf":[{"if":{"properties":{"kind":{"const":"in-memory-store"}}},"then":{"required":["symbol"]},"else":{"not":{"required":["symbol"]}}}]}},"factsHash":{"type":"string","minLength":1}},"allOf":[{"if":{"properties":{"completeness":{"const":"complete"}}},"then":{"properties":{"completenessReasons":{"maxItems":0},"files":{"items":{"properties":{"parseStatus":{"const":"parsed"}}}}}}},{"if":{"properties":{"completeness":{"enum":["partial","unavailable"]}}},"then":{"properties":{"completenessReasons":{"minItems":1}}}}]}

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "3.7.0",
+  "version": "3.8.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.7.0",
+      "version": "3.8.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-explore.md

@@ -60,7 +60,7 @@ say so in one line and hand off `stop`.
 |------|------|-------------|
 | **Recon (default)** | map / residual / “what next?” / bare `/ark-explore` | Headline → map → ranked table → **Top 3** → residue → Completion |
 | **Dual-plan seed** | user asks for a **plan**, mejora, roadmap, “Ark + patrón”, **or** spaghetti signals fire (§G) | Same recon **plus** **§ Dual-plan seed** (A + B). **Cap 3–5 B bets.** |
-| **Shape-focus** | plan A already empty / ENFORCE, user wants **pattern** depth only | Abbreviated map + **mandatory** concurrent-patterns table + B bets only (A = “goal.met / empty”) |
+| **Shape-focus** | plan A already empty / ENFORCE, `plan.completeness` is `complete`, user wants **pattern** depth only | Abbreviated map + **mandatory** concurrent-patterns table + B bets only (A = “goal.met / empty”) |
 
 **Auto-upgrade:** if §G spaghetti signals fire, you **must** use dual-plan seed or shape-focus
 — never end on recon-only with “layers are clean.”
@@ -75,7 +75,7 @@ say so in one line and hand off `stop`.
 
 | Section | Content |
 |---------|---------|
-| **A. Remediation** | From `--plan` — usually empty when ENFORCE; one line if so |
+| **A. Remediation** | From `--plan` — usually empty when ENFORCE; one line if so. Empty counts only when `plan.completeness === "complete"` |
 | **B. Pattern / evolution** | **3–5** bets max; each: evidence · así te lo re-soluciono · **success signal** · next skill · **pilot** · **kill-switch** if new layer/big move |
 | **Phase ladder** | Name which of Align / Stabilize / **Shape** the repo is in (§G) |
 
@@ -123,7 +123,7 @@ Useful split: **core product tree** | **field path** (`examples/`, starters) | *
 6. **§G spaghetti / design-depth** when signals fire (or always on brownfield).
 7. Ranked rows that **change a decision**; each bet has a **success signal** (not a file count).
 8. Hard lines: never weaken the contract; never invent mechanical-safe kinds; never claim ENFORCE from type-only cleanup while false-green doctor ids are active.
-9. **Parse honesty:** if `doctor.parseHealth.affectedFiles > 0`, open and name those paths; never describe them as clean or successfully inspected. The advisory does not change the gate verdict.
+9. **Parse honesty:** require `plan.completeness === "complete"` before accepting `goal.met`. If `doctor.parseHealth.affectedFiles > 0`, open and name those paths; never describe them as clean or successfully inspected. Doctor alone does not change the gate verdict, but check/plan completeness is `partial`, plan goal is false, and strict merge fails.
 
 ## Reconnaissance pass (do all that apply)
 
@@ -202,7 +202,7 @@ Prefer bets the user can run next (`command` / skill), not vague “improve DX
 ### G. Spaghetti / design-depth ladder (non-deterministic path — mandatory when signals fire)
 
 **Signals (any one → dual-plan seed or shape-focus):**
-- Plan A empty / `goal.met` **and** you still see design-weak / concurrent patterns / god modules.
+- Plan A empty / `goal.met` with `completeness: complete` **and** you still see design-weak / concurrent patterns / god modules.
 - Brownfield with mixed layouts (flat services + “hex” folders + feature dumps).
 - Semantic false-green (path-correct, design-wrong).
 - User words: spaghetti, monstruo, legacy, “está enforce pero horrible”, pattern, refactor shape.
@@ -275,7 +275,7 @@ Kinds: `risk` | `false-green` | `debt` | `opportunity` | `shape` | `manifiesto`
    On false-green dominant: **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`.
    On concentrated edge dominant: **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).
 7. **Dual-plan seed** — required in dual-plan seed / shape-focus (and when §G auto-upgrades); A + B cap 3–5; extraction cards for I/O bets.
-8. **Deterministic residue** — plan steps, violations, doctor top action. Point to `/ark-loop` / `/ark-fix` **only when A steps exist**; never pretend loop is the architecture story when goal is already met.
+8. **Deterministic residue** — plan completeness, steps, violations, doctor top action. Point to `/ark-loop` / `/ark-fix` **only when A steps exist**; never call a `partial`/`unavailable` plan met, and never pretend loop is the architecture story when a complete goal is already met.
 
 Optional: **Diff vs naive sensor-only read** (what reading the tree changed).
 

package/templates/skills/ark-fix.md

@@ -18,7 +18,7 @@ the two files on the violation edge.
 | Judgment design for a known violation | Contract wrong / false-green → STOP to `/ark-contract` / `/ark-adopt` |
 
 When the fix is really a **Shape** extraction (I/O out of routes, god module split), write an
-**extraction card** before editing — same template as [brownfield-adoption.md](../../docs/brownfield-adoption.md)
+**extraction card** before editing — same template as `docs/brownfield-adoption.md`
 §6 and explore §G. Fixed fields (never mechanical-safe, never silent B apply):
 
 ```text

package/templates/skills/ark-runtime.md

@@ -8,11 +8,12 @@ description: Evaluate the experimental Ark runtime kernel against hand-rolled ev
 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.
 
-`arkgate` ships the experimental runtime kernel
+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. This skill migrates hand-rolled versions of those to the
-kernel, one feature at a time.
+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)
 
@@ -41,20 +42,25 @@ the same files or weaken the gate.
    - 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/nestjs`
+   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. **Migrate** — import from `arkgate/runtime` (preferred experimental subpath) or
-   `arkgate/nestjs`, and read the package's `docs/agent-guide.md`
-   (in `node_modules/arkgate/docs/`) for the runtime API before
+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.
-4. **Delete the hand-rolled version** once call sites are moved — the point is
+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
@@ -63,6 +69,7 @@ the same files or weaken the gate.
 ## 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