arkgate 4.8.23 → 4.8.24

package/docs/README.md

@@ -73,7 +73,8 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Current release: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.23`; confirm npm with `npm view arkgate@4.8.23 version`; does not close `K01`).
+Current release: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.24`; confirm npm with `npm view arkgate@4.8.24 version`; does not close `K01`).
+Prior published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.23`).
 Prior published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.22`).
 Prior published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.21`).
 Prior published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.20`). Plain-English history: [arkgate.online/changelog](https://www.arkgate.online/changelog/).

package/docs/agent-guide.md

@@ -207,6 +207,16 @@ npx ark status --json
 npx ark status --json --expected-root /abs/project/root
 ```
 
+`--config <file>` reads a non-default contract (same for `ark agents-md --config <file>`).
+When the resolved config fails the shared contract validator, status adds
+`contract: { valid: false, errors: [...] }` and the next action is `fix-config` — the same
+config every enforcing surface refuses is never reported as ready. `ark-check --json` (and
+`--doctor --json`) print `{ "ok": false, "error": "CONFIG_INVALID", "configPath", "messages" }`
+on stdout for that case (exit 2), so a JSON consumer always gets the reason. Any other fatal
+error under `--json` prints `{ "ok": false, "error": "POLICY_BASE_UNREADABLE" | "CHECK_ERROR", "message" }`
+(also exit 2); `POLICY_BASE_UNREADABLE` means the policy base ref (for example `GITHUB_BASE_REF`)
+could not be read in this checkout — fetch it or pass `--base <ref>`.
+
 MCP parity tool: **`ark_status`** (same envelope; pass `project.expectedRoot` after `ark_identity`).
 Schema: `arkgate/schema/status-manifest`. Never prompts; under `CI=1` JSON is forced. **Not a
 score** — counts, honesty modes, and residual ids only. Write-path interpretation of activation vs
@@ -312,14 +322,35 @@ npx ark-check --ratchet-cores                   # require populated core layers
 npx ark-check --watch                           # debounced re-check when governed files change
 ```
 
+**Package pin:** `ark start` and `ark init` both pin `arkgate` in `package.json`
+`devDependencies` (and install it unless `--skip-package-manager`) before writing the CI workflow
+and host hooks, because those call the local `ark-check` / `arkgate-mcp` bins. `--no-install`
+skips the pin; without a `package.json` setup prints a warning instead. When arkgate is not a
+local dependency (no pin, no `node_modules/arkgate`), every generated command runs
+`npx -y -p arkgate@<exact version> <bin>` instead of a bare `npx ark-check`, which npm would
+resolve as a nonexistent `ark-check` package (404) or a stale global. `--doctor` leads with
+`PACKAGE_PIN_ABSENT` when an existing generated file still uses the local runner without the pin.
+`start --remove-host`
+never runs the package manager. An explicit `--archetype` / `--preset` on `ark start` is the
+contract that is written (not only a way past the shape-confidence gate), and re-running
+`ark start --apply` on a project that already has `ark.config.json` keeps that contract and is not
+re-gated on detected shape confidence (so the `--remove-host` restore command works).
+The generated `typecheck` script and CI step are added only when `typescript` is a dependency
+(or resolves from the project root); otherwise setup prints a note.
+
 **Day-zero origin (2.12+):** `ark init` freezes `.ark/reports/origin.*` before writing agent
-docs or CI templates. Compact `ark start` previews first and keeps the applied setup small
+docs or CI templates (the day-zero HTML is written under `.ark/reports/`, not the project root). Compact `ark start` previews first and keeps the applied setup small
 (budget: 8 files / 32 KB including project `.mcp.json`);
 run `ark-check --report ark-report.html` explicitly when you want to establish an origin/evolution
 baseline. Do not `--reset-origin` unless the user explicitly wants a new baseline.
 `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/`.
+`--report` applies the committed `.ark-baseline.json` by default (the same freeze `--doctor`
+reads), so `latest.json` and `ark status` count frozen debt as frozen, not active. Under
+`--strict` / `--strict-merge` / `--contract-diff` the implicit freeze is not applied (pass
+`--baseline` explicitly), so `--report` never changes a merge verdict. Only
+`--report` refreshes that snapshot; a plain check or `--doctor` does not.
 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
@@ -625,7 +656,9 @@ Plan by default — there is no `--dry-run` anywhere in `bin/`. `--apply` needs
 one named rule id: `--promote <ruleId> --apply`, or `--promote=<ruleId>` when
 the id starts with `-`. It refuses a bare `--promote --apply` rather than
 rewriting the contract in bulk behind a single flag, refuses an id declared in
-two documents rather than silently writing the first, and refuses to make a
+two documents rather than silently writing the first (starter ids are unique:
+`thin-persistence-adapter` / `thin-presentation-adapter`, and a layer that clones
+another layer's archetype gets its ids prefixed with its kebab-cased name), and refuses to make a
 contract change on a cost this run did not measure. `--promote` cannot be
 combined with a mode that answers first (`--sensors`, `--coverage`, `--plan`,
 `--doctor`, …) — that printed the report and exited 0 having written nothing —
@@ -1005,6 +1038,13 @@ a `Domain.*` event — the publish throws `ObservedLayerFlowViolationError` befo
 reaches history, outbox, or subscribers. Use `'soft'` to record `layer.observedViolation`
 trace/audit records without blocking, or `'off'` to disable. Agents should name the event's
 `source` honestly: it is checked against the layer matrix, not just the intent name.
+Kernels built from `ark.config.json` map intents to layers through `layers[].intentPrefixes`;
+canonical layer names (`DomainModel`, `ApplicationOrchestration`, … as `ark init` writes them)
+without prefixes get the built-in ones. A custom-named deny-rule layer with no prefixes is
+recorded once as a `layer.observedFlowUnresolvable` audit record
+(`ARKRUN_LAYER_FLOW_UNRESOLVABLE`) and listed by `ark doctor`; pass
+`enforceObservedLayerFlow: 'hard'` explicitly to make it throw `ArkKernelConfigError`.
+`peerIsolation` slice walls are not evaluated at runtime (names cannot place a slice).
 
 Strict kernels also require published events to have a registered source intent
 and a matching event contract:
@@ -1150,9 +1190,9 @@ edges are not denied by that rule.
 - **Denied:** `src/features/auth/**` → `src/features/payments/**` (different slice id).
 - **Allowed:** same-slice imports when both paths classify; classic non-peerIsolation denies still apply across layers.
 - **`sliceFolders`:** optional parent segments (default: inferred from layer globs). A bare name stays an unanchored one-segment match (`features` on `src/features/auth` is `features/auth`). A starred anchored pattern with `sliceIdentity` `path` (the default) includes the literal prefix plus the star bindings (`lib/features/*/*` → `lib/features/projects/rfi`), so parallel trees get different ids.
-- **`sliceIdentity`:** `path` (default, also when the key is absent) or `stars`. `path` keeps today's slice ids. `stars` names a starred prefix as the last literal plus the star bindings (`lib/features/*/*` and `lib/repositories/features/*/*` both yield `features/projects/rfi`). Doctor names both prefixes when they collapse onto one id. Additive — no migration.
+- **`sliceIdentity`:** `path` (default, also when the key is absent) or `stars`. `path` keeps today's slice ids. `stars` names a starred prefix as the last literal plus every star binding (`lib/features/*/*` and `lib/repositories/features/*/*` both yield `features/projects/rfi`; `modules/*/api/*` keeps the module: `orders/api/v1`). Doctor names both prefixes when they collapse onto one id. Additive — no migration.
 - **Fail-closed:** missing paths, empty/unresolvable slice folders, or unclassifiable either side → **deny** via peerIsolation (cannot prove same-slice).
-- **`childSlices`** (optional): a second wall under the same rule. The universe wall runs first and is unchanged when the block is absent. With it present, a cross-universe deny is `reasonId` `CROSS_PARENT_SLICE` (never advisory). Inside one universe, `commonFolders` and flat files are common; a child may import them; common may import a child only when `parentMayImportChild` is true. Sibling crossings are `CROSS_SIBLING_SLICE` — error when `siblings` is `deny` (the default), warning when `advisory`, and a new one past the baseline still fails. `ruleId` stays `LAYER_IMPORT_VIOLATION`. arkgate 4.8.22 and older reject the key.
+- **`childSlices`** (optional): a second wall under the same rule. The universe wall runs first and is unchanged when the block is absent. With it present, a cross-universe deny is `reasonId` `CROSS_PARENT_SLICE` (never advisory). Needs `peerIsolation: true` and `allowed: false` on the rule. Inside one universe, flat files and a `commonFolders` directory directly under the universe are common (the same folder name inside a child belongs to the child); a child may import them; common may import a child only when `parentMayImportChild` is true. Sibling crossings are `CROSS_SIBLING_SLICE` — error when `siblings` is `deny` (the default), warning when `advisory`. With a baseline, a new advisory crossing fails only when the baseline already records an advisory crossing of that rule, or with `siblings.ratchet: true`; `ratchet: false` measures only. `childSlices.message` is the inner-wall text; the rule `message` stays the universe-wall text. `ruleId` stays `LAYER_IMPORT_VIOLATION`; adapter diagnostics carry `evidence.reasonId`. arkgate 4.8.22 and older reject the key; `CONFIG_CHILD_SLICES_VERSION` fires only when the repo pins such a version (package.json, hook, CI), at that file.
 - **`sharedRoots`** (4.8.4): roots the repo declares shared on purpose (`["ui", "hooks", "lib/permissions"]`). A file under a declared shared root is evidence, not an unclassifiable path, so fail-closed stops firing on every shared file. **Anchored** — the root starts the path, optionally after one `src/` or `app/`; write deeper or monorepo roots out (`packages/web/src/ui`) or glob them, and a bare `*` / `**` is refused. A path that still resolves to a slice keeps its slice.
 - **`allowedCrossSlice`** (4.8.4): `[{ "from": "features/checkout", "to": "features/catalog" }]` — one directed slice→slice edge the repo declares on purpose. The reverse still denies.
 - **The denial names its reason:** `cross-slice edge a → b` (a fact about the code) vs `unclassifiable path (…)`, `no slice folders`, `no path evidence` (facts about the evidence ArkGate had).
@@ -1241,8 +1281,14 @@ imports/exports; resolved CLI/preflight is authoritative outside that envelope),
 `ark/no-denied-capabilities` (per-layer capability deny sets),
 `ark/no-arkrun-kernel-in-domain` / `ark/no-arkrun-direct-new` /
 `ark/no-arkrun-transport-bypass` (ArkRun extra; silent when absent; import / `new`
-envelope only), `ark/no-raw-event-publish`, and
-`ark/require-publish-source`. See [ai-gates.md](ai-gates.md).
+envelope only), `ark/no-arkorder-kernel-in-domain` / `ark/no-arkorder-generic-update`
+(ArkOrder extra), `ark/arkrules-structure` (ArkRules structure sensors, file-local),
+`ark/no-raw-event-publish`, and `ark/require-publish-source`. Findings ark-check reports as
+warnings (type-only placement debt, advisory slice walls, advisory extras) report on the
+warn-level `ark/architecture-advisory`, so ESLint errors only where ark-check fails (a
+config without that rule gets them on the blocking rule id, tagged advisory). An
+invalid contract is one `configInvalid` error per file, not a crash. See
+[ai-gates.md](ai-gates.md#eslint-editor-feedback--bounded-parity-envelope).
 
 ## Runtime Observability
 
@@ -1324,7 +1370,10 @@ not replace your web framework, HTTP clients, or job scheduler.
 The strongest place to constrain an AI agent is the moment it writes a file, not after.
 `arkgate-mcp` / `ark-mcp` exposes ArkGate over MCP (JSON-RPC over stdio; it prefers a usable
 project TypeScript API, then exact `typescript-ark-host@6.0.3`) so a host can gate
-the write path:
+the write path. `arkgate mcp` / `ark mcp` starts the same server; that is the form
+`npx arkgate@<version> mcp --root .` and the MCP Registry use, since npx runs the bin named
+after the package. Without `--config` the server reads `ark.config.json` when it exists and still
+starts in a fresh project; an explicit `--config` that points at a missing file exits 1:
 
 For a complete multi-file candidate, use `ark preflight --changes changes.json --json` or MCP
 `ark_prepare_change`. Add `--change-map map.json` (or MCP `changeMap`) only for an explicit schema
@@ -1370,13 +1419,13 @@ The server exposes these thirteen tools. Every tool accepts the additive
 |------|---------------------------|
 | `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. |
+| `validate_code` | `{ source, layer?, filePath? }`: single-file lexical check (layer plane plus the enforced ArkRun / ArkRules structure / ArkOrder sensors CI runs on that file); infer the layer from `filePath` when possible. Always partial: `valid:false` / `isError:true` until complete-candidate preflight — read `lexicalValid` for the one-file verdict. Not a hook; hard blocking is `arkgate-mcp --hook`. |
 | `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. Weakening / new layer / new allow edge needs `adrPath` on the acknowledgement. |
+| `ark_policy_delta` | `{ baseConfig, candidateConfig?, baseArkRuleFiles?, candidateArkRuleFiles?, acknowledgement? }`: classify a complete contract transition, ArkRules included; never edits the contract. `baseArkRuleFiles` (`{ "<path from baseConfig.arkRules>": <file JSON> }`) is required when `baseConfig` maps `arkRules`. Weakening / new layer / new allow edge needs `adrPath` on the acknowledgement. |
 | `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. |
-| `ark_prepare_write` | `{ source, filePath?, description?, layer? }`: compose placement and snippet validation, with hashes and a mechanical-safe patch when available. |
-| `ark_prepare_change` | `{ changes, changeMap? }`: preflight one complete create/update/delete batch in memory; never writes files. |
+| `ark_place` | `{ filePath, description? }`: resolve the governed home for `filePath` (fail-closed without it; never invents a path) and return its import/global constraints. |
+| `ark_prepare_write` | `{ source, filePath, description?, layer? }`: compose placement and snippet validation, with hashes and a mechanical-safe patch when available. `filePath` is required (fail-closed). Partial like `validate_code`: read `lexicalValid`. |
+| `ark_prepare_change` | `{ changes, changeMap? }`: preflight one complete create/update/delete batch in memory against the same Effective Contract as `ark-check` (ArkRules included: same `policyHash`, structure/invariant findings; a missing referenced ArkRules file fails closed); ArkRules-plane findings the base tree already has are returned as `preExisting: true` warnings and do not block, so baselined brownfield debt does not reject an unrelated batch; 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. |
@@ -1406,7 +1455,13 @@ Every project-bound tool success, tool error, and JSON-RPC error data carries:
 ```
 
 `projectId` stays stable across process restarts and contract edits; `runtimeId` and
-`processStartedAt` identify this live process. Binding states are:
+`processStartedAt` identify this live process. The contract (`ark.config.json`, the project
+manifest, referenced ArkRules files) is loaded once at startup: after any of them changes on
+disk, every project tool except `ark_identity` returns `CONTRACT_STALE` (`isError`,
+`authoritative: false`, `contractStale: true`) until the MCP server restarts — the process never
+answers authoritatively from an old contract. `ark_identity` keeps answering with
+`contractStale: true` so the host can diagnose it; the project-local CLI reads the current
+contract meanwhile. 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`;
@@ -1513,8 +1568,22 @@ doctor → compact router (and `/ark-autopilot` only after the skill pack).
 | `GET /workflows` | Workflows monitor: counts + `workflows[]` summaries (`id`, `name`, `status`, optional `currentStep` / `error`) |
 
 Dual package bins **`ark-dashboard`** and **`arkgate-dashboard`**
-(`bin/ark-dashboard.mjs`) poll `--url` (default `http://127.0.0.1:3000/snapshot`)
-and sibling `/outbox` + `/workflows` on an interval (`--interval`, 200–60000 ms).
+(`bin/ark-dashboard.mjs`) poll `--url` and sibling `/outbox` + `/workflows` on an
+interval (`--interval` / `--timeout`, clamped to 200–60000 ms). `--url` accepts the
+inspector root (`handle.url`) or `handle.snapshotUrl`. `startInspector()` binds a
+**random port** unless you pass `{ port }`, so pass the URL your app printed (or set
+`ARK_DASHBOARD_URL`); the fallback `http://127.0.0.1:3000/snapshot` only matches
+`startInspector({ port: 3000 })`, and the dashboard prints that hint when it cannot
+connect. `--once` renders one frame and exits (non-zero when unreachable);
+`--help` / `--version` exit 0; unknown flags exit 2 with one line.
+
+The default in-memory event buffer (`InMemoryEventBuffer`) is capped at
+`maxHistorySize` (default 1000) and its records are marked `dispatched` once the kernel
+finishes local delivery, so `/outbox` shows real backlog only. Broker sends are marked
+`dispatched` / `failed` from the handoff outcome, and a failed handoff (awaited or
+fire-and-forget) records an `event.handoffFailed` trace + audit entry. An injected
+`eventBuffer` stays relay-owned: records remain `pending` for your relay's `claim` /
+`markDispatched` (except broker handoffs the kernel performs itself).
 ANSI escape sequences + polling only — no React, Ink, or Blessed. Use
 `ark dashboard` / `arkgate dashboard` (passthrough to `bin/ark-dashboard.mjs`) or the
 dual bins `ark-dashboard` / `arkgate-dashboard`.

package/docs/ai-gates.md

@@ -50,7 +50,8 @@ fail-open. OpenCode is MCP-only. Required CI is always the merge line.
 
 Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
 rules file shared by every surface. From **4.0**, optional **ArkRules** (`arkRules` map +
-`arkrules/*.json`) ride the **same** write path, doctor, and CI adapter; absence of ArkRules
+`arkrules/*.json`) ride the **same** write path, doctor, and CI adapter (ESLint runs the
+file-local structure sensors only — see [ESLint](#eslint-editor-feedback--bounded-parity-envelope)); absence of ArkRules
 does not change inter-layer verdicts. Optional ArkRun / ArkOrder extras ride that envelope
 when on (`proposeRelease` then `apply`). Absence is silent. Label residual **`[Layer]`** vs
 **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. See
@@ -128,7 +129,11 @@ project id before using project evidence.
 Like `ark-check --baseline`, the hook ratchets: an edit is blocked only when it **adds**
 violations relative to the file's current on-disk state, so files with pre-existing
 (baselined) violations stay editable — they just can't get worse. New files block on
-every violation.
+every violation. A contract failure (`WRITE_GATE_UNAVAILABLE`, e.g. a referenced ArkRules
+file missing) is never ratcheted: it blocks edits to existing files as well as new ones.
+The Codex `apply_patch` atomic preflight ratchets ArkRules-plane findings (`ARKRULE_*`,
+`INVARIANT_*`) the same way against the base tree: debt the repository already has is
+reported as a warning (`preExisting: true`), and only findings the patch adds block.
 
 The hook classifies import targets with the same `layerForRelativePath` specificity as
 `ark-check` (an explicit file pattern beats a broader glob such as `src/lib/**`).
@@ -250,7 +255,11 @@ After edits run: npx ark-check --root . --config ark.config.json --strict
 ```
 
 The hook belongs in the **project's** `.claude/settings.json` (that's what
-`--install-agent-gates` generates). It is also safe by construction if you prefer it in
+`--install-agent-gates` generates). An existing `.claude/settings.json` (or `.codex/hooks.json`)
+is **merged**, not skipped or replaced: Ark upserts only its own `SessionStart` / `PreToolUse`
+`arkgate-mcp` entries and keeps `permissions`, `env`, other hook events, and your own hook
+entries; re-running is a no-op. Only a file that is not a JSON object is left untouched (and
+`--require-write-hook` then refuses until you fix it or pass `--force`). It is also safe by construction if you prefer it in
 your global settings: without an `ark.config.json` in the project, `--session-context`
 prints nothing and exits 0, so non-Ark projects are untouched.
 
@@ -721,8 +730,25 @@ If your runtime can run a shell command before file writes and pass the tool pay
 - Grok: `{ "decision": "deny", "reason": "…" }` on stdout when blocked
 - Antigravity: **stdout `decision` is required** — allow → `{ "decision": "allow" }`; deny →
   `{ "decision": "deny", "reason": "…" }` (exit 2 still set on deny)
-- plumbing problems (no stdin, non-source files, files outside `--root`) never block; Antigravity
-  still emits `{ "decision": "allow" }` on those fail-open paths
+- plumbing problems (no stdin, malformed payload, non-file tools, non-source files, files outside
+  `--root`) never block; Antigravity still emits `{ "decision": "allow" }` on those fail-open paths.
+  "Outside `--root`" is judged after realpath: `/tmp` vs `/private/tmp` or a symlinked checkout is
+  the same workspace and is gated
+- a gate that **cannot run** blocks every governed source write (exit `2`, `WRITE_GATE_UNAVAILABLE`,
+  plus the host deny JSON): `ark.config.json` missing / unparsable / invalid, a referenced ArkRules
+  file missing or invalid, or `dist/` missing or broken. No checker, no write. This applies to
+  existing files too: the same-file ratchet never cancels a contract failure. Writes to the law
+  files (`ark.config.json` and every ArkRules file it references under `arkRules`) are still
+  allowed so the contract can be repaired, but a write or `apply_patch` delete that would leave
+  one unloadable is denied (`WRITE_GATE_UNAVAILABLE`)
+- Codex `apply_patch`: the full grammar is reconstructed (`*** End of File`, a first hunk without
+  `@@`, `*** Move to:` judged at the destination). A patch that truly cannot be reconstructed is
+  allowed with a stderr notice and stays CI-backed
+- the hook runs the same file-local extra planes CI runs on that file: enforced ArkRun editor
+  sensors, enforced ArkRules structure sensors (`ARKRULE_STRUCTURE`), and enforced ArkOrder editor
+  sensors (`ARKORDER_KERNEL_IN_DOMAIN`, `ARKORDER_GENERIC_UPDATE`, …), under the same
+  classification floor. Cross-file evidence (invariant coverage, missing plane roots) stays
+  CI-authoritative
 
 ## ESLint (editor feedback) — bounded parity envelope
 
@@ -731,31 +757,108 @@ Layer imports and purity globals are driven by **`ark.config.json`** (walk-up fr
 linted file).
 
 ```js
-// eslint.config.js  (flat config)
+// eslint.config.js  (flat config, ESM)
 import ark from 'arkgate/eslint';
 
 export default [
   ark.configs.recommended,
-  // no-domain-infra-imports  → config-driven layer edges (type-only + value)
-  // no-forbidden-globals     → layer.forbiddenGlobals from ark.config.json
-  // ark/no-denied-capabilities → layer.capabilities.deny / layer.pure
-  // ark/no-arkrun-kernel-in-domain + no-arkrun-direct-new + no-arkrun-transport-bypass
-  //   → arkRun extra (silent when absent; import / `new` envelope only)
-  // no-raw-event-publish + require-publish-source → runtime event hygiene
+  // error: no-domain-infra-imports   → config-driven layer edges that fail ark-check
+  // error: no-forbidden-globals      → layer.forbiddenGlobals from ark.config.json
+  // error: no-denied-capabilities    → layer.capabilities.deny / layer.pure
+  // error: no-arkrun-kernel-in-domain + no-arkrun-direct-new + no-arkrun-transport-bypass
+  //          → arkRun extra (silent when absent; import / `new` envelope only)
+  // error: no-arkorder-kernel-in-domain + no-arkorder-generic-update → arkOrder extra
+  // error: arkrules-structure        → ArkRules structure sensors (file-local)
+  // error: no-raw-event-publish + require-publish-source → runtime event hygiene
+  // warn:  architecture-advisory     → the findings ark-check reports as warnings
 ];
 ```
 
-**Exact layer-edge parity envelope:** the linted production source is on disk, inside
-`include`, outside configured/generated exclusions, parse-clean, and uses a static
-`import`/`export` with a **relative** or **tsconfig `paths` / `baseUrl` alias** (e.g. `@/*`)
-literal whose target is also on disk. Inside that envelope, ESLint uses the same layer glob
-specificity, rule decision, rule id, and evidence as the resolved CLI. It reloads
-`ark.config.json` when its content changes and never invents a not-yet-created target.
+```js
+// eslint.config.cjs  (CommonJS works the same way)
+const ark = require('arkgate/eslint');
+module.exports = [ark.configs.recommended];
+```
+
+`require('arkgate/eslint')` returns the plugin itself (`configs`, `rules`, `meta`), the same
+object as the ESM default export.
+
+**Severity follows ark-check, per finding.** ESLint takes severity from the rule's configured
+level; one rule cannot report some findings as errors and others as warnings. So the plugin
+splits them by rule id. The blocking rules above report only findings that fail ark-check
+(`severity: "error"`). Every finding ark-check reports as a warning (`failsStrict: false`)
+reports on **`ark/architecture-advisory`** instead, which `recommended` sets to `warn`:
+
+- type-only placement debt (a non-peer `import type` across a denied edge);
+- a `CROSS_SIBLING_SLICE` crossing under `childSlices.siblings: "advisory"` (or not listed in
+  `enforce`);
+- `arkRun.mode`, `arkOrder.mode`, or an ArkRules rule set to `advisory`.
+
+So `eslint` exits `0` wherever `arkgate-check` exits `0` for these findings, and a Next.js
+build that runs ESLint does not fail on them. The warning text names the ark-check rule id.
+The blocking rule and `architecture-advisory` share one evaluation per file, so enabling both
+does not resolve a file's imports twice.
+
+A hand-written config that turns on single rules without `architecture-advisory` does not
+lose these findings. They fall back to the blocking rule id, at that rule's level, with the
+text `[<ark-check rule id>; advisory — does not fail ark-check. Enable
+ark/architecture-advisory …]`. Add `'ark/architecture-advisory': 'warn'` to see them as
+warnings instead.
+There is no baseline in the editor: a new advisory crossing past the recorded baseline, which
+fails in CI, is still only a warning here.
+
+**Messages are the ark-check text.** A layer denial reads
+`Architecture: <ark-check message> Specifier: <import>`. That message carries the rule-level
+`message` and the slice reason (cross-slice, cross-sibling, cross-parent, unclassifiable) plus
+the type-only suffix. ArkOrder and ArkRules findings print the sensor's own message.
+
+**Invalid contract.** When `ark.config.json` does not parse or validate, or a referenced
+ArkRules file is missing or invalid, ESLint does not crash. The file gets one
+`configInvalid` error carrying the validator text (fail closed, same as `ark-check`, which
+exits `2`), and other rules and files keep linting.
+
+**`eslint --cache`.** The plugin has `meta` (`arkgate@<version>`), so an upgrade invalidates
+cached results. `configs.recommended` also carries `settings.ark.contractHash`, a fingerprint of
+the `ark.config.json` (and referenced ArkRules files) found by walking up from the **current
+working directory** of the process that reads `configs.recommended` — not from the config
+file's directory. Editing that contract therefore invalidates the cache too. When ESLint runs
+from another directory (`eslint -c some/dir/eslint.config.js` from elsewhere, or an editor
+whose cwd is a workspace root above the project), the fingerprint covers a different contract
+or none. Pin it to the config file's directory yourself:
+
+```js
+// eslint.config.js
+import ark, { contractFingerprint } from 'arkgate/eslint';
+const contractHash = contractFingerprint(import.meta.dirname);
+export default [
+  ark.configs.recommended,
+  ...(contractHash ? [{ settings: { ark: { contractHash } } }] : []),
+];
+```
 
-**Path-alias residual (honest):** simple `paths` + `baseUrl` (including one level of relative
-`extends`) are resolved. Not claimed: TypeScript project references, multi-target path arrays
-beyond the first entry, catch-all `*` mappings, package/workspace bare imports, or symlink
-hops. Those stay CI / preflight / write-gate truth.
+Not covered by the fingerprint: a second `ark.config.json` deeper in a monorepo,
+`tsconfig.json` edits, and a cross-file target that appears or disappears. Use
+`--cache-strategy content`, clear the cache, or rely on `ark-check` / CI, which stay the
+source of truth.
+
+**Exact layer-edge parity envelope:** the linted production source is inside `include`,
+outside configured/generated exclusions, parse-clean, and uses a static `import`/`export` with
+a **relative** or **tsconfig `paths` / `baseUrl` alias** (e.g. `@/*`) literal whose target is
+on disk. Inside that envelope, ESLint uses the same layer glob specificity, rule decision,
+severity, rule id, message, and evidence as the resolved CLI. It reloads `ark.config.json`
+when its content changes and never invents a not-yet-created target. File-local facts
+(`new`, ArkOrder, ArkRules structure) come from the editor buffer, so unsaved edits and
+`--stdin --stdin-filename` are linted as written.
+
+**Path-alias resolution:** like the CLI (`ts.findConfigFile`), the tsconfig is the one nearest
+to the linted file, so a nested `apps/web/tsconfig.json` is used under a single root
+`ark.config.json`. It is read as JSONC (comments, trailing commas, and `"@/*"` / `"**/*.ts"`
+strings are safe). `extends` may be relative, absolute, a package (`@tsconfig/next/...`), or an
+array. Inheritance follows TypeScript: a child's `paths` replaces the parent's, and `paths`
+resolve against `baseUrl`, else against the tsconfig that declares them. Each target in a path
+array is tried in order, and a `*` may sit mid-pattern. Parsed tsconfigs are cached and re-read
+when the file changes. Not claimed: TypeScript project references, catch-all `*` mappings,
+package/workspace bare imports, or symlink hops. Those stay CI / preflight / write-gate truth.
 
 Outside that envelope—packages/workspaces, symlinks, CommonJS, `import = require`, dynamic
 imports, virtual creates/deletes, unresolved targets, or complete cross-file candidates—ESLint
@@ -765,8 +868,9 @@ ApplyPatch hook, or final strict CI; those paths consume the canonical resolved
 Additional rule notes:
 
 - Relative and tsconfig-aliased imports resolve only to existing on-disk TS/JS targets; package bare imports are left to CI/TS.
-- Value forbidden edges error (same pass/fail as `arkgate-check`). Type-only forbidden edges are **placement debt** (reported with `typeOnly`); merge blocking prefers value edges — align with doctor `typeEdgePolicy`.
-- `no-forbidden-globals` applies from the file layer’s `forbiddenGlobals`; the `globals` option is only a standalone fallback when no project config applies, never an override that weakens the project contract. Layers without either surface are not inventively restricted. `process` also owns exact value imports of `process` / `node:process`; type-only forms, subpaths, and `child_process` stay excluded. If the same layer also denies the `process` capability, this rule is the single `FORBIDDEN_GLOBAL` voice.
+- Value forbidden edges error (same pass/fail as `arkgate-check`). Type-only forbidden edges that are not `peerIsolation` walls are **placement debt**: a warning on `ark/architecture-advisory`, never an error — align with doctor `typeEdgePolicy`.
+- `no-forbidden-globals` applies from the file layer’s `forbiddenGlobals`; the `globals` option is only a standalone fallback when no project config applies, never an override that weakens the project contract. Layers without either surface are not inventively restricted. It sees dotted access (`Date.now`), static bracket access (`Date['now']`, ``Date[`now`]``, `globalThis['fetch']`), and destructuring from a global (`const { now } = Date`, `const { now: n } = globalThis.Date`); a dynamic key (`Date[k]`) is not a verdict. `process` also owns exact value imports of `process` / `node:process`; type-only forms, subpaths, and `child_process` stay excluded. If the same layer also denies the `process` capability, this rule is the single `FORBIDDEN_GLOBAL` voice.
+- `require-publish-source` uses the ark-check candidate test: the first argument is an Ark intent string (`'Domain.Order.Placed'`), an `{ intent }` object, or an intent-creator reference (`OrderPlaced`, `Events.OrderPlaced`). `source` counts in the first argument's `metadata`, or in the second or third argument. A generic `pubsub.publish('USER_CREATED', …)` or `client.publish({ topic })` is not flagged. The rule is silent without an `ark.config.json` and outside `include`, like ark-check.
 - Without `ark.config.json`, `no-domain-infra-imports` emits no contract verdict.
 - **ArkRun (RN06):** when `arkRun` is present, `no-arkrun-kernel-in-domain`,
   `no-arkrun-direct-new`, and `no-arkrun-transport-bypass` reuse the same
@@ -779,6 +883,21 @@ Additional rule notes:
   kernel imports (including type-only). Type-only broker imports do not flag
   transport-bypass. Missing-root and undeclared emit/handle/depend are **not**
   in this adapter — use CLI / preflight / CI.
+- **ArkOrder:** when `arkOrder` is present, `no-arkorder-kernel-in-domain` flags an
+  `arkgate/order` import, export-from, `require`, or dynamic import in a Domain-role layer — a
+  layer named `Domain` / `DomainModel` / `Domain…`, or one whose `intentPrefixes` include
+  `Domain.` — with the same sensor as ark-check. `no-arkorder-generic-update` runs the
+  file-local ξ sensors: generic `update()`, ξ field writes, `ingest()` into a Release, and
+  oversized `release()`. Missing-plane stays CLI / preflight / CI.
+- **ArkRules:** `arkrules-structure` resolves the same Effective Contract as ark-check (a
+  missing or invalid referenced file is the `configInvalid` error above) and runs the
+  **structure** sensors on the linted file: `aggregate-private-state`,
+  `always-valid-factory`, `domain-event-on-mutation`, `no-anemic-model` (always advisory),
+  and the text heuristics for `orchestration-only`, `thin-adapter`, and
+  `writes-via-aggregate`. Not in the ESLint adapter — use preflight, `ark_prepare_change`, or
+  CI: invariant coverage and `INVARIANT_*` findings (they need test globs across files),
+  empty `appliesTo` and empty invariant catalogs, the structural-hint budget, and persistence
+  hints that need resolved import layers.
 
 Rule ids are `ark/<kebab-name>`. Individual rules are also on `ark.rules` if you wire them by hand.
 Prefer keeping editor + CI on the same `ark.config.json`. Use the rule-local `globals` list only
@@ -822,10 +941,13 @@ but stays advisory.
 **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:
+Or use the repository's composite Action at a pinned release or commit. Pin the tag (or commit
+SHA) that matches the `arkgate` version in your `package.json` and write hook. The Action runs the
+checker from the ref you pin, so an older ref runs an older checker, and that checker rejects newer
+config keys (for example `schemaVersion` 1.3, `childSlices`, `sliceIdentity`) with exit 2:
 
 ```yaml
-- uses: pedroknigge/arkgate@v3.7.0
+- uses: pedroknigge/arkgate@v4.8.24 # same version as the arkgate devDependency
   with:
     root: .
     config: ark.config.json
@@ -912,6 +1034,18 @@ npx ark-check --update-baseline   # writes .ark-baseline.json — commit it
 npx ark-check --baseline          # only NEW violations fail
 ```
 
