arkgate 4.8.23 → 4.8.25

package/CHANGELOG.md

@@ -5,7 +5,78 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.8.25 — 2026-10-05
+
+**Patch** over **4.8.24**. Weekly accumulate (#342, #344, #345, #346, #347, #348, #349, #350). **Write. Check. Ship.** **No required config migration.** `childSlices.arkRulesFile` and pinned `sliceAliases` need 4.8.25. No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother `ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: released** (tag `v4.8.25`). Run `npm view arkgate@4.8.25 version` to confirm (#314).
+
 ### Added
+- Per-slice ArkRules file `childSlices.arkRulesFile` and pinned `sliceAliases` (#342, #341).
+- `arkgate-check --probe-invariants[=<id>]` checks that the tests covering an
+  invariant actually pin it. A test title that names the rule proves the test
+  exists, not that it would fail if the rule broke. For each invariant with a
+  `coverage.symbol`, the probe copies the project to a temporary folder and
+  runs only the covering tests (titles that name the id, and tests that import
+  the symbol's file) with your own runner — vitest, jest or `node --test`:
+  unchanged, then with the file throwing on load, then with the symbol
+  throwing when called, then with at most three small changes inside it
+  (negate a guard, drop a `throw`, flip or shift a comparison, shift a
+  constant). Each invariant reads `killed`, `survived`, `not-reached`,
+  `inconclusive` or `unprobeable`, with the change that went unnoticed and the
+  line. Your files are never changed. Report by default; `--write` saves
+  `.ark/invariant-probe.json` (new schema export `arkgate/schema/invariant-probe`).
+  Exit 0 when nothing survived, 1 when something did, 2 when it could not run.
+  Not a score.
+- Promotion reads the committed probe result. When `.ark/invariant-probe.json`
+  has a fresh `survived` or `not-reached` row — the symbol file, its covering
+  tests and the invariant unchanged since the run — `--promote` and the policy
+  delta refuse to promote that invariant to `enforced` (blocker
+  `probe-survived`). A stale, `killed`, `inconclusive` or missing result
+  changes nothing, so every promotion without the file behaves as before.
+  Status and `--rules-inventory` show the probe state per invariant when the
+  file exists; new catalog id `INVARIANT_PROBE_SURVIVED` (advisory, never in
+  the check). The probe runs only when you start it: never from the write
+  hook, MCP, ESLint, the GitHub Action or `--strict-merge`, and it refuses to
+  combine with them. The runner gets a short environment allowlist (no
+  tokens); that is best effort, not a sandbox. No config key, no new skill;
+  `/ark-contract` and `/ark-coverage` explain the blocker and the next test to
+  write.
+- Status lists code copied across a wall. When a slice wall denies an import,
+  the cheapest way around it is a copy, and a copy is not an import.
+  `--doctor --all`, the HTML report and `--doctor --all --json` (under
+  `doctor.crossWallDuplication`) now list near-identical code whose copies sit
+  on two sides of a slice wall, in two child slices of one universe, or in two
+  layers, with a place the shared code could live (the declared shared root,
+  the universe common folder, or the lower layer both sides may import).
+  Copies inside one slice are counted, never listed. It reads token
+  fingerprints taken while status runs, with the TypeScript ArkGate already
+  loaded; they never enter the check, so the verdict and `factsHash` do not
+  change. Tests, `.d.ts`, generated files and files over 256 KB are skipped.
+  Fixed thresholds (at least 50 tokens, 5 lines, most names matching), no
+  config key. Compact status never runs it; its JSON says `not-run` and names
+  the command. When a cap stops the pass the section says `partial` and how
+  much was left. New catalog ids `CROSS_WALL_DUPLICATE` and
+  `CROSS_LAYER_DUPLICATE` (advisory). Never a score, never in the write hook,
+  MCP, ESLint, `--changed`, or `--strict-merge`. No new skill; `/ark-place`
+  names the destination and `/ark-fix` moves one copy at a time.
+- Status lists the files nothing imports. A governed file with no importer —
+  no governed file, test, project script, or known entry point — shows in
+  `--doctor --all`, the HTML report, and `--doctor --json` under
+  `doctor.orphanModules`; compact status prints one count line at most. It
+  reads the import edges the check already resolved, so the verdict and
+  `factsHash` do not change. Entry points come from `package.json` (built
+  `dist/` paths map back to source), CI workflow run steps, Next / Vite / Nest /
+  Vercel / Storybook conventions, the arkRun / arkOrder roots, config and setup
+  files, ambient declaration files, and an optional `.ark/entry-points.json`
+  (glob + reason + optional `reviewBy`; not a config key). Files only tests
+  import are counted, not listed. When a dynamic import, `import.meta.glob`, a
+  quoted path, or an unresolved import may still reach a file, the item says
+  so and the list is `partial`. `--doctor --all` and `--report` also list
+  exports nothing imports by name. New catalog ids `ORPHAN_MODULE` and
+  `UNUSED_EXPORT` (advisory). Never a score, never in the write hook, MCP
+  write tools, ESLint, or `--strict-merge`. No new skill; `/ark-explore` maps
+  the list and `/ark-fix` deletes one file at a time through the write gate.
 - Soft doctor residual when Domain is declared but empty and the UI holds the
   rules (`noDomainFrontend`). Projects empty Domain + presentation share, or
   the existing `domain-logic-in-ui` smell. Friendly next step: one Domain file
@@ -48,6 +119,10 @@ in the immutable pre-2.0 archive linked below.
   short phrase templates so the shape is visible. No new skill, schema, or flag.
 
 ### Changed
+- `brace-expansion` is overridden to 5.0.12 (Dependabot medium, quadratic expansion) (#350).
+- Eval fixtures pin Next.js 16.3.6 (#346).
+- The package no longer ships `bin/lib/ark-order-invariants.mjs`, `bin/lib/ark-order-error.mjs`, or `bin/lib/stable-hash.mjs`; no CLI loaded them. ArkOrder invariants still ship in `arkgate/order`. One new generated CLI module, `bin/lib/schema-validation.mjs`, holds the JSON-Schema walker shared by the config and ArkRules contracts.
+- Internal cleanup with no public export or behavior change: about 390 unused internal exports removed (knip) and hand-written copy/paste duplication cut from 1.01% to 0% (jscpd). Maintainers: `npm run check:knip` and `npm run check:duplication` run in the CI build job.
 - Compact `--doctor` names ArkRules only when the `arkRules` map is on
   (one breath + counts, not a score). Absence stays silent. Reuses
   `rulesUnderContract` — no new schema, flag, or skill. `--doctor --all`
@@ -66,6 +141,16 @@ in the immutable pre-2.0 archive linked below.
   Required CI is still the shared merge line. No new skill, schema, or host.
 
 ### Fixed
+- `writes-via-aggregate` flags tagged-template SQL writes (`UPDATE`, `MERGE`, `TRUNCATE`, including `ONLY`, quoted names, and interpolated tables). Comments, `FOR UPDATE`, and `DO UPDATE SET` stay silent (#344, #343).
+- `--policy-base` and MCP policy-delta now judge an advisory → enforced
+  invariant promotion with the declared `coverage.coverageRoots`, the same way
+  `--promote` does. Before, a covered promotion with roots declared came out
+  `judgment-required` ("Declare coverage.coverageRoots…") while `--promote`
+  allowed it.
+- The flat-parent suggestion in status reads the resolved importer index
+  instead of re-reading every file for import text.
+- Doctor sees CI jobs gated by `needs:`: a job that runs the fail-closed Ark check behind unconditional jobs (such as a CI-profile job) now counts as a merge gate; `ciMergeBoundary.ci.workflowPresent` / `merge-gate` no longer report it absent. Jobs a profile output can skip, jobs with `continue-on-error`, and chains with a conditional job still do not count.
+- With `ARK_DOCTOR_GITHUB=1`, the Ark check counts as required only when every job that can skip it is required too (a skipped job satisfies branch protection); otherwise the doctor reports `unverified`, `arkCheckUpstreamNotRequired`, and the gap `enforcement-ark-check-upstream-not-required`. Required checks bound to the GitHub Actions app now correlate (`arkCheckSourceBound: true`).
 - Write hook and `ark-check` now agree on overlapping layer globs: the hook
   probes the same specifier extensions as `ark-check` and classifies with
   `layerForRelativePath` (explicit `money.ts` beats `src/lib/**`). Field
@@ -96,6 +181,74 @@ in the immutable pre-2.0 archive linked below.
   Existing configs keep whatever URL they already have. Editor completion
   matches the 4.x line you just installed.
 
+## 4.8.24 — 2026-09-29
+
+**Patch** over **4.8.23**. Follow-ups to the hierarchical slices shipped in 4.8.23
+(issues #335–#338), every defect a full audit of the gate and its add-ons
+confirmed, and much lower memory per validation (#339). **Write. Check. Ship.**
+**No required config migration:** a config that loads in 4.8.23 still loads;
+ids that changed meaning warn (`CONFIG_CHILD_SLICES_INERT`,
+`CONFIG_SLICE_LEGACY_STARS_ID`) and keep their 4.8.23 verdict for one release.
+No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Minimum version 4.8.24 for the new config fields** (`sharedImportsSlice`
+object form with `stopAt`, `childSlices.message`, `childSlices.siblings.ratchet`).
+arkgate 4.8.23 and older reject them at config load. Pin 4.8.24 in the write
+hook and CI first.
+
+**Status: released** (tag `v4.8.24`). This file does not assert registry
+state; run `npm view arkgate@4.8.24 version` to confirm (#314).
+
+### Added
+- `sharedImportsSlice` accepts `{ "mode": "deny-cross-parent", "stopAt": [...] }`. The whole-graph `CROSS_PARENT_VIA_SHARED` walk never starts at or passes through a stop file, so a declared composition root (`kernel/bootstrap.ts`, `kernel/registrations/**`) is no longer reported as a crossing. `stopAt` matches like a shared root or an alias glob; a stop that covers the whole tree or a whole layer root is rejected. Findings carry `via`, and doctor `sharedWalkHubs` names a likely undeclared composition root. Adding stops is a weakening policy delta. The string forms are unchanged. arkgate 4.8.23 and older reject the object (issue [#335](https://github.com/pedroknigge/arkgate/issues/335)).
+- Optional `childSlices.message` sets the text for inner-wall findings (`CROSS_SIBLING_SLICE`, universe common code importing a child). Without it ArkGate uses its own text; the rule `message` stays the universe-wall text and is never reused on inner-wall findings. Same text in ark-check, CI, the write hook, MCP, and ESLint (issue [#337](https://github.com/pedroknigge/arkgate/issues/337)).
+- Optional `childSlices.siblings.ratchet`: `true` always fails a new advisory crossing, `false` only measures (issue [#336](https://github.com/pedroknigge/arkgate/issues/336)).
+- `arkgate mcp` / `ark mcp` start the stdio MCP server (same as `arkgate-mcp`).
+- ESLint: warn-level `ark/architecture-advisory` rule (findings ark-check reports as warnings) and `ark/arkrules-structure` (ArkRules structure sensors on the same Effective Contract).
+- New advisory `ARKRULE_FILE_UNREFERENCED` for an `arkrules/*.json` the config does not reference, and `doctor.rulesMigration`.
+- `ark-dashboard --help`, `--version`, `--once`, `ARK_DASHBOARD_URL`.
+- `npm run bench:memory` regression guard (budgets in `eval/performance/memory-budgets.v1.json`).
+
+### Changed
+- **Memory and speed.** ark-check, `--doctor`, the write hook, ApplyPatch preflight, the MCP server and the ESLint plugin use much less memory; verdicts are byte-identical. On a 20k-file repo: ark-check peak 422 → 303 MB (3.7 → 2.3 s), ApplyPatch hook 649 → 414 MB (9.5 → 3.6 s), Write hook 163 → 146 MB (0.68 → 0.24 s), MCP server after 50 calls 725 → 442 MB. Sources are read one at a time and released, the facts hash streams, module resolution is memoized per run, the Write/Edit hook no longer walks the whole `include` tree for tsconfig aliases, and preflight reuses base parses.
+- Advisory sibling crossings are advisory on day 1. The anti-growth ratchet is judged per rule and turns on only when the baseline in use already records an advisory sibling crossing of that rule (issue [#336](https://github.com/pedroknigge/arkgate/issues/336)).
+- `CONFIG_CHILD_SLICES_VERSION` (and the other new-key version warnings) fire only with evidence that the repo pins an older arkgate (exact `package.json` dependency, installed copy, lockfile, hook script, or CI workflow). The finding points at that file and line and names the version to bump to (issue [#338](https://github.com/pedroknigge/arkgate/issues/338)).
+- `childSlices` on a rule without `peerIsolation: true` and `allowed: false` still loads (as in 4.8.23) but is inert; ark-check now warns `CONFIG_CHILD_SLICES_INERT` and says how to fix it (add both flags to the rule, or remove `childSlices`). No config that loads in 4.8.23 fails to load.
+- `sliceIdentity: "stars"` keeps every star binding (`modules/*/api/*` binds `orders/api/v1`, not `api/v1`). **Migration:** a `sliceAliases` `to` or an `allowedCrossSlice` / `childSlices.allowedCrossSlice` entry written against the 4.8.23 id (`api/v1/x`, `api/v1`) keeps loading and keeps its 4.8.23 verdict for this release: the alias joins the universe whose old id it names, and the allowance still clears the edge it cleared. ark-check warns `CONFIG_SLICE_LEGACY_STARS_ID` and names the new id to write (`orders/api/v1/x`). A legacy alias target is rejected at config load only when it maps to more than one universe shape of the rule. The legacy form is removed in the next minor release.
+- `childSlices.commonFolders` counts only a folder directly under the universe; the same name inside a child belongs to that child.
+- The write hook fails closed: if it cannot run inside an Ark project (invalid config, missing ArkRules file, missing `dist/`), governed writes are denied with exit 2 (`WRITE_GATE_UNAVAILABLE`) instead of exit 1, which hosts let through. The hook finds its project root like ark-check: a set `--root-env` variable, else the root that holds `ark.config.json`, else it walks up from the payload (written file, `cwd`, `workspace_roots`) to the nearest `ark.config.json`. A write outside any Ark project (no `ark.config.json` found) is allowed, as in 4.8.23.
+- `ark start --apply --remove-host <host>` removes only the Ark hook entries from a merged `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json` or `.agents/hooks.json` (same identity as the merge) and keeps every user key and hook; the file is deleted only when nothing else remains. "customized" is reported only when the Ark entry itself was edited.
+- An enforced invariant with `coverage: { test: false }` and no `coverage.symbol` is uncovered; `coverage.symbol: "Class.member"` needs the member declared in that class.
+- ArkOrder `apply()` only accepts a proposal bound to the current Release (`ARKORDER_STALE_PROPOSAL`); `restore()` never changes ξ or rolls the version back; `ReleaseStore.load()` is validated; the plane advances only after `save()`; `informationBudget` is enforced when a Release is created.
+- ArkRun: the default event buffer is capped and settles after local delivery; broker handoff failures are recorded (`event.handoffFailed`); config kernels with canonical layer names enforce hard observed-layer-flow.
+- `ark-check --update-baseline` always freezes the whole tree and refuses `--changed` / `--local`.
+
+### Fixed
+- `--changed`, `--local`, `--against` and `--persona` no longer give a false green: paths resolve relative to `--root` (monorepo packages), non-ASCII names are kept, large or failed git listings exit 2, and a missing base ref exits 2 (`changed-needs-base`) instead of "nothing changed".
+- `--changed` catches a new `CROSS_PARENT_VIA_SHARED` created by editing only a shared-root file, and no longer warns `CONFIG_LAYER_PATTERN_NO_MATCHES` for untouched layers.
+- `ark-check --report`, `latest.json`, `--doctor` and `ark status` agree on frozen versus active findings.
+- Write path parity with CI: the hook, `validate_code`, `ark_prepare_write`, `ark_prepare_change` and ApplyPatch preflight enforce ArkRules structure sensors and ArkOrder editor sensors, load ArkRules like ark-check, handle realpath aliases, and accept the full Codex `apply_patch` format.
+- MCP: `validate_code` / `ark_check` output schemas pass MCP SDK validation (tools no longer disappear); a stale contract returns `CONTRACT_STALE`; `ark_status` honors `--config`; `arkgate-mcp --help` / `--version` exit.
+- MCP Registry: `server.json` runs `npx arkgate@<version> mcp --root .`; the old descriptor never started the server.
+- CommonJS TypeScript consumers: `.d.cts` declarations ship and are mapped for every entry.
+- ESLint: warnings in ark-check are warnings in ESLint; messages carry the rule message and slice reason; ArkOrder rules show real text at 1-based columns; tsconfig JSONC / nearest tsconfig / `extends` are read correctly; an invalid config reports one diagnostic instead of crashing; `require('arkgate/eslint')` returns the plugin (it also carries a non-enumerable `__esModule`, so Babel `_interopRequireWildcard` and TypeScript `__importStar` still see every named export); `--cache` invalidates on contract change; forbidden-globals catches destructuring and bracket access.
+- Slices: adapter diagnostics carry `reasonId` and the universe pair; `CROSS_PARENT_VIA_SHARED` honors the universe `allowedCrossSlice`; fail-closed reasons are named in the hook and MCP; folder-form `sliceAliases` cover their subtree; the flat-parent move card counts every resolved importer; `SHARED_IMPORTS_SLICE` is catalogued.
+- Setup: `ark start --archetype/--preset` writes that shape; re-running `ark start --apply` works; `--remove-host` does not touch packages; existing `.claude/settings.json` / `.codex/hooks.json` are merged instead of skipped or wiped; `typecheck` is added only when TypeScript is present; the steward lock holds under `--strict-merge --contract-session`; `ark status --config` / `ark agents-md --config` work; starter ArkRules ids are unique.
+- ArkRules: policy delta reads base ArkRules from the base ref (demoting an enforced rule is weakening); class-shape sensors see generic classes, ignore braces in strings and regexes, and skip a `static { … }` initialization block (it is not a public member); `ArkRulesValidationError` is exported from the root.
+- ArkRun: undeclared emit/handle/depend count only kernel-traced receivers (`res.send`, `require.resolve`, rxjs `subscribe` are ignored); typed `send(Creator)` resolves names; `ArkModule.forRoot()` is a composition root; `arkgate/runtime` and `arkgate/nestjs` share one kernel chunk (`instanceof` works). A namespace import of a composition root (`import * as main from '../main'; main.ark.publisher(..)`) is traced as a kernel receiver, and an untraced receiver counts when its name carries one of the project's effective intent prefixes (configured `layers[].intentPrefixes` plus the canonical ones), not only `Domain.`/`Application.`….
+- ArkOrder: `ARKORDER_XI_FIELD_WRITE` recognizes Prisma/ORM clients by construction, `GENERIC_UPDATE` / `INGEST_WRITES_XI` false positives removed, `xi-ttl` and `information-budget` sensors emit, NaN/Infinity rejected, documented types exported, and the shipped `bin/lib/ark-order-invariants.mjs` loads.
+- Docs: the composite Action pin tracks the current release, and configuration.md names the real policy-delta entry points.
+- Generated CI workflows, host hooks and MCP entries in a project that does not
+  have arkgate as a local dependency run `npx -y -p arkgate@<exact version> <bin>`
+  instead of a bare `npx ark-check` / `npx arkgate-mcp` (npm resolved those as a
+  nonexistent package, or ran a stale global). Without a `package.json` the workflow
+  skips the install step and the npm cache. `--migrate-commands` rewrites bare runners
+  into the pinned form, and `--doctor` leads with `PACKAGE_PIN_ABSENT` when a generated
+  file still uses the local runner without the pin.
+- `ark-check --json` answers every fatal error with a JSON envelope (`POLICY_BASE_UNREADABLE` when a CI base ref such as `GITHUB_BASE_REF` cannot be read in the checkout, otherwise `CHECK_ERROR`), not only `CONFIG_INVALID`; exit code stays 2.
+- Security: CodeQL `js/polynomial-redos` in the steward email check and two incomplete-sanitization alerts are closed.
+
 ## 4.8.23 — 2026-09-28
 
 **Patch** over **4.8.22**. Hierarchical slices: the issue #326 series

package/README.md

@@ -25,11 +25,11 @@ Design the boundary before you implement. Put a small interface in front of the
 
 ## Try it
 
-One command. Preview only — no files change. Current release is **4.8.23**
+One command. Preview only — no files change. Current release is **4.8.25**
 (check npm `latest` with `npm view arkgate version`):
 
 ```bash
-npx arkgate@4.8.23 start
+npx arkgate@4.8.25 start
 ```
 
 ## What a red result looks like
@@ -320,9 +320,11 @@ queue monitors:
 
 Poll those facts from the dual bins **`ark-dashboard`** / **`arkgate-dashboard`**
 (`bin/ark-dashboard.mjs`). ANSI + polling only (no React/Ink/Blessed). Point
-`--url` / `-u` at the inspector snapshot (default
-`http://127.0.0.1:3000/snapshot`); the dashboard also fetches sibling `/outbox`
-and `/workflows`. `--interval` / `-i` is clamped to 200–60000 ms (default 2000).
+`--url` / `-u` at the inspector (`handle.url` or `handle.snapshotUrl`); the dashboard
+also fetches sibling `/outbox` and `/workflows`. `startInspector()` binds a random port
+unless you pass `{ port }`, so the fallback `http://127.0.0.1:3000/snapshot` (or
+`ARK_DASHBOARD_URL`) only matches `startInspector({ port: 3000 })`. `--interval` / `-i`
+is clamped to 200–60000 ms (default 2000); `--once`, `--help`, `--version` are supported.
 Also available as `ark dashboard` / `arkgate dashboard` (passthrough to the same bin). Kernel stays
 JSON-only; presentation stays in `bin/`.
 

package/bin/ark-check-runtime.mjs

@@ -77,6 +77,7 @@ import {
   printViolationBreakdown,
   printHumanWarnings,
   CONCENTRATION_MIN_VIOLATIONS,
+  color,
 } from './lib/violations.mjs';
 import {
   detectBestFitModel,
@@ -106,7 +107,7 @@ import {
   normalize,
   walk,
 } from './lib/scan-files.mjs';
-import { configWarning } from './lib/config-warnings.mjs';
+import { configInvalidJsonEnvelope, configWarning } from './lib/config-warnings.mjs';
 import { runArchitectureScan } from './lib/architecture-scan.mjs';
 import {
   ANALYSIS_COMPLETENESS,
@@ -124,6 +125,7 @@ import {
   applyAgainstRatchet,
   bindTeamBaseRefs,
   contractSessionFrom,
+  pruneScopedPatternWarnings,
   runTeamPreflight,
   ungovernedDumpMessage,
 } from './lib/team-parliament-io.mjs';
@@ -135,7 +137,9 @@ import {
   resolveEffectiveProjectRoot,
 } from './lib/project-root.mjs';
 import { demoteArkRuleTeethUnderClassificationFloor } from './lib/rules-under-contract.mjs';
-import { localCheckEnvelope, parseArgs, resolveDesignDeltaBaseRef } from './lib/check-args.mjs';
+import {
+  effectiveBaselineName, localCheckEnvelope, parseArgs, resolveDesignDeltaBaseRef, UPDATE_BASELINE_SCOPE_MESSAGE,
+} from './lib/check-args.mjs';
 import { detectConfig, proposeForUncovered } from './lib/check-config-detect.mjs';
 import { runWatchMode } from './lib/check-watch.mjs';
 
@@ -1030,15 +1034,6 @@ function readManifest(root, manifestPath) {
   return readJson(fullPath);
 }
 
-const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
-const color = {
-  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
-  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
-  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
-  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
-  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
-};
-
 /**
  * Monorepo honesty: when cwd/--root has no ark.config.json, walk parents (bounded).
  * Stamps configRoot / configWalkedUp. Mutates args.root only for read paths, or
@@ -1144,6 +1139,14 @@ async function main() {
     return;
   }
 
+  if (args.probeInvariants) {
+    // ADR 0039: owner-invoked, outside the gate path. Loaded only here; parseArgs
+    // refuses every pairing with --strict-merge, --changed, --local or --doctor.
+    const { runProbeInvariants } = await import('./lib/invariant-probe-cli.mjs');
+    await runProbeInvariants(args, readConfig);
+    return;
+  }
+
   if (args.sensors) {
     const { runSensors } = await import('./lib/sensor-promote-cli.mjs');
     await withSensorsPartialModeHonesty(args, () => runSensors(args, readConfig));
@@ -1333,6 +1336,7 @@ async function main() {
     strictMerge: args.strictMerge || args.contractDiff,
     basePath: args.policyBase,
     baseRef: args.policyBaseRef,
+    adoptMissingBase: args.policyBaseFromTeam === true,
     acknowledgementPath: args.policyAck,
   });
   const preflight = runTeamPreflight({
@@ -1433,7 +1437,7 @@ async function main() {
 
   const {
     violations: rawViolations, warnings, safety, parseHealth, completeness, completenessReasons,
-    mode, policyHash, resolverIdentity, factsHash, candidateTreeHash,
+    mode, policyHash, resolverIdentity, factsHash, candidateTreeHash, importGraph,
   } = runArchitectureScan({
     root,
     config,
@@ -1445,8 +1449,11 @@ async function main() {
     files: args.changed ? files : [],
     ts,
     args,
+    // ADR 0037: doctor / report read a compact importer index, never the verdict path.
+    graphProjection: Boolean(args.doctor || args.report) && !args.changed,
   });
 
+  if (args.changed) pruneScopedPatternWarnings(warnings, root, loadGovernedFiles);
   // Align merge with extraMergeTeeth stamp: demote enforced ArkRules under classification floor.
   const preCov = computeCoverage(root, config, files, rules);
   const populatedLayerCount = Array.isArray(preCov.layers)
@@ -1503,8 +1510,8 @@ async function main() {
       configWalkedUp: args.configWalkedUp === true,
       safety, designDelta,
       ts, parseHealth, completeness,
-      all: args.all === true, requireGates: args.requireGates === true,
-      warnings,
+      all: args.all === true, changed: args.changed === true, requireGates: args.requireGates === true,
+      warnings, architectureFacts: importGraph ? { importGraph } : undefined,
     });
     if (designDelta) process.exitCode = !designDelta.complete ? 2 : designDelta.valid ? 0 : 1; return;
   }
@@ -1515,6 +1522,8 @@ async function main() {
   }
 
   if (args.updateBaseline) {
+    // A persona can turn on --changed after parseArgs; a subset scan must never rewrite the baseline.
+    if (args.changed) { console.error(UPDATE_BASELINE_SCOPE_MESSAGE); process.exitCode = 2; return; }
     if (!contractSessionFrom(args)) {
       console.error('Growing the baseline requires --contract-session. Freeze in a law-only PR.');
       process.exitCode = 1;
@@ -1587,14 +1596,16 @@ async function main() {
       changed: args.changed,
       changedPaths,
       occurrenceKeys: baselineOccurrenceKeys(violations),
+      rules,
+      layers: config.layers,
     });
     activeViolations = ratcheted.activeViolations;
     suppressed = ratcheted.suppressed;
-  } else if (args.baseline) {
-    const baseline = readBaseline(root, args.baseline);
+  } else if (effectiveBaselineName(args, root)) {
+    const baseline = readBaseline(root, effectiveBaselineName(args, root));
     if (baseline.exists) {
       const occurrenceKeys = baselineOccurrenceKeys(violations);
-      const judged = applyAdvisorySiblingRatchet(violations, occurrenceKeys, baseline.keys);
+      const judged = applyAdvisorySiblingRatchet(violations, occurrenceKeys, baseline.keys, { rules, layers: config.layers });
       suppressed = judged.filter((_, index) => baseline.keys.has(occurrenceKeys[index]));
       activeViolations = judged.filter((_, index) => !baseline.keys.has(occurrenceKeys[index]));
       const currentKeys = new Set(occurrenceKeys);
@@ -1639,81 +1650,16 @@ async function main() {
   }
 
   if (args.rulesInventory) {
-    const { buildRulesInventory, inventoryToExtractionCard } = await import('./lib/rules-inventory.mjs');
-    const fileContents = {};
-    const fileLayers = {};
-    for (const file of files.slice(0, 400)) {
-      const rel = normalize(path.relative(root, file));
-      try {
-        fileContents[rel] = fs.readFileSync(file, 'utf8');
-        const layer = layerForFile(root, file, config.layers);
-        if (layer) fileLayers[rel] = layer;
-      } catch {
-        /* skip unreadable */
-      }
-    }
-    const contracted = [];
-    if (config.arkRules) {
-      try {
-        const { loadEffectiveArkRulesFromDisk } = await import('./lib/effective-contract-load.mjs');
-        const loaded = loadEffectiveArkRulesFromDisk(root, config);
-        for (const rule of loaded.arkRules.structure ?? []) contracted.push(rule.id);
-        for (const inv of loaded.arkRules.invariants ?? []) contracted.push(inv.id);
-      } catch {
-        /* advisory inventory still useful */
-      }
-    }
-    const inventory = buildRulesInventory({
-      fileContents,
-      fileLayers,
-      layerContexts: (config.layers ?? []).map((layer) => ({
-        name: layer.name,
-        intentPrefixes: layer.intentPrefixes ?? [],
-      })),
-      contractedRuleIds: contracted,
-    });
-    const nextPilot =
-      inventory.candidates[0] != null
-        ? inventoryToExtractionCard(inventory.candidates[0])
-        : null;
-    let evidenceLines = [];
-    let coverageEvidence = null;
-    if (config.arkRules && Object.keys(config.arkRules).length > 0) {
-      try {
-        const { summarizeRulesUnderContract, formatArkRulesEvidenceLines } = await import(
-          './lib/rules-under-contract.mjs'
-        );
-        const section = summarizeRulesUnderContract(root, config, {
-          files: files.map((file) => ({ path: normalize(path.relative(root, file)) })),
-        });
-        evidenceLines = formatArkRulesEvidenceLines(section);
-        if (section.active === true) {
-          coverageEvidence = {
-            symbolEvidence: section.symbolEvidence ?? [],
-            discarded: section.coverageStats?.discarded ?? null,
-          };
-        }
-      } catch {
-        /* inventory still useful when coverage cannot be read */
-      }
-    }
-    const payload = {
-      rulesInventory: inventory,
-      rulesMigration: {
-        inventoried: inventory.inventoried,
-        underContract: inventory.underContract,
-        frozen: inventory.frozen,
-        notAScore: true,
-      },
-      nextPilot: nextPilot,
-      ...(coverageEvidence ? { coverageEvidence } : {}),
-    };
+    // Same helper as MCP ark_rules_inventory and doctor.rulesMigration (AR15).
+    const { buildRulesInventoryPayload, formatRulesMigrationCounts } = await import(
+      './lib/rules-under-contract.mjs'
+    );
+    const { payload, evidenceLines } = buildRulesInventoryPayload(root, config, files);
+    const { rulesInventory: inventory, nextPilot } = payload;
     if (args.json) {
       console.log(JSON.stringify(payload, null, 2));
     } else {
-      console.log(
-        `Rules inventory: ${inventory.inventoried} inventoried, ${inventory.underContract} under contract, ${inventory.frozen} frozen (not a score).`
-      );
+      console.log(`Rules inventory: ${formatRulesMigrationCounts(payload.rulesMigration)}.`);
       for (const c of inventory.candidates.slice(0, 12)) {
         console.log(`  - [${c.confidence}] ${c.kind} @ ${c.file}:${c.line} — ${c.message}`);
       }
@@ -1846,8 +1792,9 @@ async function main() {
           files,
           ts,
           parseHealth,
-          undefined,
-          activeViolations
+          importGraph ? { importGraph } : undefined,
+          activeViolations,
+          { details: true, changed: args.changed === true }
         ),
         // Doctor parity: always emit improvement compass when doctor would (reportParity).
         ...(designDepth?.improvementCompass
@@ -1865,6 +1812,7 @@ async function main() {
       ? renderBeginnerHtmlReport(reportPayload)
       : renderHtmlReport(reportPayload);
     const reportPath = path.isAbsolute(args.report) ? args.report : path.join(root, args.report);
+    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
     fs.writeFileSync(reportPath, html);
 
     const archive = archiveReportSnapshots(root, {
@@ -2087,6 +2035,8 @@ async function main() {
 }
 
 main().catch((error) => {
+  const envelope = configInvalidJsonEnvelope(error, process.argv);
+  if (envelope) console.log(envelope);
   console.error(
     process.env.ARK_DEBUG_STACK === '1' && error instanceof Error
       ? error.stack

package/bin/ark-dashboard.mjs

@@ -1,43 +1,55 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
+import {
+  DASHBOARD_DEFAULT_INTERVAL_MS,
+  DASHBOARD_DEFAULT_TIMEOUT_MS,
+  DASHBOARD_DEFAULT_URL,
+  DASHBOARD_EPHEMERAL_PORT_HINT,
+  DASHBOARD_HELP,
+  clampDashboardMs,
+  dashboardSiblingUrl,
+} from './lib/dashboard-cli.mjs';
 
-const DEFAULT_INTERVAL_MS = '2000';
-const DEFAULT_SNAPSHOT_URL = 'http://127.0.0.1:3000/snapshot';
-const DEFAULT_FETCH_TIMEOUT_MS = 5_000;
 const MAX_FIELD_LEN = 120;
 
-const args = parseArgs({
-  options: {
-    interval: {
-      type: 'string',
-      short: 'i',
-      default: DEFAULT_INTERVAL_MS
-    },
-    url: {
-      type: 'string',
-      short: 'u',
-      default: DEFAULT_SNAPSHOT_URL
-    },
-    timeout: {
-      type: 'string',
-      short: 't',
-      default: String(DEFAULT_FETCH_TIMEOUT_MS)
-    }
-  },
-  allowPositionals: true
-});
+function parseDashboardArgs() {
+  try {
+    return parseArgs({
+      options: {
+        interval: { type: 'string', short: 'i' },
+        url: { type: 'string', short: 'u' },
+        timeout: { type: 'string', short: 't' },
+        once: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+      },
+      allowPositionals: true,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message.split('. ')[0] : String(err);
+    process.stderr.write(`ark-dashboard: ${message}. Run ark-dashboard --help.\n`);
+    process.exit(2);
+  }
+}
+
+const args = parseDashboardArgs();
+if (args.values.help || args.positionals[0] === 'help') {
+  console.log(DASHBOARD_HELP);
+  process.exit(0);
+}
+if (args.values.version) {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
 
-const parsedInterval = parseInt(args.values.interval, 10);
-const interval =
-  Number.isFinite(parsedInterval) && parsedInterval >= 200 && parsedInterval <= 60_000
-    ? parsedInterval
-    : Number(DEFAULT_INTERVAL_MS);
-const targetUrl = args.values.url || DEFAULT_SNAPSHOT_URL;
-const parsedTimeout = parseInt(args.values.timeout, 10);
-const fetchTimeoutMs =
-  Number.isFinite(parsedTimeout) && parsedTimeout >= 200 && parsedTimeout <= 60_000
-    ? parsedTimeout
-    : DEFAULT_FETCH_TIMEOUT_MS;
+const envUrl = process.env.ARK_DASHBOARD_URL?.trim();
+const urlExplicit = Boolean(args.values.url || envUrl);
+const targetUrl = args.values.url || envUrl || DASHBOARD_DEFAULT_URL;
+const interval = clampDashboardMs(args.values.interval, DASHBOARD_DEFAULT_INTERVAL_MS);
+const fetchTimeoutMs = clampDashboardMs(args.values.timeout, DASHBOARD_DEFAULT_TIMEOUT_MS);
+const once = Boolean(args.values.once);
 
 const RESET = '\x1b[0m';
 const RED = '\x1b[31m';
@@ -73,22 +85,6 @@ function sanitizeField(value, maxLen = MAX_FIELD_LEN) {
   return text;
 }
 
-function siblingUrl(snapshotUrl, suffix) {
-  try {
-    const u = new URL(snapshotUrl);
-    let basePath = u.pathname;
-    if (basePath.endsWith('/snapshot')) {
-      basePath = basePath.slice(0, -'/snapshot'.length);
-    } else if (basePath.endsWith('/snapshot/')) {
-      basePath = basePath.slice(0, -'/snapshot/'.length);
-    }
-    u.pathname = `${basePath}${suffix}`;
-    return u.toString();
-  } catch {
-    return null;
-  }
-}
-
 /**
  * @returns {{ ok: true, data: unknown } | { ok: false, kind: 'waiting' | 'failure', error?: string }}
  */
@@ -340,6 +336,7 @@ function renderHardening(snapshotResult) {
     } else {
       const detail = snapshotResult.error ? ` (${snapshotResult.error})` : '';
       console.log(`${RED}Failure contacting kernel${detail}${RESET}`);
+      if (!urlExplicit) console.log(`${MUTED}${DASHBOARD_EPHEMERAL_PORT_HINT}${RESET}`);
     }
     return;
   }
@@ -381,13 +378,13 @@ function renderHardening(snapshotResult) {
 }
 
 async function render() {
-  process.stdout.write('\x1b[2J\x1b[H');
+  if (!once) process.stdout.write('\x1b[2J\x1b[H');
   console.log(`ArkGate Observability Dashboard`);
   console.log(`Time: ${sanitizeField(new Date().toISOString())}`);
   console.log(`Endpoint: ${sanitizeField(targetUrl)}\n`);
 
-  const outboxUrl = siblingUrl(targetUrl, '/outbox');
-  const workflowsUrl = siblingUrl(targetUrl, '/workflows');
+  const outboxUrl = dashboardSiblingUrl(targetUrl, '/outbox');
+  const workflowsUrl = dashboardSiblingUrl(targetUrl, '/workflows');
   const [snapshotResult, outboxResult, workflowsResult] = await Promise.all([
     fetchJsonResult(targetUrl),
     fetchJsonResult(outboxUrl),
@@ -404,9 +401,15 @@ async function render() {
     snapshot?.outbox,
     snapshot?.workflows,
   );
+  return snapshotResult.ok;
 }
 
 async function startDashboard() {
+  if (once) {
+    const ok = await render();
+    process.exitCode = ok ? 0 : 1;
+    return;
+  }
   console.log(
     `Starting ArkGate Observability Dashboard (polling every ${interval}ms, fetch timeout ${fetchTimeoutMs}ms)`,
   );