arkgate 4.1.1 → 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/) · latest: [enforcement-evidence-and-docs-truth](plans/enforcement-evidence-and-docs-truth/README.md) (Phase EH shipped; 4.1.1 prepared) |
+| 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.1.0.md](releases/4.1.0.md) (`arkgate@4.1.0` on npm `latest`).  
-Prepared next: [releases/4.1.1.md](releases/4.1.1.md) (Phase EH — **Status: prepared**, not on npm until publish).  
+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).
 

package/docs/agent-guide.md

@@ -46,6 +46,13 @@ status context name. Never claim Cursor/Codex/OpenCode hard write. Soft-write al
 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`
 
 Before generating project structure, agents should read the **tool-agnostic application
@@ -112,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
@@ -130,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
@@ -145,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
@@ -456,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` |
@@ -464,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:
@@ -846,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. |
@@ -864,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:
+
+```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
+}
+```
 
-Current diagnostic envelopes use schema `1.3` and require `mode`,
+`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`,
@@ -875,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
@@ -887,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"
           }
         ]
       }
@@ -896,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
 {
@@ -910,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
@@ -330,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.
@@ -359,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 —
@@ -381,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

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/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.
 

package/docs/package-surface.md

@@ -16,9 +16,9 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
-| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. In 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. |
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
-| **Doctor design fitness (P02+)** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. Y02 extends `handler-in-persistence` to static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so **absence of a smell is not full-tree proof** above that envelope (incomplete/`partial` analysis also never proves “no smells”). Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`** (Q02). Does **not** fail the gate by itself. |
+| **Doctor design fitness (P02+)** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. Y02 extends `handler-in-persistence` to static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so **absence of a smell is not full-tree proof** above that envelope (incomplete/`partial` analysis also never proves “no smells”). **4.2 feedback hardening:** mode labels preserve the observed SUGGEST/ADAPT/ENFORCE state; a local permission/UI-state `canEdit` name alone is not a domain smell; real UI business rules route Domain → Application → UI; seed/fixture/demo/migration/generated files are not god-module pilots. Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`** (Q02). Does **not** fail the gate by itself. |
 | **Post-green path (Q01)** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. |
 | **Golden pattern (Q03)** | Optional `.ark/golden-pattern.json`; doctor JSON `doctor.goldenPattern`; MCP `ark_place` / `ark_prepare_write` → `goldenPattern` | Additive, **advisory for NEW code only**. Required fields: `name`, `norm`; optional `newCodeHome`, `examplePath`, `schemaVersion`. **Absent is normal** (no claim). Never ENFORCE; never clears design-weak. Malformed → `invalid: true`, not silent guidance. |
 | **Plan pattern B (P03+)** | `ark-check --plan --json` → `plan.patternBets[]`, `plan.goal.designWeak` | Additive. Each bet: `id`, `smellId`, `pilot`, `evidence`, `successSignal`, `killSwitch`, **`neverMechanicalSafe: true`**, `class: "judgment"`. **Never** auto-applied by loop/autoPatch; not a `remediationKind` mechanical-safe. `goal.met` remains edge honesty only. |
@@ -32,10 +32,12 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Capability walls, every adapter (U04+U06)** | CLI scan, pure IR engine, atomic preflight, `ark-mcp --hook` / MCP gate (`capabilityWalls`), ESLint `ark/no-denied-capabilities` | The same opt-in deny set enforces across every surface: hook/MCP and CLI cover ambient + import evidence (symbol-aware); the pure engine, preflight, and ESLint cover the import dimension (documented envelope). Dual depth everywhere: plain port hint (`FIX_HINTS`/`suggestion`) + stable JSON (`ruleId`, `capability`, `fixClass: inject-port`, deterministic `nextAction`). |
 | **Hook-path budgets (U06)** | Repository-only evidence: `npm run bench:hook-path`; `eval/performance/hook-budgets.v1.json`; CI job "Hook-path end-to-end budgets" | Measures the COMPLETE pre-tool paths as fresh child processes (hook cold/warm, doctor cold) at 1k/10k. D5 method locked: ceilings are Linux-baseline p95 + fixed headroom, set once per cycle, never ratcheted; scenarios without a recorded baseline stay in RECORDING mode and cannot fail CI. |
 | **Governance weight (W02)** | `ark-check --doctor --json` → `doctor.contractHealth.governanceWeight` | Additive, **advisory only** — raw facts (`declaredLayers`, `populatedLayers`, `governedFiles`, `rules`, `deniedEdges`, `allowedEdges`, `filesPerLayer`, `rulesPerLayer`) plus a fixed comparative band `weight: heavy | typical | light | unknown` and its fixed `note`. Fixed deterministic thresholds: **heavy** = fewer than 25 governed files per declared layer AND (6+ layers OR 4+ well-formed rules per layer); **light** = at most 2 layers over 150+ governed files; **unknown** = no layers or no governed files; everything else is **typical** (banding uses raw ratios; the reported ratios are rounded for display). `notAScore: true` is explicit: never a composite score, ranking, or gate input; the heavy note asks to justify NEW layers/rules and never suggests deleting working ones. Human doctor prints a line only for `heavy`/`light`. |
-| **Report parity (X01)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth"`, nested `governanceWeight`) + layer wall badges | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. |
-| **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
+| **Report parity and snapshot evidence (X01/4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. |
+| **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
+| **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
 | **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`arkRules`** map (schema `1.1+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `arkRules` is byte-for-byte silent on inter-layer verdicts. |
-| **ArkRules inventory / under-contract (4.0)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. Structure/invariant diagnostics use adapter `1.4` provenance. |
+| **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
+| **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
 | **Product honesty readiness split (4.1.1 EH)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
 | **Policy transition analysis (T01, 3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
@@ -49,7 +51,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **`arkgate/schema/arkrules`** or **`arkgate/schema/ark.arkrules.schema.json`** | Per-layer structure sensors + invariant catalog (ADR 0012) | Schema `1.0`. Opt-in via root `arkRules` map (`ark.config` schema `1.1`). |
 | **`arkgate/schema/resolved-candidate-facts`** or **`arkgate/schema/ark.resolved-candidate-facts.schema.json`** | Versioned parity-capable input for `analyzeResolvedProject` / `preflightResolvedChange` | Schema `1.0` is serializable and deterministic. Tooling owns filesystem/compiler resolution; Domain/Kernel validate and evaluate supplied facts without importing those effects. Facts name resolver/compiler inputs, governed files, dependency evidence, completeness reasons, and candidate tree/facts hashes. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
-| **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) | **Day zero** is the compact router from `ark start` / `start --apply` + doctor control plane — not the full skill pack. Skill *names* and the guided expert path (`/ark-autopilot` after pack install) are stable; internal skill prose may evolve. **4.0:** all skills except experimental `/ark-runtime` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. |
+| **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) | **Day zero** is the compact router from `ark start` / `start --apply` + doctor control plane — not the full skill pack. Skill *names* and the guided expert path (`/ark-autopilot` after pack install) are stable; internal skill prose may evolve. **4.0:** all skills except experimental `/ark-runtime` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. **4.2:** repo catalogs are content-idempotent; the optional shared Codex home catalog is monotonic across 4.2.0+ installers. Pre-4.2 writers are outside that protocol and must be upgraded first. A durable pending-catalog journal preserves the floor across an interrupted install and is cleared only by its owning same/newer recovery. |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
 | **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 | **Package metadata** | `arkgate/package.json` | Stable resource subpath for tooling that needs the installed manifest. |
@@ -86,6 +88,7 @@ are grouped below.
 | Group | Exported runtime values |
 |-------|-------------------------|
 | Metadata and adapter diagnostics | `version`, `ARK_ANALYSIS_RESULT_SCHEMA_VERSION`, `ARK_ANALYSIS_RESULT_SCHEMA`, `createAdapterResult`, `toAdapterDiagnostic` |
+| MCP project identity | `ARK_PROJECT_IDENTITY_SCHEMA_VERSION`, `ARK_PROJECT_IDENTITY_SCHEMA_URL`, `ARK_PROJECT_IDENTITY_SCHEMA`, `PROJECT_EXPECTATION_SCHEMA`, `PROJECT_BINDING_SCHEMA`, `createProjectId`, `createProjectIdentity` |
 | AI snippet gate | `createAICodeGate` |
 | Profiles and config factories | `createArchitectureProfile`, `createArchitectureProfileFromArkConfig`, `createElevenLayerArkConfig`, `elevenLayerProfile` |
 | Analysis and preflight | `loadContract`, `analyzeResolvedProject`, `preflightResolvedChange`, lexical-compatibility `analyzeProject` / `analyzeChange` / `preflightChange`, `analyzePolicyDelta`, `analyzeArchitectureConvergence`, `explainViolation`, `evaluateArchitectureGraph`, `collectAnalysisConfigWarnings`, `detectArchitectureCycles`, `collectForbiddenCapabilityUses`, `extractSemanticDependencies` |
@@ -98,6 +101,7 @@ The type-only root exports are also semver-supported:
 
 - Adapter diagnostics: `AdapterDiagnostic`, `AdapterResult`, `AdapterSeverity`,
   `AdapterViolationInput`, `AdapterCompletenessReason`, `AnalysisCompleteness`, `AnalysisMode`.
+- MCP project identity: `ProjectIdentity`, `ProjectExpectation`, `ProjectBinding`.
 - Resolved facts: `ResolvedCandidateFacts`, `ResolvedCandidateFactsInput`, and their
   dependency/file/evidence component types.
 - AI snippet gate: `AICodeGate`, `AICodeGateResult`, `AICodeGateViolation`,
@@ -190,8 +194,9 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current published: [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md);
-prepared next: [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md);
-previous: [4.0.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.1.md),
+(prepared: [4.2.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.0.md);
+current published: [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md);
+previous: [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md),
+[4.0.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.1.md),
 [4.0.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.0.md)).
 Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](https://github.com/pedroknigge/arkgate/blob/main/CONTRIBUTING.md)).

package/docs/product-voice.md

@@ -22,7 +22,8 @@ because the design space is small and honest.
 - **Co-pilot side:** where code belongs, who talks to whom, how; dual plan **A** (edges) +
   **B** (shape); one pilot at a time; never silent judgment codemod; never weaken the contract.
 - **False done is forbidden:** Enforce ≠ elegant design. `design-weak` / residual must not
-  read as “healthy finished.” Empty ArkRules inventory is not a score.
+  read as “healthy finished.” Empty ArkRules inventory is not a score. MCP configuration on
+  disk is not proof that the current process belongs to this project.
 
 ---
 
@@ -73,6 +74,12 @@ Examples:
 | **compact router** | Default onboarding agent instructions (not the full skill pack) |
 | **hard write** | Non-bypassable PreToolUse block for listed ops (Claude/Grok when installed + trusted) |
 | **advisory write** | MCP/rules coach only (Cursor/Codex at write time) — not a hard block |
+| **project identity** | Stable canonical root + config identity returned by `ark_identity`; separate from contract and process identity |
+| **matched binding** | Live MCP answered for the exact project root, or for a contained descendant together with the matching project id; only this binding is authoritative |
+| **authoritative manifest** | Contract returned by `ark_manifest` after a matched identity handshake |
+| **compatibility manifest resource** | `ark://manifest` through standard `resources/read`; always unverified/non-authoritative because the request cannot portably carry a project expectation |
+| **configured on disk** | Host files name an Ark MCP command; says nothing about which process is currently running |
+| **runtime observed** | A live `ark_identity` response matched this workspace; never infer it from `.codex/config.toml` or hook files |
 | **required CI / status context** | Merge hard boundary when the repository makes the Ark job a **required GitHub status context** (CLI: `arkgate-check --strict-merge` / `ark-check --strict-merge`) |
 | **contract ready** | Project/layers/ArkRules honesty residual clear — not the same as “hard local write” |
 | **environment residual** | Permanent host/provider posture (e.g. soft-write Codex) kept in evidence without forcing global **Not finished** |
@@ -89,6 +96,8 @@ Examples:
 | Keep Suggest on start → doctor | New-here primary is finish `start`, not a competing recommend/architect curriculum |
 | Qualify edge-clean under design-weak | “None on checked edges … design residual remains. Not healthy finished.” |
 | Prefer fail-closed over fake hard | Incomplete analysis, unobserved hooks, and soft MCP never paint as hard green |
+| State project binding before verdict | “Ark MCP matched this workspace; `ark_manifest` evidence is authoritative.” Otherwise: “Ark MCP is configured, but runtime identity is unverified. Restart and call `ark_identity` with the exact project root.” |
+| Keep inventory claims evidence-bound | “Possible rule candidate in the configured Application layer.” A filename or technical constant alone is not Domain evidence. |
 | Honesty clear ≠ architecture healthy | `productHonesty.finished` means residual **architecture** honesty sensors are clear — not a green graph score. Open blocking violations, ADAPT/SUGGEST with debt, dual-truth pin, or design residual keep `unfinished: true`. Permanent soft-write alone does **not**. |
 | Separate CI runtime from provider policy | Successful CI run ≠ required status; GitHub Free plan 403 → `unavailable-plan`, not “CI never ran.” |
 
@@ -105,6 +114,9 @@ Examples:
 | “Healthy / done” while design-weak | False done |
 | “Honesty clear” as “architecture finished” | Honesty clear only means residual honesty sensors are quiet; graph/mode debt is separate |
 | “Not finished” solely because host is Codex/Cursor | Soft-write is environment residual; do not paint a green whole-tree project as unfinished architecture |
+| “MCP installed / active” because a config file exists | Say **configured on disk · runtime unverified** until `ark_identity` matches the expected root |
+| Treating an unverified legacy MCP call as authoritative | Compatibility is not proof; require `binding.status: "matched"` and `authoritative: true` |
+| “Handler means controller” / “every constant is a business rule” | ArkRules inventory uses configured layer context and suppresses narrow technical/test evidence; candidates remain prompts for judgment |
 | Conflating CLI name with required status | `ark-check` is the command; the hard boundary is the GitHub required **status context** |
 | “ArkRules prove business correctness” | They enforce *declared* structure/coverage evidence, not arbitrary logic or full semantic proof |
 | “Structure enforced = Domain extraction done” | Structure sensors are **heuristics**; extraction is judgment (`/ark-fix` / pilot) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,6 +21,8 @@
     "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
     "./schema/analysis-result": "./schemas/ark.analysis-result.schema.json",
     "./schema/ark.analysis-result.schema.json": "./schemas/ark.analysis-result.schema.json",
+    "./schema/project-identity": "./schemas/ark.project-identity.schema.json",
+    "./schema/ark.project-identity.schema.json": "./schemas/ark.project-identity.schema.json",
     "./schema/change-map": "./schemas/ark.change-map.schema.json",
     "./schema/ark.change-map.schema.json": "./schemas/ark.change-map.schema.json",
     "./schema/resolved-candidate-facts": "./schemas/ark.resolved-candidate-facts.schema.json",