arkgate 4.8.3 → 4.8.5

package/docs/configuration.md

@@ -86,11 +86,38 @@ 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**.
-- **`arkRun`** (optional, schema `1.2+`) — inline ArkRun extra (`mode`, `compositionRoots`,
-  `managedLayers`, `requireDeclarations`). Absence is silent. Unknown keys fail closed.
+- **`arkRun`** (optional, schema `1.2+`) — inline ArkRun extra (`mode`, `kernelRoots`
+  (`compositionRoots` alias), `managedLayers`, `requireDeclarations`). Absence is silent. Unknown keys fail closed.
   `managedLayers` must name existing `layers[].name` values. Empty `compositionRoots` in
   `enforced` mode fails closed (`ARKRUN_MISSING_ROOT`); empty `managedLayers` in `enforced`
   mode also fails closed (direct-new / undeclared / transport-bypass would otherwise no-op).
@@ -103,8 +130,15 @@ Top-level fields:
   Import `createOrderPlane` from `arkgate/order` (same package). Empty `planeRoots` in
   `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.
+  leaves `ARKORDER_XI_FIELD_WRITE` silent. Membership ids are not keys. Factory options
+  `informationBudget` and `sigmaMaxAgeMs` belong on `createOrderPlane`, not this extra
+  object. Demotion or deletion is a policy-delta **weakening**. Field ingest never mints
+  a pattern.
+
+**Activation is one shape.** ArkRun and ArkOrder both use `mode` + `managedLayers`.
+Absence of either extra is silent. They keep different *root* names because they
+name different factories: `arkRun.kernelRoots` (`compositionRoots` alias) vs
+`arkOrder.planeRoots`. Do not fold them. Canonical: [arkorder.md](arkorder.md#activation-same-shape-as-arkrun).
 
 Layer fields:
 
@@ -130,11 +164,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

@@ -10,7 +10,8 @@ request. Not an API Gateway. Not a folder linter. Without a required CI status,
 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).
+If you only want the happy path, start at [use.md](use.md). Optional ArkOrder
+(library + sensors, not a service): [arkorder.md](arkorder.md).
 
 ### Why it exists
 
@@ -60,7 +61,7 @@ Full matrix and install commands: [ai-gates.md](ai-gates.md) · canonical table
 
 ```bash
 # All common hosts (examples)
-npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity
 npx arkgate-check --install-agent-gates --tools antigravity   # alias: agy
 npx arkgate-check --install-agent-gates --tools opencode
 # Full /ark-* skill pack (optional expert depth)
@@ -86,6 +87,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)
 
@@ -409,6 +424,33 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 - **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.
 
+<a id="ARKORDER_INFORMATION_BUDGET"></a>
+
+### `ARKORDER_INFORMATION_BUDGET`
+
+**Projection observes a forbidden kind**
+
+- **Why:** h(ξ) allowedKinds includes a kind listed in informationBudget.cannotObserve. A scale may not look at what it was told not to see.
+- **Fix:** Cut that kind from the projector or from cannotObserve, then preflight again. Never mechanical-safe.
+
+<a id="ARKORDER_XI_TTL"></a>
+
+### `ARKORDER_XI_TTL`
+
+**Slow key carries a freshness field**
+
+- **Why:** ξ named ttl/freshUntil/maxAge. Freshness belongs on σ. A slow parameter that expires per transaction is not slow.
+- **Fix:** Move freshness onto σ (freshUntil) and keep ξ stable, then preflight again. Never mechanical-safe.
+
+<a id="ARKORDER_STALE_SIGMA"></a>
+
+### `ARKORDER_STALE_SIGMA`
+
+**σ is stale**
+
+- **Why:** ingest ran after σ.freshUntil (or sigmaMaxAgeMs). ξ does not TTL.
+- **Fix:** Refresh σ and ingest again, or freeze a new release if the pattern changed. Never mechanical-safe.
+
 ## Atomic preflight and change sets
 
 <a id="INVALID_CHANGE_PATH"></a>
@@ -530,6 +572,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 +590,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/how-to-agent-gates.md

@@ -2,7 +2,7 @@
 
 ```bash
 npx arkgate-check --install-agent-gates
-npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity
 # aliases: ark-check …
 ```
 

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. |
@@ -173,9 +173,9 @@ product claims**. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, and `/graph` slices of the information package (no public / authless bind). Built-in stores are **InMemory reference only**. Branding ArkRun is not a production-durability claim. **`@arkgate/runtime` is deprecated** leftover 0.x (`experimental` dist-tag). |
+| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, and `/graph` slices of the information package (no public / authless bind). **Shadow / replay / compare** (`shadowInformationPackage`, `compareInformationPackages`, `replayInformationPackages`) are in-memory helpers on that snapshot — not durable, not a second bus (ADR 0033). Built-in stores are **InMemory reference only**. Branding ArkRun is not a production-durability claim. **`@arkgate/runtime` is deprecated** leftover 0.x (`experimental` dist-tag). |
 | **NestJS adapter** | **`arkgate/nestjs`** | Experimental optional peer `@nestjs/common` for the ArkRun kernel. Same npm package. `@arkgate/runtime/nestjs` is deprecated. |
