arkgate 4.6.3 → 4.6.5

package/docs/README.md

@@ -58,10 +58,11 @@ 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) |
 
-Current published: [releases/4.6.2.md](releases/4.6.2.md) (`arkgate@4.6.2` on npm `latest`).  
-Prepared: [releases/4.6.3.md](releases/4.6.3.md) (Codex operation-scoped hard write; not yet published).
-Prior: [releases/4.6.1.md](releases/4.6.1.md) (`arkgate@4.6.1`).  
-Previous: [releases/4.6.0.md](releases/4.6.0.md) · [releases/4.5.7.md](releases/4.5.7.md) · [releases/4.5.6.md](releases/4.5.6.md) · [releases/4.5.5.md](releases/4.5.5.md) · [releases/4.5.0.md](releases/4.5.0.md) · [releases/4.4.0.md](releases/4.4.0.md) · [releases/4.3.0.md](releases/4.3.0.md) · [releases/4.2.1.md](releases/4.2.1.md) · [releases/4.2.0.md](releases/4.2.0.md) · [releases/4.1.1.md](releases/4.1.1.md).  
+Current: [releases/4.6.5.md](releases/4.6.5.md) (`arkgate@4.6.5`).
+Prior published: [releases/4.6.4.md](releases/4.6.4.md) (`arkgate@4.6.4` on npm `latest` until 4.6.5 lands).
+Prior published: [releases/4.6.3.md](releases/4.6.3.md) (`arkgate@4.6.3`).
+Prior: [releases/4.6.2.md](releases/4.6.2.md) (`arkgate@4.6.2`).
+Previous: [releases/4.6.1.md](releases/4.6.1.md) · [releases/4.6.0.md](releases/4.6.0.md) · [releases/4.5.7.md](releases/4.5.7.md) · [releases/4.5.6.md](releases/4.5.6.md) · [releases/4.5.5.md](releases/4.5.5.md) · [releases/4.5.0.md](releases/4.5.0.md) · [releases/4.4.0.md](releases/4.4.0.md) · [releases/4.3.0.md](releases/4.3.0.md) · [releases/4.2.1.md](releases/4.2.1.md) · [releases/4.2.0.md](releases/4.2.0.md) · [releases/4.1.1.md](releases/4.1.1.md).
 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/agent-guide.md

@@ -86,6 +86,16 @@ npx ark status --json --expected-root /abs/project/root
 npx ark-check --doctor --json
 ```
 
+`--doctor --json` is a stable envelope (4.6.5+): `{ "schemaVersion": "1.0", "envelope": "doctor", "ok": boolean, "doctor": { … } }`.
+Payload lives only under `doctor`. Do not parse sibling root keys as the doctor object.
+
+Doctor also writes `.ark/ci-merge-boundary.json` (hook configured-not-fired, per-host writePath,
+CI present-but-not-required, GitHub Free cannot require). Read that file — do not grep `node_modules`.
+Hook green is not tree green (scripted edits bypass PreToolUse).
+
+CLI-first: if the local CLI already resolved the project root, identity handshake is optional.
+Do not wait on MCP “still connecting”. The same projection schema is merged into `AGENTS.md` and `CLAUDE.md`.
+
 Product path: [use.md — Session recipe](use.md#session-recipe-agent-turn).
 
 ### Multi-project MCP and upgrade honesty (4.5.6)
@@ -97,7 +107,8 @@ One human often has **N checkouts** and **N package pins**. Product rules:
 | One checkout = one `project.expectedRoot` | Identity (WI01) fail-closes cross-project evidence when used correctly |
 | After `npm install arkgate@…`, restart/retarget Ark MCP | Process `arkgateVersion` is startup-loaded; long-lived MCP can lag install |
 | Read `processPackage` on every tool response | `processPackageMismatch` / `processStale` + `nextAction` when process ≠ project install |
-| Prefer project-local CLI until versions align | CLI always available; MCP analysis is not “fully current” while process is stale |
+| Stale MCP in 4.6.4+ | `ark_identity` stays diagnostic; project tools return `PROCESS_PACKAGE_STALE` and top-level `authoritative:false` until restart |
+| Prefer project-local CLI until versions align | A modern stale global `ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry |
 | Upgrade each package that pins arkgate | Monorepo “done” is not one package’s pin |
 | Registry-aware `ark upgrade --apply` | Does not false-skip when CLI == pin but registry is ahead; skip JSON has `reasonCode` + `suggestedInstallCmd` |
 | Skills: `skillDrift` + optional `--refresh-skills` | Customized skill bodies stay preserved unless you opt in; never silent overwrite of true edits |

