arkgate 4.8.23 → 4.8.25

package/docs/package-surface.md

@@ -61,40 +61,43 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Ambient state (pure layers)** | `ark-check --doctor --json` → `doctor.ambientState`; optional `.ark/ambient-state-acks.json` | Additive, **advisory only and opt-in**: only layers declared `pure: true` are scanned; the MVP shape is module-scope `let`/`var`. Findings carry `file`/`line`/`name`/`kind` (sorted, capped with honest `truncated` count). Acknowledgments live in the bounded sidecar (`{ acks: [{ file, name, reason }] }`, ≤64 KB / ≤200 entries); `acknowledged` counts applied acks; malformed file suppresses nothing. When TypeScript is unavailable the sensor reports `available: false` instead of guessing. **No strict mode exists** — A5: strictness requires a completed corpus and an explicit later decision. |
 | **Parse health + analysis completeness** | `ark-check --doctor --json` → `doctor.parseHealth` + `doctor.completeness`; check JSON → `completeness`; report section `data-advisory="parseHealth"` | The resolved candidate facts contribute only `parseDiagnosticCount` per governed file (no raw diagnostics, second parser pass, or `tsc`). Z04's correctness path ignores legacy v9 caches and parses the complete candidate on every invocation; Z07 owns any future identity-keyed warm snapshot. Doctor remains diagnostic: parse health adds no architecture violation and does not change `designFitness` or `patternBets`. Verdict surfaces consume the evidence fail-closed: affected governed files mean `partial`, plan `goal.met: false`, normal JSON `valid:false`/`ok:false`, and strict merge exit `1`; the non-strict process exit remains advisory for compatibility. No usable host means `unavailable`, plan false, and CLI exit `2`. JSON reports `scannedFiles`, `affectedFiles`, `diagnosticCount`, deterministic top-12 `{ file, diagnosticCount }` entries, and honest `truncated`/`overflow`; missing/unsafe evidence never becomes a clean claim. |
 | **Physical cohesion + reshape pilot** | `ark-check --doctor --json` → `doctor.physicalCohesion` (`reshapePilot`, `reshapeDecisions`); optional `.ark/reshape-decisions.json`; report section `data-advisory="physicalCohesion"` | Additive, **advisory only** — `notAScore`; never feeds the verdict, `designFitness`, or `patternBets`. Signal is **concentration, not volume**: concept clusters per anchor directory (deterministic path/name tokenization; framework filenames like `route.ts` take the topmost meaningful path segment — ADR 0010 D2). Fixed corpus-calibrated thresholds (`maxCluster ≥ 40` OR ≥2 anchors ≥ 20, ADR 0010 D3); findings ranked and capped (top 5, honest `truncated`). Anchors under `app/`/`pages/` are `fixedByConvention` and never move (D7). `reshapePilot` is **proposed, never applied** (`neverMechanicalSafe`): one Q04-style pilot card at a time targeting the smallest convention-free anchor, with `moveSample`/`movesTotal`, `successSignal`, `killSwitch`, `doNot[]`; each `to` is `concept/` under the source anchor and is kept only when layer and slice id are unchanged — if every candidate fails, `nextPilot` is null; real moves run only through the write gate + atomic preflight via `/ark-loop`; merges are `/ark-architect` judgment cards, never a codemod (D6). **Y01 verdict memory:** bounded sidecar `{ schemaVersion?: "1", decisions: [{ concept, anchors, verdict: "accepted"|"deferred"|"rejected", reason, reviewBy? }] }` (≤64 KiB / ≤200 unique targets). Identity is concept + complete sorted anchor set, never counts/change-map evidence. Current rejected/deferred records suppress pilot pressure only; accepted keeps the existing path. Expired/malformed/stale/invalid records suppress nothing; lifecycle and decisions render in doctor/report. Explicit only — golden-pattern prose never infers a verdict. |
