arkgate 4.6.6 → 4.7.0

package/CHANGELOG.md

@@ -5,12 +5,149 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.7.0 — 2026-08-25
+
+**Minor** over **4.6.7**. Ships **ArkRun**: an opt-in extra on schema `1.2` for kernel
+usage and complete declarations, plus companion `@arkgate/runtime` DX. Absence is
+silent (Layers / ArkRules verdicts unchanged). In-memory stores remain
+reference-only. **No required config migration.** Does not close Z09 / K01.
+
+**Status: prepared** (see `docs/releases/4.7.0.md`). npm `latest` remains **4.6.7**
+until publish.
+
+### Added
+
+- **`arkRun` extra on `ark.config.json` schema `1.2` (RN02):** optional inline
+  `{ mode, compositionRoots, managedLayers, requireDeclarations }`. `1.1` and
+  earlier configs migrate in memory; absence is silent (Layers / ArkRules
+  verdicts unchanged). Unknown keys, unknown `managedLayers` names, and empty
+  `compositionRoots` in `enforced` mode fail closed (`ARKRUN_MISSING_ROOT`).
+  Advisory → enforced is a strengthening policy delta; demotion or deletion is
+  weakening and needs the existing hash-bound ack. ESLint envelope is RN06
+  (landed below); CI extra teeth landed in RN07. Does not close Z09 / K01.
+
+- **ArkRun resolver facts on resolved-candidate-facts schema `1.2` (RN03):**
+  additive optional `arkRunKernelCalls`, `arkRunManagedNews`, and
+  `arkRunCompositionRootHits`. `1.0`/`1.1` payloads stay loadable (empty
+  arrays). Syntax evidence only — sensors consume these in RN04. Absence of
+  `arkRun` still leaves Layers / ArkRules verdicts unchanged. Does not close
+  Z09 / K01.
+
+- **ArkRun tier-1 sensors (RN04):** when `arkRun` is present, closed sensors
+  emit `ARKRUN_MISSING_ROOT`, `ARKRUN_KERNEL_IN_DOMAIN`, `ARKRUN_DIRECT_NEW`,
+  `ARKRUN_UNDECLARED_EMIT`, `ARKRUN_UNDECLARED_HANDLE`, `ARKRUN_UNDECLARED_DEPEND`,
+  and `ARKRUN_TRANSPORT_BYPASS`. Advisory findings never flip `valid`; enforced
+  blocks. Absence of the extra is still silent on Layers / ArkRules verdicts.
+  Optional `arkRunDeclarations` facts stay additive on schema `1.2`. Dual-depth
+  catalog nextAction is RN05 (landed below). Does not close Z09 / K01.
+
+- **ArkRun diagnostic catalog dual-depth (RN05):** closed `ARKRUN_*` catalog
+  entries have dual-depth remediation: casual `enthusiastHint` plus engineer
+  `nextAction` (target interpolates the call-site literal or specifier). Adding
+  an existing declaration-list string is `mechanical-safe` (`arkrun-declaration-list`)
+  only when that literal is already present; other ArkRun findings stay
+  `judgment`. Sensors, adapter fallback, and CLI remediation share
+  `deterministicNextAction`. Does not close Z09 / K01.
+
+- **ArkRun ESLint envelope (RN06):** `arkgate/eslint` recommended config adds
+  `ark/no-arkrun-kernel-in-domain`, `ark/no-arkrun-direct-new`, and
+  `ark/no-arkrun-transport-bypass`. Same `ARKRUN_*` sensors as ark-check for
+  the import / `new` envelope; silent when `arkRun` is absent. Missing-root and
+  undeclared-* stay CLI/MCP/preflight. Does not close Z09 / K01.
+
+- **ArkRun extra-teeth parity (RN07):** CLI `--strict-merge`, MCP `ark_check` /
+  snippet write, PreToolUse hook, atomic preflight, and CI share one ArkRun
+  verdict. Enforced extra teeth arm only when the layer plane is classified
+  (same ≥50% governed / ≥1 populated-layer floor as ArkRules); advisory and
+  absence stay silent on `valid`. Doctor/status `arkRun` section landed in
+  RN08 below. Does not close Z09 / K01.
+
+- **ArkRun doctor / status / report (RN08):** `ark-check --doctor`, HTML
+  `--report`, and `ark status` / MCP `ark_status` expose an `arkRun` section
+  that is always `notAScore`. Residual is a finding-id count, never a score or
+  LLM verdict. `mergePlanes.arkRun` states whether the extra can fail merge;
+  advisory and absence never arm extra teeth. Report parity requires
+  `data-advisory="arkRun"`. Does not close Z09 / K01.
+
+- **ArkRun companion branding (RN09):** `@arkgate/runtime` README and public
+  docs brand the kernel **ArkRun**. `createStrictArkKernel` stays the factory
+  (per-instance; no process-wide singleton). Kernel implementation stays out of
+  the `arkgate` tarball. Branding is not a production-durability claim. Does not
+  close Z09 / K01.
+
+- **ArkRun interaction declarations (RN10):** `@arkgate/runtime` `register()`
+  accepts `uses` / `reactsTo` / `raises` / `sends` plus optional tooling-only
+  `extendedInfo`. `getDependencyInformationPackage()` returns a JSON-serializable
+  snapshot of ids, lifetime, and declarations — never factories, live instances,
+  or input DTOs. Companion registrations may omit declarations for local
+  experiments; enforced `arkRun` on the gate still requires them. Does not close
+  Z09 / K01.
+
+- **ArkRun transport ports (RN11):** `@arkgate/runtime` `send()` is one call site
+  for `local` / `localBlocking` / `broker`. `ephemeral` defaults true (await local
+  recording or adapter accept — not a durability claim). Missing broker adapter
+  falls back to in-process local delivery, not cloud portability. No cloud SDKs
+  ship in the package. Does not close Z09 / K01.
+
+- **ArkRun dev inspector (RN12):** `@arkgate/runtime` `startInspector()` /
+  `startArkRunInspector()` is opt-in. Default bind is `127.0.0.1`; `NODE_ENV=production`
+  vetoes start; public hosts (`0.0.0.0`, `::`) are rejected. HTTP is lazy-loaded.
+  `GET /snapshot` and `GET /events` (SSE) serve the information package plus
+  transport facts (no factories, no shipped cloud SDKs). Does not close Z09 / K01.
+
+- **ArkRun graph slices (RN13):** `@arkgate/runtime` `requestGraph()` slices the
+  information package into `process` (raises / reactsTo / sends) or `technical`
+  (`uses`) graphs. Optional `nodeIds`, `degreesOfSeparation`, and include/exclude
+  query keep a neighborhood. `formatArkRunGraphMermaid()` / `graph.mermaid` is a
+  helper string, never a score. Inspector `GET /graph` serves the same slice.
+  Does not close Z09 / K01.
+
+- **ArkRun skip corpus (RN14):** `tests/fixtures/arkrun-skip-corpus/` is the
+  executable proof: Application `new`, same-layer peer import, and homemade
+  `EventEmitter` stay green when `arkRun` is absent (Layers / ArkRules match
+  schema `1.1`) and fail write path, CLI, MCP, and `--strict-merge` when the
+  extra is enforced. Does not close Z09 / K01.
+
+- **ArkRun skill-body deepen (RN15):** `/ark-runtime`, `/ark-place`, and
+  `/ark-adopt` teach the extra vs companion (advisory adopt, kernel-only
+  scaffold, composition-root wiring). Frozen **13** names — no `/ark-run`.
+  Skills never enforce; doctor `arkRun` stays `notAScore`. Agent Skills layout
+  stays 1:1 with `templates/skills`. Does not close Z09 / K01.
+
+## 4.6.7 — 2026-08-24
+
+**Patch** over **4.6.6**. Production-hardening: CODEOWNERS, eval/pack honesty, CLI extracts,
+spawn timeouts, and HTML list cap. **No required config migration.** Does not close Z09.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.6.7.md`).
+
+### Changed
+
+- **CODEOWNERS:** `/src/`, `/bin/`, and `/schemas/` owned by `@pedroknigge`. GitHub still
+  needs `require_code_owner_reviews` (or an approving-review count) for that file to
+  enforce; the in-tree list is the product control.
+
+- **Eval comparative fixture:** `saas-dashboard/without-ark` is a real Presentation→Domain
+  **value** import. Type-only was non-blocking and made the nightly oracle go false-green.
+
+- **npm pack JSON:** `scripts/npm-pack-report.mjs` strips ANSI and parses JSON lines that
+  actually have `filename`. Empty `[]` / `{}` stay empty; missing filename still throws.
+
+- **CLI extracts:** hook payload, package-manager helpers, and check args/config/watch live
+  in `bin/lib/`. Module-budget maxima were not raised.
+
+- **git/gh timeouts:** `SPAWN_TIMEOUT_MS = 8000` on git/gh `spawnSync`. Timeout is
+  fail-closed (`status !== 0`).
+
+- **HTML violation cap:** beginner and full showcase lists share a cap of 12 plus
+  `+N more (T total)`. KPI tiles still use the full array.
+
 ## 4.6.6 — 2026-08-22
 
 **Patch** over **4.6.5**. Phase AL corrective honesty plus a slimmer public docs surface.
 **No required config migration.** Does not close Z09. AL05 stays parked.
 
-**Status: current** (shipping as `arkgate@4.6.6`; see `docs/releases/4.6.6.md`).
+**Status: published** (see `docs/releases/4.6.6.md`).
 
 ### Changed
 
@@ -49,7 +186,7 @@ in the immutable pre-2.0 archive linked below.
 **Patch** over **4.6.4**. Adoption, placement, doctor, upgrade, and write-path honesty for
 existing Next.js trees and multi-host teams. **No required config migration.**
 
-**Status: published** (on npm `latest` until 4.6.6 lands; see `docs/releases/4.6.5.md`).
+**Status: published** (see `docs/releases/4.6.5.md`).
 
 ### Changed
 

package/README.md

@@ -16,11 +16,11 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.6** is current (this train). **4.6.5** remains npm `latest` until publish.
+> **ArkGate 4.7.0** is prepared on this tree. **4.6.7** remains npm `latest` until publish.
 > A tree is **adopted** only with a required GitHub status running `arkgate-check --strict-merge`,
 > or `.ark/adoption-stance.json` `stance: "advisory-only"`. Doctor is compact (`--doctor --all`
-> for Details). [4.6.6 notes](docs/releases/4.6.6.md) · [4.6.5](docs/releases/4.6.5.md) ·
-> [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> for Details). [4.7.0 notes](docs/releases/4.7.0.md) · [4.6.7](docs/releases/4.6.7.md) ·
+> [4.6.6](docs/releases/4.6.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -78,11 +78,12 @@ A machine-readable architecture file (`ark.config.json`) plus enforcement:
 |-------|----------------|--------|
 | **Layers** (always) | Who may import whom — imports, placement, purity, isolation | `ark.config.json` layers + rules |
 | **ArkRules** (opt-in; structure rules inside a layer) | Habits *inside* a layer — structure sensors + domain invariants as data | `arkRules` → `arkrules/<Layer>.json` |
+| **ArkRun** (opt-in extra) | Kernel usage + complete declarations | `arkRun` on schema `1.2` |
 
-Absence of ArkRules changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
-Details: [configuration](docs/configuration.md#arkrules-intra-layer-opt-in) · [use path](docs/use.md).
+Absence of ArkRules or ArkRun changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
+Details: [configuration](docs/configuration.md) · [use path](docs/use.md).
 
-**Not** a web framework, ORM, or job runner. Optional experimental runtime is separate and not required for the gate.
+**Not** a web framework, ORM, or job runner. Optional **ArkRun** extra and companion kernel (`@arkgate/runtime`) are separate and not required for the gate. In-memory stores are not production durability.
 
 **Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.
 
@@ -192,9 +193,18 @@ More: [docs/develop.md](docs/develop.md) · skills install: [docs/agent-guide.md
 
 ---
 
-## Optional experimental runtime
+## Optional ArkRun kernel
 
-Gates need **no** app runtime. The experimental `@arkgate/runtime` companion is separate and is not a production-readiness claim.
+Gates need **no** app runtime. The experimental **ArkRun** companion (`@arkgate/runtime`) is separate
+and is not a production-readiness claim. `createStrictArkKernel` is the factory: each call creates
+an isolated instance (no process-wide singleton). Managed components declare `uses` / `reactsTo` /
+`raises` / `sends`; `getDependencyInformationPackage()` is a JSON snapshot and never leaks factories.
+`requestGraph()` slices that snapshot into process or technical graphs (`nodeIds`,
+`degreesOfSeparation`, include/exclude query) with a Mermaid helper. `send()` is local /
+localBlocking / broker (broker falls back to in-process local; `ephemeral`
+defaults true; no cloud SDKs in the package). Opt-in `startInspector()` binds `127.0.0.1`,
+refuses `NODE_ENV=production`, and lazy-loads HTTP for JSON snapshots, SSE, and `/graph`. The kernel is
+not bundled in the `arkgate` tarball.
 
 ### Durability stance
 
@@ -217,8 +227,10 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current release (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) · [CHANGELOG](CHANGELOG.md) |
-| Prior published (4.6.5 on npm `latest` until 4.6.6 lands) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
+| Current tree (4.7.0 prepared) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.6.7 on npm `latest`) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
+| Prior published (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) |
+| Prior published (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
 | Prior published (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |
 | Prior (4.6.2) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) |
 | Prior (4.6.1) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) |

package/SECURITY.md

@@ -18,7 +18,7 @@ Preferred path: use GitHub's private vulnerability reporting for this repository
 - reproduction steps
 - expected impact
 - whether the issue affects `arkgate-check` / `ark-check`, `arkgate-mcp` / `ark-mcp`,
-  generated agent gates, the GitHub Action, or the optional runtime kernel
+  generated agent gates, the GitHub Action, or the optional ArkRun kernel
 
 If private vulnerability reporting is unavailable, open a minimal public issue asking for
 a private security contact without including exploit details.

package/bin/ark-check-runtime.mjs

@@ -7,7 +7,6 @@ import { fileURLToPath } from 'node:url';
 const __arkCheckCli = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 
 import {
-  DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   DEFAULT_INTENT_PREFIXES,
   DEFAULT_LAYER_DIRECTORIES,
   DEFAULT_RULES,
@@ -80,7 +79,6 @@ import {
   CONCENTRATION_MIN_VIOLATIONS,
 } from './lib/violations.mjs';
 import {
-  suggestLayerForDir,
   detectBestFitModel,
   dirSegmentsFromGlob,
 } from './lib/suggestions.mjs';
@@ -126,174 +124,9 @@ import {
   resolveEffectiveProjectRoot,
 } from './lib/project-root.mjs';
 import { demoteArkRuleTeethUnderClassificationFloor } from './lib/rules-under-contract.mjs';
-
-function resolveDesignDeltaBaseRef(root, explicit, env = process.env) {
-  const flag = typeof explicit === 'string' ? explicit.trim() : '';
-  if (flag) return flag;
-  const envRef = normalizePolicyBaseRef(env.ARK_POLICY_BASE_REF);
-  if (envRef) return envRef;
-  const githubBase = typeof env.GITHUB_BASE_REF === 'string' ? env.GITHUB_BASE_REF.trim() : '';
-  if (githubBase) return `origin/${githubBase}`;
-  return discoverLocalBaseRef(root) || undefined;
-}
-
-function parseArgs(argv) {
-  const args = {
-    root: process.cwd(),
-    config: 'ark.config.json',
-    manifest: undefined,
-    printConfig: undefined,
-    tsconfig: undefined,
-    json: false,
-    strictConfig: false,
-    strictMerge: false,
-    requireGates: false,
-    requireWriteHook: undefined,
-    init: false,
-    installAgentGates: false,
-    compact: false,
-    tools: undefined,
-    force: false,
-    skillsOnly: false,
-    baseline: undefined,
-    policyBase: undefined,
-    policyBaseRef: undefined,
-    policyAck: undefined, failOnNewSmells: false, baseRef: undefined,
-    contractSession: false,
-    contractDiff: false,
-    changed: false,
-    against: undefined,
-    base: undefined,
-    persona: undefined,
-    author: undefined,
-    failUngoverned: false,
-    updateBaseline: false,
-    noCache: false,
-    resident: false,
-    coverage: false,
-    migrateCommands: false,
-    doctor: false,
-    plan: false,
-    recommend: false,
-    writePlan: false,
-    listPolicyPacks: false,
-    applyPolicyPack: undefined,
-    watch: false,
-    beginner: false,
-    openReport: false,
-    noOpenReport: false,
-    version: false,
-    help: false,
-    all: false,
-    followConfigRoot: false,
-  };
-  const requireValue = (flag, index) => {
-    const value = argv[index + 1];
-    if (value === undefined || value.startsWith('-')) {
-      throw new Error(`Missing value for ${flag}. Run arkgate-check --help for usage.`);
-    }
-    return value;
-  };
-  for (let i = 2; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--json') args.json = true;
-    else if (arg === '--strict' || arg === '--strict-merge') {
-      args.strictConfig = true;
-      args.requireGates = true;
-      args.strictMerge = true;
-    }
-    else if (arg === '--strict-config') args.strictConfig = true;
-    else if (arg === '--require-gates') {
-      args.requireGates = true;
-      args.strictConfig = true;
-    }
-    else if (arg === '--require-write-hook') {
-      args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
-    }
-    else if (arg === '--init') args.init = true;
-    else if (arg === '--preset') args.preset = requireValue(arg, i++);
-    else if (arg === '--install-agent-gates') args.installAgentGates = true;
-    else if (arg === '--compact') args.compact = true;
-    else if (arg === '--tools') {
-      // Consume the next arg only when it isn't another flag (same rule as --baseline),
-      // so `--tools --force` can't silently eat --force as a "tool name".
-      const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith('-')) {
-        i += 1;
-        args.tools = next
-          .split(',')
-          .map((tool) => tool.trim().toLowerCase())
-          .filter(Boolean);
-      } else {
-        args.tools = []; // flag without a value — rejected in runInstallAgentGates
-      }
-    }
-    else if (arg === '--force') args.force = true;
-    else if (arg === '--follow-config-root') args.followConfigRoot = true;
-    else if (arg === '--skills-only') args.skillsOnly = true;
-    else if (arg === '--coverage') args.coverage = true;
-    else if (arg === '--doctor') args.doctor = true;
-    else if (arg === '--plan') args.plan = true;
-    else if (arg === '--rules-inventory') args.rulesInventory = true;
-    else if (arg === '--recommend') args.recommend = true;
-    else if (arg === '--write-plan') args.writePlan = true;
-    else if (arg === '--list-policy-packs') args.listPolicyPacks = true;
-    else if (arg === '--apply-policy-pack') args.applyPolicyPack = requireValue(arg, i++);
-    else if (arg === '--suggest-include') args.suggestInclude = true;
-    else if (arg === '--adopt-contract') args.adoptContract = true;
-    else if (arg === '--migrate-contract') args.migrateContract = true;
-    else if (arg === '--ratchet-cores') args.ratchetCores = true;
-    else if (arg === '--write') args.write = true;
-    else if (arg === '--watch') args.watch = true;
-    else if (arg === '--beginner') args.beginner = true;
-    else if (arg === '--codex-home') args.codexHome = true;
-    else if (arg === '--claude-home') args.claudeHome = true;
-    else if (arg === '--grok-home') args.grokHome = true;
-    else if (arg === '--agent-homes') {
-      args.agentHomes = true;
-      args.codexHome = true;
-      args.claudeHome = true;
-      args.grokHome = true;
-    }
-    else if (arg === '--migrate-commands') args.migrateCommands = true;
-    else if (arg === '--no-cache') args.noCache = true;
-    else if (arg === '--resident') args.resident = true;
-    else if (arg === '--report') {
-      const next = argv[i + 1];
-      args.report = next && !next.startsWith('-') ? argv[++i] : 'ark-report.html';
-    }
-    else if (arg === '--reset-origin') args.resetOrigin = true;
-    else if (arg === '--no-archive') args.noArchive = true;
-    else if (arg === '--open') args.openReport = true;
-    else if (arg === '--no-open') args.noOpenReport = true;
-    else if (arg === '--baseline' || arg === '--update-baseline') {
-      if (arg === '--update-baseline') args.updateBaseline = true;
-      // optional path value: consume the next arg only when it isn't another flag
-      const next = argv[i + 1];
-      args.baseline = next && !next.startsWith('-') ? argv[++i] : '.ark-baseline.json';
-    }
-    else if (arg === '--policy-base') args.policyBase = requireValue(arg, i++);
-    else if (arg === '--policy-base-ref') args.policyBaseRef = requireValue(arg, i++);
-    else if (arg === '--policy-ack') args.policyAck = requireValue(arg, i++); else if (arg === '--fail-on-new-smells') args.failOnNewSmells = true; else if (arg === '--base-ref') args.baseRef = requireValue(arg, i++);
-    else if (arg === '--contract-session') args.contractSession = true;
-    else if (arg === '--contract-diff') args.contractDiff = true;
-    else if (arg === '--changed') args.changed = true;
-    else if (arg === '--against') args.against = requireValue(arg, i++);
-    else if (arg === '--base') args.base = requireValue(arg, i++);
-    else if (arg === '--persona') args.persona = requireValue(arg, i++);
-    else if (arg === '--author') args.author = requireValue(arg, i++);
-    else if (arg === '--root') args.root = path.resolve(requireValue(arg, i++));
-    else if (arg === '--config') args.config = requireValue(arg, i++);
-    else if (arg === '--manifest') args.manifest = requireValue(arg, i++);
-    else if (arg === '--print-config') args.printConfig = requireValue(arg, i++);
-    else if (arg === '--tsconfig') args.tsconfig = requireValue(arg, i++);
-    else if (arg === '--help' || arg === '-h') args.help = true;
-    else if (arg === '--all') args.all = true;
-    else if (arg === '--version' || arg === '-V') args.version = true;
-    else throw new Error(`Unknown argument: ${arg}. Run arkgate-check --help for usage.`);
-  }
-  return args;
-}
+import { parseArgs, resolveDesignDeltaBaseRef } from './lib/check-args.mjs';
+import { detectConfig, proposeForUncovered } from './lib/check-config-detect.mjs';
+import { runWatchMode } from './lib/check-watch.mjs';
 
 /** Path shown to humans: project-relative when inside root, absolute otherwise (no `../../..`). */
 function displayPathFromRoot(root, absPath) {
@@ -317,101 +150,6 @@ function readConfig(root, configPath) {
   return parseArkConfigJson(fs.readFileSync(fullPath, 'utf8'), fullPath).config;
 }
 
-/**
- * Infer an ark.config.json from the directories that actually exist in the project,
- * using the same layer→directory conventions as the eleven-layer template. A directory
- * only counts when it contains at least one source file, so an empty scaffold dir can't
- * produce a layer whose pattern matches nothing (which --strict-config would fail).
- */
-function detectConfig(root) {
-  const srcDir = fs.existsSync(path.join(root, 'src')) ? 'src' : '.';
-  const layers = [];
-
-  for (const entry of DEFAULT_INTENT_PREFIXES) {
-    const directories = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? []).filter(
-      (directory) => walk(path.join(root, srcDir, directory), [], { root }).length > 0
-    );
-    if (directories.length === 0) continue;
-    layers.push({
-      name: entry.layer,
-      patterns: directories.map((directory) => `${normalize(path.join(srcDir, directory))}/**`),
-      intentPrefixes: entry.prefixes,
-      ...(entry.layer === 'DomainModel'
-        ? { forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS }
-        : {}),
-    });
-  }
-
-  const names = new Set(layers.map((layer) => layer.name));
-  const rules = DEFAULT_RULES.filter((rule) => names.has(rule.from) && names.has(rule.to));
-
-  return { srcDir, config: { include: [srcDir], layers, rules } };
-}
-
-/** Top-level directories under srcDir not covered by any detected layer pattern. */
-function uncoveredDirectories(root, srcDir, layers) {
-  const base = path.join(root, srcDir);
-  if (!fs.existsSync(base)) return [];
-  return fs
-    .readdirSync(base, { withFileTypes: true })
-    .filter(
-      (entry) =>
-        entry.isDirectory() &&
-        entry.name !== 'node_modules' &&
-        entry.name !== 'dist' &&
-        !entry.name.startsWith('.')
-    )
-    .map((entry) => entry.name)
-    .filter((name) => {
-      const prefix = `${normalize(path.join(srcDir, name))}/`;
-      return !layers.some((layer) =>
-        layer.patterns.some((pattern) => pattern.startsWith(prefix))
-      );
-    });
-}
-
-// detectWorkspaces: shared implementation in ark-shared.mjs (npm/pnpm/rush/lerna +
-// conventional multi-package roots).
-
-// Deny every "upward" edge for an ordered layer list (index 0 = outermost/top,
-// which may import everything below it). Inner/lower layers must not import outer
-// ones — the shared shape behind linear layered and feature-sliced layouts.
-
-function proposeForUncovered(root, srcDir, layers) {
-  const proposals = [];
-  for (const top of uncoveredDirectories(root, srcDir, layers)) {
-    const direct = suggestLayerForDir(top);
-    if (direct) {
-      proposals.push({ dir: `${srcDir}/${top}`, ...direct });
-      continue;
-    }
-    let children = [];
-    try {
-      children = fs
-        .readdirSync(path.join(root, srcDir, top), { withFileTypes: true })
-        .filter((e) => e.isDirectory() && e.name !== 'node_modules' && !e.name.startsWith('.'))
-        .map((e) => e.name);
-    } catch {
-      /* not a readable directory — treat as unrecognized below */
-    }
-    if (children.length > 0) {
-      // Descend: propose per child so a mixed `lib/` yields lib/repositories → Persistence
-      // AND flags lib/db as unrecognized, instead of dropping the parts Ark can't place.
-      for (const child of children) {
-        const hit = suggestLayerForDir(child);
-        proposals.push(
-          hit
-            ? { dir: `${srcDir}/${top}/${child}`, ...hit }
-            : { dir: `${srcDir}/${top}/${child}`, unrecognized: true }
-        );
-      }
-    } else {
-      proposals.push({ dir: `${srcDir}/${top}`, unrecognized: true });
-    }
-  }
-  return proposals;
-}
-
 function printInitNextSteps(root) {
   console.log('');
   console.log('Next steps:');
@@ -1733,6 +1471,7 @@ async function main() {
         score: fitness.score,
         mode: fitness.mode,
         improvementCompass: reportCompass,
+        arkRun: designDepth?.arkRun ?? null,
       }),
       leftoverDesignWork: designDepth?.designFitness?.designWeak === true,
     };
