arkgate 4.8.3 → 4.8.5

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-CzE6LMaW.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
@@ -1234,4 +1234,4 @@ interface CreateArkKernelFromConfigOptions extends Omit<CreateArkKernelOptions,
 }
 type ArkKernelConfig = ArkCheckConfig;
 
-export { ARK_RUN_INSPECTOR_GRAPH_PATH as $, type ArkKernel as A, type OutboxRecord as B, type CreateArkKernelOptions as C, type DefineIntentOptions as D, type EventContractRegistry as E, type ObservabilityDriftReport as F, type GraphEdge as G, ARK_RUN_COMPONENT_LIFETIMES as H, IntentRegistry as I, ARK_RUN_EPHEMERAL_DEFAULT as J, ARK_RUN_GRAPH_DEFAULT_SLICE as K, ARK_RUN_GRAPH_NODE_KINDS as L, type MetadataRegistry as M, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as N, type ObservabilityReporter as O, type ProjectionRegistry as P, ARK_RUN_GRAPH_SCHEMA_VERSION as Q, type ReadModelStore as R, type SagaContext as S, type TraceRecordType as T, ARK_RUN_GRAPH_SLICES as U, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as V, type WorkflowStore as W, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as X, ARK_RUN_INSPECTOR_DEFAULT_HOST as Y, ARK_RUN_INSPECTOR_DEFAULT_PORT as Z, ARK_RUN_INSPECTOR_EVENTS_PATH as _, type DependencyGraph as a, InvalidArkRunSendOptionError as a$, ARK_RUN_INSPECTOR_SCHEMA_VERSION as a0, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as a1, ARK_RUN_INSPECTOR_SSE_EVENT as a2, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as a3, ARK_RUN_TRANSPORT_KINDS as a4, type ArkManifestArchitecture as a5, type ArkManifestData as a6, type ArkManifestEntityLink as a7, type ArkManifestGraph as a8, type ArkManifestIntent as a9, type ArkRunInspectorSource as aA, type ArkRunInspectorTransportFacts as aB, type ArkRunPublisher as aC, type ArkRunRegisterOptions as aD, type ArkRunRegistrationHandle as aE, type ArkRunSendOptions as aF, type ArkRunSendPlan as aG, type ArkRunSendPlanInput as aH, type ArkRunSendResult as aI, type ArkRunTransportKind as aJ, type AuditRecordInput as aK, type AuditRecordType as aL, type DependencyInformationPackage as aM, type EntityMeta as aN, type EventContractIssue as aO, type EventHandler as aP, type EventInterceptionInfo as aQ, type EventInterceptor as aR, type EventInterceptorContext as aS, type EventPayloadPatch as aT, type EventPayloadSchema as aU, type EventPublisher as aV, type EventSchemaField as aW, type EventSchemaFieldType as aX, type FieldMeta as aY, type GraphNode as aZ, InvalidArkRunGraphQueryError as a_, type ArkManifestPolicy as aa, type ArkManifestProjection as ab, type ArkRunBrokerAdapter as ac, type ArkRunComponentLifetime as ad, type ArkRunDeliveredVia as ae, type ArkRunExtendedInfo as af, type ArkRunGraph as ag, type ArkRunGraphEdge as ah, type ArkRunGraphEdgeKind as ai, type ArkRunGraphMatch as aj, type ArkRunGraphMatchInput as ak, type ArkRunGraphNode as al, type ArkRunGraphNodeKind as am, type ArkRunGraphProcessEdgeKind as an, type ArkRunGraphQuery as ao, type ArkRunGraphResolvedQuery as ap, type ArkRunGraphSlice as aq, type ArkRunGraphTechnicalEdgeKind as ar, type ArkRunInformationPackageComponent as as, type ArkRunInspectorBind as at, ArkRunInspectorBindError as au, type ArkRunInspectorBindInput as av, type ArkRunInspectorHandle as aw, ArkRunInspectorProductionError as ax, type ArkRunInspectorSnapshot as ay, type ArkRunInspectorSnapshotInput as az, type AuditStore as b, type ObservabilityFlow as b0, type ObservedLayerFlowMode as b1, type OutboxStore as b2, type PolicyEvaluationResult as b3, type ProjectionCheckpoint as b4, type ProjectionDefinition as b5, type PublishedEventRecord as b6, type RetryPolicy as b7, type SagaStatus as b8, type SagaStep as b9, type StartArkRunInspectorOptions as ba, type TraceSink as bb, type Unsubscribe as bc, type WorkflowDefinition as bd, type WorkflowStatus as be, type WorkflowStep as bf, arkRunGraphQueryFromSearchParams as bg, arkRunInspectorUrl as bh, buildArkRunInspectorSnapshot as bi, buildDependencyInformationPackage as bj, closeArkRunGraphQuery as bk, closedArkRunEphemeral as bl, closedArkRunTransportKind as bm, formatArkRunGraphMermaid as bn, formatArkRunInspectorSseEvent as bo, isArkRunInspectorLoopbackHost as bp, isArkRunInspectorProductionEnv as bq, requestArkRunGraph as br, resolveArkRunInspectorBind as bs, resolveArkRunSendPlan as bt, startArkRunInspector as bu, type AuditRecord as c, type AuditQuery as d, type CreateAuditTrailOptions as e, type AuditTrail as f, type EventContract as g, type EventContractValidationResult as h, type CreateProjectionRegistryOptions as i, type EventBufferStore as j, type EventBufferRecord as k, type EventBufferStatus as l, type EventBusOptions as m, type EventBus as n, type CreateObservabilityReporterOptions as o, PolicyEngine as p, type ArkManifest as q, type WorkflowSnapshot as r, type SagaDefinition as s, type CreateWorkflowEngineOptions as t, type SagaInstance as u, type WorkflowEngine as v, type ArkKernelConfig as w, type CreateArkKernelFromConfigOptions as x, type TraceRecord as y, type OutboxStatus as z };
+export { ARK_RUN_INSPECTOR_EVENTS_PATH as $, type ArkKernel as A, type OutboxStatus as B, type CreateArkKernelOptions as C, type DefineIntentOptions as D, type EventContractRegistry as E, type OutboxRecord as F, type GraphEdge as G, type ObservabilityDriftReport as H, IntentRegistry as I, ARK_RUN_COMPONENT_LIFETIMES as J, ARK_RUN_EPHEMERAL_DEFAULT as K, ARK_RUN_GRAPH_DEFAULT_SLICE as L, type MetadataRegistry as M, ARK_RUN_GRAPH_NODE_KINDS as N, type ObservabilityReporter as O, type ProjectionRegistry as P, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as Q, type ReadModelStore as R, type SagaContext as S, type TraceRecordType as T, ARK_RUN_GRAPH_SCHEMA_VERSION as U, ARK_RUN_GRAPH_SLICES as V, type WorkflowStore as W, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as X, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as Y, ARK_RUN_INSPECTOR_DEFAULT_HOST as Z, ARK_RUN_INSPECTOR_DEFAULT_PORT as _, type DependencyGraph as a, InvalidArkRunSendOptionError as a$, ARK_RUN_INSPECTOR_GRAPH_PATH as a0, ARK_RUN_INSPECTOR_SCHEMA_VERSION as a1, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as a2, ARK_RUN_INSPECTOR_SSE_EVENT as a3, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as a4, ARK_RUN_TRANSPORT_KINDS as a5, type ArkManifestArchitecture as a6, type ArkManifestData as a7, type ArkManifestEntityLink as a8, type ArkManifestGraph as a9, type ArkRunInspectorSnapshotInput as aA, type ArkRunInspectorSource as aB, type ArkRunInspectorTransportFacts as aC, type ArkRunPublisher as aD, type ArkRunRegisterOptions as aE, type ArkRunRegistrationHandle as aF, type ArkRunSendOptions as aG, type ArkRunSendPlan as aH, type ArkRunSendPlanInput as aI, type ArkRunSendResult as aJ, type ArkRunTransportKind as aK, type AuditRecordInput as aL, type AuditRecordType as aM, type EntityMeta as aN, type EventContractIssue as aO, type EventHandler as aP, type EventInterceptionInfo as aQ, type EventInterceptor as aR, type EventInterceptorContext as aS, type EventPayloadPatch as aT, type EventPayloadSchema as aU, type EventPublisher as aV, type EventSchemaField as aW, type EventSchemaFieldType as aX, type FieldMeta as aY, type GraphNode as aZ, InvalidArkRunGraphQueryError as a_, type ArkManifestIntent as aa, type ArkManifestPolicy as ab, type ArkManifestProjection as ac, type ArkRunBrokerAdapter as ad, type ArkRunComponentLifetime as ae, type ArkRunDeliveredVia as af, type ArkRunExtendedInfo as ag, type ArkRunGraph as ah, type ArkRunGraphEdge as ai, type ArkRunGraphEdgeKind as aj, type ArkRunGraphMatch as ak, type ArkRunGraphMatchInput as al, type ArkRunGraphNode as am, type ArkRunGraphNodeKind as an, type ArkRunGraphProcessEdgeKind as ao, type ArkRunGraphQuery as ap, type ArkRunGraphResolvedQuery as aq, type ArkRunGraphSlice as ar, type ArkRunGraphTechnicalEdgeKind as as, type ArkRunInformationPackageComponent as at, type ArkRunInspectorBind as au, ArkRunInspectorBindError as av, type ArkRunInspectorBindInput as aw, type ArkRunInspectorHandle as ax, ArkRunInspectorProductionError as ay, type ArkRunInspectorSnapshot as az, type AuditStore as b, type ObservabilityFlow as b0, type ObservedLayerFlowMode as b1, type OutboxStore as b2, type PolicyEvaluationResult as b3, type ProjectionCheckpoint as b4, type ProjectionDefinition as b5, type PublishedEventRecord as b6, type RetryPolicy as b7, type SagaStatus as b8, type SagaStep as b9, type StartArkRunInspectorOptions as ba, type TraceSink as bb, type Unsubscribe as bc, type WorkflowDefinition as bd, type WorkflowStatus as be, type WorkflowStep as bf, arkRunGraphQueryFromSearchParams as bg, arkRunInspectorUrl as bh, buildArkRunInspectorSnapshot as bi, buildDependencyInformationPackage as bj, closeArkRunGraphQuery as bk, closedArkRunEphemeral as bl, closedArkRunTransportKind as bm, formatArkRunGraphMermaid as bn, formatArkRunInspectorSseEvent as bo, isArkRunInspectorLoopbackHost as bp, isArkRunInspectorProductionEnv as bq, requestArkRunGraph as br, resolveArkRunInspectorBind as bs, resolveArkRunSendPlan as bt, startArkRunInspector as bu, type AuditRecord as c, type AuditQuery as d, type CreateAuditTrailOptions as e, type AuditTrail as f, type EventContract as g, type EventContractValidationResult as h, type CreateProjectionRegistryOptions as i, type EventBufferStore as j, type EventBufferRecord as k, type EventBufferStatus as l, type EventBusOptions as m, type EventBus as n, type CreateObservabilityReporterOptions as o, PolicyEngine as p, type ArkManifest as q, type WorkflowSnapshot as r, type SagaDefinition as s, type CreateWorkflowEngineOptions as t, type SagaInstance as u, type WorkflowEngine as v, type DependencyInformationPackage as w, type ArkKernelConfig as x, type CreateArkKernelFromConfigOptions as y, type TraceRecord as z };