+| **Files nothing imports** | `ark-check --doctor --json` → `doctor.orphanModules` (nested `unusedExports`); human status details (`--doctor --all`) section **Files nothing imports (not a score)** and at most one dim count line in compact status; HTML report `data-advisory="orphanModules"`; optional `.ark/entry-points.json` | Additive schema `1.0`, **advisory only** — always `notAScore: true`; never flips `valid`, strict-merge, `goal.met` or a compass lens; never runs in the write hook, MCP write tools, ESLint, `--changed` or `--strict-merge`. Projects the resolved import edges the check already built (ADR 0037): a governed file with zero incoming project edges (type-only imports and `export … from` count) that no entry source covers. Closed entry sources, each labelled in `entryEvidence.bySource`: `package-json` (`main`/`module`/`types`/`browser`/`exports`/`bin` per workspace; built paths map back through a bundler entry map in a `*.config.*` file, tsconfig `outDir`/`rootDir`, then `dist\|build\|lib\|out` → `src`; an unmapped path forces `partial`), `package-scripts` (package scripts and CI workflow run steps), `framework` (Next route files, `pages/**`, `middleware`/`proxy`/`instrumentation`; Vite `index.html`; Nest `main`; Vercel root `api/**`; Storybook stories), `ark-config` (arkRun / arkOrder roots, `stopAt`), `config-file` (config and setup files, and any source file a config file names), `ambient` (`declare global` / `declare module`), `sidecar`. Files only tests import are counted in `testOnly`; files only non-governed source or a generated copy uses count as `outsideOnly`. `status` is `complete` \| `partial` \| `deferred` \| `unavailable`; under `partial` each item carries `certainty` `no-importer` \| `maybe-dynamic` \| `maybe-unresolved` and `honesty[]` names what could not be followed. Lists capped at 20 with honest `truncated`; with no framework recognised and more than a quarter of governed files listed, the list is cut to 5 and the headline says entry points were not recognised. Outside pass bounded to 5000 files / 256 KB each. `unusedExports` (`UNUSED_EXPORT`) is `deferred` in compact status and filled only by `--doctor --all` and `--report`. Sidecar `{ "schemaVersion": "1", "entryPoints": [{ "glob", "reason", "reviewBy?" }] }` (≤64 KiB / ≤200 entries); an expired `reviewBy` stops applying and annotates the file; a malformed file suppresses nothing and a line says so. Not a config key and not in `policyHash`. Domain pure + CLI gen mirror (`orphanModules.ts` / `bin/lib/orphan-modules.mjs`); not a root package export. |
+| **Copies across a wall** | `ark-check --doctor --all --json` → `doctor.crossWallDuplication`; human status details (`--doctor --all`) section **Copies across a wall (not a score)**; HTML report `data-advisory="crossWallDuplication"` | Additive schema `1.0`, **advisory only** — always `notAScore: true`; never flips `valid`, strict-merge, `goal.met` or a compass lens; never runs in the write hook, MCP, ESLint, compact status, `--changed` or `--strict-merge`. Without `--all` (and under `--changed`) the key says `status: "not-run"` with `next: "arkgate-check --doctor --all"`. Token fingerprints taken at status time (ADR 0038) from the TypeScript already loaded — one `createSourceFile` per governed file, a JSX-safe node walk (identifiers and literals collapse, imports and `export … from` skipped); they never enter facts, `factsHash` or the verdict. Tests, `.d.ts`, default generated globs, files whose first five lines say `@generated` / `GENERATED FILE` / `DO NOT EDIT` / `generated from|by`, and files over 256 KB are never read for it. A family is listed only when a pair crosses a boundary the gate's own classifier (`findDeniedEdgeDecision`, both directions) draws: `crossing` `cross-slice` \| `cross-parent` \| `cross-sibling` \| `cross-layer-walled` (`CROSS_WALL_DUPLICATE`) or `cross-layer` (`CROSS_LAYER_DUPLICATE`). Same-slice pairs (`totals.pairsSameSliceUnexamined`), unclassifiable (`fail-closed`) pairs (`pairsUnclassifiable`) and files outside every layer (`pairsUnplaced`) are counted, never listed. Each family carries `members[]` (path, layer, `startLine`/`endLine`, tokens), `pairs[]`, `names` (`same` of `total` identifiers matching), a plain `destination` (`shared-root` \| `universe-common` \| `lower-layer` \| `shared-layer` \| `either-layer` \| `ask-place`; never applied) and `line`. Fixed constants in `method` (20-token grams, 31-gram winnowing window, ≥50 tokens, ≥5 lines, ≥60% names, bucket cap 16); not configurable. Caps: `graphScanLimit(n)` files, 1 000 000 fingerprints, 50 000 seed pairs, 1000 compared file pairs; any cap → `status: "partial"` with `honesty[]` counts. Families capped at 8 with honest `truncated`. No config key. Domain pure + CLI gen mirror (`cloneDetection.ts` / `bin/lib/clone-detection.mjs`); not a root package export. |
 | **Capability walls, every adapter** | CLI scan, pure IR engine, atomic preflight, `ark-mcp --hook` / MCP gate (`capabilityWalls`), ESLint `ark/no-denied-capabilities` | The same opt-in deny set enforces across every surface: hook/MCP and CLI cover ambient + import evidence (symbol-aware); the pure engine, preflight, and ESLint cover the import dimension (documented envelope). Dual depth everywhere: plain port hint (`FIX_HINTS`/`suggestion`) + stable JSON (`ruleId`, `capability`, `fixClass: inject-port`, deterministic `nextAction`). |
 | **Hook-path budgets (maintainer)** | Repository-only evidence: `npm run bench:hook-path`; `eval/performance/hook-budgets.v1.json`; CI job "Hook-path end-to-end budgets" | Measures the COMPLETE pre-tool paths as fresh child processes (hook cold/warm, doctor cold) at 1k/10k. D5 method locked: ceilings are Linux-baseline p95 + fixed headroom, set once per cycle, never ratcheted; scenarios without a recorded baseline stay in RECORDING mode and cannot fail CI. |
 | **Governance weight** | `ark-check --doctor --json` → `doctor.contractHealth.governanceWeight` | Additive, **advisory only** — raw facts (`declaredLayers`, `populatedLayers`, `governedFiles`, `rules`, `deniedEdges`, `allowedEdges`, `filesPerLayer`, `rulesPerLayer`) plus a fixed comparative band `weight: heavy | typical | light | unknown` and its fixed `note`. Fixed deterministic thresholds: **heavy** = fewer than 25 governed files per declared layer AND (6+ layers OR 4+ well-formed rules per layer); **light** = at most 2 layers over 150+ governed files; **unknown** = no layers or no governed files; everything else is **typical** (banding uses raw ratios; the reported ratios are rounded for display). `notAScore: true` is explicit: never a composite score, ranking, or gate input; the heavy note asks to justify NEW layers/rules and never suggests deleting working ones. Human doctor prints a line only for `heavy`/`light`. |
 | **Report parity and snapshot evidence (4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth\|arkRun"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. Thin `arkRun` on `latest.json` is `notAScore` residual honesty for `ark status`. |
 | **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
-| **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
-| **`ark.config.json`** | Layer globs, optional `layers[].description`, optional `layers[].trustBoundary`, optional `layers[].owners`, optional `requireLayerOwners`, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
+| **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. Every published `outputSchema` has top-level `type: "object"` and the returned `structuredContent` validates against it (MCP SDK clients check both). A contract edit after startup makes project tools return `CONTRACT_STALE` until restart. `arkgate-mcp --help` / `--version` print and exit. |
+| **`ark.config.json`** | Layer globs, optional `layers[].description`, optional `layers[].trustBoundary`, optional `layers[].owners`, optional `requireLayerOwners`, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map of one path or a list of paths (schema `1.1+`), plus optional `childSlices.arkRulesFile` and `sliceAliases.pinned`; optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
 | **Layer caption (`layers[].description`, 4.8.7)** | Optional string on each layer. Projected onto `ark_place` / prepare-write / MCP place JSON, doctor JSON + human, coverage JSON, and the HTML Purpose column when present. `/ark-adopt` writes it from the product map or glossary; `/ark-place` prints it next to layer name + globs. | Existing optional field — **no `schemaVersion` bump**, no new key, no 14th skill. Copy is **app context** (a product sentence such as `Purchase requests — from asked to received.`), not architecture jargon. Stripped from `policyHash` like `stewards`; caption-only edits are neutral. Absence is silent: never a residual, never a score, never `--strict-config` fail, never flips `valid`. Compact starters may omit. |
 | **Layer trust (`layers[].trustBoundary`)** | Optional closed tag on each layer: `public` \| `auth` \| `admin` \| `internal`. Projected onto `ark_place` / prepare-write / MCP place JSON, doctor JSON + human, coverage JSON, and the HTML report when present. `/ark-adopt` writes it when the product map names that door; `/ark-place` prints `trust: public`. | Additive optional field — **no `schemaVersion` bump**, no new skill. Stripped from `policyHash` like `stewards` and `layers[].description`; tag-only edits are neutral. Absence is silent: never a residual, never a score, never `--strict-config` fail, never flips `valid`. Invalid values fail the schema. Compact starters may omit. Not host/CI TLS. Not an import-rule matrix. |
 | **Layer owners (`layers[].owners` + `requireLayerOwners`)** | Optional GitHub handles or emails on each layer. Projected onto place / prepare-write / MCP / doctor / coverage / HTML when present. `requireLayerOwners: true` asks for owners on every live (non-reserved) layer: doctor names the first missing house, `--strict-config` refuses, and the write gate denies a write into that house. | Additive optional fields — **no `schemaVersion` bump**, no new skill. Owners are stripped from `policyHash` like captions; owner-only edits are neutral. The require flag stays in the hash. Absence of owners is silent unless the require flag is on. Invalid identity (display name) fails the schema. Compact starters may omit. Not import-rule teeth. No `/ark-owners`. |
-| **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
+| **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract` + `rulesMigration`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. Structure candidates count as under contract by declared (layer, sensor); frozen counts `ARKRULE_*` / `INVARIANT_*` baseline keys. CLI and MCP payloads share one builder (same keys, incl. `coverageEvidence`). When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
 | **Managed upgrade self-service honesty (4.5 / DF05)** | `ark upgrade [--json]` → `selfService` (+ human “Self-service honesty” lines) | Additive, advisory. Answers without a maintainer: write-path activation labels per selected host (`hard`\|`advisory`\|`unavailable`) and customized content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Not a gate input; not part of `planDigest`. |
 | **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. A physical-cohesion residual that reshape decisions have not suppressed adds `physical-cohesion-residual`, which clears `elegant` and `finished` and sets the headline to residual remaining; the gate verdict, `designFitness`, `designWeak`, and `patternBets` stay unchanged. When that residual still proposes `reshapePilot.nextPilot`, `pilotLoop` is active with that one extraction card. |
 | **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. A new layer or new allow edge is `judgment-required`. On the CLI/MCP policy-ack plane, `adrPath` must name a short note under `docs/adr/` or `docs/decisions/` (`policyDelta.adrNote`). Domain hash match stays I/O-free. |
-| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--local` / `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources plus their import closure. `--local` (or `ARK_CHECK_LOCAL=1`) is the same cheap path and stays per `--root`; it cannot combine with `--strict-merge`. Check JSON may add `local`, `scope: "changed"`, `analysisRoot`. `stewards`, `layers[].description`, `layers[].trustBoundary`, and `layers[].owners` are excluded from policy hash. `requireLayerOwners` stays in the hash. Identity is handle or email, not git `user.name`. No org plane. |
+| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--local` / `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources plus their import closure. `--local` (or `ARK_CHECK_LOCAL=1`) is the same cheap path and stays per `--root`; it cannot combine with `--strict-merge` or `--update-baseline`. Changed paths are relative to `--root` (monorepo packages included). A missing base ref or failed git listing is exit 2 (`changed-needs-base` / `local-needs-base` / `contract-diff-needs-base` for `--contract-diff` and `--persona steward` / `changed-paths-unavailable`), never a pass. `--report` applies the committed baseline implicitly except under `--strict` / `--strict-merge` / `--contract-diff` / `--against`. Check JSON may add `local`, `scope: "changed"`, `analysisRoot`. `stewards`, `layers[].description`, `layers[].trustBoundary`, and `layers[].owners` are excluded from policy hash. `requireLayerOwners` stays in the hash. Identity is handle or email, not git `user.name`. No org plane. |
 | **Atomic change preflight (3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
 | **Architecture change map (3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
 | **Structural convergence (3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
 | **Enforcement ladder + fixed journey (3.1.0)** | `doctor.writePath.enforcementLadder`; hook repair `enforcement`; `npm run eval:change-integrity` | Additive schema `1.0` separates supported/installed/active/bypassable state and evidence. Hard is operation-scoped only for a supported covered hook; MCP is advisory; required CI status stays unverified locally. Fixed no-context fixture proves CLI/MCP/hook/final parity, one casual denial, acceptance behavior, and strict Ark. |
 | **Enforcement state** | `doctor.writePath.enforcementState`; schema/type | Schema `1.1`: runtime observation, operation coverage, and operation-scoped `hard`. Only fresh covered active-host evidence permits `hard:true`; unverified assets and MCP remain non-hard. |
 | **Design delta** | `--strict-merge` / `--strict` (created paths when a Git base exists); `--fail-on-new-smells --base-ref <ref>` (full ratchet); hook/MCP; schema/types | Schema `1.0`: identities, touched paths, optional `enforcementScope`. Default merge blocks **created** `domain-logic-in-ui` files vs merge-base; missing base skips (does not exit 2). Full new+worsened on touched paths remains opt-in `--fail-on-new-smells` (missing base fails closed). Historical residual and worsened-in-existing-file stay green on `--strict-merge`. Global doctor smells stay advisory. |
-| **`arkgate/schema/analysis-result`** or **`arkgate/schema/ark.analysis-result.schema.json`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `mode`, `valid`, `completeness`, `completenessReasons`, `diagnostics`, resolved identities) | Schema **`1.5`** adds optional stable finding refs on diagnostics: `findingRef` (`fnv1a-` + hex), `targetKey` (baseline-compatible freeze identity), `docsCodePath` (`docs/diagnostics.md#RULE_ID`). Factory-emitted diagnostics always include them; consumer-owned 1.0–1.4 values remain valid without them. `1.4` added optional `evidence.arkruleId` / `evidence.arkruleSource` for ArkRules; `1.3` distinguished `resolved-candidate-facts` from `lexical-compatibility`; partial/unavailable analysis is always non-green, and resolved complete/partial results require policy/resolver/facts/tree identities. `1.2` added completeness and remains accepted alongside consumer-owned 1.0/1.1 values. |
+| **`arkgate/schema/analysis-result`** or **`arkgate/schema/ark.analysis-result.schema.json`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `mode`, `valid`, `completeness`, `completenessReasons`, `diagnostics`, resolved identities) | Schema **`1.5`** adds optional stable finding refs on diagnostics: `findingRef` (`fnv1a-` + hex), `targetKey` (baseline-compatible freeze identity), `docsCodePath` (`docs/diagnostics.md#RULE_ID`). Factory-emitted diagnostics always include them; consumer-owned 1.0–1.4 values remain valid without them. Optional `evidence.reasonId` (`CROSS_PARENT_SLICE` / `CROSS_SIBLING_SLICE` / `CROSS_PARENT_VIA_SHARED`) with `evidence.universeFrom` / `universeTo` is additive within `1.5` and outside the baseline key. `1.4` added optional `evidence.arkruleId` / `evidence.arkruleSource` for ArkRules; `1.3` distinguished `resolved-candidate-facts` from `lexical-compatibility`; partial/unavailable analysis is always non-green, and resolved complete/partial results require policy/resolver/facts/tree identities. `1.2` added completeness and remains accepted alongside consumer-owned 1.0/1.1 values. |
 | **Stable finding refs (4.3)** | Root API `adapterFindingTargetKey` / `adapterFindingRefFromTargetKey` / `toAdapterDiagnostic` / `createAdapterResult`; CLI/MCP/repair envelopes via analysis-result diagnostics | Multi-turn re-address without fuzzy message match. `targetKey` **is** the baseline (occurrence) key so freeze identity is never orphaned; `findingRef` is a compact FNV-1a of that key. Line/message drift does not change the ref. Multi-turn fixture: `tests/fixtures/finding-refs/multi-turn-stability.json`. |
 | **Diagnostic code catalog** | Root API `DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`; docs [diagnostics.md](diagnostics.md) (`#RULE_ID` anchors) | Closed vocabulary of public `ruleId`s with why/fix anchors. Cataloguing only — no new rule semantics. Remediation parity is test-guarded. ArkRun `ARKRUN_*` codes (RN05) share dual-depth `nextAction` / `enthusiastHint`; declaration-list adds are mechanical-safe only when the call-site literal already exists. Docs ship in the npm tarball. |
 | **Status manifest** | CLI `ark status [--json] [--vs <ref>]`; MCP `ark_status`; `arkgate/schema/status-manifest`; root API `buildStatusManifest` / `ARK_STATUS_MANIFEST_SCHEMA` / `projectStatusImprovementCompass` | Schema `1.0`. One session/project snapshot: identity binding, honest write-path activation (`hard`\|`advisory`\|`unavailable`), last-check summary, rules residual counts, primary next action, **`improvementCompass`** with honesty **`mode`** `full`\|`subset`\|`unavailable` (residual ids only; always `notAScore: true`; optional `reasonCode`/`reason`/`factsSource`/`contractHash`), optional **`vsBase`** (pin / contract / baseline grow vs a git ref; advisory only), and additive **`arkRun`** (`notAScore`; `present` / `mode` / `extraMergeTeeth` / residual count — null residual is unknown, not green). **Not a score.** Residual never changes gate verdicts. Never prompts (`CI=1` forces JSON). Optional `--expected-root` / `--expected-project-id` (MCP `project`) for matched vs stale identity. |
 | **Agent contract projection** | CLI `ark agents-md [--write] [--check] [--stdout] [--json]`; install/upgrade AGENTS templates; root API `buildAgentProjectionBlock` / `mergeAgentProjectionDocument` | Schema `1.0` (projection markers). Version-stamped managed block (`arkgateVersion` + contract summary + diagnostic short list). **Non-authoritative** — not a gate input; enforcement is ark-check / hooks / CI. Content-identity merge preserves customized regions outside markers. Drift: `--check` vs package version. |
 | **Agent Skills packaging** | `templates/agent-skills/<name>/SKILL.md` (+ package README); root API `ARK_SKILL_NAMES` / `ARK_FIRST_CLASS_SKILL_NAMES` / `validateAgentSkillsPackage` / `validateSkillProductCapacity`; `npm run check:agent-skills` | Schema `1.0` (package contract). Closed catalog (`ARK_SKILL_NAMES`): first-class doors plus one-release stubs, 1:1 with flat `templates/skills/*.md`. First-class `/ark-order` (issue #216 / ADR 0036). `check:agent-skills` fails closed when a product plane or the north star drops out of skill bodies or living hubs. Add a name only with a live ROADMAP item. |
 | **`arkgate/schema/arkrules`** or **`arkgate/schema/ark.arkrules.schema.json`** | Per-layer structure sensors + invariant catalog (ADR 0012) | Schema `1.0`. Opt-in via root `arkRules` map (`ark.config` schema `1.1`). |
+| **Invariant probe** | CLI `arkgate-check --probe-invariants[=<id>] [--write] [--json] [--runner vitest\|jest\|node]` → JSON `probeInvariants`; optional committed `.ark/invariant-probe.json`; **`arkgate/schema/invariant-probe`** or **`arkgate/schema/ark.invariant-probe.schema.json`**; coverage evidence `probe` (type `InvariantProbeSummary`); promotion blocker `probe-survived`; doctor `rulesUnderContract.probe` and `--rules-inventory` `coverageEvidence.probe` when the file exists; catalog `INVARIANT_PROBE_SURVIVED` | Schema `1.0`, always `notAScore: true`. **Owner-invoked only** ([ADR 0039](adr/0039-invariant-mutation-probe.md)): runs the project's own covering tests (vitest, jest or `node --test`) in a temporary copy; never in the write hook, MCP, ESLint, the GitHub Action or `--strict-merge` (flag pairings refused). Closed operator set `ip-ops@1`, at most 3 changes per invariant after a green baseline and two wiring checks; rows `killed` \| `survived` \| `not-reached` \| `inconclusive` \| `unprobeable`, each bound to SHA-256 hashes of the symbol file, the covering tests and the invariant (without `mode`). The artifact can **only subtract**: a fresh `survived` / `not-reached` row refuses promotion on `--promote` and the policy delta; stale, killed, inconclusive, unprobeable, malformed or absent changes nothing. Exit 0 / 1 survived or not reached / 2 could not run (`reasonCode`). Best-effort environment allowlist — not a sandbox. Not a mutation score. No config key. |
 | **`arkgate/schema/resolved-candidate-facts`** or **`arkgate/schema/ark.resolved-candidate-facts.schema.json`** | Versioned parity-capable input for `analyzeResolvedProject` / `preflightResolvedChange` | Schema `1.2` is additive: optional `classShapes` (1.1) plus ArkRun `arkRunKernelCalls` / `arkRunManagedNews` / `arkRunCompositionRootHits` / `arkRunDeclarations` (RN03–RN04) and ArkOrder `arkOrderPlaneCalls` / `arkOrderGenericUpdates` / `arkOrderRootHits` (OR05). `1.0`/`1.1` payloads remain loadable. Tooling owns filesystem/compiler resolution; Domain/Kernel validate and evaluate supplied facts without importing those effects. Facts name resolver/compiler inputs, governed files, dependency evidence, completeness reasons, candidate tree/facts hashes, and (when present) ArkRun/ArkOrder call-site evidence. Tier-1 sensors emit `ARKRUN_*` / `ARKORDER_*` diagnostics from those facts: advisory never flips `valid`; enforced blocks. Extra absence is silent. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
 | **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) **or** Agent Skills ecosystem path | **Day zero** is the compact router from `ark start` / `start --apply` + doctor — not the full skill pack. Closed catalog (`ARK_SKILL_NAMES`): first-class doors (including `/ark-order`) plus one-release stubs. Guided expert path remains `/ark-autopilot` after pack install. **4.0:** first-class doors except experimental `/ark-runtime` / `/ark-order` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. **4.2:** repo catalogs are content-idempotent; the optional shared Codex home catalog is monotonic across 4.2.0+ installers. Pre-4.2 writers are outside that protocol and must be upgraded first. A durable pending-catalog journal preserves the floor across an interrupted install and is cleared only by its owning same/newer recovery. **4.3:** Agent Skills–compatible layout at `templates/agent-skills/<name>/SKILL.md` (1:1 with flat `templates/skills/*.md`); install via `npx skills add ./node_modules/arkgate/templates/agent-skills` (or the GitHub tree). **#216:** first-class `/ark-order`; ACS05 freeze opened (ADR 0036). Domain `ARK_SKILL_NAMES` + `validateAgentSkillsPackage` + `validateSkillProductCapacity`; drift `npm run check:agent-skills` (layout **and** 100% product coverage). Skills never enforce. |
