arkgate 4.6.1 → 4.6.3

package/CHANGELOG.md

@@ -5,6 +5,53 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.6.3 — 2026-08-18
+
+**Patch** over **4.6.2**. Codex CLI and local ChatGPT Desktop/App Server now get a
+runtime-proven pre-write block for complete `apply_patch` calls. ArkGate accepts the current
+`tool_input.command` payload, while incomplete, hosted, specialized, shell/direct, and human
+write paths remain CI-backed. **No required config migration.**
+
+**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.3.md`).
+
+### Changed
+
+- **Codex hook payload:** current `PreToolUse` `apply_patch` bodies are read from
+  `tool_input.command`; historical patch/input/content fields stay compatible.
+- **Operation-scoped hard write:** a complete trusted and runtime-observed local patch can report
+  `hard:true` and exit `2` before disk mutation. Hook files alone stay unverified.
+- **Honesty surfaces:** host matrix, doctor/status, `--require-write-hook codex`, onboarding,
+  upgrade self-service, skills, and public docs now share the same boundary.
+- **All-path backstop:** required `arkgate-check --strict-merge` CI remains mandatory. MCP stays
+  advisory and repair reinjection is not claimed.
+
+## 4.6.2 — 2026-08-16
+
+**Patch** over **4.6.1**. First-contact copy: a newcomer (human or coding agent) sees what
+to do in a few lines — `arkgate` / `arkgate-check --help`, start wrap-up, doctor light +
+#1, write-gate deny, SessionStart, MCP tool order, and the five doors. Same 13 skill names.
+**No required config migration.**
+
+**Status: published** (on npm `latest`; see `docs/releases/4.6.2.md`).
+
+### Changed
+
+- **First-run help:** `arkgate --help` and `arkgate-check --help` are short; encyclopedia
+  text is `--help --all`. `arkgate upgrade --help` is preview vs apply.
+- **Start wrap-up:** doctor → `/ark-adopt` session 0 (not `/ark-autopilot` as step 1).
+- **Doctor:** operating-mode light + primary next action #1 print first.
+- **Write-gate deny:** `blocked {file} — {reason}` then `Next:` (move the import / `/ark-place`).
+  Rule id on a following line. No “call ark_manifest”.
+- **Agents:** SessionStart points at `/ark-adopt` or `arkgate-check --doctor`. `ark_identity`
+  is first. `ark_check` is a scan (pass/fail/incomplete), not a yes/no architecture score.
+  `server.json` first sentence is the layers definition.
+- **Skills:** five doors open with when + steps. Shortcuts are not the first-run menu.
+- **Status:** `nextAction` is `map-leftover-design` when leftover design work remains
+  (never `stay-enforced`).
+- **npm `description`:** `One architecture config. One check. One coach.` (not “co-pilot”).
+- **`docs/use.md`:** Cursor hard-blocks Write/StrReplace when hooks are trusted;
+  Codex/OpenCode stay advisory.
+
 ## 4.6.1 — 2026-08-14
 
 **Patch** over **4.6.0**. Five-door autonomy (skills write or map in-turn; CLI is sensor +
@@ -12,7 +59,7 @@ gate) plus team parliament (law vs feature: stewards, mixed-PR deny, ratchet vs
 base, cheap `--changed` check). Same 13 skill names. Steward identity is a GitHub handle or
 email, not git `user.name`. **No required config migration.**
 
-**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.1.md`).
+**Status: published** (on npm `latest`; see `docs/releases/4.6.1.md`).
 
 ### Added
 
@@ -28,6 +75,8 @@ email, not git `user.name`. **No required config migration.**
 
 - Doctor, compact router, and public lanes prefer the five doors. Historical changelogs stay
   as shipped.
+- Published 4.6.1 tarball `README.md` still banners 4.6.0 (packed at `1eadc96` before the
+  pointer flip). Tree README on `main` is current. No 4.6.2 for that banner.
 
 ## 4.6.0 — 2026-08-12
 

package/README.md

