arkgate 4.6.2 → 4.6.4

package/docs/agent-guide.md

@@ -8,9 +8,9 @@ reference for agents and codegen: write hooks, advisory MCP tools, CI, and `/ark
 - Docs hub: [README.md](README.md)  
 
 Guarantees differ by host; start with the
-[canonical host support matrix](../README.md#host-enforcement-support). The advisory-local /
-hard-CI split is a deliberate trade-off, not a gap: local hooks and MCP coach at write time,
-while a required merge status is the one boundary a repository can make every write path share.
+[canonical host support matrix](../README.md#host-enforcement-support). The operation-scoped
+local / all-path CI split is a deliberate trade-off, not a gap: covered local hooks block early,
+MCP coaches, and a required merge status is the one boundary every write path can share.
 
 CLI names: prefer **`arkgate` / `arkgate-check` / `arkgate-mcp`**; aliases `ark` / `ark-check` /
 `ark-mcp` still work for one major. **arkgate@3.8.0+** tests packed project TypeScript
@@ -41,17 +41,20 @@ npx ark-check --install-agent-gates --skills-only --force
 ### Write-path honesty
 
 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
+and trusted (Cursor: `Write` / `StrReplace` via `.cursor/hooks.json`). Codex CLI and local
+ChatGPT Desktop/App Server can hard-block a complete `apply_patch` through a trusted
+`.codex/hooks.json`; installed files stay unverified until a fresh covered invocation. Hosted
+tools, specialized opt-out paths, shell/direct writes, incomplete patch reconstruction, and
+OpenCode remain CI-backed or advisory. 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. Soft-write or
+unverified-hook evidence alone does not mean the project is unfinished. 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**
-merge status as the hard boundary. Product path: [use.md — What you get](use.md#what-you-get) ·
+**`ark-check --doctor`** (`doctor.writePath`) — operation-scoped local hard evidence where
+observed, then **required** merge status as the all-path boundary. Product path:
+[use.md — What you get](use.md#what-you-get) ·
 [README host matrix](../README.md#host-enforcement-support).
 
 **MCP project identity (4.2.0):** before trusting project-specific MCP evidence, call
@@ -94,7 +97,8 @@ One human often has **N checkouts** and **N package pins**. Product rules:
 | 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 |
+| Stale MCP in 4.6.4+ | `ark_identity` stays diagnostic; project tools return `PROCESS_PACKAGE_STALE` and top-level `authoritative:false` until restart |
+| Prefer project-local CLI until versions align | A modern stale global `ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry |
 | 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 |
@@ -1187,8 +1191,10 @@ Register the server itself in `.mcp.json` so the agent can handshake with `ark_i
 }
 ```
 
-On Claude/Grok, the installed PreToolUse hook makes matched writes an enforced checkpoint. MCP
-registration by itself remains advisory on every host because the agent must call the tool.
+On Claude/Grok, the installed PreToolUse hook makes matched writes an enforced checkpoint. Cursor
+does the same for Write/StrReplace, and Codex CLI/local Desktop does so for complete
+`apply_patch` calls after trust and runtime observation. MCP registration by itself remains
+advisory on every host because the agent must call the tool.
 
 Decision rationale: [ADR 0017 — MCP verdicts require explicit project identity](adr/0017-mcp-project-identity-binding.md).
 

package/docs/ai-gates.md

@@ -12,15 +12,17 @@ overview: [develop.md](develop.md) · hub: [README.md](README.md).
 | **Claude Code** | Hard PreToolUse for listed ops when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
 | **Grok Build** | Hard PreToolUse for listed ops when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
 | **Google Antigravity** | Hard PreToolUse for listed write tools when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
-| **Cursor** | **Advisory only** (MCP/rules) — no hard PreToolUse | Required CI status (same check) |
-| **OpenAI Codex** | **Advisory / best-effort** (MCP + optional hooks.json) — **not** equivalent to Claude/Grok hard block | Required CI status (same check) |
+| **Cursor** | Hard preToolUse for Write/StrReplace when installed + trusted + runtime-observed | Required CI status (same check) |
+| **OpenAI Codex** | Hard PreToolUse for complete local `apply_patch` in CLI/Desktop when installed + trusted + runtime-observed | Required CI status (same check) |
 | **OpenCode** | **Advisory / best-effort** (MCP + optional experimental plugin) — **not** a hard boundary | Required CI status (same check) |
 
