arkgate 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -4,6 +4,89 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 2.13.0 — 2026-07-11
+
+- Added the stable, deterministic analysis IR and public in-memory API: `loadContract`,
+  `analyzeProject`, `analyzeChange`, and `explainViolation`.
+
+### Fixed
+
+- **Temp-worktree release verification:** Codex multi-project fixtures now keep the simulated
+  primary project outside temp-root policy even when the repository itself is checked out under
+  `/tmp`, so the release confidence gate is reproducible without weakening fail-closed temp MCP
+  rewrites.
+- **Test and Codex-home isolation:** Vitest now redirects `CODEX_HOME` to a disposable test home,
+  so direct helper calls and spawned CLIs cannot rewrite the developer's real Codex config. Temp
+  project installs also recognize an explicitly exported default `~/.codex` as the real home and
+  skip implicit MCP rewiring unless `--codex-home` is requested.
+- **Workflow retry boundary:** `RetryPolicy` now retries only `step.execute` failures and
+  timeouts. A snapshot-store or completion-audit failure after a successful effect is terminal,
+  enters compensation, and never executes the completed effect again.
+- **Scanner bypass corpus:** forbidden-global checks now use single-file TypeScript symbols, so
+  local `fetch` / `Date` bindings do not false-positive while ambient aliases and
+  `globalThis.Date.now()` remain violations. CLI, AICodeGate, and ESLint share the verdict.
+  TypeScript `import x = require('...')` now creates a dependency edge, and direct
+  `require(expr)` emits `DYNAMIC_REQUIRE_NOT_ALLOWLISTED` (strict profiles fail unless the file
+  is reviewed in `dynamicImportAllowlist`). The scan cache is versioned past the old semantics.
+
+### Added
+
+- **Versioned configuration contract:** `ark.config.json` now carries `$schema` and
+  `schemaVersion: "1.0"`. One canonical loader validates and migrates the contract for CLI, MCP,
+  and ESLint with path-specific diagnostics and a fail-closed unknown-key policy. The generated
+  JSON Schema ships at the stable `arkgate/schema` subpath; unversioned configs from the previous
+  major migrate deterministically in memory.
+- **Active-host enforcement capabilities:** doctor and adoption checks now project
+  `hard-write`, `advisory-write`, `merge-gate`, and `repair-payload` from the active host only,
+  with evidence paths and a separate repo-wide inventory. Claude/Grok hooks can no longer make
+  Codex, Cursor, or an unknown host appear hard-enforced; human doctor output names the host and
+  separates advisory MCP checks from the shared CI check and its external required-status policy.
+- **Host-compatible enforcement profiles:** generated CI now uses `--strict-merge`, while
+  `--strict` remains a compatibility alias; neither depends on an editor hook. The optional
+  `--require-write-hook <host>` check verifies Claude/Grok explicitly, reports Cursor/Codex as
+  advisory-write plus the shared CI check only, and makes `ark start` reject impossible,
+  mismatched, or preserved-incompatible requests before writing project files.
+- **Executable regression confidence gate:** `npm run test:confidence` now combines the existing
+  broad Vitest coverage thresholds with real Stryker mutation testing over write-path detection,
+  dependency extraction, forbidden-global detection, baseline keys, and workflow retry logic.
+  CI and both npm release paths invoke the same gate; mutation score fails below 90%.
+- **Q2 repair dogfood closed:** deny → `ARK_REPAIR_JSON`/`autoPatch` → host re-inject →
+  revalidation allow proven via shipped `bin/ark-mcp.mjs` (Claude/Grok hooks already
+  `--hook-repair`; `doctor.writePath.mode = repair`).
+- **Q3 weakest-link sensors:** `bin/lib/weakest-link.mjs` + doctor adoption gaps
+  (`enforcement-ci-*`, config drift, pre-commit missing); maintained
+  `templates/hooks/pre-commit-ark`; optional `ARK_DOCTOR_GITHUB=1` branch-protection
+  report (honest unavailable / not-protected — never fake green).
+- **Q5 scale bench:** `scripts/ark-scale-bench.mjs` / `npm run bench:scale` (real
+  ark-check cold/warm p50/p95 on generated trees).
+- **Q6 module budgets:** `scripts/check-module-budgets.mjs` / `npm run check:module-budgets`.
+- **Q8 fault-injection tests:** compensation failure audit, cancellation-ignoring timeout,
+  outbox retry attempts + clear (durability boundary).
+- **Q9 threat model + package allowlist:** `docs/threat-model.md`,
+  `scripts/verify-package-files.mjs` / `npm run check:package-files`.
+
+### Changed
+
+- **Product identity retained:** ArkGate, `arkgate`, the `arkgate*` / `ark*` commands,
+  `ark.config.json`, `ark://`, `ARK_*`, the existing GitHub repository, and `arkgate.online` remain
+  canonical. The unpublished local rename experiment was reversed before any external cutover.
+- **Truthful host support matrix and runtime status:** one capability-backed matrix now drives
+  README and generated `AGENTS.md` guarantees for Claude, Grok, Cursor, and Codex. Doctor exposes
+  both the supported host profile and repository evidence; public docs distinguish hard local
+  hooks, advisory MCP, CI checks, and required-status merge blocking. The optional runtime/Nest
+  surface is explicitly experimental and is not required for architecture-gate adoption.
+- **Active host vs deferred Codex on upgrade/doctor:** `/ark-upgrade` greens the
+  **session host** first; Codex `$CODEX_HOME` prompts/MCP multi-project debt is
+  **deferred** when the session host is **known and not Codex** (Grok/Claude/Cursor).
+  Unknown host (CI/plain shell) keeps original severity. Doctor marks deferred gaps
+  `deferred: true` (severity `info`), prefixes the message, and omits them from Top
+  actions. Temp/upgrade MCP `--root` stays urgent (fail-closed). New helpers:
+  `detectActiveAgentHost`, `codexConcernIsActive` (do not treat `CODEX_HOME` alone
+  as Codex). `ark-check` advisory for stale Codex-home skills notes the deferral.
+  Completion contract adds **Active host** / **Deferred hosts**.
+- **ROADMAP Track Q:** Q2 `done`; Q3/Q5/Q6/Q8/Q9 `doing` with residual external/DoD
+  items listed; Q4/Q7/Q10 remain `todo` (no false complete).
+
 ## 2.12.0 — 2026-07-10
 
 ### Fixed

