arkgate 4.5.5 → 4.5.7

package/docs/README.md

@@ -53,13 +53,12 @@ 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. deep-module coach post-4.5 **implemented, not published**; 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. |
+| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. [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. |
 | 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.5.0.md](releases/4.5.0.md) (`arkgate@4.5.0` on npm `latest`).
-Prepared next: [releases/4.5.5.md](releases/4.5.5.md) (`arkgate@4.5.5` — not on `latest` until publish).  
+Current published: [releases/4.5.6.md](releases/4.5.6.md) (`arkgate@4.5.6` 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`).  

package/docs/agent-guide.md

@@ -40,12 +40,14 @@ npx ark-check --install-agent-gates --skills-only --force
 
 ### Write-path honesty
 
-Claude/Grok/Antigravity can hard-block listed PreToolUse ops when installed and trusted.
-Cursor/Codex/OpenCode remain **advisory at write**. For every host, the repository-wide hard
-boundary is a **required GitHub status context** that runs `arkgate-check --strict-merge` (alias
-`ark-check --strict-merge`) — the CLI name is not the status context name. Never claim
-Cursor/Codex/OpenCode hard write. Soft-write alone does not mean the project is unfinished; doctor
-keeps it as an environment residual. See [ai-gates.md](ai-gates.md) and the README host matrix.
+Claude/Grok/Antigravity/Cursor can hard-block listed PreToolUse / preToolUse ops when installed
+and trusted (Cursor: `Write` / `StrReplace` via `.cursor/hooks.json`). Codex/OpenCode remain
+**advisory at write**. For every host, the repository-wide hard boundary is a **required GitHub
+status context** that runs `arkgate-check --strict-merge` (alias `ark-check --strict-merge`) —
+the CLI name is not the status context name. Never claim Codex/OpenCode hard write; never claim
+Cursor hard write without the trusted hooks file covering Write|StrReplace. Soft-write alone does
+not mean the project is unfinished; doctor keeps it as an environment residual. See
+[ai-gates.md](ai-gates.md) and the README host matrix.
 
 Surface the same plane from the CLI: pair **`ark status --json`** (activation facts) with
 **`ark-check --doctor`** (`doctor.writePath`) — advisory local write on soft hosts → **required**
@@ -83,6 +85,27 @@ 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:

package/docs/ai-gates.md

@@ -286,20 +286,30 @@ Use both: the MCP server for discovery, the hook for enforcement.
 
 ## Cursor
 
-Cursor supports MCP servers (`.cursor/mcp.json`):
+Cursor supports MCP servers (`.cursor/mcp.json`) and project hooks (`.cursor/hooks.json`):
 
 ```json
 {
-  "mcpServers": {
-    "ark": {
-      "command": "npx",
-      "args": ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
-    }
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "npx arkgate-mcp --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json",
+        "matcher": "Write|StrReplace",
+        "failClosed": true,
+        "timeout": 30
+      }
+    ]
   }
 }
 ```
 
-Cursor has no pre-write hook, so the gate is advisory at write time — pair it with a rules file so the agent actually calls it. `.cursor/rules/ark.mdc`:
+When that hook is installed and trusted, Cursor **hard-blocks** agent `Write` / `StrReplace`
+for governed TypeScript sources (exit 2 or `permission: "deny"`). Repair envelopes may emit;
+Cursor does **not** guarantee Write `updated_input` reinjection — the agent must fix and retry
+from `agent_message`. Shell, Tab, and human edits still rely on CI.
+
+Pair with MCP + a rules file so the agent also calls advisory tools. `.cursor/rules/ark.mdc`:
 
 ```markdown
 ---
@@ -307,15 +317,15 @@ description: Ark architecture contract
 alwaysApply: true
 ---
 