-| **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import/purity rules plus ArkRun import/`new` envelope (`ark/no-arkrun-kernel-in-domain`, `ark/no-arkrun-direct-new`, `ark/no-arkrun-transport-bypass`) when `arkRun` is on, and ArkOrder envelope (`ark/no-arkorder-kernel-in-domain`, `ark/no-arkorder-generic-update`) when `arkOrder` is on; loads consumer `ark.config.json`. Absence of an extra is silent. Missing-root / missing-plane and undeclared-* stay CLI/MCP. |
+| **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import/purity rules plus ArkRun import/`new` envelope (`ark/no-arkrun-kernel-in-domain`, `ark/no-arkrun-direct-new`, `ark/no-arkrun-transport-bypass`) when `arkRun` is on, ArkOrder envelope (`ark/no-arkorder-kernel-in-domain`, `ark/no-arkorder-generic-update`) when `arkOrder` is on, and ArkRules structure sensors (`ark/arkrules-structure`) when `arkRules` is on; loads consumer `ark.config.json`. Non-blocking findings (ark-check warnings) report on the warn-level `ark/architecture-advisory` (when that rule is not enabled they fall back to the blocking rule id, tagged advisory). `require('arkgate/eslint')` and the ESM default are the same plugin object (`meta`, `rules`, `configs`). Absence of an extra is silent. Missing-root / missing-plane, undeclared-*, and ArkRules invariant coverage stay CLI/MCP. |
 | **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 | **Package metadata** | `arkgate/package.json` | Stable resource subpath for tooling that needs the installed manifest. |
 