+`--update-baseline` always measures the whole governed tree. It refuses `--changed` /
+`--local` and ignores `ARK_CHECK_LOCAL=1`, because a changed-files scan would overwrite the
+freeze with only that subset.
+
+`ark-check --report` applies the committed `.ark-baseline.json` by default (the same file
+`--doctor` reads), so the report, `.ark/reports/latest.json`, and `ark status` agree with
+doctor on what is active versus frozen. A plain `ark-check` without `--baseline` is
+unchanged, and so is a merge verdict: with `--strict` / `--strict-merge` / `--contract-diff`,
+`--report` does **not** apply the implicit freeze (pass `--baseline` explicitly), so adding a
+reporting flag can never turn a failing merge run green. Only `--report` refreshes the `ark status` last-check snapshot; a plain check or
+`--doctor` does not write it.
+
 `--update-baseline` also patches existing check **invocations** so CI keeps using the
 new freeze file: `package.json` scripts and GitHub workflow `run:` lines that already
 call `ark-check` / `arkgate-check` via `npx`, `pnpm`, `yarn`, `npm`, or `node`. Those

package/docs/arkorder.md

@@ -58,8 +58,8 @@ They already exist:
 | Escalation as a first-class concept | `IngestResult` residual `absorb \| escalate_up \| hold` (`reasonCode`, `IngestEscalate.target`) | 4.8.0 / 4.8.6 |
 | Projection at the boundary | `Projector = (release, sigma) => Projection` | 4.8.0 |
 | Cap on badly designed slow parameters | `DEFAULT_MAX_XI_KEYS = 7`, `maxXiKeys`, `ARKORDER_TOO_MANY_PARAMS`, `ARKORDER_EMPTY_XI`, `ARKORDER_NESTED_XI` | 4.8.0 |
