arkgate 4.8.8 → 4.8.10

package/dist/{types-BK47clMl.d.ts → types-Djbs3KjE.d.ts}

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

package/dist/{types-DxvmJO-D.d.ts → types-tGhZUiGX.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-BK47clMl.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-Djbs3KjE.js';
 
 /**
  * PolicyEngine

package/docs/README.md

@@ -66,13 +66,14 @@ 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)). [arkorder-arkrun](plans/arkorder-arkrun/README.md) (Phase XP; `XP01`–`XP08` done; shipped **4.8.5**; ADR [0033](adr/0033-arkorder-runtime-half-is-arkrun.md)). [arkorder-valve-loop](plans/arkorder-valve-loop/README.md) (Phase LV; `LV01`–`LV09` done; shipped **4.8.6**; [ADR 0034](adr/0034-arkorder-valved-loop.md); does not close K01). [layer-description-projection](plans/layer-description-projection/README.md) (Phase LD; `LD01`–`LD06` done; shipped **4.8.7**; [ADR 0035](adr/0035-layer-description-projection.md); project `layers[].description`; no schema bump). [observability-tui](plans/observability-tui/README.md) (`OD01`–`OD04` done on the **4.8.8 prepared tree**; not yet published; in-memory honesty retained). |
+| 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; shipped **4.8.5**; ADR [0033](adr/0033-arkorder-runtime-half-is-arkrun.md)). [arkorder-valve-loop](plans/arkorder-valve-loop/README.md) (Phase LV; `LV01`–`LV09` done; shipped **4.8.6**; [ADR 0034](adr/0034-arkorder-valved-loop.md); does not close K01). [layer-description-projection](plans/layer-description-projection/README.md) (Phase LD; `LD01`–`LD06` done; shipped **4.8.7**; [ADR 0035](adr/0035-layer-description-projection.md); project `layers[].description`; no schema bump). [observability-tui](plans/observability-tui/README.md) (`OD01`–`OD04` done; shipped **4.8.8**; in-memory honesty retained). |
 | 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) |
 
-Prepared: [releases/4.8.8.md](releases/4.8.8.md) (`arkgate@4.8.8`; not published).
-Current published: [releases/4.8.7.md](releases/4.8.7.md) (`arkgate@4.8.7` on npm `latest`; does not close `K01`).
+Prepared: [releases/4.8.10.md](releases/4.8.10.md) (`arkgate@4.8.10`; not published).
+Current published: [releases/4.8.9.md](releases/4.8.9.md) (`arkgate@4.8.9` on npm `latest`; does not close `K01`).
+Prior published: [releases/4.8.8.md](releases/4.8.8.md) (`arkgate@4.8.8`).
 Prior: [releases/4.8.6.md](releases/4.8.6.md) · [releases/4.8.5.md](releases/4.8.5.md) · [releases/4.8.4.md](releases/4.8.4.md) · [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

@@ -93,11 +93,26 @@ Default loop for each agent session (product language — no inventing residual)
    `unavailable`, run `ark-check --doctor` (and `--json` for the full 15-lens map) before treating
    residual as complete. When mode is `full`, status residual ids are a subset of doctor residual
    for the same facts.
+5. **Report ArkGate defects to upstream (human confirms first)** — if you find a bug, a false
+   green, a false red, a missing doc, or improvable behavior **in ArkGate itself** (the `arkgate`
+   package — not leftover design in the consumer app), run **`arkgate report` / `ark report`**
+   (existing dual bins — not a new skill). Default prints a draft GitHub issue for **upstream**
+   `pedroknigge/arkgate` (`package.json` `bugs.url`) with the installed arkgate version and an
+   optional last-check snippet. **Ask the human to confirm send.** Create only with `--submit`
+   **and** `--i-confirm-submit` (after they said yes) or a TTY `Type submit to send`. `--yes`
+   does not submit. One finding per invocation (`--finding <ref>`); otherwise one bundled field
+   report (`--title` is editable). If `gh` is missing or not logged in, the CLI prints the draft
+   plus the exact `gh issue create --repo pedroknigge/arkgate` command and exits 2. Never auto-file.
+   Never file ArkGate defects on the consumer product repo. This is not `ark-check --report` (HTML).
 
 ```bash
 npx ark status --json --expected-root /abs/project/root
 # mode !== full → full residual map:
 npx ark-check --doctor --json
+# draft an upstream issue (nothing created yet):
+npx ark report
+# after the human says yes — one finding, upstream only:
+npx ark report --submit --i-confirm-submit
 ```
 
 `--doctor --json` is a stable envelope (4.6.5+): `{ "schemaVersion": "1.0", "envelope": "doctor", "ok": boolean, "doctor": { … } }`.
@@ -358,7 +373,8 @@ into orchestration/persistence), `contract-lateral-adapter-allow` (adapter layer
 sibling adapter layer; X03 — an adapter into its OWN family's infra base, e.g.
 `PaymentsAdapters -> PaymentsInfra`, is the sanctioned direction and does not fire),
 `contract-dead-rule` (rule references an empty or unknown layer, or is a
-same-layer no-op; `optional: true` layers are exempt). Advisory only: it never changes the
+same-layer allow / classic same-layer deny; a same-layer `peerIsolation: true`
++ `allowed: false` wall is live, not this smell; `optional: true` layers are exempt). Advisory only: it never changes the
 verdict, `designFitness`, or `patternBets` — layer roles come from name heuristics, so treat a
 miss as a warning to read, not a defect to silence. A deliberate edge is acknowledged in
 `.ark/contract-smell-acks.json` (`{ acks: [{ id, edge, reason, reviewBy? }] }`); `acknowledged` counts
@@ -1095,7 +1111,7 @@ edges are not denied by that rule.
 - **`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).
+- Enforced by `ark-check`, `arkgate/eslint`, and `ark-mcp` (path-aware edges and path-less intent refs at declared event/saga/publish-metadata sites share the same SoT).
 - Fixes are **judgment** (not mechanical-safe).
 
 Agents can generate a config from the project's actual directory layout instead of inventing layer mappings:
@@ -1146,6 +1162,15 @@ Example config:
 plus intent/publish evidence. It uses the nearest `tsconfig.json` unless `--tsconfig` is set;
 importless type references are out.
 
+Intent-prefix checks (`LAYER_INTENT_REFERENCE_VIOLATION` on the candidate, write-hook
+`LAYER_REFERENCE_VIOLATION` / `UNKNOWN_INTENT`) apply only at declared intent-reference sites:
+`publish` / `subscribe` / `defineIntent` / `registerHandler` arguments, `intent` / `onEvent` /
+`reactsTo` properties, and publish `metadata.source` (or the 2nd/3rd-arg `source` object). A
+string that merely matches a layer prefix — including a kernel DType name such as
+`Management.EvmInspection.Data` — is not an intent reference. `looksLikeArkIntent` still
+classifies names; it is not a scan of every quoted string. There is no `kernel.dtypePrefixes`
+exemption list. Real event and saga string refs still fail closed.
+
 Each run parses the full candidate and ignores retired `.cache/ark-check.json`; `--no-cache` is a
 no-op. Z07 owns the identity-keyed snapshot after exact cold/warm parity.
 

package/docs/ai-gates.md

@@ -894,3 +894,11 @@ Adopting Ark on an existing codebase with violations? Freeze them once and ratch
 npx ark-check --update-baseline   # writes .ark-baseline.json — commit it
 npx ark-check --baseline          # only NEW violations fail
 ```
+
+`--update-baseline` also patches existing check **invocations** so CI keeps using the
+new freeze file: `package.json` scripts and GitHub workflow `run:` lines that already
+call `ark-check` / `arkgate-check` via `npx`, `pnpm`, `yarn`, `npm`, or `node`. Those
+writes are outside the three law files (`ark.config.json`, `arkrules/`,
+`.ark-baseline.json`) and are announced (`Synced --baseline into: …`). The matcher
+does **not** append `--baseline` to YAML that only *names* the check — a
+`concurrency.group` such as `ark-check-${{ github.ref }}`, or a job id `ark-check:`.

package/docs/arkorder.md

@@ -25,7 +25,7 @@ Config: [configuration.md](configuration.md). Surface:
 | Is | Is not |
 |----|--------|
 | A **library** (`createOrderPlane`) plus **static sensors** | A running service, daemon, or hosted plane |
-| Valved verbs: `release` / `project` / `ingest` / `proposeRelease` / `apply` / `refreshSigma` | A generic `update` / `patch` / `set` |
+| Valved verbs: `release` / `project` / `ingest` / `proposeRelease` / `apply` / `refreshSigma` / `restore` | 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` |
@@ -66,6 +66,9 @@ They already exist:
 | Capacity as data | `ConstraintPack.capacity` (`kind` / `sigmaKey` / `payloadKey` / `op`) | 4.8.6 |
 | Store port | `ReleaseStore` / `createMemoryReleaseStore` in-memory default — not durable, not K01 | 4.8.6 |
 | Thin travel helper | `ingestTravelAction` absorb→`send` / escalate_up human→`raises` | 4.8.6 |
+| Verify a stored `Release.hash` | `hashOf(ξ, σ)` alias of `hashReleasePayload` — no `release()` side effect | 4.8.9 |
+| Reinstall a frozen Release | `restore(release)` — process-local; hash is identity; not durable; does not close K01 | 4.8.9 |
+| Default clock | omitted `clocks` is Kernel `Date.now()`; Domain must not call `Date.now` | 4.8.9 |
 
 Nothing here is a hosted runtime. Nothing here can be “down”. A degraded-mode
 contract would defend against an outage that cannot happen.
@@ -77,13 +80,13 @@ contract would defend against an outage that cannot happen.
 **ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels.**
 
 ```ts
-import { createOrderPlane } from 'arkgate/order';
+import { createOrderPlane, hashOf, hashReleasePayload } 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
+  clocks,             // optional; default Kernel Date.now(); Domain must not call Date.now
   packs,              // data, not user predicates (capacity is kind/sigmaKey/payloadKey/op)
   informationBudget,  // optional { cannotObserve: ['ledger'] } — not a config key
   sigmaMaxAgeMs,      // optional σ freshness; never on ξ — not a config key
@@ -97,6 +100,8 @@ plane.ingest(event);           // residual absorb | escalate_up | hold. Never a
 plane.proposeRelease(delta);   // blast radius. Empty blast = domain error
 plane.apply(proposal);         // valve: later ξ change
 plane.refreshSigma(sigma);     // saldo / clocks; xiHash unchanged
+plane.restore(release);        // process-local install; hash is identity; not durable; not K01
+hashOf(xi, sigma);             // same bytes as hashReleasePayload; no freeze side effect
 ```
 
 There is no `update()`. Calling `update` / `patch` / `set` on the plane throws
@@ -112,9 +117,24 @@ There is no `update()`. Calling `update` / `patch` / `set` on the plane throws
 | Change plan / protocol / cost-code bound | `proposeRelease` then `apply` |
 | 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`).
+Gallery (not in the npm tarball):
+[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).
+Rename the three keys. Membership ids (`projectId`) are not keys: a
+`proposeRelease` that does not change `h(ξ)` fails closed (`ARKORDER_EMPTY_BLAST`).
+
+---
+
+## Ingest kinds vs payload (deliberate)
+
+`classifyIngest` uses `event.kind` for `escalateKinds` and `allowedKinds`.
+`ConstraintPack` is data-only: a function in the pack is `hold` with
+`reasonCode: pack` ([ADR 0016](adr/0016-arkrules-no-executable-core.md) /
+[ADR 0034](adr/0034-arkorder-valved-loop.md) D5). Capacity already compares
+numeric `payload[payloadKey]` against `sigma[sigmaKey]`.
+
+A payload-dependent story such as "second week failing a goal" is domain /
+projector work (a new kind, or that kind in `allowedKinds` when ξ says so).
+It is not a pack predicate. Do not add user functions to `ConstraintPack`.
 
 ---
 
@@ -204,6 +224,8 @@ 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.
+`restore(release)` reinstalls a frozen Release in this process. It is not a
+store. It does not close `K01`.
 
 ---
 
@@ -233,6 +255,7 @@ In-memory `ReleaseStore` is **not** durable. Doctor / status `arkOrder` stays
 
 ```bash
 npx arkgate-check --doctor
-# copy examples/arkorder-billing/ and rename the three keys
+# gallery (not in the npm tarball):
+# https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing
 # /ark-adopt to turn arkOrder on advisory
 ```

package/docs/brownfield-adoption.md

@@ -135,6 +135,36 @@ If Ark still refuses (a single edge dominates), the contract is still wrong —
 step 3; don't `--force` past it. From now `ark-check --baseline` fails only on NEW
 violations — the ratchet only moves toward zero.
 
+`ARKRULE_SCOPE_EMPTY` is a **config diagnostic**, not code debt. It is **not freezable**
+(even with `--force`). There is no `allowEmptyScope` key: an enforced rule whose
+`appliesTo` matches zero governed files is incomplete analysis and must not look green.
+
+### Law then product (when a rule needs a folder that does not exist yet)
+
+`mixed-law-and-product` still requires law files (`ark.config.json`, `arkrules/`,
+`.ark-baseline.json`) to travel without product. When the product folder is not there
+yet, do **not** freeze the empty-scope finding. Sequence:
+
+1. **Law PR (advisory or placeholder):** declare the ArkRule as `advisory`, *or* point
+   `appliesTo` at a tracked placeholder path that already exists. Empty enforced scope
+   fails the gate and cannot be baselined.
+2. **Product PR:** add the folder and the code so `appliesTo` matches governed files.
+3. **Law PR (promote):** raise the rule to `enforced` (hash-bound policy acknowledgement
+   when required). The ratchet then protects the now-visible scope.
+
+### STRUCTURE freeze keys include the sensor
+
+New `ARKRULE_STRUCTURE` keys are `ARKRULE_STRUCTURE|<file>|<layer>||<sensor>` (and
+`<sensor>:<symbol>` when a class/method symbol is known). A freeze for
+`orchestration-only` on a file must not silence `thin-adapter` or `writes-via-aggregate`
+on the same file.
+
+**v1 empty-target keys** (`ARKRULE_STRUCTURE|<file>|<layer>||`) still load as frozen
+residual, but they are **exact-match only**. They do not prefix-match every later sensor
+on that file — hidden new debt must not look green. After upgrade they go stale; re-freeze
+in a law PR (`--update-baseline --force --contract-session --author <steward>` as
+applicable) so new keys carry the sensor. Do not treat stale v1 rows as a wildcard mute.
+
 ## 5. Burn down, in order
 
 `summary.edges` is the burn-down order. Prefer `ark-check --plan`: it tags each step

package/docs/configuration.md

@@ -90,7 +90,13 @@ Top-level fields:
   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
+  Unknown keys fail closed. **`maxFiles` also bounds structural-hint preload** for
+  `orchestration-only`, `thin-adapter`, and `writes-via-aggregate` (the hint loader reuses
+  coverage contents when present). There is no separate `arkrules.hintBudget`. When eligible
+  governed files exceed that budget, the loader emits `ARKRULE_HINT_BUDGET_EXHAUSTED` with
+  exact hinted/governed counts and per-sensor reviewed N/M of scope; `--strict-config` fails
+  if an enforced hint sensor cannot see its scope. `--doctor` names this coupling.
+  When the coverage 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
@@ -126,17 +132,23 @@ Top-level fields:
   preflight / CI verdict and arm only when the layer plane is classified (same ≥50%
   governed and ≥1 populated-layer floor as ArkRules).
 - **`arkOrder`** (optional, schema `1.3+`) — inline ArkOrder extra (`mode`, `planeRoots`,
-  `managedLayers`, `maxXiKeys`, **`xiKeys`**). Absence is silent. Unknown keys fail closed.
-  Import `createOrderPlane` from `arkgate/order` (same package). Empty `planeRoots` in
-  `enforced` mode fails closed (`ARKORDER_MISSING_PLANE`). `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 and recomputable statuses
-  such as `paid` / `overdue` are not keys. Factory options
-  `informationBudget`, `sigmaMaxAgeMs`, `store` (`ReleaseStore`), and capacity packs
-  belong on `createOrderPlane`, not this extra object. Later ξ is `proposeRelease`
-  then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold`.
-  Demotion or deletion is a policy-delta **weakening**. Field ingest never mints
-  a pattern.
+  `managedLayers`, `maxXiKeys`, **`xiKeys`**, optional **`appliesTo`**). Absence is silent.
+  Unknown keys fail closed. Import `createOrderPlane` from `arkgate/order` (same package).
+  Empty `planeRoots` in `enforced` mode fails closed (`ARKORDER_MISSING_PLANE`).
+  `xiKeys` is a repo-wide watchlist of slow names the product already knows (plan,
+  protocol, cost-code bound). Empty `xiKeys` leaves `ARKORDER_XI_FIELD_WRITE` silent.
+  `maxXiKeys` (default 7) is the Haken cap on one `release()` / `assertXiKeyCap`, not
+  a cap on watchlist length: eight named `xiKeys` with `maxXiKeys` 7 is valid.
+  `ARKORDER_TOO_MANY_PARAMS` fires when `release()` `keyCount` exceeds `maxXiKeys`.
+  Optional `appliesTo` uses the same glob engine as `layers[].patterns`. Absence or
+  empty keeps current behavior (every file in `managedLayers`). Non-empty emits
+  `ARKORDER_XI_FIELD_WRITE` only when the layer is managed **and** the file matches
+  at least one glob. Membership ids and recomputable statuses such as `paid` /
+  `overdue` are not keys. Factory options `informationBudget`, `sigmaMaxAgeMs`,
+  `store` (`ReleaseStore`), and capacity packs belong on `createOrderPlane`, not this
+  extra object. Later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest
+  residual `absorb | escalate_up | hold`. 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
@@ -191,8 +203,36 @@ Rule fields:
 - `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).
+  when both paths classify. Applies to **any** declared `from`→`to` pair, not only self-edges.
+  Missing paths, empty slice folders, or unclassifiable slices **fail closed** (deny — cannot
+  prove same-slice).
+
+#### Cross-layer slice walls (already in the engine)
+
+A slice wall on a cross-layer edge is a `peerIsolation` rule on that `from`/`to` pair
+(`allowed: false`). There is no slice-wide engine mode, no new config key, and no new skill
+name. `findDeniedEdgeDecision` already applies `peerIsolation` to any declared pair
+(same-layer or cross-layer) — locked on `EdgeRule` and `findDeniedEdgeDecision` in
+[`src/domain/layerMatch.ts`](../src/domain/layerMatch.ts). There is no dedicated ADR to add.
+
+A feature slice is often cross-layer. Classic Application→Domain is allowed by omission, so
+`ApplicationOrchestration/management` importing `DomainModel/projects` is invisible to an
+Application→Application wall. Declare the cross-layer pair with the same `sliceFolders` /
+`sharedRoots` as the same-layer wall:
+
+```jsonc
+{
+  "from": "ApplicationOrchestration",
+  "to": "DomainModel",
+  "allowed": false,
+  "peerIsolation": true,
+  "sliceFolders": ["features"],
+  "sharedRoots": ["ui", "hooks"]
+}
+```
+
+Domain files that do not resolve to a slice **fail closed** unless they sit under a declared
+`sharedRoots` entry. Do not invent a sixth rule shape for this.
 
 #### Declared peerIsolation exceptions (4.8.4)
 
@@ -413,6 +453,13 @@ Write-gate ApplyPatch denies a batch that mixes law files with product source. H
 never hit PreToolUse are unchanged. Local `pnpm` gates should call `--changed --base`, not
 only full-tree `--strict-merge`.
 
+`--changed` honors the touched-file list for **file-local** ArkRules structure sensors
+(class shape, orchestration-only, thin-adapter, writes-via-aggregate) and for
+structural-hint preload. Import-edge, layer, and cycle sensors still evaluate the full
+governed graph. That is a bound on the existing scan, not a second analysis engine, and
+it does not turn a full-tree run into a seconds-long one. A `--changed` pass is not a
+full-tree structural verdict.
+
 MCP clients can call `ark_policy_delta` with the previous `baseConfig`, an optional candidate
 contract (the current project contract is the default), and the same optional acknowledgement.
 It invokes the public classifier directly, is read-only, and marks a blocking result as an MCP

package/docs/develop.md

@@ -214,8 +214,10 @@ First freeze is `release()`. Later pattern change is `proposeRelease` then
 `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data;
 `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`.
 
-Copy [examples/arkorder-billing/](../examples/arkorder-billing/) (`plan` / `cycle` /
-`tenancy`) and rename the keys. Posting an invoice is absorbed; changing plan is
+The billing gallery (`plan` / `cycle` / `tenancy`) lives on GitHub, not in the
+npm tarball:
+[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).
+Rename the keys. Posting an invoice is absorbed; changing plan is
 `proposeRelease` then `apply`. See [configuration.md](configuration.md) and
 [package-surface.md](package-surface.md).
 

package/docs/diagnostics.md

@@ -43,6 +43,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ARKRULE_STRUCTURE`](#ARKRULE_STRUCTURE) | arkrules | ArkRule structure sensor failed |
 | [`ARKRULE_INVARIANT`](#ARKRULE_INVARIANT) | arkrules | ArkRule invariant failed |
 | [`ARKRULE_SCOPE_EMPTY`](#ARKRULE_SCOPE_EMPTY) | arkrules | ArkRule appliesTo matched zero files |
+| [`ARKRULE_HINT_BUDGET_EXHAUSTED`](#ARKRULE_HINT_BUDGET_EXHAUSTED) | arkrules | Structural-hint budget exhausted |
 | [`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 |
@@ -279,6 +280,15 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 - **Why:** An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.
 - **Fix:** Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.
 
+<a id="ARKRULE_HINT_BUDGET_EXHAUSTED"></a>
+
+### `ARKRULE_HINT_BUDGET_EXHAUSTED`
+
+**Structural-hint budget exhausted**
+
+- **Why:** `orchestration-only`, `thin-adapter`, and `writes-via-aggregate` only evaluate files the hint loader preloaded. When eligible governed files exceed that budget (`coverage.maxFiles`, default `400` — there is no `arkrules.hintBudget`), those sensors never saw the rest of their scope. Enforced + unreviewed is not green. The finding names exact hinted/governed counts and per-sensor reviewed N/M of scope.
+- **Fix:** Raise `coverage.maxFiles` in ark.config.json (this cap also bounds structural-hint preload; `--doctor` names the coupling) so hinted/governed counts match, then re-run with `--strict-config`. An enforced hint sensor that cannot see its scope fails strict.
+
 <a id="INVARIANT_UNCOVERED"></a>
 
 ### `INVARIANT_UNCOVERED`

package/docs/package-surface.md

@@ -37,7 +37,8 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
-| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`); optional ArkRun **`ark-dashboard`** / **`arkgate-dashboard`** | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **Dashboard bins** poll an ArkRun inspector snapshot (ANSI + interval polling; `--url` / `--interval`); they are not a gate verdict. The main CLI also accepts `ark dashboard` / `arkgate dashboard` as a passthrough to those bins. |
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`); optional ArkRun **`ark-dashboard`** / **`arkgate-dashboard`** | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**, **report**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **`arkgate report` / `ark report`** drafts an upstream GitHub issue for `pedroknigge/arkgate` (`package.json` `bugs.url`) — never the consumer repo. **Dashboard bins** poll an ArkRun inspector snapshot (ANSI + interval polling; `--url` / `--interval`); they are not a gate verdict. The main CLI also accepts `ark dashboard` / `arkgate dashboard` as a passthrough to those bins. |
+| **Upstream report CLI (4.8.10)** | `arkgate report` / `ark report` on the existing dual bins (no new bin, no new skill) | Default prints a draft for **upstream** `pedroknigge/arkgate` (`package.json` `bugs.url`) with the arkgate version and optional last-check snippet. Create only with `--submit` **and** `--i-confirm-submit` (after HITL) or TTY `Type submit to send`. `--yes` does not submit. Missing/unauthenticated `gh`: print the draft plus the exact `gh issue create --repo pedroknigge/arkgate` command, exit 2. Never files against the consumer repo. Not `ark-check --report` (HTML architecture report). |
 | **Host write boundaries** | Generated trusted PreToolUse/preToolUse hooks + `ark-mcp --hook`; inspect with doctor/status | Hard is always operation-scoped and runtime-evidenced. From 4.6.3, Codex CLI and local ChatGPT Desktop/App Server can hard-block a complete `apply_patch` sent as `tool_input.command`; `.codex/hooks.json` on disk remains unverified until a fresh covered invocation. Hosted tools, specialized hook opt-outs, shell/direct writes, incomplete reconstruction, and humans rely on required CI. Repair envelopes may emit, but Codex reinjection is not guaranteed. |
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
 | **Improvement compass (4.4; status honesty 4.5)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. **`ark status --json` / MCP `ark_status`** project a thin `improvementCompass` residual map with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`). When `mode` is `full`, status residual lens **ids** are a **subset of** doctor residual for the same facts (report snapshot stores the thin slice after `--report`). Incomplete or missing session facts → `subset` / `unavailable` + `reasonCode` / `reason` — **never invent green residual**. Residual never flips `valid` / strict-merge / `goal.met`. When status mode ≠ full, run doctor for full 15-lens detail. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input. Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`; status: `projectStatusImprovementCompass` / `STATUS_COMPASS_MODES`. |
@@ -191,7 +192,7 @@ claims. Static architecture enforcement does not depend on them.
 |---------|-------------|--------|
 | **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, `/graph` slices of the information package, plus queue monitors **`GET /outbox`** and **`GET /workflows`** (full counts + sanitized samples capped at 32; no full event payloads; missing ports are unavailable; no public / authless bind). Snapshot `hardening.durability` classifies the explicit outbox/audit/workflow store ports; default `InMemory*` stores stay visibly `memory`, never durable. Dual bins **`ark-dashboard`** / **`arkgate-dashboard`** poll those JSON facts (ANSI TUI in `bin/` only — presentation is not in the kernel); `ark dashboard` / `arkgate dashboard` dispatch to the same executable. **Shadow / replay / compare** (`shadowInformationPackage`, `compareInformationPackages`, `replayInformationPackages`) are in-memory helpers on that snapshot — not durable, not a second bus (ADR 0033). **Decision tape** `decisionTape` `{ xiHash, event, residual }` via `appendDecisionTape` (ADR 0034). 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`. Valved verbs: `release` / `project` / `ingest` / `proposeRelease` / `apply` / `refreshSigma`. No `update`. First freeze is `release()`; later ξ change is `apply` (`ARKORDER_UNVALVED_RELEASE`). Haken: few slow keys; ingest residual `absorb | escalate_up | hold` + closed `reasonCode`; empty blast fails closed. Capacity pack as data (`kind` / `sigmaKey` / `payloadKey` / `op`). Factory options (not config keys): `informationBudget.cannotObserve`, `sigmaMaxAgeMs`, `store` (`ReleaseStore` / `createMemoryReleaseStore`), `catalogDigest`. Thin travel: `ingestTravelAction` absorb→`send` / escalate_up human→`raises`. `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 close K01. Does not replace ArkRun. Runtime half (shadow/replay/compare + `decisionTape` / `appendDecisionTape`) is ArkRun (ADR 0033 / 0034). Canonical: [ArkOrder](arkorder.md). |
+| **ArkOrder plane** | **`arkgate/order`** | Public brand **ArkOrder**. Same npm package `arkgate` (ADR 0030) — not `@arkgate/order`. Factory `createOrderPlane`. Valved verbs: `release` / `project` / `ingest` / `proposeRelease` / `apply` / `refreshSigma` / `restore`. No `update`. First freeze is `release()`; later ξ change is `apply` (`ARKORDER_UNVALVED_RELEASE`). `restore(release)` installs a previously frozen `Release` (hash remains identity; not durable). `hashOf` / `hashReleasePayload` verify a stored hash without a second freeze. Default Kernel clock is `Date.now()`. Optional `arkOrder.appliesTo` globs; `maxXiKeys` caps one `release()`, not `xiKeys.length`. Haken: few slow keys; ingest residual `absorb | escalate_up | hold` + closed `reasonCode`; empty blast fails closed. Capacity pack as data (`kind` / `sigmaKey` / `payloadKey` / `op`). Factory options (not config keys): `informationBudget.cannotObserve`, `sigmaMaxAgeMs`, `store` (`ReleaseStore` / `createMemoryReleaseStore`), `catalogDigest`. Thin travel: `ingestTravelAction` absorb→`send` / escalate_up human→`raises`. `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 close K01. Does not replace ArkRun. Runtime half (shadow/replay/compare + `decisionTape` / `appendDecisionTape`) is ArkRun (ADR 0033 / 0034). Billing gallery is git-only: [examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) (not in the npm tarball). Canonical: [ArkOrder](arkorder.md). |
 
 ---
 
@@ -201,7 +202,7 @@ claims. Static architecture enforcement does not depend on them.
 import { createAICodeGate } from 'arkgate';
 import { createStrictArkKernel, createStrictArkKernelFromConfig } from 'arkgate/runtime';
 import { ArkModule, InjectArk } from 'arkgate/nestjs';
-import { createOrderPlane } from 'arkgate/order';
+import { createOrderPlane, hashOf } from 'arkgate/order';
 ```
 
 One install: `npm install arkgate`. `@arkgate/runtime` is deprecated.
@@ -265,8 +266,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 tree candidate: [4.8.8.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.8.md), prepared and not published;
-current published: [4.8.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.7.md);
+(current published: [4.8.9.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.9.md);
+prior published: [4.8.8.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.8.md);
+prior published: [4.8.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.7.md);
 prior published: [4.8.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.6.md);
 prior published: [4.8.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.5.md);
 prior published: [4.8.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.4.md);

package/docs/use.md

@@ -163,12 +163,23 @@ Short loop so agents do not invent residual or re-run doctor every message:
    **`unavailable`** (or compass facts are missing), run `npx ark-check --doctor` (add `--json` for
    the full 15-lens map) before treating residual as complete. When mode is **`full`**, status
    residual ids are a safe subset of doctor residual for the same facts.
+5. **If ArkGate itself is wrong** — run `npx arkgate report` (alias `ark report`). Default prints
+   a draft GitHub issue for **upstream** `pedroknigge/arkgate` (`package.json` `bugs.url`) with
+   the arkgate version and last-check snippet. **Ask the human to confirm send.** Create only
+   with `--submit` and `--i-confirm-submit` (or TTY `Type submit to send`). `--yes` does not
+   submit. If `gh` is missing, the command prints the draft plus `gh issue create --repo
+   pedroknigge/arkgate …` and exits 2. Never auto-file. Never file ArkGate defects on the
+   consumer product repo. Not `arkgate-check --report` (HTML).
 
 ```bash
 npx ark status --json --expected-root /abs/project/root
 # when mode is not full:
 npx ark-check --doctor
 npx ark-check --doctor --json   # doctor.improvementCompass
+# draft an upstream issue (nothing created yet):
+npx ark report
+# after the human says yes — one finding, upstream only:
+npx ark report --submit --i-confirm-submit
 ```
 
 Details: [agent-guide — Session recipe](agent-guide.md#session-recipe-agent-turn) ·

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.8",
+  "version": "4.8.10",
   "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",

package/schemas/ark.config.schema.json

@@ -837,7 +837,7 @@
     "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.",
+      "description": "Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget and also bounds structural-hint preload for orchestration-only, thin-adapter, and writes-via-aggregate (default 400; there is no arkrules.hintBudget); 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",
@@ -850,7 +850,8 @@
         },
         "maxFiles": {
           "type": "integer",
-          "minimum": 1
+          "minimum": 1,
+          "description": "Evidence file budget (default 400) and structural-hint preload cap for orchestration-only, thin-adapter, and writes-via-aggregate. Raise this when hinted/governed counts show truncated sensors. There is no separate arkrules.hintBudget."
         },
         "coverageRoots": {
           "type": "array",
@@ -954,6 +955,15 @@
           },
           "uniqueItems": true,
           "default": []
+        },
+        "appliesTo": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
         }
       }
     }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.8.8",
+  "version": "4.8.10",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.8.8",
+      "version": "4.8.10",
       "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.6**
+Package version when last generated context: **arkgate@4.8.9**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

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

@@ -45,7 +45,7 @@ Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrd
 
 Application / Features may declare advisory **`writes-via-aggregate`**: a use-case that imports a persistence driver and calls `.insert` / `.create` / `INSERT INTO` is the skip. Persistence adapters stay the write edge. Do not add `Externals/` or `admission.ts` as contract law.
 
-When `arkOrder` is on, name **`xiKeys`** (3–5 slow product decisions). Membership ids and recomputable statuses are not keys: derive a status on read or fold it from ingest instead. A use-case that persists those keys is `ARKORDER_XI_FIELD_WRITE`. First freeze is `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore`; ArkRun `decisionTape`. Copy [examples/arkorder-billing/](../../../examples/arkorder-billing/) and rename the three keys. The check remains silent on semantic entailment.
+When `arkOrder` is on, name **`xiKeys`** (3–5 slow product decisions). Membership ids and recomputable statuses are not keys: derive a status on read or fold it from ingest instead. A use-case that persists those keys is `ARKORDER_XI_FIELD_WRITE`. First freeze is `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore`; ArkRun `decisionTape`. The billing gallery lives on GitHub, not in the npm tarball: [examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing). Rename the three keys. The check remains silent on semantic entailment.
 
 ## Subagent fan-out (optional, host-dependent)
 

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

@@ -19,6 +19,7 @@ description: Map import rules and leftover design. No apply. CLI is a sensor; yo
 - Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
 - Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
 - Hook green is not tree green (scripted edits bypass PreToolUse).
+- Bug / false green / false red / missing doc / improvable behavior **in ArkGate itself** → draft one upstream GitHub issue (`pedroknigge/arkgate` or the installed package `repository.url`), **ask the human to confirm send**, then `gh issue create`. Never auto-file. Never file ArkGate defects on the consumer product repo.
 
 ## Autonomy contract
 
@@ -27,7 +28,24 @@ incomplete. **Do not write** config or product code (that is `/ark-adopt` / `/ar
 **CLI budget:** one doctor / coverage; then open ≥12 files across ≥4 dirs; then the map.
 
 **Still never:** weaken the config; invent `mechanical-safe` kinds; claim healthy because
-plan A is empty while leftover design work remains.
+plan A is empty while leftover design work remains; auto-file GitHub issues; file ArkGate
+defects on the consumer product repo; skip the human confirm step.
+
+## Report ArkGate defects (ask first)
+
+This skill maps **this** tree. If recon shows a bug, false green, false red, missing doc, or
+improvable behavior **in ArkGate itself** (the `arkgate` package — not leftover design in the
+consumer app):
+
+1. Draft one GitHub issue for **upstream** (`pedroknigge/arkgate`, or `package.json`
+   `repository.url` of the installed `arkgate` package).
+2. **Ask the human in the loop to confirm send.** Do not create the issue until they say yes.
+3. If confirmed, `gh issue create` with the logged-in account. One finding per issue. Include
+   repro commands, version, and measured evidence.
+4. Never auto-file, batch-spam, or skip confirm. Never file ArkGate defects on the consumer
+   product repo.
+
+Reporting is not applying product code. Stay map-only on this tree.
 
 Use when you need a decision-grade map or the **Primary post-green door**; hand off to
 `/ark-autopilot` to apply. Day-to-day place + gate work does not require this skill.
@@ -168,7 +186,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ### Explore + extras
 - Map extras when present; never write `arkRun` / `arkOrder`. Extra off → residual `n/a` / silent.
 - When `arkOrder` is on, name the valve: first freeze `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore` (`createMemoryReleaseStore`); thin travel `ingestTravelAction`. ArkRun residual may include information package `decisionTape` `{ xiHash, event, residual }`.
-- Field path may name `examples/arkorder-billing/` (ArkOrder fixture — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
+- Field path may name the ArkOrder gallery on GitHub (`https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing`; not in the npm tarball — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
 
 ## Output mode (pick one — do not invent a fourth)
 
@@ -297,7 +315,7 @@ When `examples/`, `templates/`, gallery starters, eval fixtures, or docs claim
 3. Diff **rule strength** across archetypes (missing denies = soft false-green for consumers).
 4. Note import style vs package surface docs (`arkgate` root barrel vs preferred subpath).
 5. Flag **false promises**: demo fails under its own check, or green with a hollow contract.
-6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name `examples/arkorder-billing/`. Never write extras from this skill.
+6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name the ArkOrder gallery on GitHub (`https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing`; not in the npm tarball). Never write extras from this skill.
 
 If the repo is a **pure app** (no examples): state **Field path: internal** and do one of:
 - Name the **norm for new code** that the residual implies (e.g. “no new `platform/db` in routes”), or
@@ -431,6 +449,9 @@ Optional: **Diff vs naive sensor-only read** (what reading the tree changed).
 - Mode respected: no multi-week roadmap in recon mode; dual-plan seed capped at 3–5 B bets.
 - Clear handoff: `/ark-adopt` | `/ark-autopilot` | `/ark-place` | CLI | `stop`.
 - No gate weakening; no false ENFORCE claim; no README echo as primary content.
+- If you found a bug / false green / false red / missing doc / improvable behavior in the
+  **ArkGate package**, you drafted one upstream issue, asked the human to confirm, and did not
+  `gh issue create` until they said yes. Never filed it on the consumer repo.
 
 ## Completion contract (skill incomplete if missing)