arkgate 4.1.1 → 4.2.0

package/CHANGELOG.md

@@ -5,13 +5,91 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
-## 4.1.1 — 2026-07-25 (prepared)
+## 4.2.0 — 2026-07-30 (prepared)
+
+**Minor** over 4.1.1. Phase WI — workspace identity, activation truth, and safe multi-repository
+skill installation. Adds a stable MCP project-identity contract, exact-root `ark_identity`
+handshake, and project-bound `ark_manifest`; cross-project/config paths fail before Layers or
+ArkRules analysis; Codex setup distinguishes files configured on disk from a runtime observed
+after restart. **No required config migration.** Legacy MCP calls remain callable but explicitly
+non-authoritative until bound. Codex remains advisory at write time. **Status: prepared**
+(`arkgate@4.2.0` not published yet).
+
+### Added
+
+- **Project identity contract:** public `ark.project-identity` JSON schema, root API exports,
+  stable `projectId`, independent contract/runtime identities, and package-isolation coverage.
+- **MCP handshake and manifest:** `ark_identity` plus shared `project.expectedRoot` /
+  `expectedProjectId` input on every tool. The initial handshake requires the exact project root;
+  descendants require the matching project id. Project-bound `ark_manifest` is authoritative
+  after binding; compatibility `ark://manifest` reads are always unverified/non-authoritative.
+  Project-bound results and errors carry identity, binding state, and `authoritative`.
+- **Verdict facets:** `ark_check.verdict` separates identity, analysis completeness, graph,
+  coverage, active gates, and overall result without removing legacy `ok`.
+- **Portable evidence:** focused Linux, macOS, and Windows CI for native canonical paths,
+  activation, and multi-repo skill behavior.
+- **Report provenance:** architecture snapshots record the Git `HEAD`, branch when attached, and
+  dirty-worktree state with a shell-free, best-effort probe.
+
+### Fixed
+
+- **Wrong-project MCP reuse:** a process bound to project A rejects project B, config/manifest/
+  tsconfig escapes, nested Ark roots, and external write/change paths before returning placement,
+  golden-pattern, Layers, or ArkRules analysis.
+- **Skill MCP ordering:** every shipped `/ark-*` skill now requires a matched `ark_identity`
+  preflight before consuming any MCP analysis and carries the exact root plus returned project id
+  on each later call; stale/mismatched hosts fall back to the workspace-local CLI.
+- **Codex activation truth:** install/start/doctor say configured + restart required until a live
+  identity match; compact setup reports partial installs and removes only exact ArkGate-owned
+  project TOML.
+- **Gate-presence false green:** `--require-gates` now implies strict config validation and checks
+  semantic Ark content in AGENTS, project-rooted MCP/Codex compact registrations, and fail-closed
+  CI instead of accepting placeholder files. Backgrounded `ark-check ... &` is not accepted as
+  merge enforcement. Native Windows launcher paths are recognized.
+- **Same-machine skill churn:** managed upgrades no longer rewrite an unchanged skill only to
+  refresh `arkVersion`; repo catalogs remain isolated.
+- **Shared Codex downgrade:** ArkGate 4.2.0+ installers cannot replace a newer managed
+  `$CODEX_HOME/skills` entry with an older bundle, including with `--force`; identical installs
+  are idempotent and report why they were skipped. Pre-4.2 binaries do not understand this
+  protocol, so legacy repos must be upgraded before they write the optional home catalog.
+  Versioned catalog metadata + an install lock prevent
+  reintroducing retired skills and serialize concurrent repos. A durable pending-catalog journal
+  preserves that version floor across interrupted writes; same/newer retries recover it, while
+  corrupt metadata fails safe before skill mutation.
+- **Path aliases and junctions:** hook paths retain the caller spelling while MCP/resident
+  identities canonicalize root, config, manifest, tsconfig, launcher, and missing-tail import
+  paths. macOS `/var` → `/private/var` aliases and Windows junctions therefore reach the same
+  resident endpoint without turning in-project writes into external paths or losing import edges.
+  Windows cross-drive import targets are rejected as external even though `path.relative()`
+  returns an absolute drive-qualified path for them.
+- **ArkRules inventory noise:** actual governed layer, generated/test/fixture context, technical
+  constants, and error-constructor metadata suppress false business-rule pilots while preserving
+  eligible Domain/controller candidates.
+- **Design guidance truth:** UI business-rule pilots now route Domain → Application → UI; local
+  permission/UI-state `canEdit` helpers are not flagged by name alone; god-module pilots exclude
+  seed/fixture/demo/migration/generated files; design-weak labels retain the observed
+  SUGGEST/ADAPT/ENFORCE mode.
+- **Cross-version report deltas:** evolution reports no longer present an Ark score delta when the
+  origin and current snapshots were produced by different ArkGate versions. Raw coverage, file,
+  violation, layer, rule, and gate facts remain visible.
+
+### Compatibility
+
+- No required `ark.config.json` migration and no new ArkRules sensor family.
+- Existing MCP clients continue to work with `binding.status = "unverified"` and
+  `authoritative = false`; generated instructions require `ark_identity` followed by
+  `ark_manifest`. Standard `ark://manifest` resource reads remain compatibility-only and
+  non-authoritative.
+- `projectId` is stable for one canonical local checkout across process restarts and contract
+  edits. It is intentionally not a cross-machine or cross-operating-system content id.
+
+## 4.1.1 — 2026-07-25 (published)
 
 **Patch** over 4.1.0. Phase EH — enforcement evidence modeling + documentation truth (field Codex
 feedback + public-lane claims audit). Honesty and doctor/CI evidence taxonomy; first-push-safe CI
 base-ref; report `.gitignore` coverage without defeating `!` exceptions. **No required config
 migration.** Does not invent hard-write for Codex/Cursor/OpenCode. Does not close Z09 / RB-11.
