arkgate 4.8.23 → 4.8.25

package/docs/README.md

@@ -73,7 +73,9 @@ 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.25`; confirm npm with `npm view arkgate@4.8.25 version`; does not close `K01`).
+Prior published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.24`).
+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

@@ -41,7 +41,7 @@ the project API is unusable. See the distribution and completeness boundary in
 ark start → ark start --apply → ark-check --doctor
   day to day: compact router / MCP place + validate + check
   guided work: install skill pack → /ark-autopilot
-  optional: arkRules map + arkrules/*.json (intra-layer; starts advisory)
+  optional: arkRules map (one path or a list) + arkrules/*.json, or childSlices.arkRulesFile at a slice root (intra-layer; starts advisory)
 ```
 
 `arkgate-check --doctor` shows what's wrong and what to do first. From **4.0.0**, doctor may
@@ -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
@@ -590,6 +621,9 @@ block a promotion, and the surface names which one fired:
 - **`no-coverage-evidence`** — an invariant whose evidence does not support
   promotion. The text is `canPromoteInvariant`'s own, so this surface can never
   promise a promotion the gate then refuses.
+- **`probe-survived`** — the committed invariant probe shows the covering tests
+  still pass with the rule broken, or never call it. Same judge; named apart
+  because the fix is a stronger test. See [Probe an invariant](#probe-an-invariant).
 
 It needs no TypeScript and runs no analysis: the contract, the ArkRules
 documents it points at, and the coverage evidence walk (a filesystem walk plus a
@@ -625,7 +659,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 —
@@ -642,6 +678,63 @@ than a targeted text edit. Exit 0 for a preview or a successful write, 1 for an
 unknown rule id or a refused write, 2 for bad arguments or ArkRules references
 that will not load.
 
+### Probe an invariant
+
+A test title that names an invariant counts as coverage. That proves the test
+exists, not that it would fail if the rule broke. The probe checks that, on
+request:
+
+```bash
+npx arkgate-check --probe-invariants                 # every invariant with a coverage.symbol
+npx arkgate-check --probe-invariants=INV-REFUND-WINDOW
+npx arkgate-check --probe-invariants --write         # save .ark/invariant-probe.json
+npx arkgate-check --probe-invariants --runner vitest # only when the runner is unclear
+```
+
+```text
+INV-REFUND-WINDOW: the tests still pass when the guard is negated (src/domain/refunds/refundPolicy.ts:14).
+The test names the rule but does not pin it. Next: add a case that fails when the rule is broken, then re-run with --write.
+```
+
+For each invariant with a `coverage.symbol`, it copies the project to a
+temporary folder, then runs only the covering tests (titles that name the id,
+and tests that import the symbol's file), with your own runner (vitest, jest or
+`node --test`):
+
+1. unchanged — they must pass;
+2. with the file throwing on load — a test must fail, or the copy is not the one
+   the tests load (`inconclusive`);
+3. with the symbol throwing when called — a test must fail, or the tests never
+   call it (`not-reached`);
+4. with at most three small changes inside the symbol (negate a guard, drop a
+   `throw`, flip or shift a comparison, shift a constant) — each must make a test
+   fail, or the change went unnoticed (`survived`).
+
+Every row reads `killed`, `survived`, `not-reached`, `inconclusive` or
+`unprobeable` (no symbol, a type or interface, no covering test — a declaration
+is not a test). It is not a score.
+
+**Your files are never changed.** Every change happens in the copy, which is
+removed when the run ends, including on Ctrl-C. `--write` adds only
+`.ark/invariant-probe.json`. Exit 0 when nothing survived or went unreached,
+1 when something did, 2 when it could not run (`reasonCode` in the JSON).
+
+**What the result can do.** Only refuse. When the committed file has a fresh
+`survived` or `not-reached` row, `--promote` and the policy delta refuse to
+promote that invariant to `enforced` (blocker `probe-survived`). Fresh means
+the symbol file, every covering test and the invariant are unchanged since the
+run; anything else is stale and changes nothing, like `killed`, `inconclusive`
+or no file at all. Status and `--rules-inventory` show the state per invariant
+(`INVARIANT_PROBE_SURVIVED` when it refuses). CI sees the refusal only if you
+commit the file.
+
+**Trust.** Running the probe runs your tests, exactly like `npm test`; you start
+it, nothing else does. It never runs from the write hook, MCP, ESLint, the
+GitHub Action or `--strict-merge`, and refuses to combine with them. The runner
+gets a short list of environment variables (no tokens, proxies pointed at a
+dead port, `HOME` and the temp folder inside the copy). That is best effort,
+not a sandbox.
+
 ### Literal path drift after a rename (`--path-drift`)
 
 A repo path written inside a **string, a comment or a docstring** is invisible to
@@ -714,6 +807,78 @@ TS/TSX gate the type-aware passes use, because a comment is not code and the
 class was first found in a `.css` file. Generated files are skipped, and every
 file the walk refuses is counted by reason in the output.
 
+### Files nothing imports
+
+A rewrite often lands next to the old file, and the old one stays. Nothing
+imports it. Status reads that from the import edges the check already resolved,
+so it costs no second analysis and never changes the check.
+
+```bash
+npx arkgate-check --doctor            # one dim count line at most
+npx arkgate-check --doctor --all      # the list, plus exports nothing imports by name
+npx arkgate-check --doctor --json     # doctor.orphanModules
+```
+
+```text
+Nothing imports src/lib/legacy-pricing.ts, and no entry point covers it.
+Next: Delete it through the write gate, or add it to .ark/entry-points.json if a framework loads it.
+```
+
+A file is listed only when no governed file, no test, no project script and no
+known entry point imports it. Entry points come from `package.json` (`main`,
+`exports`, `bin`, scripts — built `dist/` paths map back to source), CI workflow
+run steps, framework conventions (Next routes and `middleware`, Vite
+`index.html`, Nest `main`, Vercel `api/`, Storybook stories), the arkRun /
+arkOrder roots in `ark.config.json`, config and setup files, ambient declaration
+files, and `.ark/entry-points.json`. A file only tests import is counted, not
+listed.
+
+When a dynamic import, `import.meta.glob`, `new URL(…, import.meta.url)`, a
+quoted path, or an import that did not resolve could still reach a file, the
+item says so (`maybe-dynamic`, `maybe-unresolved`) and the section is
+`partial`. Read those before deleting. A framework or loader ArkGate does not
+know goes in the sidecar, with a reason and an optional review date:
+
+```json
+{
+  "schemaVersion": "1",
+  "entryPoints": [
+    { "glob": "src/plugins/**", "reason": "loaded by name from the plugin manifest", "reviewBy": "2027-01-01" }
+  ]
+}
+```
+
+Delete one file at a time through the write gate (`/ark-fix`), then run status
+again. Never delete a `maybe-*` item without reading what may load it.
+
+### Copies across a wall
+
+A slice wall denies the import. The cheapest way around it is to copy the code,
+and a copy is not an import, so the check cannot see it. Status details can.
+
+```bash
+npx arkgate-check --doctor --all            # the list, with a place the shared code could live
+npx arkgate-check --doctor --all --json     # doctor.crossWallDuplication
+```
+
+```text
+This code is copied between src/features/billing and src/features/invoices (34 of 35 names match).
+The wall stops the import, not the copy. Next: move it to src/shared/ with /ark-place.
+```
+
+A copy is listed only when its two files sit on two sides of a wall the check
+would enforce — two slices, two child slices of one universe — or in two
+layers. Copies inside one slice are counted, never listed: the slice may
+import its own code. The suggested home comes from your config: the declared
+`sharedRoots`, the universe common folder (`childSlices.commonFolders`), or the
+lower layer both sides may import. When none fits, it says `/ark-place`.
+
+Compact status never runs this; its JSON says `not-run` and names the command.
+Tests, `.d.ts`, generated files and files over 256 KB are never read for it. The
+thresholds are fixed (at least 50 tokens and 5 lines, and most names matching);
+there is no config key. Move one copy at a time through the write gate
+(`/ark-fix`), import it from both sides, then run status again.
+
 ### Presets
 
 - `hexagonal` / `layered` / `feature-sliced` / `monorepo` / **`ui-surface`** (UI/Vite/Remotion-style) / **`vertical-slice`** (features/* + peerIsolation) / **`ddd-bounded-contexts`** (contexts/*/domain|application|infra + shared kernel)