-| **ArkOrder plane** | **`arkgate/order`** | Public brand **ArkOrder**. Same npm package `arkgate` (ADR 0030) — not `@arkgate/order`. Factory `createOrderPlane`. Four verbs: `release` / `project` / `ingest` / `proposeRelease`. No `update`. Haken: few slow keys; ingest never mints a pattern; empty blast fails closed. Root `arkgate` export does **not** include the factory. Optional extra `arkOrder` on schema `1.3`. In-memory; not durable. Does not replace ArkRun. |
+| **ArkOrder plane** | **`arkgate/order`** | Public brand **ArkOrder**. Same npm package `arkgate` (ADR 0030) — not `@arkgate/order`. Factory `createOrderPlane`. Four verbs: `release` / `project` / `ingest` / `proposeRelease`. No `update`. Haken: few slow keys; ingest never mints a pattern; empty blast fails closed. Factory options (not config keys): `informationBudget.cannotObserve`, `sigmaMaxAgeMs` (freshness on σ, never ξ). `IngestEscalate.target` includes `human`. Root `arkgate` export does **not** include the factory. Optional extra `arkOrder` on schema `1.3`. In-memory; not durable. Does not replace ArkRun. Runtime half (shadow/replay/compare) is ArkRun (ADR 0033). Canonical: [ArkOrder](arkorder.md). |
 
 ---
 
@@ -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.
 