package/README.md

@@ -43,15 +43,19 @@ commands above).
 
 ## What it is (30 seconds)
 
-**ArkGate** = a machine-readable architecture file (`ark.config.json`) enforced in two places
-you always care about:
+**ArkGate** = a machine-readable architecture file (`ark.config.json`) enforced at CI, with
+host-specific protection while an agent writes:
+
+**Name note:** this is the TypeScript architecture-enforcement package published as `arkgate`.
+It is not affiliated with the separate Archgate CLI project.
 
 | When | Tool |
 |------|------|
-| **While the AI writes** | `arkgate-mcp` write gate (blocks bad edits) |
-| **Before merge** | `arkgate-check` CI |
+| **While the AI writes** | Hard PreToolUse block on Claude/Grok; advisory MCP on Cursor/Codex |
+| **Before merge** | `arkgate-check` CI check; merge blocking requires it as a required status |
 
-Optional later: runtime kernel (`createArkKernel`) if you want event/intent governance.
+Optional later: the **experimental** runtime kernel (`createArkKernel`) if you want to evaluate
+event/intent governance. It is not required for gate adoption.
 
 It is **not** a web framework, ORM, or job runner.
 
@@ -82,7 +86,7 @@ mode you configure:
 |-------|--------|-----------|
 | **Suggest** | New/thin project | Finish `start` + autopilot |
 | **Adapt** | Not fully protected yet | Keep autopilot / adopt until clean |
-| **Enforce** | Gates can honestly protect you | Build features; fix with `/ark-fix` if blocked |
+| **Enforce** | Contract coverage is honest and checked edges are clean | Keep the host-appropriate write path; require the CI status if it must block merges |
 
 You **arrive** at Enforce. You never “turn on Enforce”.
 
@@ -143,7 +147,7 @@ npx arkgate-check --coverage
 
 ## Other skills (only when you need them)
 
-Install once: `npx arkgate-check --install-agent-gates`  
+Install once: `npx arkgate-check --install-agent-gates`
 (`--tools claude,cursor,codex,grok` to pick hosts.)
 
 **Default is always `/ark-autopilot`.** The rest are escapes, not a second curriculum.