@@ -141,6 +144,8 @@ are grouped below.
 | Design delta contract | `ARK_DESIGN_DELTA_SCHEMA_VERSION` |
 | Analysis IR + resolved facts | `ANALYSIS_IR_SCHEMA_VERSION`, `RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION`, `RESOLVED_CANDIDATE_FACTS_SCHEMA`, `createResolvedCandidateFacts`, `loadResolvedCandidateFacts`, `resolvedFactsEvidenceRequirementsHash`, `deterministicHash`, `stableSerialize` |
 | Config contract | `ARK_CONFIG_SCHEMA`, `ARK_CONFIG_SCHEMA_VERSION`, `loadArkConfigContract`, `parseArkConfigJson` |
+| ArkRules contract | `ARK_RULES_SCHEMA`, `ARK_RULES_SCHEMA_VERSION`, `ARK_RULE_SENSORS`, `ArkRulesValidationError`, `buildEffectiveArkRules`, `emptyEffectiveArkRules`, `loadArkRulesContract`, `parseArkRulesJson` (`parseArkRulesJson` / `loadArkRulesContract` throw `ArkRulesValidationError` with `.issues: ArkRulesIssue[]`) |
+| Effective contract | `EffectiveContractError`, `effectiveContractPolicyPayload`, `resolveEffectiveContract` |
 
 The type-only root exports are also semver-supported:
 
