arkgate 4.8.15 → 4.8.16

package/bin/lib/architecture-scan.mjs

@@ -16,6 +16,12 @@ 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';
 
@@ -198,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/baseline-key.mjs

@@ -12,6 +12,8 @@
 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.

package/bin/lib/config-contract.mjs

@@ -243,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: {

package/bin/lib/diagnostic-catalog.mjs

@@ -59,6 +59,8 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     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.'),

package/bin/lib/doctor-advisories.mjs

@@ -36,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 = {
@@ -127,6 +128,24 @@ export function printCompactExtraDoctorLines(advisories, io) {
     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) {
@@ -221,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,

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,24 +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';
 import { layerGuidanceLine } from './layer-description.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 {
+  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}`);
@@ -97,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,
@@ -114,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]}`);
@@ -132,13 +124,10 @@ 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 ?? []) {
     const guidance = layerGuidanceLine(row);
     if (guidance) line(' ', `${row.name} — ${guidance}`);
@@ -175,7 +164,7 @@ export function printDoctorCompactHuman(view) {
       ...doctorAdvisories,
       layerOwners: view.layerOwners,
       adrPresence: view.adrPresence,
-      statesTransitions: view.statesTransitions, statusTransitionCatalog: view.statusTransitionCatalog, noDomainFrontend: view.noDomainFrontend,
+      statesTransitions: view.statesTransitions, statusTransitionCatalog: view.statusTransitionCatalog, noDomainFrontend: view.noDomainFrontend, invariantTestsPath: view.invariantTestsPath, invariantCoverageRoots: view.invariantCoverageRoots,
     },
     { line, warn }
   );
@@ -261,7 +250,12 @@ 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');
+  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('');
@@ -288,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)) {
@@ -355,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`));
@@ -387,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);
@@ -397,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) {
@@ -415,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);
@@ -430,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)');
   }
@@ -480,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);
     }
@@ -494,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(', ')}`);
   }
@@ -502,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) {
@@ -553,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

@@ -56,6 +56,15 @@ export function collectDoctorNextActions(ctx) {
   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

@@ -20,6 +20,7 @@ import { collectAdrPresenceResidual, printAdrPresenceHint } from './adr-presence
 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 };
@@ -73,6 +74,7 @@ import { writeCiMergeBoundary } from './ci-merge-boundary.mjs';
 import {
   classifyAdopted,
   githubEvidenceForCiMergeBoundary,
+  isAdopted,
   readAdoptionStance,
   NOT_ADOPTED_NEXT_ACTION,
 } from './adoption-stance.mjs';
@@ -650,6 +652,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   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,
@@ -782,7 +785,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             ...(layerOwners ? { layerOwners } : {}),
             ...(adrPresence ? { adrPresence } : {}),
             ...(statesTransitions ? { statesTransitions } : {}),
-            ...(statusTransitionCatalog ? { statusTransitionCatalog } : {}), ...(noDomainFrontend ? { noDomainFrontend } : {}),
+            ...(statusTransitionCatalog ? { statusTransitionCatalog } : {}), ...(noDomainFrontend ? { noDomainFrontend } : {}), ...(invariantTestsPath ? { invariantTestsPath } : {}), ...(invariantCoverageRoots ? { invariantCoverageRoots } : {}),
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
             ungovernedDirs: cov.suggestions.length,
@@ -927,7 +930,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     layerOwners,
     adrPresence,
     statesTransitions,
-    statusTransitionCatalog, noDomainFrontend,
+    statusTransitionCatalog, noDomainFrontend, prototypeShortcuts: doctorAdvisories.prototypeShortcuts, invariantTestsPath, invariantCoverageRoots,
   });
   const humanView = {
     root,
@@ -937,7 +940,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     layerOwners,
     adrPresence,
     statesTransitions,
-    statusTransitionCatalog, noDomainFrontend,
+    statusTransitionCatalog, noDomainFrontend, prototypeShortcuts: doctorAdvisories.prototypeShortcuts, invariantTestsPath, invariantCoverageRoots,
     operatingMode,
     designFitness,
     adopted,