@@ -155,8 +159,9 @@ otherwise they **fall back to sequential**.
 
 **Write path (Track W):** Prefer MCP **`ark_prepare_write`** when you have a snippet (place +
 constrain + validate + optional `autoPatch` + `judgmentBrief`). PreToolUse hooks with
-`--hook-repair` emit machine-readable repair payloads on deny (still hard block; never silent
-write). See [docs/ai-gates.md](docs/ai-gates.md).
+`--hook-repair` on Claude/Grok emit machine-readable repair payloads on deny (still hard block;
+never silent write). Cursor/Codex MCP calls remain advisory. See
+[docs/ai-gates.md](docs/ai-gates.md).
 
 | Need | Skill |
 |------|--------|
@@ -170,11 +175,24 @@ write). See [docs/ai-gates.md](docs/ai-gates.md).
 | Edit `ark.config.json` safely | `/ark-contract` |
 | Plain-language tour of the report | `/ark-explain` |
 | Deep coverage + opportunities audit | `/ark-coverage` |
-| Migrate hand-rolled bus/outbox (TS) | `/ark-runtime` |
-| Bump ArkGate + refresh all agent hosts | `/ark-upgrade` |
+| Evaluate the experimental runtime against hand-rolled bus/outbox (TS) | `/ark-runtime` |
+| Bump ArkGate + refresh active host (defer Codex when not on Codex) | `/ark-upgrade` |
+
+### Host enforcement support
+
+<!-- arkgate-host-support:start -->
+| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |
+|------|----------------------|----------------|-----------------|----------------|
+| Claude Code | Hard block for PreToolUse `Write` / `Edit` / `MultiEdit` | Advisory; the agent must call it | Available `arkgate-check --strict-merge` check | Emitted on hook deny; host must re-inject |
+| Grok Build | Hard block for PreToolUse `write` / `search_replace` (plus aliases) | Advisory; the agent must call it | Available `arkgate-check --strict-merge` check | Emitted on hook deny; host must re-inject |
+| Cursor | No hard hook; MCP/rules are advisory | Advisory; the agent must call it | Available `arkgate-check --strict-merge` check | No hard-boundary payload |
+| OpenAI Codex | No hard hook; MCP/rules are advisory | Advisory; the agent must call it | Available `arkgate-check --strict-merge` check | No hard-boundary payload |
+
+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 payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run `arkgate-check --doctor` for the evidence actually detected in the current repository.
+<!-- arkgate-host-support:end -->
+
+Detailed setup: [docs/ai-gates.md](docs/ai-gates.md).
 
-Hosts with full MCP/hooks: **Claude Code**, **Cursor**, **Codex**, **Grok Build**.  
-More: [docs/ai-gates.md](docs/ai-gates.md). Health: **`npx arkgate-check --doctor`**.
 ---
 
 ## How it works (short)
@@ -182,19 +200,24 @@ More: [docs/ai-gates.md](docs/ai-gates.md). Health: **`npx arkgate-check --docto
 ```
 ark.config.json
       │