-| Valved proposals, never direct mutation | `ProposeResult` then `apply` (`ARKORDER_UNVALVED_RELEASE`) | 4.8.0 / 4.8.6 |
-| Typed cell schema | `XiSchema` / `XiPropertySchema` | 4.8.0 |
+| Valved proposals, never direct mutation | `ProposeResult` then `apply` (`ARKORDER_UNVALVED_RELEASE`); a proposal carries `baseXiHash` / `baseVersion`; a stale one, one without that binding, or one whose blast radius is not the transition that would commit fails `ARKORDER_STALE_PROPOSAL`. The binding is data, not a capability: an object that states the current base and the exact transition applies whoever built it | 4.8.0 / 4.8.6 |
+| Typed cell schema | `XiSchema` / `XiPropertySchema` / `XiPrimitive` (finite numbers only; NaN / ±Infinity fail `ARKORDER_NESTED_XI`) | 4.8.0 |
 | Named slow keys on the write path | `arkOrder.xiKeys`; `ARKORDER_XI_FIELD_WRITE` | 4.8.3 |
 | Factory isolation | `createOrderPlane` from `arkgate/order` only | 4.8.0 |
 | Information budget | `informationBudget.cannotObserve`; `ARKORDER_INFORMATION_BUDGET` | 4.8.5 |
