arkgate 4.8.14 → 4.8.15

package/bin/lib/doctor-next-actions.mjs

@@ -34,6 +34,9 @@ export function collectDoctorNextActions(ctx) {
   ) {
     actions.push(nudge.nextAction);
   }
+  if (ctx.layerOwners?.required && ctx.layerOwners.nextAction) {
+    actions.push(ctx.layerOwners.nextAction);
+  }
   const enforceEmptyPlan =
     ctx.operatingMode === 'enforce' && planAEmpty && gatesInstalled && !notAdopted;
   if (enforceEmptyPlan) {
@@ -42,6 +45,17 @@ export function collectDoctorNextActions(ctx) {
         '/ark-explore, then one small refactor with /ark-autopilot and your OK'
     );
   }
+  if (ctx.adrPresence?.missing && ctx.adrPresence.nextAction) {
+    actions.push(ctx.adrPresence.nextAction);
+  }
+  if (ctx.statusTransitionCatalog?.nextAction) {
+    actions.push(ctx.statusTransitionCatalog.nextAction);
+  } else if (ctx.statesTransitions?.nextAction) {
+    actions.push(ctx.statesTransitions.nextAction);
+  }
+  if (ctx.noDomainFrontend?.nextAction) {
+    actions.push(ctx.noDomainFrontend.nextAction);
+  }
   if (!ctx.analysisComplete) actions.push('restore complete analysis, then rerun ark-check --doctor');
   if (ctx.designSmells.length > 0 && ctx.postGreenPath) actions.push(ctx.postGreenPath.action);
   if (ctx.coverageHonesty.greenIsNotEnforcement && ctx.coverageHonesty.worseThanNoGate) {

package/bin/lib/doctor-plan.mjs

@@ -15,7 +15,12 @@ import { describePackageVersionDualTruth } from './field-install.mjs';
 import { detectAgentHomeGaps } from './agent-homes.mjs';
 import { collectDoctorNextActions } from './doctor-next-actions.mjs';
 import { printDoctorCompactHuman, printDoctorDetailsHuman } from './doctor-human.mjs';
-import { placementDescriptionFields } from './layer-description.mjs';
+import { collectLayerOwnerResidual, layerGuidanceLine, placementDescriptionFields } from './layer-description.mjs';
+import { collectAdrPresenceResidual, printAdrPresenceHint } from './adr-presence.mjs';
+import { collectStatesTransitionsResidual } from './states-transitions-presence.mjs';
+import { collectStatusTransitionCatalogResidual } from './status-transition-catalog.mjs';
+import { collectNoDomainFrontendResidual } from './no-domain-frontend.mjs';
+export { printAdrPresenceHint };
 export { printDoctorCompactHuman, printDoctorDetailsHuman };
 export { summarizeRulesUnderContract };
 
@@ -173,7 +178,8 @@ export function runCoverage(root, config, files, rules, asJson) {
   console.log(`  ${pad('Layer')}  Files`);
   for (const row of layerRows) {
     const flag = row.files === 0 ? '   (pattern matches nothing)' : '';
-    const caption = row.description ? `  ${row.description}` : '';
+    const guidance = layerGuidanceLine(row);
+    const caption = guidance ? `  ${guidance}` : '';
     console.log(`  ${pad(row.name)}  ${String(row.files).padStart(5)}${flag}${caption}`);
   }
   console.log(`  ${pad('(unclassified)')}  ${String(unclassified.length).padStart(5)}`);
@@ -616,6 +622,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     options.facts ?? options.architectureFacts,
     activeViolations
   );
+  const layerOwners = collectLayerOwnerResidual(config);
   const rulesUnderContract = doctorAdvisories.rulesUnderContract;
   const arkRun = doctorAdvisories.arkRun;
   // Single residual expression (nextPilot || extractionCard) — HTML report uses the same.
@@ -636,6 +643,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     github: githubForBoundary,
     ci: ciMergeBoundary?.ci,
   });
