arkgate 4.6.4 → 4.6.6

package/docs/README.md

@@ -40,7 +40,7 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 | Doc | What it is |
 |-----|------------|
 | [CONTRIBUTING.md](../CONTRIBUTING.md) | Setup, rules, PR/release |
-| [ROADMAP.md](../ROADMAP.md) | Implementation queue (one `doing` at a time) |
+| [ROADMAP.md](../ROADMAP.md) | Live implementation queue (one `doing` at a time). History: [archive/roadmap-history.md](archive/roadmap-history.md) |
 | [adr/](adr/README.md) | Architecture decisions |
 | [SECURITY.md](../SECURITY.md) · [threat-model.md](threat-model.md) | Security |
 
@@ -52,18 +52,15 @@ 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/) — maintainer seeds (e.g. [team-parliament](plans/team-parliament/README.md) **shipped in 4.6.1**; [five-door-autonomy](plans/five-door-autonomy/README.md) **shipped in 4.6.1**; [understandable-ark-4.6](plans/understandable-ark-4.6/README.md) **4.6.0**; [field-upgrade-mcp-truth](plans/field-upgrade-mcp-truth/README.md) **shipped in 4.5.6**; deep-module coach **shipped in 4.5.5**; domain fitness & session truth for **4.5.0**; improvement compass for **4.4.0**; agent contract surface for **4.3.0**). Product how-to stays in use/develop/agent-guide; plans are not required reading to use the package. |
+| Release notes (by version) | [releases/](releases/) · npm [CHANGELOG.md](../CHANGELOG.md) (Unreleased + 4.6.x) · [pre-4.6 archive](archive/CHANGELOG-pre-4.6.md) |
+| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done on `main`; `AL05` parked). |
 | 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 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).
