arkgate 4.6.4 → 4.6.5

package/docs/README.md

@@ -58,8 +58,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) |
 
-Current published: [releases/4.6.3.md](releases/4.6.3.md) (`arkgate@4.6.3` on npm `latest`).
-Prepared: [releases/4.6.4.md](releases/4.6.4.md) (Codex upgrade activation guidance; not yet published).
+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`).  

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)

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

@@ -106,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

@@ -211,8 +211,9 @@ 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.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.4.md);
-current published: [4.6.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.3.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),

package/package.json

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

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