arkgate 2.6.1 → 2.8.0

package/docs/ai-gates.md

@@ -189,20 +189,54 @@ Your hard backstop in Cursor is CI: `ark-check` fails the PR on anything that sl
 
 Recommended for Ark projects.
 
-`~/.codex/config.toml`:
+Unlike Claude/Cursor (project-local MCP files), **Codex loads MCP servers only from
+`$CODEX_HOME/config.toml`** (default `~/.codex/config.toml`) — a **global** home file.
+Hand-editing with relative `--root .` is wrong: Codex does not use the project as cwd, so
+`.` resolves against the launch directory. Prefer absolute paths, or let Ark write them:
+
+```bash
+npx ark-check --install-agent-gates --tools codex
+# optional: install /ark-* slash prompts into $CODEX_HOME/prompts
+npx ark-check --install-agent-gates --codex-home
+```
+
+Example shape (absolute paths — also what install writes):
 
 ```toml
 [mcp_servers.ark]
 command = "npx"
-args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+args = ["arkgate-mcp", "--root", "/absolute/path/to/project", "--config", "/absolute/path/to/project/ark.config.json"]
+```
+
+Then **restart Codex** — it does not hot-load MCP servers. Expect resource `ark://manifest`
+and tools `validate_code`, `ark_check`, `ark_coverage`, `ark_place`.
+
+Same model as Cursor for enforcement: MCP for discovery/validation, `ark-check` in CI as
+the hard gate. Register the MCP server as soon as the repo is adopted.
+
+### Multi-project Codex (home config last-wins)
+
+`[mcp_servers.ark]` is a **single primary** binding. If project A is already registered and
+you install gates for project B **without** `--force`, Ark does **not** silently steal
+primary A. It writes a **scoped secondary** table:
+
+```toml
+[mcp_servers.ark]            # primary — still project A
+# ...
+
+[mcp_servers.ark_proj-b_a1b2c3d4]  # secondary — basename + path hash (no slug collisions)
+# absolute --root for B
 ```
 
-Same model as Cursor: MCP for discovery/validation, `ark-check` in CI as the hard gate.
-For Ark projects, register the MCP server as soon as the repo is adopted so the agent
-has the contract available from the first edit.
+| Goal | Command |
+|------|---------|
+| Add B without moving primary | `ark-check --install-agent-gates --tools codex` (no `--force`) |
+| Make B the primary binding | `ark-check --install-agent-gates --tools codex --force` |
+| Doctor: primary points at another permanent project | gap id `codex-home-multi-project` (warn if no secondary yet; info if scoped table already present) |
 
-`ark-check --install-agent-gates --tools codex` auto-merges absolute paths into
-`~/.codex/config.toml` and can install `/ark-*` prompts with `--codex-home`.
+`ark-check --doctor` surfaces the multi-project state so you are not left thinking B owns
+`ark://manifest` when only a secondary table exists. Temp/upgrade primary roots are still
+rewritten fail-closed (not multi-project).
 
 ## Grok Build (xAI)
 

package/docs/brownfield-adoption.md

@@ -71,6 +71,13 @@ violations — the ratchet only moves toward zero.
 - **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()`.
+- **Named type exports from mixed modules** (`namedBindingsTypeOnly` — plan:
+  `import-type-of-type-exports`): value-syntax `import { Row }` / `export { Row }` where every
+  binding is an `export type` / `interface` on the target — convert to `import type` /
+  `export type`. Still **judgment** when any binding is a value, dual-space name
+  (`export type Foo` + `export const Foo`), the target has top-level side effects (including
+  impure value-export initializers like `export const db = connect()`), or the edge is
+  `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

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

@@ -40,8 +40,9 @@ npx ark-check --plan --json     # { ok, plan: { goal, counts, steps } }
 ```
 
 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
+`rationale`, and often `remediationKind`. Auto-safe kinds: type-only type move, pure-type **file**
+relocate, `import type` of pure-type modules, and named type-export imports from mixed modules
+(`import-type-of-type-exports`). `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."
 

package/docs/enthusiast/reference-commands.md

@@ -51,7 +51,7 @@ arkgate-check --watch
 
 | `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` |
+| `mechanical-safe` | Yes (validate + rollback) | `type-only-import-move`, `pure-type-file-relocate`, `import-type-from-pure-type-module`, `import-type-of-type-exports` |
 | `judgment` | No — propose | value imports, ports, infra relocate, cycles |
 | `deferred` | No | unclear shape |
 
@@ -62,4 +62,4 @@ When present on violations:
 - `fixClass` — e.g. `port-inversion`, `file-move`
 - `effort` — `small` | `medium`
 - `enthusiastHint` — plain English fix guidance
-- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`
+- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`, `namedBindingsTypeOnly`

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

@@ -131,7 +131,8 @@ Or edit `.grok/config.toml` → `args` use `arkgate-mcp`.
 
 ```diff
 - import { createStrictArkKernelFromConfig } from 'ark-runtime-kernel';
-+ import { createStrictArkKernelFromConfig } from 'arkgate';
++ import { createStrictArkKernelFromConfig } from 'arkgate/runtime';
+  // root `arkgate` still re-exports kernel symbols this major (compat)
 
 - import { ArkModule } from 'ark-runtime-kernel/nestjs';
 + import { ArkModule } from 'arkgate/nestjs';
@@ -140,7 +141,8 @@ Or edit `.grok/config.toml` → `args` use `arkgate-mcp`.
 + import ark from 'arkgate/eslint';
 ```
 
