arkgate 4.8.14 → 4.8.16

package/bin/lib/doctor-green-cite.mjs

@@ -0,0 +1,139 @@
+/**
+ * Golden rule: a doctor green / healthy claim must cite a file, config key,
+ * or test. Uncited greens are dishonest — demote or omit.
+ *
+ * Tooling only. Reuses existing doctor view fields (IT01 / ADR / CI
+ * residual shape). No new schema, RPC, or skill name.
+ */
+import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
+import { CI_MERGE_BOUNDARY_REL } from './ci-merge-boundary.mjs';
+
+export const HEALTHY_CLAIM = 'Healthy — nothing to do.';
+export const HEALTHY_KEEP = '  Keep write path + CI.';
+export const UNCITE_SUFFIX =
+  'not green until a file, config key, or test is named';
+
+const CONFIG_KEY_DOT = /^[A-Za-z_][\w]*\.[A-Za-z_][\w.]*$/;
+const CONFIG_KEY_BARE = new Set([
+  'include',
+  'exclude',
+  'layers',
+  'rules',
+  'arkRules',
+  'arkRun',
+  'arkOrder',
+  'coverage',
+  'stewards',
+  'schemaVersion',
+]);
+const FILE_LIKE =
+  /(?:^|\/)(?:\.[A-Za-z][\w.-]*|[A-Za-z][\w.-]*\.(?:json|ya?ml|md|ts|mjs|js|cjs))$|\/|[.](?:json|ya?ml|md|ts|mjs|js|cjs)$/;
+const TEST_LIKE = /(?:^|\/)tests?\/|(?:\.|\b)test\.(?:ts|mjs|js)\b/i;
+
+/**
+ * True when a stranger can open this in about a minute.
+ * Generic words ("CI", "gates") are not cites.
+ */
+export function isConcreteCite(value) {
+  if (typeof value !== 'string') return false;
+  const cite = value.trim();
+  if (cite.length < 3 || cite.length > 240) return false;
+  if (/\s/.test(cite)) return false;
+  if (cite === REQUIRED_GATE_WORKFLOW) return false;
+  return (
+    FILE_LIKE.test(cite) ||
+    TEST_LIKE.test(cite) ||
+    CONFIG_KEY_DOT.test(cite) ||
+    CONFIG_KEY_BARE.has(cite)
+  );
+}
+
+export function uniqueConcreteCites(cites) {
+  const out = [];
+  for (const raw of Array.isArray(cites) ? cites : [cites]) {
+    if (!isConcreteCite(raw)) continue;
+    const cite = String(raw).trim();
+    if (!out.includes(cite)) out.push(cite);
+  }
+  return out;
+}
+
+/**
+ * @returns {{ mark: 'ok', text: string } | { mark: 'warn', text: string }}
+ */
+export function citeOrDemoteGreen(claim, cites) {
+  const named = typeof claim === 'string' && claim.trim() ? claim.trim() : 'This claim';
+  const list = uniqueConcreteCites(cites);
+  if (list.length > 0) {
+    return { mark: 'ok', text: `${named} (${list.join(' · ')})` };
+  }
+  return { mark: 'warn', text: `${named} — ${UNCITE_SUFFIX}` };
+}
+
+export function citedGreen(line, marks, claim, cites) {
+  const row = citeOrDemoteGreen(claim, cites);
+  line(row.mark === 'ok' ? marks.ok : marks.warn, row.text);
+  return row;
+}
+
+/** Backing artifacts already on the doctor view — no second scan. */
+export function healthyCitesFromView(view) {
+  const cites = ['ark.config.json'];
+  if (view?.ciMergeBoundary) cites.push(CI_MERGE_BOUNDARY_REL);
+  const workflow =
+    view?.ciMergeBoundary?.ci?.workflowFile || view?.ciNotFailClosed?.workflowFile;
+  if (workflow) cites.push(workflow);
+  return uniqueConcreteCites(cites);
+}
+
+export function printHealthyHeadline(view, color) {
+  const row = citeOrDemoteGreen(HEALTHY_CLAIM, healthyCitesFromView(view));
+  if (row.mark === 'ok') {
+    console.log(color.green(`✔ ${row.text}`));
+    console.log(color.dim(HEALTHY_KEEP));
+    return row;
+  }
+  console.log(color.yellow(`! ${row.text}`));
+  return row;
+}
+
+export function displayedMissingGates(gatesMissing, view) {
+  const list = Array.isArray(gatesMissing) ? gatesMissing : [];
+  const hideGlob = Boolean(
+    view?.ciNotFailClosed?.workflowFile ||
+      view?.ciNotFailClosed?.error === 'ci-not-fail-closed' ||
+      view?.ciMergeBoundary?.ci?.workflowPresent
+  );
+  return hideGlob ? list.filter((item) => item !== REQUIRED_GATE_WORKFLOW) : list;
+}
+
+export function ciNotFailClosedNotice(view) {
+  const file = view?.ciNotFailClosed?.workflowFile;
+  if (!file) return null;
+  return `CI not fail-closed: ${file} — remove the skippable if:, or write .ark/adoption-stance.json with stance: advisory-only`;
+}
+
+export function ciMergeGreenCites(view) {
+  const cites = [];
+  if (view?.ciMergeBoundary) cites.push(CI_MERGE_BOUNDARY_REL);
+  const workflow = view?.ciMergeBoundary?.ci?.workflowFile || view?.ciNotFailClosed?.workflowFile;
+  if (workflow) cites.push(workflow);
+  return uniqueConcreteCites(cites);
+}
+
+export function foundGateCites(view) {
+  const cites = ['AGENTS.md'];
+  if (view?.ciMergeBoundary) cites.push(CI_MERGE_BOUNDARY_REL);
+  const workflow = view?.ciMergeBoundary?.ci?.workflowFile;
+  if (workflow) cites.push(workflow);
+  return uniqueConcreteCites(cites);
+}
+
+export function writePathGreenCites(writePath) {
+  return uniqueConcreteCites([
+    ...(Array.isArray(writePath?.capabilityEvidence?.['hard-write'])
+      ? writePath.capabilityEvidence['hard-write']
+      : []),
+    ...(Array.isArray(writePath?.evidence) ? writePath.evidence : []),
+  ]);
+}

