arkgate 4.8.2 → 4.8.4

package/dist/{types-DCSlrRnV.d.ts → types-BuM8WNqe.d.ts}

@@ -1,4 +1,4 @@
-import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-BdCe_gvv.js';
+import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-dy5PfTqS.js';
 
 /**
  * Policy types for the Ark kernel.

package/dist/{types-C9KApBzX.d.ts → types-D95drJ3_.d.ts}

@@ -1,4 +1,4 @@
-import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-DCSlrRnV.js';
+import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-BuM8WNqe.js';
 
 /**
  * PolicyEngine

package/docs/README.md

@@ -45,7 +45,7 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 |-----|------------|
 | [CONTRIBUTING.md](../CONTRIBUTING.md) | Setup, rules, PR/release |
 | [ROADMAP.md](../ROADMAP.md) | Live implementation queue (one `doing` at a time). History: [archive/roadmap-history.md](archive/roadmap-history.md) |
-| [adr/](adr/README.md) | Architecture decisions |
+| [adr/](adr/README.md) | Architecture decisions ([0032](adr/0032-writes-via-aggregate-sensor.md) writes-via-aggregate) |
 | [SECURITY.md](../SECURITY.md) · [threat-model.md](threat-model.md) | Security |
 
 ---
@@ -62,8 +62,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 published: [releases/4.8.2.md](releases/4.8.2.md) (`arkgate@4.8.2` on npm `latest`; does not close `K01`).
-Prior: [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
+Current published: [releases/4.8.3.md](releases/4.8.3.md) (`arkgate@4.8.3` on npm `latest`; does not close `K01`). Current tree: [releases/4.8.4.md](releases/4.8.4.md) (pending publish).
+Prior: [releases/4.8.2.md](releases/4.8.2.md) · [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
 Older notes: [releases/](releases/). Config: [configuration.md](configuration.md).
 
 ---
@@ -74,4 +74,4 @@ Older notes: [releases/](releases/). Config: [configuration.md](configuration.md
 2. **One primary flow** — `start` → doctor → optional guided work.
 3. **Honest hardness** — host write guarantees differ; a **required GitHub status context** running the merge CLI is the shared hard boundary.
 4. **History is not the product** — version archaeology lives under `releases/` and `plans/`, not the front door.
-5. **Common language** — first-contact copy uses ordinary software words (import rules, the write doesn’t land, required CI). ArkGate is import rules; ArkRules is policies; ArkRun is an experimental runtime; ArkOrder is an optional pattern extra in the same npm package. Voice: [product-voice.md](product-voice.md).
+5. **Common language** — first-contact copy uses ordinary software words (import rules, the write doesn’t land, required CI). ArkGate is import rules; ArkRules is policies; ArkRun is an experimental runtime; ArkOrder stops the agent rewriting the few slow product decisions as CRUD. Voice: [product-voice.md](product-voice.md).

package/docs/agent-guide.md

@@ -461,6 +461,23 @@ order (universal): `lint` → `typecheck` → `arkgate-check` / `check:architect
 When `include` matches **zero** TS/JS files, plan/doctor treat that as **not done**
 (`goal.emptyScope`, adoption gap `empty-scope`) — never “clean architecture.”
 
+The **verdict path refuses** in that state rather than passing: a plain or `--strict`
+`ark-check` over zero governed files exits 1 with `ANALYSIS_COVERS_NO_FILES`, because
+every rule is vacuously satisfied on an empty set. It fires when source exists under the
+analyzed root and the contract governs none of it, or when the analyzed root is not the
+root you asked for (a contract found outside `--root` makes ArkGate adopt the contract's
+directory). A genuinely greenfield repo — no governable source anywhere under the root
+you asked for — still passes, so `ark init` can land a contract before the code.
+
+"Source exists" is answered by a probe the contract cannot steer: it ignores `exclude`
+(otherwise `exclude: ["**"]` would buy a green), skips dot-directories, never follows a
+symlink, skips `*.config.*` (a repo whose only TS is `vite.config.ts` is greenfield, not
+a mismatch), and stops at 200 files — the message says *at least N* when it did.
+
+The commands below are exempt on purpose: they are how the refusal gets diagnosed and
+fixed, so `--plan`, `--coverage` and `--doctor` still exit 0 on an empty scope and report
+`empty-scope`. **Do not gate CI on a report mode** — gate on `ark-check` / `--strict`.
+
 ```bash
 npx ark-check --suggest-include --json    # workspaces + nested package.json+TS roots
 npx ark-check --adopt-contract --write  # expand include + UI patterns (no rule weakening)
@@ -469,6 +486,167 @@ npx ark-check --coverage
 
 Polyglot repos: Ark only governs TypeScript/JS. Point include at package roots that have sources.
 
+### Which rules can be enforced (`--sensors`, `--promote`)
+
+Promotion — moving a rule from `advisory` to `enforced` — used to be discovered
+by trial. Edit the ArkRules JSON, wait for a full run (~160s on a real
+repository), read the result, `git checkout` it back. Four attempts before the
+map was clear, and one of them ended in a rejection naming a sensor id the
+author had never typed: a rule called `types-only` refused with *"sensor
+`no-anemic-model` is Tier-2 advisory-only"*.
+
+Both surfaces are read-only by default and neither invents a second opinion:
+they project the same declarations the gate reads.
+
+```bash
+npx ark-check --sensors [--json]              # the map: what can ever be enforced
+npx ark-check --promote [--json]              # the price: what enforcing would cost, one run
+npx ark-check --promote <ruleId> --apply      # write mode "enforced" into that rule's own file
+```
+
+**`--sensors`** lists every sensor ArkGate ships — ArkRules, ArkRun and
+ArkOrder — with its plane, its tier and whether it can *ever* be enforced, so
+Tier-2 shows up before you write the rule rather than after you wait for a run.
+It also says *how*: only the ArkRules plane is promoted per rule; ArkRun and
+ArkOrder are switched by the plane-level `arkRun.mode` / `arkOrder.mode`, and
+`--promote --apply` writes ArkRules documents only.
+Underneath it lists every rule the contract actually declares, each with its
+local id, the sensor it delegates to, the layer, the file it was declared in,
+its current mode, and the reason it can or cannot be promoted. Three things
+block a promotion, and the surface names which one fired:
+
+- **`tier-2-advisory-only`** — the sensor is a heuristic (`no-anemic-model`,
+  `arkrun-skip-resolve`). Advisory forever; the contract rejects `enforced`.
+- **`no-structure-teeth`** — `invariant-coverage` as a *structure* entry emits
+  nothing (coverage is judged per entry in `invariants`), so enforcing it would
+  change nothing. Promote the invariant instead.
+- **`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.
+
+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
+text match — ArkGate never executes a test). Exit 0 on a report, **2** when the
+contract or its ArkRules references will not load, or when the governed-file
+scan itself fails — reporting every invariant as uncovered because ArkGate could
+not collect the inputs would be our limitation printed as a fact about your
+tests.
+
+**`--promote`** adds the price. Advisory rules are already evaluated on every
+run, so the findings each one produces are sitting in the analysis that just
+happened, stamped with the rule that produced them: **one** run prices **every**
+declared rule, which is the whole difference from the loop it replaces. A
+promotable advisory rule with zero findings today is a free promotion; one with
+seven is seven findings that stop being warnings and start failing the gate.
+
+Findings are counted per `<sourceFile>#<ruleId>`, not per bare id. Rule ids are
+unique inside one ArkRules document, not across them, so two layer files may
+both declare `shared-id` — keyed on the id alone their findings pool and each
+row reports the other's as its own.
+
+**A price the run could not measure is never printed as a price.** Two things
+qualify the numbers, and both are named above them rather than left implied:
+
+- **Incomplete analysis.** Parse failures suppress findings, so the count is a
+  floor, not the cost.
+- **The classification floor.** Below it every enforced ArkRules finding is
+  demoted to a warning, so promoting buys a label and not a tooth — the gate
+  would still pass. `wouldBlock` drops to zero and the run says so. Classify
+  more of the tree (`--coverage`) before promoting.
+
+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
+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 —
+nor with `--changed` / `--against` / `--baseline`, which narrow or suppress the
+findings the price is made of.
+
+The write binds to the rule that was priced (an edit that changed its sensor in
+between is refused), writes every byte before it truncates so a failed write
+cannot leave the project without a loadable contract, and names its refusals:
+`symlink`, `hard-link`, `not-utf8`, `outside-root`, `short-write`. A document
+that was already indented keeps its indentation and trailing newline; a minified
+one comes back pretty-printed, because the write is a JSON round-trip rather
+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.
+
+### Literal path drift after a rename (`--path-drift`)
+
+A repo path written inside a **string, a comment or a docstring** is invisible to
+the rest of the gate: `tsc` resolves imports, not strings, and ESLint does not
+either. A rename therefore compiles green and the reference lies afterwards.
+
+```bash
+npx ark-check --path-drift --base-ref origin/main          # preview
+npx ark-check --path-drift --base-ref origin/main --write  # apply the anchored fixes
+npx ark-check --path-drift --base-ref origin/main --all    # + the unanchored sweep
+```
+
+Two modes, because they make different claims:
+
+- **Anchored** (default) — the referenced path is gone and exactly one rename in
+  `git diff --find-renames <base-ref>` says where it went. A finding
+  (`LITERAL_PATH_DRIFT`) normally carries a replacement written in the author's
+  own form (alias stays alias, relative is recomputed relative, a path with no
+  include-root prefix keeps its coordinate space); the fix is one-directional
+  and `--write` applies it. Exit 1 while anchored drift remains. Three things
+  must hold before a replacement is offered at all: a rename explains the
+  reference, the destination itself resolves (otherwise the "fix" only moves the
+  drift), and the destination is path-shaped — a git path is raw bytes, and a
+  destination containing a quote or a newline would edit the program rather than
+  repair a reference. A finding that clears the first two but whose destination
+  leaves its own alias root is reported with the target only and marked *rewrite
+  by hand*; `--write` never touches it, so the summary counts writable
+  replacements separately.
+- **Unanchored** (`--all`) — a literal that looks like a repo path and does not
+  resolve, with nothing to say where it went (`LITERAL_PATH_UNRESOLVED`).
+  Advisory: never written, never fails a run. It is opt-in because ArkGate
+  cannot tell a dead reference from an illustrative one, and reporting the
+  difference as if it could would be our limitation stated as a fact about your
+  code. The **count is always printed**, listed or not.
+
+Three exit codes, so a pipeline can tell the three outcomes apart from the
+status alone:
+
+| exit | meaning |
+| --- | --- |
+| `0` | anchored mode ran and nothing is left |
+| `1` | anchored drift remains |
+| `2` | anchored mode could not run (no usable base ref) — this run proved nothing |
+
+A green tick is printed only for `0`. With no usable base ref the run prints
+`○ Anchored mode did not run` and exits `2`: a tick, or a zero status, over a
+check that never happened is the false green this pass exists to remove.
+
+`--write` refuses rather than risks the file, and every refusal is named in the
+output: a symlinked leaf or parent (`symlink`), a hard link to a file the repo
+does not own (`hard-link`), content that is not valid UTF-8 (`not-utf8` — a
+whole-file rewrite would replace the offending byte with U+FFFD), a token that
+has moved since the scan (`token-moved`), and anything resolving outside the
+root (`outside-root`). The read-modify-write goes through a single
+`O_NOFOLLOW` descriptor, so the path is never resolved twice.
+
+The rename set is taken against the working tree, so a rename that is staged
+but not yet committed is covered — the moment the drift is cheapest to fix. (A
+bare `mv` without `git add` is invisible to rename detection: its destination is
+untracked.) Without a usable base ref the
+run says so instead of printing a green.
+
+The pass reads the contract for one thing only — `include`, to learn which
+prefixes a path may be written under — and ignores `exclude`: a contract must not
+be able to hide drift from the pass that reports it, and a contract too broken to
+parse is no reason to stop looking either. Scope: every text format where a repo
+path is written by hand (`.ts .tsx .mts
+.cts .js .jsx .mjs .cjs .css .scss .json .md`) — deliberately wider than the
+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.
+
 ### 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)
@@ -899,6 +1077,10 @@ edges are not denied by that rule.
 - **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).
 - **Fail-closed:** missing paths, empty/unresolvable slice folders, or unclassifiable either side → **deny** via peerIsolation (cannot prove same-slice).
+- **`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).
+- Promoting a genuinely shared slice to its own layer remains the recommended model; the two declarations exist so ArkGate can enforce a repo that deliberately chose otherwise.
 - Enforced by `ark-check`, `arkgate/eslint`, and `ark-mcp` (path-aware edges and path-less intent refs share the same SoT).
 - Fixes are **judgment** (not mechanical-safe).
 

package/docs/configuration.md

@@ -86,6 +86,33 @@ Top-level fields:
 - `include`, `exclude`, `excludeGenerated`, `frameworkOverlay`
 - `layers`, `rules`, `cyclePolicy`
 - `dynamicImportAllowlist`, `safety`
+- **`coverage`** (optional) — invariant-coverage scan controls: `testGlobs` (globs that decide
+  which files count as tests, replacing the built-in `*.test.*` / `tests/` name heuristic),
+  `maxFiles` (evidence file budget, default `400`) and `coverageRoots` (path prefixes where the
+  project declares its runner actually executes tests). Absence is silent and changes no verdict.
+  Unknown keys fail closed. When the budget is hit, `INVARIANT_UNCOVERED` reports the numbers
+  (files loaded, tests retained, files discarded at the cap) and names `coverage.maxFiles` as
+  the knob that raises it — coverage never claims "never had tests" because of our own cap.
+  `maxFiles` is clamped to a hard ceiling of 20000 (the config validator has no
+  `maximum` keyword, so a schema bound would be accepted and then ignored). The cap
+  bounds files **retained as evidence**, not files opened: a test is read before it can
+  be judged for naming an invariant, so the diagnostic reports files read alongside
+  files retained.
+  Nothing is dropped in silence: files past the budget, files over the 256KB per-file cap,
+  unreadable files or directories (permissions, broken symlinks), directories past the walk depth
+  limit (8), symlinks whose target resolves outside the project root, and tests naming no
+  catalogued invariant are each counted and named in the diagnostic. A symlinked test is read only
+  when its target is inside the root: a file that is not in this repo never proves an invariant
+  covered.
+
+  `coverageRoots` closes a false green ArkGate could otherwise produce. Coverage is proven by
+  matching an invariant id in a test title — a filesystem walk plus a text match. **ArkGate never
+  executes tests and never reads a runner config**, so a test in a folder no runner runs certifies
+  the invariant just as well as one that runs. Declaring `coverageRoots` gives ArkGate a second
+  declaration to compare the first against: when the only covering test falls outside them, it
+  reports `INVARIANT_COVERAGE_OUTSIDE_ROOTS` (advisory) and refuses to promote that invariant to
+  `enforced`. Declaring nothing keeps the old silence — without a declaration there is nothing to
+  compare, and ArkGate makes no claim about where tests run.
 - **`arkRules`** (optional, schema `1.1+`) — map of layer name → project-relative path to an
   ArkRules file (e.g. `"DomainModel": "arkrules/DomainModel.json"`). Keys must match a declared
   layer. Missing/invalid referenced files **fail closed**.
@@ -99,10 +126,12 @@ Top-level fields:
   preflight / CI verdict and arm only when the layer plane is classified (same ≥50%
   governed and ≥1 populated-layer floor as ArkRules).
 - **`arkOrder`** (optional, schema `1.3+`) — inline ArkOrder extra (`mode`, `planeRoots`,
-  `managedLayers`, `maxXiKeys`). Absence is silent. Unknown keys fail closed.
+  `managedLayers`, `maxXiKeys`, **`xiKeys`**). Absence is silent. Unknown keys fail closed.
   Import `createOrderPlane` from `arkgate/order` (same package). Empty `planeRoots` in
-  `enforced` mode fails closed (`ARKORDER_MISSING_PLANE`). Demotion or deletion is a
-  policy-delta **weakening**. Haken: few slow keys (ξ); field ingest never mints a pattern.
+  `enforced` mode fails closed (`ARKORDER_MISSING_PLANE`). `xiKeys` are the 3–5 slow
+  names the product already knows (plan, protocol, cost-code bound). Empty `xiKeys`
+  leaves `ARKORDER_XI_FIELD_WRITE` silent. Membership ids are not keys. Demotion or
+  deletion is a policy-delta **weakening**. Field ingest never mints a pattern.
 
 Layer fields:
 
@@ -128,11 +157,60 @@ process module-capability family must be denied.
 
 Rule fields:
 
-- `from`, `to`, `allowed`, `message`, `peerIsolation`, `sliceFolders`
+- `from`, `to`, `allowed`, `message`, `peerIsolation`, `sliceFolders`, `sharedRoots`,
+  `allowedCrossSlice`
 - `peerIsolation: true` + `allowed: false`: deny only when slice ids differ; same-slice allows
   when both paths classify. Missing paths, empty slice folders, or unclassifiable slices
   **fail closed** (deny — cannot prove same-slice).
 
+#### Declared peerIsolation exceptions (4.8.4)
+
+Fail-closed denies on **absence of evidence**, so in a repo that legitimately keeps shared code
+outside `features/<slice>/` (a `ui/`, `hooks/`, `lib/permissions/` tree) every shared file reads as
+a violation — thousands of them, none a real cross-slice import. That is ArkGate reporting *our*
+inability to place a file as a fact about *your* code. Two declarations fix it, and a declaration
+is evidence:
+
+```jsonc
+{
+  "from": "Features", "to": "Features", "allowed": false, "peerIsolation": true,
+  "sliceFolders": ["features"],
+  // Roots this repo keeps shared on purpose — no longer "unclassifiable".
+  "sharedRoots": ["ui", "layout", "providers", "hooks", "lib/permissions"],
+  // Directed slice→slice edges this repo wants. One entry = one direction.
+  "allowedCrossSlice": [{ "from": "features/checkout", "to": "features/catalog" }]
+}
+```
+
+- `sharedRoots` is **anchored**: the root must start the repo-relative path, optionally after a
+  single conventional source folder (`src/`, `app/`). So `ui` covers `ui/button.tsx` and
+  `src/ui/button.tsx` but **not** `modules/a/ui/x.tsx` — an unanchored root would exempt a whole
+  tree you never declared. Write a deeper or monorepo root out (`packages/web/src/ui`) or glob it
+  (`packages/*/src/ui`). Matching is case-insensitive; a bare `*` or `**` is refused, because one
+  character must not disable fail-closed. A path that still resolves to a slice keeps its slice —
+  `features/auth/ui/form.tsx` stays `features/auth` — so a shared root can never launder a real
+  cross-slice edge.
+- `allowedCrossSlice` entries match a full slice id (`features/catalog`) or a bare slice name
+  (`catalog`), and only in the direction written. The reverse edge still denies. A bare name
+  matches that name under **any** slice folder, so in a repo with several slice parents
+  (`features/auth` and `modules/auth`) write the full id — `features/auth` — or the
+  declaration allows more edges than you meant.
+- Everything else is unchanged: two different slices with nothing declared still deny, and a file
+  that is neither in a slice nor under a declared shared root still **fails closed**.
+- The denial now names which reason fired — `cross-slice edge features/a → features/b` (a fact
+  about your code) versus `unclassifiable path (src/widgets/x.tsx)` (a fact about our evidence).
+  `no slice folders` and `no path evidence` are the two remaining evidence reasons. A rule-level
+  `message` override no longer hides it: the reason is appended to your text, not replaced by it.
+- Both declarations are **weakening** changes in `ark policy-delta`
+  (`shared-roots-added`, `cross-slice-allowance-added`), so a policy review sees them. Both are
+  inert on a rule without `peerIsolation: true`, and policy-delta stays silent about them until
+  the wall exists.
+
+**The recommended model is still to promote a genuinely shared slice to its own layer** and let
+the layer edges carry it: a one-way peer import between slices is a DAG the layer graph cannot
+see. `sharedRoots` and `allowedCrossSlice` exist so ArkGate can enforce a design that made the
+other choice deliberately, not so slices can drift into a mesh.
+
 ### Type-only edges (placement debt)
 
 `import type` / `export type` and pure type-only named bindings are **type placement debt**, not
@@ -161,15 +239,17 @@ See [brownfield adoption](brownfield-adoption.md#nextjs-honesty-default-overlays
 | **Structure sensors** | Intra-layer heuristics | Only `mode: "enforced"` |
 | **Invariants** | Catalog + coverage evidence (not a business runtime) | Only enforced + proven-uncovered |
 | **ArkRun** (opt-in extra) | Kernel usage + complete declarations | Only `arkRun.mode: "enforced"` when classified |
+| **ArkOrder** (opt-in extra) | Frozen pattern + four verbs (no `update`) | Only `arkOrder.mode: "enforced"` when classified |
 
-Absence of `arkRules` or `arkRun` adds **no** extra merge teeth. **Advisory** structure sensors, advisory
-invariants, and advisory ArkRun also add **no** merge teeth (FG-ARKRULES-ADVISORY-ONLY / ADR 0020) — packing every starter
-`arkrules/*` file does not make merge fail structure alone. Enforced structure/invariants/ArkRun arm
+Absence of `arkRules`, `arkRun`, or `arkOrder` adds **no** extra merge teeth. **Advisory** structure sensors, advisory
+invariants, advisory ArkRun, and advisory ArkOrder also add **no** merge teeth (FG-ARKRULES-ADVISORY-ONLY / ADR 0020 / ADR 0027) — packing every starter
+`arkrules/*` file does not make merge fail structure alone. Enforced structure/invariants/ArkRun/ArkOrder arm
 `mergePlanes.extraMergeTeeth` only when the layer plane is honestly classified
 (governed ≥ 50% and ≥ 1 populated layer); empty classification never gets extra-plane teeth
 (P1M-EXTRATEETH-EMPTY-GRAPH). Extra planes **never** merge into one architecture
 score. Doctor exposes `rulesUnderContract.mergePlanes` (including `mergePlanes.arkRun`) for which plane can fail,
-and a dedicated `doctor.arkRun` section that is always `notAScore`.
+and a dedicated `doctor.arkRun` section that is always `notAScore`. ArkOrder skip findings are
+`ARKORDER_*` diagnostics on that same extra-teeth floor.
 
 Safety fields:
 
@@ -196,7 +276,7 @@ Each `arkrules/<Layer>.json` may declare:
 
 | Section | Purpose | Modes | What it really enforces |
 |---------|---------|--------|-------------------------|
-| `structure[]` | Closed sensor ids (e.g. `orchestration-only`, `thin-adapter`, `aggregate-private-state`, `always-valid-factory`, `domain-event-on-mutation`, `no-anemic-model`) | `advisory` (default) or `enforced` | **Heuristics of module shape** — not proof that logic was extracted to Domain. Tier-2 sensors (`no-anemic-model`) stay advisory-only (cannot promote to enforced). |
+| `structure[]` | Closed sensor ids (e.g. `orchestration-only`, `thin-adapter`, `writes-via-aggregate`, `aggregate-private-state`, `always-valid-factory`, `domain-event-on-mutation`, `no-anemic-model`) | `advisory` (default) or `enforced` | **Heuristics of module shape** — not proof that logic was extracted to Domain. `writes-via-aggregate` is driver-import + write-token in the declaring layer (ADR 0032). Tier-2 sensors (`no-anemic-model`) stay advisory-only (cannot promote to enforced). |
 | `invariants[]` | Stable ids + description + `coverage` (`test` / `symbol`) + optional `appliesTo` globs | `advisory` or `enforced` | **Named policy + evidence** (symbol in source and/or test title/content). Does **not** execute business logic at check time and does **not** replace behavior/property tests. |
 
 **Reporting:** diagnostics carry `evidence.arkruleId` + `evidence.arkruleSource`. Label residual

package/docs/develop.md

@@ -6,8 +6,9 @@ For **developers** integrating ArkGate into a product repo: agents, CI, config,
 
 When the agent writes a bad import, the write doesn’t land. The same check fails the pull
 request. Not an API Gateway. Not a folder linter. Without a required CI status,
-`ark.config.json` is just documentation. ArkGate is import rules. ArkRules and ArkRun
-are optional — policies and an experimental runtime, not a second install.
+`ark.config.json` is just documentation. ArkGate is import rules. ArkRules, ArkRun,
+and ArkOrder are optional — policies, an experimental runtime, and the extra that
+stops slow product decisions being CRUD. Not a second install.
 
 If you only want the happy path, start at [use.md](use.md).
 
@@ -85,6 +86,7 @@ can show `runtimeObserved: true` even when branch-protection policy is plan-unav
 | Layers, rules, globs | [configuration.md](configuration.md) · `ark.config.json` |
 | ArkRules (structure + invariants) | [configuration.md](configuration.md#arkrules-intra-layer-opt-in) · `arkRules` / `arkrules/*` · skill `/ark-adopt` (session 0) or `/ark-autopilot` |
 | Rules inventory (brownfield) | `arkgate-check --rules-inventory` · MCP `ark_rules_inventory` |
+| Which rules can be enforced | `arkgate-check --sensors` (the map) · `arkgate-check --promote [<ruleId>] [--apply]` (the price) · [agent-guide](agent-guide.md#which-rules-can-be-enforced---sensors---promote) |
 | Stable package API | [package-surface.md](package-surface.md) |
 | Diagnostic codes (`ruleId` why/fix) | [diagnostics.md](diagnostics.md) · root `DIAGNOSTIC_CATALOG` |
 | Session / project status snapshot | `ark status --json` · MCP `ark_status` · [session recipe](agent-guide.md#session-recipe-agent-turn) · schema `arkgate/schema/status-manifest` |
@@ -186,6 +188,26 @@ See [configuration.md](configuration.md), [package-surface.md](package-surface.m
 
 ---
 
+## Optional ArkOrder extra and plane
+
+Layers can be green while the agent still PATCHes `plan` as if it were `seatCount`.
+Optional **`arkOrder`** on `ark.config.json` (schema `1.3`) is the extra that makes
+those few slow product decisions a write rule: field events absorb or escalate;
+a generic `update` of the plan does not land. Absence is silent. Compact starters
+leave it off.
+
+The plane is `arkgate/order` in package `arkgate`, not a second install.
+`createOrderPlane` is the factory. Call it only in `arkOrder.planeRoots`. Domain
+stays plane-free. Empty `planeRoots` in `enforced` mode fails closed
+(`ARKORDER_MISSING_PLANE`). In-memory. Not durable. Does not replace ArkRun.
+
+Copy [examples/arkorder-billing/](../examples/arkorder-billing/) (`plan` / `cycle` /
+`tenancy`) and rename the keys. Posting an invoice is absorbed; changing plan is a
+new release. See [configuration.md](configuration.md) and
+[package-surface.md](package-surface.md).
+
+---
+
 ## Migrate from `ark-runtime-kernel`
 
 Same product, new package name: [migrate-from-ark-runtime-kernel.md](migrate-from-ark-runtime-kernel.md).

package/docs/diagnostics.md

@@ -44,6 +44,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ARKRULE_INVARIANT`](#ARKRULE_INVARIANT) | arkrules | ArkRule invariant failed |
 | [`ARKRULE_SCOPE_EMPTY`](#ARKRULE_SCOPE_EMPTY) | arkrules | ArkRule appliesTo matched zero files |
 | [`INVARIANT_UNCOVERED`](#INVARIANT_UNCOVERED) | arkrules | Invariant without coverage evidence |
+| [`INVARIANT_COVERAGE_OUTSIDE_ROOTS`](#INVARIANT_COVERAGE_OUTSIDE_ROOTS) | arkrules | Covering test outside the declared coverage roots |
 | [`ARKRUN_MISSING_ROOT`](#ARKRUN_MISSING_ROOT) | arkrun | No kernel factory in composition roots |
 | [`ARKRUN_KERNEL_IN_DOMAIN`](#ARKRUN_KERNEL_IN_DOMAIN) | arkrun | Domain-role layer imports the kernel |
 | [`ARKRUN_DIRECT_NEW`](#ARKRUN_DIRECT_NEW) | arkrun | Managed type constructed with new |
@@ -69,7 +70,10 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`DESIGN_SMELL_REGRESSION`](#DESIGN_SMELL_REGRESSION) | preflight | Design smell regression on base-relative ratchet |
 | [`ANALYSIS_PARSE_INCOMPLETE`](#ANALYSIS_PARSE_INCOMPLETE) | analysis | Parse incomplete |
 | [`LEXICAL_EVIDENCE_INCOMPLETE`](#LEXICAL_EVIDENCE_INCOMPLETE) | analysis | Lexical evidence incomplete |
+| [`ANALYSIS_COVERS_NO_FILES`](#ANALYSIS_COVERS_NO_FILES) | analysis | Analysis covered no files |
 | [`ANALYSIS_HOST_UNAVAILABLE`](#ANALYSIS_HOST_UNAVAILABLE) | analysis | Analysis host unavailable |
+| [`LITERAL_PATH_DRIFT`](#LITERAL_PATH_DRIFT) | drift | Literal path moved by a rename |
+| [`LITERAL_PATH_UNRESOLVED`](#LITERAL_PATH_UNRESOLVED) | drift | Literal path does not resolve |
 | [`ADAPTER_NOT_ALLOWED_FOR_PORT`](#ADAPTER_NOT_ALLOWED_FOR_PORT) | adapter | Adapter not allowed for port |
 | [`FORBIDDEN_PATTERN`](#FORBIDDEN_PATTERN) | snippet-policy | Forbidden regex pattern |
 | [`FORBIDDEN_SUBSTRING`](#FORBIDDEN_SUBSTRING) | snippet-policy | Forbidden substring |
@@ -281,7 +285,18 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 **Invariant without coverage evidence**
 
 - **Why:** An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is `never-had-tests` (adopt residual) vs `tests-disappeared` (suite exists).
-- **Fix:** Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green.
+- **Fix:** Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green. When the message reports an exhausted file budget, raise `coverage.maxFiles` (or narrow `coverage.testGlobs`) in ark.config.json. The message also names every file the scan discarded and why (budget, per-file byte cap, unreadable, walk depth limit, symlink resolving outside the project root, no catalogued invariant named) — nothing is dropped in silence.
+
+<a id="INVARIANT_COVERAGE_OUTSIDE_ROOTS"></a>
+
+### `INVARIANT_COVERAGE_OUTSIDE_ROOTS`
+
+**Covering test outside the declared coverage roots** · often advisory
+
+- **Why:** The only test naming this invariant sits outside `coverage.coverageRoots` — the places the project declares its runner executes. ArkGate matches declared text and never executes tests, so it cannot tell whether that file is ever run: coverage there is a test that *exists*, not a test that *runs*.
+- **Fix:** Move the test under a declared coverage root, or add its root to `coverage.coverageRoots` in ark.config.json. Advisory: it never fails strict, but promotion to enforced refuses on it.
+
+Declaring nothing is silent — without `coverage.coverageRoots` there is no second declaration to compare against, and ArkGate makes no claim about where tests run.
 
 ## ArkRun (opt-in extra)
 
@@ -400,6 +415,15 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 - **Why:** An ingest() result is written into a Release or ξ store. ingest may absorb or escalate; it never mints a pattern.
 - **Fix:** Keep ingest results as absorb/escalate only. Change ξ with proposeRelease + release. Never mechanical-safe.
 
+<a id="ARKORDER_XI_FIELD_WRITE"></a>
+
+### `ARKORDER_XI_FIELD_WRITE`
+
+**Slow key written around the order plane**
+
+- **Why:** A managed-layer file imports a persistence driver and writes a declared arkOrder.xiKeys name. Field events absorb or escalate; they do not PATCH the slow pattern.
+- **Fix:** Keep invoices, seats, hours, and logs on ingest. Change the slow key with proposeRelease + release, then preflight again. Never mechanical-safe.
+
 ## Atomic preflight and change sets
 
 <a id="INVALID_CHANGE_PATH"></a>
@@ -521,6 +545,15 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 - **Why:** Single-file validation cannot prove project module resolution. The write hook is already the verdict.
 - **Fix:** Re-run `npx arkgate-check --root . --config ark.config.json`, or treat the hook deny as final. Do not call `ark_prepare_change` from a hook deny.
 
+<a id="ANALYSIS_COVERS_NO_FILES"></a>
+
+### `ANALYSIS_COVERS_NO_FILES`
+
+**Analysis covered no files**
+
+- **Why:** No file matched the contract `include` and layer patterns under the analyzed root, so the run had nothing to check. Every rule is vacuously satisfied on an empty set: a green here would read exactly like a green over a governed tree while certifying nothing. Usual causes are a `--root` that is not the tree the contract describes (including a contract found outside the requested root, whose directory is then adopted as the project root), `include` / `exclude` patterns that match nothing, or layer patterns written for a different layout.
+- **Fix:** Point `--root` at the tree the contract describes, or keep the contract inside that tree, or fix the `include` / `exclude` / layer patterns so they match real files — then re-run `npx arkgate-check --root . --config ark.config.json`. `--plan` and `--coverage` report the empty scope without refusing, and `--adopt-contract --write` proposes an `include` that matches the tree. This is a refusal about ArkGate's own inputs, not a finding about your code; no baseline or policy acknowledgement can suppress it, and `exclude` cannot silence it — the "is there source here" probe deliberately ignores the contract's own `exclude`, skips dot-directories, never follows a symlink, and skips `*.config.*` tooling files so a polyglot repo is not mistaken for a mismatch.
+
 <a id="ANALYSIS_HOST_UNAVAILABLE"></a>
 
 ### `ANALYSIS_HOST_UNAVAILABLE`
@@ -530,6 +563,51 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 - **Why:** No usable TypeScript / analysis host was available for this invocation.
 - **Fix:** Install a supported TypeScript version visible to the project, then re-run. Unavailable analysis is fail-closed.
 
+## Literal path drift
+
+Reported by `arkgate-check --path-drift` only — this pass is not part of the
+architecture verdict. A path written inside a string, a comment or a docstring
+is invisible to the rest of the gate: `tsc` resolves imports, not strings, and
+ESLint does not either, so a rename compiles green and the reference lies
+afterwards. Field data from a 783-rename migration found the drift in four
+forms — the tsconfig alias, a relative literal, a path written without the
+include-root prefix, and prose (the largest class, and the only one with no
+detector anywhere; it turned up in `.ts`, `.tsx` and `.css`).
+
+The pass reads every text format where a repo path is written by hand
+(`.ts .tsx .mts .cts .js .jsx .mjs .cjs .css .scss .json .md`), skips generated
+files, and reports every file it refused to read, by reason.
+
+<a id="LITERAL_PATH_DRIFT"></a>
+
+### `LITERAL_PATH_DRIFT`
+
+**Literal path moved by a rename**
+
+- **Why:** A repo path written inside a string, a comment or a docstring no longer resolves, and the rename set says where it went. Nothing in the gate sees this class: `tsc` resolves imports, not strings, and ESLint does not either, so the rename compiles green and the reference lies afterwards. It appears in four forms — the tsconfig alias, a relative literal, a path written without the include-root prefix, and prose — and a hand sweep reliably covers one of them.
+- **Fix:** Apply the suggested replacement, or re-run `npx arkgate-check --path-drift --base-ref <ref> --write` to apply every writable anchored replacement at once. The rewrite is mechanical and one-directional: the destination comes from the rename, it must itself resolve and be path-shaped, and the token is rewritten in the form the author wrote it in. A destination that leaves the alias root of the literal is reported with the target only and must be rewritten by hand.
+
+Only a rename whose source really is gone and that has exactly one destination
+may anchor a finding. A source that maps to two destinations is not a
+one-directional fix, so it anchors nothing and its references fall through to
+the advisory list below; the count is printed.
+
+<a id="LITERAL_PATH_UNRESOLVED"></a>
+
+### `LITERAL_PATH_UNRESOLVED`
+
+**Literal path does not resolve** · often advisory
+
+- **Why:** A literal that looks like a repo path does not resolve under this root, and no rename explains where it went. Unlike `LITERAL_PATH_DRIFT` this is a candidate, not a verdict: with nothing to anchor it, ArkGate cannot tell a dead reference from an illustrative path in a comment, an example in documentation, or a path belonging to another tree.
+- **Fix:** Read the candidate and decide: fix the path, or leave it. Advisory only — it never fails a run and is never rewritten by `--write`, because there is no destination to propose. Run `--path-drift --all` to list the sweep.
+
+The sweep is opt-in for exactly the reason the coverage budget is reported
+rather than hidden: on a repository that *writes about* paths it produced 4085
+candidates out of 9536 literals, nearly all of them illustrative. Listing that
+by default would be ArkGate's inability to resolve a string presented as a fact
+about your code. The count is always printed, so opting out of the list is
+never opting out of knowing.
+
 ## Port adapters
 
 <a id="ADAPTER_NOT_ALLOWED_FOR_PORT"></a>

package/docs/enthusiast/README.md

@@ -25,16 +25,18 @@ aliases `ark` / `ark-check` still work).
 
 `ark start` and `ark-check --plan` will not claim "everything is guarded" while governed coverage is near zero. On Nest/Next/express starters, init also merges **framework filename conventions** into the layer globs so day-one coverage is real.
 
-### Two kinds of rules (4.0 — optional extra)
+### Layers always. Extras when you ask.
 
 | Kind | Plain English |
 |------|---------------|
 | **Layers** | Who may import whom (always on after start) |
 | **ArkRules** (optional) | Habits *inside* a layer — structure and named invariants as data |
-| **ArkRun** (optional extra) | Kernel usage + complete declarations (`arkRun` on schema `1.2`) |
+| **ArkRun** (optional extra) | How the app talks (`arkgate/runtime`; `arkRun` on schema `1.2`) |
+| **ArkOrder** (optional extra) | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`; `arkOrder` on schema `1.3`) |
 
-You can stay on layers only. When you add ArkRules or ArkRun, start **advisory** and promote only with
-coverage. Compact starters leave ArkRun off. Residual labels: **`[Layer]`** vs **`[ArkRules]`**. Details:
+You can stay on layers only. When you add an extra, start **advisory** and promote only with
+coverage. Compact starters leave ArkRun and ArkOrder off. Residual labels: **`[Layer]`** vs
+**`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. Details:
 [use.md](../use.md) · [configuration](../configuration.md).
 
 ## Start here