-**Status: prepared** (not on npm until publish).
+**Status: published** (`arkgate@4.1.1` on npm `latest`).
 
 ### Added
 
@@ -59,7 +137,7 @@ write-root split, SPA/lib classification vacuum fixes, ESLint path-alias parity,
 false-positive tuning, ArkRules merge-plane honesty, type-edge placement debt, rules-inventory
 UI noise reduction, migrate-contract retrofit, and config write containment.
 **No required config migration.** Does not weaken write gate or CI value edges. Does not close
-Z09 / RB-11 field claims. **Status: published** (`arkgate@4.1.0` on npm `latest` at ship time).
+Z09 / RB-11 field claims. **Status: published** (`arkgate@4.1.0`; superseded by 4.1.1 on `latest`).
 
 ### Added
 

package/README.md

@@ -16,8 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.1.0** is on npm `latest`. Tree prepares **4.1.1** (Phase EH honesty + CI/report fixes) — [4.1.1 notes](docs/releases/4.1.1.md) (**prepared**, not on npm until publish).
-> [4.1.0 notes](docs/releases/4.1.0.md) · [4.0.1](docs/releases/4.0.1.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.2.0** is prepared (workspace identity + safe multi-repo skills);
+> **4.1.1** remains on npm `latest` until publication.
+> [4.2.0 candidate](docs/releases/4.2.0.md) · [4.1.1](docs/releases/4.1.1.md) · [4.1.0](docs/releases/4.1.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -110,6 +111,7 @@ GitHub **status context** that runs the CLI — not “CI file present,” and n
 Cursor/Codex/OpenCode never get a fake hard write claim.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
+
 <!-- arkgate-host-support:end -->
 
 #### Why the hard guarantee lives at the merge gate
@@ -130,6 +132,12 @@ the gate.
 
 Setup per host: [docs/ai-gates.md](docs/ai-gates.md) · Develop path: [docs/develop.md](docs/develop.md)
 
+For authoritative MCP contract evidence, call `ark_identity` with the exact project root, then
+call `ark_manifest` with that root plus the returned project id. A contained descendant requires
+the matching id. The legacy `ark://manifest` resource remains compatibility-only and always
+unverified/non-authoritative because standard `resources/read` cannot portably carry that
+expectation.
+
 ---
 
 ## Why not only ESLint / Nx / cruiser?
@@ -138,7 +146,7 @@ Setup per host: [docs/ai-gates.md](docs/ai-gates.md) · Develop path: [docs/deve
 |--|:---:|:---:|
 | CI import rules | ✅ | ✅ |
 | Hard-block AI writes on supported hosts | ✅ | ❌ |
-| Contract agents can read (`ark://manifest`) | ✅ | ❌ |
+| Project-bound contract agents can read (`ark_manifest`) | ✅ | ❌ |
 | Placement + preflight for multi-file changes | ✅ | ❌ |
 | Honest governed % + dual plan (edges vs shape) | ✅ | ❌ |
 | Opt-in intra-layer ArkRules (structure + invariants) | ✅ | ❌ |
@@ -186,7 +194,10 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current published (4.1.0) | [docs/releases/4.1.0.md](docs/releases/4.1.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared candidate (4.2.0) | [docs/releases/4.2.0.md](docs/releases/4.2.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.1.1) | [docs/releases/4.1.1.md](docs/releases/4.1.1.md) |
+| Previous (4.1.0) | [docs/releases/4.1.0.md](docs/releases/4.1.0.md) |
+| Previous patch (4.0.1) | [docs/releases/4.0.1.md](docs/releases/4.0.1.md) |
 | Previous (4.0.0) | [docs/releases/4.0.0.md](docs/releases/4.0.0.md) |
 | Previous (3.9.2) | [docs/releases/3.9.2.md](docs/releases/3.9.2.md) |
 | History / maintainer evidence | [docs/archive/](docs/archive/README.md) |

package/bin/ark-check-runtime.mjs

@@ -169,7 +169,10 @@ function parseArgs(argv) {
       args.strictMerge = true;
     }
     else if (arg === '--strict-config') args.strictConfig = true;
-    else if (arg === '--require-gates') args.requireGates = true;
+    else if (arg === '--require-gates') {
+      args.requireGates = true;
+      args.strictConfig = true;
+    }
     else if (arg === '--require-write-hook') {
       args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
     }
@@ -323,9 +326,9 @@ function usage() {
     'specific host. Cursor and Codex expose advisory MCP tools plus the shared CI check;',
     'merge blocking requires repository policy to make that status required.',
     '',
-    '--require-gates fails the check when AGENTS.md, .mcp.json, or the generated CI',
-    'workflow is missing, so "installed but never configured" is a red CI. Combine it',
-    'with --strict-config to enforce gate presence and architecture in one run.',
+    '--require-gates implies --strict-config and fails when the Ark contract in AGENTS.md,',
+    'the project-rooted Ark server in .mcp.json, or fail-closed CI is missing/invalid.',
+    'Included but unclassified source files therefore stay red instead of false-green.',
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
@@ -1255,7 +1258,7 @@ async function main() {
       if (args.requireGates) {
         const compactHost = compactRouterHost(args.root);
         console.log(
-          'Ark gates present (merge profile): ' +
+          'Ark gate artifacts found on disk (merge profile; runtime activation not implied): ' +
             (compactHost
               ? `AGENTS.md, compact host registration (${compactHost})`
               : REQUIRED_GATE_FILES.join(', '))
@@ -1467,10 +1470,13 @@ async function main() {
   if (args.rulesInventory) {
     const { buildRulesInventory, inventoryToExtractionCard } = await import('./lib/rules-inventory.mjs');
     const fileContents = {};
+    const fileLayers = {};
     for (const file of files.slice(0, 400)) {
       const rel = normalize(path.relative(root, file));
       try {
         fileContents[rel] = fs.readFileSync(file, 'utf8');
+        const layer = layerForFile(root, file, config.layers);
+        if (layer) fileLayers[rel] = layer;
       } catch {
         /* skip unreadable */
       }
@@ -1488,6 +1494,11 @@ async function main() {
     }
     const inventory = buildRulesInventory({
       fileContents,
+      fileLayers,
+      layerContexts: (config.layers ?? []).map((layer) => ({
+        name: layer.name,
+        intentPrefixes: layer.intentPrefixes ?? [],
+      })),
       contractedRuleIds: contracted,
     });
     const nextPilot =