arkgate 4.8.23 → 4.8.25

package/docs/arkorder.md

@@ -58,8 +58,8 @@ They already exist:
 | Escalation as a first-class concept | `IngestResult` residual `absorb \| escalate_up \| hold` (`reasonCode`, `IngestEscalate.target`) | 4.8.0 / 4.8.6 |
 | 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` then `apply` (`ARKORDER_UNVALVED_RELEASE`) | 4.8.0 / 4.8.6 |
-| Typed cell schema | `XiSchema` / `XiPropertySchema` | 4.8.0 |
+| Valved proposals, never direct mutation | `ProposeResult` then `apply` (`ARKORDER_UNVALVED_RELEASE`); a proposal carries `baseXiHash` / `baseVersion`; a stale one, one without that binding, or one whose blast radius is not the transition that would commit fails `ARKORDER_STALE_PROPOSAL`. The binding is data, not a capability: an object that states the current base and the exact transition applies whoever built it | 4.8.0 / 4.8.6 |
+| Typed cell schema | `XiSchema` / `XiPropertySchema` / `XiPrimitive` (finite numbers only; NaN / ±Infinity fail `ARKORDER_NESTED_XI`) | 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 |
@@ -69,10 +69,10 @@ They already exist:
 | Decision tape | ArkRun information package `decisionTape` `{ xiHash, event, residual }` | 4.8.6 |
 | σ vs ξ identity | `xiHash` / `sigmaHash` / `refreshSigma` | 4.8.6 |
 | 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 |
+| Store port | `ReleaseStore` / `createMemoryReleaseStore` in-memory default — not durable, not K01. `load()` output is validated like `restore()`: JSON copies are accepted; hashes are recomputed from ξ / σ and an inconsistent one fails closed; a `releasedAt` (or σ.`releasedAt`) after the plane clock fails closed, so a rewritten timestamp cannot switch off σ staleness. Hashes are a consistency check, not a signature — authenticity stays the store's job. The plane advances only after `save()` returns | 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 |
+| Reinstall a Release | `restore(release)` — frozen or JSON-deserialized; hash is identity; onto an empty plane, or the same ξ at the current version or the next one. Never changes ξ, never rolls the version back, never jumps it (`ARKORDER_UNVALVED_RELEASE`); a freeze time after the plane clock fails closed. Process-local; 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
@@ -102,10 +102,10 @@ const plane = createOrderPlane({
 plane.release(xi, sigma);      // first freeze only
 plane.project();               // derive allowed s + invalidations
 plane.ingest(event);           // residual absorb | escalate_up | hold. Never a Release
-plane.proposeRelease(delta);   // blast radius. Empty blast = domain error
-plane.apply(proposal);         // valve: later ξ change
+plane.proposeRelease(delta);   // blast radius, bound to the current Release. Empty blast = domain error
+plane.apply(proposal);         // valve: later ξ change; stale proposal = ARKORDER_STALE_PROPOSAL
 plane.refreshSigma(sigma);     // saldo / clocks; xiHash unchanged
-plane.restore(release);        // process-local install; hash is identity; not durable; not K01
+plane.restore(release);        // reinstall (same ξ, current or next version); not durable; not K01
 hashOf(xi, sigma);             // same bytes as hashReleasePayload; no freeze side effect
 ```
 
@@ -114,6 +114,12 @@ There is no `update()`. Calling `update` / `patch` / `set` on the plane throws
 `ARKORDER_GENERIC_UPDATE`. A second `release()` whose ξ differs fails
 `ARKORDER_UNVALVED_RELEASE`.
 
+`release`, `proposeRelease`, `apply`, `refreshSigma`, and `restore` check the
+candidate projection against `informationBudget` before the Release is offered
+or persisted (`ARKORDER_INFORMATION_BUDGET`), so a denied pattern never lands.
+σ goes stale after a numeric `σ.freshUntil` on its own, or after
+`sigmaMaxAgeMs` when σ has no `freshUntil`.
+
 | Field write | Verb |
 |-------------|------|
 | Invoice, seat within cap, timesheet, daily log | `ingest` → absorb (`ingestTravelAction` may `send`) |
@@ -209,13 +215,22 @@ except withdrawn heuristics.
 |------------|------|
 | `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_GENERIC_UPDATE` | `update` / `patch` / `set` on a plane receiver: bound to `createOrderPlane(...)` in the file, annotated `: OrderPlane`, a `plane` / `*Plane` import from a `planeRoots` module, or a `plane` / `*Plane` name in a file that imports `arkgate/order`. A name alone (`clipPlane`, `controlPlane`) is not evidence |
 | `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` |