@@ -219,7 +249,9 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current published: [4.8.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.3.md);
+(current tree prepared: [4.8.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.5.md);
+current published: [4.8.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.4.md);
+prior published: [4.8.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.3.md);
 prior published: [4.8.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.2.md);
 prior published: [4.8.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.1.md);
 prior published: [4.8.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.0.md);

package/docs/use.md

@@ -81,7 +81,7 @@ The config only binds when the write doesn’t land and CI is required.
 | **ArkGate** (layers) | Import rules. The write doesn’t land. The PR fails. | Always — this is the product |
 | **ArkRules** | Optional policies *inside* a layer. | Off until you turn it on (start may ship advisory templates) |
 | **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off. In-memory. Not Postgres. |
-| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`) | Off. Name `xiKeys` (plan / protocol, not `projectId`). Invoices and seats still flow. In-memory. Not durable. |
+| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Library + sensors, [not a service](arkorder.md). | Off. Name `xiKeys` (plan / protocol, not `projectId`). Invoices and seats still flow. In-memory. Not durable. |
 
 Start always gives you **layers**. Compact starters do **not** turn on ArkRun or
 ArkOrder. No extras is fine — only ArkGate runs. Leftovers are labeled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.3",
+  "version": "4.8.5",
   "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",
@@ -88,6 +88,7 @@
     "docs/assets",
     "docs/brownfield-adoption.md",
     "docs/configuration.md",
+    "docs/arkorder.md",
     "docs/package-surface.md",
     "docs/diagnostics.md",
     "docs/threat-model.md",
@@ -163,7 +164,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.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.8.3",
+      "version": "4.8.5",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/agent-skills/README.md

@@ -7,7 +7,7 @@
 This directory is the **Agent Skills–compatible** packaging of the same **13**
 `/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
 
-Package version when last generated context: **arkgate@4.8.3**
+Package version when last generated context: **arkgate@4.8.5**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -237,6 +237,11 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    to a compact starter. Do not promote to enforced as the session-0 default.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
    Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
+   The denial names its reason. `unclassifiable path` in bulk means shared code lives outside
+   the slice folders — declare those roots (`sharedRoots`) on the rule instead of treating
+   thousands of shared files as violations; `cross-slice edge a → b` is the real one, and a
+   deliberate directed edge goes in `allowedCrossSlice`. Promoting the shared slice to its own
+   layer is still the preferred fix.
    If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge:** rewrite `ark.config.json` **in this turn** with source evidence (do not freeze a wrong config or grind N freezes).
    Empty Domain/Persistence + I/O under Application → false-green.
    **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the config **in this turn** before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.

package/templates/agent-skills/ark-coverage/SKILL.md

@@ -92,6 +92,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
 4. Editing `arkrules/*` or promoting modes is **`/ark-adopt`** / leftover **`/ark-contract`**; fixing code under a structure sensor is leftover **`/ark-fix`** / **`/ark-loop`** or **`/ark-autopilot`** (judgment, never invent mechanical-safe).
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+5b. Invariant coverage is a **text match, never an execution**: a file walk plus the invariant id in a `describe`/`it` title. Never report `INVARIANT_UNCOVERED: 0` as “the tests pass” or “the tests run” — ArkGate does not run tests and reads no runner config. When the project declares `coverage.coverageRoots`, a covering test found outside them raises the advisory `INVARIANT_COVERAGE_OUTSIDE_ROOTS`; without that declaration ArkGate makes no claim about where tests run.
 6. Extras silent when off. Doctor `arkRun` is `notAScore`. Do not force extras. Do not invent `/ark-run` or `/ark-order`.
 
 

package/templates/agent-skills/ark-upgrade/SKILL.md

@@ -86,7 +86,7 @@ Never invent gate verdicts from these suggestions. Missing residual is honest em
 | Skills customized after install | Preserved by default. Preview `skillDrift` shows counts. **`--refresh-skills`** rewrites customized *skills* only with consent. |
 | Conflicted managed assets | Still need `--accept-conflicts`. Never silent overwrite of true edits. |
 | Multiple checkouts / monorepo packages | One `expectedRoot` per project; upgrade **each** pin; restart MCP after bump; prefer project-local CLI until identity matched **and** process version aligns. |
-| Stale `~/.claude/skills` or `~/.grok/skills` | Shared homes should be the newest ArkGate on the machine (additive; never downgrade). Refresh: `--install-agent-gates --skills-only --agent-homes --force`. Project skills may lag with the pin. |
+| Stale `~/.claude/skills`, `~/.grok/skills`, or `~/.gemini/config/skills` | Shared homes should be the newest ArkGate on the machine (additive; never downgrade). Refresh: `--install-agent-gates --skills-only --agent-homes --force`. Project skills may lag with the pin. Antigravity’s global catalog still refreshes when the project `.agents/skills` already exists. |
 | Active host not in `--tools` / manifest | Preview `hostSelection` notes it and suggests `--tools` expansion. |
 
 **Post-apply:** read `postUpgradeChecks` (advisory). Confirm pin↔CLI, run doctor (compass + deepModuleCoach),

package/templates/skills/ark-adopt.md

@@ -237,6 +237,11 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    to a compact starter. Do not promote to enforced as the session-0 default.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
    Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
+   The denial names its reason. `unclassifiable path` in bulk means shared code lives outside
+   the slice folders — declare those roots (`sharedRoots`) on the rule instead of treating
+   thousands of shared files as violations; `cross-slice edge a → b` is the real one, and a
+   deliberate directed edge goes in `allowedCrossSlice`. Promoting the shared slice to its own
+   layer is still the preferred fix.
    If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge:** rewrite `ark.config.json` **in this turn** with source evidence (do not freeze a wrong config or grind N freezes).
    Empty Domain/Persistence + I/O under Application → false-green.
    **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the config **in this turn** before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.

package/templates/skills/ark-coverage.md

@@ -92,6 +92,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
 4. Editing `arkrules/*` or promoting modes is **`/ark-adopt`** / leftover **`/ark-contract`**; fixing code under a structure sensor is leftover **`/ark-fix`** / **`/ark-loop`** or **`/ark-autopilot`** (judgment, never invent mechanical-safe).
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+5b. Invariant coverage is a **text match, never an execution**: a file walk plus the invariant id in a `describe`/`it` title. Never report `INVARIANT_UNCOVERED: 0` as “the tests pass” or “the tests run” — ArkGate does not run tests and reads no runner config. When the project declares `coverage.coverageRoots`, a covering test found outside them raises the advisory `INVARIANT_COVERAGE_OUTSIDE_ROOTS`; without that declaration ArkGate makes no claim about where tests run.
 6. Extras silent when off. Doctor `arkRun` is `notAScore`. Do not force extras. Do not invent `/ark-run` or `/ark-order`.
 
 

package/templates/skills/ark-upgrade.md

@@ -86,7 +86,7 @@ Never invent gate verdicts from these suggestions. Missing residual is honest em
 | Skills customized after install | Preserved by default. Preview `skillDrift` shows counts. **`--refresh-skills`** rewrites customized *skills* only with consent. |
 | Conflicted managed assets | Still need `--accept-conflicts`. Never silent overwrite of true edits. |
 | Multiple checkouts / monorepo packages | One `expectedRoot` per project; upgrade **each** pin; restart MCP after bump; prefer project-local CLI until identity matched **and** process version aligns. |
-| Stale `~/.claude/skills` or `~/.grok/skills` | Shared homes should be the newest ArkGate on the machine (additive; never downgrade). Refresh: `--install-agent-gates --skills-only --agent-homes --force`. Project skills may lag with the pin. |
+| Stale `~/.claude/skills`, `~/.grok/skills`, or `~/.gemini/config/skills` | Shared homes should be the newest ArkGate on the machine (additive; never downgrade). Refresh: `--install-agent-gates --skills-only --agent-homes --force`. Project skills may lag with the pin. Antigravity’s global catalog still refreshes when the project `.agents/skills` already exists. |
 | Active host not in `--tools` / manifest | Preview `hostSelection` notes it and suggests `--tools` expansion. |
 
 **Post-apply:** read `postUpgradeChecks` (advisory). Confirm pin↔CLI, run doctor (compass + deepModuleCoach),