-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).
+Current: [releases/4.6.6.md](releases/4.6.6.md) (`arkgate@4.6.6`).
+Prior: [releases/4.6.5.md](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
+Older notes: [releases/](releases/). Config: [configuration.md](configuration.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)

package/docs/ai-gates.md

@@ -81,7 +81,10 @@ bypassable/advisory because some Code Mode paths do not dispatch the project hoo
 **Design fitness (3.0.1+):** the same doctor JSON may include `doctor.designFitness` and
 `doctor.designSmells[]` (path evidence). Edge-clean `operatingMode: enforce` can still set
 `designFitness.designWeak: true` (**ENFORCE · design-weak**). That global inventory remains Shape
-residual, not a write-path failure. Separately, Z10's opt-in design delta blocks only new/worsened
+residual, not a write-path failure. Required `arkgate-check --strict-merge` also evaluates
+created-path `domain-logic-in-ui` when a merge base exists (Action inherits via `--strict` and
+`ARK_POLICY_BASE_REF`; missing base skips, does not exit 2). Leftover design on existing files
+stays Shape residual. Z10's opt-in `--fail-on-new-smells --base-ref` still blocks new/worsened
 supported smells on touched paths. Companion plan JSON: `plan.patternBets[]` with `neverMechanicalSafe: true`
 — never treat as write-boundary `autoPatch` / mechanical-safe. See
 [package-surface.md](package-surface.md) and [brownfield-adoption.md](brownfield-adoption.md) §6.
@@ -739,10 +742,14 @@ Whatever the agent side does, run the merge profile in CI:
     fi
 ```
 
-This explicit brownfield ratchet records schema `1.0` identities, touched paths, and stable
-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.
+The required status command is `arkgate-check --strict-merge` (alias `--strict`): import edges
+plus created-path `domain-logic-in-ui` when a Git base exists. The composite Action already runs
+`--strict` and exports `ARK_POLICY_BASE_REF`; it needs no extra flags. Generated CI still adds
+`--fail-on-new-smells --base-ref` when the SHA is resolvable (stricter than created-path).
+Missing base with `--fail-on-new-smells` exits `2`, so the generated workflow skips the full
+ratchet on first-push all-zero / unresolvable SHA while keeping `--strict-merge` (created-path
+also skips when the base is missing). Residual, path-only moves, unrelated work, and worsened
+rules in existing files stay green on the merge command.
 Generated Claude/Grok hooks share the delta and golden-pattern repair hint. MCP exposes the result
 but stays advisory.
 

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.
@@ -247,6 +248,14 @@ Optional `stewards` lists **GitHub handles or emails** who may **loosen** the co
 matches `--author`, then `GITHUB_ACTOR` / `ARK_STEWARD`, then `GIT_AUTHOR_EMAIL`. A
 noreply GitHub mail and the handle are the same person. Git `user.name` is not identity.
 
+`--contract-session` is required to loosen the contract (T4) or grow the baseline
+(`--update-baseline`, T5) **even when `stewards` is empty**. `--policy-ack` remains the
+hash tooth on a weakening; session is the change-type tooth. An empty list cannot print
+Healthy ENFORCE: doctor treats it as unfinished residual (`empty-stewards`) after a
+30-day grace from the git first-add of `ark.config.json`, or immediately when that age
+is unknown. `operatingMode` stays `enforce` (contract-fit). `/ark-adopt` asks; it does
+not invent names.
+
 Doctor detects several recent authors or a CODEOWNERS file (`doctor.stewardNudge`).
 When `stewards` is empty it **asks** who owns the law and proposes handles or emails.
 When the list exists but CODEOWNERS is ahead, or you started with one steward and git
@@ -254,7 +263,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
@@ -265,7 +274,7 @@ type than product source:
 | `ark-check --changed --base origin/dev` | Layer check on touched sources only. A CSS/i18n PR pays almost nothing. |
 | `ark-check --against origin/dev` | New violation keys vs **that ref's** baseline (not only HEAD). |
 | `ark-check --contract-diff --base origin/dev` | Classifies tighten / loosen / reclassify / baseline-grow. |
-| `--contract-session --author <id>` | Law-only PR. Mixed law+product still fails. Loosen/grow need a listed steward. |
+| `--contract-session --author <id>` | Law-only PR. Mixed law+product still fails. Loosen/grow need a session even with an empty `stewards[]`; a non-empty list also needs a matching listed author. |
 | `--persona touch\|contributor\|agent\|steward` | Budget presets for the same teeth. |
 | `ark status --vs origin/dev` | One line: pin / contract / baseline drift vs that ref. |
 

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
 
@@ -368,8 +369,8 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 
 **Design smell regression on base-relative ratchet**
 
-- **Why:** Compared to the base ref, the candidate introduces or worsens a blocking design-smell class (e.g. domain-logic-in-ui) under --fail-on-new-smells.
-- **Fix:** Revert the regression or redesign so the smell does not worsen versus base, then re-run with the same base ref.
+- **Why:** Compared to the base ref, the candidate introduces a created-path `domain-logic-in-ui` file under `--strict-merge`, or introduces or worsens a blocking design-smell class under `--fail-on-new-smells`.
+- **Fix:** Move the new UI business rule out of the created file (or revert a `--fail-on-new-smells` regression), then re-run with the same base ref.
 
 ## Analysis host and completeness
 
@@ -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

@@ -54,7 +54,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Structural convergence (3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
 | **Enforcement ladder + fixed journey (3.1.0)** | `doctor.writePath.enforcementLadder`; hook repair `enforcement`; `npm run eval:change-integrity` | Additive schema `1.0` separates supported/installed/active/bypassable state and evidence. Hard is operation-scoped only for a supported covered hook; MCP is advisory; required CI status stays unverified locally. Fixed no-context fixture proves CLI/MCP/hook/final parity, one casual denial, acceptance behavior, and strict Ark. |
 | **Enforcement state** | `doctor.writePath.enforcementState`; schema/type | Schema `1.1`: runtime observation, operation coverage, and operation-scoped `hard`. Only fresh covered active-host evidence permits `hard:true`; unverified assets and MCP remain non-hard. |
-| **Design delta (opt-in ratchet)** | `--fail-on-new-smells --base-ref <ref>`; hook/MCP; schema/types | Schema `1.0`: identities, touched paths, stable evidence/verdict. Missing base fails closed; only new/worsened `domain-logic-in-ui` blocks; global doctor smells stay advisory. |
+| **Design delta** | `--strict-merge` / `--strict` (created paths when a Git base exists); `--fail-on-new-smells --base-ref <ref>` (full ratchet); hook/MCP; schema/types | Schema `1.0`: identities, touched paths, optional `enforcementScope`. Default merge blocks **created** `domain-logic-in-ui` files vs merge-base; missing base skips (does not exit 2). Full new+worsened on touched paths remains opt-in `--fail-on-new-smells` (missing base fails closed). Historical residual and worsened-in-existing-file stay green on `--strict-merge`. Global doctor smells stay advisory. |
 | **`arkgate/schema/analysis-result`** or **`arkgate/schema/ark.analysis-result.schema.json`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `mode`, `valid`, `completeness`, `completenessReasons`, `diagnostics`, resolved identities) | Schema **`1.5`** adds optional stable finding refs on diagnostics: `findingRef` (`fnv1a-` + hex), `targetKey` (baseline-compatible freeze identity), `docsCodePath` (`docs/diagnostics.md#RULE_ID`). Factory-emitted diagnostics always include them; consumer-owned 1.0–1.4 values remain valid without them. `1.4` added optional `evidence.arkruleId` / `evidence.arkruleSource` for ArkRules; `1.3` distinguished `resolved-candidate-facts` from `lexical-compatibility`; partial/unavailable analysis is always non-green, and resolved complete/partial results require policy/resolver/facts/tree identities. `1.2` added completeness and remains accepted alongside consumer-owned 1.0/1.1 values. |
 | **Stable finding refs (4.3)** | Root API `adapterFindingTargetKey` / `adapterFindingRefFromTargetKey` / `toAdapterDiagnostic` / `createAdapterResult`; CLI/MCP/repair envelopes via analysis-result diagnostics | Multi-turn re-address without fuzzy message match. `targetKey` **is** the baseline (occurrence) key so freeze identity is never orphaned; `findingRef` is a compact FNV-1a of that key. Line/message drift does not change the ref. Multi-turn fixture: `tests/fixtures/finding-refs/multi-turn-stability.json`. |
 | **Diagnostic code catalog** | Root API `DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`; docs [diagnostics.md](diagnostics.md) (`#RULE_ID` anchors) | Closed vocabulary of public `ruleId`s with why/fix anchors. Cataloguing only — no new rule semantics. Remediation parity is test-guarded. Docs ship in the npm tarball. |
@@ -143,7 +143,8 @@ The type-only root exports are also semver-supported:
 - Policy delta: `PolicyDelta`, `PolicyDeltaAcknowledgement`, `PolicyDeltaClassification`,
   `PolicyDeltaFinding`.
 - Design delta: `ArkDesignDeltaResult`, `ArkDesignDeltaIdentity`, `ArkDesignDeltaChange`,
-  `ArkDesignDeltaEvidence`, `ArkDesignSmellId`, `ArkDesignDeltaVerdict`.
+  `ArkDesignDeltaEvidence`, `ArkDesignSmellId`, `ArkDesignDeltaVerdict`,
+  `DesignDeltaEnforcementScope`.
 - Analysis IR: `AnalysisFileInput`, `AnalysisFileChange`, `AnalysisCompilerOptions`,
   `AnalysisFile`, `AnalysisImportEdge`, `AnalysisCapabilityUse`, `AnalysisEvidence`,
   `AnalysisViolation`, `AnalysisIr`.
@@ -211,8 +212,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.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.6.md);
+prior published: [4.6.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.5.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/docs/product-voice.md

@@ -94,8 +94,8 @@ stay stable unless a change explicitly adds an alias.
 | **five doors** | skill menu of 13 | adopt · place · autopilot · explore · upgrade — other names are shortcuts |
 | **law / constitution** | contract + baseline + ArkRules files | `ark.config.json`, `arkrules/*`, `.ark-baseline.json` — a different change type than product |
 | **steward** | contract owner | GitHub handle or email in `stewards`; only they may loosen the law or grow the baseline |
-| **several hands** | multi-author / CODEOWNERS | Doctor asks for stewards or shows list drift; adopt proposes handles or emails, never invents names |
-| **contract session** | `--contract-session` | Explicit “this diff is a law change”; still never mixed with product files |
+| **several hands** | multi-author / CODEOWNERS | Doctor asks for stewards or shows list drift; empty `stewards[]` is unfinished ENFORCE (not Adapt); adopt proposes handles or emails, never invents names |
+| **contract session** | `--contract-session` | Explicit “this diff is a law change”; required to loosen or grow the baseline even with an empty steward list; still never mixed with product files |
 | **vs the base branch** | `--against` / `--changed --base` / `status --vs` | Ratchet and honesty against the ref you merge to |
 | **doctor** | doctor | Status light + next action |
 | **short agent router** | compact router | Default onboarding agent instructions (not the full skill pack) |
@@ -308,8 +308,10 @@ This change mixes the constitution with product files. Next: split the PR, or ru
 
 ### Healthy finished
 
-Print “Healthy — nothing to do” **only** when there is no leftover design work and no open top actions.
-Otherwise name the leftover work.
+Print “Healthy — nothing to do” **only** when the merge boundary is adopted as a **required**
+GitHub status running `arkgate-check --strict-merge`, there is no leftover design work, and no
+open top actions. An explicit `.ark/adoption-stance.json` `stance: "advisory-only"` ack is
+adopted for honesty, but it is not this Healthy string. Workflow files on disk are not adopted.
 
 ---
 

package/docs/threat-model.md

@@ -30,8 +30,8 @@ infrastructure beyond how this package is published.
 | T1 | Agent bypasses hook (direct `fs` / alternate tool) | Ungoverned code lands | CI gate; optional pre-commit (Q3); doctor ladder never upgrades installed files to active/hard proof |
 | T2 | Human commits without agent path | Same as T1 | `templates/hooks/pre-commit-ark`; branch protection + required check (Q3 external) |
 | 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 |
+| T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | semantic policy-delta guard in strict merge; hash-bound `--policy-ack`; `--contract-session` required even when `stewards[]` is empty; present-state safety diagnostics |
+| T5 | Baseline ratcheted open | Debt reintroduced | `--update-baseline` requires `--contract-session` even with an empty steward list (`--force` is concentration, not parliament); unused/stale signals; occurrence keys |
 | 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 |

package/docs/use.md

@@ -13,9 +13,10 @@ npm install -D arkgate typescript
 npx arkgate start                 # preview what will change
 npx arkgate start --apply         # install compact contract + host router + CI plan
 npx arkgate-check --doctor        # where am I? one status light, one next action
+npx arkgate-check --doctor --all  # encyclopedia (Details)
 ```
 
-Then keep working with your agent. The doctor is the **control plane**: when stuck, run doctor and do action **#1**.
+Then keep working with your agent. The doctor is the **control plane**: when stuck, run doctor and do action **#1**. Compact first; `--all` for Details.
 
 | Stuck on… | Do this |
 |-----------|---------|
@@ -46,7 +47,7 @@ In those cases a boundary linter or editor rules may be enough; see [README —
 | When | What happens |
 |------|----------------|
 | While the AI writes | Host write gate or advisory MCP (depends on host) |
-| Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) |
+| Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`). Until that status is required — or you write `.ark/adoption-stance.json` with `stance: "advisory-only"` — doctor will not call the tree adopted. |
 | Anytime | Doctor: Suggest / Adapt / Enforce (+ leftover design work if the design is still messy) |
 
 **Cursor:** pre-write block for Write/StrReplace when `.cursor/hooks.json` is trusted.