@@ -69,10 +69,10 @@ They already exist:
 | Decision tape | ArkRun information package `decisionTape` `{ xiHash, event, residual }` | 4.8.6 |
 | σ vs ξ identity | `xiHash` / `sigmaHash` / `refreshSigma` | 4.8.6 |
 | Capacity as data | `ConstraintPack.capacity` (`kind` / `sigmaKey` / `payloadKey` / `op`) | 4.8.6 |
-| Store port | `ReleaseStore` / `createMemoryReleaseStore` in-memory default — not durable, not K01 | 4.8.6 |
+| Store port | `ReleaseStore` / `createMemoryReleaseStore` in-memory default — not durable, not K01. `load()` output is validated like `restore()`: JSON copies are accepted; hashes are recomputed from ξ / σ and an inconsistent one fails closed; a `releasedAt` (or σ.`releasedAt`) after the plane clock fails closed, so a rewritten timestamp cannot switch off σ staleness. Hashes are a consistency check, not a signature — authenticity stays the store's job. The plane advances only after `save()` returns | 4.8.6 |
 | Thin travel helper | `ingestTravelAction` absorb→`send` / escalate_up human→`raises` | 4.8.6 |
 | Verify a stored `Release.hash` | `hashOf(ξ, σ)` alias of `hashReleasePayload` — no `release()` side effect | 4.8.9 |