package/docs/README.md

@@ -36,6 +36,7 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 | [agent-guide.md](agent-guide.md) | Agent, CLI, and MCP reference (incl. `ark status --json` / MCP `ark_status`) |
 | [diagnostics.md](diagnostics.md) | Public diagnostic `ruleId` catalog (why / fix anchors) |
 | [configuration.md](configuration.md) | `ark.config.json` contract |
+| [arkorder.md](arkorder.md) | Optional ArkOrder extra: library + sensors, not a service |
 | [brownfield-adoption.md](brownfield-adoption.md) | Existing messy repos |
 | [package-surface.md](package-surface.md) | Stable vs experimental package surface |
 | [typescript-support.md](typescript-support.md) | TS 5 / 6 / 7 analysis boundary |
@@ -45,7 +46,7 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 |-----|------------|
 | [CONTRIBUTING.md](../CONTRIBUTING.md) | Setup, rules, PR/release |
 | [ROADMAP.md](../ROADMAP.md) | Live implementation queue (one `doing` at a time). History: [archive/roadmap-history.md](archive/roadmap-history.md) |
-| [adr/](adr/README.md) | Architecture decisions ([0032](adr/0032-writes-via-aggregate-sensor.md) writes-via-aggregate) |
+| [adr/](adr/README.md) | Architecture decisions ([0032](adr/0032-writes-via-aggregate-sensor.md) writes-via-aggregate · [0033](adr/0033-arkorder-runtime-half-is-arkrun.md) ArkOrder runtime half) |
 | [SECURITY.md](../SECURITY.md) · [threat-model.md](threat-model.md) | Security |
 
 ---