@@ -178,6 +183,7 @@ The type-only root exports are also semver-supported:
   `AnalysisFile`, `AnalysisImportEdge`, `AnalysisCapabilityUse`, `AnalysisEvidence`,
   `AnalysisViolation`, `AnalysisIr`.
 - Config contract: `ArkConfig`, `ArkConfigLoadResult`.
+- ArkRules contract: `ArkRulesFile`, `ArkRulesIssue`, `EffectiveArkRules`.
 
 Runtime-kernel factories, `CAPABILITY_IDS`, `collectCapabilityUses`, and Domain capability mapping
 helpers are deliberately absent from this root. Use `arkgate/runtime` for the
@@ -195,9 +201,9 @@ claims. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, `/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` / `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). |
+| **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**; the default event buffer is capped at `maxHistorySize` and settled after local delivery, and broker handoff outcomes (including failures, as `event.handoffFailed`) are recorded. `createStrictArkKernelFromConfig` gives canonical layer names (what `ark init` writes) their built-in intent prefixes; a custom-named deny-rule layer without `intentPrefixes` is recorded as a `layer.observedFlowUnresolvable` audit record, and throws `ArkKernelConfigError` only when `enforceObservedLayerFlow: 'hard'` is passed explicitly. 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` and `arkgate/nestjs` load **one shared kernel chunk**, so errors thrown by an `ArkModule` kernel pass `instanceof` against the classes exported from `arkgate/runtime`. `ArkModule.forRoot()` / `forRootAsync()` count as an ArkRun composition-root factory; a Domain-role import of `arkgate/nestjs` is `ARKRUN_KERNEL_IN_DOMAIN`. `@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` / `restore`. No `update`. First freeze is `release()`; later ξ change is `apply` (`ARKORDER_UNVALVED_RELEASE`). `apply` rejects a proposal not computed against the current Release (`ARKORDER_STALE_PROPOSAL`). `restore(release)` reinstalls a validated `Release` (frozen or JSON-deserialized; hash remains identity; not durable) onto an empty plane or at the same ξ at the current or next version (no rollback, no jump; a freeze time after the plane clock fails closed); `ReleaseStore.load()` output is validated the same way (hashes are a consistency check, not a signature), and the plane advances only after `save()` returns. `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). |
 
 ---
 
@@ -212,6 +218,26 @@ import { createOrderPlane, hashOf } from 'arkgate/order';
 
 One install: `npm install arkgate`. `@arkgate/runtime` is deprecated.
 
+**Types for ESM and CommonJS consumers.** Every code entry (`arkgate`, `arkgate/eslint`,
+`arkgate/order`, `arkgate/runtime`, `arkgate/nestjs`) maps `import` to `index.js` +
+`index.d.ts` and `require` to `index.cjs` + `index.d.cts`, and the package ships both
+declaration sets. A CommonJS TypeScript project (`.cts`, or `module` / `moduleResolution`
+`node16` without `"type": "module"`, the usual NestJS shape) type-checks `require` /
+`import x = require(...)` against the CJS declarations. `typesVersions` maps the subpaths for
+legacy `moduleResolution: node10`. Through 4.8.23 the tarball dropped `*.d.cts`, so those
+consumers got TS1471 / TS1479 / TS2307 although runtime `require()` worked.
+
+### MCP server via npx and the MCP Registry
+
+`npx arkgate@<version> <args>` always runs the bin named after the package, `arkgate`. So
+`arkgate mcp [--root <dir>] [--config <path>] [--hook]` starts the same stdio MCP server as
+`arkgate-mcp`, and forwards every flag to it. The MCP Registry descriptor (`server.json`) launches
+`npx arkgate@<version> mcp --root .` with no `--config`, so it starts in a fresh project too
+(the server reads `ark.config.json` when present; an explicit `--config` to a missing file exits
+1). `arkgate arkgate-mcp` and `arkgate ark-mcp` are accepted as well. Registry entries published
+through 4.8.23 pin arkgate versions that have no `mcp` route, so they keep failing until the
+descriptor is republished for a version that has it.
+
 ---
 
 ## Installing from git

package/docs/product-voice.md

@@ -80,7 +80,7 @@ On the seven lane openings — `docs/use.md`, `docs/develop.md`, `docs/README.md
 `README.md` is the first-contact module. Its first screen is four beats: what
 (**Contener · Guiar · Ordenar**), why (design the boundary before you implement;
 a green check is **needs a refactor** when leftover mess remains), one command
