arkgate 4.1.0 → 4.2.0

package/docs/README.md

@@ -52,13 +52,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/) |
+| Epic plans (seeded + shipped) | [plans/](plans/) · active: [workspace identity and activation truth](plans/workspace-identity-activation-truth/README.md) (`WI01`, 4.2.0 corrective minor) |
 | 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) |
 
-Current published: [releases/4.0.1.md](releases/4.0.1.md) (`arkgate@4.0.1` on npm `latest`).  
-Next prepared: [releases/4.1.0.md](releases/4.1.0.md) (`arkgate@4.1.0` — field product phases + CI PR slim; not published until registry).  
+Prepared candidate: [releases/4.2.0.md](releases/4.2.0.md) (`arkgate@4.2.0`, not published).
+
+Current published: [releases/4.1.1.md](releases/4.1.1.md) (`arkgate@4.1.1` on npm `latest`).  
+Previous: [releases/4.1.0.md](releases/4.1.0.md) (`arkgate@4.1.0`).  
 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).
 
@@ -68,5 +70,5 @@ Config: [configuration.md](configuration.md) · Agent skills dual-plane: [agent-
 
 1. **Audience first** — every page should be use, develop, or contribute.
 2. **One primary flow** — `start` → doctor → optional guided work.
-3. **Honest hardness** — host write guarantees differ; CI required status is the shared merge boundary.
+3. **Honest hardness** — host write guarantees differ; a **required GitHub status context** running the merge CLI is the shared hard boundary.
 4. **History is not the product** — version archaeology lives under `releases/` and `plans/`, not the front door.

package/docs/agent-guide.md

@@ -40,9 +40,18 @@ npx ark-check --install-agent-gates --skills-only --force
 
 **Write-path honesty:** Claude/Grok/Antigravity can hard-block listed PreToolUse ops when
 installed and trusted. Cursor/Codex/OpenCode remain **advisory at write**. For every host, the
-repository-wide hard boundary is a **required** CI status (`arkgate-check --strict-merge`) —
-never claim Cursor/Codex/OpenCode hard write. See [ai-gates.md](ai-gates.md) and the README host
-matrix.
+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 Cursor/Codex/OpenCode hard write. Soft-write alone does not mean
+the project is unfinished; doctor keeps it as an environment residual. See [ai-gates.md](ai-gates.md)
+and the README host matrix.
+
+**MCP project identity (4.2.0):** before trusting project-specific MCP evidence, call
+`ark_identity` with `project.expectedRoot` set to the exact project's absolute root. Reuse that
+root plus the returned `projectIdentity.projectId` on every later Ark tool call. A descendant
+path is authoritative only when that matching project id is also supplied. Only
+`binding.status: "matched"` with `authoritative: true` is authoritative; calls that omit the
+expectation remain compatible but are explicitly `unverified`.
 
 ## Architecture playbook and `ark-check --recommend`
 
@@ -110,6 +119,10 @@ baseline. Do not `--reset-origin` unless the user explicitly wants a new baselin
 `ark-check --report --no-archive` still creates `origin.*` on the first report (or on an explicit
 reset) and refreshes `latest.*`; it skips only the timestamped JSON file under
 `.ark/reports/history/`.
+Snapshots record best-effort, shell-free Git provenance (`HEAD`, attached branch, and dirty
+worktree state). Evolution keeps raw metrics visible across ArkGate upgrades, but an Ark score
+delta is comparable—and therefore rendered—only when origin and current snapshots use the same
+ArkGate version.
 
 Once the **raw** graph has zero violations (the baseline is deliberately ignored) and governed
 coverage is at least 50%, `ark-check --ratchet-cores` changes `optional: true` to
@@ -128,7 +141,9 @@ brownfield Align/Stabilize + seed Shape B. `/ark-loop` = plan A only. Empty plan
 “architecture healthy” if design-weak residual remains. Full routing table: full-install
 `AGENTS.md` / [README expert skills](../README.md#expert-skills-escapes--not-onboarding).
 
-**Design fitness (3.0.1+ / Phase Q 3.0.3):** after edges are clean, doctor can still report **ENFORCE · design-weak**.
+**Design fitness (3.0.1+ / Phase Q 3.0.3):** after checked edges are clean, doctor can still
+report **SUGGEST / ADAPT / ENFORCE · design-weak** using the mode it actually observed; a weak
+design does not imply that enforcement is active.
 
 ```bash
 npx ark-check --doctor --json   # designFitness, designSmells[].outcome, postGreenPath, goldenPattern, pilotLoop
@@ -143,7 +158,10 @@ npx ark-check --doctor --fail-on-new-smells --base-ref origin/main --json # opt-
 **Pilot loop (Q04):** when design-weak, `pilotLoop.nextPilot` is **one** extraction card
 (pilot target, move, success, kill-switch). Apply **that one pilot only**, then re-doctor.
 Success = reduced smell evidence on pilot paths; residual outside the pilot may remain.
-Never multi-pilot batch; never mechanical-safe; never claim healthy finished while design-weak.
+Never select seed/fixture/demo/migration/generated files as god-module pilots. A real UI business
+rule moves Domain → Application → UI; local permission/UI-state helpers are not selected by their
+`canEdit`-style name alone. Never multi-pilot batch; never mechanical-safe; never claim healthy
+finished while design-weak.
 
 **AI-velocity evidence (Q05):** deterministic fixture bench (no live LLM) compares the same
 feature add on design-weak vs golden-path trees. Run `npm run eval:ai-velocity`; metric is
@@ -454,7 +472,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 |------|-----------------|-------------|
 | Claude Code | `.claude/settings.json` hook + `.mcp.json` / `claude mcp add` | `.claude/skills/<name>/SKILL.md` |
 | Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | `.cursor/commands/` |
-| OpenAI Codex | `.codex/config.toml` (project primary, relative `--root .`); optional legacy `$CODEX_HOME/config.toml` fallback uses absolute roots and scoped secondaries — see [ai-gates.md](ai-gates.md) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$CODEX_HOME/skills/<name>/SKILL.md` (`--codex-home`) |
+| OpenAI Codex | `.codex/config.toml` (project primary, relative `--root .`; configured on disk is not runtime-active until restart + `ark_identity` match); optional legacy `$CODEX_HOME/config.toml` fallback uses absolute roots and scoped secondaries — see [ai-gates.md](ai-gates.md) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$CODEX_HOME/skills/<name>/SKILL.md` (`--codex-home`) |
 | **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | `.grok/skills/<name>/SKILL.md` |
 | Google Antigravity | `.agents/hooks.json` (+ `GEMINI.md` for shared Gemini consumers) | `.agents/skills/<name>/SKILL.md` |
 | OpenCode | `opencode.json` MCP (`type: local`; advisory) | `.opencode/skills/<name>/SKILL.md` |
@@ -462,6 +480,11 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 This is a path reference, not a guarantee table. Full copy-paste setups:
 [ai-gates.md](ai-gates.md). Skill inventory: main
 [README](../README.md#other-skills-only-when-you-need-them).
+When several repositories share one machine, repo catalogs stay pinned and isolated; unchanged
+skill bodies are not rewritten for a version stamp. The optional `$CODEX_HOME/skills` catalog is
+monotonic across ArkGate 4.2.0+ installers. Pre-4.2 binaries ignore its metadata and lock, so
+upgrade legacy repos before they write the optional home catalog. See
+[AI gates — Codex skill catalog](ai-gates.md#codex-skill-catalog-skillmd-not-flat-prompts).
 
 For an optional executable adoption check, copy the shipped template into a Vitest/Jest suite
 after installing ArkGate:
@@ -844,17 +867,41 @@ required, and `behavioralCompletion` remains `not-evaluated` even when structure
 npx ark-mcp --root . --config ark.config.json [--manifest ark.manifest.json]
 ```
 
-- **Resource `ark://manifest`** — contract discovery. Serve an exported
-  `ark.manifest().toJSON()` via `--manifest`. Without that flag, the resource uses every active
-  layer and the effective rules from `ark.config.json`; the strict 11-layer profile is the
-  fallback only when the project config declares no layers.
+- **Identity handshake** — first call `ark_identity` with:
 
-The server exposes these nine tools:
+  ```json
+  {
+    "project": {
+      "expectedRoot": "/absolute/exact-project-root"
+    }
+  }
+  ```
+
+  Then reuse both `expectedRoot` and the returned `projectIdentity.projectId` as
+  `project.expectedProjectId` on every later Ark tool call. `expectedProjectId` without
+  `expectedRoot` can detect the wrong id, but it remains non-authoritative because it does not
+  prove the current workspace root. The first handshake requires the exact project root; a
+  contained descendant becomes authoritative only on later calls that also send the matching
+  project id.
+- **Tool `ark_manifest`** — authoritative contract discovery after the identity handshake.
+  Serve an exported `ark.manifest().toJSON()` via `--manifest`. Without that flag, the tool uses
+  every active layer and the effective rules from `ark.config.json`; the strict 11-layer profile
+  is the fallback only when the project config declares no layers. Call it with the same root +
+  project id expectation.
+- **Resource `ark://manifest`** — compatibility discovery for standard MCP `resources/read`
+  clients. That protocol request has no portable project-expectation field, so Ark always marks
+  this resource `unverified` and non-authoritative. It never substitutes for `ark_manifest` in
+  a project verdict.
+
+The server exposes these twelve tools. Every tool accepts the additive
+`project: { expectedRoot, expectedProjectId? }` input:
 
 | Tool | Primary input and purpose |
 |------|---------------------------|
+| `ark_identity` | `{ project: { expectedRoot, expectedProjectId? } }`: return the canonical root/config, stable project id, contract identity, and live runtime identity; use it before every other project-bound surface. |
+| `ark_manifest` | No non-project args: return the machine-readable architecture contract with an authoritative binding after the identity handshake. |
 | `validate_code` | `{ source, layer?, filePath? }`: validate one snippet; infer the layer from `filePath` when possible; return an error result when invalid. |
-| `ark_check` | `{ strict?, baseline? }`: run the full project architecture check with structured diagnostics. |
+| `ark_check` | `{ strict?, baseline? }`: run the full project architecture check. `verdict` separates `identity`, `completeness`, `graph`, `coverage`, `gates`, and `overallOk`; no individual green fact substitutes for the combined verdict. |
 | `ark_policy_delta` | `{ baseConfig, candidateConfig?, acknowledgement? }`: classify a complete contract transition; never edits the contract. |
 | `ark_coverage` | No args: report per-layer counts, every unclassified file, unmatched layers, and missing rule edges. |
 | `ark_place` | `{ filePath?, description? }`: resolve or propose a governed home and return its import/global constraints. |
@@ -862,8 +909,55 @@ The server exposes these nine tools:
 | `ark_prepare_change` | `{ changes, changeMap? }`: preflight one complete create/update/delete batch in memory; never writes files. |
 | `ark_recommend` | No args: return the deterministic application-shape plan used by `ark-check --recommend --json`. |
 | `ark_suggest_include` | No args: propose TypeScript/JavaScript include roots from workspaces and nested packages. |
+| `ark_rules_inventory` | No args: inventory possible intra-layer rules using configured layer evidence when available; test/fixture/seed/migration surfaces and narrow technical constants are excluded from extraction pilots. Counts are not a score. |
+
+Every project-bound tool success, tool error, and JSON-RPC error data carries:
 
-Current diagnostic envelopes use schema `1.3` and require `mode`,
+```json
+{
+  "projectIdentity": {
+    "schemaVersion": "1.0",
+    "projectId": "sha256:…",
+    "resolvedRoot": "/absolute/project",
+    "resolvedConfigPath": "/absolute/project/ark.config.json",
+    "arkgateVersion": "4.2.0",
+    "contractHash": "sha256:…",
+    "contractSource": "project",
+    "runtimeId": "process-specific",
+    "processStartedAt": "2026-07-30T00:00:00.000Z"
+  },
+  "binding": {
+    "status": "matched",
+    "authoritative": true
+  },
+  "authoritative": true
+}
+```
+
+`projectId` stays stable across process restarts and contract edits; `runtimeId` and
+`processStartedAt` identify this live process. Binding states are:
+
+- `matched` — canonical `expectedRoot` is the exact project root, or it is a contained
+  descendant and the caller also supplied the matching project id; `authoritative` is `true`;
+- `unverified` — no expectation was supplied, or only the id matched; callable for legacy
+  clients, but `authoritative` is `false`;
+- `mismatch` — invalid/wrong root or id; `authoritative` is `false` and Ark returns
+  `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, or `INVALID_PROJECT_EXPECTATION`.
+
+Roots, configs, manifests, TypeScript configs, and project-bound tool paths are canonicalized
+through real paths. A config or file path outside the bound project fails before Ark returns
+placement, golden-pattern, Layers, or ArkRules evidence. The MCP process never retargets itself
+from tool input; disjoint projects need disjoint processes. The compatibility `ark://manifest`
+resource also carries the identity envelope, but its binding is always `unverified` and
+non-authoritative.
+
+For `ark_check`, treat `verdict.overallOk` as the combined control-plane fact. It can be true only
+when the binding is matched, analysis is complete, the graph is valid, coverage is complete
+(non-empty, 100% governed, zero unclassified files), and both local-write and CI-merge gate state
+are active. The underlying CLI fields remain present for diagnosis, but are not an authoritative
+whole-project green on their own.
+
+Current diagnostic envelopes use schema `1.4` and require `mode`,
 `completeness: "complete" | "partial" | "unavailable"`, and structured
 `completenessReasons`. Resolved results expose `policyHash`, `resolverIdentity`, `factsHash`, and
 `candidateTreeHash`; MCP `ark_check` mirrors CLI `ok`. Single-file `validate_code`,
@@ -873,7 +967,9 @@ preflight. Consumer-owned 1.0/1.1/1.2 `AdapterResult` values remain accepted by
 
 For hook-based enforcement, `ark-mcp --hook` runs one-shot: it reads a PreToolUse payload
 from stdin, validates the post-edit file content, and exits `2` with violations on stderr
-to block the write (`0` to allow). Working Claude Code configuration
+to block the write (`0` to allow). `--root-env` accepts a prioritized comma-separated
+environment-variable list; ArkGate uses the first populated value and otherwise keeps
+the explicit `--root` fallback. Working Claude Code configuration
 (`.claude/settings.json`):
 
 ```json
@@ -885,7 +981,7 @@ to block the write (`0` to allow). Working Claude Code configuration
         "hooks": [
           {
             "type": "command",
-            "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\""
+            "command": "npx ark-mcp --hook --root . --root-env CLAUDE_PROJECT_DIR"
           }
         ]
       }
@@ -894,8 +990,8 @@ to block the write (`0` to allow). Working Claude Code configuration
 }
 ```
 
-Register the server itself in `.mcp.json` so the agent can read `ark://manifest` and call
-`validate_code` on demand:
+Register the server itself in `.mcp.json` so the agent can handshake with `ark_identity`, call
+`ark_manifest`, and use `validate_code` on demand:
 
 ```json
 {
@@ -908,6 +1004,8 @@ Register the server itself in `.mcp.json` so the agent can read `ark://manifest`
 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.
 
+Decision rationale: [ADR 0017 — MCP verdicts require explicit project identity](adr/0017-mcp-project-identity-binding.md).
+
 ## Experimental runtime kernel workflow (not the default path)
 
 This section is for adopters who **opt into** the experimental `@arkgate/runtime` / kernel surfaces.

package/docs/ai-gates.md

@@ -85,9 +85,12 @@ supported smells on touched paths. Companion plan JSON: `plan.patternBets[]` wit
 [package-surface.md](package-surface.md) and [brownfield-adoption.md](brownfield-adoption.md) §6.
 
 If your project uses Codex or Grok, treat MCP registration as part of the default
-setup, not an optional extra. Ark works best when the agent can read `ark://manifest`
+setup, not an optional extra. Ark works best when the agent can call `ark_manifest`
 before it writes code; that is the fast path to avoiding architecture drift during
-generation.
+generation. Registration on disk is not runtime proof: after the host starts the server, call
+`ark_identity` with `project.expectedRoot` set to the exact project's absolute root and require
+a `matched`, authoritative binding. Then call `ark_manifest` with that root plus the returned
+project id before using project evidence.
 
 ## Claude Code — hook (recommended, hard block)
 
@@ -158,7 +161,7 @@ Add to your project's `.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "npx ark-mcp --hook --hook-repair --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+            "command": "npx ark-mcp --hook --hook-repair --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json"
           }
         ]
       }