@@ -16,8 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.0** is on npm `latest` — clearer language + shared agent home skills.
-> [4.6.0 notes](docs/releases/4.6.0.md) · [4.5.7](docs/releases/4.5.7.md) · [4.5.6](docs/releases/4.5.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.6.2** is on npm `latest` — first-contact copy (what to do in a few lines).
+> **4.6.3 is prepared** — Codex CLI/local Desktop hard-block complete trusted `apply_patch`.
+> [4.6.3 notes](docs/releases/4.6.3.md) · [4.6.2](docs/releases/4.6.2.md) · [4.6.1](docs/releases/4.6.1.md) · [4.6.0](docs/releases/4.6.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -116,14 +117,15 @@ 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 | **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) |
+| 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 |
+| OpenAI Codex | **Hard** block for listed ops (PreToolUse `apply_patch` in Codex CLI and local ChatGPT Desktop/App Server) 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 |
 | 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.
-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.
+Codex hard write covers only a complete local `apply_patch`; Cursor covers only listed
+`preToolUse` ops. In both cases the project hook must be installed + trusted, while shell/direct
+filesystem writes, hosted or specialized opt-out paths, and 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 -->
@@ -132,10 +134,11 @@ This table describes the supported profile **after its files are installed and t
 
 The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary
 each host offers and enforces at the earliest boundary a repository can make non-bypassable: the
-required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity) deny the listed
-write operations at write time; advisory surfaces (MCP, rules, OpenCode plugins) coach the agent
-while it works. But any local boundary can be routed around — another tool, a direct filesystem
-write, a human edit — so the only guarantee ArkGate claims for every path is the
+required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity, Cursor, and
+Codex’s complete local `apply_patch`) deny their listed write operations at write time; advisory
+surfaces (MCP, rules, OpenCode plugins) coach the agent while it works. But any local boundary can
+be routed around — another tool, a hosted/specialized path, a direct filesystem write, or a human
+edit — so the only guarantee ArkGate claims for every path is the
 `arkgate-check --strict-merge` check, and only when the repository makes that status required.
 Local checks optimize feedback speed; the merge gate owns correctness.
 
@@ -213,7 +216,10 @@ 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) |
-| Current release (4.6.0 on npm `latest`) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Current release (4.6.2 on npm `latest`) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared patch (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |
+| Prior (4.6.1) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) |
+| Prior (4.6.0) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) |
 | Prior (4.5.7) | [docs/releases/4.5.7.md](docs/releases/4.5.7.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) |

package/bin/ark-check-runtime.mjs

@@ -95,6 +95,7 @@ import {
   writeArkRulesTemplates,
 } from './lib/presets.mjs';
 import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
+import { checkUsage, checkUsageAll } from './lib/first-run-help.mjs';
 import { createAdapterResult } from './lib/adapter-contract.mjs';
 import { collectGovernedFiles, normalize, walk } from './lib/scan-files.mjs';
 import { configWarning } from './lib/config-warnings.mjs';
@@ -166,12 +167,13 @@ function parseArgs(argv) {
     noOpenReport: false,
     version: false,
     help: false,
+    all: false,
     followConfigRoot: false,
   };
   const requireValue = (flag, index) => {
     const value = argv[index + 1];
     if (value === undefined || value.startsWith('-')) {
-      throw new Error(`Missing value for ${flag}. Run ark-check --help for usage.`);
+      throw new Error(`Missing value for ${flag}. Run arkgate-check --help for usage.`);
     }
     return value;
   };
@@ -269,8 +271,9 @@ function parseArgs(argv) {
     else if (arg === '--print-config') args.printConfig = requireValue(arg, i++);
     else if (arg === '--tsconfig') args.tsconfig = requireValue(arg, i++);
     else if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--all') args.all = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
-    else throw new Error(`Unknown argument: ${arg}. Run ark-check --help for usage.`);
+    else throw new Error(`Unknown argument: ${arg}. Run arkgate-check --help for usage.`);
   }
   return args;
 }
@@ -283,116 +286,6 @@ function displayPathFromRoot(root, absPath) {
   }
   return rel.split(path.sep).join('/');
 }