-Before writing or editing any TypeScript source file, call the `validate_code`
-tool from the `ark` MCP server with the full post-edit file content and its
-path. If it reports violations, fix them before writing. The architecture
-contract is available authoritatively from `ark_manifest` after `ark_identity`
-matches. `ark://manifest` is compatibility-only and always unverified.
+Before trusting Ark MCP evidence, call `ark_identity` with `project.expectedRoot`
+set to the exact project root. Then call `ark_manifest`. Before writing TypeScript,
+prefer MCP `ark_prepare_write` / `validate_code` when available; the project
+`.cursor/hooks.json` hard gate still blocks invalid Write/StrReplace.
 ```
 
-Your repository backstop in Cursor is CI: `ark-check` fails its check on anything that slips
-through. It blocks the merge only when that status is required by repository policy.
+Your repository backstop remains CI: `ark-check` fails its check on anything that slips
+through (Shell bypass, Tab, incomplete coverage). It blocks the merge only when that status
+is required by repository policy.
 
 ## OpenAI Codex CLI
 

package/docs/enthusiast/how-to-agent-gates.md

@@ -8,8 +8,9 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 
 Installs:
 
-- Write-path configuration (Claude/Grok hard PreToolUse; Cursor/Codex advisory MCP)
-  — PreToolUse uses **`--hook-repair`** (W4): on deny, stderr may include
+- Write-path configuration (Claude/Grok/Antigravity/Cursor hard PreToolUse when covered;
+  Codex advisory MCP)
+  — PreToolUse / Cursor `preToolUse` uses **`--hook-repair`** (W4): on deny, stderr may include
   `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` for hosts that re-inject a patch.
   Still exit 2 / hard block; never silent write. Drop `--hook-repair` for
   reject-only prose, or set `ARK_HOOK_REPAIR=0` and omit the flag.
@@ -20,7 +21,7 @@ Installs:
 | Host | Extra paths |
 |------|-------------|
 | Claude Code | `.claude/settings.json`, `.claude/skills/` |
-| Cursor | `.cursor/mcp.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
+| Cursor | `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
 | Codex | `.codex/hooks.json`, `.codex/config.toml`, `.agents/skills/` |
 | **Grok Build** | `.grok/config.toml`, `.grok/hooks/`, `.grok/skills/` |
 

package/docs/package-surface.md

@@ -20,7 +20,9 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
 | **Improvement compass (4.4; status honesty 4.5)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. **`ark status --json` / MCP `ark_status`** project a thin `improvementCompass` residual map with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`). When `mode` is `full`, status residual lens **ids** are a **subset of** doctor residual for the same facts (report snapshot stores the thin slice after `--report`). Incomplete or missing session facts → `subset` / `unavailable` + `reasonCode` / `reason` — **never invent green residual**. Residual never flips `valid` / strict-merge / `goal.met`. When status mode ≠ full, run doctor for full 15-lens detail. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input. Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`; status: `projectStatusImprovementCompass` / `STATUS_COMPASS_MODES`. |
 | **Deep-module coach (post-4.5 advisory)** | `ark-check --doctor --json` → `doctor.deepModuleCoach`; human doctor section **Deep-module coach (advisory — not a score)** always when doctor runs (empty candidates / hot-path `unavailable` are honesty, not omission); HTML `data-advisory="deepModuleCoach"`. | Additive schema `1.0`. Always **`notAScore: true`**. **`hotPaths`**: recent-churn heuristic from bounded git log; `available` + `status` `ok` \| `unavailable`; empty `paths` when history missing/incomplete — **never invent**. **`deepeningCandidates`**: cards projected only from existing design smells / physical cohesion / reshape pilot / pilotLoop / residual compass lenses — **empty when no evidence** (no fake candidates). Never flips `valid`, strict-merge, completeness green, or `goal.met`. Prefer deep modules / named seams / test-at-public-interface process language in skills. Domain pure + CLI gen mirror (`deepeningCoach.ts` / `bin/lib/deepening-coach.mjs`); **not** a root package export — consume via `doctor.deepModuleCoach` (or the gen mirror in Tooling). |
-| **Upgrade what’s new (4.5.5)** | `ark upgrade --json` → `whatsNew` (+ human **Suggested improvements** block). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty. Never invents residual or flips gates. |
+| **Upgrade what’s new (4.5.6+)** | `ark upgrade --json` → `whatsNew` (+ human **Suggested improvements** block; also on preview). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty, registry-aware upgrade, skill drift/refresh, multi-project MCP. 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. |
@@ -207,8 +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.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md); prepared: [4.5.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.5.md);
- prior published: [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
+(current published: [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.5.5",
+  "version": "4.5.7",
   "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.5",
+  "version": "4.5.7",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.5.5",
+      "version": "4.5.7",
       "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.5.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-upgrade/SKILL.md

@@ -35,16 +35,34 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 ## Suggested improvements (what to try next)
 
 After `ark upgrade` (preview or apply), read JSON **`whatsNew`** or the human **Suggested improvements**
-block. It lists concrete try/inspect actions for this package line (advisory only — not a score):
+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)
 
@@ -62,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.
@@ -111,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
@@ -172,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
@@ -199,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-upgrade.md

@@ -35,16 +35,34 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 ## Suggested improvements (what to try next)
 
 After `ark upgrade` (preview or apply), read JSON **`whatsNew`** or the human **Suggested improvements**
-block. It lists concrete try/inspect actions for this package line (advisory only — not a score):
+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)
 
@@ -62,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.
@@ -111,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
@@ -172,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
@@ -199,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