@@ -173,7 +176,7 @@ That's the whole setup. Try asking the agent to import a persistence adapter fro
 Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainModel):
 - [FORBIDDEN_PATTERN] Forbidden pattern matched: /from ['"].*\/(infra|adapters|persistence|db)/i (line 1)
 - [FORBIDDEN_IMPORT] Forbidden import target: "../adapters/persistence/pg-order-repository". (line 1)
-Fix the violations and retry. The architecture contract is available as the ark://manifest MCP resource.
+Fix the violations and retry. After ark_identity matches, call ark_manifest with the same project expectation for the authoritative contract.
 ```
 
 ## Claude Code — SessionStart context injection (know the rules before the first token)
@@ -191,7 +194,7 @@ injects into the agent's context at session start:
         "hooks": [
           {
             "type": "command",
-            "command": "npx ark-mcp --session-context --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+            "command": "npx ark-mcp --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json"
           }
         ]
       }
@@ -207,7 +210,7 @@ Ark architecture contract governs this project (ark.config.json is authoritative
 Layers:
   - DomainModel: src/domain/** — forbidden globals: fetch, process, Date.now, Math.random
   - PersistenceAdapters: src/adapters/persistence/**
-Rules: 10 denied layer edge(s). Full contract: ark://manifest MCP resource.
+Rules: 10 denied layer edge(s). Full authoritative contract: ark_manifest after ark_identity.
 Baseline: 3 frozen violation(s) — only NEW violations fail; do not add to them.
 After edits run: npx ark-check --root . --config ark.config.json --strict
 ```
@@ -219,9 +222,20 @@ prints nothing and exits 0, so non-Ark projects are untouched.
 
 ## Claude Code — MCP server (contract discovery + on-demand validation)
 
-The MCP server exposes a resource and tools agents can use proactively (not an exhaustive list — `tools/list` is authoritative):
-
-- **`ark://manifest`** (resource) — the machine-readable architecture contract (layers + rules), so the agent can read the architecture before generating code.
+The MCP server exposes tools plus one compatibility resource that agents can use proactively
+(not an exhaustive list — `tools/list` is authoritative):
+
+- **`ark_identity`** (tool) — returns the canonical project/config identity and this live MCP
+  runtime identity. Call it first with
+  `{ "project": { "expectedRoot": "/absolute/exact-project-root" } }`, then reuse the same root
+  and returned `projectIdentity.projectId` as `project.expectedProjectId` on later calls. A
+  descendant path is authoritative only when that matching id is also supplied.
+- **`ark_manifest`** (tool) — returns the authoritative machine-readable architecture contract
+  (layers + rules) after the identity handshake. Call it with the same project expectation before
+  generating code.
+- **`ark://manifest`** (resource) — compatibility-only discovery for standard MCP
+  `resources/read`. Because that request has no portable project-expectation field, this resource
+  is always `unverified` and non-authoritative.
 - **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate). May return additive **`autoPatch`** (W1) for mechanical-safe import-type rewrites.
 - **`ark_prepare_write`** (tool) — **W2:** place + constrain + validate + optional autoPatch + judgmentBrief + contentHash in one call (composes `ark_place` + write gate).
 - **`ark_prepare_change`** (tool) — **T02–T05:** read-only atomic create/update/delete preflight with cross-file edge/cycle findings and candidate fingerprints. Optional `changeMap` accepts strict schema `1.0` intent and returns its hash plus satisfied/missing/contradictory/unplanned structural convergence; behavioral completion is not evaluated. Omission is supported. MCP registration remains advisory unless the host makes invocation non-bypassable.