-function usage() {
-  return [
-    'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
-    '       ark-check --version',
-    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
-    '       ark-check --doctor [--json] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  read-only diagnosis; resident JSON falls back cold',
-    '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
-    '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
-    '       ark-check --rules-inventory [--json]   brownfield rules inventory (AR13; deterministic candidates, not a score)',
-    '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
-    '       ark-check --list-policy-packs            enthusiast packs (hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts)',
-    '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',
-    '       ark-check --suggest-include [--json]   propose include roots (TS packages / workspaces)',
-    '       ark-check --adopt-contract [--write]   expand include + layer patterns from ungoverned dirs (never bare lib→Presentation)',
-    '       ark-check --migrate-contract [--write] additive P0-A retrofit: inject app/api/** → Application when missing',
-    '       ark-check --ratchet-cores              when raw graph is green (0 violations; baseline ignored), set optional:false on populated cores only (writes ark.config.json)',
-    '       ark-check --watch                      re-run the check when governed files change (debounced)',
-    '       ark-check --report [file.html] [--beginner] [--reset-origin] [--no-archive] [--open|--no-open]',
-    '           HTML report + snapshots under .ark/reports/ (origin once, latest each run, history JSON)',
-    '           Best-effort open in browser (local TTY). No-op if open fails. --no-open / ARK_NO_OPEN_REPORT=1 to skip; --open forces open.',
-    '       ark-check --init [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|vite-vercel-spa|clean-architecture|onion-architecture] [--force] [--follow-config-root]',
-    '       --follow-config-root  On writes (init/install-agent-gates/migrate --write/…), adopt walked-up monorepo config root (default: keep explicit --root)',
-    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--require-write-hook <host>] [--skills-only] [--codex-home] [--claude-home] [--grok-home] [--agent-homes] [--force]',
-    '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
-    '       ark-check --print-config eleven-layer',
-    '',
-    'Adopting Ark in an existing codebase? Run --update-baseline once to freeze existing',
-    'violations, commit the baseline file, and gate CI with --baseline: only NEW violations',
-    'fail the check, so the ratchet only moves toward zero.',
-    '',
-    'Team parliament: law files (ark.config / arkrules / .ark-baseline.json) cannot ship in',
-    'the same diff as product source. --changed --base <ref> checks touched files only.',
-    '--against <ref> ratchets new keys vs that ref\'s baseline. --contract-session is a',
-    'steward law-only PR. Loosen / baseline-grow need stewards[] + --author when set.',
-    '',
-    '--init scans the project for the built-in layer directory conventions (src/domain,',
-    'src/application, src/adapters/persistence, ...) and writes an ark.config.json covering',
-    'only the layers that actually exist, with the default rules filtered to those layers.',
-    'Undetected profile layers are printed as suggestions with their conventional',
-    'directories. When nothing is detected, the full 11-layer starter profile is written',
-    'instead (all layers optional, anchored at src/), so the strict check passes today and',
-    'each layer starts being enforced as soon as its directory gains source files.',
-    '',
-    'Resolves relative, tsconfig path-alias, and package imports via the TypeScript',
-    'module resolver, then checks each resolved cross-layer import against the rules.',
-    'Path aliases resolve against the NEAREST tsconfig.json above each source file, so',
-    'monorepo packages with per-package configs work under a single --root. Pass',
-    '--tsconfig to force one config for every file. If no tsconfig is found, path',
-    'aliases are unavailable but relative/package imports still resolve.',
-    '',
-    'The correctness path resolves and parses one complete candidate on every invocation.',
-    'Legacy node_modules/.cache/ark-check.json files are ignored. --no-cache remains an',
-    'accepted compatibility no-op; the identity-keyed warm snapshot is introduced in Z07.',
-    '',
-    'Config shape:',
-    '{',
-    '  "include": ["src"],',
-    '  // optional: "exclude": ["**/vendor/**"], "excludeGenerated": false  (default skips *.gen.ts / *.generated.ts)',
-    '  "layers": [',
-    '    { "name": "DomainModel", "patterns": ["src/domain/**"], "intentPrefixes": ["Domain."],',
-    '      "forbiddenGlobals": ["fetch", "process", "Date.now", "Math.random"] }',
-    '  ],',
-    '  "rules": [{ "from": "DomainModel", "to": "PersistenceAdapters", "allowed": false }]',
-    '}',
-    '',
-    'Config warnings are advisory by default and are included in JSON output.',
-    'Use --strict-config to make config warnings fail the check.',
-    'Use --strict-merge for the fail-closed CI profile: --strict-config + --require-gates',
-    'plus the security diagnostics surfaced by doctor. --strict is a compatibility alias.',
-    'This merge profile never depends on an editor/agent hook.',
-    'When a Git merge base is available, --strict-merge classifies the ark.config.json',
-    '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|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.',
-    'Included but unclassified source files therefore stay red instead of false-green.',
-    '',
-    '--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/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',
-    'detected tool\'s command location (.claude/skills/, .cursor/commands/,',
-    '.agents/skills/ (Codex REPO catalog), .grok/skills/, .windsurf/workflows/,',
-    '.clinerules/workflows/, .github/prompts/).',
-    'Kiro, Roo, Continue, and Gemini have no command mechanism and receive only their',
-    'rule file. Existing files are never overwritten without --force, so re-running',
-    'after an update only adds what is missing. --skills-only restricts the write to',
-    'just the /ark-* skills (safe to --force-refresh — it leaves a customized AGENTS.md,',
-    'settings, and CI workflow untouched).',
-    'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
-    'from their config directories (.claude/, .cursor/, .codex/, .grok/, .windsurf/,',
-    '.clinerules/, .kiro/, .roo/, .continue/, .gemini/; copilot is explicit-only).',
-    'claude+cursor+codex+grok are written when nothing is detected.',
-    '',
-    'Generate a starter 11-layer config:',
-    '  ark-check --print-config eleven-layer > ark.config.json',
-    '',
-    'Install agent + CI enforcement templates:',
-    '  ark-check --install-agent-gates',
-  ].join('\n');
-}
 
 function readConfig(root, configPath) {
   const fullPath = path.isAbsolute(configPath)
@@ -1148,7 +1041,7 @@ async function main() {
     process.exit(0);
   }
   if (args.help) {
-    console.log(usage());
+    console.log(args.all ? checkUsageAll() : checkUsage());
     return;
   }
   if (args.init) {
@@ -1706,20 +1599,23 @@ async function main() {
                 }),
           }
         : null;