-| Reinstall a frozen Release | `restore(release)` — process-local; hash is identity; not durable; does not close K01 | 4.8.9 |
+| Reinstall a Release | `restore(release)` — frozen or JSON-deserialized; hash is identity; onto an empty plane, or the same ξ at the current version or the next one. Never changes ξ, never rolls the version back, never jumps it (`ARKORDER_UNVALVED_RELEASE`); a freeze time after the plane clock fails closed. Process-local; not durable; does not close K01 | 4.8.9 |
 | Default clock | omitted `clocks` is Kernel `Date.now()`; Domain must not call `Date.now` | 4.8.9 |
 
 Nothing here is a hosted runtime. Nothing here can be “down”. A degraded-mode
@@ -102,10 +102,10 @@ const plane = createOrderPlane({
 plane.release(xi, sigma);      // first freeze only
 plane.project();               // derive allowed s + invalidations
 plane.ingest(event);           // residual absorb | escalate_up | hold. Never a Release
-plane.proposeRelease(delta);   // blast radius. Empty blast = domain error
-plane.apply(proposal);         // valve: later ξ change
+plane.proposeRelease(delta);   // blast radius, bound to the current Release. Empty blast = domain error
+plane.apply(proposal);         // valve: later ξ change; stale proposal = ARKORDER_STALE_PROPOSAL
 plane.refreshSigma(sigma);     // saldo / clocks; xiHash unchanged
-plane.restore(release);        // process-local install; hash is identity; not durable; not K01
+plane.restore(release);        // reinstall (same ξ, current or next version); not durable; not K01
 hashOf(xi, sigma);             // same bytes as hashReleasePayload; no freeze side effect
 ```
 
@@ -114,6 +114,12 @@ There is no `update()`. Calling `update` / `patch` / `set` on the plane throws
 `ARKORDER_GENERIC_UPDATE`. A second `release()` whose ξ differs fails
 `ARKORDER_UNVALVED_RELEASE`.
 
+`release`, `proposeRelease`, `apply`, `refreshSigma`, and `restore` check the
+candidate projection against `informationBudget` before the Release is offered
+or persisted (`ARKORDER_INFORMATION_BUDGET`), so a denied pattern never lands.
+σ goes stale after a numeric `σ.freshUntil` on its own, or after
+`sigmaMaxAgeMs` when σ has no `freshUntil`.
+
 | Field write | Verb |
 |-------------|------|
 | Invoice, seat within cap, timesheet, daily log | `ingest` → absorb (`ingestTravelAction` may `send`) |
@@ -209,13 +215,22 @@ except withdrawn heuristics.
 |------------|------|
 | `ARKORDER_MISSING_PLANE` | Extra on, no `createOrderPlane` in `planeRoots` |
 | `ARKORDER_KERNEL_IN_DOMAIN` | Domain-role layer imports `arkgate/order` |
-| `ARKORDER_GENERIC_UPDATE` | `update` / `patch` / `set` on the plane |
+| `ARKORDER_GENERIC_UPDATE` | `update` / `patch` / `set` on a plane receiver: bound to `createOrderPlane(...)` in the file, annotated `: OrderPlane`, a `plane` / `*Plane` import from a `planeRoots` module, or a `plane` / `*Plane` name in a file that imports `arkgate/order`. A name alone (`clipPlane`, `controlPlane`) is not evidence |
 | `ARKORDER_TOO_MANY_PARAMS` | ξ keys > `maxXiKeys` |
-| `ARKORDER_INGEST_WRITES_XI` | `ingest` result assigned into a Release / ξ store |
-| `ARKORDER_XI_FIELD_WRITE` | Managed-layer driver import **and** write token **and** a declared `xiKeys` name |
-| `ARKORDER_INFORMATION_BUDGET` | `h(ξ)` allows a kind in `informationBudget.cannotObserve` |
-| `ARKORDER_XI_TTL` | ξ named ttl/freshUntil/maxAge — freshness is σ |
-| `ARKORDER_STALE_SIGMA` | ingest after σ.freshUntil, or after `release.releasedAt` + `sigmaMaxAgeMs` |
+| `ARKORDER_INGEST_WRITES_XI` | `ingest` result assigned into a Release / ξ holder (`release`, `xi`, `xiNext`, `nextXi`, `currentRelease`, `store.xi`, …); a prefix alone (`releaseState`, `currentResidual`) is not evidence |
+| `ARKORDER_XI_FIELD_WRITE` | Managed-layer driver import **and** a write on a persistence client (`db` / `prisma` / …, `new PrismaClient()`, a name bound to a driver constructor or annotated with a client type, or imported from a local `db` / `orm` / … module) **and** a declared `xiKeys` name |
+| `ARKORDER_INFORMATION_BUDGET` | A literal `allowedKinds` entry that a literal `informationBudget.cannotObserve` denies |
+| `ARKORDER_XI_TTL` | ttl/freshUntil/maxAge (shorthand included) in the ξ literal of `plane.release` / `plane.proposeRelease` on a plane receiver — freshness is σ |
+
+Runtime `ArkOrderError` codes (thrown by the plane; not static sensors, not
+promoted by `arkOrder.mode`):
+
+| Code | Thrown when |
+|------|-------------|
+| `ARKORDER_STALE_SIGMA` | ingest after σ.freshUntil, or after `release.releasedAt` + `sigmaMaxAgeMs` (ingest returns `hold`, reason `stale-sigma`) |
+| `ARKORDER_STALE_PROPOSAL` | `apply` gets a proposal not computed against the current Release |
+| `ARKORDER_UNVALVED_RELEASE` | a second `release` with a different ξ, or a `restore` that changes ξ / rolls the version back |
+| `ARKORDER_INFORMATION_BUDGET` / `ARKORDER_XI_TTL` | also thrown at runtime, whatever the static sensor saw |
 
 Why / fix: [diagnostics.md](diagnostics.md#ARKORDER_MISSING_PLANE).
 `ark-check --sensors` lists every extra sensor with plane, tier, and whether
@@ -230,8 +245,10 @@ package, inspector, in-memory compare). ArkOrder does not grow a bus, outbox,
 or hosted replay. [ADR 0033](adr/0033-arkorder-runtime-half-is-arkrun.md).
 
 Durability (`K01`) stays parked. In-memory is the honesty line.
-`restore(release)` reinstalls a frozen Release in this process. It is not a
-store. It does not close `K01`.
+`restore(release)` reinstalls a validated Release in this process: onto an
+empty plane, or the same ξ at the current version or the next one. It is
+not a store and not a rollback (that is `proposeRelease` then `apply`). It does
+not close `K01`.
 
 ---
 

package/docs/brownfield-adoption.md

@@ -101,7 +101,11 @@ ark-check --rules-inventory --json
 # MCP: ark_rules_inventory
 ```
 
-Output is **honest counts** (inventoried / under-contract / frozen) — never a score. Route
+Output is **honest counts** (inventoried / under-contract / frozen) — never a score. A
+structure candidate is under contract when its layer declares a rule on the suggested
+**sensor** (the rule id is yours to name); an invariant candidate by its id. Frozen counts the
+ArkRules-plane keys (`ARKRULE_*` / `INVARIANT_*`) in `.ark-baseline.json`. `--doctor` shows the
+same counts as `rulesMigration` (JSON and human line), and the MCP payload matches the CLI. Route
 extraction through `/ark-fix` or `/ark-loop` (one pilot card at a time) and declaration
 through `/ark-contract` editing `arkrules/<Layer>.json` (ADR 0015 — no new skill names).
 Report residual as **`[Layer]`** (import edges / baseline) vs **`[ArkRules]`** (inventory /