arkgate 3.9.2 → 4.0.1

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>`
 

package/templates/skills/ark-upgrade.md

@@ -19,9 +19,34 @@ Use the semantic sensor (`ark-check --doctor --json` plus the strict contract
 check) and direct inspection of every managed file the preview will change.
 Neither signal replaces the other.
 
+
+## 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`.
+
+
+### Upgrade + ArkRules
+- Refresh skills + note if templates gained ArkRules deepen; do not force consumers to adopt `arkRules`.
+- After upgrade: doctor `rulesUnderContract` if map exists; dual-truth note if `--no-install` left package pin old.
+
 ## Safety contract
 
-- `ark upgrade` is read-only. It reports the selected profile and hosts, every
+- Always invoke the **project-local** CLI (`npx arkgate` /
+  `node node_modules/arkgate/bin/ark.mjs`). Bare PATH `ark` / `arkgate` is unsafe
+  when a global 2.x install shadows the project (mutative legacy upgrade).
+- `ark upgrade` (managed era) is read-only. It reports the selected profile and hosts, every
   managed asset, its content state, and the exact next command.
 - The first `ark upgrade --apply` updates the dependency and lockfile, then runs
   the newly installed CLI to produce another read-only preview. It does **not**
@@ -50,16 +75,54 @@ Neither signal replaces the other.
 
 ## Procedure
 
-1. **Establish versions and context.** Read the installed
+1. **Resolve the project CLI (mandatory before any upgrade command).** Prefer the
+   **project-local** binary — never bare `ark` / `arkgate` from PATH unless you
+   prove it is this project's install.
+
+   Resolution order:
+
+   1. `node node_modules/arkgate/bin/ark.mjs` from the repository root (both `arkgate`
+      and `ark` package bins map to this file).
+   2. Package-manager exec from the project: `npx arkgate`, `pnpm exec arkgate`,
+      `yarn arkgate`, etc.
+
+   **Do not** use bare `ark` / `arkgate` from PATH unless `which ark` (or the
+   resolved realpath) is under this project's `node_modules/arkgate`, or the
+   binary reports the **same** version as `node_modules/arkgate/package.json` and
+   supports managed upgrade.
+
+   **Capability probe (abort if missing):** run
+   `node node_modules/arkgate/bin/ark.mjs upgrade --help` (or the resolved local
+   equivalent) and require a **managed upgrade** surface — help text must mention
+   `--plan-digest` (and read-only `upgrade --json` preview). If the only available
+   CLI is old (global Homebrew / npm global 2.x, or any binary whose help lacks
+   `--plan-digest`), **stop**: skill incomplete; do **not** preview or apply.
+   Global 2.x `ark upgrade` is mutative and can rewrite managed skills, forcing a
+   later `--accept-conflicts` recovery.
+
+   **Recovery (preferred → optional):**
+
+   - Preferred: package-manager runner from project / `--root`
+     (`npx arkgate upgrade …` / `pnpm exec arkgate upgrade …` / `yarn arkgate upgrade …`).
+     This works when arkgate is **hoisted** and a nested package has no shallow
+     `node_modules/arkgate`.
+   - Secondary: `node node_modules/arkgate/bin/ark.mjs upgrade …` from the
+     **workspace install root** (not a nested package lacking a local install).
+   - Optional: refresh a global install with `npm i -g arkgate@latest` only if the
+     user wants a global binary; still prefer project-local for this procedure.
+
+   Record the resolved CLI path/version, read
    `node_modules/arkgate/package.json`, query `npm view arkgate version`, identify
    the repository package manager, and open the intervening entries in the
    shipped `CHANGELOG.md` (fall back to registry or release notes and name that
    source). Do not infer “latest” from `node_modules` alone.
 