-(`npx arkgate@4.8.23 start`), and one honest red result (fail-open named; required
+(`npx arkgate@4.8.25 start`), and one honest red result (fail-open named; required
 CI is the hard line). The four paragraphs, the not-that line, the host matrix,
 and the release index sit below `## Appendix`. The not-that line does not lead
 the README.
@@ -134,6 +134,9 @@ Three beats when a line teaches:
 | ArkRun is experimental. In-memory. Data is gone on restart. | The kernel is production-ready |
 | The agent PATCHed the billing plan as if it were a seat count. The write didn’t land. Next: `proposeRelease` then `apply`, not `update`. | Freeze ξ. Four verbs. Haken slaving. |
 | Status: one light, one next step. | Become an architect in 60 seconds |
+| Nothing imports src/lib/legacy-pricing.ts, and no entry point covers it. Next: delete it through the write gate. | Dead code detected! Auto-removing unused files |
+| This code is copied between features/billing and features/invoices. The wall stops the import, not the copy. Next: move it to shared/ with `/ark-place`. | 12.4% duplication! Refactor score: C |
+| INV-REFUND-WINDOW: the tests still pass when the refund guard is negated. The test names the rule but does not pin it. Next: add a case that fails when the window is crossed. | Mutation score 67%! 2 of 3 mutants killed |
 
 **Brands, then the common word:** ArkGate, ArkRules, ArkRun, ArkOrder. Gloss once.
 
@@ -212,6 +215,9 @@ a product PR — that is an owner `--contract-session` (config change).
 - ArkRun as Postgres, an outbox, or Temporal
 - ArkOrder as durable storage, a second npm package, or a replacement for ArkRun
 - New skill *names* without a live queue item
+- “Dead code” for a file nothing imports — say what was seen (nothing imports it), and say when a dynamic import may still load it
+- A duplication percentage or score for copies — name the two places and the wall between them, and where the shared code could live
+- A mutation score or percentage for the invariant probe — say which change went unnoticed, where, and which test to add
 - “the house stays up” / “training wheels” / “mimo” on first contact
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.23",
+  "version": "4.8.25",
   "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",
@@ -8,29 +8,54 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./eslint": {
-      "types": "./dist/eslint/index.d.ts",
-      "import": "./dist/eslint/index.js",
-      "require": "./dist/eslint/index.cjs"
+      "import": {
+        "types": "./dist/eslint/index.d.ts",
+        "default": "./dist/eslint/index.js"
+      },
+      "require": {
+        "types": "./dist/eslint/index.d.cts",
+        "default": "./dist/eslint/index.cjs"
+      }
     },
     "./order": {
-      "types": "./dist/order/index.d.ts",
-      "import": "./dist/order/index.js",
-      "require": "./dist/order/index.cjs"
+      "import": {
+        "types": "./dist/order/index.d.ts",
+        "default": "./dist/order/index.js"
+      },
+      "require": {
+        "types": "./dist/order/index.d.cts",
+        "default": "./dist/order/index.cjs"
+      }
     },
     "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js",
