arkgate 4.8.24 → 4.8.26

package/docs/diagnostics.md

@@ -29,6 +29,8 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`LAYER_REFERENCE_VIOLATION`](#LAYER_REFERENCE_VIOLATION) | layer | Layer reference blocked (snippet / AI gate) |
 | [`SHARED_IMPORTS_SLICE`](#SHARED_IMPORTS_SLICE) | layer | A shared root imports a slice |
 | [`CIRCULAR_DEPENDENCY`](#CIRCULAR_DEPENDENCY) | layer | Dependency cycle |
+| [`CROSS_WALL_DUPLICATE`](#CROSS_WALL_DUPLICATE) | layer | Code copied across a wall |
+| [`CROSS_LAYER_DUPLICATE`](#CROSS_LAYER_DUPLICATE) | layer | Code copied in two layers |
 | [`FORBIDDEN_GLOBAL`](#FORBIDDEN_GLOBAL) | capability | Forbidden ambient global or dual import |
 | [`CAPABILITY_VIOLATION`](#CAPABILITY_VIOLATION) | capability | Denied effect capability |
 | [`RAW_EVENT_PUBLISH`](#RAW_EVENT_PUBLISH) | publish | Raw event publish |
@@ -46,10 +48,13 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ARKRULE_SCOPE_EMPTY`](#ARKRULE_SCOPE_EMPTY) | arkrules | ArkRule appliesTo matched zero files |
 | [`ARKRULE_HINT_BUDGET_EXHAUSTED`](#ARKRULE_HINT_BUDGET_EXHAUSTED) | arkrules | Structural-hint budget exhausted |
 | [`ARKRULE_FILE_UNREFERENCED`](#ARKRULE_FILE_UNREFERENCED) | arkrules | ArkRules file not referenced |
+| [`ARKRULE_DUPLICATE_ID`](#ARKRULE_DUPLICATE_ID) | arkrules | ArkRule id declared more than once |
+| [`ARKRULE_SCOPE_ESCAPES_SLICE`](#ARKRULE_SCOPE_ESCAPES_SLICE) | arkrules | Slice ArkRule appliesTo leaves its slice |
 | [`INVARIANT_CATALOG_EMPTY`](#INVARIANT_CATALOG_EMPTY) | arkrules | Domain invariant catalog is empty |
 | [`INVARIANT_UNCOVERED`](#INVARIANT_UNCOVERED) | arkrules | Invariant without coverage evidence |
 | [`INVARIANT_COVERAGE_OUTSIDE_ROOTS`](#INVARIANT_COVERAGE_OUTSIDE_ROOTS) | arkrules | Covering test outside the declared coverage roots |
 | [`INVARIANT_COVERAGE_ROOTS_MISSING`](#INVARIANT_COVERAGE_ROOTS_MISSING) | arkrules | Coverage roots missing while an invariant is enforced |
+| [`INVARIANT_PROBE_SURVIVED`](#INVARIANT_PROBE_SURVIVED) | arkrules | Covering tests do not pin the invariant |
 | [`INVARIANT_TESTS_PATH_MISSING`](#INVARIANT_TESTS_PATH_MISSING) | arkrules | Domain-invariant tests path missing under adopted |
 | [`ARKRUN_MISSING_ROOT`](#ARKRUN_MISSING_ROOT) | arkrun | No kernel factory in composition roots |
 | [`ARKRUN_KERNEL_IN_DOMAIN`](#ARKRUN_KERNEL_IN_DOMAIN) | arkrun | Domain-role layer imports the kernel |
@@ -83,6 +88,8 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ANALYSIS_HOST_UNAVAILABLE`](#ANALYSIS_HOST_UNAVAILABLE) | analysis | Analysis host unavailable |
 | [`LITERAL_PATH_DRIFT`](#LITERAL_PATH_DRIFT) | drift | Literal path moved by a rename |
 | [`LITERAL_PATH_UNRESOLVED`](#LITERAL_PATH_UNRESOLVED) | drift | Literal path does not resolve |
+| [`ORPHAN_MODULE`](#ORPHAN_MODULE) | drift | File nothing imports |
+| [`UNUSED_EXPORT`](#UNUSED_EXPORT) | drift | Export nothing imports by name |
 | [`ADAPTER_NOT_ALLOWED_FOR_PORT`](#ADAPTER_NOT_ALLOWED_FOR_PORT) | adapter | Adapter not allowed for port |
 | [`FORBIDDEN_PATTERN`](#FORBIDDEN_PATTERN) | snippet-policy | Forbidden regex pattern |
 | [`FORBIDDEN_SUBSTRING`](#FORBIDDEN_SUBSTRING) | snippet-policy | Forbidden substring |
@@ -320,8 +327,26 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 
 **ArkRules file not referenced** · often advisory
 
-- **Why:** A JSON file under `arkrules/` is not referenced by the `arkRules` map in ark.config.json (or no map exists), so none of its rules are enforced or reported. Drift looks like governance until someone notices.
-- **Fix:** Reference the file from `arkRules` (`"<Layer>": "arkrules/<file>.json"`), or delete it. Advisory only: it never fails the check.
+- **Why:** A JSON file under `arkrules/`, or a slice file named `arkrules.<Layer>.json` beside governed code, is not in the effective catalog, so none of its rules are enforced. Drift looks like governance until someone notices.
+- **Fix:** Reference a central file from `arkRules`, set `childSlices.arkRulesFile` so a slice file is discovered, or delete it. Advisory only: it never fails the check.
+
+<a id="ARKRULE_DUPLICATE_ID"></a>
+
+### `ARKRULE_DUPLICATE_ID`
+
+**ArkRule id declared more than once**
+
+- **Why:** Two ArkRules files in one layer declare the same effective id. Central ids stay bare. A slice file is namespaced as `<childId>#<localId>`, so the same local id in two slices is not a duplicate.
+- **Fix:** Rename one id, or split the files onto different slices. Config load fails closed. The catalog is not enforced until the id is unique.
+
+<a id="ARKRULE_SCOPE_ESCAPES_SLICE"></a>
+
+### `ARKRULE_SCOPE_ESCAPES_SLICE`
+
+**Slice ArkRule appliesTo leaves its slice**
+
+- **Why:** A file discovered from `childSlices.arkRulesFile` set `appliesTo` to a glob that can match outside that child slice. The default, when `appliesTo` is omitted, is the slice directory.
+- **Fix:** Narrow `appliesTo` to the slice directory, or omit it. Config load fails closed. The escaping rule is not enforced.
 
 <a id="INVARIANT_CATALOG_EMPTY"></a>
 
@@ -363,6 +388,17 @@ Declaring nothing is silent unless any catalogued invariant is enforced — then
 
 No enforced invariant, or roots already declared, stays silent. This is not a new config key. Promotion to enforced also refuses without roots.
 
+<a id="INVARIANT_PROBE_SURVIVED"></a>
+
+### `INVARIANT_PROBE_SURVIVED`
+
+**Covering tests do not pin the invariant** · often advisory
+
+- **Why:** The committed invariant probe (`.ark/invariant-probe.json`, written by `arkgate-check --probe-invariants --write`) shows, for files that have not changed since, that the covering tests still pass with the invariant's `coverage.symbol` broken on purpose (`survived`), or never call it (`not-reached`). The test names the rule but does not pin it.
+- **Fix:** Add a test case that fails when the rule is broken — the line names the change that went unnoticed — then re-run `arkgate-check --probe-invariants --write` and commit the file. Promotion to `enforced` refuses while the fresh artifact says `survived` or `not-reached`.
+
+A status (`--doctor`) and `--rules-inventory` line only. It never enters the check, so `valid`, `--strict-merge` and the exit code do not change. A stale row (the symbol file, a covering test or the invariant changed since the run), `killed`, `inconclusive`, `unprobeable`, or no artifact at all changes nothing. The probe is opt-in, runs your own test runner in a temporary copy, and is not a mutation score — see [Probe an invariant](agent-guide.md#probe-an-invariant).
+
 <a id="INVARIANT_TESTS_PATH_MISSING"></a>
 
 ### `INVARIANT_TESTS_PATH_MISSING`
@@ -698,7 +734,7 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 
 **Analysis covered no files**
 
-- **Why:** No file matched the contract `include` and layer patterns under the analyzed root, so the run had nothing to check. Every rule is vacuously satisfied on an empty set: a green here would read exactly like a green over a governed tree while certifying nothing. Usual causes are a `--root` that is not the tree the contract describes (including a contract found outside the requested root, whose directory is then adopted as the project root), `include` / `exclude` patterns that match nothing, layer patterns written for a different layout, or an `include` that matched files none of which belong to a layer.
+- **Why:** No file matched the contract `include` and layer patterns under the analyzed root, so the run had nothing to check. Every rule is vacuously satisfied on an empty set: a green here would read exactly like a green over a governed tree while certifying nothing. Usual causes are a `--root` the contract misses, basename walk-up adopting a parent that governs nothing, or `include` / `exclude` / layer patterns that match nothing. An explicit `--config` path stays a file: the check runs on `--root`.
 - **Fix:** Point `--root` at the tree the contract describes, or keep the contract inside that tree, or fix the `include` / `exclude` / layer patterns so they match real files — then re-run `npx arkgate-check --root . --config ark.config.json`. `--plan` and `--coverage` report the empty scope without refusing, and `--adopt-contract --write` proposes an `include` that matches the tree. This is a refusal about ArkGate's own inputs, not a finding about your code; no baseline or policy acknowledgement can suppress it, and `exclude` cannot silence it — the "is there source here" probe deliberately ignores the contract's own `exclude`, skips dot-directories, never follows a symlink, and skips `*.config.*` tooling files so a polyglot repo is not mistaken for a mismatch.
 
 <a id="ANALYSIS_HOST_UNAVAILABLE"></a>
@@ -755,6 +791,86 @@ by default would be ArkGate's inability to resolve a string presented as a fact
 about your code. The count is always printed, so opting out of the list is
 never opting out of knowing.
 
+## Files nothing imports
+
+Status (`arkgate-check --doctor`) reads the import edges the check already
+resolved. A governed file that nothing imports — no governed file, no test,
+no project script, no known entry point — is listed in status details
+(`--doctor --all`), in `--json` under `doctor.orphanModules`, and in the
+HTML report. The compact status prints one count line at most. It is not a
+score and never changes the check.
+
+Entry points come from a closed list: `package.json` (`main`, `module`,
+`types`, `exports`, `bin`, scripts) and CI workflow run steps, framework
+conventions (Next, Vite, Nest, Vercel, Storybook), the arkRun / arkOrder /
+slice-wall roots in `ark.config.json`, config and setup files, ambient
+declaration files, and `.ark/entry-points.json`:
+
+```json
+{
+  "schemaVersion": "1",
+  "entryPoints": [
+    { "glob": "src/plugins/**", "reason": "loaded by name at runtime", "reviewBy": "2027-01-01" }
+  ]
+}
+```
+
+<a id="ORPHAN_MODULE"></a>
+
+### `ORPHAN_MODULE`
+
+**File nothing imports** · often advisory
+
+- **Why:** No governed file, test or entry point imports this module. It is the leftover an agent leaves when a rewrite lands next to the old file. Status reads it from the import facts the check already resolved, so it never changes the verdict. When a dynamic import, an unresolved import or an unmapped entry could reach the file, the item says so (`maybe-dynamic`, `maybe-unresolved`) and the list is `partial`.
+- **Fix:** Delete the file through the write gate, one file at a time. If a framework, a script or a runtime loader uses it, add a glob with a reason to `.ark/entry-points.json` (optional `reviewBy`) instead. Advisory only — it never fails a run.
+
+<a id="UNUSED_EXPORT"></a>
+
+### `UNUSED_EXPORT`
+
+**Export nothing imports by name** · often advisory
+
+- **Why:** An export no governed file or test imports by name. Listed only in status details (`--doctor --all`) and the report. Default, namespace, star, dynamic and require use count as using every export, so those files are skipped.
+- **Fix:** Drop the export keyword (or the code) if nothing outside the file needs it, or keep it when it is public API an entry point exposes. Advisory only — it never fails a run.
+
+## Copies across a wall
+
+A slice wall denies the import. The cheapest way around it is to copy the
+code, and a copy is not an import. Status details (`arkgate-check --doctor --all`)
+and the HTML report list near-identical code whose copies sit on two sides of
+a wall, or in two layers, with a place the shared code could live. `--json`
+carries it under `doctor.crossWallDuplication`; without `--all` it says
+`not-run` and names the command. It is not a score and never changes the check.
+
+The copies come from token fingerprints taken while status runs: one parse per
+governed file with the TypeScript ArkGate already loaded. Tests, `.d.ts`,
+generated files (default globs, or a `@generated` / `GENERATED FILE` /
+`DO NOT EDIT` header in the first five lines) and files over 256 KB are never
+read for this. A copy is listed only when the import between its two files is
+one the check would deny, or when it sits in two layers. Copies inside one
+slice are counted, never listed. A path the wall cannot classify is counted,
+never listed. The constants are fixed: at least 50 tokens and 5 lines, and at
+least 60% of the names matching. When a cap stops the pass, the section says
+`partial` and how much was left.
+
+<a id="CROSS_WALL_DUPLICATE"></a>
+
+### `CROSS_WALL_DUPLICATE`
+
+**Code copied across a wall** · often advisory
+
+- **Why:** Near-identical code sits on two sides of a slice wall (`cross-slice`, `cross-parent`, `cross-sibling`) or in two layers that may not import each other (`cross-layer-walled`). The wall would deny the import, so the code was copied instead. Fingerprints are taken at status time and never enter the check, so the verdict does not change.
+- **Fix:** Move one copy to a shared home the wall allows — the declared shared root, the universe common folder, or a layer both sides may import — then import it from both sides. One move at a time, through the write gate (`/ark-place` names the destination). Advisory only — it never fails a run.
+
+<a id="CROSS_LAYER_DUPLICATE"></a>
+
+### `CROSS_LAYER_DUPLICATE`
+
+**Code copied in two layers** · often advisory
+
+- **Why:** Near-identical code sits in two layers, and at least one of them may import the other (`cross-layer`).
+- **Fix:** Keep one copy in the lower layer both sides may import, and import it from the other. One move at a time, through the write gate. Advisory only — it never fails a run.
+
 ## Port adapters
 
 <a id="ADAPTER_NOT_ALLOWED_FOR_PORT"></a>

package/docs/package-surface.md

@@ -61,13 +61,15 @@ 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. 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 (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). |
+| **`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`. |
@@ -91,6 +93,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **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. |

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.24 start`), and one honest red result (fail-open named; required
+(`npx arkgate@4.8.26 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.24",
+  "version": "4.8.26",
   "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",
@@ -75,6 +75,8 @@
     "./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": {
@@ -165,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",
@@ -234,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"
     },
@@ -244,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.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": {}
     },
@@ -954,10 +968,15 @@
               "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 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 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,
@@ -973,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."
                   }
                 }
               }