-2. **Preview managed content.** Run:
+2. **Preview managed content.** Using the **project-local** CLI from step 1
+   (never a bare PATH `ark` that failed the probe), run:
 
    ```bash
-   ark upgrade --json
+   npx arkgate upgrade --json
+   # or: node node_modules/arkgate/bin/ark.mjs upgrade --json
    ```
 
    Pass `--root <path>` and `--tools <active-host>` when selection would otherwise
@@ -67,10 +130,10 @@ Neither signal replaces the other.
    that customized files remain non-applying and that any deletion/conflict is
    blocked.
 
-3. **Update and re-preview.** If the registry is newer, run:
+3. **Update and re-preview.** If the registry is newer, run (project-local CLI):
 
    ```bash
-   ark upgrade --apply
+   npx arkgate upgrade --apply
    ```
 
    This updates through the detected package manager and hands control to the new
@@ -83,20 +146,25 @@ Neither signal replaces the other.
    off, and prove `pnpm install --frozen-lockfile` succeeds.
 
 4. **Apply only the reviewed candidate.** When there are no blocked assets, run
-   the preview's exact `nextCommand`, whose shape is:
+   the preview's **exact** `nextCommand` as emitted (JSON field / human “Apply the
+   exact preview with: …”). That command is already **project-local**
+   (`npx arkgate` / `pnpm exec arkgate` / `yarn arkgate` — never bare PATH `ark`).
+   Do **not** rewrite it to bare `ark upgrade`; pasting through a global 2.x PATH
+   reintroduces the mutative footgun. Shape:
 
    ```bash
-   ark upgrade --apply --no-install --plan-digest <preview-digest>
+   npx arkgate upgrade --apply --no-install --plan-digest <preview-digest>
    ```
 
    If recorded deletion/conflict recovery is desired, ask first and then add
    `--accept-conflicts`. Never add it merely to make the run green. Run a second
    preview and require `summary.changed: 0`.
 
-5. **Verify enforcement and architecture.** Run `ark-check --doctor --json` and
+5. **Verify enforcement and architecture.** Run
+   `npx arkgate-check --doctor --json` (or the project-local `ark-check`) and
    the same fail-closed architecture command used by managed apply (normally
-   `ark-check --root . --config ark.config.json --strict-merge --json`). Require
-   `completeness: "complete"` and `ok: true`. Treat provider-unavailable CI
+   `npx arkgate-check --root . --config ark.config.json --strict-merge --json`).
+   Require `completeness: "complete"` and `ok: true`. Treat provider-unavailable CI
    required-check evidence as `unverified`, never as proof that merges are
    blocked. If new violations appear, hand off to `/ark-fix` for a small set or
    `/ark-loop` / `/ark-autopilot` for residual debt; do not regenerate a baseline
@@ -133,6 +201,7 @@ End with exactly this structure:
 - **Active host:** host and verified status
 - **Deferred hosts:** `none` or host plus future action
 - **Result:** old → new version and managed-upgrade outcome
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Handoff:** `/ark-…`, CLI action, or `none`
 - **Incomplete?** `no` or `yes — <missing work>`
 

package/compat/nestjs.cjs

@@ -1,2 +0,0 @@
-'use strict';
-module.exports = require('@arkgate/runtime/nestjs');

package/compat/nestjs.d.ts

@@ -1,2 +0,0 @@
-/** @deprecated Install `@arkgate/runtime` and import from `@arkgate/runtime/nestjs`. */
-export * from '@arkgate/runtime/nestjs';

package/compat/nestjs.js

@@ -1 +0,0 @@
-export * from '@arkgate/runtime/nestjs';

package/compat/runtime.cjs

@@ -1,2 +0,0 @@
-'use strict';
-module.exports = require('@arkgate/runtime');

package/compat/runtime.d.ts

@@ -1,2 +0,0 @@
-/** @deprecated Install and import from `@arkgate/runtime`. This shim is removed in ArkGate 4. */
-export * from '@arkgate/runtime';

package/compat/runtime.js

@@ -1 +0,0 @@
-export * from '@arkgate/runtime';