arkgate 4.6.1 → 4.6.3

package/docs/README.md

@@ -53,15 +53,15 @@ 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. [team-parliament](plans/team-parliament/README.md) **4.6.1 prepared**; [five-door-autonomy](plans/five-door-autonomy/README.md) **4.6.1 prepared**; [understandable-ark-4.6](plans/understandable-ark-4.6/README.md) **4.6.0**; [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. |
+| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. [team-parliament](plans/team-parliament/README.md) **shipped in 4.6.1**; [five-door-autonomy](plans/five-door-autonomy/README.md) **shipped in 4.6.1**; [understandable-ark-4.6](plans/understandable-ark-4.6/README.md) **4.6.0**; [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) |
 
-Prepared: [releases/4.6.1.md](releases/4.6.1.md) (`arkgate@4.6.1` — not yet npm `latest`).  
-Current published: [releases/4.6.0.md](releases/4.6.0.md) (`arkgate@4.6.0` on npm `latest`).  
-Prior: [releases/4.5.7.md](releases/4.5.7.md) (`arkgate@4.5.7`).  
-Previous: [releases/4.5.6.md](releases/4.5.6.md) · [releases/4.5.5.md](releases/4.5.5.md) · [releases/4.5.0.md](releases/4.5.0.md) · [releases/4.4.0.md](releases/4.4.0.md) · [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).  
+Current published: [releases/4.6.2.md](releases/4.6.2.md) (`arkgate@4.6.2` on npm `latest`).  
+Prepared: [releases/4.6.3.md](releases/4.6.3.md) (Codex operation-scoped hard write; not yet published).
+Prior: [releases/4.6.1.md](releases/4.6.1.md) (`arkgate@4.6.1`).  
+Previous: [releases/4.6.0.md](releases/4.6.0.md) · [releases/4.5.7.md](releases/4.5.7.md) · [releases/4.5.6.md](releases/4.5.6.md) · [releases/4.5.5.md](releases/4.5.5.md) · [releases/4.5.0.md](releases/4.5.0.md) · [releases/4.4.0.md](releases/4.4.0.md) · [releases/4.3.0.md](releases/4.3.0.md) · [releases/4.2.1.md](releases/4.2.1.md) · [releases/4.2.0.md](releases/4.2.0.md) · [releases/4.1.1.md](releases/4.1.1.md).  
 Previous major: [releases/4.0.0.md](releases/4.0.0.md) (`arkgate@4.0.0`).  
 Config: [configuration.md](configuration.md) · Agent skills dual-plane: [agent-guide.md](agent-guide.md).
 

package/docs/agent-guide.md

@@ -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
@@ -493,7 +496,7 @@ generating project structure on greenfield or early-adoption repos.
 coverage is low or the config is fresh:
 
 ```
-New to Ark? Run /ark-adopt (or /ark-architect) or: ark-check --recommend
+New to Ark? /ark-adopt or: arkgate-check --doctor
 ```
 
 The `/ark-adopt` skill ships in `templates/skills/ark-adopt.md` (leftover
@@ -1187,8 +1190,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,9 @@ 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.
+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 +509,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

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
@@ -33,7 +33,7 @@ local, MCP, CI, and repair guarantees. The table above only lists installed path
 `arkgate-mcp --session-context` appends when governed coverage is low:
 
 ```
-New to Ark? Run /ark-adopt (or /ark-architect) or: ark-check --recommend
+New to Ark? /ark-adopt or: arkgate-check --doctor
 ```
 
 ## Verify gates

package/docs/package-surface.md

@@ -17,6 +17,7 @@ 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). |
@@ -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.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md);
- current published: [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md);
- prior published: [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.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.3.md);
+current published: [4.6.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.2.md);
+ prior published: [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

@@ -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,9 +49,14 @@ 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) |
 
-**Codex / Cursor / OpenCode:** local write stays advisory forever — that is not unfinished architecture. Doctor may say **contract ready** while still reminding you that local writes are advisory; **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 + co-pilot for AI TypeScript.
+ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + a coach for AI TypeScript.
 
 ### Two planes (you choose)
 
@@ -83,7 +88,7 @@ list: [configuration.md](configuration.md).
 | **Suggest** | New or thin project | Finish `start`, re-run doctor |
 | **Adapt** | Not fully protected yet | Doctor action #1 until clean |
 | **Enforce** | Edges honest under the contract | Keep write path + CI |
