arkgate 2.3.0 → 2.5.0

package/docs/agent-guide.md

@@ -1,7 +1,11 @@
-# Ark — Agent Integration Guide
+# ArkGate — Agent Integration Guide
 
-**Ark — Architecture Co-pilot for AI TypeScript.** This guide describes how AI agents
-and codegen tools can safely interact with the write gate, MCP tools, and `/ark-*` skills.
+**ArkGate** (`arkgate`) — architecture co-pilot for AI TypeScript. This guide describes how AI
+agents and codegen tools safely interact with the write gate, MCP tools, and `/ark-*` skills.
+
+CLI names: prefer **`arkgate` / `arkgate-check` / `arkgate-mcp`**; aliases `ark` / `ark-check` /
+`ark-mcp` still work for one major. TypeScript **5.x / 6.x / 7.x** as the project compiler:
+see [typescript-support.md](typescript-support.md).
 
 ## Architecture playbook and `ark-check --recommend`
 
@@ -120,7 +124,8 @@ directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`
 Wire write-gate + MCP + `/ark-*` skills with:
 
 ```bash
-npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+# alias: npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
 ```
 
 | Host | Write gate | MCP | Skills path |
@@ -333,7 +338,7 @@ layers, unclassified included files, unmatched layer patterns, duplicate layers,
 that reference unknown layers. These are advisory by default. Use `--strict-config` once a
 project is ready to fail CI on coverage gaps.
 
-Use the optional ESLint plugin for fast local feedback:
+Use the optional ESLint plugin for fast local feedback aligned with CI:
 
 ```js
 import ark from 'arkgate/eslint';
@@ -343,8 +348,9 @@ export default [
 ];
 ```
 
-Rules: `ark/no-domain-infra-imports`, `ark/no-raw-event-publish`, and
-`ark/require-publish-source`.
+Rules: `ark/no-domain-infra-imports` (layer edges from `ark.config.json`, same semantics as
+`arkgate-check`), `ark/no-forbidden-globals` (per-layer `forbiddenGlobals`),
+`ark/no-raw-event-publish`, and `ark/require-publish-source`. See [ai-gates.md](ai-gates.md).
 
 ## Runtime Observability
 
@@ -424,7 +430,8 @@ not replace your web framework, HTTP clients, or job scheduler.
 ## Write-Path Gate (MCP)
 
 The strongest place to constrain an AI agent is the moment it writes a file, not after.
-`ark-mcp` exposes Ark over MCP (zero dependencies, JSON-RPC over stdio) so a host can gate
+`arkgate-mcp` / `ark-mcp` exposes ArkGate over MCP (JSON-RPC over stdio; gate host needs a
+JS-API TypeScript — nested or project) so a host can gate
 the write path:
 
 ```bash

package/docs/ai-gates.md

@@ -1,32 +1,36 @@
-# Gating AI Agents with Ark
+# Gating AI Agents with ArkGate
 
-**Ark** is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
+**ArkGate** (`arkgate`) is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
 The write-path gate is what makes it different from every other architecture linter:
 generated code is validated against your architecture **before it lands on disk**, not
 after the PR is red.
 
-Everything below uses the same `ark.config.json` as `ark-check` (CI) — one contract, enforced everywhere. Generate it once:
+Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
+contract, enforced everywhere. Generate it once:
 
 ```bash
-npx ark-check --init
+npx arkgate-check --init
+# aliases: ark-check, ark init, arkgate start
 ```
 
 For guided setup with prompts, use:
 
 ```bash
-npx ark init
+npx arkgate start
+# or: npx ark init
 ```
 
 For non-interactive defaults, use:
 
 ```bash
-npx ark init --yes
+npx arkgate start --yes
+# or: npx ark init --yes
 ```
 
 You can also generate only the starter gate files for common agent runtimes and CI:
 
 ```bash
-npx ark-check --install-agent-gates
+npx arkgate-check --install-agent-gates
 ```
 
 The command writes templates for `.mcp.json`, Claude hooks, Cursor MCP/rules,
@@ -279,47 +283,33 @@ If your runtime can run a shell command before file writes and pass the tool pay
 - Grok payloads also get `{ "decision": "deny", "reason": "…" }` on stdout when blocked
 - plumbing problems (no stdin, non-source files, files outside `--root`) never block
 