-      ├─► Write gate (arkgate-mcp)  — agent PreToolUse / MCP tools
-      ├─► CI gate (arkgate-check)   — PR / main
-      └─► Runtime kernel (opt-in)   — only if you call it
+      ├─► Write path (arkgate-mcp)  — hard hook or advisory MCP, by host
+      ├─► CI check (arkgate-check)  — merge block only when status is required
+      └─► Runtime kernel            — experimental opt-in; gates do not need it
 ```
 
 - **Presets:** hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts (+ aliases clean-architecture / onion-architecture). Layers start optional; doctor suggests tightening populated cores. Cross-slice / cross-context bans use optional `peerIsolation` rules.
+- **Versioned config:** generated contracts include `$schema` + `schemaVersion`; CLI, MCP, and
+  ESLint validate through the same loader. Unknown keys fail with their JSON path. See the
+  [configuration and editor guide](docs/configuration.md).
 - **Frameworks:** Nest / Next / express / library layouts get sensible globs on init so day-one coverage is real.
 - **Brownfield:** baseline ratchet, refuse to freeze a wrong contract, `/ark-adopt` for mature trees.
 - **Agents:** skills install into Claude / Cursor / Codex / Grok; `ark start` freezes **day-zero origin** under `.ark/reports/` **before** agent docs/CI templates.
 - **Write protocol (2.10 / Track W):** mechanical-safe **autoPatch** on the write gate (`import type`); MCP **`ark_prepare_write`** (place + validate + patch + judgmentBrief); opt-in hook **`--hook-repair`** (`ARK_REPAIR_JSON`); doctor **`writePath`** (repair vs reject-only); loop-cost eval (`npm run eval:loop-cost`). Port-proof inject is **judgment** (arity change), not silent auto-apply.
-- **Fail-closed CI (2.11):** `--strict` combines config coverage, required CI/MCP/write gates,
-  PreToolUse hook presence, and bypass diagnostics for dynamic imports, TypeScript suppressions,
-  explicit `any` casts, InMemory runtime defaults, and disabled peer isolation.
+- **Fail-closed CI (2.11):** `--strict-merge` combines config coverage, shared gate-file
+  presence, and bypass diagnostics for dynamic imports, TypeScript suppressions, explicit `any`
+  casts, InMemory runtime defaults, and disabled peer isolation. `--strict` is a compatibility
+  alias. Neither requires an editor hook; use `--require-write-hook claude|grok` when that local
+  guarantee is part of the check.
 - **Trust / coverage (2.12):** package unit-test floors on the broad product surface
   (statements/lines **≥80%**, branches/functions **≥85%**; enforcement-critical modules **≥95%**
   branch). Explore dual-plan + day-zero origin first (see above). Roadmap next: Q2 repair dogfood matrix.
@@ -205,7 +228,7 @@ ark.config.json
 | | ArkGate | Typical boundary linter |
 |--|:---:|:---:|
 | CI import rules | ✅ | ✅ |
-| Block **AI writes** before they land | ✅ | ❌ |
+| Hard-block supported-host AI writes before they land | ✅ (Claude/Grok hooks) | ❌ |
 | Contract agents can read (`ark://manifest`) | ✅ | ❌ |
 | Placement tools (`ark_place`, …) | ✅ | ❌ |
 | Honest governed % + adoption path | ✅ | ❌ |
@@ -225,7 +248,7 @@ npx arkgate-check --doctor --json         # machine-readable doctor.adoption
 npx arkgate-check --strict                # fail-closed CI + installed-gate/safety checks
 npx arkgate-check --plan                  # safe-to-auto-fix vs your call
 npx arkgate-check --coverage              # Governed: N%
-npx arkgate-check --report ark-report.html  # showcase HTML + Adoption card + origin/latest
+npx arkgate-check --report ark-report.html  # showcase HTML (opens in browser on local TTY; --no-open to skip)
 npx arkgate-check --baseline              # only NEW violations fail
 npx arkgate upgrade                       # package + gates/skills + MCP/Codex normalize
 ```
@@ -239,10 +262,11 @@ CI (example):
 
 ---
 
-## Optional: runtime kernel
+## Optional experimental runtime kernel
 
-Gates need **no app code changes**. If you also want runtime intent/event contracts,
-use the **opt-in** subpath (preferred):
+Gates need **no app code changes**. The runtime API is currently **experimental** and is not a
+production-readiness claim. If you want to evaluate runtime intent/event contracts, use the
+opt-in subpath (preferred):
 
 ```ts
 import { createStrictArkKernelFromConfig } from 'arkgate/runtime';
@@ -250,7 +274,7 @@ import { createStrictArkKernelFromConfig } from 'arkgate/runtime';
 ```
 
 Root `import { … } from 'arkgate'` still re-exports kernel symbols for compatibility
-in this major; prefer `arkgate/runtime` for new code.
+in this major; use `arkgate/runtime` when evaluating the experimental surface.
 
 NestJS: `arkgate/nestjs` (optional peer `@nestjs/common`).
 
@@ -269,7 +293,7 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Audience | Link |
 |----------|------|
 | New builders (plain language) | [docs/enthusiast/](docs/enthusiast/README.md) |
-| **Package surface (stable vs opt-in)** | [docs/package-surface.md](docs/package-surface.md) |
+| **Package surface (stable vs experimental)** | [docs/package-surface.md](docs/package-surface.md) |
 | Wire Claude / Cursor / Codex / Grok + **ESLint (CI-parity)** | [docs/ai-gates.md](docs/ai-gates.md) |
 | **TypeScript 5 / 6 / 7 support** | [docs/typescript-support.md](docs/typescript-support.md) |
 | Migrate from `ark-runtime-kernel` | [docs/migrate-from-ark-runtime-kernel.md](docs/migrate-from-ark-runtime-kernel.md) |
@@ -290,11 +314,11 @@ npm run typecheck
 npm run check:architecture   # Ark gates itself
 ```
 