-    const currentSnapshot = buildReportSnapshot({
-      root,
-      config,
-      coverage,
-      violations: activeViolations,
-      ok,
-      suppressed: suppressed.length,
-      version: arkPackageVersion(),
-      fileCountByLayer,
-      enforcement: enforcementForReport,
-      score: fitness.score,
-      mode: fitness.mode,
-      improvementCompass: reportCompass,
-    });
+    const currentSnapshot = {
+      ...buildReportSnapshot({
+        root,
+        config,
+        coverage,
+        violations: activeViolations,
+        ok,
+        suppressed: suppressed.length,
+        version: arkPackageVersion(),
+        fileCountByLayer,
+        enforcement: enforcementForReport,
+        score: fitness.score,
+        mode: fitness.mode,
+        improvementCompass: reportCompass,
+      }),
+      leftoverDesignWork: designDepth?.designFitness?.designWeak === true,
+    };
     const reportPayload = {
       root,
       config,

package/bin/ark-mcp-runtime.mjs

@@ -358,6 +358,7 @@ function mapAntigravityToolCall(toolCall) {
  * 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).
+ * Codex:       { tool_name: "apply_patch", tool_input: { command: "*** Begin Patch..." } }
  */
 function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_HOOK_EVENT)) {
   const antigravityStyle =
@@ -643,6 +644,25 @@ function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
   emitCursorAllow(output, cursorStyle);
 }
 