-## ESLint (editor feedback)
+## ESLint (editor feedback) — same contract as CI
 
-For in-editor red squiggles on layer violations, add the ESLint plugin. It ships a
-flat-config preset you can spread directly:
+For in-editor red squiggles that match **`arkgate-check`**, add the ESLint plugin.
+Layer imports and purity globals are driven by **`ark.config.json`** (walk-up from the
+linted file): same layer globs, specificity, `exclude`, and `rules[]` edges as the CI gate.
 
 ```js
 // eslint.config.js  (flat config)
 import ark from 'arkgate/eslint';
 
 export default [
-  ark.configs.recommended,   // ark/no-domain-infra-imports, no-raw-event-publish, require-publish-source
+  ark.configs.recommended,
+  // no-domain-infra-imports  → config-driven layer edges (type-only + value)
+  // no-forbidden-globals     → layer.forbiddenGlobals from ark.config.json
+  // no-raw-event-publish + require-publish-source → runtime event hygiene
 ];
 ```
 
-`recommended` deliberately omits **`ark/no-forbidden-globals`** (domain purity: no
-`fetch`, `Date.now`, `Math.random`, …). That rule is only correct when scoped to your
-domain directories — a global block would flag legitimate infrastructure code. Add it
-as its own block with a `files` glob matching your `DomainModel` layer:
-
-```js
-import ark from 'arkgate/eslint';
+**Parity notes (2.5+):**
 
-export default [
-  ark.configs.recommended,
-  {
-    files: ['packages/*/domain/**', 'src/**/domain/**'],  // your DomainModel layer paths
-    plugins: { ark },
-    rules: {
-      'ark/no-forbidden-globals': [
-        'error',
-        { globals: ['fetch', 'process', 'Date.now', 'Math.random'] },  // match ark.config.json
-      ],
-    },
-  },
-];
-```
+- Relative imports are resolved to on-disk TS/JS targets; package bare imports are left to CI/TS.
+- Type-only and value forbidden edges both error (same pass/fail as `arkgate-check`).
+- `no-forbidden-globals` only applies when the file’s layer declares `forbiddenGlobals` (or you pass a `globals` option). Layers without a purity list are not inventively restricted.
+- Without `ark.config.json`, `no-domain-infra-imports` falls back to a domain→infra path heuristic.
 
-Rule ids are `ark/<kebab-name>`. Keep the `globals` list in sync with the
-`forbiddenGlobals` on your `DomainModel` layer in `ark.config.json` so the editor and
-`ark-check` agree. All four rules are exported individually too (`ark.rules`) if you
-prefer to wire them by hand.
+Rule ids are `ark/<kebab-name>`. Individual rules are also on `ark.rules` if you wire them by hand.
+Prefer keeping editor + CI on the same `ark.config.json` — do not maintain a parallel globals list unless you intentionally override.
 
 ## CI backstop
 

package/docs/brownfield-adoption.md

@@ -61,19 +61,20 @@ violations — the ratchet only moves toward zero.
 
 ## 5. Burn down, in order
 
-`summary.edges` is the burn-down order. Two patterns cover most of it — and Ark tells you
-which is which via the `typeOnly` tag (value = real coupling, fix first; type-only = placement):
-
-- **Type-only inversion** (a lower layer `import type`s a type that lives in an upper layer):
-  move the type down to the layer that owns it and re-export it from the original module for
-  back-compat. Cosmetic at runtime, `tsc`-verifiable, safe to sweep. (Not mechanical if the
-  type extends a persistence/ORM row — that needs a domain-owned type/port — or if the source
-  file mixes types with logic — split first.)
-- **Raw infrastructure access** (a route/handler running SQL or importing the DB directly):
-  relocate the data-access **verbatim** into a repository/adapter method the route calls. Same
-  query bytes = same behavior; do NOT rewrite the query. This edits the data layer — if your
-  repo reserves that to core maintainers, migrate one route as a demonstrated pattern and hand
-  the bulk over; a route with interleaved transactions isn't a pure relocation, so flag it.
+`summary.edges` is the burn-down order. Prefer `ark-check --plan`: it tags each step
+`mechanical-safe` / `judgment` / `deferred` and sets `remediationKind` for auto-safe cases.
+
+- **Type-only inversion** (`typeOnly` — plan: `type-only-import-move`): move the type to the
+  owning layer + re-export for back-compat. Safe to sweep when mechanical-safe.
+- **Pure-type file** (`sourcePureTypeModule` — plan: `pure-type-file-relocate`): whole file is
+  type-surface only — relocate the file (or extract types) to the owning layer.
+- **Value import of pure type module** (`targetTypeOnlyExports` — plan:
+  `import-type-from-pure-type-module`): convert static import to `import type`. Not safe for
+  `require()` / dynamic `import()`.
+- **Raw infrastructure access** (value coupling — always **judgment**): relocate data-access
+  **verbatim** into a repository/adapter. Same query bytes = same behavior; do NOT rewrite the
+  query. If CODEOWNERS reserves the data layer, migrate one route as a pattern and hand bulk
+  work over; interleaved transactions aren't a pure relocation — flag them.
 
 `/ark-fix` resolves each cluster at the root cause; fixing a frozen violation shrinks the
 baseline permanently. Re-freeze lower with `--update-baseline` as you go.

