arkgate 4.8.14 → 4.8.16

package/bin/lib/enforcement-honesty.mjs

@@ -180,6 +180,8 @@ export function buildBaselineHonesty(input = {}) {
  *   packagePinAbsent?: boolean,
  *   selfHost?: boolean,
  *   motherCli?: boolean,
+ *   nativeFailClosed?: boolean | null,
+ *   nativeFailClosedPolicy?: 'required' | 'unsupported' | 'none',
  * }} [extras]
  */
 export function buildWritePathHonesty(activeHost, hardWriteActive = false, extras = {}) {
@@ -202,7 +204,21 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
   const hardAllowed = packageInstalled && !pinAbsentForUser;
   const effectiveHard =
     Boolean(hardWriteActive) && hardCapable && !softWriteHost && hardAllowed;
-  const message = doctorWritePathHonestyMessage(host, effectiveHard);
+  const nativeFailClosedPolicy =
+    extras.nativeFailClosedPolicy === 'required' ||
+    extras.nativeFailClosedPolicy === 'none' ||
+    extras.nativeFailClosedPolicy === 'unsupported'
+      ? extras.nativeFailClosedPolicy
+      : HOST_SUPPORT_MATRIX[host]?.nativeFailClosed ?? (hardCapable ? 'unsupported' : 'none');
+  const nativeFailClosed =
+    extras.nativeFailClosed === true ? true : extras.nativeFailClosed === false ? false : null;
+  const failOpen = nativeFailClosedPolicy === 'required' && nativeFailClosed === false;
+  const honestyMessage = doctorWritePathHonestyMessage(host, effectiveHard);
+  const failOpenMessage =
+    `${HOST_SUPPORT_MATRIX[host]?.label ?? 'This host'}: the write hook is fail-open. ` +
+    'If the checker cannot run, the write still lands. Set failClosed: true on the write hook — ' +
+    'same idea as a file permission: no checker, no write. Required CI is the shared merge line.';
+  const message = failOpen ? failOpenMessage : honestyMessage;
 
   /** @type {Record<string, unknown>} */
   const out = {
@@ -212,6 +228,8 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
     hardWriteSupported: hardCapable,
     hardWriteActive: effectiveHard,
     hardWriteUnverified: hardCapable && !effectiveHard,
+    nativeFailClosed,
+    nativeFailClosedPolicy,
     hardMergeBoundary:
       'required-github-status-context (CLI: arkgate-check --strict-merge / ark-check --strict-merge)',
     packageInstalled,
@@ -385,6 +403,16 @@ export function buildProductHonesty(input = {}) {
     });
   }
 
+  if (write?.nativeFailClosed === false && write?.nativeFailClosedPolicy === 'required') {
+    reasons.push({
+      id: 'native-fail-open',
+      bucket: 'environment',
+      message:
+        write.message ||
+        'The write hook is fail-open. If the checker cannot run, the write still lands. Set failClosed: true on the write hook.',
+    });
+  }
+
   const adopted =
     typeof input.adopted === 'string'
       ? input.adopted
@@ -442,7 +470,7 @@ export function buildProductHonesty(input = {}) {
   }
 
   // EH05: environment residual deny-list (future reason ids stay architecture debt by default).
-  const ENVIRONMENT_REASON_IDS = new Set(['soft-write-host']);
+  const ENVIRONMENT_REASON_IDS = new Set(['soft-write-host', 'native-fail-open']);
 
   const environmentResiduals = reasons.filter((r) => ENVIRONMENT_REASON_IDS.has(r.id));
   const architectureReasons = reasons.filter((r) => !ENVIRONMENT_REASON_IDS.has(r.id));
