arkgate 2.8.3 → 2.9.0

package/dist/{types-CSJhEOk2.d.cts → types-D6Q8WHes.d.cts}

@@ -274,6 +274,13 @@ interface ArchitectureRule {
     to: string;
     allowed: boolean;
     message?: string;
+    /**
+     * When true with allowed:false: deny only when slice ids differ (same or cross layer).
+     * Requires path resolution at check time (write-gate / CI). Matches domain EdgeRule.
+     */
+    peerIsolation?: boolean;
+    /** Parent folder names that own the slice id as the next path segment. */
+    sliceFolders?: string[];
 }
 interface ArchitectureProfile {
     name: string;

package/dist/{types-CSJhEOk2.d.ts → types-D6Q8WHes.d.ts}

@@ -274,6 +274,13 @@ interface ArchitectureRule {
     to: string;
     allowed: boolean;
     message?: string;
+    /**
+     * When true with allowed:false: deny only when slice ids differ (same or cross layer).
+     * Requires path resolution at check time (write-gate / CI). Matches domain EdgeRule.
+     */
+    peerIsolation?: boolean;
+    /** Parent folder names that own the slice id as the next path segment. */
+    sliceFolders?: string[];
 }
 interface ArchitectureProfile {
     name: string;

package/docs/agent-guide.md

@@ -13,11 +13,12 @@ Before generating project structure, agents should read the **tool-agnostic appl
 shape** that fits the repository — not a vendor stack label. Ark ships a versioned playbook
 at `templates/architecture-playbook.json` (also in the npm package under `templates/`).
 
-Each of the ten archetypes (`crud-product`, `api-backend`, `frontend-surface`,
+Each of the twelve archetypes (`crud-product`, `api-backend`, `frontend-surface`,
 `library-sdk`, `cli-utility`, `worker-pipeline`, `event-coordinator`,
-`integration-bridge`, `multi-app-workspace`, `prototype-spike`) maps to:
+`integration-bridge`, `multi-app-workspace`, `prototype-spike`,
+`vertical-slice-product`, `ddd-bounded-contexts`) maps to:
 
-- a named Ark preset (`hexagonal`, `layered`, `feature-sliced`, or `monorepo`),
+- a named Ark preset (`hexagonal`, `layered`, `feature-sliced`, `monorepo`, `ui-surface`, `vertical-slice`, or `ddd-bounded-contexts`),
 - phased 11-layer adoption (phase 1–3),
 - plain-language analogy and anti-patterns,
 - optional book references for depth only.
@@ -99,7 +100,7 @@ Polyglot repos: Ark only governs TypeScript/JS. Point include at package roots t
 
 ### Presets
 
-- `hexagonal` / `layered` / `feature-sliced` / `monorepo` / **`ui-surface`** (UI/Vite/Remotion-style hooks+lib+routes+components)
+- `hexagonal` / `layered` / `feature-sliced` / `monorepo` / **`ui-surface`** (UI/Vite/Remotion-style) / **`vertical-slice`** (features/* + peerIsolation) / **`ddd-bounded-contexts`** (contexts/*/domain|application|infra + shared kernel)
 
 ### Cycle policy
 
@@ -341,6 +342,56 @@ Use `ark-check` in CI for repository-level checks that need real file paths:
 npx ark-check --root . --config ark.config.json
 ```
 
+### Monorepo tooling (Turborepo / Nx)
+
+Use **`ark init --preset monorepo`** (or archetype `multi-app-workspace`). Ark does **not**
+reimplement the Nx project graph. It maps conventional trees:
+
+| Tooling | Typical roots | Ark `include` fallback |
+|---------|---------------|------------------------|
+| Turborepo | `apps/`, `packages/` | `packages`, `apps`, `libs` |
+| Nx | `apps/`, `libs/` | same |
+
+Layers still match by folder **name** (`**/domain/**`, `**/application/**`, …) across packages.
+Doctor surfaces `turbo.json` / `nx.json` as monorepo tooling hints.
+
+### Nest modular monolith
+
+Prefer **`hexagonal`** with Nest filename overlays (`*.controller.ts` / services). If you
+literally have `src/contexts/*` bounded contexts, use **`ddd-bounded-contexts`**. Do not
+invent a separate Nest-only engine — modules map to `src/**/domain/**` style globs already.
+
+### Clean / Onion aliases
+
+`ark init --preset clean-architecture` and `--preset onion-architecture` are **aliases** of
+`hexagonal` (same layer matrix). Prefer the hexagonal name in docs; aliases exist for
+discoverability.
+
+### Peer isolation (cross-slice bans)
+
+Classic rules deny **layer A → layer B** always. **Same-layer is always allowed** unless a
+rule sets `peerIsolation: true`.
+
+`peerIsolation: true` + `allowed: false` means: deny **only when importer and importee
+resolve to different slice ids** (works for same-layer *and* cross-layer pairs). Same-slice
+edges are not denied by that rule.
+
+```json
+{
+  "from": "Features",
+  "to": "Features",
+  "allowed": false,
+  "peerIsolation": true
+}
+```
+
+- **Denied:** `src/features/auth/**` → `src/features/payments/**` (different slice id).
+- **Allowed:** same-slice imports; classic non-peerIsolation denies still apply across layers.
+- **`sliceFolders`:** optional parent segments (default: inferred from layer globs).
+- **Fail-open:** missing paths or unclassifiable slices → do not deny via peerIsolation.
+- Enforced by `ark-check`, `arkgate/eslint`, and `ark-mcp` when paths resolve.
+- Fixes are **judgment** (not mechanical-safe).
+
 Agents can generate a config from the project's actual directory layout instead of inventing layer mappings:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.8.3",
+  "version": "2.9.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -73,6 +73,8 @@
     "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",
+    "check:gallery-starters": "node scripts/check-gallery-starters.mjs",
+    "generate:gallery-starters": "node scripts/check-gallery-starters.mjs --write",
     "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",

package/server.json

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

package/templates/architecture-playbook.json

@@ -299,7 +299,8 @@
         }
       ],
       "detectionSignals": {
-        "workspaces": 10
+        "workspaces": 10,
+        "monorepoTooling": 4
       },
       "negativeSignals": {
         "cli": 2,
@@ -334,6 +335,69 @@
         "workflows": 4,
         "jobs": 3
       }
+    },
+    "vertical-slice-product": {
+      "label": "Feature-first product (vertical slices)",
+      "preset": "vertical-slice",
+      "phases": {
+        "1": ["Features", "Shared"],
+        "2": ["Lib", "App"],
+        "3": []
+      },
+      "analogy": "A food truck menu: each dish (feature) is cooked end-to-end; shared utensils stay in the common drawer — never borrow another dish's mise en place.",
+      "antiPatterns": [
+        "Importing code from features/A into features/B",
+        "Dumping business rules into shared/ just to avoid a cross-slice import"
+      ],
+      "books": [
+        {
+          "title": "Vertical Slice Architecture",
+          "author": "Jimmy Bogard (community)",
+          "for": "organizing by use-case instead of technical layer only"
+        }
+      ],
+      "detectionSignals": {
+        "verticalSliceLayout": 10,
+        "ui": 2,
+        "fullStackProduct": 2
+      },
+      "negativeSignals": {
+        "dddBoundedContextsLayout": 6,
+        "domainHeavy": 4,
+        "workspaces": 3,
+        "cli": 4
+      }
+    },
+    "ddd-bounded-contexts": {
+      "label": "Multiple business domains (bounded contexts)",
+      "preset": "ddd-bounded-contexts",
+      "phases": {
+        "1": ["DomainModel", "ApplicationOrchestration", "SharedKernel"],
+        "2": ["PersistenceAdapters", "PresentationAdapters"],
+        "3": []
+      },
+      "analogy": "Separate city districts: each has its own shops and rules; only the shared square (kernel) and mail (events) connect them — never dig tunnels between private basements.",
+      "antiPatterns": [
+        "One context importing another context's domain model",
+        "A god shared/ folder that re-exports every context"
+      ],
+      "books": [
+        {
+          "title": "Implementing Domain-Driven Design",
+          "author": "Vernon",
+          "for": "bounded contexts, shared kernel, and integration patterns"
+        }
+      ],
+      "detectionSignals": {
+        "dddBoundedContextsLayout": 12,
+        "domain": 3,
+        "domainHeavy": 2
+      },
+      "negativeSignals": {
+        "verticalSliceLayout": 4,
+        "tinyTree": 3,
+        "uiOnly": 4
+      }
     }
   }
 }

package/templates/policy-packs/enthusiast-ddd-bounded-contexts.json

@@ -0,0 +1,19 @@
+{
+  "id": "enthusiast-ddd-bounded-contexts",
+  "preset": "ddd-bounded-contexts",
+  "variant": "enthusiast",
+  "label": "DDD bounded contexts — enthusiast",
+  "summary": "One folder per bounded context with domain / application / infrastructure / presentation. Shared kernel only for truly shared types; contexts do not import each other.",
+  "phases": {
+    "1": ["DomainModel", "ApplicationOrchestration", "SharedKernel"],
+    "2": ["PersistenceAdapters", "PresentationAdapters"],
+    "3": []
+  },
+  "layerDescriptions": {
+    "DomainModel": "Per-context pure business rules and entities. No I/O.",
+    "ApplicationOrchestration": "Per-context use cases that call domain through ports.",
+    "PresentationAdapters": "Controllers, HTTP, or UI entrypoints for a context.",
+    "PersistenceAdapters": "Repository and external I/O implementations for a context.",
+    "SharedKernel": "Cross-context primitives only — keep this thin."
+  }
+}

package/templates/policy-packs/enthusiast-ui-surface.json

@@ -0,0 +1,18 @@
+{
+  "id": "enthusiast-ui-surface",
+  "preset": "ui-surface",
+  "variant": "enthusiast",
+  "label": "UI surface — enthusiast",
+  "summary": "Presentation-heavy trees (hooks, components, routes) with optional domain and data clients. Good for Vite/Next UI packages.",
+  "phases": {
+    "1": ["PresentationAdapters", "ApplicationOrchestration"],
+    "2": ["DomainModel", "PersistenceAdapters"],
+    "3": []
+  },
+  "layerDescriptions": {
+    "PresentationAdapters": "UI, routes, hooks, and components.",
+    "ApplicationOrchestration": "Server actions and feature orchestration when present.",
+    "DomainModel": "Shared types and pure view-models.",
+    "PersistenceAdapters": "Client data access and external API adapters."
+  }
+}

package/templates/policy-packs/enthusiast-vertical-slice.json

@@ -0,0 +1,18 @@
+{
+  "id": "enthusiast-vertical-slice",
+  "preset": "vertical-slice",
+  "variant": "enthusiast",
+  "label": "Vertical slice — enthusiast",
+  "summary": "Organize by feature slices under src/features. Shared and lib are the only escape hatches; sibling features must not import each other.",
+  "phases": {
+    "1": ["Features", "Shared"],
+    "2": ["Lib", "App"],
+    "3": []
+  },
+  "layerDescriptions": {
+    "Features": "One folder per feature/use-case — API, UI, hooks, types together. No imports from sibling features.",
+    "Shared": "Reusable primitives (UI kit, utils, types) with zero feature knowledge.",
+    "Lib": "Infrastructure clients (db, HTTP, env) shared across features.",
+    "App": "App shell, routing, and composition root."
+  }
+}

package/templates/skills/ark-adopt.md

@@ -32,7 +32,11 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
 ## Steps
 
 1. **Config** — missing → `ark-check --init` (detection). Keep existing unless asked to regenerate.
+   If the tree is `src/features` + `shared`/`lib` **without** FSD `entities`/`widgets`, prefer
+   `vertical-slice` (or pack `enthusiast-vertical-slice`) — do **not** force hexagonal.
+   If `src/contexts` or `src/bounded-contexts` exists, prefer `ddd-bounded-contexts`.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
+   Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
 3. **Classify ungoverned** — use coverage `suggestions`; 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.

package/templates/skills/ark-architect.md

@@ -70,6 +70,8 @@ package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
      | `api-backend` | `examples/api-backend-starter/` |
      | `worker-pipeline` | `examples/worker-pipeline-starter/` |
      | `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
+     | `vertical-slice-product` | `examples/vertical-slice-starter/` |
+     | `ddd-bounded-contexts` | `examples/ddd-context-starter/` |
 
      Say they can copy that folder as a baseline (`npm install && npm run check`).
      For a runnable API with break exercises, mention `examples/hexagonal-order-api/`.
@@ -78,7 +80,9 @@ package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
 ## Operating rules
 
 - Never weaken `ark.config.json`, the baseline, CI, or agent settings to pass.
-- Never invent layers outside the 11-layer profile or named presets.
+- Never invent layers outside the 11-layer profile or named presets
+  (`hexagonal`, `layered`, `feature-sliced`, `monorepo`, `ui-surface`,
+  `vertical-slice`, `ddd-bounded-contexts`).
 - Flag unrecognized dirs (`utils/`, `lib/`) — user must classify via `/ark-contract`.
 - Default to smallest viable phase 1; unlock phase 2 only when the user describes need.
 - All user-facing copy is **English**.

package/templates/skills/ark-autopilot.md

@@ -35,9 +35,11 @@ never weaken the gate).
 
 ## Flow
 
-1. **Setup if needed** — `ark start` if no `ark.config.json`.
+1. **Setup if needed** — `ark start` if no `ark.config.json`. Trust `--recommend` / playbook:
+   `vertical-slice-product` and `ddd-bounded-contexts` are first-class shapes (not hexagonal by default).
 2. **Origin report** — `ark-check --report ark-report.html` (do not `--reset-origin` unless asked).
 3. **Plan + code read** — `--plan --json`; read each step’s source/target; group by edge.
+   Treat `peerIsolation` / cross-slice steps as **judgment** (never mechanical-safe).
 4. **Concentrated edge?** — if one edge dominates, route to `/ark-contract` with a **source-based** diagnosis (not freeze).
 5. **Worktree preferred** — discardable git worktree when possible.
 6. **Mechanical-safe** — only kinds from `/ark-loop` table; one step, validate, rollback.

package/templates/skills/ark-fix.md

@@ -12,6 +12,9 @@ You fix violations Ark reports. Prefer structural fixes over silencing the gate.
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
 - **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **peerIsolation / cross-slice:** always **judgment** — extract to shared, events/ports, or redesign ownership. Never auto-apply cross-feature or cross-context moves.
+- **`vertical-slice` ownership:** feature code stays under `src/features/<slice>/…` (no sibling-slice imports); shared primitives in `src/shared/`; infra in `src/lib/`; shell in `src/app/`. Cross-feature edges are peerIsolation — extract shared or use events/ports.
+- **`ddd-bounded-contexts` ownership:** code under `src/contexts/<context>/{domain,application,infrastructure,presentation}/`; shared kernel only under `src/shared/kernel/`. Cross-context imports (same or cross technical layer) are peerIsolation — integrate via application APIs/events, not peer technical layers.
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
 ## Anti-wrapper rule (mandatory)

package/templates/skills/ark-place.md

@@ -34,6 +34,13 @@ not a stalling question.
      that matches the direction (driven/persistence vs driving/http).
    - Reacts to events, long-running coordination (saga/workflow), scheduled
      jobs, projections → the event/workflow layers if the config declares them.
+   - **`vertical-slice` contract:** put co-located feature code under
+     `src/features/<slice>/…` (never import a sibling slice); shared primitives
+     under `src/shared/`; infra under `src/lib/`; shell under `src/app/`.
+   - **`ddd-bounded-contexts` contract:** put code under
+     `src/contexts/<context>/{domain,application,infrastructure,presentation}/`;
+     shared kernel only under `src/shared/kernel/`. Cross-context imports at the
+     same technical layer are peerIsolation violations.
 3. **Answer concretely**: layer name, target directory (from the layer's
    `patterns`), intent-name prefix if the layer declares `intentPrefixes`, and
    which layers it may/may not import (from `rules`).

package/templates/skills/ark-think.md

@@ -0,0 +1,43 @@
+---
+name: ark-think
+description: "Host-side architectural reasoning within the Ark contract — trade-offs, evolution, design options. No gate bypass. No package LLM call."
+---
+
+# /ark-think — Architectural reasoning (host LLM only)
+
+You are the user's architecture thinking partner **inside** the project's Ark contract.
+This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)
+reason; the write-gate and CI remain deterministic.
+
+## When to use
+
+- Design trade-offs before writing code
+- "Should this be a new layer or a feature slice?"
+- Evolving brownfield layout toward a named preset
+- Explaining why a peerIsolation or layer rule exists
+
+## Steps
+
+1. **Load the contract** — `ark.config.json`, MCP `ark://manifest` if available, and
+   `ark-check --coverage --json` / `--doctor` for honesty about governed%.
+2. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,
+   ddd-bounded-contexts, feature-sliced, monorepo, …). If none, run `--recommend --json`.
+3. **Reason within bounds** — propose options that **stay enforceable** by the gate.
+   Prefer concrete paths and import rules over abstract diagrams.
+4. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
+   judgment auto-apply, codemod engines, or skipping write-gate/CI.
+5. **Hand off** — for placement use `/ark-place`; for config edits `/ark-contract`; for
+   bulk debt `/ark-loop` / `/ark-autopilot`; for violations `/ark-fix`.
+
+## Output format
+
+- **Context:** 2–3 sentences on current contract + shape
+- **Options:** 2–3 alternatives with trade-offs (coupling, testability, AI-agent safety)
+- **Recommendation:** one option + why it is enforceable today
+- **Next command:** exact `ark-check` / skill to run next
+
+## Related
+
+- Greenfield shape: `/ark-architect`
+- Brownfield: `/ark-adopt`
+- Explain existing: `/ark-explain`