package/bin/lib/doctor-human.mjs

@@ -13,23 +13,16 @@ import { enforcementDoctorLines } from './enforcement-state.mjs';
 import { analysisIncompleteStatement } from './analysis-completeness.mjs';
 import { skillGapsForActiveHost, detectCodexHomeGap, codexConcernIsActive } from './agent-gates.mjs';
 import { agentHomeConcernIsActive } from './agent-homes.mjs';
-import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
-
-function displayedMissingGates(gatesMissing, view) {
-  const list = Array.isArray(gatesMissing) ? gatesMissing : [];
-  const hideGlob = Boolean(
-    view?.ciNotFailClosed?.workflowFile ||
-      view?.ciNotFailClosed?.error === 'ci-not-fail-closed' ||
-      view?.ciMergeBoundary?.ci?.workflowPresent
-  );
-  return hideGlob ? list.filter((item) => item !== REQUIRED_GATE_WORKFLOW) : list;
-}
-
-function ciNotFailClosedNotice(view) {
-  const file = view?.ciNotFailClosed?.workflowFile;
-  if (!file) return null;
-  return `CI not fail-closed: ${file} — remove the skippable if:, or write .ark/adoption-stance.json with stance: advisory-only`;
-}
+import { layerGuidanceLine } from './layer-description.mjs';
+import {
+  citedGreen,
+  ciMergeGreenCites,
+  ciNotFailClosedNotice,
+  displayedMissingGates,
+  foundGateCites,
+  printHealthyHeadline,
+  writePathGreenCites,
+} from './doctor-green-cite.mjs';
 
 function lineWith(ok, warn, bad, color) {
   return (mark, text) => console.log(`  ${mark} ${text}`);
@@ -96,14 +89,13 @@ export function printDoctorCompactHuman(view) {
         : 'import rules check out. Keep host + CI.',
   };
   const modeTitle = operatingModeTitle(mode, designFitness.designWeak, stewardUnfinished);
-  line(
-    modeMark,
-    `${modeTitle} — ${
-      designFitness.designWeak
-        ? 'import rules check out; leftover design work remains.'
-        : modeHelp[mode]
-    }`
-  );
+  const modeClaim = `${modeTitle} — ${
+    designFitness.designWeak
+      ? 'import rules check out; leftover design work remains.'
+      : modeHelp[mode]
+  }`;
+  if (modeMark === ok) citedGreen(line, { ok, warn }, modeClaim, ['ark.config.json']);
+  else line(modeMark, modeClaim);
   if (emptyScope) {
     line(
       bad,
@@ -113,17 +105,18 @@ export function printDoctorCompactHuman(view) {
 
   console.log('');
   if (ciMergeBoundary?.ci?.state) {
-    line(
-      ciMergeBoundary.ci.state === 'required' ? ok : warn,
-      `CI merge: ${ciMergeBoundary.ci.state}`
-    );
+    const mergeClaim = `CI merge: ${ciMergeBoundary.ci.state}`;
+    if (ciMergeBoundary.ci.state === 'required') {
+      citedGreen(line, { ok, warn }, mergeClaim, ciMergeGreenCites(view));
+    } else {
+      line(warn, mergeClaim);
+    }
   }
   if (adopted === 'advisory-only-acked') {
     line(warn, 'Adoption: advisory-only ack — not a required GitHub status.');
   }
   if (isDoctorHealthyNothingToDo(designFitness, uniqueActions, adopted)) {
-    console.log(color.green('✔ Healthy — nothing to do.'));
-    console.log(color.dim('  Keep write path + CI.'));
+    printHealthyHeadline(view, color);
   } else {
     console.log(color.bold('Primary next action'));
     console.log(`  1. ${uniqueActions[0]}`);
@@ -131,21 +124,20 @@ export function printDoctorCompactHuman(view) {
 
   console.log('');
   console.log(color.bold('Coverage'));
-  const govMark =
-    emptyScope || cov.governed.percent < 50
-      ? bad
-      : cov.governed.percent >= 80
-        ? ok
-        : warn;
-  line(govMark, `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`);
+  const govClaim = `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`;
+  if (emptyScope || cov.governed.percent < 50) line(bad, govClaim);
+  else if (cov.governed.percent >= 80) citedGreen(line, { ok, warn }, govClaim, ['ark.config.json', 'include', 'layers']);
+  else line(warn, govClaim);
   for (const row of cov.layers ?? []) {
-    if (row.description) line(' ', `${row.name} — ${row.description}`);
+    const guidance = layerGuidanceLine(row);
+    if (guidance) line(' ', `${row.name} — ${guidance}`);
   }
 
   const hostRed =
     listedMissing.length > 0 ||
     Boolean(writePath.gap) ||
     writePathHonesty?.softWriteHost === true ||
+    writePathHonesty?.nativeFailClosed === false ||
     Boolean(skippableCi);
   if (hostRed) {
     console.log('');
@@ -153,7 +145,9 @@ export function printDoctorCompactHuman(view) {
     if (writePath.activeHost) line(' ', `Active host: ${writePath.activeHost}`);
     if (listedMissing.length > 0) line(bad, `Missing gates: ${listedMissing.join(', ')}`);
     if (skippableCi) line(warn, skippableCi);
-    else if (listedMissing.length === 0 && (writePath.gap || writePathHonesty?.softWriteHost)) {
+    else if (writePathHonesty?.nativeFailClosed === false) {
+      line(warn, writePathHonesty.message || 'Write hook is fail-open — if the checker cannot run, the write still lands.');
+    } else if (listedMissing.length === 0 && (writePath.gap || writePathHonesty?.softWriteHost)) {
       line(warn, 'Local writes are advisory; required CI is the merge boundary.');
     }
   }
@@ -165,7 +159,15 @@ export function printDoctorCompactHuman(view) {
     line(warn, nudge.ask);
   }
 
-  printCompactExtraDoctorLines(doctorAdvisories, { line, warn });
+  printCompactExtraDoctorLines(
+    {
+      ...doctorAdvisories,
+      layerOwners: view.layerOwners,
+      adrPresence: view.adrPresence,
+      statesTransitions: view.statesTransitions, statusTransitionCatalog: view.statusTransitionCatalog, noDomainFrontend: view.noDomainFrontend, invariantTestsPath: view.invariantTestsPath, invariantCoverageRoots: view.invariantCoverageRoots,
+    },
+    { line, warn }
+  );
 
   if (violations.length === 0) {
     if (!analysisComplete) {
@@ -248,12 +250,17 @@ export function printDoctorDetailsHuman(view) {
       `Dual-match: ${cov.dualMembership.count} file(s) match multiple layers — ${cov.dualMembership.note ?? 'review overlapping globs'}`
     );
   }
-  if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) line(ok, 'Every layer classifies files; no empty layers');
-  const captioned = (cov.layers ?? []).filter((row) => row.description);
+  if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) {
+    citedGreen(line, { ok, warn }, 'Every layer classifies files; no empty layers', [
+      'ark.config.json',
+      'layers',
+    ]);
+  }
+  const captioned = (cov.layers ?? []).filter((row) => layerGuidanceLine(row));
   if (captioned.length > 0) {
     console.log('');
     console.log(color.bold('Layers'));
-    for (const row of captioned) line(' ', `${row.name} — ${row.description}`);
+    for (const row of captioned) line(' ', `${row.name} — ${layerGuidanceLine(row)}`);
   }
 
   if (packageVersionTruth?.dualTruth) {
@@ -275,7 +282,8 @@ export function printDoctorDetailsHuman(view) {
   console.log('');
   console.log(color.bold('Design fitness'));
   if (designSmells.length === 0) {
-    line(analysisComplete ? ok : warn, designFitness.label);
+    if (analysisComplete) citedGreen(line, { ok, warn }, designFitness.label, ['ark.config.json']);
+    else line(warn, designFitness.label);
   } else {
     line(designFitness.designWeak ? warn : warn, designFitness.label);
     for (const smell of designSmells.slice(0, 5)) {
@@ -342,15 +350,16 @@ export function printDoctorDetailsHuman(view) {
     } else if (designFitness.designWeak) {
       line(warn, `None on checked imports — import rules match the config; leftover design work remains (${modeTitle}). Not healthy finished.`);
     } else {
-      line(ok, 'None — the code matches the contract on checked edges');
+      citedGreen(line, { ok, warn }, 'None — the code matches the contract on checked edges', [
+        'ark.config.json',
+      ]);
     }
   } else {
     const typeNote = summary.typeOnlyCount > 0 ? ` (${summary.valueCount} value · ${summary.typeOnlyCount} type-only)` : '';
     const supNote = suppressed > 0 ? `, ${suppressed} frozen` : '';
-    line(
-      activeCount > 0 ? warn : ok,
-      `${violations.length} total${typeNote}${supNote}${activeCount > 0 ? ` — ${activeCount} NOT baselined` : ''}`
-    );
+    const violClaim = `${violations.length} total${typeNote}${supNote}${activeCount > 0 ? ` — ${activeCount} NOT baselined` : ''}`;
+    if (activeCount > 0) line(warn, violClaim);
+    else citedGreen(line, { ok, warn }, violClaim, ['.ark-baseline.json']);
     for (const edge of summary.edges.slice(0, 3)) line(' ', color.dim(`${edge.count}  ${edge.edge}`));
     if (summary.concentrated && typeof summary.dominant === 'string' && summary.dominant.includes(' → ')) {
       line(warn, color.dim(`${Math.round(summary.dominantShare * 100)}% on one edge (${summary.dominant}) — likely a contract fix, not debt`));
@@ -374,7 +383,17 @@ export function printDoctorDetailsHuman(view) {
         : bad;
   line(' ', `Active host: ${writePath.activeHost}`);
   line(' ', `Supported profile: ${writePath.supportSummary}`);
-  line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
+  const modeLine = `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`;
+  if (wpMark === ok) {
+    citedGreen(
+      line,
+      { ok, warn },
+      modeLine,
+      writePathGreenCites(writePath)
+    );
+  } else {
+    line(wpMark, modeLine);
+  }
   if (writePathHonesty.message) line(warn, writePathHonesty.message);
   if (writePath.sessionNote) {
     line(warn, writePath.sessionNote);
@@ -384,14 +403,21 @@ export function printDoctorDetailsHuman(view) {
   const supportCaps = writePath.support?.capabilities || {};
   const repairReinjection = supportCaps['repair-reinjection-guaranteed'] === true;
   const repairEnvelope = supportCaps['repair-envelope-emitted'] === true || supportCaps['repair-payload'] === true;
-  line(
-    repairReinjection ? ok : warn,
-    repairReinjection
-      ? 'Repair: envelope + reinjection guaranteed on hard path when installed + trusted'
-      : repairEnvelope
+  if (repairReinjection) {
+    citedGreen(
+      line,
+      { ok, warn },
+      'Repair: envelope + reinjection guaranteed on hard path when installed + trusted',
+      writePathGreenCites(writePath)
+    );
+  } else {
+    line(
+      warn,
+      repairEnvelope
         ? 'Repair: envelope may emit (`--hook-repair`); reinjection not guaranteed (advisory host)'
         : 'Repair: no hard-boundary payload'
-  );
+    );
+  }
   if (writePath.gap) {
     line(writePath.gap.severity === 'warn' ? warn : warn, writePath.gap.message);
     if (writePath.gap.fix) {
@@ -402,7 +428,12 @@ export function printDoctorDetailsHuman(view) {
   console.log('');
   console.log(color.bold('Gates & skills'));
   if (listedMissing.length === 0 && !skippableCi) {
-    line(ok, 'Shared gate artifacts found on disk (AGENTS.md, .mcp.json, CI); runtime activation is reported separately');
+    citedGreen(
+      line,
+      { ok, warn },
+      'Shared gate artifacts found on disk; runtime activation is reported separately',
+      foundGateCites(view)
+    );
   } else {
     if (listedMissing.length > 0) line(bad, `Missing gates: ${listedMissing.join(', ')}`);
     if (skippableCi) line(warn, skippableCi);
@@ -417,7 +448,11 @@ export function printDoctorDetailsHuman(view) {
   );
   const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
   const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
-  if (remMiss + remStale === 0 && !legacyCodex) line(ok, '/ark-* skills current for detected tools');
+  if (remMiss + remStale === 0 && !legacyCodex) {
+    citedGreen(line, { ok, warn }, '/ark-* skills current for detected tools', [
+      '.agents/skills',
+    ]);
+  }
   if (legacyCodex) {
     line(warn, 'Codex: legacy flat .codex/prompts only (not a loadable skill catalog)');
   }
@@ -467,10 +502,17 @@ export function printDoctorDetailsHuman(view) {
   console.log('');
   console.log(color.bold('Baseline'));
   if (!baseline.exists) {
-    line(!analysisComplete || violations.length > 0 ? warn : ok, !analysisComplete ? 'No baseline — current violations were not fully evaluated' : violations.length > 0 ? 'No baseline — adopting a dirty repo? freeze with --update-baseline --force --contract-session --author <steward>' : 'No baseline (nothing to freeze)');
+    const none = !analysisComplete
+      ? 'No baseline — current violations were not fully evaluated'
+      : violations.length > 0
+        ? 'No baseline — adopting a dirty repo? freeze with --update-baseline --force --contract-session --author <steward>'
+        : 'No baseline (nothing to freeze)';
+    if (!analysisComplete || violations.length > 0) line(warn, none);
+    else line(' ', none);
   } else {
-    const baseMark = !analysisComplete || baselineHonesty.dirtyBaselineRisk ? warn : ok;
-    line(baseMark, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
+    const baseClaim = `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`;
+    if (!analysisComplete || baselineHonesty.dirtyBaselineRisk) line(warn, baseClaim);
+    else citedGreen(line, { ok, warn }, baseClaim, ['.ark-baseline.json']);
     if (analysisComplete && baselineHonesty.dirtyBaselineRisk) {
       line(warn, baselineHonesty.message);
     }
@@ -481,7 +523,9 @@ export function printDoctorDetailsHuman(view) {
 
   console.log('');
   console.log(color.bold('Command runners'));
-  if (staleRunners.length === 0) line(ok, 'Emitted commands match the package manager');
+  if (staleRunners.length === 0) {
+    citedGreen(line, { ok, warn }, 'Emitted commands match the package manager', ['package.json']);
+  }
   else {
     line(warn, `Stale runner in ${staleRunners.join(', ')}`);
   }
@@ -489,9 +533,11 @@ export function printDoctorDetailsHuman(view) {
   console.log('');
   console.log(color.bold('Adoption (separate from fitness score)'));
   if (adoption.gaps.length === 0 && !adoption.layerBalance) {
-    line(
-      ok,
-      'Hosts, MCP argv, core optionality, origin report, baseline policy, and deploy-path lint/types look complete'
+    citedGreen(
+      line,
+      { ok, warn },
+      'Hosts, MCP argv, core optionality, origin report, baseline policy, and deploy-path lint/types look complete',
+      ['AGENTS.md', 'ark.config.json']
     );
   } else {
     for (const gap of adoption.gaps) {
@@ -540,7 +586,9 @@ export function printDoctorDetailsHuman(view) {
       ['Rules with peerIsolation: false', safety.disabledPeerIsolationRules],
     ];
     for (const [label, entries] of rows) {
-      line(entries.length === 0 ? ok : warn, `${label}: ${entries.length}`);
+      const claim = `${label}: ${entries.length}`;
+      if (entries.length === 0) line(' ', claim);
+      else line(warn, claim);
     }
   }
 }

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,26 @@ 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.prototypeShortcuts?.nextAction) {
+    actions.push(ctx.prototypeShortcuts.nextAction);
+  }
+  if (ctx.invariantTestsPath?.missing && ctx.invariantTestsPath.nextAction) {
+    actions.push(ctx.invariantTestsPath.nextAction);
+  }
+  if (ctx.invariantCoverageRoots?.missing && ctx.invariantCoverageRoots.nextAction) {
+    actions.push(ctx.invariantCoverageRoots.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,13 @@ 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';
+import { collectInvariantCoverageResiduals } from './invariant-tests-path.mjs';
+export { printAdrPresenceHint };
 export { printDoctorCompactHuman, printDoctorDetailsHuman };
 export { summarizeRulesUnderContract };
 
@@ -68,6 +74,7 @@ import { writeCiMergeBoundary } from './ci-merge-boundary.mjs';
 import {
   classifyAdopted,
   githubEvidenceForCiMergeBoundary,
+  isAdopted,
   readAdoptionStance,
   NOT_ADOPTED_NEXT_ACTION,
 } from './adoption-stance.mjs';
@@ -173,7 +180,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 +624,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 +645,14 @@ 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 { invariantCoverageRoots, invariantTestsPath } = collectInvariantCoverageResiduals({ adopted: isAdopted(adopted) || options.requireGates === true, coverage: config?.coverage, config, root });
   const { coverageHonesty, baselineHonesty, writePathHonesty, productHonesty } =
     computeDoctorEnforcementHonesty({
       governedPercent: cov.governed.percent,
@@ -671,6 +688,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 +782,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 } : {}), ...(invariantTestsPath ? { invariantTestsPath } : {}), ...(invariantCoverageRoots ? { invariantCoverageRoots } : {}),
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
             ungovernedDirs: cov.suggestions.length,
@@ -827,6 +850,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 +927,20 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     operatingMode,
     adopted,
     stewardNudge: doctorAdvisories.stewardNudge,
+    layerOwners,
+    adrPresence,
+    statesTransitions,
+    statusTransitionCatalog, noDomainFrontend, prototypeShortcuts: doctorAdvisories.prototypeShortcuts, invariantTestsPath, invariantCoverageRoots,
   });
   const humanView = {
     root,
     analysisComplete,
     completeness,
     doctorAdvisories,
+    layerOwners,
+    adrPresence,
+    statesTransitions,
+    statusTransitionCatalog, noDomainFrontend, prototypeShortcuts: doctorAdvisories.prototypeShortcuts, invariantTestsPath, invariantCoverageRoots,
     operatingMode,
     designFitness,
     adopted,