-| **Enforce · design-weak** | Edges clean; design still messy | Shape door — not “done” |
+| **Enforce · leftover design work** | Edges clean; design still messy | Shape door — not “done” |
 
 **Green edges ≠ elegant design.** Empty remediation plan is not “architecture finished” if design residual remains.
 
@@ -175,7 +180,7 @@ Human doctor prints the short section above.
 | **Stabilize** | Edges under Enforce | Real debt only in baseline; write path + CI honest |
 | **Shape** | One golden pattern + pilots | Residual lenses shrink pilot by pilot — never silent multi-pilot |
 
-Green edges under **Enforce · design-weak** mean Align/Stabilize may be fine while Shape remains open.
+Green edges under **Enforce · leftover design work** mean Align/Stabilize may be fine while Shape remains open.
 Empty plan A is **not** “architecture finished.”
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "arkgate",
-  "version": "4.6.1",
-  "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
+  "version": "4.6.3",
+  "description": "One architecture config. One check. One coach.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

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": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
+  "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.1",
+  "version": "4.6.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.6.1",
+      "version": "4.6.3",
       "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.1**
+Package version when last generated context: **arkgate@4.6.2**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

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

@@ -5,8 +5,17 @@ description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield
 
 # /ark-adopt — Mark the path (session 0)
 
+**When:** empty tree, or the architecture config does not match the real folders (session 0).
+**Not when:** a single new file (`/ark-place`) or leftover design after the path is honest (`/ark-explore` then `/ark-autopilot`).
+
+## Steps
+
+1. Read `arkgate-check --doctor` (one light, one next action).
+2. Write `ark.config.json` (and a baseline only for genuine debt) in this turn.
+3. Re-run doctor. Day-to-day new files: `/ark-place`.
+
 Invoking this skill **is** the approval. Write the architecture config in this turn.
-Greenfield: scaffold like `--recommend` / today’s architect. Brownfield: match **product
+Greenfield: scaffold like `--recommend`. Brownfield: match **product
 reality**, freeze only genuine debt. A green check over a wrong config is a **false green**.
 
 ## Autonomy contract
@@ -36,7 +45,7 @@ write them in this turn. If they say the list is still right, leave it. Never in
 or auto-remove stewards.
 
 **Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
-spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+spaghetti leftover design work. Always end with dual-plan **B** seeds (or handoff explore)
 when design smells remain after the contract is honest.
 
 ## Improvement compass (process preflight)
@@ -152,7 +161,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 2. **Product map** — what ships, which apps/packages, entry routes/CLIs.
 3. **Read real source** in largest ungoverned dirs and top import edges (min **12 files**
    across **≥4 dirs**).
-4. **“Así te lo re-soluciono”** — concrete layer globs, file moves, manifest/intent proposals.
+4. **“How to fix”** — concrete layer globs, file moves, manifest/intent proposals.
 5. **Suggestive burn-down** — ranked next steps after adopt (not only “baseline done”).
 6. Never freeze a concentrated edge without investigating contract smell / false-green.
 
@@ -182,7 +191,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
      land structure/invariant entries under `arkrules/<Layer>.json` **in this turn** (ADR 0015 routing).
    - Write the config; move pure rules into Domain when safe; validate with ark-check.
-   - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
+   - Deliver section **How to fix the architecture config** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
 6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
 7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
@@ -197,7 +206,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
 ## Operating modes
 
 Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
-**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
+**Guard on the contract ≠ Shape done.** Say leftover design work remains when B residual remains.
 
 ## Verify
 

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

@@ -5,8 +5,8 @@ description: Shortcut to /ark-adopt for greenfield shape. Deprecated as a first-
 
 # /ark-architect — Shortcut to /ark-adopt
 
-**Deprecated as a first-class door.** Session 0 is **`/ark-adopt`**. Do that job now
-(greenfield scaffold via `ark-check --recommend` / MCP `ark_recommend` after `ark_identity`).
+**Not a first-run door.** This leftover name is a shortcut. Session 0 is **`/ark-adopt`**.
+Do that job now. Do not send the user to `/ark-contract` or `/ark-fix`.
 
 ## Autonomy contract
 

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

