arkgate 4.8.3 → 4.8.4

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

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

package/dist/{types-DeK7SYGC.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-dK24fDZa.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

@@ -62,7 +62,7 @@ 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.3.md](releases/4.8.3.md) (`arkgate@4.8.3` on npm `latest`; does not close `K01`).
+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).
 

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**.
@@ -130,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

package/docs/develop.md

@@ -86,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` |

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)
 
@@ -530,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`
@@ -539,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/package-surface.md

@@ -35,7 +35,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Field upgrade truth (4.5.6)** | `ark upgrade` registry-aware install; JSON `reasonCode` / `suggestedInstallCmd`; `skillDrift`; `--refresh-skills`; `postUpgradeChecks`; `hostSelection`. | No false-skip when registry ahead; offline honesty; customized skills preserved unless opt-in refresh; checks are advisory only. |
 | **MCP process package honesty (4.5.6; fail-closed in 4.6.4)** | Every MCP tool context → `processPackage` (`processPackageMismatch` / `processStale`, versions, `nextAction`). | Multi-checkout users: restart MCP after pin bump. From 4.6.4, stale process context is non-authoritative; `ark_identity` remains diagnostic and project tools return `PROCESS_PACKAGE_STALE` until restart/retarget. Prefer project-local CLI until identity matched and versions align. |
 | **Doctor design fitness** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. `handler-in-persistence` covers static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so **absence of a smell is not full-tree proof** above that envelope (incomplete/`partial` analysis also never proves “no smells”). **4.2 feedback hardening:** mode labels preserve the observed SUGGEST/ADAPT/ENFORCE state; a local permission/UI-state `canEdit` name alone is not a domain smell; real UI business rules route Domain → Application → UI; seed/fixture/demo/migration/generated files are not god-module pilots. Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`**. Does **not** fail the gate by itself. |
-| **Post-green Shape door** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. |
+| **Post-green Shape door** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. A **passing** `ark-check` human run also prints one dim line naming `--plan`, the smell count and the smell ids. Its weakness test is `isDesignWeak` over the **blocking** violation count — the same input doctor uses, so the two surfaces cannot disagree about `designWeak`, and non-blocking type-only placement debt still gets the line. Report only: never a warning, never an exit-code change, silent when no smell remains, silent on `--changed` (a partial scan would report a slice as the tree) and on `--watch`. A baselined run is not called clean: the opening clause names the suppressed count instead. `--json` is unchanged. |
 | **Golden pattern (new code)** | Optional `.ark/golden-pattern.json`; doctor JSON `doctor.goldenPattern`; MCP `ark_place` / `ark_prepare_write` → `goldenPattern` | Additive, **advisory for NEW code only**. Required fields: `name`, `norm`; optional `newCodeHome`, `examplePath`, `schemaVersion`. **Absent is normal** (no claim). Never ENFORCE; never clears design-weak. Malformed → `invalid: true`, not silent guidance. |
 | **Plan pattern B (Shape bets)** | `ark-check --plan --json` → `plan.patternBets[]`, `plan.goal.designWeak` | Additive. Each bet: `id`, `smellId`, `pilot`, `evidence`, `successSignal`, `killSwitch`, **`neverMechanicalSafe: true`**, `class: "judgment"`. **Never** auto-applied by loop/autoPatch; not a `remediationKind` mechanical-safe. `goal.met` remains edge honesty only. |
 | **Pilot loop (one at a time)** | `plan.pilotLoop` / `doctor.pilotLoop` | Additive. When design-weak: `active`, `oneAtATime`, `neverMechanicalSafe`, **`nextPilot`** extraction-card fields (`pilotTarget`, `smellId`, `move`, `successSignal`, `killSwitch`, `doNot[]`). **One pilot → re-doctor**; never multi-pilot batch; never mechanical-safe. |
@@ -51,7 +51,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Report parity and snapshot evidence (4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth\|arkRun"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. Thin `arkRun` on `latest.json` is `notAScore` residual honesty for `ark status`. |
 | **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
 | **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
-| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
+| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
 | **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
@@ -190,6 +190,36 @@ import { createOrderPlane } from 'arkgate/order';
 
 One install: `npm install arkgate`. `@arkgate/runtime` is deprecated.
 
+---
+
+## Installing from git
+
+`npm install github:pedroknigge/arkgate` and `pnpm add git+https://github.com/pedroknigge/arkgate`
+are supported for pinning an unreleased commit, and they need **no build-allowlist entry**:
+this package declares no `prepack`, no `prepare`, and no install script. Through 4.8.3 the
+`prepack` hook made a pnpm git install fail closed with
+`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` — the whole install, not just the build — and the only
+way through was adding `arkgate` to `allowBuilds` for a script that shells out to `npm`.
+The publish path builds explicitly instead (`scripts/release-npm.mjs`, plus `prepublishOnly`
+as a backstop, which pnpm does not run when it prepares a git dependency).
+
+A git install is **not** the same package as the npm tarball, because `dist/` is a build
+output and is not committed:
+
+| From a git install | Works | Why |
+|---|---|---|
+| `arkgate` / `arkgate-check` (and `ark` / `ark-check`) | **yes** | `bin/` and `bin/lib/*.mjs` are committed sources — the deliberate zero-build CLI |
+| `arkgate/schema*` subpath exports | **yes** | `schemas/*.json` are committed |
+| `import … from 'arkgate'`, `arkgate/eslint`, `arkgate/order`, `arkgate/runtime`, `arkgate/nestjs` | **no** | all resolve into `dist/` |
+| `ark-mcp` / `arkgate-mcp` | **no** | loads `dist/index.js`; it says so and names this section |
+
+So: install from git when you want the **CLI or the CI check** at a specific commit, install
+from npm (`npm i arkgate`) when you want the **library, the MCP server, or the ESLint plugin**.
+To get everything from a checkout, clone and run `npm install && npm run build` — that is the
+maintainer path in [develop.md](https://github.com/pedroknigge/arkgate/blob/main/docs/develop.md),
+and the build stays *your* explicit command, never a script your package manager has to be
+allowed to run.
+
 See [production-hardening.md](https://github.com/pedroknigge/arkgate/blob/main/docs/production-hardening.md) for requirements an eventual
 production deployment would need to satisfy; it is not a readiness certification.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.3",
+  "version": "4.8.4",
   "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -163,7 +163,7 @@
     "audit:beta-exit": "node scripts/beta-exit-audit.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
-    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
     "bench:hook-path": "node scripts/hook-path-bench.mjs"
   },
   "dependencies": {

package/schemas/ark.config.schema.json

@@ -625,6 +625,9 @@
         "allowDisabledPeerIsolation": false
       }
     },
+    "coverage": {
+      "$ref": "#/$defs/coverage"
+    },
     "arkRules": {
       "type": "object",
       "additionalProperties": {
@@ -773,6 +776,37 @@
           },
           "uniqueItems": true,
           "minItems": 1
+        },
+        "sharedRoots": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        },
+        "allowedCrossSlice": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "from",
+              "to"
+            ],
+            "properties": {
+              "from": {
+                "type": "string",
+                "minLength": 1
+              },
+              "to": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
         }
       }
     },
@@ -800,6 +834,35 @@
         }
       }
     },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget; coverageRoots declares where the project runs its tests, so a covering test found outside them is reported instead of silently certifying an invariant.",
+      "properties": {
+        "testGlobs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        },
+        "maxFiles": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "coverageRoots": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        }
+      }
+    },
     "arkRun": {
       "type": "object",
       "additionalProperties": false,

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/arkgate",
-  "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
+  "description": "When the agent writes a bad import, the write doesn\u2019t land. The same check fails the pull request.",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.8.3",
+  "version": "4.8.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.8.3",
+      "version": "4.8.4",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"