arkgate 4.5.5 → 4.5.7

package/CHANGELOG.md

@@ -5,14 +5,80 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.5.7 — 2026-08-12
+
+**Patch** over **4.5.6**. Cursor hard write path: project `.cursor/hooks.json` `preToolUse`
+gate for `Write` / `StrReplace` (failClosed), host matrix + doctor honesty, payload mapping
+(`contents` / `StrReplace`), install/merge without wiping sibling hooks. Repair envelope may
+emit; Write `updated_input` reinjection is **not** claimed. Codex/OpenCode stay advisory at
+write. Shell/Tab/human edits still rely on required CI. **No required config migration.**
+
+**Status: prepared** (not published).
+
+### Added
+
+- **Cursor hard write (CH01):** install writes `.cursor/hooks.json` with
+  `preToolUse` matcher `Write|StrReplace`, `failClosed: true`, `--hook --hook-repair`,
+  `--root-env CURSOR_PROJECT_DIR`. Merge preserves sibling Cursor hooks.
+- **Hook runtime:** Cursor payload normalization (`contents` → `content`, `StrReplace` → Edit)
+  and stdout `{ permission: "deny", agent_message, user_message }` on block.
+
+### Changed
+
+- Host support matrix: Cursor `hard-write: true` for listed ops; soft hosts are Codex/OpenCode.
+- Docs: `docs/ai-gates.md`, agent guide, README matrix, CLI help.
+
+## 4.5.6 — 2026-08-11
+
+**Patch** over **4.5.5**. Field upgrade & multi-project MCP truth (Phase FX): registry-aware
+package install, structured skip recovery, skill drift + opt-in refresh, post-upgrade checks,
+MCP process package honesty, host selection notes, early whatsNew, inventory UX-copy quieting.
+**No required config migration.** No new skill names, sensors, or scores. Freezes held.
+
+**Status: published** (on npm `latest`; see
+`docs/releases/4.5.6.md`).
+
+### Added
+
+- **Registry-aware upgrade (FX01–FX02):** `ark upgrade --apply` no longer skips package install
+  solely because CLI version equals `node_modules/arkgate`. When the registry (injectable for
+  tests) is ahead, install runs. Skip paths emit structured JSON (`reasonCode`,
+  `installedVersion`, `cliVersion`, `registryLatest`, `suggestedInstallCmd`) plus human
+  recovery. Offline / registry-unknown stays honest (`REGISTRY_UNAVAILABLE`) without inventing
+  a bump.
+- **Skill content drift honesty (FX03):** upgrade preview/JSON `skillDrift` counts
+  current/stale/customized/missing skills with sample paths and preserve notes.
+- **Opt-in skill refresh (FX04):** `--refresh-skills` rewrites customized managed *skills* to
+  package templates with explicit consent. Conflicted assets still need `--accept-conflicts`.
+  Never silent overwrite of true user edits by default.
+- **Post-upgrade verification block (FX05):** after apply, advisory `postUpgradeChecks` (pin↔CLI,
+  architecture verification, dual-truth, doctor/status/MCP notes). Always `notAScore`.
+- **MCP multi-project process honesty (FX06):** every MCP tool context includes
+  `processPackage` (`processArkgateVersion`, `projectInstalledVersion`,
+  `processPackageMismatch` / `processStale`, `nextAction`). Prefer project-local CLI until
+  identity matched and versions align; multi-checkout recipe in agent-guide + `/ark-upgrade`.
+- **Host selection honesty (FX07):** upgrade notes when detected active host ∉ managed
+  `--tools`/manifest hosts and suggests `--tools` expansion.
+- **whatsNew early path (FX08):** suggested improvements on preview even when nothing to apply;
+  includes FX field-truth try/inspect items.
+- **Inventory UX message quieting (FX09):** rules inventory downranks pure UX/error-message
+  string constants so they do not crowd business-rule pilots (no new sensors).
+
+### Changed
+
+- `/ark-upgrade` skill + upgrade help document registry-aware install, `--refresh-skills`,
+  skill drift, post-upgrade checks, and multi-project MCP restart guidance.
+
+**Freezes held:** no principle scores/ranks; no new skill names; no silent customized overwrite;
+no silent multi-project MCP retarget; soft hosts stay advisory; no fake published claims.
+
 ## 4.5.5 — 2026-08-11
 
 **Patch** over **4.5.0**. Deep-module coach train plus upgrade **suggested improvements /
 what’s new** so consumers know what to try after install. **No required config migration.**
 No new skill names, sensors, or scores. Freezes held.
 
