arkgate 4.5.0 → 4.5.6

package/docs/README.md

@@ -53,15 +53,14 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · [CHANGELOG.md](../CHANGELOG.md) |
-| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. domain fitness & session truth for **4.5.0** with honesty modes / mandatory domain split / self-service residual, 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. |
+| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. [field-upgrade-mcp-truth](plans/field-upgrade-mcp-truth/README.md) **in progress → 4.5.6 prepared**; 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. |
 | 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.4.0.md](releases/4.4.0.md) (`arkgate@4.4.0` on npm `latest`).  
-Next prepare: [releases/4.5.0.md](releases/4.5.0.md) (Status: prepared — not on npm until publish verify).  
-Prior: [releases/4.3.0.md](releases/4.3.0.md) (`arkgate@4.3.0`).  
-Previous: [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 published: [releases/4.5.5.md](releases/4.5.5.md) (`arkgate@4.5.5` on npm `latest`).  
+Prior: [releases/4.4.0.md](releases/4.4.0.md) (`arkgate@4.4.0`).  
+Previous: [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

@@ -83,6 +83,42 @@ npx ark-check --doctor --json
 
 Product path: [use.md — Session recipe](use.md#session-recipe-agent-turn).
 
+### Multi-project MCP and upgrade honesty (4.5.6)
+
+One human often has **N checkouts** and **N package pins**. Product rules:
+
+| Rule | Why |
+|------|-----|
+| 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 |
+| 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 |
+
+```bash
+npx arkgate upgrade --json          # skillDrift, whatsNew, hostSelection
+npx arkgate upgrade --apply         # registry-aware package step, then re-preview
+# digest-bound apply + optional skill refresh:
+npx arkgate upgrade --apply --no-install --plan-digest sha256:… --refresh-skills
+```
+
+### Two-axis done recipe
+
+Architecture residual and feature residual are **separate axes**. Never collapse them:
+
+| Axis | Where truth lives | Done means |
+|------|-------------------|------------|
+| **1. Architecture residual** | `ark status` / `ark-check --doctor` / improvement compass (scan) | Edges honest under the contract; residual lenses / design-weak addressed or deliberately deferred |
+| **2. Feature / ticket residual** | User brief, PR, tracker (process **outside** the package) | Requested behavior matches acceptance; product QA |
+
+**Enforce green ≠ feature done.** Green edges (or quiet residual lenses) only clear axis 1.
+Axis 2 is never a package LLM verdict or second scoreboard — agents and humans judge the ticket.
+
+Optional Completion bullet for skills: **Done axes** — architecture residual | feature residual.
+Compact router restates the same rule for day-zero installs.
+
 ### Improvement compass (doctor + status)
 
 `ark-check --doctor` (human + `--json`) projects residual architecture work as a closed set of

package/docs/brownfield-adoption.md

@@ -9,6 +9,18 @@ The rule underneath all of it: **`ark.config.json` is authoritative.** A green c
 governs 40% of the tree, or a baseline full of false positives, is worse than no gate — it
 looks safe. Report the truth, then fix it.
 
+### Domain glossary (process only)
+
+If the repo already has a product/domain glossary, prefer those terms when naming layers,
+slices, intents, and Shape pilots. Common root names (detect; none required):
+
+- `CONTEXT.md`
+- `docs/glossary.md` · `docs/domain.md` · `docs/ubiquitous-language.md` · `docs/CONTEXT.md`
+
+Call out glossary language vs lived code when they disagree. **Missing glossary is normal** —
+do not spam warnings and do not invent a glossary file. Glossary content never enforces; the
+gate remains the contract + scan. Skills: `/ark-adopt`, `/ark-explore`.
+
 ## 1. Config — reflect what exists, propose the rest
 
 ```bash

package/docs/package-surface.md

@@ -19,6 +19,10 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). |
 | **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.5+)** | `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. |
+| **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. |
 | **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. |
@@ -205,9 +209,8 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current published: [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md);
- next prepare: [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md);
- prior published: [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
+(current published: [4.5.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.5.md);
+ prior published: [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/product-voice.md

@@ -106,6 +106,19 @@ Examples:
 | **out-of-scope lens** | Principle Ark does not instrument (e.g. scalability APM, SAST) — say so; do not invent residual |
 | **AI-easy architecture** | Small, pure, placeable modules and a golden pattern so the next agent turn stays ordered under the contract |
 | **self-service upgrade honesty** | After managed upgrade, consumers can see write-path activation labels and customized-content preserve without asking a maintainer |
+| **module** | Anything with a surface callers depend on and an implementation behind it (function, package, slice) — not only a TypeScript `module` keyword |
+| **interface** (product sense) | Everything a caller must know: types, invariants, errors, ordering, config — not only a TypeScript `interface` keyword |
+| **depth** / **deep module** | Much behavior behind a **small interface** (deep) vs interface almost as complex as the body (shallow). Prefer deep modules. **Never** a 0–10 depth score |
+| **seam** | Place where behavior can be swapped or tested without editing callers (port boundary). Name seams when proposing ports/adapters or Shape pilots |
+| **adapter** | Concrete thing that satisfies an interface at a seam |
+| **leverage** | Capability callers get per unit of interface they must learn |
+| **locality** | Change, bugs, and verification concentrate in one place |
+| **deletion test** | Process heuristic before extracting “just for tests”: if you delete the module and complexity *vanishes*, it was mostly pass-through; if complexity *reappears* across many callers, it was earning its keep. One adapter → seam still hypothetical; two real adapters → seam justified |
+| **test at the public interface** | Prefer verifying behavior through the seam’s public surface, not through private pass-through layers or extraction-for-test-only modules |
+| **hot path** (advisory) | Repo-relative path with elevated **recent change volume** (heuristic from git history when available). Advisory residual only — never a gate input; omit or mark unavailable when history is missing |
+| **deepening candidate** (advisory) | Shape residual card projected only from **existing** smells / cohesion / compass evidence — locality/leverage intent; never invents candidates without evidence; never flips the verdict |
+| **domain glossary** | Optional consumer file of product terms (common roots: `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`). Prefer terms for layer/slice/pilot naming when present. Missing glossary is normal — no warning spam; never enforces |
+| **two-axis done** | (1) architecture residual via status/doctor/compass (scan); (2) feature/ticket residual outside the package (process). **Enforce green ≠ feature done** |
 
 ## Public docs are product-only (from 4.4.0)
 
@@ -161,6 +174,10 @@ gate  →  same binary verdict on every parity-capable adapter
 | Name scan before process | “Scan: two layer import violations. Process: fix the Application→Domain edge first.” |
 | Label projection non-enforcing | “Regenerated agent contract for this package version. Enforcement remains ark-check / hooks / required CI.” |
 | Keep status counts honest | “Inventory and residual counts are evidence — not a health score.” |
+| Prefer deep modules | “Small interface, hide the complexity. Name the seam; test at the public interface.” |
+| Apply the deletion test | “If deleting this extract would vanish the complexity, skip the pass-through; if callers re-absorb it, keep the module.” |
+| Two-axis done | “Edges green and residual lenses quiet is architecture residual; ticket acceptance is a separate axis — Enforce green ≠ feature done.” |
+| Glossary when present | “Prefer `CONTEXT.md` / product glossary terms for pilot and layer names; missing glossary is fine.” |
 
 ## Avoid
 
@@ -190,6 +207,10 @@ gate  →  same binary verdict on every parity-capable adapter
 | Treating AGENTS.md / projection / skills as the write gate | Advisory surface; hard path is hooks / MCP prepare / required CI |
 | Free-generated sensor or rule ids outside the catalog | Guardrail catalog is closed; unknown codes are a bug, not creativity |
 | Numeric “architecture health” or trust score in status JSON | Counts and residuals yes; scored trust no |
+| Depth score / “deepness rank” / Excellent module bands | Depth is vocabulary for process judgment, not a score surface |
+| Extract “just for tests” without a deletion test | Pass-through modules add interface without locality or leverage |
+| Treat hot paths or deepening candidates as gate failures | Advisory residual only; missing git never invents hot paths |
+| Claim feature done solely because Enforce is green | Two-axis done: architecture residual and ticket residual are separate |
 
 ---
 

package/docs/use.md

@@ -87,6 +87,9 @@ list: [configuration.md](configuration.md).
 
 **Green edges ≠ elegant design.** Empty remediation plan is not “architecture finished” if design residual remains.
 
+**Two-axis done:** (1) architecture residual via status/doctor/compass; (2) feature/ticket residual
+outside the package. **Enforce green ≠ feature done.**
+
 ---
 
 ## When the gate is green but the code is still messy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.5.0",
+  "version": "4.5.6",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

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

package/templates/agent-skills/README.md

@@ -1,13 +1,13 @@
 # ArkGate Agent Skills package
 
-> **Generated layout (Agent Skills packaging).** Do not edit SKILL.md files here by hand.
+> **Generated layout (ACS05).** Do not edit SKILL.md files here by hand.
 > Author skill bodies in `templates/skills/<name>.md`, then run
 > `npm run generate:agent-skills`. Drift: `npm run check:agent-skills`.
 
 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.3.0**
+Package version when last generated context: **arkgate@4.5.6**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

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

@@ -31,6 +31,18 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Spaghetti → honest contract.** SoC/DIP false-green STOP paths in plain language; residual lenses stay Incomplete until mapped.
 
+## Domain glossary (process)
+
+When present, prefer the consumer **domain glossary** for layer names, slice folders, intent names, and pilot wording:
+
+| Detect (no requirement) |
+|-------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Prefer glossary terms over inventing parallel vocabulary.
+- Call out conflicts between glossary language and code reality (process judgment).
+- **Missing glossary is normal** — continue without warning spam. Never treat glossary prose as enforcement.
+
 ## When / not when
 
 | Use `/ark-adopt` when… | Do **not** use it when… |
@@ -184,6 +196,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

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

@@ -34,6 +34,26 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Map residual lenses → dual-plan B seeds.** Plain Align / Stabilize / Shape from compass + design-weak — not a scorecard.
 
+## Deep modules (process)
+
+- Prefer **deep modules**: small **interface**, complexity hidden behind it (not a depth score).
+- When proposing a port/adapter or Shape pilot, **name the seam** (callers stay stable; behavior swaps behind it). One adapter → seam still hypothetical; two real adapters → seam justified.
+- Apply the **deletion test** before extracting “just for tests”: if deleting the module makes complexity *vanish*, it was pass-through; if complexity *reappears* across callers, it earned its keep.
+- Prefer verification **at the public interface** of the seam (locality/leverage), not private pass-through layers.
+- When doctor surfaces **hot paths** or **deepening candidates**, treat them as advisory residual only — never as a gate fail; bias dual-plan B pilots toward recent churn when listed.
+
+## Domain glossary (process)
+
+If the consumer tree has a **domain glossary**, prefer its terms for layer/slice folders, pilot names, and next-action prose:
+
+| Common root names (detect, do not require) |
+|--------------------------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Call out **glossary vs code** conflicts when names disagree with lived folders.
+- **Missing glossary is normal** — do not warn-spam or invent a glossary file.
+- Glossary content never enforces; the gate remains `ark.config.json` + scan.
+
 ## When / not when
 
 | Use `/ark-explore` when… | Do **not** use it when… |
@@ -390,6 +410,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

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

@@ -28,6 +28,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Name residual lenses** on each cluster (SoC, DIP, coupling, …). Still no weaken-gate to clear a lens.
 
+## Deep modules (process)
+
+- Prefer fixes that leave a **deep module** at a named **seam** (port in the owning layer; adapter outside).
+- Apply the **deletion test** before extracting a layer “just so tests can mock it.”
+- After a port/inject fix, **test at the public interface** of the seam (match remediation `nextAction` language), not only private internals.
+
 ## When / not when
 
 | Use `/ark-fix` when… | Do **not** use it when… |
@@ -198,6 +204,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

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

@@ -31,6 +31,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Lens language on each cluster** while looping edges; residual shape lenses hand off to explore/autopilot.
 
+## Deep modules (process)
+
+- Judgment remediations that introduce ports: **name the seam**, prefer deep modules, **test at the public interface**.
+- Do not invent pass-through files that fail the **deletion test** just to clear a plan step.
+- Empty plan A is edge residual only — Shape residual still needs explore/autopilot; green edges ≠ feature done.
+
 ## When / not when
 
 | Use `/ark-loop` when… | Do **not** use it when… |
@@ -193,6 +199,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

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

@@ -24,6 +24,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Where so the AI doesn’t mess up next time** — golden pattern + layer home before the write.
 
+## Deep modules (process)
+
+- Place so new code stays **deep**: one small public surface per concern; hide implementation details.
+- If the artifact is a port or adapter, **name the seam** and put the interface where callers should depend (usually Domain/Application), implementation on the outer side.
+- Do not scaffold empty pass-through modules that fail the **deletion test** (complexity would vanish if deleted).
+
 ## When / not when
 
 | Use `/ark-place` when… | Do **not** use it when… |
@@ -175,6 +181,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

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

@@ -28,6 +28,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **2–3 options labeled by lens impact** (what residual improves / what stays out-of-scope).
 
+## Deep modules (process)
+
+- Prefer **deep modules** (small interface, hidden complexity). Never invent a depth score.
+- Label the **seam** on each option that introduces a port/adapter; apply the **deletion test** before pass-through extracts “for testability.”
+- Recommend tests **at the public interface** of the chosen seam.
+
 ## When / not when
 
 | Use `/ark-think` when… | Do **not** use it when… |
@@ -146,6 +152,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

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

@@ -32,6 +32,38 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **After upgrade:** refresh projection; re-doctor; compass residual still drives process, not scores.
 
+## Suggested improvements (what to try next)
+
+After `ark upgrade` (preview or apply), read JSON **`whatsNew`** or the human **Suggested improvements**
+block (also on preview when nothing to apply). It lists concrete try/inspect actions for this package
+line (advisory only — not a score):
+
+1. **Deep-module coach** — `ark-check --doctor` → `doctor.deepModuleCoach` (hot paths + deepening)
+2. **Improvement compass** — residual lenses on doctor/HTML (not a score)
+3. **Session recipe** — `ark status --json` honesty modes; doctor when mode is not full
+4. **Two-axis done** — architecture residual vs feature/ticket residual (Enforce green ≠ feature done)
+5. **Self-service honesty** — upgrade `selfService` write-path labels + customized preserve
+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
+
+Never invent gate verdicts from these suggestions. Missing residual is honest empty, not green.
+
+## Field truth (package install + skills + multi-project MCP)
+
+| Situation | Honest product behavior |
+|-----------|-------------------------|
+| CLI version == `node_modules` but npm registry is ahead | `--apply` **installs** (does not false-skip). Inspect `reasonCode: BEHIND_REGISTRY`. |
+| Offline / `npm view` failed | May skip with `REGISTRY_UNAVAILABLE` + `suggestedInstallCmd` — do not invent a version. |
+| Skills customized after install | Preserved by default. Preview `skillDrift` shows counts. **`--refresh-skills`** rewrites customized *skills* only with consent. |
+| Conflicted managed assets | Still need `--accept-conflicts`. Never silent overwrite of true edits. |
+| Multiple checkouts / monorepo packages | One `expectedRoot` per project; upgrade **each** pin; restart MCP after bump; prefer project-local CLI until identity matched **and** process version aligns. |
+| Active host not in `--tools` / manifest | Preview `hostSelection` notes it and suggests `--tools` expansion. |
+
+**Post-apply:** read `postUpgradeChecks` (advisory). Confirm pin↔CLI, run doctor (compass + deepModuleCoach),
+`agents-md --check`, `ark status --json`, and MCP version note if MCP was used.
+
+
 ## Dual engine (mandatory)
 
 Use the semantic sensor (`ark-check --doctor --json` plus the strict contract
@@ -48,6 +80,11 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
 uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
 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.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
@@ -97,8 +134,8 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
 | `current` | Content identity matches the candidate. | Record/adopt safely; metadata-only stamps may refresh. |
 | `stale` | Recorded managed content still matches its old identity. | Safe candidate replacement. |
 | `missing` | Candidate is absent. | Create if new; require consent if a recorded asset was deleted. |
-| `customized` | User content diverged without a competing managed base. | Preserve it. |
-| `conflicted` | Both managed base and user content diverged. | Preserve and require explicit consent. |
+| `customized` | User content diverged without a competing managed base. | Preserve it. Opt-in rewrite for **skills only**: `--refresh-skills`. |
+| `conflicted` | Both managed base and user content diverged. | Preserve and require explicit consent (`--accept-conflicts`). |
 | `retired` | A recorded asset is no longer selected by the candidate. | Preserve its file and manifest identity; take no action. |
 
 ## Procedure
@@ -158,16 +195,18 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
    that customized files remain non-applying and that any deletion/conflict is
    blocked.
 
-3. **Update and re-preview.** If the registry is newer, run (project-local CLI):
+3. **Update and re-preview.** If the registry is newer **or** CLI == pin but registry is ahead
+   (field false-skip is fixed), run (project-local CLI):
 
    ```bash
    npx arkgate upgrade --apply
    ```
 
-   This updates through the detected package manager and hands control to the new
-   package for a fresh preview. Review that new preview; do not assume the old
-   candidate and new candidate are identical. If already on the latest package,
-   retain the current read-only preview.
+   This updates through the detected package manager (registry-aware) and hands control to the new
+   package for a fresh preview. On skip, read `reasonCode` / `suggestedInstallCmd` — agents must not
+   invent recovery. Review the new preview; do not assume old and new candidates are identical.
+   If already current (`ALREADY_CURRENT`), retain the read-only preview and still read `whatsNew`
+   + `skillDrift`.
 
    For pnpm repositories with `minimumReleaseAge`, use the repository's existing
    trusted first-party exception mechanism when the new release is still cooling
@@ -185,18 +224,25 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
    ```
 
    If recorded deletion/conflict recovery is desired, ask first and then add
-   `--accept-conflicts`. Never add it merely to make the run green. Run a second
-   preview and require `summary.changed: 0`.
+   `--accept-conflicts`. Never add it merely to make the run green.
+
+   If customized **skills** should match package templates after pin bump, ask first and add
+   `--refresh-skills` on the digest-bound apply (or a new preview that includes the flag). Never
+   add it merely to make the run green. Run a second preview and require `summary.changed: 0`
+   (unless more deliberate refreshes remain).
 
-5. **Verify enforcement and architecture.** Run
+5. **Verify enforcement and architecture (post-upgrade checks).** Read apply JSON
+   `postUpgradeChecks` when present. Also run:
    `npx arkgate-check --doctor --json` (or the project-local `ark-check`) and
    the same fail-closed architecture command used by managed apply (normally
    `npx arkgate-check --root . --config ark.config.json --strict-merge --json`).
-   Require `completeness: "complete"` and `ok: true`. Treat provider-unavailable CI
-   required-check evidence as `unverified`, never as proof that merges are
-   blocked. If new violations appear, hand off to `/ark-fix` for a small set or
-   `/ark-loop` / `/ark-autopilot` for residual debt; do not regenerate a baseline
-   without explicit approval.
+   Require `completeness: "complete"` and `ok: true`. Confirm `doctor.improvementCompass` and
+   `doctor.deepModuleCoach` honesty. Run `npx arkgate agents-md --check` and
+   `npx arkgate status --json`. If MCP was used, restart MCP after package bump and re-bind
+   identity. Treat provider-unavailable CI required-check evidence as `unverified`, never as proof
+   that merges are blocked. If new violations appear, hand off to `/ark-fix` for a small set or
+   `/ark-loop` / `/ark-autopilot` for residual debt; do not regenerate a baseline without explicit
+   approval.
 
 ## Active host vs deferred hosts
 

package/templates/skills/ark-adopt.md

@@ -31,6 +31,18 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Spaghetti → honest contract.** SoC/DIP false-green STOP paths in plain language; residual lenses stay Incomplete until mapped.
 
+## Domain glossary (process)
+
+When present, prefer the consumer **domain glossary** for layer names, slice folders, intent names, and pilot wording:
+
+| Detect (no requirement) |
+|-------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Prefer glossary terms over inventing parallel vocabulary.
+- Call out conflicts between glossary language and code reality (process judgment).
+- **Missing glossary is normal** — continue without warning spam. Never treat glossary prose as enforcement.
+
 ## When / not when
 
 | Use `/ark-adopt` when… | Do **not** use it when… |
@@ -184,6 +196,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-explore.md

@@ -34,6 +34,26 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Map residual lenses → dual-plan B seeds.** Plain Align / Stabilize / Shape from compass + design-weak — not a scorecard.
 
+## Deep modules (process)
+
+- Prefer **deep modules**: small **interface**, complexity hidden behind it (not a depth score).
+- When proposing a port/adapter or Shape pilot, **name the seam** (callers stay stable; behavior swaps behind it). One adapter → seam still hypothetical; two real adapters → seam justified.
+- Apply the **deletion test** before extracting “just for tests”: if deleting the module makes complexity *vanish*, it was pass-through; if complexity *reappears* across callers, it earned its keep.
+- Prefer verification **at the public interface** of the seam (locality/leverage), not private pass-through layers.
+- When doctor surfaces **hot paths** or **deepening candidates**, treat them as advisory residual only — never as a gate fail; bias dual-plan B pilots toward recent churn when listed.
+
+## Domain glossary (process)
+
+If the consumer tree has a **domain glossary**, prefer its terms for layer/slice folders, pilot names, and next-action prose:
+
+| Common root names (detect, do not require) |
+|--------------------------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Call out **glossary vs code** conflicts when names disagree with lived folders.
+- **Missing glossary is normal** — do not warn-spam or invent a glossary file.
+- Glossary content never enforces; the gate remains `ark.config.json` + scan.
+
 ## When / not when
 
 | Use `/ark-explore` when… | Do **not** use it when… |
@@ -390,6 +410,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-fix.md

@@ -28,6 +28,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Name residual lenses** on each cluster (SoC, DIP, coupling, …). Still no weaken-gate to clear a lens.
 
+## Deep modules (process)
+
+- Prefer fixes that leave a **deep module** at a named **seam** (port in the owning layer; adapter outside).
+- Apply the **deletion test** before extracting a layer “just so tests can mock it.”
+- After a port/inject fix, **test at the public interface** of the seam (match remediation `nextAction` language), not only private internals.
+
 ## When / not when
 
 | Use `/ark-fix` when… | Do **not** use it when… |
@@ -198,6 +204,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-loop.md

@@ -31,6 +31,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Lens language on each cluster** while looping edges; residual shape lenses hand off to explore/autopilot.
 
+## Deep modules (process)
+
+- Judgment remediations that introduce ports: **name the seam**, prefer deep modules, **test at the public interface**.
+- Do not invent pass-through files that fail the **deletion test** just to clear a plan step.
+- Empty plan A is edge residual only — Shape residual still needs explore/autopilot; green edges ≠ feature done.
+
 ## When / not when
 
 | Use `/ark-loop` when… | Do **not** use it when… |
@@ -193,6 +199,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-place.md

@@ -24,6 +24,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Where so the AI doesn’t mess up next time** — golden pattern + layer home before the write.
 
+## Deep modules (process)
+
+- Place so new code stays **deep**: one small public surface per concern; hide implementation details.
+- If the artifact is a port or adapter, **name the seam** and put the interface where callers should depend (usually Domain/Application), implementation on the outer side.
+- Do not scaffold empty pass-through modules that fail the **deletion test** (complexity would vanish if deleted).
+
 ## When / not when
 
 | Use `/ark-place` when… | Do **not** use it when… |
@@ -175,6 +181,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`