arkgate 4.0.0 → 4.1.0

package/docs/README.md

@@ -57,8 +57,9 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Prepared major: [releases/4.0.0.md](releases/4.0.0.md) (`arkgate@4.0.0` — layers + optional **ArkRules**).  
-Last npm `latest` until publish: [releases/3.9.2.md](releases/3.9.2.md) (`arkgate@3.9.2`).  
+Current published: [releases/4.0.1.md](releases/4.0.1.md) (`arkgate@4.0.1` on npm `latest`).  
+Next prepared: [releases/4.1.0.md](releases/4.1.0.md) (`arkgate@4.1.0` — field product phases + CI PR slim; not published until registry).  
+Previous major: [releases/4.0.0.md](releases/4.0.0.md) (`arkgate@4.0.0`).  
 Config: [configuration.md](configuration.md) · Agent skills dual-plane: [agent-guide.md](agent-guide.md).
 
 ---

package/docs/ai-gates.md

@@ -560,21 +560,25 @@ export default [
 
 **Exact layer-edge parity envelope:** the linted production source is on disk, inside
 `include`, outside configured/generated exclusions, parse-clean, and uses a static
-`import`/`export` with a relative literal whose target is also on disk. Inside that envelope,
-ESLint uses the same layer glob specificity, rule decision, rule id, severity, and evidence as
-the resolved CLI. It reloads `ark.config.json` when its content changes and never invents a
-not-yet-created target.
+`import`/`export` with a **relative** or **tsconfig `paths` / `baseUrl` alias** (e.g. `@/*`)
+literal whose target is also on disk. Inside that envelope, ESLint uses the same layer glob
+specificity, rule decision, rule id, and evidence as the resolved CLI. It reloads
+`ark.config.json` when its content changes and never invents a not-yet-created target.
 
-Outside that envelope—path aliases, packages/workspaces, symlinks, CommonJS,
-`import = require`, dynamic imports, virtual creates/deletes, unresolved targets, or complete
-cross-file candidates—ESLint emits no layer-parity verdict. Use `ark preflight`,
-`ark_prepare_change`, the complete ApplyPatch hook, or final strict CI; those paths consume the
-canonical resolved facts.
+**Path-alias residual (honest):** simple `paths` + `baseUrl` (including one level of relative
+`extends`) are resolved. Not claimed: TypeScript project references, multi-target path arrays
+beyond the first entry, catch-all `*` mappings, package/workspace bare imports, or symlink
+hops. Those stay CI / preflight / write-gate truth.
+
+Outside that envelope—packages/workspaces, symlinks, CommonJS, `import = require`, dynamic
+imports, virtual creates/deletes, unresolved targets, or complete cross-file candidates—ESLint
+emits no layer-parity verdict. Use `ark preflight`, `ark_prepare_change`, the complete
+ApplyPatch hook, or final strict CI; those paths consume the canonical resolved facts.
 
 Additional rule notes:
 
-- Relative imports are resolved only to existing 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`).
+- Relative and tsconfig-aliased imports resolve only to existing on-disk TS/JS targets; package bare imports are left to CI/TS.
+- Value forbidden edges error (same pass/fail as `arkgate-check`). Type-only forbidden edges are **placement debt** (reported with `typeOnly`); merge blocking prefers value edges — align with doctor `typeEdgePolicy`.
 - `no-forbidden-globals` applies from the file layer’s `forbiddenGlobals`; the `globals` option is only a standalone fallback when no project config applies, never an override that weakens the project contract. Layers without either surface are not inventively restricted. `process` also owns exact value imports of `process` / `node:process`; type-only forms, subpaths, and `child_process` stay excluded. If the same layer also denies the `process` capability, this rule is the single `FORBIDDEN_GLOBAL` voice.
 - Without `ark.config.json`, `no-domain-infra-imports` emits no contract verdict.
 

package/docs/brownfield-adoption.md

@@ -20,6 +20,42 @@ every ungoverned directory** (harvested from the 11-layer profile + presets; unr
 ones are flagged for you to classify, never guessed). Keep an existing config; don't
 regenerate it unasked.
 
+### Next.js honesty (default overlays / ui-surface / monorepo)
+
+**App Router API routes are Application / use-case shell by default**, not Presentation/UI:
+
+| Path | Default layer |
+|------|----------------|
+| `app/api/**`, `src/app/api/**` | **ApplicationOrchestration** (orchestration shell) |
+| `pages/api/**`, `src/pages/api/**` | **ApplicationOrchestration** |
+| UI routes (`app/(…)`, `page.tsx`, `components/**`) | **PresentationAdapters** |
+
+Without this split, broad `**/app/**` Presentation patterns push every API handler into UI and
+create a Presentation→Persistence tsunami. Specificity still wins: more-specific Application
+globs beat Presentation. ArkRules stay **opt-in** (not forced on by start/adopt).
+
+### Composition-root / factory modules (optional Application-only)
+
+Many brownfield trees park DI composition roots and object factories next to domain code
+(`src/factories/**`, `src/composition/**`, `src/app/container.ts`). Those modules are
+**wiring**, not domain rules:
+
+| Pattern | Recommended layer | Why |
+|---------|-------------------|-----|
+| `**/factories/**`, `**/composition/**`, `**/container.ts`, `**/bootstrap.ts` | **ApplicationOrchestration** (or a dedicated optional CompositionRoot layer if you need it) | Constructs aggregates / wires ports; may import Domain + Persistence adapters |
+| Aggregate `static create` / private ctor factories **inside** domain entities | **DomainModel** | Always-valid factory is a domain rule (ArkRules `always-valid-factory`), not composition |
+| NestJS modules / providers | FrameworkAdapters / Application | Framework shell, not Domain |
+
+Do **not** map composition roots into DomainModel solely because a file constructs entities —
+that turns honest Application→Domain edges into false Domain purity failures. Prefer:
+
+1. Application patterns that match `**/factories/**` / `**/composition/**` (higher specificity than broad Domain globs), or  
+2. An optional **CompositionRoot** layer that may depend on Domain + Persistence and is
+   forbidden as a dependency *from* Domain (mirror Application rules).
+
+Field note (S3.1.3): factory-bag composition roots belong in Application (or CompositionRoot),
+not Domain — document the choice in `ark.config.json` rather than freezing factory noise.
+
 ## 2. Diagnose before you freeze
 
 ```bash
@@ -53,6 +89,8 @@ structure / invariants). Case study shape:
 
 **Upgrade note (4.0):** `ark upgrade --no-install` can refresh skills/gates while leaving
 `package.json` on an older pin—doctor exposes `packageVersionTruth` when the CLI is ahead.
+Prefer project-local `npx arkgate upgrade …` over bare PATH `ark` — global **2.x** is mutative
+and unsafe next to 3.8+/4.0 ([field footgun](releases/4.0.0.md#field-footgun--global-arkgate-2x-on-path)).
 
 ## 3. Make the contract real (via `/ark-contract`)
 

package/docs/configuration.md

@@ -107,6 +107,42 @@ Rule fields:
   when both paths classify. Missing paths, empty slice folders, or unclassifiable slices
   **fail closed** (deny — cannot prove same-slice).
 
+### Type-only edges (placement debt)
+
+`import type` / `export type` and pure type-only named bindings are **type placement debt**, not
+runtime coupling. They still appear on the **violations** list with `typeOnly: true`,
+`failsStrict: false`, and adapter diagnostic **severity: warning** so doctor/HTML keep
+`violations.typeOnly` / `typeEdgePolicy` honest — but they **do not** fail merge/exit, library
+`valid`, or preflight the way **value** edges do. **Exception:** `peerIsolation` slice
+boundaries stay hard even for type-only. A value import of a pure-type barrel is still a value
+edge (not soft-skipped). Prefer placing shared types in a **SharedTypes** (or owning) layer
+both sides may import. Optional starter: [`templates/layers/shared-types.starter.json`](../templates/layers/shared-types.starter.json)
+(layer globs + allow rules). Doctor always emits `violations.typeEdgePolicy`; plan groups type-only
+steps under `plan.typeOnlyGroup` when volume is high.
+
+### Next.js API shell (framework overlay / presets)
+
+When Next is detected (or `ui-surface` / monorepo patterns apply), **`app/api/**` and
+`pages/api/**` classify as Application orchestration**, not Presentation. UI routes stay
+Presentation. More-specific Application globs win over broad `**/app/**` Presentation patterns.
+See [brownfield adoption](brownfield-adoption.md#nextjs-honesty-default-overlays--ui-surface--monorepo).
+
+### ArkRules dual plane (when `arkRules` is present)
+
+| Plane | What it is | Merge teeth |
+|-------|------------|-------------|
+| **Layers** | Inter-layer import graph | Always on |
+| **Structure sensors** | Intra-layer heuristics | Only `mode: "enforced"` |
+| **Invariants** | Catalog + coverage evidence (not a business runtime) | Only enforced + proven-uncovered |
+
+Absence of `arkRules` adds **no** extra merge teeth. **Advisory** structure sensors and advisory
+invariants also add **no** merge teeth (FG-ARKRULES-ADVISORY-ONLY) — packing every starter
+`arkrules/*` file does not make merge fail structure alone. Enforced structure/invariants arm
+`mergePlanes.extraMergeTeeth` only when the layer plane is honestly classified
+(governed ≥ 50% and ≥ 1 populated layer); empty classification never gets structure teeth
+(P1M-EXTRATEETH-EMPTY-GRAPH). Structure and invariants **never** merge into one architecture
+score. Doctor exposes `rulesUnderContract.mergePlanes` for which plane can fail.
+
 Safety fields:
 
 - `maxTsSuppressions`, `maxAnyCasts`
@@ -119,20 +155,36 @@ policy.
 
 Sibling schema export: `arkgate/schema/arkrules` (`schemas/ark.arkrules.schema.json`).
 
+**Two planes (never one score):**
+
+| Plane | Question | Where |
+|-------|----------|--------|
+| **[Layer]** (inter-layer) | Who may import whom? Pure / forbidden globals / capabilities? | `layers[]` + `rules[]` |
+| **[ArkRules]** (intra-layer, opt-in) | How is code shaped *inside* a layer, and which named business policies are catalogued with coverage evidence? | `arkRules` map + `arkrules/<ExactLayerName>.json` |
+
+Absence of `arkRules` is valid: only the Layers plane runs; inter-layer verdict is unchanged.
+
 Each `arkrules/<Layer>.json` may declare:
 
-| Section | Purpose | Modes |
-|---------|---------|--------|
-| `structure[]` | Closed sensor ids (e.g. `aggregate-private-state`, `always-valid-factory`, `thin-adapter`) | `advisory` (default) or `enforced` |
-| `invariants[]` | Stable ids + description + optional coverage (`test` / `symbol`) | `advisory` or `enforced` |
+| Section | Purpose | Modes | What it really enforces |
+|---------|---------|--------|-------------------------|
+| `structure[]` | Closed sensor ids (e.g. `orchestration-only`, `thin-adapter`, `aggregate-private-state`, `always-valid-factory`, `domain-event-on-mutation`, `no-anemic-model`) | `advisory` (default) or `enforced` | **Heuristics of module shape** — not proof that logic was extracted to Domain. Tier-2 sensors (`no-anemic-model`) stay advisory-only (cannot promote to enforced). |
+| `invariants[]` | Stable ids + description + `coverage` (`test` / `symbol`) + optional `appliesTo` globs | `advisory` or `enforced` | **Named policy + evidence** (symbol in source and/or test title/content). Does **not** execute business logic at check time and does **not** replace behavior/property tests. |
 
 **Reporting:** diagnostics carry `evidence.arkruleId` + `evidence.arkruleSource`. Label residual
-**`[Layer]`** (import edges / capabilities) vs **`[ArkRules]`** (structure / invariants) in agent
-output. Doctor JSON: `rulesUnderContract` (counts, never a score).
+**`[Layer]`** vs **`[ArkRules]`** in agent output. Doctor / HTML: `rulesUnderContract` (catalog +
+counts, **never a score**). Showcase HTML lists per-layer totals, structure sensors, uncovered
+invariants, and a covered sample when the map is active.
 
 **Promotion:** advisory→enforced is strengthening when coverage evidence exists; demote/delete is
 a hash-bound policy weakening. Empty `appliesTo: []` fails closed; zero-match globs emit
-`ARKRULE_SCOPE_EMPTY` (advisory warn / enforced fail).
+`ARKRULE_SCOPE_EMPTY` (advisory warn / enforced fail). Enforced + proven uncovered →
+`INVARIANT_UNCOVERED` with `failsStrict` (partial evidence stays honest, never fake-green).
+
+**What they do not do:** prove business semantics end-to-end; replace Layers import edges;
+make “green” mean elegant Shape. Promoting structure to enforced can force rename-to-pass
+heuristics — prefer judgment extraction via `/ark-fix` / `/ark-loop` when the real goal is
+Domain ownership.
 
 ```bash
 # Brownfield candidates (not a score)

package/docs/package-surface.md

@@ -189,6 +189,7 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(prepared: [4.0.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.0.md);
-last published: [3.9.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.9.2.md)).
+(current published: [4.0.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.1.md);
+next prepared: [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md);
+previous: [4.0.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.0.md)).
 Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](https://github.com/pedroknigge/arkgate/blob/main/CONTRIBUTING.md)).

package/docs/product-voice.md

@@ -51,8 +51,11 @@ Examples:
 | **contract** | `ark.config.json` layers, rules, include — the machine-readable architecture file |
 | **Layers plane** | Inter-layer edges: imports, placement, purity, isolation |
 | **ArkRules** (opt-in) | Intra-layer structure sensors + domain invariant catalogs as data (`arkrules/*`) |
+| **advisory ArkRules** | Default sensor mode — **not** merge teeth; does not fail CI/merge alone (FG-ARKRULES-ADVISORY-ONLY) |
+| **extraMergeTeeth** | Only when enforced structure/invariant rules exist **and** classification is honest (≥50% governed, ≥1 populated layer) |
 | **dual-plane residual** | Label findings **`[Layer]`** vs **`[ArkRules]`** — never blur them |
 | **rulesUnderContract** | Doctor/inventory counts for ArkRules — **never a score** |
+| **type-only placement debt** | `import type` edges on the violations list with `failsStrict:false` — prefer SharedTypes / owning layer; not runtime coupling |
 | **gate** / **write gate** | Host boundary that blocks or advises on invalid writes |
 | **edges** | Allowed import graph (plan **A** / remediation) |
 | **baseline** | Frozen known debt; does not make a wrong contract honest |
@@ -83,6 +86,7 @@ Examples:
 | Keep Suggest on start → doctor | New-here primary is finish `start`, not a competing recommend/architect curriculum |
 | Qualify edge-clean under design-weak | “None on checked edges … design residual remains. Not healthy finished.” |
 | Prefer fail-closed over fake hard | Incomplete analysis, unobserved hooks, and soft MCP never paint as hard green |
+| Honesty clear ≠ architecture healthy | `productHonesty.finished` means residual honesty sensors are clear — not a green graph score. Open blocking violations, ADAPT/SUGGEST with debt, dual-truth pin, or design residual keep `unfinished: true`. |
 
 ## Avoid
 
@@ -95,7 +99,12 @@ Examples:
 | “modes you pick” for Suggest/Adapt/Enforce | Those are **status lights**, not settings |
 | Skill-shopping lists as the default curriculum | Progressive disclosure: one door first |
 | “Healthy / done” while design-weak | False done |
-| “ArkRules prove business correctness” | They enforce *declared* structure/coverage evidence, not arbitrary logic |
+| “Honesty clear” as “architecture finished” | Honesty clear only means residual honesty sensors are quiet; graph/mode debt is separate |
+| “ArkRules prove business correctness” | They enforce *declared* structure/coverage evidence, not arbitrary logic or full semantic proof |
+| “Structure enforced = Domain extraction done” | Structure sensors are **heuristics**; extraction is judgment (`/ark-fix` / pilot) |
+| “Covered invariant = E2E business tests” | Coverage = symbol/test evidence for a named policy, not a runtime test runner |
+| “Max arkRules packs = merge fails structure” | **Advisory ArkRules ≠ merge teeth.** Only `mode: "enforced"` can add teeth, and only after honest classification (FG-ARKRULES-ADVISORY-ONLY) |
+| “Type-only volume means the gate is broken” | High type-only count is placement debt (behavior OK); group under plan A type-only, offer SharedTypes starter |
 | Blurring import edges with invariants | Always label **`[Layer]`** vs **`[ArkRules]`** |
 
 ---

package/docs/typescript-support.md

@@ -176,11 +176,15 @@ The release compatibility workflow packs the candidate first, then tests clean c
 - **npm / pnpm / Yarn**;
 - project TypeScript **5.9.3 / 6.0.3 / 7.0.2**.
 
-That is 36 installed-artifact cells. Each cell verifies that the project's `tsc` stays on the
-requested project compiler and that ArkGate resolves its fallback as exact 6.0.3 when the project
-API is unusable. Reports record `installMode` so the Yarn TS7 linker boundary cannot disappear
-behind a green job. All 36 cells passed on source `228dd893` in CI run `29655190747`. Locally, the
-repository entry point is:
+That is **36** installed-artifact cells on the **full matrix** path (`push` to `main`, PR labels
+`full-matrix` / `release`, or release-prep branch names such as `feat/4.1*`). Ordinary PRs run a
+**slim** packed smoke: **one** cell (Node 20 + npm) that still exercises TS 5/6/7 in-process.
+See [CONTRIBUTING.md — CI profiles](../CONTRIBUTING.md#ci-profiles-pr-slim-vs-full-matrix).
+
+Each cell verifies that the project's `tsc` stays on the requested project compiler and that
+ArkGate resolves its fallback as exact 6.0.3 when the project API is unusable. Reports record
+`installMode` so the Yarn TS7 linker boundary cannot disappear behind a green job. All 36 cells
+passed on source `228dd893` in CI run `29655190747`. Locally, the repository entry point is:
 
 ```bash
 npm run test:ts-compat

package/docs/use.md

@@ -40,12 +40,14 @@ ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enfo
 
 ### Two planes (you choose)
 
-| Plane | Plain English | Config |
-|-------|---------------|--------|
-| **Layers** | Who may talk to whom (imports, purity) | `ark.config.json` layers + rules |
-| **ArkRules** (optional) | Habits *inside* a layer (aggregates, factories, named invariants) | `arkRules` + `arkrules/<Layer>.json` |
+| Plane | Plain English | Config | Enforces |
+|-------|---------------|--------|----------|
+| **Layers** | Who may talk to whom | `layers[]` + `rules[]` | Import direction, purity, forbidden globals, capabilities, peer isolation |
+| **ArkRules** (optional) | Habits *inside* a layer + named policies | `arkRules` + `arkrules/<Layer>.json` | Structure **heuristics** (module shape); invariant **catalog + coverage evidence** (not full business proof) |
 
-Start always gives you **layers**. ArkRules templates may ship with start/init; they begin **advisory** until you promote them. Doctor may show `rulesUnderContract` counts (not a score).
+Start always gives you **layers**. ArkRules templates may ship with start/init; they begin **advisory** until you promote them. Doctor / HTML show `rulesUnderContract` (catalog, **not a score**). No `arkRules` map is fine — only Layers run.
+
+**Do not confuse:** green Layers ≠ perfect design (Shape residual can remain). Covered invariants ≠ “the business always does the right thing” — they mean the named policy is declared and has symbol/test evidence.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -136,6 +136,7 @@
     "check:package-files": "node scripts/verify-package-files.mjs",
     "check:release-artifacts": "node scripts/verify-release-artifacts.mjs",
     "test:release-artifacts": "vitest run tests/unit/scripts/verifyReleaseArtifacts.test.ts",
+    "test:field-dogfood-smoke": "node scripts/field-dogfood/smoke.mjs",
     "audit:beta-exit": "node scripts/beta-exit-audit.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
@@ -156,6 +157,7 @@
   "overrides": {
     "qs": "6.15.3",
     "vite": "6.4.3",
+    "postcss": "8.5.23",
     "tsup": {
       "esbuild": "0.28.1"
     },

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/arkgate",
-  "description": "ArkGate \u2014 architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
+  "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.0.0",
+  "version": "4.1.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.0.0",
+      "version": "4.1.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/architecture-playbook.json

@@ -86,6 +86,9 @@
       "label": "UI-focused repository; backend lives elsewhere or is thin",
       "preset": "layered",
       "presetAlternatives": {
+        "vite-vercel-spa": {
+          "whenSignal": "viteVercelSpaLayout"
+        },
         "feature-sliced": {
           "whenSignal": "featureSlicedLayout"
         }

package/templates/layers/shared-types.starter.json

@@ -0,0 +1,29 @@
+{
+  "$comment": "Optional SharedTypes layer starter (NEW-TYPEONLY-VOLUME). Copy the layer + allow rules into ark.config.json when type-only placement debt volume is high. Both application and presentation may import SharedTypes; SharedTypes must not import adapters or orchestration.",
+  "layer": {
+    "name": "SharedTypes",
+    "patterns": [
+      "src/types/**",
+      "src/shared/types/**",
+      "packages/shared/src/types/**",
+      "lib/types/**"
+    ],
+    "intentPrefixes": ["Shared.Types."]
+  },
+  "suggestedRules": [
+    { "from": "DomainModel", "to": "SharedTypes", "allowed": true },
+    { "from": "ApplicationOrchestration", "to": "SharedTypes", "allowed": true },
+    { "from": "PresentationAdapters", "to": "SharedTypes", "allowed": true },
+    { "from": "PersistenceAdapters", "to": "SharedTypes", "allowed": true },
+    { "from": "SharedTypes", "to": "DomainModel", "allowed": false },
+    { "from": "SharedTypes", "to": "ApplicationOrchestration", "allowed": false },
+    { "from": "SharedTypes", "to": "PresentationAdapters", "allowed": false },
+    { "from": "SharedTypes", "to": "PersistenceAdapters", "allowed": false }
+  ],
+  "guidance": [
+    "Type-only edges (`import type`) are placement debt — failsStrict:false; value edges still block merge.",
+    "Move pure type modules both sides need into SharedTypes (or an owning Domain surface).",
+    "Do not put runtime logic or I/O in SharedTypes.",
+    "Doctor violations.typeEdgePolicy and plan.typeOnlyGroup describe the same policy."
+  ]
+}

package/templates/skills/ark-adopt.md

@@ -99,6 +99,8 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    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`.
+   **Next.js:** `app/api/**` / `pages/api/**` (and route-group `app/(…)/api/**`) default to
+   **ApplicationOrchestration**, not Presentation — do not reclassify API shells as UI.
 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.
    If one edge dominates residual debt: **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).

package/templates/skills/ark-explain.md

@@ -45,8 +45,20 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 
 
 ### Explain + ArkRules
-- HTML/plain tour: section **Layers** and section **ArkRules** (structure + invariants + residual).
-- Never merge them into one “architecture score.”
+- HTML/plain tour: section **Layers** and section **Rules under contract (ArkRules)** —
+  when `arkRules` is active the showcase lists **per-layer counts**, **structure sensors**
+  (id / sensor / mode), **uncovered** invariants (call them out), and a **covered sample**.
+  Inactive map stays a short opt-in note. Counts are never a score.
+- Spoken tour: name 2–4 real invariant IDs and one structure sensor from this repo’s
+  `arkrules/*` (open the files — do not invent). Residual candidates → `--rules-inventory`.
+- **Teach the product model (required when arkRules is active):**
+  - **[Layer]** = dependency direction / purity / capabilities.
+  - **[ArkRules] structure** = module-shape **heuristics** (orchestration-only, thin-adapter, …);
+    enforced is not proof of Domain extraction.
+  - **[ArkRules] invariants** = named business policies as **data + coverage evidence**
+    (symbol/test); not a runtime engine and not a substitute for behavior tests.
+  - Green edges + covered catalog ≠ elegant Shape (design-weak residual stays honest).
+- Never merge Layers and ArkRules into one “architecture score.”
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -117,15 +129,21 @@ the same files or weaken the gate.
    (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.
+dependency direction, matrix, violations, **ArkRules under contract** (when mapped),
+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 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; W6 port-proof inject is judgment when proof holds) — everything
 else is judgment/deferred and must not be auto-applied.
 
+**Type-edge honesty:** type-only denied edges are **placement debt** (`typeOnly` +
+`failsStrict: false`) — prefer SharedTypes / owning layer; they do not fail merge like value
+edges. Doctor `productHonesty` and `violations.typeEdgePolicy` must not be sold as “all done”
+when residual signals remain.
+
 ## Spoken / written explanation
 
 1. **Load the real contract**: `ark.config.json`, `ark://manifest` if available, `AGENTS.md`.

package/templates/skills/ark-explore.md

@@ -276,6 +276,25 @@ in parallel. When `pilotLoop.queuedBets > 0`, those bets stay **queued**, not co
 lines — never silent codemod of plan B. After the pilot lands, re-run doctor; success =
 reduced evidence on pilot paths.
 
+### Plan B one-pilot checklist (mandatory before any B apply)
+
+Empty plan A + design-weak is **not** architecture finished. Plan B is judgment only.
+
+| Step | Gate | Fail closed if… |
+|------|------|-----------------|
+| 1. Confirm residual | `designFitness.designWeak` **or** non-empty `patternBets` / `designSmells` | You would claim healthy finished because plan A is empty |
+| 2. Pick **one** pilot | `pilotLoop.nextPilot` (preferred) **or** one ranked B bet with a path scope | Multi-pilot batch / “fix all smells this PR” |
+| 3. Write extraction card | Pilot · Smell · Move · Do not · Success · **Kill-switch** · Next | Missing kill-switch or success signal |
+| 4. User OK | Explicit approval before edit (or stay map-only) | Silent auto-apply of plan B |
+| 5. Apply **only** that pilot | Via `/ark-autopilot` (apply B) or `/ark-fix` (one cluster) | Opening a second pilot before re-doctor |
+| 6. Re-doctor | Success = reduced evidence on pilot paths; residual outside pilot may remain | Declaring whole-tree done from one pilot |
+
+**Hard lines (never break):**
+- `killSwitch` / kill-switch is **required** on every B card (stop condition if pilot does not reduce confusion).
+- `multiPilotBatchForbidden` — never multi-batch Shape extractions.
+- `autoApplyPlanBForbidden` / `neverMechanicalSafe: true` — never invent mechanical-safe for B.
+- `healthyFinishedForbidden` while design-weak — empty plan A is baseline, not done.
+
 ```text
 ### Extraction card
 Pilot: <one dir or feature — or pilotLoop.nextPilot.pilotTarget>
@@ -286,8 +305,9 @@ Do not:
   - weaken ark.config.json
   - auto-apply as mechanical-safe or invent new mechanical-safe kinds
   - big-bang the monorepo
+  - open a second pilot before re-doctor
 Success: <observable / falsifiable — re-doctor>
-Kill-switch: <stop condition>
+Kill-switch: <stop condition — e.g. if pilot does not clear smell evidence in 1 PR → stop / re-map>
 Next: /ark-autopilot (apply with user ok) | /ark-fix (one cluster) | re-doctor
 ```
 

package/templates/skills/ark-fix.md

@@ -19,16 +19,27 @@ the two files on the violation edge.
 
 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 `docs/brownfield-adoption.md`
-§6 and explore §G. Fixed fields (never mechanical-safe, never silent B apply):
+§6 and explore §G. Fixed fields (never mechanical-safe, never silent B apply).
+
+### Plan B one-pilot checklist (when Shape residual, not a single edge fix)
+
+Empty plan A + `designWeak` is **not** architecture finished. One pilot only:
+
+1. **Confirm** doctor `designFitness.designWeak` / non-empty `patternBets` (or agent-detected smell).
+2. **One pilot** — prefer `pilotLoop.nextPilot`; never multi-batch concurrent Shape extractions.
+3. **Extraction card** with **Kill-switch** + falsifiable Success (required).
+4. **User OK** before apply — `autoApplyPlanBForbidden` / never mechanical-safe.
+5. **Edit only that pilot scope** — then `ark-check` / re-doctor; residual outside pilot may remain.
+6. **Stop** if kill-switch fires; do not open pilot #2 in the same batch.
 
 ```text
 ### Extraction card
-Pilot: <one directory or feature path>
+Pilot: <one directory or feature path — or pilotLoop.nextPilot.pilotTarget>
 Smell: <doctor designSmells id if present>
 Move: <verbatim relocate / split>
-Do not: rewrite queries; weaken ark.config; invent mechanical-safe kinds; big-bang
-Success: <falsifiable>
-Kill-switch: <stop condition>
+Do not: rewrite queries; weaken ark.config; invent mechanical-safe kinds; big-bang; multi-pilot batch
+Success: <falsifiable — re-doctor on pilot paths>
+Kill-switch: <stop condition — required>
 Next: re-run ark-check; shrink baseline if applicable
 ```
 

package/templates/skills/ark-upgrade.md

@@ -43,7 +43,10 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 
 ## 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**
@@ -72,16 +75,54 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 
 ## 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
@@ -89,10 +130,10 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
    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
@@ -105,20 +146,25 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
    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