-**Status: prepared** (implementation only; not yet on npm `latest` — remains `4.5.0` until
-the publication checklist completes).
+**Status: published** (`arkgate@4.5.5` on npm `latest`; see `docs/releases/4.5.5.md`).
 
 ### Added
 

package/README.md

@@ -16,9 +16,8 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.5.5** is **prepared** (deep-module coach + upgrade what’s new). npm `latest` remains
-> **4.5.0** until publish. [4.5.5 notes](docs/releases/4.5.5.md) · [4.5.0](docs/releases/4.5.0.md) ·
-> [4.4.0](docs/releases/4.4.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.5.6** is on npm `latest` — field upgrade truth, multi-project MCP honesty, skill drift.
+> [4.5.6 notes](docs/releases/4.5.6.md) · [4.5.5](docs/releases/4.5.5.md) · [4.5.0](docs/releases/4.5.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -114,16 +113,16 @@ Details: [docs/use.md](docs/use.md).
 | Claude Code | **Hard** block for listed ops (PreToolUse `Write` / `Edit` / `MultiEdit`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
 | Grok Build | **Hard** block for listed ops (PreToolUse `write` / `search_replace` (plus aliases)) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
 | Google Antigravity | **Hard** block for listed ops (PreToolUse `write_to_file` / `replace_file_content` / `multi_replace_file_content`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
-| Cursor | **Advisory only** at write (no hard hook) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | No hard-boundary payload |
-| OpenAI Codex | **Advisory / best-effort** at write (not equivalent to Claude/Grok hard block) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
+| Cursor | **Hard** block for listed ops (preToolUse `Write` / `StrReplace`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
+| OpenAI Codex | **Advisory / best-effort** at write (not equivalent to Claude/Grok/Cursor hard block) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
 | OpenCode | **Advisory / best-effort** at write (MCP + optional plugin; not a hard boundary) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | No hard-boundary payload |
 
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
-Cursor/Codex/OpenCode never get a fake hard write claim.
+Codex/OpenCode never get a fake hard write claim. Cursor hard write covers only listed
+`preToolUse` ops when `.cursor/hooks.json` is installed and trusted — Shell/Tab/human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
-
 <!-- arkgate-host-support:end -->
 
 #### Why the hard guarantee lives at the merge gate
@@ -209,8 +208,8 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Prepared (4.5.5) | [docs/releases/4.5.5.md](docs/releases/4.5.5.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.5.0 on npm `latest`) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
+| Current release (4.5.6 on npm `latest`) | [docs/releases/4.5.6.md](docs/releases/4.5.6.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
 | Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |
 | Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |
 | Prior (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) |

package/bin/ark-check-runtime.mjs

@@ -322,9 +322,10 @@ function usage() {
     'transition. Weakening or judgment-required findings fail unless --policy-ack names',
     'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
     'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
-    'Add --require-write-hook claude|grok to validate a hard local write boundary for that',
-    'specific host. Cursor and Codex expose advisory MCP tools plus the shared CI check;',
-    'merge blocking requires repository policy to make that status required.',
+    'Add --require-write-hook claude|grok|antigravity|cursor to validate a hard local write',
+    'boundary for that specific host. Codex and OpenCode expose advisory MCP (plus best-effort',
+    'hooks where applicable) and the shared CI check; merge blocking requires repository policy',
+    'to make that status required.',
     '',
     '--require-gates implies --strict-config and fails when the Ark contract in AGENTS.md,',
     'the project-rooted Ark server in .mcp.json, or fail-closed CI is missing/invalid.',
@@ -332,7 +333,8 @@ function usage() {
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
-    '(Claude/Grok hard-write hooks; Cursor/Codex advisory MCP; shared CI check for all) and',
+    '(Claude/Grok/Antigravity/Cursor hard-write hooks when covered; Codex advisory MCP;',
+    'shared CI check for all) and',
     'windsurf, cline, copilot, kiro, roo, continue, gemini',
     '(instruction-tier rule files derived from the same contract).',
     'It also installs the /ark-* skills shipped in templates/skills/ into each',

package/bin/ark-mcp-runtime.mjs

@@ -6,6 +6,10 @@ import readline from 'node:readline';
 import { createHash, randomUUID } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import {
+  buildProcessPackageHonesty,
+  readProjectInstalledArkgateVersion,
+} from './lib/mcp-process-package.mjs';
 import {
   DEFAULT_INTENT_PREFIXES,
   DEFAULT_LAYER_DIRECTORIES,
@@ -350,6 +354,8 @@ function mapAntigravityToolCall(toolCall) {
  * Grok Build:  { toolName, toolInput:  { file_path, content | old_string/new_string } }
  *              (aliases Write/Edit/MultiEdit → write/search_replace; matcher keeps both)
  * Antigravity: { toolCall: { name, args: { TargetFile, CodeContent, … } } }
+ * Cursor:      { tool_name, tool_input, hook_event_name?, workspace_roots? }
+ *              Write uses `contents`; StrReplace maps to Edit (path/old_string/new_string).
  */
 function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_HOOK_EVENT)) {
   const antigravityStyle =
@@ -366,17 +372,25 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
       toolInput: { ...(mapped?.toolInput ?? {}), file_path: filePath },
       grokStyle: true, // decision JSON on stdout (deny)
       antigravityStyle: true,
+      cursorStyle: false,
       operation: mapped?.operation ?? mapped?.toolName ?? null,
     };
   }
 
   const rawName = payload?.tool_name ?? payload?.toolName ?? '';
-  const toolInput = payload?.tool_input ?? payload?.toolInput ?? {};
+  const toolInputRaw = payload?.tool_input ?? payload?.toolInput ?? {};
+  const toolInput =
+    toolInputRaw && typeof toolInputRaw === 'object' ? { ...toolInputRaw } : {};
+  // Cursor Write uses `contents`; Claude/Grok use `content`.
+  if (toolInput.content == null && typeof toolInput.contents === 'string') {
+    toolInput.content = toolInput.contents;
+  }
   const nameMap = {
     Write: 'Write',
     write: 'Write',
     Edit: 'Edit',
     search_replace: 'Edit',
+    StrReplace: 'Edit',
     MultiEdit: 'MultiEdit',
     ApplyPatch: 'ApplyPatch',
     apply_patch: 'ApplyPatch',
@@ -387,6 +401,15 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
   const toolName = nameMap[rawName] ?? rawName;
   const filePath =
     toolInput.file_path ?? toolInput.filePath ?? toolInput.path ?? toolInput.target_file;
+  const cursorStyle =
+    Boolean(process.env.CURSOR_PROJECT_DIR) ||
+    Boolean(process.env.CURSOR_VERSION) ||
+    (payload != null &&
+      typeof payload === 'object' &&
+      (payload.hook_event_name === 'preToolUse' ||
+        Array.isArray(payload.workspace_roots) ||
+        rawName === 'StrReplace' ||
+        (rawName === 'Write' && typeof toolInputRaw?.contents === 'string')));
   return {
     toolName,
     toolInput: { ...toolInput, file_path: filePath },
@@ -395,7 +418,8 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
       grokHookEvent ||
       (payload != null && typeof payload === 'object' && 'toolName' in payload),
     antigravityStyle: false,
-    operation: null,
+    cursorStyle,
+    operation: rawName === 'StrReplace' ? 'StrReplace' : null,
   };
 }
 
@@ -550,7 +574,7 @@ function designDeltaViolations(delta) {
  * generated code are inserted literally, never interpreted as replacement patterns.
  */
 function proposedSource(toolName, toolInput) {
-  if (toolName === 'Write') return toolInput.content;
+  if (toolName === 'Write') return toolInput.content ?? toolInput.contents;
 
   let text = '';
   try {
@@ -606,18 +630,30 @@ function emitAntigravityAllow(output, antigravityStyle) {
   output.stdout(`${JSON.stringify({ decision: 'allow' })}\n`);
 }
 
+/** Cursor preToolUse accepts explicit allow; exit 0 alone also works. */
+function emitCursorAllow(output, cursorStyle) {
+  if (!cursorStyle) return;
+  output.stdout(`${JSON.stringify({ permission: 'allow' })}\n`);
+}
+
+function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
+  emitAntigravityAllow(output, antigravityStyle);
+  emitCursorAllow(output, cursorStyle);
+}
+
 function runHookPayload(payload, gate, config, args, ts, attemptContext, output = processHookOutput()) {
-  const { toolName, toolInput, grokStyle, antigravityStyle, operation } = normalizeHookPayload(
-    payload,
-    attemptContext?.grokHookEvent ?? Boolean(process.env.GROK_HOOK_EVENT)
-  );
+  const { toolName, toolInput, grokStyle, antigravityStyle, cursorStyle, operation } =
+    normalizeHookPayload(
+      payload,
+      attemptContext?.grokHookEvent ?? Boolean(process.env.GROK_HOOK_EVENT)
+    );
   if (toolName === 'ApplyPatch') {
     const patch = toolInput.patch ?? toolInput.input ?? toolInput.content;
     const parsedPatch = codexPatchWrites(patch, args.root);
     // Codex ApplyPatch is only preflighted when Ark can reconstruct every file operation.
     // An incomplete reconstruction must not be mislabeled as atomic or hard enforcement.
     if (!parsedPatch.complete) {
-      emitAntigravityAllow(output, antigravityStyle);
+      emitHostAllow(output, { antigravityStyle, cursorStyle });
       return;
     }
     const patchWrites = parsedPatch.writes;
@@ -683,7 +719,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
         );
       }
       if (changes.length === 0) {
-        emitAntigravityAllow(output, antigravityStyle);
+        emitHostAllow(output, { antigravityStyle, cursorStyle });
         return;
       }
       result = prepareChangeFromRoot({
@@ -741,7 +777,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       ? evaluateWriteDesignDelta({ root: args.root, config, changes, ts })
       : null;
     if (result.valid && (designDelta?.valid ?? true)) {
-      emitAntigravityAllow(output, antigravityStyle);
+      emitHostAllow(output, { antigravityStyle, cursorStyle });
       return;
     }
     const message = [
@@ -775,23 +811,23 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
   const filePath = toolInput.file_path;
   if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
     // Non-file tools: fail-open. Antigravity still needs an explicit allow decision.
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
   if (typeof filePath !== 'string' || !SOURCE_FILE.test(filePath) || filePath.endsWith('.d.ts')) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
   const rel = path.relative(args.root, path.resolve(filePath));
   const segments = rel.split(path.sep);
   if (segments[0] === '..' || segments.includes('node_modules')) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
 
   const source = proposedSource(toolName, toolInput);
   if (typeof source !== 'string') {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
 
@@ -829,7 +865,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       })
     : null;
   if (result.valid && (designDelta?.valid ?? true)) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
 
@@ -860,7 +896,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     return false;
   });
   if (newViolations.length === 0 && (designDelta?.valid ?? true)) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
   const combinedViolations = [...newViolations, ...designDeltaViolations(designDelta)];
@@ -922,7 +958,13 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       enforcement: hookEnforcement(
         args.root,
         attemptContext?.host ??
-          (antigravityStyle ? 'antigravity' : grokStyle ? 'grok' : 'claude'),
+          (antigravityStyle
+            ? 'antigravity'
+            : cursorStyle
+              ? 'cursor'
+              : grokStyle
+                ? 'grok'
+                : 'claude'),
         attemptContext?.operation ??
           operation ??
           (antigravityStyle
@@ -931,11 +973,15 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
               : toolName === 'MultiEdit'
                 ? 'multi_replace_file_content'
                 : 'write_to_file'
-            : grokStyle
+            : cursorStyle
               ? toolName === 'Edit'
-                ? 'search_replace'
-                : 'write'
-              : toolName),
+                ? 'StrReplace'
+                : 'Write'
+              : grokStyle
+                ? toolName === 'Edit'
+                  ? 'search_replace'
+                  : 'write'
+                : toolName),
         toolName === 'Write' || Boolean(attemptContext?.completePatch)
       ),
       ...(layer ? { layer } : {}),
@@ -967,6 +1013,16 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       }) + '\n'
     );
   }
+  // Cursor preToolUse: permission deny + agent_message (exit 2 also blocks).
+  if (cursorStyle) {
+    output.stdout(
+      JSON.stringify({
+        permission: 'deny',
+        agent_message: message,
+        user_message: `ArkGate blocked write to ${rel}`,
+      }) + '\n'
+    );
+  }
   output.status(2);
 }
 
@@ -1847,11 +1903,25 @@ export async function runArkMcp({ hookInput } = {}) {
     return currentBinding;
   }
 
+  /**
+   * FX06 — process package vs project install honesty (multi-project field truth).
+   * Process arkgateVersion is startup-loaded; after consumer `npm i arkgate@newer`,
+   * long-lived MCP can report a stale process version until restart.
+   * Algorithm lives in bin/lib/mcp-process-package.mjs for unit coverage.
+   */
+  function processPackageHonesty() {
+    return buildProcessPackageHonesty({
+      processVersion: typeof ark.version === 'string' ? ark.version : null,
+      root: resolvedRoot,
+    });
+  }
+
   function contextFor(binding) {
     return {
       projectIdentity,
       binding,
       authoritative: binding.authoritative,
+      processPackage: processPackageHonesty(),
     };
   }
 

package/bin/ark-shared.mjs

@@ -722,35 +722,14 @@ export function packageInstallArgv(root, versionSpec = 'latest') {
   return ['npm', ['install', '-D', pkgSpec]];
 }
 
-/**
- * Whether an install of arkgate@latest can be skipped because node_modules already
- * resolves the same version as this CLI package.
- *
- * @param {string} root
- * @param {string} [cliVersion]  this binary's package version
- * @returns {{ skip: boolean, installedVersion: string|null, reason: string }}
- */
-export function shouldSkipArkgateInstall(root, cliVersion) {
-  const pkgPath = path.join(root, 'node_modules', 'arkgate', 'package.json');
-  if (!fs.existsSync(pkgPath)) {
-    return { skip: false, installedVersion: null, reason: 'not-installed' };
-  }
-  let installedVersion = null;
-  try {
-    installedVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version ?? null;
-  } catch {
-    return { skip: false, installedVersion: null, reason: 'unreadable' };
-  }
-  if (
-    typeof cliVersion === 'string' &&
-    cliVersion &&
-    installedVersion &&
-    installedVersion === cliVersion
-  ) {
-    return { skip: true, installedVersion, reason: 'already-current' };
-  }
-  return { skip: false, installedVersion, reason: 'version-differs' };
-}
+// FX01–FX02: registry-aware skip lives in upgrade-package-decision (injectable probe).
+export {
+  shouldSkipArkgateInstall,
+  buildPackageInstallSkipPayload,
+  formatPackageInstallDecisionHuman,
+  compareSemverCore,
+  probeRegistryArkgateLatest,
+} from './lib/upgrade-package-decision.mjs';
 
 /** Package-manager aware "install a dev dependency" hint (e.g. for a missing typescript). */
 export function installDevHint(root, pkg) {

package/bin/ark.mjs

@@ -77,6 +77,7 @@ function parseArgs(argv) {
     installExplicit: false,
     apply: false,
     acceptConflicts: false,
+    refreshSkills: false,
     planDigest: undefined,
     json: false,
     internalApply: false,
@@ -118,6 +119,7 @@ function parseArgs(argv) {
     }
     else if (arg === '--apply') args.apply = true;
     else if (arg === '--accept-conflicts') args.acceptConflicts = true;
+    else if (arg === '--refresh-skills') args.refreshSkills = true;
     else if (arg === '--plan-digest') args.planDigest = requireValue(arg, i++);
     else if (arg === '--json') args.json = true;
     else if (arg === '--internal-apply') args.internalApply = true;
@@ -153,7 +155,7 @@ function usage() {
   ark start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
   ark init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture]
               [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
-  ark upgrade [--root <project>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--json] [--no-install] [--no-strict]
+  ark upgrade [--root <project>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--refresh-skills] [--json] [--no-install] [--no-strict]
   ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--manifest <manifest.json>] [--tsconfig <tsconfig.json>] [--json]
   ark status  [--root <project>] [--config ark.config.json] [--json]
               [--expected-root <abs>] [--expected-project-id sha256:…] [--tools <host>]
@@ -164,8 +166,10 @@ Commands:
   start     New here? Analyze and preview the complete setup. Read-only unless --apply.
   init      Configure Ark project enforcement with explicit prompts.
   upgrade   Preview identity-proven Ark-managed asset updates. With package install,
-            --apply bumps to @latest and recomputes the preview; a second explicit
-            --apply --no-install applies those exact bytes and verifies them.
+            --apply bumps toward registry latest when behind (not only when CLI ≠ pin)
+            and recomputes the preview; a second explicit --apply --no-install applies
+            those exact bytes and verifies them. --refresh-skills opts in to rewrite
+            customized managed skills to package templates (never silent default).
             (alias: ark update)
   preflight Validate one atomic create/update/delete set without writing project files.
   status    Unified session/project manifest (identity, activation, last check, rules).
@@ -203,8 +207,8 @@ Options:
   --remove-host <host>
                Preview or apply removal of that compact host integration; re-add it with --tools <host>.
   --require-write-hook <host>
-               Require and verify a hard local write hook for Claude or Grok. Cursor/Codex are
-               advisory-write plus hard CI merge only; impossible requests fail before any write.
+               Require and verify a hard local write hook for Claude, Grok, Antigravity, or Cursor.
+               Codex/OpenCode are advisory-write plus hard CI merge only; impossible requests fail before any write.
 
 Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
 Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.

package/bin/lib/agent-gates.mjs

@@ -26,9 +26,11 @@ export {
   antigravityHooks,
   claudeSettings,
   codexProjectConfig,
+  cursorHooks,
   grokHooks,
   grokProjectConfig,
   mergeAntigravityArkHook,
+  mergeCursorArkHook,
   mergeOpencodeArkMcp,
   opencodeProjectConfig,
 } from './hook-templates.mjs';

package/bin/lib/ci-and-commands.mjs

@@ -370,7 +370,8 @@ ${steps}
 ${placementBody}
 
 The project is only considered Ark-enforced when its host-appropriate write path is configured
-and the CI check passes. Only Claude/Grok provide a hard local write boundary; Cursor/Codex use
+and the CI check passes. Only Claude/Grok/Antigravity/Cursor provide a hard local write boundary
+(Cursor: Write/StrReplace when .cursor/hooks.json is trusted); Codex/OpenCode use
 advisory MCP plus CI. The experimental runtime is not required.
 `;
 }

package/bin/lib/gate-files.mjs

@@ -127,7 +127,7 @@ const FAIL_CLOSED_ARK_FLAG = /(?:^|\s)--(?:strict|strict-merge|require-gates)(?=
 const COMPACT_HOST_FILES = {
   claude: ['.claude/settings.json'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json'],
-  cursor: ['.cursor/mcp.json'],
+  cursor: ['.cursor/mcp.json', '.cursor/hooks.json'],
   codex: ['.codex/hooks.json', '.codex/config.toml'],
   windsurf: ['.windsurf/rules/ark.md'],
   cline: ['.clinerules/ark.md'],

package/bin/lib/hook-templates.mjs

@@ -1,20 +1,22 @@
 // Generated from hook-templates.source.mjs — run npm run generate:packaged-tooling.
-import{execCommandParts as i,execRunner as s}from"../ark-shared.mjs";const c="arkgate-mcp";function l(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${c} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function p(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function f(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),n=e.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
+import{execCommandParts as l,execRunner as i}from"../ark-shared.mjs";const s="arkgate-mcp";function h(e){const r=i(e);return`${JSON.stringify({version:1,hooks:{preToolUse:[{command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json`,matcher:"Write|StrReplace",failClosed:!0,timeout:30}]}},null,2)}
+`}function y(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${s} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function $(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function O(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),c=o.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
 # CONFIGURED ON DISK \u2014 RUNTIME NOT VERIFIED.
 # Restart Codex, then call ark_identity with expectedRoot before trusting MCP verdicts.
 [mcp_servers.ark]
 command = "${t(r)}"
-args = [${n}]
-`}function g(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]),t=e.map(n=>`"${n.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
+args = [${c}]
+`}function R(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=o.map(c=>`"${c.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
 # Restart Grok (or /mcps \u2192 refresh) after changes. Also loads repo-root .mcp.json.
 [mcp_servers.ark]
 command = "${r.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"
 args = [${t}]
-`}function u(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function k(o){const r=s(o);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
-`}function d(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...e],enabled:!0}}},null,2)}
-`}function h(o,r){let e,t;try{e=o&&o.trim()?JSON.parse(o):{},t=JSON.parse(r)}catch{return null}if(!e||typeof e!="object"||Array.isArray(e)||!t||typeof t!="object"||Array.isArray(t))return null;const n=t["ark-write-gate"];if(!n||typeof n!="object")return null;const a={...e,"ark-write-gate":n};return`${JSON.stringify(a,null,2)}
-`}function y(o,r){let e,t;try{e=o&&o.trim()?JSON.parse(o):{},t=JSON.parse(r)}catch{return null}if(!e||typeof e!="object"||Array.isArray(e))return null;const n={...e};!n.$schema&&t.$schema&&(n.$schema=t.$schema);const a=e.mcp&&typeof e.mcp=="object"&&!Array.isArray(e.mcp)?{...e.mcp}:{};return a.ark=t.mcp.ark,n.mcp=a,`${JSON.stringify(n,null,2)}
-`}export{c as PREFERRED_MCP_BIN,k as antigravityHooks,l as claudeSettings,p as codexHooks,f as codexProjectConfig,u as grokHooks,g as grokProjectConfig,h as mergeAntigravityArkHook,y as mergeOpencodeArkMcp,d as opencodeProjectConfig};
+`}function _(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function A(e){const r=i(e);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
+`}function j(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...o],enabled:!0}}},null,2)}
+`}function E(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t.hooks,p=(Array.isArray(c?.preToolUse)?c.preToolUse:[]).find(n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `));if(!p)return null;const m=o.hooks&&typeof o.hooks=="object"&&!Array.isArray(o.hooks)?{...o.hooks}:{},f=Array.isArray(m.preToolUse)?[...m.preToolUse]:[],k=n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `)&&(typeof n.matcher!="string"||/Write/.test(n.matcher)||/StrReplace/.test(n.matcher)),g=f.filter(n=>!k(n));m.preToolUse=[...g,p];const u={...o,version:o.version??t.version??1,hooks:m};return`${JSON.stringify(u,null,2)}
+`}function S(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t["ark-write-gate"];if(!c||typeof c!="object")return null;const a={...o,"ark-write-gate":c};return`${JSON.stringify(a,null,2)}
+`}function C(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o))return null;const c={...o};!c.$schema&&t.$schema&&(c.$schema=t.$schema);const a=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return a.ark=t.mcp.ark,c.mcp=a,`${JSON.stringify(c,null,2)}
+`}export{s as PREFERRED_MCP_BIN,A as antigravityHooks,y as claudeSettings,$ as codexHooks,O as codexProjectConfig,h as cursorHooks,_ as grokHooks,R as grokProjectConfig,S as mergeAntigravityArkHook,E as mergeCursorArkHook,C as mergeOpencodeArkMcp,j as opencodeProjectConfig};