arkgate 4.0.1 → 4.1.1

package/docs/README.md

@@ -52,14 +52,14 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · [CHANGELOG.md](../CHANGELOG.md) |
-| Epic plans (seeded + shipped) | [plans/](plans/) |
+| Epic plans (seeded + shipped) | [plans/](plans/) · latest: [enforcement-evidence-and-docs-truth](plans/enforcement-evidence-and-docs-truth/README.md) (Phase EH shipped; 4.1.1 prepared) |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Current major on npm `latest`: [releases/4.0.0.md](releases/4.0.0.md) (`arkgate@4.0.0` — layers + optional **ArkRules**).  
-Next prepared: [releases/4.0.1.md](releases/4.0.1.md) (`arkgate@4.0.1` — not yet `latest`).  
-Previous: [releases/3.9.2.md](releases/3.9.2.md) (`arkgate@3.9.2`).  
+Current published: [releases/4.1.0.md](releases/4.1.0.md) (`arkgate@4.1.0` on npm `latest`).  
+Prepared next: [releases/4.1.1.md](releases/4.1.1.md) (Phase EH — **Status: prepared**, not on npm until publish).  
+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).
 
 ---
@@ -68,5 +68,5 @@ Config: [configuration.md](configuration.md) · Agent skills dual-plane: [agent-
 
 1. **Audience first** — every page should be use, develop, or contribute.
 2. **One primary flow** — `start` → doctor → optional guided work.
-3. **Honest hardness** — host write guarantees differ; CI required status is the shared merge boundary.
+3. **Honest hardness** — host write guarantees differ; a **required GitHub status context** running the merge CLI is the shared hard boundary.
 4. **History is not the product** — version archaeology lives under `releases/` and `plans/`, not the front door.

package/docs/agent-guide.md

@@ -40,9 +40,11 @@ npx ark-check --install-agent-gates --skills-only --force
 
 **Write-path honesty:** Claude/Grok/Antigravity can hard-block listed PreToolUse ops when
 installed and trusted. Cursor/Codex/OpenCode remain **advisory at write**. For every host, the
-repository-wide hard boundary is a **required** CI status (`arkgate-check --strict-merge`) —
-never claim Cursor/Codex/OpenCode hard write. See [ai-gates.md](ai-gates.md) and the README host
-matrix.
+repository-wide hard boundary is a **required GitHub status context** that runs
+`arkgate-check --strict-merge` (alias `ark-check --strict-merge`) — the CLI name is not the
+status context name. Never claim Cursor/Codex/OpenCode hard write. Soft-write alone does not mean
+the project is unfinished; doctor keeps it as an environment residual. See [ai-gates.md](ai-gates.md)
+and the README host matrix.
 
 ## Architecture playbook and `ark-check --recommend`
 

package/docs/ai-gates.md

@@ -307,8 +307,10 @@ required CI status is the hard repository boundary.
 npx ark-check --install-agent-gates --tools codex
 ```
 
-The generated hook includes `--hook-repair`, so a rejected patch carries the same structured
-repair envelope as Claude and Grok. Codex still needs hook trust enabled for the project.
+The generated hook includes `--hook-repair`, so a rejected patch **may emit** a structured
+repair envelope (same JSON shape as Claude/Grok). **Reinjection is not guaranteed** on Codex —
+local write stays advisory/bypassable; the host must re-apply any fix, and required CI remains
+the hard merge boundary. Codex still needs hook trust enabled for the project.
 
 Modern Codex resolves MCP servers from the active project's `.codex/config.toml`. Ark writes
 that file with relative paths, so every repository owns its primary `ark` binding without
@@ -387,7 +389,7 @@ Ark verifies those references against each selected host catalog.
   `--skills-only --tools codex --force` (repo) or `--codex-home --force` (home) fix.
 - Codex **write path is advisory**: MCP + best-effort `.codex/hooks.json` is **not** a hard
   write boundary and is **not** equivalent to Claude/Grok PreToolUse hard-write + repair.
-  The hard merge backstop is CI `--strict-merge` (or `--strict`) plus a required status check.
+  The hard merge backstop is CI `--strict-merge` (or `--strict`) as a **required GitHub status context** (not “workflow file present”).
 - CI workflows that run ark-check without the fail-closed profile (or with only
   `--strict-config`) surface gap `enforcement-ci-not-fail-closed`.
 
@@ -560,21 +562,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.
 
@@ -587,13 +593,34 @@ for standalone linting where no project contract applies.
 Whatever the agent side does, run the merge profile in CI:
 
 ```yaml
-- run: npx ark-check --root . --config ark.config.json --strict-merge --fail-on-new-smells --base-ref "${{ github.event.pull_request.base.sha || github.event.before }}"
+# EH04: first push may have all-zero github.event.before — only pass --base-ref when resolvable.
+- name: Ark architecture check
+  env:
+    ARK_POLICY_BASE_REF: ${{ github.event.pull_request.base.sha || github.event.before }}
+  run: |
+    set -euo pipefail
+    BASE_REF="${ARK_POLICY_BASE_REF:-}"
+    if [[ "$BASE_REF" =~ ^0{40,64}$ ]]; then BASE_REF=""; fi
+    if [ -n "$BASE_REF" ] && git cat-file -e "${BASE_REF}^{commit}" 2>/dev/null; then
+      export ARK_POLICY_BASE_REF="$BASE_REF"
+      npx ark-check --root . --config ark.config.json --strict-merge \
+        --fail-on-new-smells --base-ref "$BASE_REF"
+    else
+      export ARK_POLICY_BASE_REF=""
+      npx ark-check --root . --config ark.config.json --strict-merge
+    fi
 ```
 
 This explicit brownfield ratchet records schema `1.0` identities, touched paths, and stable
-evidence; missing base exits `2`. Its first semantic smell is `domain-logic-in-ui`; residual,
-path-only moves, and unrelated work stay green. Generated Claude/Grok hooks share the delta and
-golden-pattern repair hint. MCP exposes the result but stays advisory.
+evidence; missing base with `--fail-on-new-smells` exits `2`, so the generated workflow skips the
+delta when the SHA is all-zero or unresolvable while keeping the full merge gate. Its first
+semantic smell is `domain-logic-in-ui`; residual, path-only moves, and unrelated work stay green.
+Generated Claude/Grok hooks share the delta and golden-pattern repair hint. MCP exposes the result
+but stays advisory.
+
+**CLI vs required status:** `arkgate-check --strict-merge` / `ark-check --strict-merge` is the
+**command**. The hard merge boundary is making that job a **required GitHub status context** —
+not “workflow file present.”
 
 Or use the repository's composite Action at a pinned release or commit:
 

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

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`

package/docs/develop.md

@@ -14,14 +14,18 @@ npx arkgate start --apply
 npx arkgate-check --doctor
 ```
 
-Make the architecture check a **required** merge status (GitHub/GitLab/etc.):
+Make the architecture check a **required** merge **status context** (GitHub/GitLab/etc.). The CLI
+command is `arkgate-check --strict-merge` / `ark-check --strict-merge` — the hard boundary is
+requiring that job’s status, not merely adding a workflow file:
 
 ```yaml
 - run: npx arkgate-check --root . --config ark.config.json --strict-merge
 # or: uses: pedroknigge/arkgate@<tag-or-SHA>
 ```
 
-`--strict-merge` (or compatibility `--strict`) is the repository-wide hard boundary for every agent host.
+Generated workflows also gate `--fail-on-new-smells --base-ref` so a first push with an all-zero
+`github.event.before` still runs the full merge gate without a broken delta (see
+[ai-gates.md](ai-gates.md#ci-backstop)).
 
 ---
 
@@ -31,9 +35,9 @@ Local write hardness **differs by host**. CI required status is the shared hard
 
 | Host | Local write | MCP | Merge |
 |------|-------------|-----|-------|
-| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status |
-| Codex · OpenCode | Best-effort / advisory | Advisory | Required status |
-| Cursor | Advisory only | Advisory | Required status |
+| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status context |
+| Codex · OpenCode | Best-effort / advisory | Advisory | Required status context |
+| Cursor | Advisory only | Advisory | Required status context |
 
 Full matrix and install commands: [ai-gates.md](ai-gates.md) · canonical table in [README](../README.md#host-enforcement-support).
 
@@ -46,7 +50,13 @@ npx arkgate-check --install-agent-gates --tools opencode
 npx arkgate-check --install-agent-gates --skills-only --force
 ```
 
-Doctor reports what is actually installed and observed (`writePath` / enforcement state). Installed files alone do not imply `hard:true` without runtime evidence where the product requires it.
+Doctor reports what is actually installed and observed (`writePath` / enforcement state). Installed
+files alone do not imply `hard:true` without runtime evidence where the product requires it.
+
+**Evidence split (Phase EH):** soft-write hosts keep `soft-write-host` in evidence without forcing
+global **Not finished** when the contract is ready. With `ARK_DOCTOR_GITHUB=1`, successful CI runs
+can show `runtimeObserved: true` even when branch-protection policy is plan-unavailable
+(`unavailable-plan` on GitHub Free private); `hard: false` until the status is required.
 
 ---
 

package/docs/package-surface.md

@@ -37,6 +37,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`arkRules`** map (schema `1.1+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `arkRules` is byte-for-byte silent on inter-layer verdicts. |
 | **ArkRules inventory / under-contract (4.0)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
+| **Product honesty readiness split (4.1.1 EH)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
 | **Policy transition analysis (T01, 3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
 | **Atomic change preflight (T02, 3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
 | **Architecture change map (T03, 3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
@@ -189,7 +190,8 @@ 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)
-(current on npm: [4.0.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.0.md); prepared:
-[4.0.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.1.md); previous:
-[3.9.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.9.2.md)).
+(current published: [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md);
+prepared next: [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md);
+previous: [4.0.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.1.md),
+[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 |
@@ -70,7 +73,9 @@ Examples:
 | **compact router** | Default onboarding agent instructions (not the full skill pack) |
 | **hard write** | Non-bypassable PreToolUse block for listed ops (Claude/Grok when installed + trusted) |
 | **advisory write** | MCP/rules coach only (Cursor/Codex at write time) — not a hard block |
-| **required CI** | Merge hard boundary when the repository makes `arkgate-check` a required status |
+| **required CI / status context** | Merge hard boundary when the repository makes the Ark job a **required GitHub status context** (CLI: `arkgate-check --strict-merge` / `ark-check --strict-merge`) |
+| **contract ready** | Project/layers/ArkRules honesty residual clear — not the same as “hard local write” |
+| **environment residual** | Permanent host/provider posture (e.g. soft-write Codex) kept in evidence without forcing global **Not finished** |
 
 ## Do (product copy)
 
@@ -79,10 +84,13 @@ Examples:
 | Name the status light + plain fact + term + next action | “Enforce · design-weak. Checked edges are honest; design smells remain. Next: one Shape door — explore → dual-plan B → autopilot with OK.” |
 | Rank one primary door under residual | Doctor **Primary next action** #1; **Also** only for secondary |
 | Label expert skills as escapes | “Install skill pack only when doctor or a STOP handoff names a skill.” |
-| State host write honesty | “Cursor/Codex: advisory write. Required CI is the hard merge boundary.” |
+| State host write honesty | “Cursor/Codex: advisory write. Required GitHub status context is the hard merge boundary.” |
+| Soft-write ≠ unfinished project | “Architecture contract ready; Codex local writes are advisory.” Keep `soft-write-host` in evidence; reserve **Not finished** for contract/project debt. |
 | 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 **architecture** 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`. Permanent soft-write alone does **not**. |
+| Separate CI runtime from provider policy | Successful CI run ≠ required status; GitHub Free plan 403 → `unavailable-plan`, not “CI never ran.” |
 
 ## Avoid
 
@@ -95,9 +103,14 @@ 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 |
+| “Honesty clear” as “architecture finished” | Honesty clear only means residual honesty sensors are quiet; graph/mode debt is separate |
+| “Not finished” solely because host is Codex/Cursor | Soft-write is environment residual; do not paint a green whole-tree project as unfinished architecture |
+| Conflating CLI name with required status | `ark-check` is the command; the hard boundary is the GitHub required **status context** |
 | “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

@@ -33,9 +33,11 @@ Full skill pack is **optional** (expert depth). Day-to-day: compact router + doc
 | When | What happens |
 |------|----------------|
 | While the AI writes | Host write gate or advisory MCP (depends on host) |
-| Before merge | `arkgate-check` — make it a **required** CI status |
+| Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) |
 | Anytime | Doctor: Suggest / Adapt / Enforce (+ design-weak if residual) |
 
+**Codex / Cursor / OpenCode:** local write stays advisory forever — that is not unfinished architecture. Doctor may say **contract ready** while still reminding you that local writes are advisory; **Not finished** is reserved for real project/contract debt.
+
 ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + co-pilot for AI TypeScript.
 
 ### Two planes (you choose)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.0.1",
+  "version": "4.1.1",
   "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.1",
+  "version": "4.1.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.0.1",
+      "version": "4.1.1",
       "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

@@ -139,6 +139,11 @@ When explaining the **plan**, name the four `mechanical-safe` remediation kinds
 `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
 ```