-On Claude Code, Grok Build, and Google Antigravity, an installed and trusted PreToolUse hook can
-block matched writes before they land on disk. Cursor, OpenAI Codex, and OpenCode use advisory MCP
-validation at write time; CI is their hard repository check. Codex 0.123+ dispatches hooks for its
-native `apply_patch` handler, but Code Mode hosts can execute deferred nested writes without that
-project hook event. OpenCode `tool.execute.before` plugins have known subagent bypass holes. See
+On Claude Code, Grok Build, Google Antigravity, Cursor, and Codex, an installed and trusted
+PreToolUse hook can block the listed local operation before it lands on disk. Codex’s claim is
+intentionally narrow: Ark must reconstruct the complete `apply_patch`, and a fresh hook invocation
+must prove the operation. Current Codex CLI and local ChatGPT Desktop/App Server send the patch in
+`tool_input.command`; hosted tools, specialized opt-out paths, shell/direct writes, and incomplete
+patches remain outside that local claim. OpenCode `tool.execute.before` plugins have known subagent
+bypass holes. See
 the [canonical host support matrix](../README.md#host-enforcement-support) before installing. The
 advisory-local / hard-CI split is a deliberate trade-off: local surfaces optimize feedback speed,
 while a required merge status is the one boundary a repository can make every write path share.
@@ -327,29 +329,34 @@ Your repository backstop remains CI: `ark-check` fails its check on anything tha
 through (Shell bypass, Tab, incomplete coverage). It blocks the merge only when that status
 is required by repository policy.
 
-## OpenAI Codex CLI
+## OpenAI Codex CLI and local Desktop
 
 Recommended for Ark projects.
 
+Platform authority: [Codex Hooks](https://developers.openai.com/codex/hooks) ·
+[Advanced configuration](https://developers.openai.com/codex/config-advanced) ·
+[App Server](https://developers.openai.com/codex/app-server). Project-local hooks run only after
+the project and exact hook definition are trusted.
+
 Codex 0.123+ dispatches `PreToolUse` for the native `apply_patch` handler. Ark installs
 `.codex/hooks.json` with `ApplyPatch|apply_patch|Write|Edit|MultiEdit` aliases and reconstructs
 every added or updated file in a multi-file patch before allowing it. The hook passes
 `--root . --root-env CODEX_PROJECT_DIR`: ArkGate reads the environment directly without
 POSIX shell expansion and safely falls back to the hook working directory.
 
-This hook is best-effort in Codex Code Mode: some hosts execute deferred nested `apply_patch`
-calls without dispatching the project `PreToolUse` event. ArkGate therefore does not treat the
-presence of `.codex/hooks.json` as a universal hard-write guarantee; MCP remains advisory and the
-required CI status is the hard repository boundary.
+The trusted hook is a hard boundary for the covered local operation, not a universal Codex
+guarantee. ArkGate claims `hard:true` only while processing a complete runtime-observed
+`apply_patch`; `.codex/hooks.json` on disk is merely configured/unverified. Hosted tools,
+specialized opt-out paths, shell/direct writes, and incomplete reconstruction remain CI-backed.
 
 ```bash
 npx ark-check --install-agent-gates --tools codex
 ```
 
 The generated hook includes `--hook-repair`, so a rejected patch **may emit** a structured
-repair envelope (same JSON shape as Claude/Grok). **Reinjection is not guaranteed** on Codex —
-local write stays advisory/bypassable; the host must re-apply any fix, and required CI remains
-the hard merge boundary. Codex still needs hook trust enabled for the project.
+repair envelope (same JSON shape as Claude/Grok). **Reinjection is not guaranteed** on Codex:
+the host must re-apply any fix. Exit `2` is the supported deny, and required CI remains the
+all-path hard merge boundary. Codex still needs hook trust enabled for the project.
 
 Modern Codex resolves MCP servers from the active project's `.codex/config.toml`. Ark writes
 that file with relative paths, so every repository owns its primary `ark` binding without
@@ -409,8 +416,14 @@ observe a later MCP conversation from files alone. The matched `ark_identity` re
 runtime observation for that caller and live process; it does not mutate the setup JSON.
 `.codex/config.toml` by itself never upgrades `runtimeObserved` or `active`.
 
-Codex uses the best-effort local patch hook plus advisory MCP for discovery/validation and
-`ark-check` as the hard merge backstop. Register all three as soon as the repo is adopted.
+After a package bump, a long-lived Ark MCP whose package version no longer matches the project is
+non-authoritative. `ark_identity` reports `processPackage.processStale`; project tools return
+`PROCESS_PACKAGE_STALE` until Codex/local Desktop restarts or retargets the server. A modern
+outside-tree/global `ark upgrade` hands the original invocation to the project-local CLI.
+
+Codex uses an operation-scoped hard local patch hook plus advisory MCP for discovery/validation
+and `ark-check` as the all-path hard merge backstop. Register all three as soon as the repo is
+adopted.
 
 ### Legacy Codex home fallback
 
@@ -501,9 +514,10 @@ released from Ark ownership.
   home (`$CODEX_HOME/skills`). Home debt is **deferred** when the session host is not Codex.
 - Legacy flat prompts alone are reported as non-loadable skill debt with a
   `--skills-only --tools codex --force` (repo) or `--codex-home --force` (home) fix.
-- Codex **write path is advisory**: MCP + best-effort `.codex/hooks.json` is **not** a hard
-  write boundary and is **not** equivalent to Claude/Grok PreToolUse hard-write + repair.
-  The hard merge backstop is CI `--strict-merge` (or `--strict`) as a **required GitHub status context** (not “workflow file present”).
+- Codex **complete local `apply_patch` is hard** when `.codex/hooks.json` is trusted and the
+  invocation is runtime-observed. MCP remains advisory; incomplete, hosted, specialized, shell,
+  and direct-write paths rely on CI `--strict-merge` (or `--strict`) as a **required GitHub status
+  context** (not “workflow file present”).
 - CI workflows that run ark-check without the fail-closed profile (or with only
   `--strict-config`) surface gap `enforcement-ci-not-fail-closed`.
 

package/docs/develop.md

@@ -36,8 +36,9 @@ Local write hardness **differs by host**. CI required status is the shared hard
 | Host | Local write | MCP | Merge |
 |------|-------------|-----|-------|
 | Claude · Grok · Antigravity | Pre-write block when installed + trusted | Advisory | Required status context |
-| Codex · OpenCode | Warning only (not blocked) | Advisory | Required status context |
 | Cursor | Pre-write block for Write/StrReplace when `.cursor/hooks.json` is trusted | Advisory | Required status context |
+| Codex CLI · local Desktop/App Server | Pre-write block for complete `apply_patch` when `.codex/hooks.json` is trusted | Advisory | Required status context |
+| OpenCode | Warning only (not blocked) | Advisory | Required status context |
 
 Full matrix and install commands: [ai-gates.md](ai-gates.md) · canonical table in [README](../README.md#host-enforcement-support).
 
@@ -52,6 +53,8 @@ npx arkgate-check --install-agent-gates --skills-only --force
 
 Doctor reports what is actually installed and observed (`writePath` / enforcement state). Installed
 files alone do not imply `hard:true` without runtime evidence where the product requires it.
+Codex hosted tools, specialized opt-out paths, shell/direct filesystem writes, and incomplete
+patch reconstruction remain outside the local hard claim and rely on required CI.
 
 **Evidence split (Phase EH):** soft-write hosts keep `soft-write-host` in evidence without forcing
 global **Not finished** when the contract is ready. With `ARK_DOCTOR_GITHUB=1`, successful CI runs
@@ -72,6 +75,7 @@ can show `runtimeObserved: true` even when branch-protection policy is plan-unav
 | Session / project status snapshot | `ark status --json` · MCP `ark_status` · [session recipe](agent-guide.md#session-recipe-agent-turn) · schema `arkgate/schema/status-manifest` |
 | Status compass honesty | `improvementCompass.mode`: `full` \| `subset` \| `unavailable` · residual ⊆ doctor when `full` · [package-surface](package-surface.md) |
 | Managed upgrade self-service | `ark upgrade --json` → `selfService` (activation labels + customized preserve) · [package-surface](package-surface.md) |
+| Stale MCP/global CLI recovery | `processPackage.processStale` → non-authoritative + `PROCESS_PACKAGE_STALE`; modern outside-tree `ark upgrade` hands off to project-local CLI |
 | Version-matched AGENTS projection | `ark agents-md` · [agent-guide](agent-guide.md) · **non-authoritative** (never enforces) |
 | Stable finding refs (`findingRef` / `targetKey`) | analysis-result schema **1.5** · [agent-guide](agent-guide.md) · [package-surface](package-surface.md) |
 | Agent Skills layout (same 13 names) | `templates/agent-skills/` · [agent-guide](agent-guide.md#install-skills-ark-and-ecosystem) · `npx skills add …` |

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

@@ -9,7 +9,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 Installs:
 
 - Write-path configuration (Claude/Grok/Antigravity/Cursor hard PreToolUse when covered;
-  Codex advisory MCP)
+  Codex hard complete local `apply_patch`; OpenCode advisory)
   — 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

package/docs/package-surface.md

@@ -17,12 +17,13 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
 | **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). |
+| **Host write boundaries** | Generated trusted PreToolUse/preToolUse hooks + `ark-mcp --hook`; inspect with doctor/status | Hard is always operation-scoped and runtime-evidenced. From 4.6.3, Codex CLI and local ChatGPT Desktop/App Server can hard-block a complete `apply_patch` sent as `tool_input.command`; `.codex/hooks.json` on disk remains unverified until a fresh covered invocation. Hosted tools, specialized hook opt-outs, shell/direct writes, incomplete reconstruction, and humans rely on required CI. Repair envelopes may emit, but Codex reinjection is not guaranteed. |
 | **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.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. |
+| **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, Codex hard-write refresh/trust/restart/verify, stale MCP/global CLI recovery. 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. |
+| **MCP process package honesty (4.5.6; fail-closed in 4.6.4)** | Every MCP tool context → `processPackage` (`processPackageMismatch` / `processStale`, versions, `nextAction`). | Multi-checkout users: restart MCP after pin bump. From 4.6.4, stale process context is non-authoritative; `ark_identity` remains diagnostic and project tools return `PROCESS_PACKAGE_STALE` until restart/retarget. Prefer project-local CLI until identity matched and versions align. |
 | **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. |
@@ -210,9 +211,9 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(prepared: [4.6.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.2.md);
- current published: [4.6.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md);
- prior published: [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md), [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md), [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
+(prepared: [4.6.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.4.md);
+current published: [4.6.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.3.md);
+prior published: [4.6.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.2.md), [4.6.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md), [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md), [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md), [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
 [4.2.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.1.md);
 previous: [4.2.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.0.md),
 [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md),

package/docs/product-voice.md

@@ -106,7 +106,7 @@ stay stable unless a change explicitly adds an alias.
 | **runtime observed** | runtime observed | A live `ark_identity` matched this workspace |
 | **required CI status** | required CI / status context | Merge hard boundary: required GitHub status running `arkgate-check --strict-merge` |
 | **config ready** | contract ready | Project/import-rules/ArkRules honesty clear — not the same as a local pre-write block |
-| **host limitation** | environment residual | Permanent soft-write host (e.g. Codex) — do not paint the whole project unfinished |
+| **host limitation** | environment residual | Soft-write or uncovered host path (e.g. OpenCode, hosted/specialized tools) — do not paint the whole project unfinished |
 | **allowed rule ids** | guardrail catalog | Closed vocabulary of sensors, capabilities, `ruleId`s, skill roles |
 | **check (tool)** | scan | Deterministic engine / CLI / MCP. Same inputs → same verdict. No LLM. |
 | **coaching / your judgment** | process | Skill- or agent-side. **Never** package pass/fail |
@@ -178,8 +178,8 @@ gate  →  same binary verdict on every parity-capable adapter
 | Name the status light + plain fact + next action | “Enforce · leftover design work. Import rules check out; design smells remain. Next: one Shape door — explore → plan B → autopilot with OK.” |
 | Rank one primary door under residual | Doctor **Primary next action** #1; **Also** only for secondary |
 | Label expert skills as escapes | “Install skill pack only when doctor or a STOP handoff names a skill.” |
-| State host write honesty | “Cursor: pre-write block for Write/StrReplace when hooks are trusted. Codex: warning only (not blocked). Required GitHub status is the merge boundary.” |
-| Soft-write ≠ unfinished project | “Architecture contract ready; Codex local writes are advisory.” Keep `soft-write-host` in evidence; reserve **Not finished** for contract/project debt. |
+| State host write honesty | “Cursor blocks trusted Write/StrReplace. Codex blocks complete trusted local `apply_patch` after runtime observation. Required GitHub status covers every path.” |
+| Soft/unverified write ≠ unfinished project | “Architecture config ready; this host operation is advisory or unverified.” Keep environment residual in evidence; reserve **Not finished** for config/project debt. |
 | Keep Suggest on start → doctor | New-here primary is finish `start`, not a competing recommend/architect curriculum |
 | Qualify import-clean under leftover design | “None on checked imports … leftover design work remains. Not healthy finished.” |
 | Prefer unverified-as-not-green | Incomplete analysis, unobserved hooks, and soft MCP never paint as a hard green pre-write block |
@@ -208,7 +208,7 @@ gate  →  same binary verdict on every parity-capable adapter
 | Skill-shopping lists as the default curriculum | Progressive disclosure: one door first |
 | “Healthy / done” while leftover design work remains | False done |
 | “Honesty clear” as “architecture finished” | Honesty clear only means residual honesty sensors are quiet; graph/mode debt is separate |
-| “Not finished” solely because host is Codex/Cursor | Soft-write is environment residual; do not paint a green whole-tree project as unfinished architecture |
+| “Not finished” solely because a host hook is unverified or one host path is advisory | Environment residual is not architecture debt; do not paint a green whole-tree project as unfinished architecture |
 | “MCP installed / active” because a config file exists | Say **configured on disk · runtime unverified** until `ark_identity` matches the expected root |
 | Treating an unverified legacy MCP call as authoritative | Compatibility is not proof; require `binding.status: "matched"` and `authoritative: true` |
 | “Handler means controller” / “every constant is a business rule” | ArkRules inventory uses configured layer context and suppresses narrow technical/test evidence; candidates remain prompts for judgment |

package/docs/threat-model.md

@@ -32,7 +32,7 @@ infrastructure beyond how this package is published.
 | T3 | CI job missing / not required | Merge green without architecture | doctor `enforcement-ci-*` gaps; `--strict-merge`; required-status remains locally `unverified` |
 | T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | semantic policy-delta guard in strict merge; hash-bound explicit acknowledgement; present-state safety diagnostics |
 | T5 | Baseline ratcheted open | Debt reintroduced | baseline unused/stale signals; occurrence keys |
-| T6 | Dual MCP bin / wrong root | Gate points at wrong tree | migrate-commands; Codex fail-closed temp roots |
+| T6 | Stale MCP/global CLI or wrong root | Gate points at old package / wrong tree | project identity binding; stale process non-authoritative + `PROCESS_PACKAGE_STALE`; project-local upgrade handoff |
 | T7 | Malicious dependency in publish | Compromised gate | signed tags, npm provenance, dependency-review, CodeQL, Semgrep, `verify-package-files` |
 | T8 | Path traversal in hooks/check | Read/write outside project | root resolution + under-root import resolve |
 | T9 | Runtime InMemory mistaken for durable | Data loss | durability stance docs + safety InMemory production detector |
@@ -44,13 +44,17 @@ infrastructure beyond how this package is published.
 
 ```
 Claude/Grok host --PreToolUse--> arkgate-mcp (hard only for observed covered operation)
-Codex ApplyPatch  --PreToolUse--> arkgate-mcp (atomic feedback; bypassable/non-hard host profile)
+Codex apply_patch --PreToolUse--> arkgate-mcp (hard for complete trusted + observed local operation)
 Any MCP host     --tool call----> arkgate-mcp (advisory validation)
 Human IDE        --disk/git-----> working tree
 working tree     --PR-----------> CI ark-check --strict-merge
 npm publish <-- signed tag ---  GitHub Release + provenance
 ```
 
+Codex hosted tools, specialized hook opt-outs, shell/direct writes, and incomplete patch
+reconstruction do not inherit the local `apply_patch` claim; required CI remains the shared
+all-path merge boundary.
+
 ## Residual risk (accepted)
 
 - Branch protection is **external GitHub state** — doctor reports honestly when unavailable.  

package/docs/use.md

@@ -49,7 +49,12 @@ In those cases a boundary linter or editor rules may be enough; see [README —
 | Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) |
 | Anytime | Doctor: Suggest / Adapt / Enforce (+ leftover design work if the design is still messy) |
 
-**Cursor:** pre-write block for Write/StrReplace when `.cursor/hooks.json` is trusted. **Codex / OpenCode:** local write stays advisory (warning only, not blocked) — that is not unfinished architecture. Doctor may say **contract ready** while still reminding you that those hosts do not hard-block writes; **Not finished** is reserved for real project/contract debt.
+**Cursor:** pre-write block for Write/StrReplace when `.cursor/hooks.json` is trusted.
+**Codex CLI / local Desktop:** pre-write block for a complete `apply_patch` when
+`.codex/hooks.json` is trusted and the operation is observed. Hosted/specialized paths,
+shell/direct writes, and incomplete patches still rely on CI. **OpenCode:** local write stays
+advisory (warning only, not blocked). An unverified host hook is environment evidence, not
+unfinished architecture; **Not finished** is reserved for real project/config debt.
 
 ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + a coach for AI TypeScript.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.6.2",
+  "version": "4.6.4",
   "description": "One architecture config. One check. One coach.",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/arkgate",
-  "description": "When your agent writes TypeScript, ArkGate stops it from breaking the layers — and CI rejects the merge if it still does.",
+  "description": "When your agent writes TypeScript, ArkGate stops it from breaking the layers.",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.6.2",
+  "version": "4.6.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.6.2",
+      "version": "4.6.4",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/agent-skills/README.md

@@ -7,7 +7,7 @@
 This directory is the **Agent Skills–compatible** packaging of the same **13**
 `/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
 
-Package version when last generated context: **arkgate@4.6.2**
+Package version when last generated context: **arkgate@4.6.4**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

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

@@ -128,9 +128,10 @@ because governed% is 100% and plan is empty.
 **Honesty hard lines (doctor JSON):**
 - `coverageHonesty.worseThanNoGate` / weak coverage (~<50%): green is **worse than no gate**.
 - `baseline.honesty.dirtyBaselineRisk`: green-via-freeze may hide false-positive debt.
-- `writePath.honesty.softWriteHost` (Cursor / Codex / OpenCode): write path is **advisory /
-  best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
-- Do not invent hard write guarantees for soft hosts.
+- `writePath.honesty.softWriteHost` (OpenCode or another uncovered path): write path is
+  **advisory / best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
+- Cursor hard evidence is limited to trusted Write/StrReplace; Codex is limited to a complete,
+  trusted, runtime-observed local `apply_patch`. Do not borrow either claim for other paths.
 
 ## Related onboarding
 

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

@@ -58,6 +58,15 @@ line (advisory only — not a score):
 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.
 
@@ -95,8 +104,10 @@ 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.
+`npm install arkgate@…`, **restart/retarget MCP** so process version matches install. From 4.6.4,
+a stale MCP is non-authoritative: `ark_identity` diagnoses it and project tools return
+`PROCESS_PACKAGE_STALE` until restart. Prefer project-local CLI meanwhile. A modern stale global
+`ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry.
 
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 

package/templates/skills/ark-coverage.md

@@ -128,9 +128,10 @@ because governed% is 100% and plan is empty.
 **Honesty hard lines (doctor JSON):**
 - `coverageHonesty.worseThanNoGate` / weak coverage (~<50%): green is **worse than no gate**.
 - `baseline.honesty.dirtyBaselineRisk`: green-via-freeze may hide false-positive debt.
-- `writePath.honesty.softWriteHost` (Cursor / Codex / OpenCode): write path is **advisory /
-  best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
-- Do not invent hard write guarantees for soft hosts.
+- `writePath.honesty.softWriteHost` (OpenCode or another uncovered path): write path is
+  **advisory / best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
+- Cursor hard evidence is limited to trusted Write/StrReplace; Codex is limited to a complete,
+  trusted, runtime-observed local `apply_patch`. Do not borrow either claim for other paths.
 
 ## Related onboarding
 

package/templates/skills/ark-upgrade.md

@@ -58,6 +58,15 @@ line (advisory only — not a score):
 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.
 
@@ -95,8 +104,10 @@ 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.
+`npm install arkgate@…`, **restart/retarget MCP** so process version matches install. From 4.6.4,
+a stale MCP is non-authoritative: `ark_identity` diagnoses it and project tools return
+`PROCESS_PACKAGE_STALE` until restart. Prefer project-local CLI meanwhile. A modern stale global
+`ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry.
 
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)