+/**
+ * Socket-style write-gate deny: two lines first. Pass/fail, no score.
+ * Rule id stays on a following line, not the first sentence.
+ */
+function formatWriteGateDeny({ file, reason, ruleId, nextAction, extraLines = [] }) {
+  const target = file || 'this write';
+  const why = String(reason || 'this change breaks the architecture layers').replace(/\s+/g, ' ').trim();
+  const next =
+    nextAction && /place|move|import|port/i.test(nextAction)
+      ? nextAction
+      : 'Move the import or run /ark-place. Do not weaken ark.config.json.';
+  const lines = [`blocked ${target} — ${why}`, `Next: ${next}`];
+  if (ruleId) lines.push(`[${ruleId}]`);
+  for (const extra of extraLines) {
+    if (extra) lines.push(extra);
+  }
+  return lines.join('\n');
+}
+
 function runHookPayload(payload, gate, config, args, ts, attemptContext, output = processHookOutput()) {
   const { toolName, toolInput, grokStyle, antigravityStyle, cursorStyle, operation } =
     normalizeHookPayload(
@@ -650,7 +670,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       attemptContext?.grokHookEvent ?? Boolean(process.env.GROK_HOOK_EVENT)
     );
   if (toolName === 'ApplyPatch') {
-    const patch = toolInput.patch ?? toolInput.input ?? toolInput.content;
+    // Current Codex CLI/Desktop hook schema uses tool_input.command. Keep the
+    // historical fields for older clients and existing integration fixtures.
+    const patch =
+      toolInput.command ?? 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.
@@ -796,17 +819,20 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       emitHostAllow(output, { antigravityStyle, cursorStyle });
       return;
     }
-    const message = [
-      `Ark architecture gate blocked this complete ${toolName} (${changes.length} governed file(s)):`,
-      ...result.diagnostics.map(
-        (diagnostic) =>
-          `- [${diagnostic.ruleId}] ${diagnostic.message}\n  Next action: ${diagnostic.nextAction}`
-      ),
-      ...(designDelta && !designDelta.valid
-        ? formatDesignDeltaBlock(designDelta).split('\n').slice(1)
-        : []),
-      'No project file was written. Fix the complete patch and retry.',
-    ].join('\n');
+    const first = result.diagnostics[0];
+    const message = formatWriteGateDeny({
+      file: `${changes.length} file(s)`,
+      reason: first?.message || `this ${toolName} breaks the architecture layers`,
+      ruleId: first?.ruleId,
+      nextAction: first?.nextAction,
+      extraLines: [
+        ...result.diagnostics.slice(1).map((d) => `[${d.ruleId}] ${d.message}`),
+        ...(designDelta && !designDelta.valid
+          ? formatDesignDeltaBlock(designDelta).split('\n').slice(1)
+          : []),
+        'No project file was written. Fix the complete patch and retry.',
+      ],
+    });
     output.stderr(`${message}\n`);
     if (args.hookRepair) {
       output.stderr(
@@ -926,13 +952,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     })),
   });
 
-  const lines = adapterResult.diagnostics.map(
-    (diagnostic) =>
-      `- [${diagnostic.ruleId}] ${diagnostic.message}${diagnostic.location.line ? ` (line ${diagnostic.location.line})` : ''}\n  Next action: ${diagnostic.nextAction}`
-  );
-  // Surface the per-violation fix hints (the gate carries them in `suggestion`,
-  // but the hook was dropping them). Dedupe so two infra violations sharing one
-  // hint — e.g. the mayImportInfrastructure escape hatch — print it once.
+  const firstDiagnostic = adapterResult.diagnostics[0];
   const suggestions = [
     ...new Set(combinedViolations.map((violation) => violation.suggestion).filter(Boolean)),
   ];
@@ -940,27 +960,34 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
   // W4: structured repair payload is opt-in (--hook-repair / ARK_HOOK_REPAIR).
   // Default remains hard block with prose only — hosts that cannot re-inject stay clean.
   const repair = Boolean(args.hookRepair);