@@ -235,7 +249,20 @@ The MCP server exposes a resource and tools agents can use proactively (not an e
 - **`ark_check`** (tool) — runs the full architecture check and returns structured violations (applies the baseline automatically when one exists).
 - **`ark_coverage`** (tool) — per-layer file counts, the full unclassified-file list, and layers whose patterns match nothing.
 
-Tools appear in the agent's tool list automatically — no skill or doc-reading needed — so the agent can query the contract instead of shelling out and parsing.
+Every Ark tool accepts the additive `project` expectation. Project-bound tool successes and
+errors carry `projectIdentity`, `binding`, and `authoritative`. A legacy call with no expectation
+stays callable but returns `binding.status: "unverified"` and `authoritative: false`; a wrong
+root/id returns a mismatch before project evidence. Absolute project paths and
+config/manifest/tsconfig inputs are real-path contained inside the server root. The process never
+switches projects from input. The compatibility resource carries the same identity envelope but
+is always unverified/non-authoritative.
+
+`ark_check.verdict` keeps `identity`, `completeness`, `graph`, `coverage`, and `gates` separate.
+Only `overallOk` combines them; a graph-clean result cannot paint an unverified binding,
+incomplete analysis, empty/partial coverage, or inactive gates green.
+
+Tools appear in the agent's tool list automatically — no skill or doc-reading needed — so the
+agent can query the contract instead of shelling out and parsing.
 
 ```bash
 claude mcp add ark -- npx ark-mcp --root . --config ark.config.json
@@ -283,7 +310,8 @@ alwaysApply: true
 Before writing or editing any TypeScript source file, call the `validate_code`
 tool from the `ark` MCP server with the full post-edit file content and its
 path. If it reports violations, fix them before writing. The architecture
-contract is available as the `ark://manifest` resource.
+contract is available authoritatively from `ark_manifest` after `ark_identity`
+matches. `ark://manifest` is compatibility-only and always unverified.
 ```
 
 Your repository backstop in Cursor is CI: `ark-check` fails its check on anything that slips
@@ -295,8 +323,9 @@ Recommended for Ark projects.
 
 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 root uses
-`${CODEX_PROJECT_DIR:-${PWD:-.}}`; it must not use Claude-only `CLAUDE_PROJECT_DIR`.
+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
@@ -307,8 +336,10 @@ required CI status is the hard repository boundary.
 npx ark-check --install-agent-gates --tools codex
 ```
 
-The generated hook includes `--hook-repair`, so a rejected patch carries the same structured
-repair envelope as Claude and Grok. Codex still needs hook trust enabled for the project.
+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.
 
 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
@@ -328,8 +359,45 @@ command = "npx"
 args = ["arkgate-mcp", "--root", ".", "--config", "ark.config.json"]
 ```
 
-Then **restart Codex** — it does not hot-load MCP servers. Expect resource `ark://manifest`
-and tools `validate_code`, `ark_check`, `ark_coverage`, `ark_place`.
+This file means **configured on disk**, not active. Install and compact
+`ark start --tools codex --json` therefore report the setup-time state explicitly:
+
+```json
+{
+  "runtimeActivation": {
+    "configuredOnDisk": true,
+    "restartRequired": true,
+    "runtimeObserved": false,
+    "identityMatch": "unverified",
+    "active": false
+  }
+}
+```
+
+Then **restart Codex** — it does not hot-load MCP servers — and call:
+
+```json
+{
+  "tool": "ark_identity",
+  "arguments": {
+    "project": {
+      "expectedRoot": "/absolute/exact-project-root"
+    }
+  }
+}
+```
+
+The live response must say `binding.status: "matched"` and `authoritative: true`. Reuse its
+`projectIdentity.projectId` with the same root on every subsequent Ark call, starting with
+`ark_manifest`. A missing `ark_identity` or `ark_manifest` means the process is from an older
+ArkGate build; restart the host and use the workspace-local CLI until the new server answers. A
+mismatch means Codex is connected to another project's process; do not use its contract,
+placement, Layers, ArkRules, or check evidence.
+
+Setup-time `runtimeActivation` remains intentionally conservative: the installer/doctor cannot
+observe a later MCP conversation from files alone. The matched `ark_identity` response is the
+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.
@@ -357,9 +425,11 @@ writes a scoped secondary table:
 | Doctor: primary points at another permanent project | gap id `codex-home-multi-project` (warn if no secondary yet and session host is unknown/Codex; **info + `deferred`** when the session host is known and not Codex — e.g. Grok/Claude/Cursor; info if a scoped secondary is already present) |
 | When using Codex: refresh home skills | `ark-check --install-agent-gates --skills-only --codex-home --force` |
 
-When a valid project `.codex/config.toml` exists, doctor treats it as the effective binding and
-does not report an unrelated home primary. Without a project binding, doctor surfaces the
-legacy multi-project state. **Deferred (fix when using Codex):**
+When a valid project `.codex/config.toml` exists, it is the expected binding, but files alone
+cannot prove which already-running process answered. Doctor therefore keeps an unrelated home
+primary as collision evidence until the live `ark_identity` matches; it does not label that home
+entry as the active project. Without a project binding, doctor surfaces the legacy multi-project
+state directly. **Deferred (fix when using Codex):**
 non-temp Codex-home gaps (`codex-home-multi-project`, stale `$CODEX_HOME/skills`) are
 severity **info**, marked `deferred: true`, and omitted from doctor **Primary next action** /
 **Also** list (formerly “Top actions”) when the session host is known and not Codex —
@@ -379,6 +449,23 @@ Flat `.codex/prompts/*.md` files are **not** the invocable skill catalog. Instal
 repo catalog above so AGENTS.md `/ark-*` references match what Codex can load. After install,
 Ark verifies those references against each selected host catalog.
 
+**Several repos on one machine:** repo catalogs are independent and follow each repository's
+locally installed ArkGate package. A managed upgrade rewrites a repo skill only when its normalized
+body changes; a package-version stamp alone is a no-op. The optional home catalog is shared, so
+ArkGate 4.2.0+ installation is monotonic there: an older bundled source cannot replace a newer
+managed home skill, even with `--force`. A pre-4.2 binary ignores the catalog/lock protocol and
+can still overwrite those files, so upgrade every legacy repo before it runs `--codex-home`
+(especially with `--force`). Identical content is idempotent, and preserved customization still
+follows the explicit force contract. The shared skill only routes the workflow; project evidence remains
+bound to the repo through `ark_identity`. Ark records the shared catalog in
+`$CODEX_HOME/skills/.arkgate-catalog.json`, writes a durable
+`.arkgate-catalog.pending.json` floor before mutations, and serializes concurrent installs.
+Doctor suppresses home refresh gaps only when the maximum valid committed/pending floor is newer
+than the repo package; an equal pending version remains actionable for recovery, and corrupt
+metadata never counts as a floor. When a newer package retires a skill, Ark removes it only if the
+bytes still match the prior managed identity; customized retired content is preserved and
+released from Ark ownership.
+
 **Parity & honesty (doctor / install):**
 
 - Doctor distinguishes **missing / stale / legacy-prompts-only** for repo (`.agents/skills`) and
@@ -387,7 +474,7 @@ Ark verifies those references against each selected host catalog.
   `--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`) plus a required status check.