-      "require": "./dist/runtime/index.cjs"
+      "import": {
+        "types": "./dist/runtime/index.d.ts",
+        "default": "./dist/runtime/index.js"
+      },
+      "require": {
+        "types": "./dist/runtime/index.d.cts",
+        "default": "./dist/runtime/index.cjs"
+      }
     },
     "./nestjs": {
-      "types": "./dist/nestjs/index.d.ts",
-      "import": "./dist/nestjs/index.js",
-      "require": "./dist/nestjs/index.cjs"
+      "import": {
+        "types": "./dist/nestjs/index.d.ts",
+        "default": "./dist/nestjs/index.js"
+      },
+      "require": {
+        "types": "./dist/nestjs/index.d.cts",
+        "default": "./dist/nestjs/index.cjs"
+      }
     },
     "./schema": "./schemas/ark.config.schema.json",
     "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
@@ -50,8 +75,26 @@
     "./schema/ark.arkrules.schema.json": "./schemas/ark.arkrules.schema.json",
     "./schema/status-manifest": "./schemas/ark.status-manifest.schema.json",
     "./schema/ark.status-manifest.schema.json": "./schemas/ark.status-manifest.schema.json",
+    "./schema/invariant-probe": "./schemas/ark.invariant-probe.schema.json",
+    "./schema/ark.invariant-probe.schema.json": "./schemas/ark.invariant-probe.schema.json",
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "eslint": [
+        "./dist/eslint/index.d.ts"
+      ],
+      "order": [
+        "./dist/order/index.d.ts"
+      ],
+      "runtime": [
+        "./dist/runtime/index.d.ts"
+      ],
+      "nestjs": [
+        "./dist/nestjs/index.d.ts"
+      ]
+    }
+  },
   "bin": {
     "arkgate": "bin/ark.mjs",
     "arkgate-check": "bin/ark-check.mjs",
@@ -74,7 +117,6 @@
     "!bin/lib/safety-diagnostics.mjs",
     "!bin/lib/ts-resolve.mjs",
     "dist",
-    "!dist/**/*.d.cts",
     "schemas",
     "!schemas/*.source.json",
     "docs/README.md",
@@ -125,6 +167,8 @@
     "security:audit": "npm audit --omit=dev --audit-level=high",
     "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict",
     "check:js": "node scripts/check-js-syntax.mjs",
+    "check:knip": "knip",
+    "check:duplication": "jscpd --config .jscpd.json",
     "generate:layer-match": "node scripts/generate-layer-match.mjs",
     "check:layer-match": "node scripts/generate-layer-match.mjs --check",
     "generate:cli-pure": "node scripts/generate-cli-pure.mjs",
@@ -168,7 +212,8 @@
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepublishOnly": "npm run build",
-    "bench:hook-path": "node scripts/hook-path-bench.mjs"
+    "bench:hook-path": "node scripts/hook-path-bench.mjs",
+    "bench:memory": "node scripts/memory-bench.mjs"
   },
   "dependencies": {
     "typescript-ark-host": "npm:typescript@6.0.3"
@@ -193,7 +238,7 @@
     "browserslist": "4.28.8",
     "nanoid": "3.3.18",
     "brace-expansion@2": "2.1.4",
-    "brace-expansion@5": "5.0.9",
+    "brace-expansion@5": "5.0.12",
     "tsup": {
       "esbuild": "0.28.1"
     },
@@ -203,12 +248,17 @@
   },
   "devDependencies": {
     "@nestjs/common": "^11.1.27",
+    "@stryker-mutator/api": "9.6.1",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^20.14.0",
     "@vitest/coverage-v8": "^4.1.11",
+    "acorn": "8.17.0",
+    "ajv": "8.18.0",
     "esbuild": "0.28.1",
     "fast-check": "^4.9.0",
+    "knip": "6.39.0",
+    "jscpd": "5.4.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",

package/schemas/ark.analysis-result.schema.json

@@ -246,6 +246,21 @@
               "arkruleSource": {
                 "type": "string",
                 "minLength": 1
+              },
+              "reasonId": {
+                "enum": [
+                  "CROSS_PARENT_SLICE",
+                  "CROSS_SIBLING_SLICE",
+                  "CROSS_PARENT_VIA_SHARED"
+                ]
+              },
+              "universeFrom": {
+                "type": "string",
+                "minLength": 1
+              },
+              "universeTo": {
+                "type": "string",
+                "minLength": 1
               }
             }
           },

package/schemas/ark.config.schema.json

@@ -631,8 +631,22 @@
     "arkRules": {
       "type": "object",
       "additionalProperties": {
-        "type": "string",
-        "minLength": 1
+        "description": "A project-relative ArkRules path, or a list of paths merged into one catalog for this layer. A string keeps today's behaviour. An older build that types this value as a string rejects an array at config load.",
+        "oneOf": [
+          {
+            "type": "string",
+            "minLength": 1
+          },
+          {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ]
       },
       "default": {}
     },
@@ -804,7 +818,7 @@
             "path",
             "stars"
           ],
