arkgate 4.8.14 → 4.8.16

package/bin/lib/architecture-scan.mjs

@@ -16,7 +16,14 @@ import {
   invariantIdsFromCatalog,
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
+import { catalogHasEnforcedInvariant } from './invariant-coverage.mjs';
+import {
+  declaredCoverageRootsPresent,
+  declaredInvariantTestsPathPresent,
+  scanDemandsInvariantTestsPath,
+} from './invariant-tests-path.mjs';
 import { loadArkRuleFileHints } from './arkrule-file-hints.mjs';
+import { collectGovernedFiles } from './scan-files.mjs';
 
 const HINT_CACHE_CAP = 16;
 /** Process-local hint map keyed by scoped path + content hash. Not a second engine. */
@@ -40,15 +47,34 @@ function normalizeScanRelPath(root, filePath) {
   return relative;
 }
 
-/** Empty / missing `files` stays unbounded (full governed set). */
-function fileLocalScope(root, files) {
+/**
+ * Empty / missing `files` stays unbounded (full governed set).
+ * A complete governed list is also unbounded — doctor and check always pass
+ * that list, and treating it as `--changed` paid import-closure + a second
+ * `resolveModuleName` pass on every full-tree run (#212).
+ */
+function fileLocalScope(root, files, config, { changed = false } = {}) {
   if (!Array.isArray(files) || files.length === 0) return null;
   const scoped = new Set();
   for (const file of files) {
     const rel = normalizeScanRelPath(root, file);
     if (rel) scoped.add(rel);
   }
-  return scoped.size > 0 ? scoped : null;
+  if (scoped.size === 0) return null;
+  // `--changed` is already a bounded envelope — do not re-walk the include tree (#205).
+  if (!changed && config && coversGovernedSet(root, scoped, config)) return null;
+  return scoped;
+}
+
+function coversGovernedSet(root, scoped, config) {
+  const governed = collectGovernedFiles(root, config);
+  if (governed.length === 0) return false;
+  if (scoped.size < governed.length) return false;
+  for (const absolute of governed) {
+    const rel = normalizeScanRelPath(root, absolute);
+    if (rel && !scoped.has(rel)) return false;
+  }
+  return true;
 }
 
 function filterHintPreload(fileContents, scoped) {
@@ -126,7 +152,9 @@ export function resolveArchitectureSnapshot({
     { ...config, rules: rules ?? config.rules },
     manifest
   );
-  const scoped = fileLocalScope(root, files);
+  const scoped = fileLocalScope(root, files, effectiveConfig, {
+    changed: args?.changed === true,
+  });
   const facts = resolveCandidateFacts({
     root,
     config: effectiveConfig,
@@ -176,9 +204,20 @@ export function resolveArchitectureSnapshot({
     filterHintPreload(coverageInputs?.fileContents, scoped),
     scoped
   );
+  const adopted = scanDemandsInvariantTestsPath(root, args);
+  const pathPresent = adopted
+    ? declaredInvariantTestsPathPresent(root, effectiveConfig.coverage)
+    : true;
+  // Silent when nothing is enforced — do not probe coverageRoots on that path.
+  const rootsPresent = catalogHasEnforcedInvariant(arkRulesLoad.arkRules?.invariants)
+    ? declaredCoverageRootsPresent(root, effectiveConfig.coverage)
+    : true;
   const analyzed = analyzeTrustedResolvedProject({
     contract: analysisContract,
     facts,
+    ...(adopted ? { adopted: true } : {}),
+    ...(adopted && pathPresent === false ? { invariantTestsPathPresent: false } : {}),
+    ...(rootsPresent === false ? { coverageRootsPresent: false } : {}),
     ...(coverageInputs ? { coverageInputs } : {}),
     ...(fileHints ? { fileHints } : {}),
   });

package/bin/lib/ark-run-doctor.mjs

@@ -11,6 +11,10 @@
 import { composeMergePlanesHonesty, extraMergeTeethAllowed, isArkRunRuleId, } from './extra-merge-teeth.mjs';
 export const ARK_RUN_DOCTOR_SCHEMA_VERSION = '1.0';
 const RESIDUAL_RULE_CAP = 12;
+/** Compact / details — only when `arkRun` is on. Absence stays silent. */
+export const ARKRUN_ONE_BREATH = 'Layers stop a bad import. ArkRun is an optional experimental runtime — in-memory, not Postgres. Data is gone on restart.';
+/** Next step when the extra is on and residual remains. */
+export const ARKRUN_FIRST_CONTACT_NEXT = 'Next: /ark-runtime to wire one candidate.';
 function closedMode(value) {
     return value === 'enforced' || value === 'advisory' ? value : null;
 }
@@ -126,6 +130,7 @@ export function formatArkRunDoctorLines(section) {
     const mode = section.mode ?? 'unknown';
     const teeth = section.extraMergeTeeth === true ? 'armed' : 'not armed';
     const lines = [
+        ARKRUN_ONE_BREATH,
         `mode: ${mode} · extra merge teeth ${teeth} · not a score`,
     ];
     if (section.residual.count > 0) {
@@ -134,6 +139,7 @@ export function formatArkRunDoctorLines(section) {
             ? ` (+${section.residual.count - section.residual.ruleIds.length} more)`
             : '';
         lines.push(`Residual: ${shown}${more}`);
+        lines.push(ARKRUN_FIRST_CONTACT_NEXT);
     }
     else {
         lines.push('Residual: none on this scan (not a score — green extras ≠ finished kernel wiring).');

package/bin/lib/ark-run-report.mjs

@@ -1,6 +1,8 @@
 /**
  * HTML for the doctor ArkRun advisory (report parity: data-advisory="arkRun").
  */
+import { ARKRUN_FIRST_CONTACT_NEXT, ARKRUN_ONE_BREATH } from './ark-run-doctor.mjs';
+
 export function formatArkRunHtml(section, esc) {
   if (!section || typeof section !== 'object' || section.notAScore !== true) return '';
   const escape = typeof esc === 'function' ? esc : (v) => String(v);
@@ -17,6 +19,7 @@ export function formatArkRunHtml(section, esc) {
   }
   const residual = section.residual && typeof section.residual === 'object' ? section.residual : { count: 0, ruleIds: [] };
   const ids = Array.isArray(residual.ruleIds) ? residual.ruleIds : [];
+  const next = residual.count > 0 ? ` ${ARKRUN_FIRST_CONTACT_NEXT}` : '';
   const residualHtml =
     residual.count > 0
       ? `<p><span class="tag warn">residual</span> ${ids
@@ -40,8 +43,9 @@ export function formatArkRunHtml(section, esc) {
   <section class="section card" data-advisory="arkRun">
     <h2>ArkRun <span class="muted">(not a score)</span></h2>
     <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
-      <b>[ArkRun]</b> Kernel usage + declarations — separate from <b>[Layer]</b> imports and <b>[ArkRules]</b> shape.
-      Advisory never flips <code>valid</code>. Enforced extra teeth only when the layer plane is classified.
+      <b>[ArkRun]</b> ${ARKRUN_ONE_BREATH}
+      Kernel usage + declarations — separate from <b>[Layer]</b> imports and <b>[ArkRules]</b> shape.
+      Advisory never flips <code>valid</code>. Enforced extra teeth only when the layer plane is classified.${next}
     </p>
     ${merge}
     <div class="kpis" style="margin-bottom:.55rem">

package/bin/lib/arkrules-sensors.mjs

@@ -378,6 +378,87 @@ export function collectEmptyAppliesToFindings(arkRules, files) {
         a.arkruleId.localeCompare(b.arkruleId) ||
         a.message.localeCompare(b.message));
 }
+/** Intent prefixes are short tokens (`Domain.`, `Application.`). Bound the scan. */
+const INTENT_PREFIX_SCAN_LIMIT = 64;
+/**
+ * Strip trailing `.` without a regex. `\.+$` on config strings is CodeQL
+ * js/polynomial-redos (backtracking on long runs of `.`). Linear walk is enough.
+ */
+function stripTrailingDots(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 46) {
+        end -= 1;
+    }
+    return end === value.length ? value : value.slice(0, end);
+}
+function normalizeIntentPrefix(prefix) {
+    const trimmed = prefix.trim();
+    const bounded = trimmed.length > INTENT_PREFIX_SCAN_LIMIT
+        ? trimmed.slice(0, INTENT_PREFIX_SCAN_LIMIT)
+        : trimmed;
+    return stripTrailingDots(bounded);
+}
+function layerNameLooksDomain(layer) {
+    const lower = layer.toLowerCase();
+    return (lower.includes('domain') ||
+        lower.includes('entity') ||
+        lower.includes('aggregate') ||
+        lower.includes('model'));
+}
+function ownsDomainIntent(intentPrefixes) {
+    return intentPrefixes.some((prefix) => {
+        const normalized = normalizeIntentPrefix(prefix);
+        return normalized === 'Domain' || normalized.startsWith('Domain.');
+    });
+}
+/** Domain-role house: name or intentPrefixes. Keep aligned with rulesInventory. */
+export function isDomainRoleLayerName(layer, intentPrefixes = []) {
+    return layerNameLooksDomain(layer) || ownsDomainIntent(intentPrefixes);
+}
+/**
+ * §2 catalog residual — ArkRules is on, Domain has code, invariants[] is empty.
+ * Advisory by default. failsStrict only when a domain structure rule is already
+ * enforced (the project opted into ArkRules merge teeth). Not freezable.
+ */
+export function collectEmptyInvariantCatalogFindings(input) {
+    if (input.arkRulesActive !== true)
+        return [];
+    const domainLayers = (input.layers ?? [])
+        .filter((layer) => isDomainRoleLayerName(layer.name, layer.intentPrefixes ?? []))
+        .map((layer) => layer.name);
+    if (domainLayers.length === 0)
+        return [];
+    const domainSet = new Set(domainLayers);
+    const domainPopulated = (input.files ?? []).some((file) => {
+        const layer = typeof file.layer === 'string' ? file.layer : '';
+        return layer.length > 0 && domainSet.has(layer);
+    });
+    if (!domainPopulated)
+        return [];
+    const domainInvariants = (input.arkRules.invariants ?? []).filter((inv) => domainSet.has(inv.provenance.layer));
+    if (domainInvariants.length > 0)
+        return [];
+    const fillLayer = domainLayers.find((name) => input.arkRules.byLayer?.[name]) ?? domainLayers[0];
+    const fillPath = input.arkRules.byLayer?.[fillLayer]?.sourceFile ?? `arkrules/${fillLayer}.json`;
+    const optedIntoTeeth = (input.arkRules.structure ?? []).some((rule) => rule.mode === 'enforced' &&
+        domainSet.has(rule.provenance.layer) &&
+        !isTier2(rule.sensor));
+    return [
+        {
+            ruleId: 'INVARIANT_CATALOG_EMPTY',
+            code: 'invariant-catalog-empty',
+            message: `ArkRules is on and ${fillLayer} has code, but invariants[] is empty — there are no phrases the code must preserve. Add 1–2 short phrases in ${fillPath}.`,
+            file: fillPath,
+            line: 1,
+            fromLayer: fillLayer,
+            arkruleId: 'invariant-catalog',
+            arkruleSource: fillPath,
+            severity: optedIntoTeeth ? 'error' : 'warning',
+            sensor: 'invariant-coverage',
+            failsStrict: optedIntoTeeth,
+        },
+    ];
+}
 /** IO / ORM import evidence. postgres and drizzle-orm include package subpaths. Keep in lockstep with arkOrderFacts. */
 const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm(?:\/[^'"]+)?|postgres(?:\/[^'"]+)?|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|postgres(?:\/[^'"]+)?|drizzle-orm(?:\/[^'"]+)?|knex|typeorm|mongoose)/;
 /**

package/bin/lib/baseline-key.mjs

@@ -9,7 +9,12 @@
  */
 
 /** Config diagnostics that are never code debt. Not a schema key. */
-export const NON_FREEZABLE_BASELINE_RULE_IDS = ['ARKRULE_SCOPE_EMPTY'];
+export const NON_FREEZABLE_BASELINE_RULE_IDS = [
+    'ARKRULE_SCOPE_EMPTY',
+    'INVARIANT_CATALOG_EMPTY',
+    'INVARIANT_TESTS_PATH_MISSING',
+    'INVARIANT_COVERAGE_ROOTS_MISSING',
+];
 /**
  * STRUCTURE freeze `target`: sensor id, plus `:symbol` when a method/class is known.
  * V1 empty-target keys (`ARKRULE_STRUCTURE|file|layer||`) stay exact-match only —

package/bin/lib/check-args.mjs

@@ -14,7 +14,55 @@ export function resolveDesignDeltaBaseRef(root, explicit, env = process.env) {
   return discoverLocalBaseRef(root) || undefined;
 }
 
-export function parseArgs(argv) {
+/** Opt-in local / multi-worktree cheap check. Ignored values: empty, 0, false, no, off. */
+export function envFlagOn(value) {
+  return /^(1|true|yes)$/i.test(String(value ?? '').trim());
+}
+
+export const LOCAL_STRICT_MERGE_MESSAGE =
+  '--local cannot be combined with --strict-merge: CI stays the full fail-closed check. Use --local (or ARK_CHECK_LOCAL=1) only on the local / pre-push path.';
+
+export const LOCAL_TREE_MODE_MESSAGE =
+  '--local cannot be combined with report modes that need the whole tree (--doctor, --coverage, --plan, --report, --promote). Use --local --base <ref> for the cheap local check.';
+
+export function localCheckEnvelope(args, root) {
+  if (!args?.local) return {};
+  return {
+    local: true,
+    scope: 'changed',
+    analysisRoot: path.resolve(root),
+  };
+}
+
+/**
+ * `--local` / `ARK_CHECK_LOCAL=1` reuse `--changed`. Env is ignored under
+ * `--strict-merge` and under full-tree report modes so CI / doctor stay whole-tree.
+ */
+export function applyLocalCheckMode(args, env = process.env) {
+  const explicit = args.local === true;
+  const fromEnv = envFlagOn(env.ARK_CHECK_LOCAL);
+  if (!explicit && !fromEnv) return args;
+  const treeModes = [
+    args.doctor && '--doctor',
+    args.coverage && '--coverage',
+    args.plan && '--plan',
+    args.report && '--report',
+    args.promote && '--promote',
+  ].filter(Boolean);
+  if (args.strictMerge) {
+    if (explicit) throw new Error(LOCAL_STRICT_MERGE_MESSAGE);
+    return args;
+  }
+  if (treeModes.length > 0) {
+    if (explicit) throw new Error(LOCAL_TREE_MODE_MESSAGE);
+    return args;
+  }
+  args.local = true;
+  args.changed = true;
+  return args;
+}
+
+export function parseArgs(argv, env = process.env) {
   const args = {
     root: process.cwd(),
     config: 'ark.config.json',
@@ -39,6 +87,7 @@ export function parseArgs(argv) {
     contractSession: false,
     contractDiff: false,
     changed: false,
+    local: false,
     against: undefined,
     base: undefined,
     persona: undefined,
@@ -180,6 +229,7 @@ export function parseArgs(argv) {
     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 === '--local') args.local = 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++);
@@ -238,5 +288,5 @@ export function parseArgs(argv) {
       );
     }
   }
-  return args;
+  return applyLocalCheckMode(args, env);
 }

package/bin/lib/config-contract.mjs

@@ -9,9 +9,40 @@
  */
 
 import { ARK_ORDER_SCHEMA_DEF, ARK_RUN_SCHEMA_DEF, defaultedArkOrder, defaultedArkRun, validateArkOrderExtra, validateArkRunExtra, } from './config-extras.mjs';
+import { canonicalStewardId } from './team-parliament.mjs';
 /** Current published ark.config.json schema version (ADR 0027: 1.3 adds optional arkOrder). */
 export const ARK_CONFIG_SCHEMA_VERSION = '1.3';
-export const ARK_CONFIG_SCHEMA_URL = 'https://unpkg.com/arkgate@2/schemas/ark.config.schema.json';
+/** Closed layer trust tags. Optional; absence is silent. Not a schemaVersion bump. */
+export const LAYER_TRUST_BOUNDARIES = ['public', 'auth', 'admin', 'internal'];
+/** Future house: empty globs are expected; missing owners stay silent even when required. */
+export function isFutureHouseLayer(layer) {
+    return layer?.optional === true || layer?.reserved === true || layer?.allowEmpty === true;
+}
+/**
+ * Present `layers[].owners` as non-empty strings. Absence / empty / wrong type → undefined.
+ */
+export function layerOwnersList(layer) {
+    const raw = layer && typeof layer === 'object' ? layer.owners : undefined;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const ids = raw.filter((entry) => typeof entry === 'string' && entry.length > 0);
+    return ids.length > 0 ? ids : undefined;
+}
+/**
+ * Layer names that must name owners when `requireLayerOwners` is on.
+ * Empty when the require flag is absent or false.
+ */
+export function layersMissingRequiredOwners(config) {
+    if (config?.requireLayerOwners !== true || !Array.isArray(config.layers))
+        return [];
+    return config.layers
+        .filter((layer) => !isFutureHouseLayer(layer) && !layerOwnersList(layer))
+        .map((layer) => layer.name);
+}
+export function missingLayerOwnersNextAction(layerName) {
+    return `Add a GitHub handle or email to ${layerName}'s owners in ark.config.json (/ark-adopt).`;
+}
+export const ARK_CONFIG_SCHEMA_URL = 'https://unpkg.com/arkgate@4/schemas/ark.config.schema.json';
 const DEFAULT_LAYER_NAMES = [
     'DomainModel',
     'ApplicationOrchestration',
@@ -121,6 +152,11 @@ export const ARK_CONFIG_SCHEMA = {
         arkOrder: { $ref: '#/$defs/arkOrder' },
         /** Team parliament — GitHub handles or emails who may loosen the law (not part of policy hash). */
         stewards: { ...stringArraySchema, default: [] },
+        /**
+         * When true, every non-reserved layer must name owners. Absence/false is
+         * silent. Policy teeth — stays in policyHash. Owners stay metadata.
+         */
+        requireLayerOwners: { type: 'boolean' },
     },
     $defs: {
         layer: {
@@ -133,6 +169,8 @@ export const ARK_CONFIG_SCHEMA = {
                 exclude: stringArraySchema,
                 intentPrefixes: stringArraySchema,
                 description: { type: 'string', minLength: 1 },
+                trustBoundary: { type: 'string', enum: [...LAYER_TRUST_BOUNDARIES] },
+                owners: { ...stringArraySchema, minItems: 1 },
                 forbiddenGlobals: stringArraySchema,
                 capabilities: {
                     type: 'object',
@@ -205,7 +243,7 @@ export const ARK_CONFIG_SCHEMA = {
         coverage: {
             type: 'object',
             additionalProperties: false,
-            description: 'Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget and also bounds structural-hint preload for orchestration-only, thin-adapter, and writes-via-aggregate (default 400; there is no arkrules.hintBudget); coverageRoots declares where the project runs its tests, so a covering test found outside them is reported instead of silently certifying an invariant.',
+            description: 'Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget and also bounds structural-hint preload for orchestration-only, thin-adapter, and writes-via-aggregate (default 400; there is no arkrules.hintBudget); coverageRoots declares where the project runs its tests, so a covering test found outside them is reported instead of silently certifying an invariant. When any invariant is enforced, missing coverageRoots fails closed.',
             properties: {
                 testGlobs: { ...stringArraySchema, minItems: 1 },
                 maxFiles: {
@@ -351,6 +389,30 @@ function validateNode(value, schema, path, root, issues) {
         }
     }
 }
+function validateLayerOwners(candidate, issues) {
+    const layers = candidate.layers;
+    if (!Array.isArray(layers))
+        return;
+    layers.forEach((layer, index) => {
+        if (!layer || typeof layer !== 'object' || Array.isArray(layer))
+            return;
+        if (!('owners' in layer))
+            return;
+        const owners = layer.owners;
+        if (!Array.isArray(owners))
+            return;
+        owners.forEach((entry, ownerIndex) => {
+            if (typeof entry !== 'string')
+                return;
+            if (!canonicalStewardId(entry)) {
+                issues.push({
+                    path: `$.layers[${index}].owners[${ownerIndex}]`,
+                    message: 'must be a GitHub handle or email (not a display name)',
+                });
+            }
+        });
+    });
+}
 function defaultedConfig(input) {
     const result = {
         ...input,
@@ -456,6 +518,7 @@ export function loadArkConfigContract(input, source = 'ark.config.json') {
     validateNode(candidate, ARK_CONFIG_SCHEMA, '$', ARK_CONFIG_SCHEMA, issues);
     validateArkRunExtra(candidate, issues);
     validateArkOrderExtra(candidate, issues);
+    validateLayerOwners(candidate, issues);
     if (issues.length > 0)
         throw new ArkConfigValidationError(source, issues);
     return { config: candidate, migratedFrom };

package/bin/lib/diagnostic-catalog.mjs

@@ -56,8 +56,11 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ARKRULE_INVARIANT', 'arkrules', 'ArkRule invariant failed', 'Reserved / remediation-recognized code for invariant-plane failures bound to an ArkRule id (coverage path also emits INVARIANT_UNCOVERED).', 'Fix the invariant for the ArkRule declared in arkrules/<Layer>.json, then preflight again. Do not demote without acknowledgement.'),
     entry('ARKRULE_SCOPE_EMPTY', 'arkrules', 'ArkRule appliesTo matched zero files', 'An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.', 'Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.', { oftenAdvisory: true }),
     entry('ARKRULE_HINT_BUDGET_EXHAUSTED', 'arkrules', 'Structural-hint budget exhausted', 'orchestration-only, thin-adapter, and writes-via-aggregate only evaluate files the hint loader preloaded. When eligible governed files exceed that budget (coverage.maxFiles, default 400 — there is no arkrules.hintBudget), those sensors never saw the rest of their scope. Enforced + unreviewed is not green. The finding names exact hinted/governed counts and per-sensor reviewed N/M of scope.', 'Raise coverage.maxFiles in ark.config.json (this cap also bounds structural-hint preload; --doctor names the coupling) so hinted/governed counts match, then re-run with --strict-config. An enforced hint sensor that cannot see its scope fails strict.'),
+    entry('INVARIANT_CATALOG_EMPTY', 'arkrules', 'Domain invariant catalog is empty', 'ArkRules is on and a Domain-role layer has code, but invariants[] has no phrases the code must preserve. Empty looks like “done” until someone fills the catalog.', 'Add 1–2 short phrases to invariants[] in arkrules/<Domain>.json (or the mapped file). Starters show the shape. Advisory unless a domain structure rule is already enforced — then --strict-merge can refuse. Do not freeze this finding.', { oftenAdvisory: true }),
     entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is never-had-tests (adopt residual) vs tests-disappeared (suite exists).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green. When the message reports an exhausted file budget, raise coverage.maxFiles (or narrow coverage.testGlobs) in ark.config.json.'),
     entry('INVARIANT_COVERAGE_OUTSIDE_ROOTS', 'arkrules', 'Covering test outside the declared coverage roots', 'The only test naming this invariant sits outside coverage.coverageRoots — the places the project declares its runner executes. ArkGate matches declared text and never executes tests, so it cannot tell whether that file is ever run: coverage there is a test that exists, not a test that runs.', 'Move the test under a declared coverage root, or add its root to coverage.coverageRoots in ark.config.json. Advisory: it never fails strict, but promotion to enforced refuses on it.', { oftenAdvisory: true }),
+    entry('INVARIANT_TESTS_PATH_MISSING', 'arkrules', 'Domain-invariant tests path missing under adopted', 'The project is adopted (required CI or explicit advisory) and has domain invariants that want test evidence, but ark.config.json does not name where those tests live. Green coverage without a real tests path is an empty checkbox.', 'Add coverage.testGlobs or coverage.coverageRoots in ark.config.json pointing at a real tests folder, then re-run. Adopted mode fails closed until that path is present. Not freezable.'),
+    entry('INVARIANT_COVERAGE_ROOTS_MISSING', 'arkrules', 'Coverage roots missing while an invariant is enforced', 'A catalogued domain invariant is enforced, but ark.config.json does not name coverage.coverageRoots — the folders where the project says its test runner actually goes. Without that declaration, INVARIANT_COVERAGE_OUTSIDE_ROOTS cannot fire and coverage can certify a test no runner runs.', 'Add coverage.coverageRoots in ark.config.json pointing at the folder the test runner uses, then re-run. testGlobs alone is not enough. Fail-closed until that path is present. Not freezable.'),
     // ── ArkRun (opt-in extra; RN05 dual-depth nextAction) ────────────────────
     entry('ARKRUN_MISSING_ROOT', 'arkrun', 'No kernel factory in composition roots', 'The ArkRun extra is on but no createArkKernel / createStrictArkKernel / createArkKernelFromConfig / createStrictArkKernelFromConfig factory was found in arkRun.compositionRoots, so agents can skip the kernel while the write gate stays green.', 'Import createStrictArkKernel from arkgate/runtime (same npm package; @arkgate/runtime is deprecated) and call it in a composition root listed in arkRun.compositionRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.'),
     entry('ARKRUN_KERNEL_IN_DOMAIN', 'arkrun', 'Domain-role layer imports the kernel', 'A Domain-role layer imports arkgate/runtime, @arkgate/runtime, or kernel types. Domain stays kernel-free; composition roots and adapters own the factory.', 'Move the kernel import out of the Domain-role layer into a composition root or adapter. Import from arkgate/runtime (same npm package; @arkgate/runtime is deprecated), then preflight again. Never mechanical-safe.'),
@@ -90,7 +93,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('DESIGN_SMELL_REGRESSION', 'preflight', 'Design smell regression on base-relative ratchet', 'Compared to the base ref, the candidate introduces a created-path domain-logic-in-ui file under --strict-merge, or introduces or worsens a blocking design-smell class under --fail-on-new-smells.', 'Move the new UI business rule out of the created file (or revert a --fail-on-new-smells regression), then re-run with the same base ref.'),
     // ── analysis completeness / host ─────────────────────────────────────────
     entry('ANALYSIS_PARSE_INCOMPLETE', 'analysis', 'Parse incomplete', 'Governed source could not be fully parsed; evidence includes the TypeScript diagnostic (line + message). Incremental mid-edit parse is normal for agents. Contract exclude paths skip the write hook.', 'Finish the source or fix the reported syntax error, then re-run `npx arkgate-check`. The write hook does not deny solely on mid-edit parse. Partial never means pass.'),
-    entry('LEXICAL_EVIDENCE_INCOMPLETE', 'analysis', 'Lexical evidence incomplete', 'Single-file validation cannot prove project module resolution. The write hook is already the verdict.', 'Re-run `npx arkgate-check --root . --config ark.config.json`, or treat the hook deny as final. Do not call ark_prepare_change from a hook deny.'),
+    entry('LEXICAL_EVIDENCE_INCOMPLETE', 'analysis', 'Lexical evidence incomplete', 'This check only saw one file, so it cannot fully prove how the import resolves. The result is provisional — `ark-check` on the project is the authority.', 'Run `npx arkgate-check --root . --config ark.config.json` to confirm. Do not call ark_prepare_change from a hook deny.'),
     entry('ANALYSIS_COVERS_NO_FILES', 'analysis', 'Analysis covered no files', '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, or layer patterns written for a different layout.', '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`. This is a refusal about ArkGate\u2019s own inputs, not a finding about your code; no baseline or policy acknowledgement can suppress it.'),
     entry('ANALYSIS_HOST_UNAVAILABLE', 'analysis', 'Analysis host unavailable', 'No usable TypeScript / analysis host was available for this invocation.', 'Install a supported TypeScript version visible to the project, then re-run. Unavailable analysis is fail-closed.'),
     entry('ADAPTER_NOT_ALLOWED_FOR_PORT', 'adapter', 'Adapter not allowed for port', 'Runtime/port wiring selected an adapter implementation that the architecture profile does not allow for that port.', 'Bind an allowed adapter for the port, or adjust the profile with an explicit policy decision — then re-run.'),
@@ -116,6 +119,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('CONFIG_RULE_UNKNOWN_TO_LAYER', 'config', 'Rule unknown to layer', 'A dependency rule references a target layer name that is not declared.', 'Fix the rule’s to field to a declared layer name.', { oftenAdvisory: true }),
     entry('CONFIG_AMBIGUOUS_LAYERS', 'config', 'Ambiguous layer classification', 'Some files match multiple layers at equal specificity; classification falls back to declaration order.', 'Disambiguate overlapping patterns so each file has one clear layer owner.', { oftenAdvisory: true }),
     entry('CONFIG_UNCLASSIFIED_FILES', 'config', 'Unclassified included files', 'Included source files match no layer pattern; import rules will not enforce on them.', 'Extend layer patterns or narrow include so every governed file is classified.', { oftenAdvisory: true }),
+    entry('CONFIG_LAYER_MISSING_OWNER', 'config', 'Layer missing owner', 'requireLayerOwners is on and this layer has no owners. Writes to that house fail closed, like a folder with no name on the door.', 'Add a GitHub handle or email to that layer’s owners in ark.config.json (/ark-adopt), then re-run. Reserved/allowEmpty houses may stay unnamed. Turn the flag off only if you no longer want owners required.'),
     // ── literal path drift ───────────────────────────────────────────────────
     entry('LITERAL_PATH_DRIFT', 'drift', 'Literal path moved by a rename', 'A repo path written inside a string, a comment or a docstring no longer resolves, and the rename set says where it went. Nothing in the gate sees this class: `tsc` resolves imports, not strings, and ESLint does not either, so the rename compiles green and the reference lies afterwards. It appears in four forms — the tsconfig alias, a relative literal, a path written without the include-root prefix, and prose — and a hand sweep reliably covers one of them.', 'Apply the suggested replacement, or re-run `npx arkgate-check --path-drift --base-ref <ref> --write` to apply every writable anchored replacement at once. The rewrite is mechanical and one-directional: the destination comes from the rename, it must itself resolve and be path-shaped, and the token is rewritten in the form the author wrote it in. A destination that leaves the alias root of the literal is reported with the target only and must be rewritten by hand.'),
     entry('LITERAL_PATH_UNRESOLVED', 'drift', 'Literal path does not resolve', 'A literal that looks like a repo path does not resolve under this root, and no rename explains where it went. Unlike LITERAL_PATH_DRIFT this is a candidate, not a verdict: with nothing to anchor it, ArkGate cannot tell a dead reference from an illustrative path in a comment, an example in documentation, or a path belonging to another tree.', 'Read the candidate and decide: fix the path, or leave it. Advisory only — it never fails a run and is never rewritten by --write, because there is no destination to propose. Run `--path-drift --all` to list the sweep.', { oftenAdvisory: true }),

package/bin/lib/doctor-advisories.mjs

@@ -18,9 +18,17 @@ import {
 } from './reshape-decisions.mjs';
 import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs';
-import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import {
+  formatArkRulesDoctorLines,
+  summarizeRulesUnderContract,
+} from './rules-under-contract.mjs';
 import { collectStewardNudge } from './team-parliament-io.mjs';
-import { formatArkRunDoctorLines, summarizeArkRunSection } from './ark-run-doctor.mjs';
+import {
+  ARKRUN_FIRST_CONTACT_NEXT,
+  ARKRUN_ONE_BREATH,
+  formatArkRunDoctorLines,
+  summarizeArkRunSection,
+} from './ark-run-doctor.mjs';
 import {
   ARKORDER_FIRST_CONTACT_NEXT,
   ARKORDER_ONE_BREATH,
@@ -28,6 +36,7 @@ import {
   summarizeArkOrderSection,
 } from './ark-order-doctor.mjs';
 import { composeMergePlanesHonesty } from './extra-merge-teeth.mjs';
+import { collectPrototypeShortcutsResidual } from './prototype-shortcuts.mjs';
 
 export function attachExtraDoctorSections(rulesUnderContract, config, classification, findings) {
   const arkRulesMerge = {
@@ -80,12 +89,78 @@ export function attachExtraDoctorSections(rulesUnderContract, config, classifica
   return { arkRun, arkOrder, mergePlanes };
 }
 
+function arkRulesDoctorMark(section, warn) {
+  if (Array.isArray(section?.loadErrors) && section.loadErrors.length > 0) return warn;
+  if (section?.emptyInvariantCatalog === true) return warn;
+  if ((Number(section?.uncoveredInvariants) || 0) > 0) return warn;
+  return ' ';
+}
+
 export function printCompactExtraDoctorLines(advisories, io) {
+  const owners = advisories?.layerOwners;
+  if (owners?.required && owners.ask) {
+    console.log('');
+    io.line(io.warn, owners.ask);
+    if (owners.nextAction) io.line(' ', `Next: ${owners.nextAction}`);
+  }
+  const adr = advisories?.adrPresence;
+  if (adr?.missing && adr.ask) {
+    console.log('');
+    io.line(io.warn, adr.ask);
+    if (adr.nextAction) io.line(' ', `Next: ${adr.nextAction}`);
+  }
+  const catalog = advisories?.statusTransitionCatalog;
+  if (catalog?.ask) {
+    console.log('');
+    io.line(io.warn, catalog.ask);
+    if (catalog.nextAction) io.line(' ', `Next: ${catalog.nextAction}`);
+  } else {
+    const states = advisories?.statesTransitions;
+    if (states?.ask) {
+      console.log('');
+      io.line(io.warn, states.ask);
+      if (states.nextAction) io.line(' ', `Next: ${states.nextAction}`);
+    }
+  }
+  const noDomain = advisories?.noDomainFrontend;
+  if (noDomain?.ask) {
+    console.log('');
+    io.line(io.warn, noDomain.ask);
+    if (noDomain.nextAction) io.line(' ', `Next: ${noDomain.nextAction}`);
+  }
+  const prototypeShortcuts = advisories?.prototypeShortcuts;
+  if (prototypeShortcuts?.ask) {
+    console.log('');
+    io.line(io.warn, prototypeShortcuts.ask);
+    if (prototypeShortcuts.nextAction) io.line(' ', `Next: ${prototypeShortcuts.nextAction}`);
+  }
+  const testsPath = advisories?.invariantTestsPath;
+  if (testsPath?.missing && testsPath.ask) {
+    console.log('');
+    io.line(io.warn, testsPath.ask);
+    if (testsPath.nextAction) io.line(' ', `Next: ${testsPath.nextAction}`);
+  }
+  const coverageRoots = advisories?.invariantCoverageRoots;
+  if (coverageRoots?.missing && coverageRoots.ask) {
+    console.log('');
+    io.line(io.warn, coverageRoots.ask);
+    if (coverageRoots.nextAction) io.line(' ', `Next: ${coverageRoots.nextAction}`);
+  }
+  const rulesUnderContract = advisories?.rulesUnderContract;
+  const arkRulesLines = formatArkRulesDoctorLines(rulesUnderContract);
+  if (arkRulesLines.length > 0) {
+    console.log('');
+    const mark = arkRulesDoctorMark(rulesUnderContract, io.warn);
+    for (const text of arkRulesLines) io.line(mark, text);
+  }
   const arkRun = advisories?.arkRun;
   if (arkRun?.active === true && arkRun.notAScore === true) {
     console.log('');
     const residual = Number(arkRun.residual?.count) || 0;
-    io.line(residual > 0 ? io.warn : ' ', `ArkRun: ${arkRun.mode || 'on'} · residual=${residual} · not a score`);
+    const mark = residual > 0 ? io.warn : ' ';
+    io.line(mark, ARKRUN_ONE_BREATH);
+    io.line(mark, `ArkRun: ${arkRun.mode || 'on'} · residual=${residual} · not a score`);
+    if (residual > 0) io.line(mark, ARKRUN_FIRST_CONTACT_NEXT);
   }
   const arkOrder = advisories?.arkOrder;
   if (arkOrder && arkOrder.notAScore === true) {
@@ -127,16 +202,36 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     root,
     decisionMemory
   );
-  // Prefer architecture facts paths when available; coverage I/O still walks test roots.
+  // Prefer architecture facts paths when available; still union the doctor walk
+  // so an empty-catalog residual can see Domain files the facts subset missed.
+  const normalizeDoctorFile = (entry) => {
+    const raw =
+      typeof entry === 'string'
+        ? entry
+        : typeof entry?.path === 'string'
+          ? entry.path
+          : '';
+    const path = raw.replace(/\\/g, '/').replace(/^\.\//, '');
+    return path ? { path } : null;
+  };
+  const walkFiles = Array.isArray(files) ? files.map(normalizeDoctorFile).filter(Boolean) : [];
+  const factFiles = Array.isArray(facts?.files)
+    ? facts.files.map(normalizeDoctorFile).filter(Boolean)
+    : [];
+  const seen = new Set();
+  const mergedFiles = [];
+  for (const entry of [...factFiles, ...walkFiles]) {
+    if (seen.has(entry.path)) continue;
+    seen.add(entry.path);
+    mergedFiles.push(entry);
+  }
   const factPaths =
-    facts ??
-    (Array.isArray(files)
+    facts || walkFiles.length > 0
       ? {
-          files: files.map((f) => ({
-            path: typeof f === 'string' ? f.replace(/\\/g, '/').replace(/^\.\//, '') : f?.path,
-          })).filter((f) => f.path),
+          ...(facts && typeof facts === 'object' ? facts : {}),
+          files: mergedFiles,
         }
-      : undefined);
+      : undefined;
   const classification = classificationFromCoverage(cov);
   const rulesUnderContract = summarizeRulesUnderContract(root, config, factPaths, classification);
   const { arkRun, arkOrder } = attachExtraDoctorSections(
@@ -145,7 +240,14 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     classification,
     activeViolations
   );
+  const prototypeShortcuts = collectPrototypeShortcutsResidual({
+    root,
+    config,
+    coverage: cov,
+    files,
+  });
   return {
+    ...(prototypeShortcuts ? { prototypeShortcuts } : {}),
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
     physicalCohesion,
@@ -179,6 +281,14 @@ export function printDoctorAdvisories(advisories, io) {
     io.line(io.warn, nudge.ask);
     if (nudge.nextAction) io.line(' ', io.color.dim(`Next: ${nudge.nextAction}`));
   }
+  const rulesUnderContract = advisories.rulesUnderContract;
+  const arkRulesLines = formatArkRulesDoctorLines(rulesUnderContract);
+  if (arkRulesLines.length > 0) {
+    console.log('');
+    console.log(io.color.bold('ArkRules (not a score)'));
+    const mark = arkRulesDoctorMark(rulesUnderContract, io.warn);
+    for (const text of arkRulesLines) io.line(mark, text);
+  }
   const arkRun = advisories.arkRun;
   if (arkRun && arkRun.notAScore === true) {
     console.log('');