+  The hard merge backstop is 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`.
 
@@ -591,13 +678,34 @@ for standalone linting where no project contract applies.
 Whatever the agent side does, run the merge profile in CI:
 
 ```yaml
-- run: npx ark-check --root . --config ark.config.json --strict-merge --fail-on-new-smells --base-ref "${{ github.event.pull_request.base.sha || github.event.before }}"
+# EH04: first push may have all-zero github.event.before — only pass --base-ref when resolvable.
+- name: Ark architecture check
+  env:
+    ARK_POLICY_BASE_REF: ${{ github.event.pull_request.base.sha || github.event.before }}
+  run: |
+    set -euo pipefail
+    BASE_REF="${ARK_POLICY_BASE_REF:-}"
+    if [[ "$BASE_REF" =~ ^0{40,64}$ ]]; then BASE_REF=""; fi
+    if [ -n "$BASE_REF" ] && git cat-file -e "${BASE_REF}^{commit}" 2>/dev/null; then
+      export ARK_POLICY_BASE_REF="$BASE_REF"
+      npx ark-check --root . --config ark.config.json --strict-merge \
+        --fail-on-new-smells --base-ref "$BASE_REF"
+    else
+      export ARK_POLICY_BASE_REF=""
+      npx ark-check --root . --config ark.config.json --strict-merge
+    fi
 ```
 
 This explicit brownfield ratchet records schema `1.0` identities, touched paths, and stable
-evidence; missing base exits `2`. Its first semantic smell is `domain-logic-in-ui`; residual,
-path-only moves, and unrelated work stay green. Generated Claude/Grok hooks share the delta and
-golden-pattern repair hint. MCP exposes the result but stays advisory.
+evidence; missing base with `--fail-on-new-smells` exits `2`, so the generated workflow skips the
+delta when the SHA is all-zero or unresolvable while keeping the full merge gate. Its first
+semantic smell is `domain-logic-in-ui`; residual, path-only moves, and unrelated work stay green.
+Generated Claude/Grok hooks share the delta and golden-pattern repair hint. MCP exposes the result
+but stays advisory.
+
+**CLI vs required status:** `arkgate-check --strict-merge` / `ark-check --strict-merge` is the
+**command**. The hard merge boundary is making that job a **required GitHub status context** —
+not “workflow file present.”
 
 Or use the repository's composite Action at a pinned release or commit:
 

package/docs/assets/ark-write-gate.svg

@@ -17,8 +17,8 @@
 
     <text x="24" y="152" fill="#f85149" font-weight="bold">✗ Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainModel):</text>
     <text x="40" y="174" fill="#f85149">- [FORBIDDEN_IMPORT] Forbidden import target: "../adapters/persistence/pg-order-repository".</text>
-    <text x="24" y="196" fill="#8b949e">Fix the violations and retry. The architecture contract is available as the</text>
-    <text x="24" y="214" fill="#8b949e">ark://manifest MCP resource.</text>
+    <text x="24" y="196" fill="#8b949e">Fix the violations and retry. The architecture contract is available through</text>
+    <text x="24" y="214" fill="#8b949e">the project-bound ark_manifest MCP tool.</text>
 
     <text x="24" y="248" fill="#c9d1d9">● The domain layer can't import persistence adapters. I'll define the port in the</text>
     <text x="24" y="266" fill="#c9d1d9">domain instead and implement it in src/adapters/persistence/.</text>

package/docs/develop.md

@@ -14,14 +14,18 @@ npx arkgate start --apply
 npx arkgate-check --doctor
 ```
 