+| `ARKORDER_INGEST_WRITES_XI` | `ingest` result assigned into a Release / ξ holder (`release`, `xi`, `xiNext`, `nextXi`, `currentRelease`, `store.xi`, …); a prefix alone (`releaseState`, `currentResidual`) is not evidence |
+| `ARKORDER_XI_FIELD_WRITE` | Managed-layer driver import **and** a write on a persistence client (`db` / `prisma` / …, `new PrismaClient()`, a name bound to a driver constructor or annotated with a client type, or imported from a local `db` / `orm` / … module) **and** a declared `xiKeys` name |
+| `ARKORDER_INFORMATION_BUDGET` | A literal `allowedKinds` entry that a literal `informationBudget.cannotObserve` denies |
+| `ARKORDER_XI_TTL` | ttl/freshUntil/maxAge (shorthand included) in the ξ literal of `plane.release` / `plane.proposeRelease` on a plane receiver — freshness is σ |
+
+Runtime `ArkOrderError` codes (thrown by the plane; not static sensors, not
+promoted by `arkOrder.mode`):
+
+| Code | Thrown when |
+|------|-------------|
+| `ARKORDER_STALE_SIGMA` | ingest after σ.freshUntil, or after `release.releasedAt` + `sigmaMaxAgeMs` (ingest returns `hold`, reason `stale-sigma`) |
+| `ARKORDER_STALE_PROPOSAL` | `apply` gets a proposal not computed against the current Release |
+| `ARKORDER_UNVALVED_RELEASE` | a second `release` with a different ξ, or a `restore` that changes ξ / rolls the version back |
+| `ARKORDER_INFORMATION_BUDGET` / `ARKORDER_XI_TTL` | also thrown at runtime, whatever the static sensor saw |
 
 Why / fix: [diagnostics.md](diagnostics.md#ARKORDER_MISSING_PLANE).
 `ark-check --sensors` lists every extra sensor with plane, tier, and whether
@@ -230,8 +245,10 @@ 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`.
+`restore(release)` reinstalls a validated Release in this process: onto an
+empty plane, or the same ξ at the current version or the next one. It is
+not a store and not a rollback (that is `proposeRelease` then `apply`). It does
+not close `K01`.
 
 ---
 

package/docs/brownfield-adoption.md

@@ -101,7 +101,11 @@ ark-check --rules-inventory --json
 # MCP: ark_rules_inventory
 ```
 
-Output is **honest counts** (inventoried / under-contract / frozen) — never a score. Route
+Output is **honest counts** (inventoried / under-contract / frozen) — never a score. A
+structure candidate is under contract when its layer declares a rule on the suggested
+**sensor** (the rule id is yours to name); an invariant candidate by its id. Frozen counts the
+ArkRules-plane keys (`ARKRULE_*` / `INVARIANT_*`) in `.ark-baseline.json`. `--doctor` shows the
+same counts as `rulesMigration` (JSON and human line), and the MCP payload matches the CLI. Route
 extraction through `/ark-fix` or `/ark-loop` (one pilot card at a time) and declaration
 through `/ark-contract` editing `arkrules/<Layer>.json` (ADR 0015 — no new skill names).
 Report residual as **`[Layer]`** (import edges / baseline) vs **`[ArkRules]`** (inventory /

package/docs/configuration.md

@@ -74,7 +74,9 @@ Invalid ArkGate config (/repo/ark.config.json):
 - $.layers[0].forbiddenGlobal: unknown field
 ```
 
-The same input cannot pass CI while being silently ignored by MCP or ESLint. Invalid JSON, wrong
+The same input cannot pass CI while being silently ignored by MCP or ESLint. In ESLint an
+invalid contract (root config or a referenced ArkRules file) is one `configInvalid` error per
+linted file with the same validator text; it does not crash the lint run. Invalid JSON, wrong
 types, empty required strings, duplicate string-array entries, negative safety thresholds, and
 unsupported schema versions also fail before scanning begins.
 
@@ -130,9 +132,24 @@ Top-level fields:
   `enforced`. Declaring nothing stays silent unless any invariant is already enforced — then
   missing roots fail closed (`INVARIANT_COVERAGE_ROOTS_MISSING`), because otherwise coverage can
   certify a test the project never declared a runner root for.
-- **`arkRules`** (optional, schema `1.1+`) — map of layer name → project-relative path to an
-  ArkRules file (e.g. `"DomainModel": "arkrules/DomainModel.json"`). Keys must match a declared
-  layer. Missing/invalid referenced files **fail closed**.
+
+  ArkGate never executes tests — except the opt-in `arkgate-check --probe-invariants`, which
+  you run yourself: it breaks an invariant's `coverage.symbol` on purpose in a temporary copy
+  and runs only its covering tests with your own runner. Its committed result
+  (`.ark/invariant-probe.json`) can only **refuse** a promotion, never grant one, and it is
+  never part of a check or the merge gate. No config key. See
+  [Probe an invariant](agent-guide.md#probe-an-invariant).
+- **`arkRules`** (optional, schema `1.1+`) — map of layer name → one project-relative path, or a
+  list of paths merged into that layer's catalog (`"DomainModel": "arkrules/DomainModel.json"`
+  or `"DomainModel": ["arkrules/DomainModel.json", "arkrules/DomainModel.shared.json"]`). A
+  string keeps today's behaviour. Keys must match a declared layer. The same effective id in
+  two files is `ARKRULE_DUPLICATE_ID` and config load fails closed. Missing or invalid
+  referenced files **fail closed**. A `arkrules/*.json` file the map does not reference, and a
+  slice file named `arkrules.<Layer>.json` beside governed code that discovery did not read,
+  is advisory drift: `ARKRULE_FILE_UNREFERENCED` in check `warnings`,
+  `rulesUnderContract.unreferencedFiles` in doctor, and `arkRulesCatalog.unreferencedFiles` in
+  MCP `ark_manifest`. It never fails the check. Doctor `rulesUnderContract.bySlice` lists the
+  rules a child slice contributed. `ark_place` shows those ids as `sliceRules` next to the layer.
 - **`arkRun`** (optional, schema `1.2+`) — inline ArkRun extra (`mode`, `kernelRoots`
   (`compositionRoots` alias), `managedLayers`, `requireDeclarations`). Absence is silent. Unknown keys fail closed.
   `managedLayers` must name existing `layers[].name` values. Empty `compositionRoots` in
@@ -142,6 +159,19 @@ Top-level fields:
   is a policy-delta **weakening**. Enforced extra teeth share the CLI / MCP / hook /
   preflight / CI verdict and arm only when the layer plane is classified (same ≥50%
   governed and ≥1 populated-layer floor as ArkRules).
+  Kernel factories in a root: `createArkKernel` / `createStrictArkKernel` /
+  `createLenientArkKernel`, their `*FromConfig` variants, or `ArkModule.forRoot()` /
+  `forRootAsync()` imported from `arkgate/nestjs`. Undeclared-* sensors count only calls
+  whose receiver is traced to the kernel (factory-bound local, import from a root module —
+  resolved through tsconfig `paths` and barrels that re-export it — a plain alias
+  `const kernel = ark`, a `typeof ark` binding, a binding typed `ArkKernel` / `EventBus` /
+  publisher from `arkgate/runtime` or `arkgate/nestjs`, its `.eventBus`, a `publisher(..)`
+  result), or whose receiver cannot be traced but whose literal name is a kernel-valid
+  intent (`Domain.…`, `Application.…`) — `res.send('ok')` or `require.resolve('pkg')` never
+  count. Call names are a string literal or a same-file
+  `define(..)` / `defineIntent(..)` creator (or string constant); anything else in
+  `enforced` mode reports `ARKRUN_INTERACTION_NAME_INCOMPLETE` (partial). See
+  [diagnostics](diagnostics.md#ARKRUN_MISSING_ROOT).
 - **`arkOrder`** (optional, schema `1.3+`) — inline ArkOrder extra (`mode`, `planeRoots`,
   `managedLayers`, `maxXiKeys`, **`xiKeys`**, optional **`appliesTo`**). Absence is silent.
   Unknown keys fail closed. Import `createOrderPlane` from `arkgate/order` (same package).
@@ -157,7 +187,11 @@ Top-level fields:
   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
+  extra object. Literal evidence of either still reports statically: a ttl/freshUntil/maxAge
+  key in a plane `release` / `proposeRelease` ξ literal (`ARKORDER_XI_TTL`), and a literal
+  `allowedKinds` entry denied by a literal `cannotObserve` (`ARKORDER_INFORMATION_BUDGET`).
+  Later ξ is `proposeRelease` then `apply` (a stale proposal fails
+  `ARKORDER_STALE_PROPOSAL`); `refreshSigma`; ingest
   residual `absorb | escalate_up | hold`. Demotion or deletion is a policy-delta
   **weakening**. Field ingest never mints a pattern.
 
@@ -230,6 +264,18 @@ That sentence is product copy. Not “Rich domain model, business rules, and dom
 ```
 
 - `intentPrefixes`, `forbiddenGlobals`, `mayImportInfrastructure`, `optional`
+  — `intentPrefixes` is how the ArkRun kernel maps an intent name to a layer at runtime.
+  A layer with a canonical 11-layer name (`DomainModel`, `ApplicationOrchestration`,
+  `PersistenceAdapters`, … — what `ark init` writes) and no `intentPrefixes` gets the
+  built-in prefixes (`Domain.`, `Application.`, `Adapter.Persistence.`, …), so default configs
+  enforce hard observed-layer-flow as-is. A custom-named layer in an `allowed: false` rule
+  with no `intentPrefixes` cannot map any intent: `createStrictArkKernelFromConfig` /
+  `createArkKernelFromConfig` still build (strict default) and record one
+  `layer.observedFlowUnresolvable` audit record (`ARKRUN_LAYER_FLOW_UNRESOLVABLE`), and
+  `ark doctor` lists those layers when the `arkRun` extra is on. Passing
+  `enforceObservedLayerFlow: 'hard'` explicitly throws `ArkKernelConfigError` instead.
+  `peerIsolation` rules are file-path slice walls; runtime flow (producer/intent names only)
+  does not evaluate them.
 - `reserved` / `allowEmpty` — future houses whose globs match nothing yet. `--strict-config` does not fail; `CONFIG_LAYER_PATTERN_NO_MATCHES` (typo warning) is skipped. A typo warning fires only when the glob is not reserved.
 - `capabilities: { deny: [...] }` — opt-in effect walls over the seven capability ids
   (`network`, `filesystem`, `clock`, `randomness`, `environment`, `process`, `persistence`);
@@ -256,6 +302,8 @@ Rule fields:
   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).
+  The wall denies imports; status details (`--doctor --all`) list code copied across it
+  (`doctor.crossWallDuplication`, advisory, no config key).
 - `sliceFolders` is a bare name or a starred prefix. A bare name (`features`) stays an
   unanchored one-segment match: `src/lib/features/projects/rfi/x.ts` with `["features"]` is
   `features/projects`. The next segment is never a filename, so
@@ -269,19 +317,43 @@ Rule fields:
   off that prefix (`src/app/api/projects/...`) is not that slice.
 - `sliceIdentity` is `path` or `stars`. Absent and `path` are the same: today's ids,
   byte for byte, so baselines and `allowedCrossSlice` keep working with no migration.
-  `stars` names a starred prefix as the last literal plus the star bindings.
+  `stars` names a starred prefix as the last literal plus every star binding. It
+  drops only the literals before the last literal; a star before it is kept, so
+  `modules/*/api/*` binds `orders/api/v1` and `users/api/v1`, never one shared `api/v1`.
+  arkgate 4.8.23 dropped that star too (`api/v1`). For one release a `sliceAliases`
+  `to`, an `allowedCrossSlice` entry, or a `childSlices.allowedCrossSlice` entry written
+  against the 4.8.23 id still loads and keeps its 4.8.23 verdict: a legacy alias target
+  (`api/v1/x`) joins the universe whose 4.8.23 id it names on each edge, and a legacy
+  allowance still clears the edges it cleared. ark-check warns `CONFIG_SLICE_LEGACY_STARS_ID`
+  (`failsStrict: false`) and names the new id to write (`orders/api/v1/x`, or one entry
+  per module when several modules share that old id). A legacy alias target is rejected at
+  config load only when it maps to more than one universe shape of the rule
+  (`maps to more than one universe shape`). Rewrite these entries before the next minor
+  release, which drops the legacy form.
   `lib/features/*/*` and `lib/repositories/features/*/*` both yield
   `features/projects/rfi`, so one feature has one id across parallel trees. Bare names
   (`features`) are unchanged. Doctor warns when two different prefixes bind as the
   same id, and the warning names both paths (`admin/features/*` and `public/features/*`
   both bind as `features/*`). That warning is advisory. Unrelated trees that share a
   last folder name should stay on `path`.
-- `childSlices` is an optional inner wall on a `peerIsolation` rule. Absent means today's
+- `childSlices` is an optional inner wall on a `peerIsolation` rule. It runs only with
+  `peerIsolation: true` and `allowed: false` on the same rule. Elsewhere it is inert: config
+  load still accepts it (4.8.23 did), and ark-check warns `CONFIG_CHILD_SLICES_INERT`
+  (`failsStrict: false`) with the fix — add both flags to the rule, or remove `childSlices`.
+  Absent means today's
   universe wall, byte for byte: no `reasonId`, same messages, same doctor output.
-  `sliceFolders` names the children (`lib/features/*/*` under a universe id `features/projects`).
-  `sliceIdentity` is the same `path` | `stars` choice. `commonFolders` (directory names such as
-  `domain`) and a flat file whose child id does not grow past the universe id are universe
-  common. A child may import that common code. Common code may import a child only when
+  `sliceFolders` names the children. `sliceIdentity` is the same `path` | `stars` choice, and
+  the child id must extend the universe id. With `"sliceIdentity": "stars"`, `lib/features/*/*`
+  yields child ids like `features/projects/rfi` under the universe id `features/projects`. Under
+  the default `path` identity the child id keeps the full prefix (`lib/features/projects/rfi`),
+  which does not extend a bare-name universe id such as `features/projects`: the check warns
+  `CONFIG_CHILD_SLICE_EXTENDS` and the child wall stays off. Pair a bare-name universe with
+  `"sliceIdentity": "stars"` on `childSlices`. A flat file whose child id does not grow
+  past the universe id is universe common. So is a `commonFolders` directory (a name such as
+  `domain`) **directly under the universe**: `lib/features/projects/domain/**`. A folder of
+  that name inside a child (`lib/features/projects/rfi/domain/**`) belongs to that child, so a
+  sibling that imports it is `CROSS_SIBLING_SLICE` and the child's own `domain/` may import
+  its own feature. A child may import universe common code. Common code may import a child only when
   `parentMayImportChild` is true (default false). `siblings` is `deny` (default, also when the
   key is omitted), `advisory`, or `{ "default": "deny" | "advisory", "enforce": [...] }`.
   The universe wall runs first. A denied cross-universe edge is
@@ -293,15 +365,43 @@ Rule fields:
   (`lib/features/projects/rfi` or `src/lib/features/projects/rfi`). A child id matches that
   importer's child id. A path matches when the importer file sits in that directory.
   Bare names do not match. `*` is not a wildcard on this list. `default: "deny"` denies every
-  sibling crossing; the list cannot loosen it. A new advisory crossing past the recorded
-  baseline still fails, the same ratchet as a string `advisory`. An enforce list does not
-  change that function. The baseline key stays `ruleId|file|fromLayer|toLayer|target` and does
+  sibling crossing; the list cannot loosen it. Advisory is advisory on day 1: with
+  `--baseline` (or an `--against` base), the anti-growth ratchet is judged **per rule** and
+  only over advisory crossings. `siblings.ratchet` on the object form picks it:
+  absent — on only when the baseline in use already records at least one advisory
+  crossing of that rule, and then only a crossing past that recorded count fails (an empty
+  baseline, or one frozen before the child wall, promotes nothing). The recorded count is
+  what the baseline holds for that rule: a key whose crossing was removed still counts when
+  the rule still classifies that edge as an advisory sibling crossing, so swapping one
+  recorded crossing for a new one keeps the count and stays a warning; `true` — any unrecorded
+  advisory crossing fails whenever a baseline is in use (the durable lock); `false` — measure
+  only, never fails (doctor `slices.crossSibling` still counts). A recorded enforced crossing
+  never switches the advisory ratchet on. A promoted finding says why and names
+  `ratchet: false`. `enforce` importers and `default: "deny"` stay errors either way. Doctor
+  `productHonesty` applies the same ratchet as `ark-check --baseline`. `ratchet: false` is a
+  weakening policy delta and `ratchet: true` a strengthening one. arkgate 4.8.23 and older
+  reject `ratchet` (`unknown field` at `$.rules[n].childSlices.siblings.ratchet`).
+  `childSlices.message` is the text for inner-wall findings (`CROSS_SIBLING_SLICE` and
+  universe common importing a child). The rule `message` stays the universe-wall text
+  (`CROSS_PARENT_SLICE` and the fail-closed denies). Without `childSlices.message`, an
+  inner-wall finding gets ArkGate's own default text; it never reuses the rule message.
+  Every surface uses the same choice: ark-check / CI, the write hook, MCP `validate_code`,
+  ESLint, and `analyzeProject` / prepare-change. Editing it is not a policy delta. arkgate
+  4.8.23 and older reject it (`unknown field` at `$.rules[n].childSlices.message`). The baseline key stays `ruleId|file|fromLayer|toLayer|target` and does
   not include `reasonId`. `productHonesty.finished` stays false while any child wall is
   advisory, including `{ "default": "advisory", "enforce": [...] }`. The list does not finish
   the house. Doctor `slices` is `{ crossParent, crossSibling, pairs }` for the directed universe
   pairs that occur. A child id that does not extend its universe id warns
   `CONFIG_CHILD_SLICE_EXTENDS` and is treated as universe common. arkgate 4.8.22 and older
-  reject `childSlices` (`CONFIG_CHILD_SLICES_VERSION`). A build that still types `siblings` as
+  reject `childSlices`. Ark warns `CONFIG_CHILD_SLICES_VERSION` only when the repo pins such
+  an older arkgate: an exact `package.json` dependency, the installed `node_modules/arkgate`,
+  `package-lock.json`, a `scripts/*hook*` / `.husky` / host hook command, or a CI workflow
+  (`pedroknigge/arkgate@vX.Y.Z` or its `version:` input). The finding points at that file and
+  line and says which version to bump to. Without such evidence it is silent. Ranges
+  (`^4.8.0`) are not evidence; pnpm/yarn lockfiles are read through the installed copy. The
+  same check covers `sliceIdentity` (4.8.21), `sharedImportsSlice` (4.8.20),
+  `"deny-cross-parent"` (4.8.23), and the keys added after 4.8.23 (`stopAt`,
+  `childSlices.message`, `siblings.ratchet`). A build that still types `siblings` as
   the string enum `deny | advisory` rejects the object at config load
   (`must be one of deny, advisory` at `$.rules[n].childSlices.siblings`). It does not ignore
   the object. No published release through 4.8.22 accepts `{ default, enforce }`. Ship that
@@ -326,10 +426,16 @@ Rule fields:
   Ship it only on a release that includes this field.
   `childSlices.sliceAliases` maps files that sit outside every slice folder onto
   a child that already exists: `{ "from": "lib/compliance/**", "to": "features/projects/compliance" }`.
-  `to` is the universe id the universe wall already knows, plus one child segment.
-  A bare name, that universe id alone, an unknown universe, and a wildcard in `to`
-  are rejected at config load (`child of an existing universe`). The source glob
-  may cover only files the slice folders do not already classify. Overlap with a
+  A `from` without a wildcard in its last segment is a folder form and also covers
+  everything under it, as `sharedRoots` does (`lib/compliance` equals `lib/compliance/**`).
+  `to` must match a universe `sliceFolders` shape of the rule, plus one child segment.
+  A bare name, a universe id alone, a target outside every universe shape, and a
+  wildcard in `to` are rejected at config load (`child of a universe shape`); under
+  `"sliceIdentity": "stars"` a target written against the 4.8.23 id loads with a
+  `CONFIG_SLICE_LEGACY_STARS_ID` warning (see `sliceIdentity` above). Config
+  load cannot see the tree, so it checks only the shape: doctor marks an alias move
+  whose target universe no scanned file belongs to (`unknownUniverse`, "check for a
+  typo"). The source glob may cover only files the slice folders do not already classify. Overlap with a
   universe `sliceFolders` entry or a child `sliceFolders` entry is rejected
   (`overlaps a slice folder`). Two aliases that can match one file are rejected
   (`two slice aliases match the same file`). An aliased file takes the target
@@ -337,9 +443,23 @@ Rule fields:
   universe is `CROSS_PARENT_SLICE` and an import into another child of the same
   universe is `CROSS_SIBLING_SLICE`. Same-child imports and imports into that
   universe's common folders follow the existing child wall. Doctor lists every
-  alias as an owed move: the source glob, the target slice, the destination
-  folder, and the files. The section says the files are not finished. Aliases
-  are debt. `productHonesty.finished` stays false while any alias is set.
+  unpinned alias as an owed move: the source glob, the target slice, the destination
+  folder, and the files. The section says those files are not finished.
+  `"pinned": true` lists the alias under pinned instead. `reason` (for example
+  `"framework-route"`) is the label doctor prints. A reason alone does not pin.
+  A pinned route is not `slice-alias-debt` and does not clear any other honesty
+  reason, so `productHonesty.finished` stays false while real debt remains.
+  `childSlices.arkRulesFile` is a filename at each child root the wall already
+  resolved (`"arkrules.<Layer>.json"`). `<Layer>` is the only token. The file is
+  law: it enters `policyHash`, and a path added or removed is one
+  `arkrules-ref-added` or `arkrules-ref-removed`. The effective id is
+  `<childId>#<localId>`. Omitting `appliesTo` scopes the rule to the slice
+  directory. An explicit `appliesTo` outside that directory is
+  `ARKRULE_SCOPE_ESCAPES_SLICE` and config load fails closed. A filename
+  `arkrules.<Layer>.json` is a law path for mixed-law classification. An older
+  build rejects the array form, `arkRulesFile`, `pinned`, and `reason` at config
+  load. Aliases
+  are debt while any unpinned alias remains. `productHonesty.finished` stays false while that debt, or any other honesty reason, remains.
   Adding aliases is a strengthening policy delta (unclassified files come under
   the walls). Removing them is weakening (those files leave the walls) and needs
   the same hash-bound acknowledgement as any other weakening. Additions and
@@ -353,13 +473,20 @@ Rule fields:
   It does not ignore the key. No published release through 4.8.22 accepts
   `sliceAliases`. Ship a config that sets it only on a release that includes
   this field. The write hook, ESLint, snippet analysis, ark-check, and CI all
-  see the per-edge decision.
+  see the per-edge decision. In ESLint an error-level crossing reports on
+  `ark/no-domain-infra-imports` and an advisory (warning) crossing reports on the
+  warn-level `ark/architecture-advisory`, because ESLint severity is per rule id
+  ([ai-gates — ESLint](ai-gates.md#eslint-editor-feedback--bounded-parity-envelope)).
 
   Doctor may suggest moving a flat file that sits at universe level when
   exactly one child slice imports it. The card names the file, that child, and
   a destination folder inside the child that keeps the file's layer. It is a
   suggestion. It is not a config field, not a finding, and not an ark-check
-  result. A file two children import stays where it is.
+  result. The importers come from the same resolved graph ark-check uses (tsconfig
+  path aliases included). A file two children import stays where it is, and so
+  does a file that anything outside that one child imports (universe common, a
+  shared root, another universe, another layer). A move that the walls would deny
+  for any recorded importer is never suggested.
 
 ```jsonc
 {
@@ -437,6 +564,30 @@ is evidence:
   That pass runs in `ark-check` and CI. The write hook and ESLint see one edge at a time
   and do not block it. arkgate 4.8.22 and older reject the value at config load (`must be
   one of deny`). They do not ignore it and they do not treat it as `"deny"`.
+  A universe edge the importer's rule declares in `allowedCrossSlice` (directed) is not
+  reported through a shared root either: it is the same dependency the direct wall
+  already allows. `childSlices.allowedCrossSlice` still never clears it.
+  In a DI app the composition root (bootstrap, registrations) has to sit under
+  `sharedRoots`, and every slice that asks the root for a service then "reaches" every
+  universe the root registers. Name those files in the object form:
+  `"sharedImportsSlice": { "mode": "deny-cross-parent", "stopAt": ["kernel/bootstrap.ts",
+  "kernel/registrations/**", "lib/feature-registrations.ts"] }`. The walk never starts at
+  or passes through a stop file, so a path through it is not a crossing. A `stopAt` entry
+  matches like a shared root (anchored, optional leading `src/` or `app/`, a plain folder
+  covers its subtree) or like an alias glob (`kernel/registrations/**` against
+  `src/kernel/registrations/x.ts`). Config load rejects an entry that covers the whole
+  tree (`*`, `**`, `src`, `src/**`, `app/**`, `*/**`) or a whole layer root of that rule
+  (layer `src/lib/**` with `lib/**`), since it would stop every shared node and silence
+  the walk: `must not cover the whole tree` / `must not cover a whole layer root of this
+  rule`. A stop file must still
+  sit under `sharedRoots`; `stopAt` does not classify files and does not silence the direct
+  `SHARED_IMPORTS_SLICE` warning. A slice destination that matches a stop is still reported.
+  Each finding carries `via` (the shared hops). Doctor `sharedWalkHubs` names a shared file
+  that sits on at least half of ten or more such findings — a likely composition root. That
+  is advisory, not a finding. Adding stops is a weakening policy delta
+  (`shared-walk-stop-added`), removing them strengthens, both together need a judgment. The
+  string forms are unchanged. arkgate 4.8.23 and older reject the object at config load
+  (`must be one of deny, deny-cross-parent`).
 - `allowedCrossSlice` entries match a full slice id (`features/catalog`) or a bare slice name
   (`catalog`), and only in the direction written. The reverse edge still denies. A bare name
   matches that name under **any** slice folder, so in a repo with several slice parents
@@ -448,7 +599,10 @@ is evidence:
   about your code) versus `unclassifiable path (src/widgets/x.tsx)` (a fact about our evidence).
   `no slice folders` and `no path evidence` are the two remaining evidence reasons. A rule-level
   `message` override no longer hides it: the reason is appended to your text, not replaced by it.
-- Both declarations are **weakening** changes in `ark policy-delta`
+  The write hook and MCP `validate_code` say the same, and for an evidence reason their fix
+  asks you to move the file into a slice or declare its root in `sharedRoots`.
+- Both declarations are **weakening** changes in the policy delta (`arkgate-check --strict-merge`
+  with `--policy-base <file>` / `--policy-base-ref <ref>`, or MCP `ark_policy_delta`)
   (`shared-roots-added`, `cross-slice-allowance-added`), so a policy review sees them. Both are
   inert on a rule without `peerIsolation: true`, and policy-delta stays silent about them until
   the wall exists.
@@ -464,7 +618,8 @@ other choice deliberately, not so slices can drift into a mesh.
 runtime coupling. They still appear on the **violations** list with `typeOnly: true`,
 `failsStrict: false`, and adapter diagnostic **severity: warning** so doctor/HTML keep
 `violations.typeOnly` / `typeEdgePolicy` honest — but they **do not** fail merge/exit, library
-`valid`, or preflight the way **value** edges do. **Exception:** `peerIsolation` slice
+`valid`, or preflight the way **value** edges do. ESLint reports them as warnings on
+`ark/architecture-advisory`, not as errors. **Exception:** `peerIsolation` slice
 boundaries stay hard even for type-only. A value import of a pure-type barrel is still a value
 edge (not soft-skipped). Prefer placing shared types in a **SharedTypes** (or owning) layer
 both sides may import. Optional starter: [`templates/layers/shared-types.starter.json`](../templates/layers/shared-types.starter.json)
@@ -526,8 +681,8 @@ Each `arkrules/<Layer>.json` may declare:
 
 | Section | Purpose | Modes | What it really enforces |
 |---------|---------|--------|-------------------------|
-| `structure[]` | Closed sensor ids (e.g. `orchestration-only`, `thin-adapter`, `writes-via-aggregate`, `aggregate-private-state`, `always-valid-factory`, `domain-event-on-mutation`, `no-anemic-model`) | `advisory` (default) or `enforced` | **Heuristics of module shape** — not proof that logic was extracted to Domain. `writes-via-aggregate` is driver-import + write-token in the declaring layer (ADR 0032). Tier-2 sensors (`no-anemic-model`) stay advisory-only (cannot promote to enforced). |
-| `invariants[]` | Stable ids + description + `coverage` (`test` / `symbol`) + optional `appliesTo` globs | `advisory` or `enforced` | **Named policy + evidence.** `coverage.symbol` means a declaration of that identifier in a non-test file (witness path `symbolEvidenceFile`; additive `shape`: `function`, `class`, `const`, `method`, `type`, `interface`, or `enum`). Imports and test calls do not count. A `describe` / `it` / `test` / `context` title may also name the invariant id. A comment, string, or other bare mention does not. Does **not** execute tests or business logic and does **not** replace behavior/property tests. Doctor and `--rules-inventory` print the witness path and discard counts on green runs too. A declaration match is not “the tests pass.” |
+| `structure[]` | Closed sensor ids (e.g. `orchestration-only`, `thin-adapter`, `writes-via-aggregate`, `aggregate-private-state`, `always-valid-factory`, `domain-event-on-mutation`, `no-anemic-model`) | `advisory` (default) or `enforced` | **Heuristics of module shape** — not proof that logic was extracted to Domain. `writes-via-aggregate` is a driver import plus a write token, or a SQL write head inside a tagged template, in the declaring layer (ADR 0032). Tier-2 sensors (`no-anemic-model`) stay advisory-only (cannot promote to enforced). Class shapes come from a tokenizer that skips strings, comments, template literals and regex literals; a class it cannot walk to its end is reported as `shape analysed until character N` (an error under an enforced sensor), never passed in silence. |
+| `invariants[]` | Stable ids + description + `coverage` (`test` / `symbol`) + optional `appliesTo` globs | `advisory` or `enforced` | **Named policy + evidence.** `coverage.symbol` means a declaration of that identifier in a non-test file (witness path `symbolEvidenceFile`, project-relative; additive `shape`: `function`, `class`, `const`, `method`, `type`, `interface`, or `enum`). A `Class.member` symbol (e.g. `Order.ensureInvariants`) requires a member with that name inside the body of `class Class`, a `const Class = class { … }` expression, a `namespace Class { … }` (function or const), or a top-level key of a `const Class = { … }` object literal; a member of another container, a nested object key, a free function, or a file that only mentions the class name does not count. The search is not restricted to the invariant's layer. `coverage.test: false` without a `coverage.symbol` declares no evidence: it is advisory-only (an enforced invariant with that shape reports `INVARIANT_UNCOVERED` and fails strict; the rest of the catalog still evaluates) and cannot be promoted. Imports and test calls do not count. A `describe` / `it` / `test` / `context` title may also name the invariant id. A comment, string, or other bare mention does not. Does **not** execute tests or business logic and does **not** replace behavior/property tests. Doctor and `--rules-inventory` print the witness path and discard counts on green runs too. A declaration match is not “the tests pass.” |
 
 **Reporting:** diagnostics carry `evidence.arkruleId` + `evidence.arkruleSource`. Label residual
 **`[Layer]`** vs **`[ArkRules]`** in agent output. Doctor / HTML: `rulesUnderContract` (catalog +
@@ -571,6 +726,14 @@ npx ark-check --strict-config --policy-base ./before.ark.config.json --json
 npx ark-check --strict-merge --policy-base-ref origin/main
 ```
 
+ArkRules are part of the policy. With a Git ref, the base `arkrules/*.json` files are read from
+that same ref (a file the base config references but the ref does not contain yet counts as an
+empty layer). With `--policy-base <file>`, the base ArkRules paths resolve next to that file (keep
+a copy of the base `arkrules/` beside it; the error names that directory and the
+`--policy-base-ref` alternative). A base ArkRules file that cannot be read or parsed fails
+closed, because comparing the candidate catalog with itself would read every demotion or
+deletion as neutral.
+
 The additive JSON result includes `policyDelta`: both policy hashes, the overall classification,
 stable findings, and `blockingFindingIds`. Supported comparisons cover governed include/exclude
 roots, layer patterns/exclusions/forbidden globals, deny rules, same-layer peer isolation,
@@ -627,14 +790,40 @@ type than product source:
 
 | Check | What it does |
 |-------|----------------|
-| `ark-check --local --base origin/dev` | Opt-in local / multi-worktree cheap check. Same engine as `--changed`. Refused with `--strict-merge`. `ARK_CHECK_LOCAL=1` is the same unless CI or a full-tree report mode is on. |
+| `ark-check --local --base origin/dev` | Opt-in local / multi-worktree cheap check. Same engine as `--changed`. Refused with `--strict-merge` and with `--update-baseline`. `ARK_CHECK_LOCAL=1` is the same unless CI, a full-tree report mode, or `--update-baseline` is on. |
 | `ark-check --changed --base origin/dev` | Layer check on touched sources only. A CSS/i18n PR pays almost nothing. |
 | `ark-check --against origin/dev` | New violation keys vs **that ref's** baseline (not only HEAD). |
 | `ark-check --contract-diff --base origin/dev` | Classifies tighten / loosen / reclassify / baseline-grow. |
-| `--contract-session --author <id>` | Law-only PR. Mixed law+product still fails. Loosen/grow need a session even with an empty `stewards[]`; a non-empty list also needs a matching listed author. |
+| `--contract-session --author <id>` | Law-only PR. Mixed law+product still fails. Loosen/grow need a session even with an empty `stewards[]`; a non-empty list also needs a matching listed author. A session always classifies the law change against the team base (`--base`, or the discovered `main`/`dev`), including under `--strict-merge`. If that base has no contract yet (the adoption PR that adds `ark.config.json`), there is nothing to loosen and the session proceeds; an explicit `--policy-base-ref` without a contract at that ref still exits 2. |
 | `--persona touch\|contributor\|agent\|steward` | Budget presets for the same teeth. |
 | `ark status --vs origin/dev` | One line: pin / contract / baseline drift vs that ref. |
 
+How the changed-file set is computed (`--changed`, `--local`, `--against`, `--persona`):
+
+- Paths are relative to `--root`, even when that root is a package inside a monorepo
+  (`git diff --relative`; base-ref files are read as `<ref>:./<path>`). Changes outside the
+  root are not part of that package's diff.
+- Committed changes since the merge base, staged, unstaged, and untracked files all count.
+  File names with spaces, quotes, or non-ASCII characters are kept exactly.
+- Without `--base` / `--against`, the base is the first of `origin/dev`, `origin/main`,
+  `origin/master`, `dev`, `main`, `master` that exists. When none exists (or the root is
+  not a git repository), `--changed` and a non-steward `--persona` stop with **exit 2**
+  (`reasonId: changed-needs-base`; `--local` uses `local-needs-base`). `--contract-diff`
+  and `--persona steward` (which implies it) also stop with **exit 2**
+  (`reasonId: contract-diff-needs-base`): the contract and baseline diff has nothing to
+  compare against. Pass `--base <ref>` or run a plain full check. A diff that could not be
+  computed never counts as "no changes".
+- Any failed git listing (bad ref, timeout, output too large) is exit 2
+  (`reasonId: changed-paths-unavailable`), never a pass.
+- `--report` applies the committed `.ark-baseline.json` implicitly, except under
+  `--strict` / `--strict-merge` / `--contract-diff` / `--against`: a merge verdict uses a
+  baseline only when `--baseline` is passed.
+- `--update-baseline` always freezes the whole tree: it refuses `--changed` / `--local`
+  (exit 2) and ignores `ARK_CHECK_LOCAL=1`, so a partial scan can never truncate
+  `.ark-baseline.json`.
+- Layer-pattern typo warnings (`CONFIG_LAYER_PATTERN_NO_MATCHES`) under `--changed` are
+  judged against the full governed tree, so an untouched layer is not reported as a typo.
+
 Write-gate ApplyPatch denies a batch that mixes law files with product source. Humans who
 never hit PreToolUse are unchanged. Local `pnpm` gates should call `--local --base` or
 `--changed --base`, not only full-tree `--strict-merge`. Write hooks stay on the lexical
@@ -645,11 +834,21 @@ worktree has its own root); there is no machine-wide analysis lock.
 include tree. File-local ArkRules sensors (class shape, orchestration-only, thin-adapter,
 writes-via-aggregate) and hint preload stay on the touched set. Layer and cycle sensors
 see that closure, so a new illegal import or a cycle the change can complete still
-fails. Untouched files outside the closure are left to the full-tree CI check. Same
+fails. When a touched file sits under the `sharedRoots` of a `"deny-cross-parent"` rule,
+the graph runs full-tree: the finding belongs to the slice that imports the shared root,
+which may be outside the closure. A `CROSS_PARENT_VIA_SHARED` path counts as part of the
+change when any file on it changed. Untouched files outside the closure are left to the full-tree CI check. Same
 engine; not a second analysis path. 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.
+When `baseConfig` maps `arkRules`, pass the base catalog as data in `baseArkRuleFiles`
+(`{ "<path from baseConfig.arkRules>": <ArkRules file JSON> }`); without it the call is refused
+instead of returning a config-only verdict. When `childSlices.arkRulesFile` is set, include each
+discovered slice file in that same map, keyed by its project-relative path. The candidate catalog is read from disk when the
+candidate is omitted or maps the same `arkRules` files as the project contract (after the loader's
+normalisation, so the project `ark.config.json` passed verbatim counts); otherwise pass
+`candidateArkRuleFiles` in the same shape.
 It invokes the public classifier directly, is read-only, and marks a blocking result as an MCP
 error without maintaining separate adapter policy.

package/docs/develop.md

@@ -214,7 +214,8 @@ stays plane-free. Empty `planeRoots` in `enforced` mode fails closed
 (`ARKORDER_MISSING_PLANE`). In-memory. Not durable. Does not replace ArkRun.
 
 First freeze is `release()`. Later pattern change is `proposeRelease` then
-`apply` (`ARKORDER_UNVALVED_RELEASE`). `refreshSigma`; ingest residual
+`apply` (`ARKORDER_UNVALVED_RELEASE`); `apply` only takes a proposal computed against the
+current Release (`ARKORDER_STALE_PROPOSAL`). `refreshSigma`; ingest residual
 `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data;
 `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`.