ark-upgrade

# /ark-upgrade — managed ArkGate upgrade

**When:** bump the published `arkgate` package and refresh managed gates.
**Not when:** session 0 (`/ark-adopt`) or leftover design (`/ark-explore`).

## Steps

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

Invoking this skill **is** the approval. Preview, then `--apply` **in this turn**.
Stopping at preview is incomplete unless the probe failed or a conflict needs
`--accept-conflicts` / `--refresh-skills` consent.

For session 0, start with `/ark-adopt` (or `ark-check --recommend`); brownfield
honesty is `/ark-adopt` before this upgrade flow.

## Improvement compass (process preflight)

When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
0–10 scores or Excellent/Good ranks.

**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.

**Anti false-done:** empty plan A + leftover design work → **Incomplete? yes**. Green imports alone
are not “architecture finished.”

**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
new files; place before write (`/ark-place` / prepare-write).

**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.

**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
9. **Codex hard write refresh** — run
   `npx arkgate-check --install-agent-gates --tools codex --force`, restart Codex/local Desktop,
   review and trust the exact hook, then inspect `doctor.writePath` after a governed
   `apply_patch`. Only a complete runtime-observed local patch is hard; every other path still
   relies on required CI.
10. **Stale process recovery** — a stale Ark MCP is non-authoritative and project tools return
    `PROCESS_PACKAGE_STALE` until restart/retarget. If a modern global `ark upgrade` is older than
    the project install, it hands the same invocation to the project-local CLI instead of managing
    the project from the stale PATH binary.

Never invent gate verdicts from these suggestions. Missing residual is honest empty, not green.

## 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. |
| Stale `~/.claude/skills`, `~/.grok/skills`, or `~/.gemini/config/skills` | Shared homes should be the newest ArkGate on the machine (additive; never downgrade). Refresh: `--install-agent-gates --skills-only --agent-homes --force`. Project skills may lag with the pin. Antigravity’s global catalog still refreshes when the project `.agents/skills` already exists. |
| 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
check) and direct inspection of every managed file the preview will change.
N