@@ -1005,6 +1170,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 +1322,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 +1413,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 +1502,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 +1551,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`. Include each `childSlices.arkRulesFile` path in that map when the wall discovers one. 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 +1587,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 +1700,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];
+```
 
-**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.
+`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 } } }] : []),
+];
+```
+
+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,27 @@ 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:
+**Skipped jobs and `needs:`:** GitHub reports a skipped job as a status that satisfies branch
+protection. Doctor therefore counts an Ark job as fail-closed only when nothing can skip it on
+purpose:
+
+| Ark job shape | Workflow evidence | Required-status verdict (`ARK_DOCTOR_GITHUB=1`) |
+|---------------|-------------------|--------------------------------------------------|
+| No `if:`, or `if: true` / `always()` | fail-closed | required when its context is required |
+| `needs:` jobs with no conditional `if:` anywhere up the chain | fail-closed (it only skips when a needed job fails) | required only when every needed job is also required; otherwise `unverified` plus gap `enforcement-ark-check-upstream-not-required` |
+| Job-level `if:` on a profile output (or any other condition), or a conditional job in its `needs:` chain | not fail-closed (the skip reports success) | not counted |
+| `continue-on-error: true` on the job or the Ark step | not fail-closed | not counted |
+
+A required check bound to the GitHub Actions app counts. A check bound to another app stays
+`unverified`. Doctor queries branch protection only with `ARK_DOCTOR_GITHUB=1` and a working `gh`.
+
+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.25 # same version as the arkgate devDependency
   with:
     root: .
     config: ark.config.json
@@ -912,6 +1048,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