package/docs/ai-gates.md

@@ -416,6 +416,11 @@ observe a later MCP conversation from files alone. The matched `ark_identity` re
 runtime observation for that caller and live process; it does not mutate the setup JSON.
 `.codex/config.toml` by itself never upgrades `runtimeObserved` or `active`.
 
+After a package bump, a long-lived Ark MCP whose package version no longer matches the project is
+non-authoritative. `ark_identity` reports `processPackage.processStale`; project tools return
+`PROCESS_PACKAGE_STALE` until Codex/local Desktop restarts or retargets the server. A modern
+outside-tree/global `ark upgrade` hands the original invocation to the project-local CLI.
+
 Codex uses an operation-scoped hard local patch hook plus advisory MCP for discovery/validation
 and `ark-check` as the all-path hard merge backstop. Register all three as soon as the repo is
 adopted.

package/docs/brownfield-adoption.md

@@ -41,10 +41,16 @@ regenerate it unasked.
 | `app/api/**`, `src/app/api/**` | **ApplicationOrchestration** (orchestration shell) |
 | `pages/api/**`, `src/pages/api/**` | **ApplicationOrchestration** |
 | UI routes (`app/(…)`, `page.tsx`, `components/**`) | **PresentationAdapters** |
+| Types / constants (`src/**/types/**`, `src/**/constants/**`) | **SharedKernel** |
+| Wiring (`src/**/composition/**`, `src/**/factories/**`, `bootstrap.ts`) | **CompositionRoot** |
+| `src/**/domain/**` | **DomainModel** |
+| Flattened `src/lib/**` bag | **Not** Application as a whole — classify interiors (use-cases → Application; types → SharedKernel). Adopt never dumps bare `src/lib/**` into Application. |
 
 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).