package/docs/demos/03-copilot-autopilot.md

@@ -39,9 +39,11 @@ npx ark-check --plan            # human view (includes Governed: N%)
 npx ark-check --plan --json     # { ok, plan: { goal, counts, steps } }
 ```
 
-Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence` and a
-plain-language `rationale`. `goal.met` is true only when there are no active violations **and**
-governed coverage is meaningful — so a clean plan that checks almost nothing is not "done."
+Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence`,
+`rationale`, and often `remediationKind`. Only three kinds are auto-safe: type-only type move,
+pure-type **file** relocate, and `import type` of pure-type modules. `goal.met` is true only when
+there are no active violations **and** governed coverage is meaningful — so a clean plan that
+checks almost nothing is not "done."
 
 ### 3. Carry the plan out — the autopilot
 

package/docs/enthusiast/README.md

@@ -1,10 +1,11 @@
-# Ark — Architecture Co-pilot (enthusiast track)
+# ArkGate — Architecture Co-pilot (enthusiast track)
 
 Plain-language onboarding for builders who use AI agents but are not professional
 developers. This track follows [Diátaxis](https://diataxis.fr/): tutorial, how-to,
-reference, and explanation.
+reference, and explanation. Package: **`arkgate`** (CLI: `arkgate` / `arkgate-check`;
+aliases `ark` / `ark-check` still work).
 
-## How Ark talks to you (2.0)
+## How ArkGate talks to you
 
 **Entry style** — who is driving: *newbie* (`ark start` / `/ark-autopilot`) vs *expert* (individual commands).
 

package/docs/enthusiast/how-to-agent-gates.md

@@ -1,15 +1,17 @@
 # How to install agent gates
 
 ```bash
-npx ark-check --install-agent-gates
-npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
+npx arkgate-check --install-agent-gates
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+# aliases: ark-check …
 ```
 
 Installs:
 
 - Write-gate hook configuration (Claude / Grok PreToolUse; Cursor advisory + MCP)
 - MCP server entry (`.mcp.json`, Cursor/Codex/Grok equivalents)
-- `/ark-*` skills including **`/ark-architect`** and **`/ark-autopilot`**
+- `/ark-*` skills including **`/ark-architect`**, **`/ark-autopilot`**, **`/ark-loop`**
+  (with current `mechanical-safe` remediation kinds)
 
 | Host | Extra paths |
 |------|-------------|
@@ -20,7 +22,7 @@ Installs:
 
 ## Session hint
 
-`ark-mcp --session-context` appends when governed coverage is low:
+`arkgate-mcp --session-context` appends when governed coverage is low:
 
 ```
 New to Ark? Run /ark-architect or: ark-check --recommend
@@ -29,8 +31,14 @@ New to Ark? Run /ark-architect or: ark-check --recommend
 ## Verify gates
 
 ```bash
-npx ark-check --doctor
-npx ark-check --require-gates
+npx arkgate-check --doctor
+npx arkgate-check --require-gates
+```
+
+After upgrading the package, refresh skills so agents see the latest plan kinds:
+
+```bash
+npx arkgate-check --install-agent-gates --skills-only --force
 ```
 
 Full copy-paste setups: [docs/ai-gates.md](../ai-gates.md).

package/docs/enthusiast/reference-commands.md

@@ -1,9 +1,13 @@
 # Reference: commands and artifacts
 