@@ -87,8 +88,8 @@ list: [configuration.md](configuration.md).
 |-------|--------|-----------|
 | **Suggest** | New or thin project | Finish `start`, re-run doctor |
 | **Adapt** | Not fully protected yet | Doctor action #1 until clean |
-| **Enforce** | Edges honest under the contract | Keep write path + CI |
-| **Enforce · leftover design work** | Edges clean; design still messy | Shape door — not “done” |
+| **Enforce** | Import edges honest, and no new UI business-rule files vs merge-base | Keep write path + CI |
+| **Enforce · leftover design work** | Edges clean; leftover design on existing files is still messy | Shape door — not “done” |
 
 **Green edges ≠ elegant design.** Empty remediation plan is not “architecture finished” if design residual remains.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.6.4",
+  "version": "4.6.6",
   "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/schemas/ark.design-delta.schema.json

@@ -1 +1 @@
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://unpkg.com/arkgate@3/schemas/ark.design-delta.schema.json","title":"ArkGate design delta","type":"object","additionalProperties":false,"required":["schemaVersion","mode","complete","valid","base","candidate","supportedSmellIds","touchedPaths","changes","baseFindingCount","candidateFindingCount","historicalResidualCount"],"properties":{"schemaVersion":{"const":"1.0"},"mode":{"enum":["git-base","write-candidate"]},"complete":{"type":"boolean"},"valid":{"type":"boolean"},"base":{"$ref":"#/$defs/identity"},"candidate":{"$ref":"#/$defs/identity"},"supportedSmellIds":{"type":"array","items":{"const":"domain-logic-in-ui"},"minItems":1,"uniqueItems":true},"touchedPaths":{"type":"array","items":{"type":"string","minLength":1},"uniqueItems":true},"changes":{"type":"array","items":{"$ref":"#/$defs/change"}},"baseFindingCount":{"type":"integer","minimum":0},"candidateFindingCount":{"type":"integer","minimum":0},"historicalResidualCount":{"type":"integer","minimum":0},"error":{"type":"string","minLength":1}},"$defs":{"identity":{"type":"object","additionalProperties":false,"required":["kind","value"],"properties":{"kind":{"enum":["git-tree","candidate-tree"]},"value":{"type":"string","minLength":1},"commit":{"type":"string","minLength":1}}},"evidence":{"type":"object","additionalProperties":false,"required":["kind","path","magnitude"],"properties":{"kind":{"type":"string","minLength":1},"path":{"type":"string","minLength":1},"line":{"type":"integer","minimum":1},"symbol":{"type":"string","minLength":1},"detail":{"type":"string","minLength":1},"magnitude":{"type":"number","minimum":0}}},"finding":{"type":"object","required":["smellId","fingerprint","identity","evidence","repairHint"],"properties":{"smellId":{"enum":["io-under-application","handler-in-persistence","god-module","domain-logic-in-ui","facade-sql-in-routes","mixed-pattern-cluster","soft-contract"]},"fingerprint":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"identity":{"type":"string","minLength":1},"evidence":{"$ref":"#/$defs/evidence"},"repairHint":{"type":"string","minLength":1}}},"change":{"type":"object","unevaluatedProperties":false,"allOf":[{"$ref":"#/$defs/finding"},{"type":"object","required":["classification","baseMagnitude","candidateMagnitude"],"properties":{"classification":{"enum":["new","worsened"]},"baseMagnitude":{"type":"number","minimum":0},"candidateMagnitude":{"type":"number","minimum":0}}}]}}}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://unpkg.com/arkgate@3/schemas/ark.design-delta.schema.json","title":"ArkGate design delta","type":"object","additionalProperties":false,"required":["schemaVersion","mode","complete","valid","base","candidate","supportedSmellIds","touchedPaths","changes","baseFindingCount","candidateFindingCount","historicalResidualCount"],"properties":{"schemaVersion":{"const":"1.0"},"mode":{"enum":["git-base","write-candidate"]},"complete":{"type":"boolean"},"valid":{"type":"boolean"},"base":{"$ref":"#/$defs/identity"},"candidate":{"$ref":"#/$defs/identity"},"supportedSmellIds":{"type":"array","items":{"const":"domain-logic-in-ui"},"minItems":1,"uniqueItems":true},"touchedPaths":{"type":"array","items":{"type":"string","minLength":1},"uniqueItems":true},"changes":{"type":"array","items":{"$ref":"#/$defs/change"}},"baseFindingCount":{"type":"integer","minimum":0},"candidateFindingCount":{"type":"integer","minimum":0},"historicalResidualCount":{"type":"integer","minimum":0},"enforcementScope":{"enum":["created-paths","touched-new-or-worsened"]},"error":{"type":"string","minLength":1}},"$defs":{"identity":{"type":"object","additionalProperties":false,"required":["kind","value"],"properties":{"kind":{"enum":["git-tree","candidate-tree"]},"value":{"type":"string","minLength":1},"commit":{"type":"string","minLength":1}}},"evidence":{"type":"object","additionalProperties":false,"required":["kind","path","magnitude"],"properties":{"kind":{"type":"string","minLength":1},"path":{"type":"string","minLength":1},"line":{"type":"integer","minimum":1},"symbol":{"type":"string","minLength":1},"detail":{"type":"string","minLength":1},"magnitude":{"type":"number","minimum":0}}},"finding":{"type":"object","required":["smellId","fingerprint","identity","evidence","repairHint"],"properties":{"smellId":{"enum":["io-under-application","handler-in-persistence","god-module","domain-logic-in-ui","facade-sql-in-routes","mixed-pattern-cluster","soft-contract"]},"fingerprint":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"identity":{"type":"string","minLength":1},"evidence":{"$ref":"#/$defs/evidence"},"repairHint":{"type":"string","minLength":1}}},"change":{"type":"object","unevaluatedProperties":false,"allOf":[{"$ref":"#/$defs/finding"},{"type":"object","required":["classification","baseMagnitude","candidateMagnitude"],"properties":{"classification":{"enum":["new","worsened"]},"baseMagnitude":{"type":"number","minimum":0},"candidateMagnitude":{"type":"number","minimum":0}}}]}}}

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.6.4",
+  "version": "4.6.6",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.6.4",
+      "version": "4.6.6",
       "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.6**
 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