@@ -5,9 +5,16 @@ description: Apply Ark end-to-end — explore first; dual plan A (edges) + B (sh
 
 # /ark-autopilot — Apply the path
 
-**This is the apply door.** Invoking it **is** the approval. Prefer it when the user wants
-architecture cleaned end-to-end, not when they only need a map (`/ark-explore`). Doctor
-remains the control plane: re-check status after each major step.
+**When:** the user wants architecture cleaned end-to-end, or leftover design after a map.
+**Not when:** map only (`/ark-explore`), session 0 / config lying (`/ark-adopt`), or one new file (`/ark-place`).
+
+## Steps
+
+1. Read `arkgate-check --doctor` (do #1).
+2. Fix import-rule debt; if leftover design remains, apply **one** small refactor.
+3. Re-run doctor. Never weaken `ark.config.json`.
+
+**This is the apply door.** Invoking it **is** the approval. Doctor remains the control plane.
 
 ## Autonomy contract
 
@@ -81,7 +88,7 @@ decision-grade explore pass **and** without opening violating files.
 2. CLI sensors: `--plan --json`, `--coverage --json` / `--doctor` as needed.
 3. **Dual plan** always emitted (sections A and B).
 4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
-5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
+5. **“How to fix”** for each A cluster and each B pattern bet.
 6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
 7. **One-pilot loop for B:** when leftover design / design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
    → apply **only** that pilot **in this turn** → **re-doctor**. Never multi-pilot batch B; residual
@@ -153,7 +160,7 @@ Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot rep
 Include explore **§G** when spaghetti / design-weak signals fire.
 
 1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
-   **ENFORCE·design-weak** risk).
+   leftover design work risk).
 2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
 3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
 4. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a` + internal norm.

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

@@ -5,7 +5,7 @@ description: Shortcut to /ark-adopt (session 0) or /ark-autopilot (later config
 
 # /ark-contract — Shortcut to adopt / autopilot
 
-**Deprecated as a first-class door.** Writing `ark.config.json` / `arkrules/*` is
+**Not a first-run door.** This leftover name is a shortcut. Writing `ark.config.json` is
 **`/ark-adopt`** at session 0 and **`/ark-autopilot`** afterward. Do that job now.
 
 ## Autonomy contract

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

@@ -5,8 +5,9 @@ description: Ark adoption fitness audit — governed%, gates, baseline honesty,
 
 # /ark-coverage — Ark adoption fitness (not full recon)
 
-**Shortcut.** Fitness numbers only. Full map / leftover design → **`/ark-explore`**.
-Apply → **`/ark-autopilot`**. Session 0 → **`/ark-adopt`**. This is not `/ark-explore`.
+**Not a first-run door.** Fitness numbers only (governed files, gates, baseline).
+Session 0 → **`/ark-adopt`**. Leftover design → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 You audit **how this repo uses ArkGate** (coverage, gates, baseline, host write path) and
 what adoption gaps remain. Work autonomously. End with a ranked fitness report.
@@ -56,7 +57,7 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 2. **Product surface** — name the app/package(s) in one line (not a full recon).
 3. **Read real source** in the top ungoverned / high-risk clusters (minimum **10 files**
    across at least **4 directories**). Prefer domain, features, adapters, routes — not only config.
-4. **“Así te lo re-soluciono”** for adoption gaps (globs, install, baseline, intents).
+4. **“How to fix”** for adoption gaps (globs, install, baseline, intents).
 5. If plan A is empty but you see design-weak / concurrent patterns / god modules:
    list them briefly and **STOP — do not continue this skill as complete** for pattern work —
    **handoff `/ark-explore` (dual-plan seed or shape-focus)**. Do not invent a second explore report here.
@@ -127,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
 
@@ -159,7 +161,7 @@ because governed% is 100% and plan is empty.
 2. **Adoption map** — clusters you read for *fitness* (paths) — keep short.
 3. **Ranked table** (adoption residual + install/capability opportunities)
 
-| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) | Next |
+| # | Kind | Gap / opportunity | Evidence (path or CLI) | How to fix (concrete) | Next |
 
 Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity` | `design-weak`
 
@@ -169,7 +171,7 @@ Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity`
 ## Done criteria
 
 - ≥10 source files read and cited; product surface named.
-- At least one **Así te lo re-soluciono** block with real paths or install commands.
+- At least one **How to fix** block with real paths or install commands.
 - CLI numbers used as evidence, not as the whole report.
 - Design residual either absent with evidence or explicitly handed to `/ark-explore`.
 

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

@@ -5,8 +5,9 @@ description: Explain this project's architecture in plain language and generate
 
 # /ark-explain — Understand this project's architecture
 
-**Shortcut.** Teach / HTML tour only. Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Session 0 → **`/ark-adopt`**.
+**Not a first-run door.** Teach / HTML tour only. Session 0 → **`/ark-adopt`**.
+Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 The user wants to understand the architecture, a specific rule, or why the gate blocked them.