@@ -457,6 +485,8 @@ export function buildProductHonesty(input = {}) {
 
   const softWriteOnly =
     !unfinished && environmentResiduals.some((r) => r.id === 'soft-write-host');
+  const failOpenOnly =
+    !unfinished && environmentResiduals.some((r) => r.id === 'native-fail-open');
   const hostLabel = (() => {
     const h = typeof write?.activeHost === 'string' ? write.activeHost.trim().toLowerCase() : '';
     if (h === 'codex') return 'Codex';
@@ -493,6 +523,10 @@ export function buildProductHonesty(input = {}) {
       'This tree acked advisory-only in .ark/adoption-stance.json. That is not a required GitHub merge status.';
   } else if (softWriteOnly) {
     primaryMessage = `${hostLabel} local writes stay advisory/bypassable; architecture contract on this slice is ready. Hard merge boundary is a required GitHub status context running arkgate-check --strict-merge (alias ark-check --strict-merge).`;
+  } else if (failOpenOnly) {
+    primaryMessage =
+      write?.message ||
+      `${hostLabel} write hook is fail-open — if the checker cannot run, the write still lands. Set failClosed: true. Required CI is the shared merge line.`;
   } else if (wholeTreeGoverned) {
     primaryMessage =
       'No residual honesty blockers on this slice — still not a numeric architecture score; re-doctor after material change.';
@@ -509,6 +543,10 @@ export function buildProductHonesty(input = {}) {
     headline = wholeTreeGoverned
       ? `Architecture contract ready; ${hostLabel} local writes are advisory`
       : `Contract residual clear; ${hostLabel} local writes are advisory`;
+  } else if (!unfinished && failOpenOnly) {
+    headline = wholeTreeGoverned
+      ? `Architecture contract ready; ${hostLabel} write hook is fail-open`
+      : `Contract residual clear; ${hostLabel} write hook is fail-open`;
   } else if (!unfinished && adopted === 'advisory-only-acked') {
     headline = 'Advisory-only adoption — merge status is not required';
   } else if (!unfinished) {
@@ -536,6 +574,9 @@ export function buildProductHonesty(input = {}) {
     primaryNextAction =
       input.stewardNudge?.nextAction ||
       '/ark-adopt (ask, then update stewards[] — do not invent names)';
+  } else if (!primaryNextAction && failOpenOnly) {
+    primaryNextAction =
+      'Set failClosed: true on the write hook, then re-run doctor. Required CI is the shared merge line.';
   } else if (!primaryNextAction && softWriteOnly) {
     primaryNextAction =
       'Confirm the GitHub required status context name runs arkgate-check --strict-merge (or ark-check --strict-merge). Soft-write hosts stay advisory at local write; the required status is the hard merge boundary.';
@@ -613,6 +654,8 @@ export function computeDoctorEnforcementHonesty({
   adoptionStance,
   emptyStewards,
   stewardNudge,
+  nativeFailClosed,
+  nativeFailClosedPolicy,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -632,6 +675,8 @@ export function computeDoctorEnforcementHonesty({
     packagePinAbsent: packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT',
     selfHost,
     motherCli,
+    nativeFailClosed,
+    nativeFailClosedPolicy,
   });
   // Prefer explicit blocking count; fall back to activeViolations only when callers
   // already pass blocking-only totals (legacy tests). Type-only must not invent debt.

package/bin/lib/field-install.mjs

@@ -83,6 +83,37 @@ function addDevDependencyPreservingFormat(source, version) {
   return `${source.slice(0, contentEnd)}${addition}${eol}${rootClosingIndent}${source.slice(rootClose)}`;
 }
 
+function replaceArkgateDependencyPreservingFormat(source, version) {
+  const encoded = JSON.stringify(version);
+  const next = source.replace(/("arkgate"\s*:\s*)(?:"(?:\\.|[^"\\])*")/, `$1${encoded}`);
+  if (next === source) {
+    throw new Error('arkgate pin not found in package.json');
+  }
+  return next;
+}
+
+/** True when a caret/tilde/exact pin is an older semver than the CLI. Non-semver stays. */
+function pinCoreIsBehind(declaredPin, cliVersion) {
+  const pinCore = String(declaredPin).replace(/^[\^~>=<\s]+/, '').split(/\s+/)[0];
+  const pinParts = pinCore.split('.').map((p) => Number.parseInt(p, 10));
+  const cliParts = String(cliVersion).split('.').map((p) => Number.parseInt(p, 10));
+  if (
+    pinParts.length < 1 ||
+    cliParts.length < 1 ||
+    !pinParts.every((n) => Number.isFinite(n)) ||
+    !cliParts.every((n) => Number.isFinite(n))
+  ) {
+    return false;
+  }
+  for (let i = 0; i < 3; i += 1) {
+    const p = pinParts[i] ?? 0;
+    const c = cliParts[i] ?? 0;
+    if (p < c) return true;
+    if (p > c) return false;
+  }
+  return false;
+}
+
 const ARK_CHECK_BIN_RE = /\b(?:ark-check|arkgate-check)(?:\.mjs|\.js)?\b/;
 const ARK_CHECK_RUNNER_RE =
   /(?:^|[\s"'`;|&])(?:npx|pnpm|yarn|npm|bunx?|node)(?:\s|$)/;
@@ -379,13 +410,6 @@ export function pinArkgateDevDependency(root, opts = {}) {
   }
   const deps = pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : {};
   const dev = pkg.devDependencies && typeof pkg.devDependencies === 'object' ? pkg.devDependencies : {};
-  if (typeof deps.arkgate === 'string' || typeof dev.arkgate === 'string') {
-    return {
-      changed: false,
-      reason: 'already-present',
-      version: deps.arkgate || dev.arkgate,
-    };
-  }
   const shipped = arkPackageVersion();
   const version =
     typeof opts.version === 'string' && opts.version
@@ -393,6 +417,22 @@ export function pinArkgateDevDependency(root, opts = {}) {
       : shipped
         ? `^${shipped}`
         : 'latest';
+  if (typeof deps.arkgate === 'string' || typeof dev.arkgate === 'string') {
+    const current = deps.arkgate || dev.arkgate;
+    const shouldBump =
+      opts.force === true || (Boolean(shipped) && pinCoreIsBehind(current, shipped));
+    if (!shouldBump || current === version) {
+      return {
+        changed: false,
+        reason: 'already-present',
+        version: current,
+      };
+    }
+    if (opts.write !== false) {
+      fs.writeFileSync(pkgPath, replaceArkgateDependencyPreservingFormat(source, version));
+    }
+    return { changed: true, reason: 'bumped', version };
+  }
   if (opts.write !== false) {
     fs.writeFileSync(pkgPath, addDevDependencyPreservingFormat(source, version));
   }

package/bin/lib/first-run-help.mjs

@@ -11,7 +11,9 @@ ${NORTH_STAR_ONE_LINE}
 
   arkgate start              preview (no writes)
   arkgate start --apply      write host + CI setup
+                             (refuses weak coverage/shape; lock with --archetype/--preset/--force)
   arkgate-check --doctor     status — one next step
+                             (if missing: npx --package=arkgate arkgate-check --doctor)
 
 Stuck? Run status (--doctor). Do #1.
 `;
@@ -167,6 +169,7 @@ export function checkUsage() {
     NORTH_STAR_ONE_LINE,
     '',
     '  arkgate-check --doctor         where you are: one status light, one next action',
+    '  arkgate-check --local --base <ref>      optional local / multi-worktree cheap check',
     '  arkgate-check --changed --base <ref>   local / pre-push: checks touched files only',
     '  arkgate-check --strict-merge   CI / merge gate (required GitHub status)',
     '  arkgate-check --sensors        which sensors can ever be enforced (does not run analysis)',
@@ -183,7 +186,7 @@ export function checkUsageAll() {
     '',
     'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
     '       arkgate-check --version',
-    '       arkgate-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       arkgate-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--local] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       ark-check --doctor [--json] [--all] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  compact first screen; --all prints Details; resident JSON falls back cold',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
@@ -225,6 +228,9 @@ export function checkUsageAll() {
     '',
     'Team parliament: law files (ark.config / arkrules / .ark-baseline.json) cannot ship in',
     'the same diff as product source. --changed --base <ref> checks touched files only.',
+    '--local (or ARK_CHECK_LOCAL=1) is the same cheap path: it turns on --changed and',
+    'stays per worktree root. It cannot combine with --strict-merge. Write hooks stay',
+    'on the lexical snippet path; they do not run a full-tree check.',
     '--against <ref> ratchets new keys vs that ref\'s baseline. --contract-session is a',
     'steward law-only PR. Loosen / baseline-grow need stewards[] + --author when set.',
     '',
@@ -279,6 +285,8 @@ export function checkUsageAll() {
     '--require-gates implies --strict-config and fails when the Ark contract in AGENTS.md,',
     'the project-rooted Ark server in .mcp.json, or fail-closed CI is missing/invalid.',
     'Included but unclassified source files therefore stay red instead of false-green.',
+    'If gates are required and there is no short decision note yet, it points at docs/adr/',
+    '(or docs/decisions/) — a hint, not a fail. Off without --require-gates.',
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok, antigravity',

package/bin/lib/host-support-matrix.mjs

@@ -35,6 +35,11 @@ function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, re
       'repair-envelope-emitted': repairEnvelopeEmitted,
       'repair-reinjection-guaranteed': repairReinjectionGuaranteed,
     }),
+    // Host-native "deny when the checker cannot run" flag (FS-permission analog).
+    // required = schema field must be true for hard-write evidence (Cursor failClosed).
+    // unsupported = host has no documented flag; hook-crash behavior is host-owned.
+    // none = advisory host; no local write block.
+    nativeFailClosed: extras.nativeFailClosed ?? (hardWrite ? 'unsupported' : 'none'),
     // EH07 minimum ops matrix (hard=false for soft hosts on every listed op).
     operationCoverage: Object.freeze(
       extras.operationCoverage ||
@@ -83,6 +88,7 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
     false,
     {
       repairEnvelopeEmitted: true,
+      nativeFailClosed: 'required',
       operationCoverage: {
         Write: true,
         StrReplace: true,
@@ -186,7 +192,9 @@ ${rows}
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
 Codex hard write covers only a complete local \`apply_patch\`; Cursor covers only listed
-\`preToolUse\` ops. In both cases the project hook must be installed + trusted, while shell/direct
+\`preToolUse\` ops with \`failClosed: true\`. A Cursor hook without that flag is fail-open
+(if the checker cannot run, the write still lands). In both cases the project hook must be
+installed + trusted, while shell/direct
 filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;

package/bin/lib/html-report-depth.mjs

@@ -127,6 +127,8 @@ export function buildReportDepthPayload(
     selfHost:
       packageVersionTruth?.selfHost === true ||
       packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
+    nativeFailClosed: writePath?.nativeFailClosed,
+    nativeFailClosedPolicy: writePath?.nativeFailClosedPolicy,
   });
   const classification = {
     governedPercent: coverage?.governed?.percent ?? null,

package/bin/lib/html-report.mjs

@@ -25,7 +25,7 @@ import { capabilityBadgesFor, renderAdvisorySections } from './html-report-advis
 import { renderEvolutionSection } from './html-report-evolution.mjs';
 import { arkGitignoreAppendDecision } from './ark-gitignore.mjs';
 import { captureGitSnapshot } from './report-snapshot-context.mjs';
-import { layerDescriptionCaption } from './layer-description.mjs';
+import { layerDescriptionCaption, layerGuidanceLine, layerOwners, layerTrustBoundary } from './layer-description.mjs';
 
 export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
@@ -423,8 +423,13 @@ export function renderBeginnerHtmlReport({ root, config, violations, ok, version
   const placementRows = layers
     .map((layer) => {
       const purpose = layerDescriptionCaption(layer) || 'See ark.config.json';
+      const guidance = layerGuidanceLine(layer);
+      const extra = guidance && guidance !== purpose ? guidance.slice(purpose.length).replace(/^ · /, '') : '';
+      const purposeCell = extra
+        ? `${esc(purpose)} <span class="tag">${esc(extra)}</span>`
+        : esc(purpose);
       const folders = (layer.patterns || []).join(', ') || '—';
-      return `<tr><td><strong>${esc(layer.name)}</strong></td><td>${esc(purpose)}</td><td><code>${esc(folders)}</code></td></tr>`;
+      return `<tr><td><strong>${esc(layer.name)}</strong></td><td>${purposeCell}</td><td><code>${esc(folders)}</code></td></tr>`;
     })
     .join('\n');
 
@@ -776,6 +781,12 @@ export function renderHtmlReport({
           ? `<span class="tag">${layer.intentPrefixes.map(esc).join(' ')}</span>`
           : '',
         layer.optional ? '<span class="tag dim-tag">optional</span>' : '',
+        layerTrustBoundary(layer)
+          ? `<span class="tag">trust: ${esc(layerTrustBoundary(layer))}</span>`
+          : '',
+        layerOwners(layer)
+          ? `<span class="tag">owner: ${esc(layerOwners(layer).map((id) => (id.includes('@') ? id : `@${id}`)).join(', '))}</span>`
+          : '',
       ].join(' ');
       const example = exampleByLayer?.get?.(layer.name);
       const files = counts.get(layer.name) || 0;

package/bin/lib/import-resolve.mjs

@@ -4,7 +4,46 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { layerForFile } from '../ark-layer-match.mjs';
+import {
+  layerForRelativePath,
+  matchingLayersForRelativePath,
+} from '../ark-layer-match.mjs';
+
+/**
+ * Same candidate list as ark-check `resolveSpecifier` (src/kernel/moduleGraph.ts).
+ * The write hook must feed `layerForRelativePath` a path with the extension
+ * ark-check already sees on disk — otherwise an explicit `money.ts` pattern
+ * loses to a broader `src/lib/**` bag.
+ */
+const SPECIFIER_SUFFIXES = Object.freeze([
+  '',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+  '/index.ts',
+  '/index.tsx',
+]);
+
+const SOURCE_EXT = /\.(?:[cm]?[jt]sx?)$/i;
+
+function posixRel(value) {
+  return String(value).split(/[/\\]/).join('/');
+}
+
+function specifierRelCandidates(rel) {
+  const base = posixRel(rel);
+  if (SOURCE_EXT.test(base)) return [base];
+  return SPECIFIER_SUFFIXES.map((suffix) => `${base}${suffix}`);
+}
+
+function isOnDiskFile(root, rel) {
+  try {
+    return fs.statSync(path.join(root, rel)).isFile();
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Read tsconfig path aliases via the TypeScript config parser (JSONC + extends).
@@ -86,16 +125,38 @@ function filePathToRel(filePath, root) {
   return relative.split(path.sep).join('/');
 }
 
+/**
+ * Classify a specifier-relative path with the same specificity scorer as ark-check.
+ * Prefer an on-disk candidate; otherwise pick the candidate whose winning
+ * `layerForRelativePath` pattern scores highest (explicit file beats `src/lib/**`).
+ */
 function classifyProbe(root, rel, layers) {
-  let probe = rel;
-  try {
-    if (fs.statSync(path.join(root, rel)).isDirectory()) probe = `${rel}/index.ts`;
-  } catch {
-    /* not on disk */
+  const candidates = specifierRelCandidates(rel);
+  const existing = candidates.find((candidate) => isOnDiskFile(root, candidate));
+  if (existing) {
+    return {
+      relPath: existing,
+      layer: layerForRelativePath(existing, layers),
+      onDisk: true,
+    };
   }
-  return (
-    layerForFile(root, probe, layers) || layerForFile(root, `${rel}/index.ts`, layers)
-  );
+  let bestRel = posixRel(rel);
+  let bestLayer;
+  let bestScore = -1;
+  for (const candidate of candidates) {
+    const layer = layerForRelativePath(candidate, layers);
+    if (!layer) continue;
+    const hit = matchingLayersForRelativePath(candidate, layers).find(
+      (row) => row.layer === layer
+    );
+    const score = hit?.score ?? -1;
+    if (score > bestScore) {
+      bestScore = score;
+      bestLayer = layer;
+      bestRel = candidate;
+    }
+  }
+  return { relPath: bestRel, layer: bestLayer, onDisk: false };
 }
 
 /**
@@ -114,7 +175,7 @@ export function createImportTargetResolver(ts, root, config) {
     if (path.isAbsolute(specifierOrFilePath)) {
       const relPath = filePathToRel(specifierOrFilePath, root);
       if (!relPath) return undefined;
-      return { relPath, layer: classifyProbe(root, relPath, layers) };
+      return classifyProbe(root, relPath, layers);
     }
 
     // Relative or path-alias import
@@ -130,7 +191,7 @@ export function createImportTargetResolver(ts, root, config) {
         tsAliases
       );
       if (!rel) return undefined;
-      return { relPath: rel, layer: classifyProbe(root, rel, layers) };
+      return classifyProbe(root, rel, layers);
     }
 
     // Try as import alias / bare package first
@@ -141,13 +202,13 @@ export function createImportTargetResolver(ts, root, config) {
       tsAliases
     );
     if (asImport) {
-      return { relPath: asImport, layer: classifyProbe(root, asImport, layers) };
+      return classifyProbe(root, asImport, layers);
     }
 
     // Repo-relative source file path (not an import specifier)
     const asFile = filePathToRel(specifierOrFilePath, root);
     if (asFile) {
-      return { relPath: asFile, layer: classifyProbe(root, asFile, layers) };
+      return classifyProbe(root, asFile, layers);
     }
 
     return undefined;

package/bin/lib/improvement-compass-doctor.mjs

@@ -42,7 +42,14 @@ export function buildDoctorImprovementCompass(input = {}) {
     if (id.includes('PEER_ISOLATION')) peerIsolationCount += 1;
     if (id === 'CAPABILITY_VIOLATION') pureOrCapabilityResidual += 1;
     if (id === 'FORBIDDEN_GLOBAL' || id.startsWith('FORBIDDEN_')) forbiddenGlobalResidual += 1;
-    if (id.startsWith('ARKRULE_') || id === 'INVARIANT_UNCOVERED') arkRulesStructureResidual += 1;
+    if (
+      id.startsWith('ARKRULE_') ||
+      id === 'INVARIANT_UNCOVERED' ||
+      id === 'INVARIANT_CATALOG_EMPTY' ||
+      id === 'INVARIANT_TESTS_PATH_MISSING' ||
+      id === 'INVARIANT_COVERAGE_ROOTS_MISSING'
+    )
+      arkRulesStructureResidual += 1;
   }
 
   const pcFindings = input.physicalCohesion?.findings;

package/bin/lib/improvement-compass-map.mjs

@@ -260,7 +260,11 @@ function mapViolations(byId, violations) {
             });
             continue;
         }
-        if (upper.startsWith('ARKRULE_') || upper === 'INVARIANT_UNCOVERED') {
+        if (upper.startsWith('ARKRULE_') ||
+            upper === 'INVARIANT_UNCOVERED' ||
+            upper === 'INVARIANT_CATALOG_EMPTY' ||
+            upper === 'INVARIANT_TESTS_PATH_MISSING' ||
+            upper === 'INVARIANT_COVERAGE_ROOTS_MISSING') {
             attach('encapsulation', 'ArkRules structure / invariant residual inside a layer.', {
                 kind: 'skill',
                 ref: '/ark-autopilot',

package/bin/lib/invariant-coverage.mjs

@@ -8,6 +8,12 @@
  * Pure CLI helper (bin/lib/invariant-coverage.mjs). Zero Node I/O.
  */
 
+/** Adopted + catalogued invariants, but no declared tests path (P2 §10). */
+export const INVARIANT_TESTS_PATH_RULE_ID = 'INVARIANT_TESTS_PATH_MISSING';
+export const INVARIANT_TESTS_PATH_MESSAGE = 'This project is adopted and has domain invariants, but ark.config.json does not name a real tests path. Add coverage.testGlobs or coverage.coverageRoots pointing at the folder where those tests live, then re-run. Without that path, coverage is an empty checkbox.';
+/** Enforced invariant, but no declared runner roots (P2 §10 residual). */
+export const INVARIANT_COVERAGE_ROOTS_RULE_ID = 'INVARIANT_COVERAGE_ROOTS_MISSING';
+export const INVARIANT_COVERAGE_ROOTS_MESSAGE = 'A domain invariant is enforced, but ark.config.json does not name coverage.coverageRoots — the folders where this project\'s test runner actually goes. Add coverage.coverageRoots pointing at that folder, then re-run. Without it, coverage can certify a test no runner runs.';
 /**
  * Human-readable discard tail. Empty when the scan discarded nothing.
  * `omitBudget` drops the budget clause and the load totals for messages whose
@@ -149,6 +155,7 @@ export function evaluateInvariantCoverage(input) {
             description: inv.description,
             ...(testEvidenceFile !== undefined ? { testEvidenceFile } : {}),
             ...(outsideDeclaredRoots !== undefined ? { outsideDeclaredRoots } : {}),
+            coverageRootsDeclared: rootsDeclared,
         });
         // The covering test exists but sits outside the roots the project declared
         // its runner walks. ArkGate does not execute tests, so it cannot tell the
@@ -233,5 +240,119 @@ export function canPromoteInvariant(coverage) {
             reason: `Invariant ${coverage.invariantId} is covered only by ${coverage.testEvidenceFile ?? 'a test'}, outside the declared coverage roots; ArkGate cannot tell whether that test runs, so it will not promote on it.`,
         };
     }
+    // Explicit false only: hand-built evidence may omit the field. The evaluator
+    // always sets it. Promoting without roots would make OUTSIDE_ROOTS silent.
+    if (coverage.coverageRootsDeclared === false) {
+        return {
+            ok: false,
+            reason: `Declare coverage.coverageRoots in ark.config.json before promoting ${coverage.invariantId} to enforced. Without that, ArkGate cannot tell whether a covering test is one the runner executes.`,
+        };
+    }
     return { ok: true, reason: `Invariant ${coverage.invariantId} has coverage evidence.` };
 }
+function nonEmptyPathStrings(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== 'string')
+            continue;
+        const trimmed = item.trim();
+        if (trimmed.length > 0)
+            out.push(trimmed);
+    }
+    return out;
+}
+/**
+ * Declared tests homes: `coverage.testGlobs` and/or `coverage.coverageRoots`.
+ * Either is a configured path. Empty strings do not count.
+ */
+export function configuredInvariantTestsPaths(coverage) {
+    if (!coverage || typeof coverage !== 'object')
+        return [];
+    return [...nonEmptyPathStrings(coverage.testGlobs), ...nonEmptyPathStrings(coverage.coverageRoots)];
+}
+export function hasConfiguredInvariantTestsPath(coverage) {
+    return configuredInvariantTestsPaths(coverage).length > 0;
+}
+/**
+ * True when at least one catalogued invariant wants test evidence.
+ * Same default as AR10: `coverage.test !== false`. `test: false` is an explicit
+ * opt-out (starter Domain phrases use it) and does not demand a tests path.
+ */
+export function catalogDemandsInvariantTestsPath(invariants) {
+    if (!Array.isArray(invariants) || invariants.length === 0)
+        return false;
+    return invariants.some((inv) => inv != null && inv.coverage?.test !== false);
+}
+/**
+ * §10 — adopted + invariants that want tests require a real tests path.
+ * Fail-closed. Not freezable. Silent when not adopted, the catalog is empty,
+ * or every entry sets `coverage.test: false`.
+ */
+export function collectMissingInvariantTestsPathFindings(input) {
+    const demanded = input.hasDomainInvariants === true ||
+        (input.hasDomainInvariants !== false && catalogDemandsInvariantTestsPath(input.invariants));
+    if (input.adopted !== true || !demanded)
+        return [];
+    const configured = hasConfiguredInvariantTestsPath(input.coverage);
+    if (configured && input.declaredPathPresent !== false)
+        return [];
+    return [
+        {
+            ruleId: INVARIANT_TESTS_PATH_RULE_ID,
+            message: INVARIANT_TESTS_PATH_MESSAGE,
+            file: 'ark.config.json',
+            line: 1,
+            severity: 'error',
+            failsStrict: true,
+            freezable: false,
+        },
+    ];
+}
+/**
+ * Declared runner homes: `coverage.coverageRoots` only.
+ * Empty strings do not count. testGlobs is not a runner root.
+ */
+export function configuredCoverageRoots(coverage) {
+    if (!coverage || typeof coverage !== 'object')
+        return [];
+    return nonEmptyPathStrings(coverage.coverageRoots);
+}
+export function hasConfiguredCoverageRoots(coverage) {
+    return configuredCoverageRoots(coverage).length > 0;
+}
+/**
+ * True when at least one catalogued invariant is `mode: "enforced"`.
+ * Structure-sensor enforced is not this — only `invariants[]`.
+ */
+export function catalogHasEnforcedInvariant(invariants) {
+    if (!Array.isArray(invariants) || invariants.length === 0)
+        return false;
+    return invariants.some((inv) => inv != null && inv.mode === 'enforced');
+}
+/**
+ * P2 §10 residual — any enforced invariant requires `coverage.coverageRoots`.
+ * Fail-closed. Not freezable. Silent when no invariant is enforced.
+ * testGlobs alone does not satisfy this: without roots, OUTSIDE_ROOTS cannot fire.
+ */
+export function collectMissingCoverageRootsFindings(input) {
+    const enforced = input.hasEnforcedInvariant === true ||
+        (input.hasEnforcedInvariant !== false && catalogHasEnforcedInvariant(input.invariants));
+    if (!enforced)
+        return [];
+    const configured = hasConfiguredCoverageRoots(input.coverage);
+    if (configured && input.declaredPathPresent !== false)
+        return [];
+    return [
+        {
+            ruleId: INVARIANT_COVERAGE_ROOTS_RULE_ID,
+            message: INVARIANT_COVERAGE_ROOTS_MESSAGE,
+            file: 'ark.config.json',
+            line: 1,
+            severity: 'error',
+            failsStrict: true,
+            freezable: false,
+        },
+    ];
+}