-  const message = [
-    `Ark architecture gate blocked this write to ${rel}${layer ? ` (layer: ${layer})` : ''}:`,
-    ...lines,
-    ...(suggestions.length > 0 ? ['Fix:', ...suggestions.map((s) => `  ${s}`)] : []),
-    ...(autoPatch && repair
-      ? [
-          `autoPatch available (${autoPatch.remediationKind}, confidence ${autoPatch.confidence}): ` +
-            'apply the patched source from ARK_AUTOPATCH_JSON / ARK_REPAIR_JSON on stderr' +
-            (grokStyle ? ' (or autoPatch in the deny JSON on stdout)' : '') +
-            ' instead of re-drafting. Gate still denies this write (never silent apply).',
-        ]
-      : []),
-    ...(autoPatch && !repair
-      ? [
-          `Mechanical-safe autoPatch is available (${autoPatch.remediationKind}). ` +
-            'Enable repair payload with ARK_HOOK_REPAIR=1 or --hook-repair to receive ' +
-            'machine-readable source (still hard-blocks; host re-injects).',
-        ]
-      : []),
-    'Fix the violations and retry. Call the project-bound ark_manifest MCP tool for the architecture contract.',
-  ].join('\n');
+  const message = formatWriteGateDeny({
+    file: rel,
+    reason: firstDiagnostic?.message || (layer ? `${layer} write breaks the layers` : 'this write breaks the layers'),
+    ruleId: firstDiagnostic?.ruleId,
+    nextAction: firstDiagnostic?.nextAction,
+    extraLines: [
+      ...adapterResult.diagnostics.slice(1).map(
+        (diagnostic) =>
+          `[${diagnostic.ruleId}] ${diagnostic.message}${diagnostic.location.line ? ` (line ${diagnostic.location.line})` : ''}`
+      ),
+      ...(suggestions.length > 0 ? suggestions.map((s) => `Fix: ${s}`) : []),
+      ...(autoPatch && repair
+        ? [
+            `autoPatch available (${autoPatch.remediationKind}, confidence ${autoPatch.confidence}): ` +
+              'apply the patched source from ARK_AUTOPATCH_JSON / ARK_REPAIR_JSON on stderr' +
+              (grokStyle ? ' (or autoPatch in the deny JSON on stdout)' : '') +
+              ' instead of re-drafting. Gate still denies this write (never silent apply).',
+          ]
+        : []),
+      ...(autoPatch && !repair
+        ? [
+            `Mechanical-safe autoPatch is available (${autoPatch.remediationKind}). ` +
+              'Enable repair payload with ARK_HOOK_REPAIR=1 or --hook-repair to receive ' +
+              'machine-readable source (still hard-blocks; host re-injects).',
+          ]
+        : []),
+    ],
+  });
   output.stderr(message + '\n');
 
   if (repair) {
@@ -1403,7 +1430,7 @@ function printSessionContext(config, profile, forbiddenGlobals, args, configPath
   const governedPercent = coverage?.coverage?.governed?.percent ?? coverage?.governed?.percent;
   if (shouldShowNewHereNudge(args.root, configPath, governedPercent, false)) {
     lines.push('');
-    lines.push('New to Ark? Run /ark-adopt (or /ark-architect) or: ark-check --recommend');
+    lines.push('New to Ark? /ark-adopt or: arkgate-check --doctor');
   }
 
   process.stdout.write(`${lines.join('\n')}\n`);
@@ -2018,9 +2045,9 @@ export async function runArkMcp({ hookInput } = {}) {
     {
       name: 'ark_identity',
       description:
-        'Return the canonical ArkGate project, config, contract, and live MCP runtime identity. ' +
-        'Pass project.expectedRoot and/or expectedProjectId to verify this process before ' +
-        'trusting any architecture evidence.',
+        'First call. Prove this MCP process is the right project: pass project.expectedRoot ' +
+        '(exact absolute root) and reuse the returned projectId. Do this before any other Ark tool. ' +
+        'A missing, unmatched, or different root means restart the host and use the local CLI.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -2063,11 +2090,10 @@ export async function runArkMcp({ hookInput } = {}) {
     {
       name: 'ark_check',
       description:
-        'Run the full Ark architecture check on the project and return structured results ' +
-        '(layer-import violations, forbidden globals, circular deps, config warnings). Use ' +
-        'this to answer "is the architecture currently valid?" instead of shelling out to ' +
-        'ark-check. Preserves legacy ok and adds identity/completeness/graph/coverage/gates/' +
-        'overall verdicts. Applies the baseline automatically when one exists. isError when not ok.',
+        'Scan the project for architecture findings (layer-import violations, forbidden globals, ' +
+        'cycles, config warnings). Returns pass/fail/incomplete plus evidence — not a yes/no ' +
+        'architecture score. Same engine as arkgate-check. Applies the baseline when one exists. ' +
+        'isError when the scan fails. Prefer after ark_identity.',
       inputSchema: {
         type: 'object',
         properties: {