-          "description": "How a starred sliceFolders prefix is named. Absent and path keep today's ids (every literal and star binding). stars keeps the last literal plus the star bindings, so parallel trees share one feature id. Bare names are unchanged."
+          "description": "How a starred sliceFolders prefix is named. Absent and path keep today's ids (every literal and star binding). stars keeps the last literal plus every star binding (a star before the last literal is kept too), so parallel trees share one feature id. Bare names are unchanged."
         },
         "sharedRoots": {
           "type": "array",
@@ -838,12 +852,41 @@
           }
         },
         "sharedImportsSlice": {
-          "type": "string",
-          "enum": [
-            "deny",
-            "deny-cross-parent"
-          ],
-          "description": "deny blocks every shared-root import of a slice. deny-cross-parent leaves that hop as a warning and, in ark-check and CI only, reports a slice that reaches another universe through a shared root. The write hook and ESLint see one edge and do not block it. arkgate 4.8.22 and older reject deny-cross-parent."
+          "description": "deny blocks every shared-root import of a slice. deny-cross-parent leaves that hop as a warning and, in ark-check and CI only, reports a slice that reaches another universe through a shared root. The write hook and ESLint see one edge and do not block it. The object form { mode: \"deny-cross-parent\", stopAt } names composition roots (bootstrap, DI registrations) the whole-graph walk never starts at or passes through; a stop file must still sit under sharedRoots, and stopAt does not silence the direct SHARED_IMPORTS_SLICE warning. arkgate 4.8.22 and older reject deny-cross-parent. arkgate 4.8.23 and older reject the object form (must be one of deny, deny-cross-parent).",
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "deny",
+                "deny-cross-parent"
+              ]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "mode",
+                "stopAt"
+              ],
+              "properties": {
+                "mode": {
+                  "type": "string",
+                  "enum": [
+                    "deny-cross-parent"
+                  ]
+                },
+                "stopAt": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true,
+                  "minItems": 1
+                }
+              }
+            }
+          ]
         },
         "childSlices": {
           "type": "object",
@@ -851,7 +894,7 @@
           "required": [
             "sliceFolders"
           ],
-          "description": "Optional inner wall under this rule. Absent keeps today's universe wall. sliceFolders names children. commonFolders and flat files are universe common. siblings is \"deny\" (default), \"advisory\", or { default, enforce }. parentMayImportChild defaults to false. allowedCrossSlice may use a whole-segment *. It clears only a sibling crossing. Cross-parent has no advisory knob. arkgate 4.8.22 and older reject this key. A build that still rejects unknown childSlices fields rejects allowedCrossSlice at config load. A build that still types siblings as a string enum rejects the object at config load.",
+          "description": "Optional inner wall under this rule. Runs only on a rule with peerIsolation: true and allowed: false; elsewhere it is inert and ark-check warns CONFIG_CHILD_SLICES_INERT (config load still accepts it, as 4.8.23 did). Absent keeps today's universe wall. sliceFolders names children. Flat files are universe common, and so is a commonFolders directory directly under the universe (a folder of that name inside a child belongs to that child). siblings is \"deny\" (default), \"advisory\", or { default, enforce, ratchet }. parentMayImportChild defaults to false. message is the text for inner-wall findings. allowedCrossSlice may use a whole-segment *. It clears only a sibling crossing. Cross-parent has no advisory knob. arkgate 4.8.22 and older reject this key. A build that still rejects unknown childSlices fields rejects allowedCrossSlice at config load. A build that still types siblings as a string enum rejects the object at config load.",
           "properties": {
             "sliceFolders": {
               "type": "array",
@@ -879,7 +922,7 @@
               "minItems": 1
             },
             "siblings": {
-              "description": "\"deny\" or \"advisory\", or { default, enforce } so listed subtrees are errors while the default stays advisory. A string-enum build rejects the object at config load (must be one of deny, advisory).",
+              "description": "\"deny\" or \"advisory\", or { default, enforce, ratchet } so listed subtrees are errors while the default stays advisory. ratchet absent: a new advisory crossing fails only when the baseline in use already records an advisory crossing of this rule. ratchet true: any unrecorded advisory crossing fails when a baseline is in use. ratchet false: measure only, never fails. A string-enum build rejects the object at config load (must be one of deny, advisory). arkgate 4.8.23 and older reject ratchet (unknown field).",
               "oneOf": [
                 {
                   "type": "string",
@@ -909,6 +952,9 @@
                         "minLength": 1
                       },
                       "uniqueItems": true
+                    },
+                    "ratchet": {
+                      "type": "boolean"
                     }
                   }
                 }
@@ -917,10 +963,20 @@
             "parentMayImportChild": {
               "type": "boolean"
             },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "description": "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 fail-closed denies). Absent: ArkGate default text, never the rule message. arkgate 4.8.23 and older reject this field (unknown field)."
+            },
+            "arkRulesFile": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Filename read at each child slice root this wall already resolved. The only token is <Layer>, replaced with a declared layer name (arkrules.<Layer>.json). No slash and no wildcard. A discovered file that omits appliesTo is scoped to that slice directory. Explicit appliesTo outside the slice fails config load (ARKRULE_SCOPE_ESCAPES_SLICE). The effective id is <childId>#<localId>. A build that rejects unknown childSlices fields fails at config load (unknown field)."
+            },
             "sliceAliases": {
               "type": "array",
               "minItems": 1,
-              "description": "Maps a source path glob onto a child slice id (universe id plus one child segment) so files outside the slice trees take that universe and child for both walls. A bare name, a universe id alone, an unknown universe, and a wildcard in to are rejected. The glob may not overlap a slice folder, and two aliases may not match the same file. Doctor lists each alias as an owed move. A build that rejects unknown childSlices fields fails at config load (unknown field). arkgate 4.8.22 and older reject childSlices.",
+              "description": "Maps a source path glob onto a child slice id (universe id plus one child segment) so files outside the slice trees take that universe and child for both walls. A path without a wildcard also covers everything under it, as sharedRoots does. A bare name, a universe id alone, a target outside every universe shape, and a wildcard in to are rejected. Under stars identity a target written against the 4.8.23 stars id (star bindings before the last literal dropped, e.g. api/v1/x for modules/*/api/*) still loads when it maps to one universe shape, and ark-check warns CONFIG_SLICE_LEGACY_STARS_ID with the new id; it is rejected only when it maps to more than one shape. Config load checks only the shape; doctor reports a target universe no file belongs to. The glob may not overlap a slice folder, and two aliases may not match the same file. Doctor lists each unpinned alias as an owed move. pinned true lists the alias separately and does not count it as debt. reason is a doctor label and does not pin by itself. A build that rejects unknown childSlices fields fails at config load (unknown field). arkgate 4.8.22 and older reject childSlices.",
               "items": {
                 "type": "object",
                 "additionalProperties": false,
@@ -936,6 +992,15 @@
                   "to": {
                     "type": "string",
                     "minLength": 1
+                  },
+                  "pinned": {
+                    "type": "boolean",
+                    "description": "True when a framework forces the path to stay. The alias is not an owed move and does not clear other honesty debt."
+                  },
+                  "reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Doctor label, such as framework-route. A label alone does not pin."
                   }
                 }
               }