+Product: **ArkGate** (`arkgate`). Prefer `arkgate` / `arkgate-check` / `arkgate-mcp`; aliases
+`ark` / `ark-check` / `ark-mcp` work for one major. TypeScript 5–7: [typescript-support.md](../typescript-support.md).
+
 ## Recommendation
 
 ```bash
-ark-check --recommend [--json] [--write-plan]
+arkgate-check --recommend [--json] [--write-plan]
+# alias: ark-check …
 ```
 
 MCP: `ark_recommend` — same JSON body.
@@ -33,18 +37,29 @@ Pack metadata: `templates/policy-packs/enthusiast-*.json`.
 ## Init and verify
 
 ```bash
-ark init --archetype <id> --yes
-ark-check --doctor [--json]
-ark-check --coverage [--json]
-ark-check --strict-config
-ark-check --report out.html --beginner
-ark-check --watch
+arkgate start --yes                    # guided setup + plan
+ark init --archetype <id> --yes        # alias path
+arkgate-check --doctor [--json]
+arkgate-check --coverage [--json]
+arkgate-check --plan [--json]          # mechanical-safe vs judgment vs deferred
+arkgate-check --strict-config
+arkgate-check --report out.html --beginner
+arkgate-check --watch
 ```
 
+## Plan classes (`--plan --json`)
+
+| `class` | Agent may auto-apply? | Examples (`remediationKind`) |
+|---------|----------------------|------------------------------|
+| `mechanical-safe` | Yes (validate + rollback) | `type-only-import-move`, `pure-type-file-relocate`, `import-type-from-pure-type-module` |
+| `judgment` | No — propose | value imports, ports, infra relocate, cycles |
+| `deferred` | No | unclear shape |
+
 ## Violation JSON (enthusiast fields)
 
 When present on violations:
 
 - `fixClass` — e.g. `port-inversion`, `file-move`
 - `effort` — `small` | `medium`