+  const adrPresence = collectAdrPresenceResidual({
+    root,
+    demanded: options.requireGates === true || adopted === 'required-merge',
+  });
+  const statesTransitions = collectStatesTransitionsResidual({ root });
+  const statusTransitionCatalog = collectStatusTransitionCatalogResidual({ root, config, files, statesTransitions });
+  const noDomainFrontend = collectNoDomainFrontendResidual({ config, coverage: cov, designSmells });
   const { coverageHonesty, baselineHonesty, writePathHonesty, productHonesty } =
     computeDoctorEnforcementHonesty({
       governedPercent: cov.governed.percent,
@@ -671,6 +685,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       selfHost:
         packageVersionTruth?.selfHost === true ||
         packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
+      nativeFailClosed: writePath.nativeFailClosed,
+      nativeFailClosedPolicy: writePath.nativeFailClosedPolicy,
       adopted,
       ciMergeBoundary,
       github: githubForBoundary,
@@ -763,6 +779,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             governed: cov.governed,
             coverageHonesty,
             layers: cov.layers,
+            ...(layerOwners ? { layerOwners } : {}),
+            ...(adrPresence ? { adrPresence } : {}),
+            ...(statesTransitions ? { statesTransitions } : {}),
+            ...(statusTransitionCatalog ? { statusTransitionCatalog } : {}), ...(noDomainFrontend ? { noDomainFrontend } : {}),
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
             ungovernedDirs: cov.suggestions.length,
@@ -827,6 +847,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               mcpPresent: writePath.mcpPresent,
               evidence: writePath.evidence,
               honesty: writePathHonesty,
+              nativeFailClosed: writePath.nativeFailClosed ?? null,
+              nativeFailClosedPolicy: writePath.nativeFailClosedPolicy ?? 'unsupported',
               ...(writePath.sessionNote ? { sessionNote: writePath.sessionNote } : {}),
               ...(writePath.gap
                 ? {
@@ -902,12 +924,20 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     operatingMode,
     adopted,
     stewardNudge: doctorAdvisories.stewardNudge,
+    layerOwners,
+    adrPresence,
+    statesTransitions,
+    statusTransitionCatalog, noDomainFrontend,
   });
   const humanView = {
     root,
     analysisComplete,
     completeness,
     doctorAdvisories,
+    layerOwners,
+    adrPresence,
+    statesTransitions,
+    statusTransitionCatalog, noDomainFrontend,
     operatingMode,
     designFitness,
     adopted,

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/first-run-help.mjs

@@ -11,6 +11,7 @@ ${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
 
 Stuck? Run status (--doctor). Do #1.
@@ -167,6 +168,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 +185,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 +227,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 +284,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,12 @@ 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'
+    )
+      arkRulesStructureResidual += 1;
   }
 
   const pcFindings = input.physicalCohesion?.findings;

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

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

package/bin/lib/layer-description.mjs

@@ -1,8 +1,12 @@
 /**
- * App-context caption from `layers[].description`.
+ * App-context caption, optional trust tag, and optional owners from layer metadata.
  * Metadata only — callers project it; policyHash strips it elsewhere.
- * Present non-empty string is returned; absence/empty/non-string is undefined.
- *
+ * Present values are returned; absence/empty/invalid is omitted.
+ */
+
+export const LAYER_TRUST_BOUNDARIES = Object.freeze(['public', 'auth', 'admin', 'internal']);
+
+/**
  * @param {{ description?: unknown } | null | undefined} layerOrPlacement
  * @returns {string | undefined}
  */
@@ -15,13 +19,91 @@ export function layerDescriptionCaption(layerOrPlacement) {
 }
 
 /**
- * Project the caption onto place / prepare-write / coverage / doctor JSON.
- * Absence omits the field (never empty string).
+ * @param {{ trustBoundary?: unknown } | null | undefined} layerOrPlacement
+ * @returns {'public' | 'auth' | 'admin' | 'internal' | undefined}
+ */
+export function layerTrustBoundary(layerOrPlacement) {
+  const tag =
+    layerOrPlacement && typeof layerOrPlacement === 'object'
+      ? layerOrPlacement.trustBoundary
+      : undefined;
+  return typeof tag === 'string' && LAYER_TRUST_BOUNDARIES.includes(tag) ? tag : undefined;
+}
+
+/**
+ * @param {{ owners?: unknown } | null | undefined} layerOrPlacement
+ * @returns {string[] | undefined}
+ */
+export function layerOwners(layerOrPlacement) {
+  const raw =
+    layerOrPlacement && typeof layerOrPlacement === 'object' ? layerOrPlacement.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;
+}
+
+function formatOwnerMention(id) {
+  return id.includes('@') ? id : `@${id}`;
+}
+
+/**
+ * One guidance fragment: caption and/or `trust: public` and/or `owner: @handle`.
+ * @param {{ description?: unknown, trustBoundary?: unknown, owners?: unknown } | null | undefined} layerOrPlacement
+ * @returns {string | undefined}
+ */
+export function layerGuidanceLine(layerOrPlacement) {
+  const caption = layerDescriptionCaption(layerOrPlacement);
+  const trust = layerTrustBoundary(layerOrPlacement);
+  const owners = layerOwners(layerOrPlacement);
+  const ownerBit = owners ? `owner: ${owners.map(formatOwnerMention).join(', ')}` : undefined;
+  const bits = [caption, trust ? `trust: ${trust}` : undefined, ownerBit].filter(Boolean);
+  return bits.length > 0 ? bits.join(' · ') : undefined;
+}
+
+/**
+ * Project caption + trust tag + owners onto place / prepare-write / coverage / doctor JSON.
+ * Absence omits the field (never empty string / empty array).
  *
- * @param {{ description?: unknown } | null | undefined} layerOrPlacement
- * @returns {{ description: string } | {}}
+ * @param {{ description?: unknown, trustBoundary?: unknown, owners?: unknown } | null | undefined} layerOrPlacement
+ * @returns {{ description?: string, trustBoundary?: string, owners?: string[] }}
  */
 export function placementDescriptionFields(layerOrPlacement) {
   const caption = layerDescriptionCaption(layerOrPlacement);
-  return caption ? { description: caption } : {};
+  const trust = layerTrustBoundary(layerOrPlacement);
+  const owners = layerOwners(layerOrPlacement);
+  return {
+    ...(caption ? { description: caption } : {}),
+    ...(trust ? { trustBoundary: trust } : {}),
+    ...(owners ? { owners } : {}),
+  };
+}
+
+/**
+ * Doctor residual when requireLayerOwners is on and a live house has no owners.
+ * Absent/false require → null (silent). Not a computeDoctorAdvisories key.
+ *
+ * @param {{ requireLayerOwners?: unknown, layers?: Array<{ name?: string, owners?: unknown, optional?: boolean, reserved?: boolean, allowEmpty?: boolean }> } | null | undefined} config
+ * @returns {{ required: true, missingLayers: string[], ask: string, nextAction: string } | null}
+ */
+export function collectLayerOwnerResidual(config) {
+  if (config?.requireLayerOwners !== true || !Array.isArray(config.layers)) return null;
+  const missing = config.layers
+    .filter(
+      (layer) =>
+        layer &&
+        layer.optional !== true &&
+        layer.reserved !== true &&
+        layer.allowEmpty !== true &&
+        !layerOwners(layer)
+    )
+    .map((layer) => layer.name)
+    .filter((name) => typeof name === 'string' && name.length > 0);
+  if (missing.length === 0) return null;
+  const named = missing[0];
+  return {
+    required: true,
+    missingLayers: missing,
+    ask: `${named} has no owner. Add a GitHub handle or email to layers[].owners.`,
+    nextAction: `Add a GitHub handle or email to ${named}'s owners in ark.config.json (/ark-adopt).`,
+  };
 }