-**Website:** [arkgate.online](https://www.arkgate.online/)  
-**npm:** [`arkgate`](https://www.npmjs.com/package/arkgate) · formerly `ark-runtime-kernel`  
-**Product:** **ArkGate** — architecture co-pilot / gate for AI TypeScript (not a runtime kernel).  
-CLI: `arkgate` · `arkgate-check` · `arkgate-mcp` (aliases `ark` / `ark-check` / `ark-mcp` still work for one major).  
-MCP registry: `io.github.pedroknigge/arkgate`.  
+**Website:** [arkgate.online](https://www.arkgate.online/)
+**npm:** [`arkgate`](https://www.npmjs.com/package/arkgate) · formerly `ark-runtime-kernel`
+**Product:** **ArkGate** — architecture co-pilot / gate for AI TypeScript (not a runtime kernel).
+CLI: `arkgate` · `arkgate-check` · `arkgate-mcp` (aliases `ark` / `ark-check` / `ark-mcp` still work for one major).
+MCP registry: `io.github.pedroknigge/arkgate`.
 **Source:** [github.com/pedroknigge/arkgate](https://github.com/pedroknigge/arkgate)
 
 Node ≥ 18 · **MIT**.

package/bin/ark-check.mjs

@@ -33,6 +33,7 @@ import {
   loadTypeScript,
   detectSkillGaps,
   detectCodexHomeGap,
+  detectActiveAgentHost,
   missingGates,
   staleRunnerGateFiles,
   brokenMcpGateFiles,
@@ -56,6 +57,7 @@ import {
   reportsDir,
   readJsonSafe,
 } from './lib/html-report.mjs';
+import { shouldOpenHtmlReport, openHtmlInBrowser } from './lib/open-html.mjs';
 import {
   computeCoverage,
   runCoverage,
@@ -81,6 +83,7 @@ import {
 import {
   ARCHITECTURE_PRESETS,
 } from './lib/presets.mjs';
+import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
 
 import {
   collectGovernedFiles,
@@ -91,6 +94,7 @@ import {
   configWarning,
 } from './lib/config-warnings.mjs';
 import { runArchitectureScan } from './lib/architecture-scan.mjs';
+import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 
 
 function parseArgs(argv) {
@@ -101,9 +105,9 @@ function parseArgs(argv) {
     printConfig: undefined,
     tsconfig: undefined,
     json: false,
-    strict: false,
     strictConfig: false,
     requireGates: false,
+    requireWriteHook: undefined,
     init: false,
     installAgentGates: false,
     tools: undefined,
@@ -122,6 +126,8 @@ function parseArgs(argv) {
     applyPolicyPack: undefined,
     watch: false,
     beginner: false,
+    openReport: false,
+    noOpenReport: false,
     version: false,
     help: false,
   };
@@ -135,13 +141,15 @@ function parseArgs(argv) {
   for (let i = 2; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') args.json = true;
-    else if (arg === '--strict') {
-      args.strict = true;
+    else if (arg === '--strict' || arg === '--strict-merge') {
       args.strictConfig = true;
       args.requireGates = true;
     }
     else if (arg === '--strict-config') args.strictConfig = true;
     else if (arg === '--require-gates') args.requireGates = true;
+    else if (arg === '--require-write-hook') {
+      args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
+    }
     else if (arg === '--init') args.init = true;
     else if (arg === '--preset') args.preset = requireValue(arg, i++);
     else if (arg === '--install-agent-gates') args.installAgentGates = true;
@@ -183,6 +191,8 @@ function parseArgs(argv) {
     }
     else if (arg === '--reset-origin') args.resetOrigin = true;
     else if (arg === '--no-archive') args.noArchive = true;
+    else if (arg === '--open') args.openReport = true;
+    else if (arg === '--no-open') args.noOpenReport = true;
     else if (arg === '--baseline' || arg === '--update-baseline') {
       if (arg === '--update-baseline') args.updateBaseline = true;
       // optional path value: consume the next arg only when it isn't another flag
@@ -214,7 +224,7 @@ 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 | --strict-config] [--require-gates] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       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 --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
@@ -224,10 +234,11 @@ function usage() {
     '       ark-check --adopt-contract [--write]   expand include + UI patterns from ungoverned dirs (contract adopt)',
     '       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]',
+    '       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|clean-architecture|onion-architecture] [--force]',
-    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--skills-only] [--codex-home] [--force]',
+    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--require-write-hook <host>] [--skills-only] [--codex-home] [--force]',
     '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',
@@ -267,8 +278,12 @@ function usage() {
     '',
     'Config warnings are advisory by default and are included in JSON output.',
     'Use --strict-config to make config warnings fail the check.',
-    'Use --strict for the fail-closed CI profile: --strict-config + --require-gates',
-    'plus the security diagnostics surfaced by doctor.',
+    '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.',
+    'Add --require-write-hook claude|grok to validate a hard local write boundary for that',
+    'specific host. Cursor and Codex expose advisory MCP tools plus the shared CI check;',
+    'merge blocking requires repository policy to make that status required.',
     '',
     '--require-gates fails the check when AGENTS.md, .mcp.json, or the generated CI',
     'workflow is missing, so "installed but never configured" is a red CI. Combine it',
@@ -276,7 +291,8 @@ function usage() {
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
-    '(full MCP/hook gates) and windsurf, cline, copilot, kiro, roo, continue, gemini',
+    '(Claude/Grok hard-write hooks; Cursor/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/,',
@@ -290,7 +306,7 @@ function usage() {
     '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 are written when nothing is detected.',
+    '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',
@@ -305,25 +321,12 @@ function readConfig(root, configPath) {
     ? configPath
     : path.join(root, configPath);
   if (!fs.existsSync(fullPath)) {
-    return {
-      include: ['src'],
-      layers: [],
-      rules: DEFAULT_RULES,
-    };
+    return loadArkConfigContract(
+      { include: ['src'], layers: [], rules: DEFAULT_RULES },
+      fullPath
+    ).config;
   }
-  const raw = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-  return {
-    include: raw.include ?? ['src'],
-    layers: raw.layers ?? [],
-    rules: raw.rules ?? DEFAULT_RULES,
-    ...(raw.exclude ? { exclude: raw.exclude } : {}),
-    ...(raw.excludeGenerated !== undefined ? { excludeGenerated: raw.excludeGenerated } : {}),
-    ...(raw.cyclePolicy ? { cyclePolicy: raw.cyclePolicy } : {}),
-    ...(raw.dynamicImportAllowlist
-      ? { dynamicImportAllowlist: raw.dynamicImportAllowlist }
-      : {}),
-    ...(raw.safety ? { safety: raw.safety } : {}),
-  };
+  return parseArkConfigJson(fs.readFileSync(fullPath, 'utf8'), fullPath).config;
 }
 
 /**
@@ -976,16 +979,41 @@ async function main() {
     return;
   }
 
-  if (args.requireGates) {
-    const missing = missingGates(args.root);
-    if (args.strict && !detectWritePathCapabilities(args.root).hookPresent) {
-      missing.push('PreToolUse write hook');
+  if (args.requireGates || args.requireWriteHook) {
+    let writeRequest = null;
+    if (args.requireWriteHook) {
+      writeRequest = validateHardWriteRequest({
+        root: args.root,
+        host: args.requireWriteHook,
+        tools: [args.requireWriteHook],
+        force: true,
+      });
+      if (!writeRequest.ok) {
+        const payload = {
+          ok: false,
+          error: 'unsupported-enforcement-profile',
+          message: writeRequest.error,
+        };
+        if (args.json) console.log(JSON.stringify(payload, null, 2));
+        else console.error(writeRequest.error);
+        process.exitCode = 2;
+        return;
+      }
+    }
+
+    const missing = args.requireGates ? missingGates(args.root) : [];
+    if (
+      writeRequest?.host &&
+      !detectWritePathCapabilities(args.root, writeRequest.host).capabilities['hard-write']
+    ) {
+      missing.push(`${writeRequest.host} hard-write hook`);
     }
     if (missing.length > 0) {
       const payload = {
         ok: false,
         error: 'missing-gates',
         missing,
+        ...(writeRequest?.host ? { writeHost: writeRequest.host } : {}),
       };
       if (args.json) {
         console.log(JSON.stringify(payload, null, 2));
@@ -994,7 +1022,12 @@ async function main() {
         for (const relativePath of missing) {
           console.error(`  - ${relativePath}`);
         }
-        console.error(`\nRun \`${arkCommand(args.root, 'ark', 'init')}\` (or \`ark-check --install-agent-gates\`) to configure enforcement.`);
+        const installArgs = writeRequest?.host
+          ? `--install-agent-gates --tools ${writeRequest.host} --require-write-hook ${writeRequest.host}`
+          : '--install-agent-gates';
+        console.error(
+          `\nRun \`${arkCommand(args.root, 'ark', 'init')}\` (or \`${arkCommand(args.root, 'ark-check', installArgs)}\`) to configure enforcement.`
+        );
       }
       process.exitCode = 1;
       return;
@@ -1004,7 +1037,12 @@ async function main() {
     // When --require-gates is the only intent (no config/architecture run needed),
     // callers still get a clear signal from the exit code and the human-mode line.
     if (!args.json) {
-      console.log('Ark gates present: ' + REQUIRED_GATE_FILES.join(', '));
+      if (args.requireGates) {
+        console.log('Ark gates present (merge profile): ' + REQUIRED_GATE_FILES.join(', '));
+      }
+      if (writeRequest?.host) {
+        console.log(`Ark hard-write hook present for ${writeRequest.host}.`);
+      }
     }
   }
 
@@ -1277,6 +1315,18 @@ async function main() {
         }
       }
     }
+
+    // Best-effort: open the report in the default browser. If it opens, fine;
+    // if not (headless, no GUI, spawn error), do nothing — never fail the check.
+    // Skipped in CI / Vitest / ARK_NO_OPEN_REPORT; --open / --no-open override.
+    if (
+      shouldOpenHtmlReport({
+        force: Boolean(args.openReport),
+        noOpen: Boolean(args.noOpenReport) || Boolean(args.json),
+      })
+    ) {
+      openHtmlInBrowser(reportPath);
+    }
   }
 
   if (args.json) {
@@ -1385,10 +1435,19 @@ async function main() {
       const parts = [];
       if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);
       if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} outdated`);
+      // Advisory always; when session host is known and not Codex, say so so
+      // /ark-upgrade does not chase home prompts as Incomplete.
+      const activeHost = detectActiveAgentHost();
+      const deferredNote =
+        activeHost != null && activeHost !== 'codex'
+          ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
+          : ' ';
       console.log(
         color.dim(
-          `/ark-* skills in ${codexPromptsDir()} are behind this Ark (${parts.join(', ')}). ` +
-            `Codex loads them from there, not the repo. Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`
+          `/ark-* skills in ${codexPromptsDir()} are behind this Ark (${parts.join(', ')}).` +
+            deferredNote +
+            `Codex loads them from $CODEX_HOME/prompts, not the repo. ` +
+            `When using Codex: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`
         )
       );
     }

package/bin/ark-mcp.mjs

@@ -58,6 +58,7 @@ import {
 import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
+import { loadArkConfigContract } from './lib/config-contract.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 
@@ -120,6 +121,11 @@ function readJson(file, { required } = {}) {
   }
 }
 
+function readArkConfig(file, { required } = {}) {
+  const raw = readJson(file, { required });
+  return raw === undefined ? undefined : loadArkConfigContract(raw, file).config;
+}
+
 function resolveInRoot(root, maybePath) {
   if (!maybePath) return undefined;
   return path.isAbsolute(maybePath) ? maybePath : path.join(root, maybePath);
@@ -460,11 +466,11 @@ async function main() {
   const ts = await loadOptionalTypeScript();
 
   const config =
-    (configPath ? readJson(configPath, { required: args.configExplicit }) : undefined) ?? {
-      include: ['src'],
-      layers: [],
-      rules: [],
-    };
+    (configPath ? readArkConfig(configPath, { required: args.configExplicit }) : undefined) ??
+    loadArkConfigContract(
+      { include: ['src'], layers: [], rules: DEFAULT_RULES },
+      configPath ?? 'ark.config.json'
+    ).config;
   if (!config.layers || config.layers.length === 0) {
     process.stderr.write(
       '[ark-mcp] warning: no layers configured — file→layer inference from config patterns ' +