-Make the architecture check a **required** merge status (GitHub/GitLab/etc.):
+Make the architecture check a **required** merge **status context** (GitHub/GitLab/etc.). The CLI
+command is `arkgate-check --strict-merge` / `ark-check --strict-merge` — the hard boundary is
+requiring that job’s status, not merely adding a workflow file:
 
 ```yaml
 - run: npx arkgate-check --root . --config ark.config.json --strict-merge
 # or: uses: pedroknigge/arkgate@<tag-or-SHA>
 ```
 
-`--strict-merge` (or compatibility `--strict`) is the repository-wide hard boundary for every agent host.
+Generated workflows also gate `--fail-on-new-smells --base-ref` so a first push with an all-zero
+`github.event.before` still runs the full merge gate without a broken delta (see
+[ai-gates.md](ai-gates.md#ci-backstop)).
 
 ---
 
@@ -31,9 +35,9 @@ Local write hardness **differs by host**. CI required status is the shared hard
 
 | Host | Local write | MCP | Merge |
 |------|-------------|-----|-------|
-| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status |
-| Codex · OpenCode | Best-effort / advisory | Advisory | Required status |
-| Cursor | Advisory only | Advisory | Required status |
+| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status context |
+| Codex · OpenCode | Best-effort / advisory | Advisory | Required status context |
+| Cursor | Advisory only | Advisory | Required status context |
 
 Full matrix and install commands: [ai-gates.md](ai-gates.md) · canonical table in [README](../README.md#host-enforcement-support).
 
@@ -46,7 +50,13 @@ npx arkgate-check --install-agent-gates --tools opencode
 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.
+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.
+
+**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
+can show `runtimeObserved: true` even when branch-protection policy is plan-unavailable
+(`unavailable-plan` on GitHub Free private); `hard: false` until the status is required.
 
 ---
 

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

@@ -42,6 +42,12 @@ npx arkgate-check --doctor
 npx arkgate-check --require-gates
 ```
 
+`--require-gates` implies strict config validation. It verifies content, not filenames alone:
+`AGENTS.md` must contain the Ark contract and strict check, MCP registration must launch one Ark
+server with an explicit project root, compact Codex must contain valid project config plus
+SessionStart/PreToolUse Ark hooks, and CI must execute a fail-closed Ark command. Included but
+unclassified source files therefore remain red.
+
 Doctor JSON includes `writePath.mode` plus `enforcementLadder`: support, installation, observed
 evidence, covered operations, bypassability, and CI honesty. MCP registration stays advisory.