@@ -57,13 +58,13 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · npm [CHANGELOG.md](../CHANGELOG.md) (Unreleased + 4.6.x) · [pre-4.6 archive](archive/CHANGELOG-pre-4.6.md) |
-| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). [arkorder](plans/arkorder/README.md) (Phase OR; `OR01`–`OR07` done; shipped **4.8.0**; extra **inside** package `arkgate` as `arkgate/order`; ADRs [0027](adr/0027-arkorder-gated-extra-plane.md)–[0031](adr/0031-one-package-extras-deprecate-companion.md)). |
+| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). [arkorder](plans/arkorder/README.md) (Phase OR; `OR01`–`OR07` done; shipped **4.8.0**; extra **inside** package `arkgate` as `arkgate/order`; ADRs [0027](adr/0027-arkorder-gated-extra-plane.md)–[0031](adr/0031-one-package-extras-deprecate-companion.md)). [arkorder-arkrun](plans/arkorder-arkrun/README.md) (Phase XP; `XP01`–`XP08` done on tree; **4.8.5** prepared; ADR [0033](adr/0033-arkorder-runtime-half-is-arkrun.md)). |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | 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`).
-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).
+Current tree: [releases/4.8.5.md](releases/4.8.5.md) (`arkgate@4.8.5`, prepared). Current published: [releases/4.8.4.md](releases/4.8.4.md) (`arkgate@4.8.4` on npm `latest`; does not close `K01`).
+Prior: [releases/4.8.3.md](releases/4.8.3.md) · [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)
@@ -631,7 +809,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 | Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | **Repo:** `.agents/skills/<name>/SKILL.md` (same catalog as Codex). Do not also copy into `.cursor/commands/` or `$CODEX_HOME/skills` — Cursor lists every path it scans. |
 | OpenAI Codex | `.codex/config.toml` (project primary, relative `--root .`; configured on disk is not runtime-active until restart + `ark_identity` match); optional legacy `$CODEX_HOME/config.toml` fallback uses absolute roots and scoped secondaries — see [ai-gates.md](ai-gates.md) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$CODEX_HOME/skills/<name>/SKILL.md` (`--codex-home`) |
 | **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | **Repo:** `.grok/skills/<name>/SKILL.md`; **home:** `$GROK_HOME/skills` (default `~/.grok/skills`, `--grok-home`) |