@@ -1755,7 +1494,17 @@ async function main() {
       adoption: adoptionForReport,
       designDepth,
       advisories: {
-        ...computeDoctorAdvisories(root, config, coverage, rules, files, ts, parseHealth),
+        ...computeDoctorAdvisories(
+          root,
+          config,
+          coverage,
+          rules,
+          files,
+          ts,
+          parseHealth,
+          undefined,
+          activeViolations
+        ),
         // Doctor parity: always emit improvement compass when doctor would (reportParity).
         ...(designDepth?.improvementCompass
           ? { improvementCompass: designDepth.improvementCompass }
@@ -1764,6 +1513,7 @@ async function main() {
         ...(designDepth?.deepModuleCoach
           ? { deepModuleCoach: designDepth.deepModuleCoach }
           : {}),
+        ...(designDepth?.arkRun ? { arkRun: designDepth.arkRun } : {}),
       },
     };
     const html = args.beginner
@@ -1964,87 +1714,17 @@ async function main() {
   }
 
   if (args.watch) {
-    await runWatchMode(args);
+    await runWatchMode(args, {
+      cliPath: __arkCheckCli,
+      loadConfig: readConfig,
+      dim: color.dim,
+    });
     return;
   }
 
   process.exitCode = designCheck.exitCode(observedOk && (!args.strictMerge || analysisComplete) ? 0 : 1);
 }
 
-async function runWatchMode(args) {
-  const argv = process.argv.slice(2).filter((token) => token !== '--watch');
-  let debounce;
-  const rerun = () => {
-    clearTimeout(debounce);
-    debounce = setTimeout(() => {
-      const result = spawnSync(process.execPath, [__arkCheckCli, ...argv], {
-        cwd: args.root,
-        stdio: 'inherit',
-        env: process.env,
-      });
-      process.exitCode = result.status ?? 1;
-    }, 300);
-  };
-
-  let config;
-  try {
-    config = readConfig(args.root, args.config);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 2;
-    return;
-  }
-
-  for (const entry of config.include ?? []) {
-    const target = path.join(args.root, entry);
-    if (!fs.existsSync(target)) continue;
-    try {
-      const watcher = fs.watch(target, { recursive: true }, rerun);
-      watcher.on('error', () => {
-        watcher.close();
-        watchByPolling(target, rerun);
-      });
-    } catch {
-      watchByPolling(target, rerun);
-    }
-  }
-
-  console.log(color.dim('Watching governed paths for changes… (Ctrl+C to stop)'));
-  await new Promise(() => {});
-}
-
-function watchByPolling(target, onChange) {
-  let previous = watchFingerprint(target);
-  setInterval(() => {
-    const current = watchFingerprint(target);
-    if (current === previous) return;
-    previous = current;
-    onChange();
-  }, 250);
-}
-
-function watchFingerprint(target) {
-  const pending = [target];
-  const entries = [];
-  while (pending.length > 0) {
-    const current = pending.pop();
-    let stat;
-    try {
-      stat = fs.statSync(current);
-    } catch {
-      continue;
-    }
-    entries.push(`${current}:${stat.mtimeMs}:${stat.size}`);
-    if (!stat.isDirectory()) continue;
-    try {
-      for (const name of fs.readdirSync(current)) pending.push(path.join(current, name));
-    } catch {
-      // A concurrent delete is represented by the next fingerprint.
-    }
-  }
-  return entries.sort().join('|');
-}
-
 main().catch((error) => {
   console.error(
     process.env.ARK_DEBUG_STACK === '1' && error instanceof Error