-- `enthusiastHint` — plain English fix guidance
+- `enthusiastHint` — plain English fix guidance
+- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`

package/docs/migrate-from-ark-runtime-kernel.md

@@ -42,6 +42,24 @@ npx arkgate upgrade
 
 (`ark upgrade` works too — both install `arkgate@latest` and refresh gates.)
 
+### TypeScript 7
+
+If the project uses **TypeScript 7** as `tsc`, the gate still works: ArkGate embeds a JS-API
+TypeScript host and falls back when `require('typescript')` is version-only. See
+[typescript-support.md](typescript-support.md). Optional dual-install (TS 6 for tools + TS 7
+CLI) is documented there.
+
+### MCP args (avoid double binary)
+
+`.mcp.json` / `.cursor/mcp.json` must look like:
+
+```json
+"args": ["arkgate-mcp", "--root", ".", "--config", "ark.config.json"]
+```
+
+**Not** `["ark-mcp", "arkgate-mcp", …]` — that breaks MCP stdio. Fixed by
+`npx arkgate-check --install-agent-gates --migrate-commands` (ArkGate ≥ 2.4.0).
+
 ---
 
 ## What to change in your repo

package/docs/typescript-support.md

@@ -0,0 +1,142 @@
+# TypeScript support (5.x · 6.x · 7.x)
+
+ArkGate’s architecture gate (`arkgate-check` / `ark-mcp`) needs a **JavaScript API**
+TypeScript package that exposes:
+
+- `ts.sys` (at least `fileExists`)
+- `createSourceFile` (AST)
+- `resolveModuleName` (module graph)
+
+It does **not** require the Go-native `tsc` binary for the gate. Type-checking
+semantics of your app still come from **your** project `typescript` + `tsconfig`.
+
+## Supported versions
+
+| Range | Status |
+|-------|--------|
+| **TypeScript 5.x** | Fully supported (primary CI) |
+| **TypeScript 6.x** | Supported (bridge release before 7) |
+| **TypeScript 7.x** | Supported as **project** compiler; gate loads project TS when API-compatible, otherwise **falls back** to a JS-API TypeScript |
+
+Optional peer (documentational):
+
+```json
+"peerDependencies": {
+  "typescript": ">=5.0.0 <8"
+}
+```
+
+ArkGate does not hard-require `typescript` as a runtime dependency of the package
+itself; the CLI resolves it from the **project** first, then from the environment.
+
+## How loading works
+
+1. Prefer `require('typescript')` from the **project** root (when it has `sys` + AST + resolve).  
+2. If missing or **not API-compatible** (TS 7.0 version-only export, or incomplete host), fall back to **ArkGate’s own** `typescript` dependency (JS-API 5.x nested under the package), then bare `import('typescript')`.  
+3. If nothing usable is found:  
+   - `--plan` still prints **coverage honesty** (no import graph)  
+   - full check exits non-zero with an install hint  
+
+Debug which TypeScript was used:
+
+```bash
+ARK_DEBUG_TS=1 npx arkgate-check --plan
+# → [ark-check] TypeScript 5.9.x via arkgate (fallback)
+```
+
+## TypeScript 7 notes
+
+TypeScript 7 is the **native (Go) compiler** generation. Important for tools like ArkGate:
+
+- **`require('typescript')` on 7.0.x** exports only `{ version, versionMajorMinor }` — not `sys`, `createSourceFile`, or `resolveModuleName`.  
+- Unstable programmatic surfaces live under `typescript/unstable/*` (sync/async API, AST). They are **not** the classic TS 5/6 host ArkGate uses today.  
+- Stable **programmatic JS API** maturity continues over the 7.x line (Microsoft: full story into **7.1+**).  
+- When the project’s TypeScript is not API-compatible, ArkGate loads its **bundled JS-API dependency** (`typescript@^5.9`, nested under the package) so the write/CI gate keeps working while you try TS 7 as the project compiler.  
+- Your **tsconfig** must follow TS 6/7 defaults (see below) or `tsc` / resolve can fail independently of ArkGate.
+
+### tsconfig defaults that surprise teams (TS 6 → 7)
+
+Adopt these before or when moving to TS 7:
+
+| Option | TS7 direction |
+|--------|----------------|
+| `strict` | default `true` |
+| `module` | often `esnext` |
+| `moduleResolution` | `nodenext` or `bundler` (not `node` / `node10`) |
+| `baseUrl` | removed — put paths relative to project root |
+| `types` | default `[]` — list globals explicitly, e.g. `["node"]` |
+| `rootDir` | default `./` — set `"./src"` when sources live under `src` |
+| `target: es5` | unsupported |
+| `esModuleInterop: false` | unsupported |
+
+Example consumer-friendly skeleton (also used in `tests/fixtures/ts-consumer`):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "rootDir": "./src",
+    "types": ["node"],
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}
+```
+
+## Side-by-side TypeScript 6 + 7 (tooling)
+
+If you need **tsc 7** for builds and a **JS API 6** for tools that still expect classic exports:
+
+```json
+{
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@^6.0.0",
+    "typescript-7": "npm:typescript@^7.0.0"
+  }
+}
+```
+
+- `npx tsc6` — TypeScript 6 CLI (from the alias package)  
+- `npx typescript-7` / install path — TypeScript 7 CLI as needed  
+
+ArkGate will prefer the project’s `typescript` package; keep that entry **API-compatible** (5/6, or 7 once `sys` is present). See Microsoft’s TS 7 RC blog for dual-install details.
+
+## CI matrix (this repo)
+
+GitHub Actions job `ts-compat` installs TypeScript **5.9.x**, **6.0.x**, and **7.0.x** into a temp copy of `tests/fixtures/ts-consumer` and runs:
+
+```bash
+node bin/ark-check.mjs --root <fixture> --plan --json --no-cache
+```
+
+Locally:
+
+```bash
+node scripts/ts-compat-matrix.mjs 5.9.3
+node scripts/ts-compat-matrix.mjs 6.0.3
+node scripts/ts-compat-matrix.mjs 7.0.2
+```
+
+## What “compatible” means for ArkGate
+
+| Goal | Status |
+|------|--------|
+| Gate does not crash on project TS 7 | Yes (fallback if API incomplete) |
+| Plan/check work with project TS 5/6 | Yes |
+| Plan/check work when project has TS 7 + usable `sys` | Yes (uses project) |
+| Gate uses native Go typechecker API exclusively | Not required; future if 7.1+ exposes a stable Node API we adopt |
+| User tsconfigs with removed options still “just work” | User must migrate tsconfig (TS6/7); Ark reports resolve/parse failures clearly |
+
+## Future (7.1+ programmatic API)
+
+When Microsoft ships a stable Node API for native TypeScript 7.1+:
+
+1. Extend `usableTypescript` for the new export shape.  
+2. Keep the multi-version matrix green.  
+3. Optionally prefer project TS 7 for resolution without fallback.
+
+Until then, **fallback + matrix** is the compatibility story so teams can try TS 7 today without breaking the architecture gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -41,10 +41,12 @@
     "docs/demos",
     "docs/ai-gates.md",
     "docs/migrate-from-ark-runtime-kernel.md",
+    "docs/typescript-support.md",
     "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
     "docs/production-hardening.md",
+    "tests/fixtures/ts-consumer",
     "templates",
     "server.json",
     "README.md",
@@ -60,18 +62,26 @@
     "typecheck": "tsc --noEmit",
     "security:audit": "npm audit --omit=dev --audit-level=high",
     "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict-config",
+    "test:ts-compat": "node scripts/ts-compat-matrix.mjs 5.9.3 && node scripts/ts-compat-matrix.mjs 6.0.3 && node scripts/ts-compat-matrix.mjs 7.0.2",
     "eval:agent": "node eval/run.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"
   },
+  "dependencies": {
+    "typescript": "^5.9.3"
+  },
   "peerDependencies": {
-    "@nestjs/common": ">=9"
+    "@nestjs/common": ">=9",
+    "typescript": ">=5.0.0 <8"
   },
   "peerDependenciesMeta": {
     "@nestjs/common": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "overrides": {
@@ -89,7 +99,6 @@
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",
-    "typescript": "^5.5.3",
     "vitest": "^3.2.6"
   },
   "engines": {

package/server.json

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

package/templates/skills/ark-autopilot.md

@@ -55,12 +55,14 @@ Never tell a user "your architecture is guarded" while `--plan` reports `goal.me
 
 3. **Show the plan.** Run `ark-check --plan` and explain it in outcome terms: how many fixes are
    _safe to auto-apply_ vs _need your decision_ vs _deferred_, and what the goal is (a clean,
-   enforced architecture). Confirm before changing anything.
+   enforced architecture). Safe auto steps are only the three `mechanical-safe` kinds:
+   type-only type move, pure-type **file** relocate, and converting static imports of pure-type
+   modules to `import type` (see `/ark-loop`). Confirm before changing anything.
 
 4. **Drive the loop.** Hand off to **`/ark-loop`**: in a discardable git worktree, auto-apply
-   the `mechanical-safe` steps one at a time (validate with `ark-check`, roll back regressions),
-   and PROPOSE each `judgment` step in plain language for a yes/no. Loop until the plan's
-   `goal.met` is true or a round makes no progress.
+   the `mechanical-safe` steps one at a time (match each `remediationKind`; validate with
+   `ark-check`, roll back regressions), and PROPOSE each `judgment` step in plain language for
+   a yes/no. Loop until the plan's `goal.met` is true or a round makes no progress.
 
 5. **Confirm it stays clean.** Verify the gates are installed and active so the architecture is
    enforced from now on (in CI, and at write time if the MCP hook is wired) — the

package/templates/skills/ark-explain.md

@@ -36,16 +36,21 @@ Your job is to **teach with this repo's real data** and leave a shareable visual
    ```bash
    npx ark-check --coverage
    npx ark-check --doctor
+   npx ark-check --plan
    ```
 
-   so your spoken explanation matches the report's governed% and operating mode
-   (SUGGEST / ADAPT / ENFORCE).
+   so your spoken explanation matches the report's governed%, operating mode
+   (SUGGEST / ADAPT / ENFORCE), and the plan's safe-to-auto vs decision counts.
 
 The HTML report is the visual twin of this skill: architecture map, files per layer,
 dependency direction, matrix, violations, enforcement points, Ark fitness score, and a
 **Senior diagnostics** block (coupling fan-in/out, deny density, purity surface, pattern
 forensics, baseline taxonomy) for tech leads.
 
+When explaining the **plan**, name the three `mechanical-safe` remediation kinds only
+(type-only move, pure-type file relocate, `import type` of pure-type modules) — everything
+else is judgment/deferred and must not be auto-applied.
+
 ## Spoken / written explanation
 
 1. **Load the real contract**: `ark.config.json`, `ark://manifest` if available, `AGENTS.md`.