-| Google Antigravity | `.agents/hooks.json` + `.agents/mcp_config.json` (+ `GEMINI.md` for shared Gemini consumers) | `.agents/skills/<name>/SKILL.md` |
+| Google Antigravity | `.agents/hooks.json` + `.agents/mcp_config.json` (+ `GEMINI.md` for shared Gemini consumers) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$ANTIGRAVITY_HOME/skills` (default `~/.gemini/config/skills`, `--antigravity-home`) |
 | OpenCode | `opencode.json` MCP (`type: local`; advisory) | `.opencode/skills/<name>/SKILL.md` |
 
 This is a path reference, not a guarantee table. Full copy-paste setups:
@@ -639,12 +817,12 @@ This is a path reference, not a guarantee table. Full copy-paste setups:
 [README](../README.md#other-skills-only-when-you-need-them).
 When several repositories share one machine, repo catalogs stay pinned and isolated; unchanged
 skill bodies are not rewritten for a version stamp. Shared **home** catalogs (Codex since 4.2;
-Claude/Grok since 4.6) are the machine floor: always latest additive, never downgrade. Refresh
-with `--agent-homes` (or `--claude-home` / `--grok-home` / `--codex-home`). Absent home trees
+Claude/Grok since 4.6; Antigravity since 4.8.5) are the machine floor: always latest additive, never downgrade. Refresh
+with `--agent-homes` (or `--claude-home` / `--grok-home` / `--antigravity-home` / `--codex-home`). Absent home trees
 are normal — doctor stays quiet until `ark-*` skills exist there. Pre-4.2 binaries ignore Codex
 home metadata and lock, so upgrade legacy repos before they write the optional Codex home
 catalog. See [AI gates — Codex skill catalog](ai-gates.md#codex-skill-catalog-skillmd-not-flat-prompts)
-and [shared Claude/Grok homes](ai-gates.md#shared-claude--grok-home-skills).
+and [shared Claude/Grok/Antigravity homes](ai-gates.md#shared-claude--grok-home-skills).
 
 ### Install skills — Ark and ecosystem {#install-skills-ark-and-ecosystem}
 
@@ -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/ai-gates.md

@@ -465,7 +465,7 @@ severity **info**, marked `deferred: true`, and omitted from doctor **Primary ne
 `/ark-upgrade` on Grok/Claude is not Incomplete because of them. **Temp/upgrade primary roots**
 stay fail-closed urgent (rewritten, not multi-project).
 
-### Shared Claude / Grok home skills {#shared-claude--grok-home-skills}
+### Shared Claude / Grok / Antigravity home skills {#shared-claude--grok-home-skills}
 
 Project catalogs follow that checkout’s ArkGate pin (they may lag). Shared user-home catalogs
 are the **machine floor**:
@@ -474,11 +474,19 @@ are the **machine floor**:
 |-------|------|------|
 | Claude home | `$CLAUDE_HOME/skills` (default `~/.claude/skills`) | `--claude-home` |
 | Grok home | `$GROK_HOME/skills` (default `~/.grok/skills`) | `--grok-home` |
-| All three + Codex | same monotonic protocol | `--agent-homes` |
+| Antigravity home | `$ANTIGRAVITY_HOME/skills` (default `~/.gemini/config/skills`) | `--antigravity-home` |
+| All four + Codex | same monotonic protocol | `--agent-homes` |
+
+Antigravity’s official global catalog is `~/.gemini/config/skills` (workspace catalog remains
+`.agents/skills`). Claude/Grok home copies override or duplicate the project catalog in the same
+session, so `--agent-homes` skips those homes when `.agents/skills` already exists. The Antigravity
+global catalog is the machine floor for **every** workspace, so `--antigravity-home` still writes
+it. `--prune-home-duplicates` does **not** delete `~/.gemini/config/skills/ark-*`.
 
 Doctor reports `agentHomeGaps` only when those catalogs already contain `ark-*` skills and
 lag the installed package. Temp/upgrade `--root` never mutates default user homes. Cursor
 sessions treat a stale Claude home as urgent because Cursor loads `~/.claude/skills`.
+Antigravity sessions treat a stale `~/.gemini/config/skills` catalog as urgent.
 
 ```bash
 npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