+globs beat Presentation. Adopt writes `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
+`ark_place` requires `filePath` (fail-closed — never invents `components/*.tsx` or defaults to Presentation).
+ArkRules stay **opt-in** (not forced on by start/adopt).
 
 ### Composition-root / factory modules (optional Application-only)
 

package/docs/configuration.md

@@ -90,6 +90,7 @@ Layer fields:
 
 - `name`, `patterns`, `exclude`, `description`
 - `intentPrefixes`, `forbiddenGlobals`, `mayImportInfrastructure`, `optional`
+- `reserved` / `allowEmpty` — future houses whose globs match nothing yet. `--strict-config` does not fail; `CONFIG_LAYER_PATTERN_NO_MATCHES` (typo warning) is skipped. A typo warning fires only when the glob is not reserved.
 - `capabilities: { deny: [...] }` — opt-in effect walls over the seven capability ids
   (`network`, `filesystem`, `clock`, `randomness`, `environment`, `process`, `persistence`);
   `pure: true` is the shorthand that denies all seven. Absence changes no verdict.
@@ -254,7 +255,7 @@ now shows more authors, it shows the **gap** and asks whether to update. `/ark-a
 writes only after you confirm — it does not invent names or remove entries.
 
 ```json
-"stewards": ["pedroknigge", "Amarilla-David"]
+"stewards": ["you", "your-co-steward"]
 ```
 
 Law files (`ark.config.json`, `arkrules/*`, `.ark-baseline.json`) are a different change

package/docs/develop.md

@@ -75,6 +75,7 @@ can show `runtimeObserved: true` even when branch-protection policy is plan-unav
 | Session / project status snapshot | `ark status --json` · MCP `ark_status` · [session recipe](agent-guide.md#session-recipe-agent-turn) · schema `arkgate/schema/status-manifest` |
 | Status compass honesty | `improvementCompass.mode`: `full` \| `subset` \| `unavailable` · residual ⊆ doctor when `full` · [package-surface](package-surface.md) |
 | Managed upgrade self-service | `ark upgrade --json` → `selfService` (activation labels + customized preserve) · [package-surface](package-surface.md) |
+| Stale MCP/global CLI recovery | `processPackage.processStale` → non-authoritative + `PROCESS_PACKAGE_STALE`; modern outside-tree `ark upgrade` hands off to project-local CLI |
 | Version-matched AGENTS projection | `ark agents-md` · [agent-guide](agent-guide.md) · **non-authoritative** (never enforces) |
 | Stable finding refs (`findingRef` / `targetKey`) | analysis-result schema **1.5** · [agent-guide](agent-guide.md) · [package-surface](package-surface.md) |
 | Agent Skills layout (same 13 names) | `templates/agent-skills/` · [agent-guide](agent-guide.md#install-skills-ark-and-ecosystem) · `npx skills add …` |
@@ -105,10 +106,12 @@ Sensors:
 ```bash
 npx arkgate-check --plan
 npx arkgate-check --coverage
-npx arkgate-check --doctor --json   # improvementCompass (notAScore lenses) + status light
+npx arkgate-check --doctor --json   # stable envelope { schemaVersion, envelope:"doctor", ok, doctor }
 ```
 
-Doctor residual lenses never flip `valid` / strict-merge alone. Product path:
+`--doctor --json` payload lives only under `doctor`. Doctor also writes `.ark/ci-merge-boundary.json`
+(writePath per host, hook configured-not-fired, CI present-but-not-required, GitHub Free cannot
+require). Hook green is not tree green. Doctor residual lenses never flip `valid` / strict-merge alone. Product path:
 [use.md — Improvement compass](use.md#improvement-compass-not-a-score).
 
 Agent reference (tools, skills, dual path): [agent-guide.md](agent-guide.md).

package/docs/diagnostics.md

@@ -56,6 +56,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ATOMIC_PREFLIGHT_UNAVAILABLE`](#ATOMIC_PREFLIGHT_UNAVAILABLE) | preflight | Atomic preflight unavailable |
 | [`DESIGN_SMELL_REGRESSION`](#DESIGN_SMELL_REGRESSION) | preflight | Design smell regression on base-relative ratchet |
 | [`ANALYSIS_PARSE_INCOMPLETE`](#ANALYSIS_PARSE_INCOMPLETE) | analysis | Parse incomplete |
+| [`LEXICAL_EVIDENCE_INCOMPLETE`](#LEXICAL_EVIDENCE_INCOMPLETE) | analysis | Lexical evidence incomplete |
 | [`ANALYSIS_HOST_UNAVAILABLE`](#ANALYSIS_HOST_UNAVAILABLE) | analysis | Analysis host unavailable |
 | [`ADAPTER_NOT_ALLOWED_FOR_PORT`](#ADAPTER_NOT_ALLOWED_FOR_PORT) | adapter | Adapter not allowed for port |
 | [`FORBIDDEN_PATTERN`](#FORBIDDEN_PATTERN) | snippet-policy | Forbidden regex pattern |
@@ -89,7 +90,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 **Layer import not allowed**
 
 - **Why:** A module import (or re-export) crosses a layer edge that ark.config.json does not allow. The architecture contract forbids that dependency direction so outer infrastructure cannot leak into pure or inner layers.
-- **Fix:** Define a port in the source layer, inject the outer-layer implementation, or move/share the type with `import type` when the edge is type-only — then preflight again. Do not weaken the layer rule without a hash-bound policy acknowledgement.
+- **Fix:** Branch by import kind: constants/types/pure → adopt into DomainModel or SharedKernel (do not invent a port); kernel/events/bootstrap from Persistence → inject a port or move the map to SharedTypes (Persistence must not emit); define a port only when the target is a real use-case. Type-only edges use `import type`. Then preflight again. Do not weaken the layer rule without a hash-bound policy acknowledgement.
 
 <a id="LAYER_INTENT_REFERENCE_VIOLATION"></a>
 
@@ -267,8 +268,8 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 
 **Invariant without coverage evidence**
 
-- **Why:** An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial).
-- **Fix:** Add a test title or declared symbol covering the arkruleId, then preflight again. Missing test globs report partial — never fake green.
+- **Why:** An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is `never-had-tests` (adopt residual) vs `tests-disappeared` (suite exists).
+- **Fix:** Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green.
 
 ## Atomic preflight and change sets
 
@@ -379,8 +380,17 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 
 **Parse incomplete**
 
-- **Why:** Governed source could not be fully parsed; analysis is partial and must not paint green.
-- **Fix:** Fix syntax/parse errors in governed files (or restore a usable TypeScript host), then re-run. Partial never means pass.
+- **Why:** Governed source could not be fully parsed; evidence includes the TypeScript diagnostic (line + message). Incremental mid-edit parse is normal for agents. Contract `exclude` paths skip the write hook.
+- **Fix:** Finish the source or fix the reported syntax error, then re-run `npx arkgate-check`. The write hook does not deny solely on mid-edit parse. Partial never means pass.
+
+<a id="LEXICAL_EVIDENCE_INCOMPLETE"></a>
+
+### `LEXICAL_EVIDENCE_INCOMPLETE`
+
+**Lexical evidence incomplete**
+
+- **Why:** Single-file validation cannot prove project module resolution. The write hook is already the verdict.
+- **Fix:** Re-run `npx arkgate-check --root . --config ark.config.json`, or treat the hook deny as final. Do not call `ark_prepare_change` from a hook deny.
 
 <a id="ANALYSIS_HOST_UNAVAILABLE"></a>
 

package/docs/package-surface.md

@@ -21,9 +21,9 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
 | **Improvement compass (4.4; status honesty 4.5)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. **`ark status --json` / MCP `ark_status`** project a thin `improvementCompass` residual map with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`). When `mode` is `full`, status residual lens **ids** are a **subset of** doctor residual for the same facts (report snapshot stores the thin slice after `--report`). Incomplete or missing session facts → `subset` / `unavailable` + `reasonCode` / `reason` — **never invent green residual**. Residual never flips `valid` / strict-merge / `goal.met`. When status mode ≠ full, run doctor for full 15-lens detail. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input. Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`; status: `projectStatusImprovementCompass` / `STATUS_COMPASS_MODES`. |
 | **Deep-module coach (post-4.5 advisory)** | `ark-check --doctor --json` → `doctor.deepModuleCoach`; human doctor section **Deep-module coach (advisory — not a score)** always when doctor runs (empty candidates / hot-path `unavailable` are honesty, not omission); HTML `data-advisory="deepModuleCoach"`. | Additive schema `1.0`. Always **`notAScore: true`**. **`hotPaths`**: recent-churn heuristic from bounded git log; `available` + `status` `ok` \| `unavailable`; empty `paths` when history missing/incomplete — **never invent**. **`deepeningCandidates`**: cards projected only from existing design smells / physical cohesion / reshape pilot / pilotLoop / residual compass lenses — **empty when no evidence** (no fake candidates). Never flips `valid`, strict-merge, completeness green, or `goal.met`. Prefer deep modules / named seams / test-at-public-interface process language in skills. Domain pure + CLI gen mirror (`deepeningCoach.ts` / `bin/lib/deepening-coach.mjs`); **not** a root package export — consume via `doctor.deepModuleCoach` (or the gen mirror in Tooling). |
-| **Upgrade what’s new (4.5.6+)** | `ark upgrade --json` → `whatsNew` (+ human **Suggested improvements** block; also on preview). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty, registry-aware upgrade, skill drift/refresh, multi-project MCP. Never invents residual or flips gates. |
+| **Upgrade what’s new (4.5.6+)** | `ark upgrade --json` → `whatsNew` (+ human **Suggested improvements** block; also on preview). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty, registry-aware upgrade, skill drift/refresh, multi-project MCP, Codex hard-write refresh/trust/restart/verify, stale MCP/global CLI recovery. Never invents residual or flips gates. |
 | **Field upgrade truth (4.5.6)** | `ark upgrade` registry-aware install; JSON `reasonCode` / `suggestedInstallCmd`; `skillDrift`; `--refresh-skills`; `postUpgradeChecks`; `hostSelection`. | No false-skip when registry ahead; offline honesty; customized skills preserved unless opt-in refresh; checks are advisory only. |
-| **MCP process package honesty (4.5.6)** | Every MCP tool context → `processPackage` (`processPackageMismatch` / `processStale`, versions, `nextAction`). | Multi-checkout users: restart MCP after pin bump; prefer project-local CLI until identity matched and versions align. Fail-closed identity (WI01) unchanged. |
+| **MCP process package honesty (4.5.6; fail-closed in 4.6.4)** | Every MCP tool context → `processPackage` (`processPackageMismatch` / `processStale`, versions, `nextAction`). | Multi-checkout users: restart MCP after pin bump. From 4.6.4, stale process context is non-authoritative; `ark_identity` remains diagnostic and project tools return `PROCESS_PACKAGE_STALE` until restart/retarget. Prefer project-local CLI until identity matched and versions align. |
 | **Doctor design fitness** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. `handler-in-persistence` covers static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so **absence of a smell is not full-tree proof** above that envelope (incomplete/`partial` analysis also never proves “no smells”). **4.2 feedback hardening:** mode labels preserve the observed SUGGEST/ADAPT/ENFORCE state; a local permission/UI-state `canEdit` name alone is not a domain smell; real UI business rules route Domain → Application → UI; seed/fixture/demo/migration/generated files are not god-module pilots. Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`**. Does **not** fail the gate by itself. |
 | **Post-green Shape door** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. |
 | **Golden pattern (new code)** | Optional `.ark/golden-pattern.json`; doctor JSON `doctor.goldenPattern`; MCP `ark_place` / `ark_prepare_write` → `goldenPattern` | Additive, **advisory for NEW code only**. Required fields: `name`, `norm`; optional `newCodeHome`, `examplePath`, `schemaVersion`. **Absent is normal** (no claim). Never ENFORCE; never clears design-weak. Malformed → `invalid: true`, not silent guidance. |
@@ -211,9 +211,10 @@ 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.6.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.3.md);
-current published: [4.6.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.2.md);
- prior published: [4.6.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md), [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md), [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md), [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
+(current: [4.6.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.5.md);
+prior published: [4.6.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.4.md);
+prior published: [4.6.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.3.md);
+prior published: [4.6.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.2.md), [4.6.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md), [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md), [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md), [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
 [4.2.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.1.md);
 previous: [4.2.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.0.md),
 [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md),

package/docs/threat-model.md

@@ -32,7 +32,7 @@ infrastructure beyond how this package is published.
 | T3 | CI job missing / not required | Merge green without architecture | doctor `enforcement-ci-*` gaps; `--strict-merge`; required-status remains locally `unverified` |
 | T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | semantic policy-delta guard in strict merge; hash-bound explicit acknowledgement; present-state safety diagnostics |
 | T5 | Baseline ratcheted open | Debt reintroduced | baseline unused/stale signals; occurrence keys |
-| T6 | Dual MCP bin / wrong root | Gate points at wrong tree | migrate-commands; Codex fail-closed temp roots |
+| T6 | Stale MCP/global CLI or wrong root | Gate points at old package / wrong tree | project identity binding; stale process non-authoritative + `PROCESS_PACKAGE_STALE`; project-local upgrade handoff |
 | T7 | Malicious dependency in publish | Compromised gate | signed tags, npm provenance, dependency-review, CodeQL, Semgrep, `verify-package-files` |
 | T8 | Path traversal in hooks/check | Read/write outside project | root resolution + under-root import resolve |
 | T9 | Runtime InMemory mistaken for durable | Data loss | durability stance docs + safety InMemory production detector |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.6.3",
+  "version": "4.6.5",
   "description": "One architecture config. One check. One coach.",
   "type": "module",
   "main": "./dist/index.cjs",

package/schemas/ark.config.schema.json

@@ -723,6 +723,12 @@
         },
         "optional": {
           "type": "boolean"
+        },
+        "reserved": {
+          "type": "boolean"
+        },
+        "allowEmpty": {
+          "type": "boolean"
         }
       }
     },

package/server.json

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

package/templates/agent-skills/README.md

@@ -7,7 +7,7 @@
 This directory is the **Agent Skills–compatible** packaging of the same **13**
 `/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
 
-Package version when last generated context: **arkgate@4.6.2**
+Package version when last generated context: **arkgate@4.6.5**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -14,6 +14,13 @@ description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield
 2. Write `ark.config.json` (and a baseline only for genuine debt) in this turn.
 3. Re-run doctor. Day-to-day new files: `/ark-place`.
 
+## Checklist
+
+- Existing tree: propose **SharedKernel** (types/constants) + **CompositionRoot** (wiring) + `src/**/domain/**`. Never dump bare `src/lib/**` into Application.
+- Generate `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
+- Future houses: mark unused layer globs `reserved` / `allowEmpty` so `--strict-config` does not fail.
+- CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
+
 Invoking this skill **is** the approval. Write the architecture config in this turn.
 Greenfield: scaffold like `--recommend`. Brownfield: match **product
 reality**, freeze only genuine debt. A green check over a wrong config is a **false green**.

package/templates/agent-skills/ark-explore/SKILL.md

@@ -14,6 +14,12 @@ description: Map skill — decision-grade recon of layers + ArkRules opportuniti
 2. Open the real tree (≥12 files across ≥4 dirs). CLI JSON alone is incomplete.
 3. Rank leftover work. Hand off to `/ark-autopilot` to apply one refactor. Do not write config or product code here.
 
+## Checklist
+
+- Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
+- Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
+- Hook green is not tree green (scripted edits bypass PreToolUse).
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval to **map**. Open the real tree. CLI JSON alone is

package/templates/agent-skills/ark-place/SKILL.md

@@ -10,16 +10,23 @@ description: "Where does new code go? Names the layer, directory, and naming for
 
 ## Steps
 
-1. Bind identity if using MCP (`ark_identity` with the exact project root).
-2. Place the file (`ark_place` or read `ark.config.json`).
+1. CLI-first: if the local CLI already resolved the root, skip waiting on MCP. Identity is optional then.
+2. Place with **filePath required** (`ark_place` or read `ark.config.json` + `.ark/golden-pattern.json`). Fail-closed without a path — never invent `components/*.tsx` or default to Presentation.
 3. Write it there. Then `arkgate-check`.
 
+## Checklist
+
+- `filePath` is known before the call. Description alone is not a path.
+- Golden pattern is load-bearing when present. Adopt generates it.
+- Do not default a repository to Presentation.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval. If the user described an artifact, **write the
 files** in this turn (prepare-write + scaffold). A path table alone is incomplete.
-The CLI is a **sensor and gate**. **CLI budget:** `ark_identity` then `ark_place` (or
-read `ark.config.json`); write; `ark-check`. Do not ask which layer they prefer.
+The CLI is a **sensor and gate**. **CLI budget:** `ark_identity` then `ark_place` when using MCP
+(or skip identity if the CLI already resolved the root); otherwise read `ark.config.json`; write;
+`ark-check`. Do not ask which layer they prefer.
 
 **Still never:** weaken `ark.config.json`; invent `mechanical-safe` kinds; claim leftover
 design work is finished because one file landed.

package/templates/agent-skills/ark-upgrade/SKILL.md

@@ -10,10 +10,17 @@ description: Upgrade ArkGate through a content-identity preview, preserve custom
 
 ## Steps
 
-1. Preview: `arkgate upgrade` (no writes).
-2. Apply in this turn: `arkgate upgrade --apply` (needs `--plan-digest` when applying managed files).
+1. Preview: `arkgate upgrade` (no writes). Default is **hosts keep** — do not retire other hosts’ skills.
+2. Apply in this turn: `arkgate upgrade --apply` (installs the bumped package unless `--no-install`). Needs `--plan-digest` when applying managed files.
 3. Re-run `arkgate-check --doctor`. Customized files stay unless you pass `--accept-conflicts` / `--refresh-skills`.
 
+## Checklist
+
+- Preview unions `--tools` with hosts already in the repo. Multi-agent trees keep every host.
+- Apply must run the package install of the new pin. Do not skip `npm install` unless `--no-install` is explicit.
+- Refresh AGENTS.md **and** CLAUDE.md (same projection schema).
+- Prefer project `.agents/skills`. Do not duplicate the catalog into `~/.codex/skills`.
+
 The preview is the source of truth. Do not treat a filename or package version as proof of ownership.
 
 ## Autonomy contract
@@ -58,6 +65,15 @@ line (advisory only — not a score):
 6. **Registry-aware upgrade** — `reasonCode` / `suggestedInstallCmd` when package install is skipped or needed
 7. **Skill drift + refresh** — `skillDrift`; opt-in `--refresh-skills` for customized skill rewrite
 8. **Multi-project MCP** — `processPackage` mismatch/stale on every MCP tool; restart after package bump
+9. **Codex hard write refresh** — run
+   `npx arkgate-check --install-agent-gates --tools codex --force`, restart Codex/local Desktop,
+   review and trust the exact hook, then inspect `doctor.writePath` after a governed
+   `apply_patch`. Only a complete runtime-observed local patch is hard; every other path still
+   relies on required CI.
+10. **Stale process recovery** — a stale Ark MCP is non-authoritative and project tools return
+    `PROCESS_PACKAGE_STALE` until restart/retarget. If a modern global `ark upgrade` is older than
+    the project install, it hands the same invocation to the project-local CLI instead of managing
+    the project from the stale PATH binary.
 
 Never invent gate verdicts from these suggestions. Missing residual is honest empty, not green.
 
@@ -95,8 +111,10 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
 
 **Process package honesty:** every tool response includes `processPackage` (`processArkgateVersion`,
 `projectInstalledVersion`, `processPackageMismatch` / `processStale`, `nextAction`). After
-`npm install arkgate@…`, **restart/retarget MCP** so process version matches install. Until then,
-prefer project-local CLI and do not treat MCP analysis as fully current.
+`npm install arkgate@…`, **restart/retarget MCP** so process version matches install. From 4.6.4,
+a stale MCP is non-authoritative: `ark_identity` diagnoses it and project tools return
+`PROCESS_PACKAGE_STALE` until restart. Prefer project-local CLI meanwhile. A modern stale global
+`ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry.
 
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 

package/templates/skills/ark-adopt.md

@@ -14,6 +14,13 @@ description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield
 2. Write `ark.config.json` (and a baseline only for genuine debt) in this turn.
 3. Re-run doctor. Day-to-day new files: `/ark-place`.
 
+## Checklist
+
+- Existing tree: propose **SharedKernel** (types/constants) + **CompositionRoot** (wiring) + `src/**/domain/**`. Never dump bare `src/lib/**` into Application.
+- Generate `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
+- Future houses: mark unused layer globs `reserved` / `allowEmpty` so `--strict-config` does not fail.
+- CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
+
 Invoking this skill **is** the approval. Write the architecture config in this turn.
 Greenfield: scaffold like `--recommend`. Brownfield: match **product
 reality**, freeze only genuine debt. A green check over a wrong config is a **false green**.

package/templates/skills/ark-explore.md

@@ -14,6 +14,12 @@ description: Map skill — decision-grade recon of layers + ArkRules opportuniti
 2. Open the real tree (≥12 files across ≥4 dirs). CLI JSON alone is incomplete.
 3. Rank leftover work. Hand off to `/ark-autopilot` to apply one refactor. Do not write config or product code here.
 
+## Checklist
+
+- Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
+- Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
+- Hook green is not tree green (scripted edits bypass PreToolUse).
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval to **map**. Open the real tree. CLI JSON alone is

package/templates/skills/ark-place.md

@@ -10,16 +10,23 @@ description: "Where does new code go? Names the layer, directory, and naming for
 
 ## Steps
 
-1. Bind identity if using MCP (`ark_identity` with the exact project root).
-2. Place the file (`ark_place` or read `ark.config.json`).
+1. CLI-first: if the local CLI already resolved the root, skip waiting on MCP. Identity is optional then.
+2. Place with **filePath required** (`ark_place` or read `ark.config.json` + `.ark/golden-pattern.json`). Fail-closed without a path — never invent `components/*.tsx` or default to Presentation.
 3. Write it there. Then `arkgate-check`.
 
+## Checklist
+
+- `filePath` is known before the call. Description alone is not a path.
+- Golden pattern is load-bearing when present. Adopt generates it.
+- Do not default a repository to Presentation.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval. If the user described an artifact, **write the
 files** in this turn (prepare-write + scaffold). A path table alone is incomplete.
-The CLI is a **sensor and gate**. **CLI budget:** `ark_identity` then `ark_place` (or
-read `ark.config.json`); write; `ark-check`. Do not ask which layer they prefer.
+The CLI is a **sensor and gate**. **CLI budget:** `ark_identity` then `ark_place` when using MCP
+(or skip identity if the CLI already resolved the root); otherwise read `ark.config.json`; write;
+`ark-check`. Do not ask which layer they prefer.
 
 **Still never:** weaken `ark.config.json`; invent `mechanical-safe` kinds; claim leftover
 design work is finished because one file landed.

package/templates/skills/ark-upgrade.md

@@ -10,10 +10,17 @@ description: Upgrade ArkGate through a content-identity preview, preserve custom
 
 ## Steps
 
-1. Preview: `arkgate upgrade` (no writes).
-2. Apply in this turn: `arkgate upgrade --apply` (needs `--plan-digest` when applying managed files).
+1. Preview: `arkgate upgrade` (no writes). Default is **hosts keep** — do not retire other hosts’ skills.
+2. Apply in this turn: `arkgate upgrade --apply` (installs the bumped package unless `--no-install`). Needs `--plan-digest` when applying managed files.
 3. Re-run `arkgate-check --doctor`. Customized files stay unless you pass `--accept-conflicts` / `--refresh-skills`.
 
+## Checklist
+
+- Preview unions `--tools` with hosts already in the repo. Multi-agent trees keep every host.
+- Apply must run the package install of the new pin. Do not skip `npm install` unless `--no-install` is explicit.
+- Refresh AGENTS.md **and** CLAUDE.md (same projection schema).
+- Prefer project `.agents/skills`. Do not duplicate the catalog into `~/.codex/skills`.
+
 The preview is the source of truth. Do not treat a filename or package version as proof of ownership.
 
 ## Autonomy contract
@@ -58,6 +65,15 @@ line (advisory only — not a score):
 6. **Registry-aware upgrade** — `reasonCode` / `suggestedInstallCmd` when package install is skipped or needed
 7. **Skill drift + refresh** — `skillDrift`; opt-in `--refresh-skills` for customized skill rewrite
 8. **Multi-project MCP** — `processPackage` mismatch/stale on every MCP tool; restart after package bump
+9. **Codex hard write refresh** — run
+   `npx arkgate-check --install-agent-gates --tools codex --force`, restart Codex/local Desktop,
+   review and trust the exact hook, then inspect `doctor.writePath` after a governed
+   `apply_patch`. Only a complete runtime-observed local patch is hard; every other path still
+   relies on required CI.
+10. **Stale process recovery** — a stale Ark MCP is non-authoritative and project tools return
+    `PROCESS_PACKAGE_STALE` until restart/retarget. If a modern global `ark upgrade` is older than
+    the project install, it hands the same invocation to the project-local CLI instead of managing
+    the project from the stale PATH binary.
 
 Never invent gate verdicts from these suggestions. Missing residual is honest empty, not green.
 
@@ -95,8 +111,10 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
 
 **Process package honesty:** every tool response includes `processPackage` (`processArkgateVersion`,
 `projectInstalledVersion`, `processPackageMismatch` / `processStale`, `nextAction`). After
-`npm install arkgate@…`, **restart/retarget MCP** so process version matches install. Until then,
-prefer project-local CLI and do not treat MCP analysis as fully current.
+`npm install arkgate@…`, **restart/retarget MCP** so process version matches install. From 4.6.4,
+a stale MCP is non-authoritative: `ark_identity` diagnoses it and project tools return
+`PROCESS_PACKAGE_STALE` until restart. Prefer project-local CLI meanwhile. A modern stale global
+`ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry.
 
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)