-If you only used the CLI + MCP (most projects), **no import changes**.
+If you only used the CLI + MCP (most projects), **no import changes**.  
+Surface policy: [package-surface.md](package-surface.md).
 
 ---
 

package/docs/package-surface.md

@@ -0,0 +1,72 @@
+# ArkGate package surface policy
+
+**Product wedge:** write gate · CI gate · co-pilot (plan / loop / skills).  
+**Not the wedge:** the optional in-process runtime kernel.
+
+This document is the consumer contract for **what is stable** vs **what is opt-in**.
+
+---
+
+## Stable surfaces (semver-supported)
+
+| Surface | How you use it | Stability notes |
+|---------|----------------|-----------------|
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
+| **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
+| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
+| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve. |
+| **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
+| **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | Inputs for running the check stay stable within a major. |
+
+Gates need **no application code imports**. Most projects only use the CLI + MCP + config.
+
+---
+
+## Opt-in surfaces
+
+| Surface | Import path | Notes |
+|---------|-------------|--------|
+| **Runtime kernel** | **`arkgate/runtime`** (preferred) | Event bus, intents, policies, sagas, outbox, projections, `createArkKernel` / strict helpers. Optional. Not required for architecture enforcement. |
+| **Root package barrel** | `arkgate` | Still re-exports the runtime kernel for **compatibility**. Prefer `arkgate/runtime` for new code. Root may be thinned in a future **major**. |
+| **NestJS adapter** | `arkgate/nestjs` | Optional peer `@nestjs/common`. Wires a kernel into Nest DI. |
+
+---
+
+## Recommended imports
+
+```ts
+// Preferred — opt-in runtime kernel
+import {
+  createStrictArkKernel,
+  createStrictArkKernelFromConfig,
+} from 'arkgate/runtime';
+
+// Still works this major (compat; not preferred for new code)
+import { createStrictArkKernel } from 'arkgate';
+
+// Nest adapter
+import { ArkModule, InjectArk } from 'arkgate/nestjs';
+```
+
+See [production-hardening.md](./production-hardening.md) for runtime operational guidance.
+
+---
+
+## Explicitly unstable / internal
+
+- `bin/lib/*` module layout and private helpers  
+- Generated `bin/ark-layer-match.mjs` (edit canonical `src/domain/layerMatch.ts` only)  
+- HTML report DOM structure (unless documented as a machine contract)  
+- Internal MCP diagnostic fields not listed in agent-guide  
+
+---
+
+## Versioning summary
+
+| Change | Version bump |
+|--------|----------------|
+| Break CLI JSON field, MCP tool rename, or required `ark.config` field | **major** |
+| New optional config field, new CLI flag, additive JSON | **minor** |
+| Bugfix with no contract change | **patch** |
+| Prefer `arkgate/runtime` over root (docs only; root still exports) | **patch/minor** |
+| Remove root kernel re-exports | **major** (with migration notes) |

package/docs/production-hardening.md

@@ -1,5 +1,8 @@
 # Production Hardening
 
+The optional runtime kernel is imported from **`arkgate/runtime`** (preferred). See
+[package-surface.md](package-surface.md).
+
 Ark's built-in stores are intentionally in-memory defaults. They are appropriate for tests,
 local development, examples, and single-process demos. Production systems should provide
 stores that match their durability, ordering, retention, and operational requirements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.6.1",
+  "version": "2.8.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "require": "./dist/runtime/index.cjs"
+    },
     "./eslint": {
       "types": "./dist/eslint/index.d.ts",
       "import": "./dist/eslint/index.js",
@@ -46,6 +51,7 @@
     "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
+    "docs/package-surface.md",
     "docs/production-hardening.md",
     "tests/fixtures/ts-consumer",
     "templates",
@@ -63,8 +69,13 @@
     "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",
+    "generate:layer-match": "node scripts/generate-layer-match.mjs",
+    "check:layer-match": "node scripts/generate-layer-match.mjs --check",
+    "generate:cli-pure": "node scripts/generate-cli-pure.mjs",
+    "check:cli-pure": "node scripts/generate-cli-pure.mjs --check",
     "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:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",

package/server.json

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

package/templates/skills/ark-explain.md

@@ -47,8 +47,9 @@ dependency direction, matrix, violations, enforcement points, Ark fitness score,
 **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
+When explaining the **plan**, name the four `mechanical-safe` remediation kinds only
+(type-only move, pure-type file relocate, `import type` of pure-type modules,
+`import-type-of-type-exports` for named type exports from mixed modules) — everything
 else is judgment/deferred and must not be auto-applied.
 
 ## Spoken / written explanation

package/templates/skills/ark-loop.md

@@ -32,8 +32,9 @@ validating every change with `ark-check` and rolling back regressions.
 | `type-only-import-move` | Move type to owning layer; re-export for back-compat |
 | `pure-type-file-relocate` | Relocate pure-type file to owning layer (or rename out of false Domain globs) |
 | `import-type-from-pure-type-module` | Convert value import of pure-type module to `import type` |
+| `import-type-of-type-exports` | Convert value-syntax named import/export of type-only exports from a mixed module to `import type` / `export type` |
 
-Never auto: value imports, dynamic import/require, mixed modules, forbidden globals, cycles, infra moves.
+Never auto: value imports (including mixed bindings with values), dynamic import/require, forbidden globals, cycles, infra moves.
 
 ## Steps