@@ -589,6 +597,8 @@ Install:
 npx ark-check --install-agent-gates --tools antigravity
 # alias:
 npx ark-check --install-agent-gates --tools agy
+# refresh the official global catalog (all workspaces):
+npx ark-check --install-agent-gates --skills-only --antigravity-home --force
 ```
 
 | File | Role |
@@ -597,6 +607,7 @@ npx ark-check --install-agent-gates --tools agy
 | `.agents/mcp_config.json` | Official workspace MCP (`mcpServers.ark` stdio) |
 | `GEMINI.md` | Instruction rule for Gemini CLI / legacy consumers sharing the tree |
 | `.agents/skills/*/SKILL.md` | Agent Skills catalog (shared path with Codex) |
+| `~/.gemini/config/skills/*/SKILL.md` | Official Antigravity **global** catalog (`--antigravity-home` / `--agent-homes`) |
 | `AGENTS.md` + `.mcp.json` + CI | Shared with other hosts (`.mcp.json` is not the Antigravity MCP path) |
 
 **Write tools covered:** `write_to_file`, `replace_file_content`, `multi_replace_file_content`.

package/docs/arkorder.md

@@ -0,0 +1,210 @@
+# ArkOrder
+
+**Write. Check. Ship.** Layers can be green while an agent still PATCHes the
+billing plan as if it were a seat count. ArkOrder is the extra that names the
+few slow product decisions and stops that write.
+
+Import: `arkgate/order` (same npm package `arkgate`). Off until you add
+`arkOrder` on schema `1.3`. Absence is silent. In-memory. Not durable. It is
+a library plus sensors, not a service. Does **not** replace ArkRun.
+
+First-contact copy: freeze / four verbs / no `update`. Haken (ξ vs s) lives
+below.
+
+Canonical plan seed: [plans/arkorder/README.md](plans/arkorder/README.md).
+ADRs: [0027](adr/0027-arkorder-gated-extra-plane.md)–[0030](adr/0030-opt-in-extras-same-npm-package.md),
+[0033](adr/0033-arkorder-runtime-half-is-arkrun.md) (runtime half is ArkRun).
+Config: [configuration.md](configuration.md). Surface:
+[package-surface.md](package-surface.md#experimental-opt-in-surfaces).
+
+---
+
+## What it is (and is not)
+
+| Is | Is not |
+|----|--------|
+| A **library** (`createOrderPlane`) plus **static sensors** | A running service, daemon, or hosted plane |
+| Four verbs: `release` / `project` / `ingest` / `proposeRelease` | A generic `update` / `patch` / `set` |
+| Opt-in extra on `ark.config.json` | Always-on; compact starters leave it off |
+| Consumer-named slow keys (`xiKeys`) | A construction OS, BIM, or FirmPack |
+| Same npm tarball | not `@arkgate/order` |
+
+If the extra is off, every ArkOrder sensor is silent. If it is on, the same
+write gate / CI / ESLint envelope as Layers applies. Domain stays plane-free:
+`createOrderPlane` lives in `arkOrder.planeRoots`.
+
+ArkRun is **how the app talks** (intents, transport, information package).
+ArkOrder is **what the app may treat as pattern**. Two extras. One activation
+shape (`mode` + `managedLayers`). Roots keep different names because they
+point at different factories: `arkRun.kernelRoots` vs `arkOrder.planeRoots`.
+`compositionRoots` remains an alias of `kernelRoots`. See
+[activation](#activation-same-shape-as-arkrun).
+
+---
+
+## Already shipped (named APIs)
+
+Adopters kept redesigning this extra because the names were not on one page.
+They already exist:
+
+| Ask | API | Since |
+|-----|-----|-------|
+| Escalation as a first-class concept | `IngestResult = IngestAbsorb \| IngestEscalate` (`kind`, `reason`) | 4.8.0 |
+| Projection at the boundary | `Projector = (release, sigma) => Projection` | 4.8.0 |
+| Cap on badly designed slow parameters | `DEFAULT_MAX_XI_KEYS = 7`, `maxXiKeys`, `ARKORDER_TOO_MANY_PARAMS`, `ARKORDER_EMPTY_XI`, `ARKORDER_NESTED_XI` | 4.8.0 |
+| Valved proposals, never direct mutation | `ProposeResult { nextXi, blastRadius, invalidations }` | 4.8.0 |
+| Typed cell schema | `XiSchema` / `XiPropertySchema` | 4.8.0 |
+| Named slow keys on the write path | `arkOrder.xiKeys`; `ARKORDER_XI_FIELD_WRITE` | 4.8.3 |
+| Factory isolation | `createOrderPlane` from `arkgate/order` only | 4.8.0 |
+| Information budget | `informationBudget.cannotObserve`; `ARKORDER_INFORMATION_BUDGET` | 4.8.5 |
+| σ freshness, never ξ | `sigmaMaxAgeMs` / `σ.freshUntil`; `ARKORDER_XI_TTL`, `ARKORDER_STALE_SIGMA` | 4.8.5 |
+| Escalate to a person | `IngestEscalate.target` including `human` | 4.8.5 |
+| Shadow / replay / compare | ArkRun `shadowInformationPackage` / `compareInformationPackages` / `replayInformationPackages` | 4.8.5 |
+
+Nothing here is a hosted runtime. Nothing here can be “down”. A degraded-mode
+contract would defend against an outage that cannot happen.
+
+---
+
+## Four verbs
+
+```ts
+import { createOrderPlane } from 'arkgate/order';
+
+const plane = createOrderPlane({
+  projector,          // consumer: (release, sigma) => { allowedKinds, invalidated }
+  xiSchema,           // JSON Schema object; additionalProperties false
+  maxXiKeys,          // default 7
+  clocks,             // injected; Domain must not call Date.now
+  packs,              // data, not user predicates
+  informationBudget,  // optional { cannotObserve: ['ledger'] } — not a config key
+  sigmaMaxAgeMs,      // optional σ freshness; never on ξ — not a config key
+});
+
+plane.release(xi, sigma);      // freeze, version, hash. No in-place mutate
+plane.project();               // derive allowed s + invalidations
+plane.ingest(event);           // absorb or escalate. Never returns a Release
+plane.proposeRelease(delta);   // blast radius. Empty blast = domain error
+```
+
+There is no `update()`. Calling `update` / `patch` / `set` on the plane throws
+`ARKORDER_FORBIDDEN_METHOD` and, on the write path, emits
+`ARKORDER_GENERIC_UPDATE`.
+
+| Field write | Verb |
+|-------------|------|
+| Invoice, seat within cap, timesheet, daily log | `ingest` → absorb |
+| Over cap / invariant pressure | `ingest` → escalate |
+| Change plan / protocol / cost-code bound | `proposeRelease` then `release` |
+| PATCH the slow key through Prisma/Drizzle | `ARKORDER_XI_FIELD_WRITE` |
+
+Copy [examples/arkorder-billing/](../examples/arkorder-billing/) and rename the
+three keys. Membership ids (`projectId`) are not keys: a `proposeRelease` that
+does not change `h(ξ)` fails closed (`ARKORDER_EMPTY_BLAST`).
+
+---
+
+## Config
+
+```json
+{
+  "schemaVersion": "1.3",
+  "arkOrder": {
+    "mode": "advisory",
+    "planeRoots": ["src/composition/order-plane.ts"],
+    "managedLayers": ["Application"],
+    "maxXiKeys": 7,
+    "xiKeys": ["plan", "cycle", "tenancy"]
+  }
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `mode` | `advisory` (default) or `enforced`. Same word as ArkRun / ArkRules |
+| `managedLayers` | Layers whose persistence writes of `xiKeys` are the skip |
+| `planeRoots` | Files allowed to call `createOrderPlane` |
+| `maxXiKeys` | Cap on ξ (default 7). Haken: few slow modes |
+| `xiKeys` | Optional 3–5 slow names. Empty → `ARKORDER_XI_FIELD_WRITE` silent |
+
+Unknown keys fail closed. Empty `planeRoots` in `enforced` fails
+`ARKORDER_MISSING_PLANE`. Demotion or deletion is a policy-delta **weakening**.
+This library’s 4-layer authoring contract does **not** turn the extra on.
+
+---
+
+## Activation (same shape as ArkRun)
+
+Both extras already share **`mode`** and **`managedLayers`**. They diverge on
+one axis: the factory root.
+
+| | ArkOrder | ArkRun |
+|--|----------|--------|
+| Extra key | `arkOrder` | `arkRun` |
+| Schema | `1.3+` | `1.2+` |
+| Factory | `createOrderPlane` from `arkgate/order` | `createStrictArkKernel` from `arkgate/runtime` |
+| Roots | `planeRoots` | `kernelRoots` (`compositionRoots` alias) |
+| Silence | absence of the extra | absence of the extra |
+
+Do not rename `planeRoots` to `kernelRoots`. They name different factories.
+List both on `ark-check --sensors` (same table, same tier vocabulary).
+
+Turn extras on with `/ark-adopt`. Place new files with `/ark-place`. There is
+no `/ark-order` skill.
+
+---
+
+## Sensors (closed)
+
+Direct evidence blocks. Inference never does. Default advisory; promotable
+except withdrawn heuristics.
+
+| Diagnostic | Skip |
+|------------|------|
+| `ARKORDER_MISSING_PLANE` | Extra on, no `createOrderPlane` in `planeRoots` |
+| `ARKORDER_KERNEL_IN_DOMAIN` | Domain-role layer imports `arkgate/order` |
+| `ARKORDER_GENERIC_UPDATE` | `update` / `patch` / `set` on the plane |
+| `ARKORDER_TOO_MANY_PARAMS` | ξ keys > `maxXiKeys` |
+| `ARKORDER_INGEST_WRITES_XI` | `ingest` result assigned into a Release / ξ store |
+| `ARKORDER_XI_FIELD_WRITE` | Managed-layer driver import **and** write token **and** a declared `xiKeys` name |
+| `ARKORDER_INFORMATION_BUDGET` | `h(ξ)` allows a kind in `informationBudget.cannotObserve` |
+| `ARKORDER_XI_TTL` | ξ named ttl/freshUntil/maxAge — freshness is σ |
+| `ARKORDER_STALE_SIGMA` | ingest after σ.freshUntil, or after `release.releasedAt` + `sigmaMaxAgeMs` |
+
+Why / fix: [diagnostics.md](diagnostics.md#ARKORDER_MISSING_PLANE).
+`ark-check --sensors` lists every extra sensor with plane, tier, and whether
+it can ever be enforced.
+
+---
+
+## Runtime half
+
+Shadow, replay, provenance, and compare belong to **ArkRun** (information
+package, inspector, in-memory compare). ArkOrder does not grow a bus, outbox,
+or hosted replay. [ADR 0033](adr/0033-arkorder-runtime-half-is-arkrun.md).
+
+Durability (`K01`) stays parked. In-memory is the honesty line.
+
+---
+
+## What we will not build here
+
+- another event bus
+- a general workflow engine
+- a permissions engine
+- a central store holding operational state
+- a DSL that duplicates domain / DB / ArkRules
+- a coordinator required on every request
+- a degraded-mode contract (nothing can be down)
+
+If a “slow parameter” changes with every click, it is not an order parameter.
+
+---
+
+## Next step
+
+```bash
+npx arkgate-check --doctor
+# copy examples/arkorder-billing/ and rename the three keys
+# /ark-adopt to turn arkOrder on advisory
+```