arkgate 4.6.4 → 4.6.6

package/bin/lib/doctor-plan.mjs

@@ -12,10 +12,7 @@ import {
 import * as arkShared from '../ark-shared.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
-import {
-  detectAgentHomeGaps,
-  agentHomeConcernIsActive,
-} from './agent-homes.mjs';
+import { detectAgentHomeGaps, agentHomeConcernIsActive } from './agent-homes.mjs';
 import { operatingModeTitle } from './product-copy.mjs';
 import { collectDoctorNextActions } from './doctor-next-actions.mjs';
 export { summarizeRulesUnderContract };
@@ -28,12 +25,12 @@ const matchingLayersForRelativePath =
 import {
   collectAdoptionGaps,
   detectSkillGaps,
-  skillGapsForActiveHost,
   detectCodexHomeGap,
   codexConcernIsActive,
   detectWritePathCapabilities,
   missingGates,
   staleRunnerGateFiles,
+  skillGapsForActiveHost,
 } from './agent-gates.mjs';
 import {
   baselineOccurrenceKeys,
@@ -64,17 +61,19 @@ import {
 } from './golden-pattern.mjs';
 import { summarizePilotLoop } from './pilot-loop.mjs';
 import { computeDoctorAdvisories, printDoctorAdvisories } from './doctor-advisories.mjs';
-import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
+import { printParseHealthSection } from './parse-health.mjs';
 import { designDeltaDoctorLines } from './design-delta.mjs';
 import { enforcementDoctorLines } from './enforcement-state.mjs';
+import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
+import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
+import { buildDeepModuleCoachAdvisory } from './deep-module-coach.mjs';
+import { writeCiMergeBoundary } from './ci-merge-boundary.mjs';
 import {
-  buildDoctorImprovementCompass,
-  printImprovementCompassSection,
-} from './improvement-compass-doctor.mjs';
-import {
-  buildDeepModuleCoachAdvisory,
-  printDeepModuleCoachSection,
-} from './deep-module-coach.mjs';
+  classifyAdopted,
+  githubEvidenceForCiMergeBoundary,
+  readAdoptionStance,
+  NOT_ADOPTED_NEXT_ACTION,
+} from './adoption-stance.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -535,6 +534,15 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const adoption = collectAdoptionGaps(root, config, cov);
   // Prefer writePath from adoption (same detector); recompute only if missing (tests/stubs).
   const writePath = adoption.writePath ?? detectWritePathCapabilities(root);
+  let ciMergeBoundary = null;
+  try {
+    ciMergeBoundary = writeCiMergeBoundary(root, {
+      writePath,
+      github: githubEvidenceForCiMergeBoundary(adoption, writePath),
+    });
+  } catch {
+    ciMergeBoundary = null;
+  }
   const baseline = readBaseline(root, '.ark-baseline.json');
   const occurrenceKeys = baselineOccurrenceKeys(violations);
   const currentKeys = new Set(occurrenceKeys);
@@ -621,6 +629,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       : packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT'
         ? 'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'
         : null;
+  const stanceFile = readAdoptionStance(root);
+  const githubForBoundary = githubEvidenceForCiMergeBoundary(adoption, writePath);
+  const adopted = classifyAdopted({
+    stance: stanceFile,
+    github: githubForBoundary,
+    ci: ciMergeBoundary?.ci,
+  });
   const { coverageHonesty, baselineHonesty, writePathHonesty, productHonesty } =
     computeDoctorEnforcementHonesty({
       governedPercent: cov.governed.percent,
@@ -646,12 +661,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         : rulesUnderContract?.active === true
           ? { active: true, extraMergeTeeth: false }
           : null,
-      primaryNextAction: postGreenPath?.action ?? dualTruthNext,
+      primaryNextAction:
+        adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext,
       operatingMode,
       packageInstalled,
       selfHost:
         packageVersionTruth?.selfHost === true ||
         packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
+      adopted,
+      ciMergeBoundary,
+      github: githubForBoundary,
+      adoptionStance: stanceFile,
+      stewardNudge: doctorAdvisories.stewardNudge,
     });
 
   // Improvement compass: projection only — never feeds ok/valid/goal.met.
@@ -677,11 +698,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     improvementCompass,
     pilotLoop,
   });
+  const stewardUnfinished = Boolean(
+    doctorAdvisories.stewardNudge?.emptyStewardsPastGrace ||
+      (doctorAdvisories.stewardNudge?.needsStewards &&
+        (doctorAdvisories.stewardNudge?.stewardCount ?? 0) === 0)
+  );
 
   if (asJson) {
     (options.writeJson ?? console.log)(
       JSON.stringify(
         {
+          schemaVersion: '1.0',
+          envelope: 'doctor',
           ok: analysisComplete && (options.designDelta?.valid ?? true),
           doctor: {
             completeness,
@@ -699,11 +727,20 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
-            ...(postGreenPath
-              ? { primaryNextAction: postGreenPath.action, ...DESIGN_WEAK_HONESTY_FLAGS }
-              : productHonesty.primaryNextAction
-                ? { primaryNextAction: productHonesty.primaryNextAction }
-                : {}),
+            adoptionStance: adopted,
+            ...(adopted === 'not-adopted'
+              ? {
+                  primaryNextAction: NOT_ADOPTED_NEXT_ACTION,
+                  ...(postGreenPath ? DESIGN_WEAK_HONESTY_FLAGS : {}),
+                }
+              : postGreenPath
+                ? { primaryNextAction: postGreenPath.action, ...DESIGN_WEAK_HONESTY_FLAGS }
+                : productHonesty.primaryNextAction
+                  ? { primaryNextAction: productHonesty.primaryNextAction }
+                  : {}),
+            ...(stewardUnfinished
+              ? { healthyFinishedForbidden: true, stewardsUnfinished: true }
+              : {}),
             // Q03: advisory golden for new-code placement (absent = no claim).
             goldenPattern,
             // Y06: advisory pure-layer opt-in (null when not applicable).
@@ -767,6 +804,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             skillGaps,
             ...(agentHomeGaps.length > 0 ? { agentHomeGaps } : {}),
             staleRunnerFiles: staleRunners,
+            ciMergeBoundary,
             writePath: {
               activeHost: writePath.activeHost,
               support: writePath.support,
@@ -827,6 +865,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const line = (mark, text) => console.log(`  ${mark} ${text}`);
   console.log(color.bold(`Ark doctor — ${path.basename(path.resolve(root)) || '.'}`));
   if (!analysisComplete) line(warn, analysisIncompleteStatement(completeness));
+  printParseHealthSection(doctorAdvisories.parseHealth, { color, warn, line });
 
   const emptyScope = emptyScopeEarly;
   const mode = operatingMode;
@@ -835,24 +874,27 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   // Modes are detected states, not user-picked settings. Plain-language "what you do next".
   // Never paint green (ok) under design residual — edges clean ≠ design done (product-voice).
   const modeMark =
-    mode === 'enforce' && !designFitness.designWeak
+    mode === 'enforce' &&
+    !designFitness.designWeak &&
+    adopted !== 'not-adopted' &&
+    !stewardUnfinished
       ? ok
       : warn;
   // modeTitle alone names the light — bodies must not re-prefix Suggest/Adapt/Enforce.
   const modeHelp = {
-    suggest:
-      'thin or new tree; architecture config is not yet in charge. You do not pick this light. Next: ark start (preview), then ark start --apply; re-check with --doctor.',
-    adapt:
-      'config and tree still disagree, or debt is open. The write path does not fully protect you yet. You do not pick this light. Next: do doctor top action #1 (often /ark-adopt or /ark-autopilot).',
+    suggest: 'thin or new tree. Next: ark start --apply, then doctor.',
+    adapt: 'config and tree still disagree. Next: do #1.',
     enforce:
-      'honest coverage and clean checked imports. You arrived here; you never turn Enforce on. Next: keep the host write path and CI check; only NEW violations should fail.',
+      adopted === 'not-adopted'
+        ? 'import rules check out; merge boundary not adopted.'
+        : 'import rules check out. Keep host + CI.',
   };
-  const modeTitle = operatingModeTitle(mode, designFitness.designWeak);
+  const modeTitle = operatingModeTitle(mode, designFitness.designWeak, stewardUnfinished);
   line(
     modeMark,
     `${modeTitle} — ${
       designFitness.designWeak
-        ? 'import rules check out; design smells remain. Green is not elegant design. You do not pick this light. Next: one Shape door — /ark-explore shape-focus → plan B; apply B only with /ark-autopilot and your OK. A clean import check is not done.'
+        ? 'import rules check out; leftover design work remains.'
         : modeHelp[mode]
     }`
   );
@@ -897,52 +939,116 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     safetyHasEntries,
     showNewHere,
     designFitness,
+    operatingMode,
+    adopted,
+    stewardNudge: doctorAdvisories.stewardNudge,
   });
   console.log('');
-  if (isDoctorHealthyNothingToDo(designFitness, uniqueActions)) {
+  if (ciMergeBoundary?.ci?.state) {
+    line(
+      ciMergeBoundary.ci.state === 'required' ? ok : warn,
+      `CI merge: ${ciMergeBoundary.ci.state}`
+    );
+  }
+  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('  Contract edges and design residual are clear. Keep write path + CI.'));
+    console.log(color.dim('  Keep write path + CI.'));
   } else {
     console.log(color.bold('Primary next action'));
     console.log(`  1. ${uniqueActions[0]}`);
-    if (uniqueActions.length > 1) {
-      console.log(color.bold(`Also (${uniqueActions.length - 1}):`));
-      uniqueActions.slice(1).forEach((action, index) => console.log(`  ${index + 2}. ${action}`));
+  }
+
+  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 hostRed =
+    gatesMissing.length > 0 ||
+    Boolean(writePath.gap) ||
+    writePathHonesty?.softWriteHost === true;
+  if (hostRed) {
+    console.log('');
+    console.log(color.bold('Host / CI'));
+    if (writePath.activeHost) line(' ', `Active host: ${writePath.activeHost}`);
+    if (gatesMissing.length > 0) line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
+    else if (writePath.gap || writePathHonesty?.softWriteHost) {
+      line(warn, 'Local writes are advisory; required CI is the merge boundary.');
     }
-    if (postGreenPath) {
-      console.log(
-        color.dim(
-          `  Shape residual is the primary door under ${modeTitle} — do not skill-shop explore vs coverage vs think.`
-        )
+  }
+
+  const nudge = doctorAdvisories.stewardNudge;
+  if ((nudge?.needsStewards || nudge?.drift || nudge?.emptyStewardsPastGrace) && nudge.ask) {
+    console.log('');
+    console.log(color.bold('Stewards'));
+    line(warn, nudge.ask);
+  }
+
+  if (violations.length === 0) {
+    if (!analysisComplete) {
+      console.log('');
+      line(
+        warn,
+        'No reported violations — contract compliance is not verified until analysis is complete'
+      );
+    } else if (emptyScope || cov.governed.percent < 50) {
+      console.log('');
+      line(
+        warn,
+        'No active violations — coverage is still thin, so green is not yet honest enforcement'
       );
-    } else {
-      console.log(color.dim('  Doctor is the control plane: do #1 first, then re-run --doctor.'));
     }
   }
 
-  // P0-B — single honesty surface (never a score; never "all good" when residual remains).
-  if (productHonesty) {
+  if (!options.all) {
     console.log('');
-    console.log(color.bold('Product honesty'));
+    console.log(color.dim('More: --doctor --all'));
+    return;
+  }
+
+  console.log('');
+  console.log(color.dim('---'));
+  console.log(color.bold('Details'));
+
+  if (coverageHonesty.greenIsNotEnforcement) {
+    line(coverageHonesty.worseThanNoGate ? bad : warn, coverageHonesty.message);
+  }
+  if (cov.suggestions.length > 0) {
+    line(warn, `${cov.suggestions.length} ungoverned director(y/ies) — proposals: ${arkCommand(root, 'ark-check', '--coverage')}`);
+  }
+  if (cov.emptyLayers.length > 0) line(warn, `Empty layers (pattern matches nothing): ${cov.emptyLayers.join(', ')}`);
+  if (cov.layersWithoutRules.length > 0) line(warn, `Layers with no rule edge: ${cov.layersWithoutRules.join(', ')}`);
+  if (cov.dualMembership?.count > 0) {
     line(
-      productHonesty.unfinished ? warn : ok,
-      `${productHonesty.headline} — ${productHonesty.primaryMessage}`
+      warn,
+      `Dual-match: ${cov.dualMembership.count} file(s) match multiple layers — ${cov.dualMembership.note ?? 'review overlapping globs'}`
     );
-    if (Array.isArray(productHonesty.reasonIds) && productHonesty.reasonIds.length > 0) {
-      line(' ', color.dim(`signals: ${productHonesty.reasonIds.join(', ')} (notAScore)`));
-    }
-    if (rulesUnderContract?.mergePlanes?.failMergeWhen) {
-      line(
-        ' ',
-        color.dim(
-          `merge planes: ${rulesUnderContract.mergePlanes.failMergeWhen} · ${rulesUnderContract.mergePlanes.dualPlaneStamp}`
-        )
-      );
-    }
   }
+  if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) line(ok, 'Every layer classifies files; no empty layers');
 
-  printImprovementCompassSection(improvementCompass, { line, warn, ok, color });
-  printDeepModuleCoachSection(deepModuleCoach, { line, warn, ok, color });
+  if (packageVersionTruth?.dualTruth) {
+    console.log('');
+    console.log(color.bold('Package pin (dual-truth)'));
+    line(warn, packageVersionTruth.note);
+  } else if (packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT') {
+    console.log('');
+    console.log(color.bold('Package pin'));
+    line(warn, packageVersionTruth.note);
+  }
+  if (options.configWalkedUp && options.configRoot) {
+    line(
+      ok,
+      `Config walk-up: using monorepo root ${options.configRoot} (ark.config.json not in cwd package)`
+    );
+  }
 
   console.log('');
   console.log(color.bold('Design fitness'));
@@ -951,7 +1057,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   } else {
     line(designFitness.designWeak ? warn : warn, designFitness.label);
     for (const smell of designSmells.slice(0, 5)) {
-      // Q02: outcome-first (plain language); technical message stays in JSON + dim detail.
       const outcome = smell.outcome || smell.message;
       line(' ', `[${smell.id}] ${outcome}`);
       if (smell.outcome && smell.message && smell.message !== smell.outcome) {
@@ -961,7 +1066,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         line(' ', color.dim(`evidence: ${smell.evidence.slice(0, 4).join(', ')}`));
       }
     }
-    // Q04 — surface one next pilot under leftover design work.
     if (pilotLoop?.active && pilotLoop.nextPilot) {
       const np = pilotLoop.nextPilot;
       line(
@@ -980,7 +1084,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       line(row.level === 'bad' ? bad : row.level === 'ok' ? ok : ' ', row.level === 'dim' ? color.dim(row.text) : row.text);
   }
 
-  // Q03 — optional golden pattern note (advisory for new code only).
   if (goldenPattern.present) {
     console.log('');
     console.log(color.bold('Golden pattern (new code)'));
@@ -999,76 +1102,11 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         'Fix or remove it — absence is fine; a bad file is not guidance.'
     );
   }
-  // Y06 — one-line pure-layer opt-in (U05 voice; never blocker).
   if (pureLayerOptIn) {
     line(' ', color.dim(pureLayerOptIn.message));
   }
 
-  printDoctorAdvisories(doctorAdvisories, { line, warn, color }); // advisory sections
-
-  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)`);
-  if (coverageHonesty.greenIsNotEnforcement) {
-    line(coverageHonesty.worseThanNoGate ? bad : warn, coverageHonesty.message);
-  }
-  if (cov.suggestions.length > 0) {
-    line(warn, `${cov.suggestions.length} ungoverned director(y/ies) — proposals: ${arkCommand(root, 'ark-check', '--coverage')}`);
-  }
-  if (cov.emptyLayers.length > 0) line(warn, `Empty layers (pattern matches nothing): ${cov.emptyLayers.join(', ')}`);
-  if (cov.layersWithoutRules.length > 0) line(warn, `Layers with no rule edge: ${cov.layersWithoutRules.join(', ')}`);
-  if (cov.dualMembership?.count > 0) {
-    line(
-      warn,
-      `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 (packageVersionTruth?.dualTruth) {
-    console.log('');
-    console.log(color.bold('Package pin (dual-truth)'));
-    line(warn, packageVersionTruth.note);
-  } else if (packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT') {
-    console.log('');
-    console.log(color.bold('Package pin'));
-    line(warn, packageVersionTruth.note);
-  }
-  if (options.configWalkedUp && options.configRoot) {
-    line(
-      ok,
-      `Config walk-up: using monorepo root ${options.configRoot} (ark.config.json not in cwd package)`
-    );
-  }
-
-  if (showNewHere) {
-    console.log('');
-    console.log(color.bold('New here?'));
-    // Suggest residual: start → doctor only (not a competing recommend/architect curriculum).
-    line(ok, `Primary path: ${arkCommand(root, 'ark', 'start')} (preview) → ${arkCommand(root, 'ark', 'start --apply')} → re-run --doctor`);
-    if (recommendation) {
-      line(warn, `Sensor shape hint (not a second curriculum): ${recommendation.archetype} — ${recommendation.label} (preset ${recommendation.preset})`);
-      if (recommendation.galleryStarter) line(ok, `Gallery starter (optional): ${recommendation.galleryStarter}`);
-      if (recommendation.policyPack) {
-        line(ok, `Policy pack (optional expert): ${arkCommand(root, 'ark-check', `--apply-policy-pack ${recommendation.policyPack}`)}`);
-      }
-      if (recommendation.signals?.nestFramework) {
-        line(ok, 'Nest modular monolith → prefer hexagonal (or ddd-bounded-contexts if you have src/contexts/*)');
-      }
-      if (recommendation.signals?.monorepoTooling?.length) {
-        line(ok, `Monorepo tooling (${recommendation.signals.monorepoTooling.join(', ')}) → preset monorepo (apps/packages/libs)`);
-      }
-    } else {
-      line(warn, 'Low governed coverage or fresh config — finish start, then re-run doctor before adding layers of code.');
-    }
-    line(ok, `Optional sensor detail: ${arkCommand(root, 'ark-check', '--recommend')}`);
-  }
+  printDoctorAdvisories(doctorAdvisories, { line, warn, color });
 
   console.log('');
   console.log(color.bold('Violations'));
@@ -1121,7 +1159,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
   const enforcement = writePath.enforcementState;
   for (const row of enforcementDoctorLines(enforcement)) line(row.level === 'ok' ? ok : row.level === 'bad' ? bad : warn, row.text);
-  // EH07 Repair: use support/matrix caps (inventory omits envelope-emitted on Codex).
   const supportCaps = writePath.support?.capabilities || {};
   const repairReinjection = supportCaps['repair-reinjection-guaranteed'] === true;
   const repairEnvelope = supportCaps['repair-envelope-emitted'] === true || supportCaps['repair-payload'] === true;
@@ -1182,7 +1219,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       codexHomeGap.stale > 0 ? `${codexHomeGap.stale} content-behind-package` : null, codexHomeGap.catalogStateReason,
     ].filter(Boolean);
     const deferred = !codexConcernIsActive();
-    // Deferred home debt is dim/info (not warn) so non-Codex sessions are not "incomplete".
     if (deferred) {
       line(color.dim('·'), color.dim(`Codex home skills ${parts.join(', ')} (deferred — not on Codex session)`));
     } else {
@@ -1209,8 +1245,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   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' : 'No baseline (nothing to freeze)');
   } else {
-    // Baseline keys are line-agnostic, so N keys can suppress ≥N violations — label as keys
-    // to avoid an apparent mismatch with the "frozen" violation count above.
     const baseMark = !analysisComplete || baselineHonesty.dirtyBaselineRisk ? warn : ok;
     line(baseMark, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
     if (analysisComplete && baselineHonesty.dirtyBaselineRisk) {
@@ -1228,7 +1262,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(warn, `Stale runner in ${staleRunners.join(', ')}`);
   }
 
-  // Adoption completeness (hosts, MCP health, codex home, core optionality, origin, baseline policy)
   console.log('');
   console.log(color.bold('Adoption (separate from fitness score)'));
   if (adoption.gaps.length === 0 && !adoption.layerBalance) {
@@ -1238,8 +1271,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   } else {
     for (const gap of adoption.gaps) {
-      // Deferred Codex-home debt (non-temp) is annotated, not a top action, when the
-      // session host is not Codex — fix when that host is used.
       const mark = gap.deferred
         ? color.dim('·')
         : gap.severity === 'warn'

package/bin/lib/enforcement-honesty.mjs

@@ -10,6 +10,11 @@ import {
   HOST_SUPPORT_MATRIX,
   HOST_SUPPORT_HOSTS,
 } from './host-support-matrix.mjs';
+import {
+  classifyAdopted,
+  MERGE_BOUNDARY_NOT_REQUIRED,
+  NOT_ADOPTED_NEXT_ACTION,
+} from './adoption-stance.mjs';
 
 /** Soft = matrix hard-write false; hard-capable = matrix hard-write true. Single source of truth. */
 function hostWriteClassSets() {
@@ -380,6 +385,37 @@ export function buildProductHonesty(input = {}) {
     });
   }
 
+  const adopted =
+    typeof input.adopted === 'string'
+      ? input.adopted
+      : input.ciMergeBoundary || input.github || input.adoptionStance || input.considerMergeBoundary
+        ? classifyAdopted({
+            stance: input.adoptionStance,
+            github: input.github,
+            ci: input.ciMergeBoundary?.ci,
+          })
+        : null;
+  if (adopted === 'not-adopted') {
+    reasons.push({
+      id: MERGE_BOUNDARY_NOT_REQUIRED,
+      message:
+        'Merge boundary not adopted — require a GitHub status running arkgate-check --strict-merge, or write .ark/adoption-stance.json with stance: "advisory-only".',
+    });
+  }
+
+  const emptyStewards =
+    input.emptyStewards === true ||
+    input.stewardNudge?.emptyStewardsPastGrace === true ||
+    (input.stewardNudge?.needsStewards === true &&
+      (input.stewardNudge?.stewardCount ?? 0) === 0);
+  if (emptyStewards) {
+    reasons.push({
+      id: 'empty-stewards',
+      message:
+        'No stewards listed — not a finished Enforce. Name GitHub handles or emails for stewards[], or this stays Adapt-or-nudge. /ark-adopt asks; it does not invent names.',
+    });
+  }
+
   // Mode adapt/suggest (FG-FINISHED-ADAPT-DEBT): prefer unfinished unless the tree is
   // whole-tree green AND zero design smells AND zero blocking violations.
   // Type-only placement debt alone must not keep adapt unfinished via active-blocking.
@@ -442,6 +478,8 @@ export function buildProductHonesty(input = {}) {
     architectureReasons.find((r) => r.id === 'package-pin-absent') ||
     architectureReasons.find((r) => r.id === 'baseline-missing-with-debt') ||
     architectureReasons.find((r) => r.id === 'residual-pilot') ||
+    architectureReasons.find((r) => r.id === MERGE_BOUNDARY_NOT_REQUIRED) ||
+    architectureReasons.find((r) => r.id === 'empty-stewards') ||
     architectureReasons[0] ||
     environmentResiduals[0];
 
@@ -450,6 +488,9 @@ export function buildProductHonesty(input = {}) {
     primaryMessage =
       primary?.message ||
       'Not finished: residual honesty signals remain (violations, mode, coverage, freeze, design, package pin, or pilots).';
+  } else if (adopted === 'advisory-only-acked') {
+    primaryMessage =
+      '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 (wholeTreeGoverned) {
@@ -468,6 +509,8 @@ 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 && adopted === 'advisory-only-acked') {
+    headline = 'Advisory-only adoption — merge status is not required';
   } else if (!unfinished) {
     headline = 'Honesty clear on residual signals';
   } else if (coverageIncomplete) {
@@ -487,6 +530,12 @@ export function buildProductHonesty(input = {}) {
   } else if (!primaryNextAction && pinAbsent) {
     primaryNextAction =
       'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)';
+  } else if (!primaryNextAction && adopted === 'not-adopted') {
+    primaryNextAction = NOT_ADOPTED_NEXT_ACTION;
+  } else if (!primaryNextAction && emptyStewards) {
+    primaryNextAction =
+      input.stewardNudge?.nextAction ||
+      '/ark-adopt (ask, then update stewards[] — do not invent names)';
   } 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.';
@@ -523,6 +572,8 @@ export function buildProductHonesty(input = {}) {
     primaryMessage,
     primaryNextAction,
     headline,
+    hookGreenIsNotTreeGreen: true,
+    scriptedEditsBypassPreToolUse: true,
   };
 }
 
@@ -556,6 +607,12 @@ export function computeDoctorEnforcementHonesty({
   packageInstalled,
   selfHost,
   motherCli,
+  adopted: adoptedInput,
+  ciMergeBoundary,
+  github,
+  adoptionStance,
+  emptyStewards,
+  stewardNudge,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -581,6 +638,14 @@ export function computeDoctorEnforcementHonesty({
   const blockingForHonesty = Number.isFinite(Number(activeBlockingViolations))
     ? Math.max(0, Number(activeBlockingViolations))
     : Number(activeViolations) || 0;
+  const adopted =
+    typeof adoptedInput === 'string'
+      ? adoptedInput
+      : classifyAdopted({
+          stance: adoptionStance,
+          github,
+          ci: ciMergeBoundary?.ci,
+        });
   const productHonesty = buildProductHonesty({
     coverageHonesty,
     baselineHonesty,
@@ -596,6 +661,13 @@ export function computeDoctorEnforcementHonesty({
     primaryNextAction,
     operatingMode,
     activeBlockingViolations: blockingForHonesty,
+    adopted,
+    ciMergeBoundary,
+    github,
+    adoptionStance,
+    considerMergeBoundary: true,
+    emptyStewards,
+    stewardNudge,
   });
   return {
     coverageHonesty,

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

@@ -5,14 +5,11 @@
 export function setupUsage() {
   return `arkgate (alias ark) — One architecture config. One check. One coach.
 
-  arkgate start              preview what will change (no writes)
-  arkgate start --apply      write the compact contract + host router + CI
-  arkgate-check --doctor     status light + primary next action
+  arkgate start              preview (no writes)
+  arkgate start --apply      write host + CI setup
+  arkgate-check --doctor     where you are + one next action
 
-Then session 0 in your agent: /ark-adopt
 Stuck? Run doctor. Do #1.
-
-More commands and flags: arkgate --help --all
 `;
 }
 
@@ -114,7 +111,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]',
-    '       ark-check --doctor [--json] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  read-only diagnosis; resident JSON falls back cold',
+    '       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',
     '       ark-check --rules-inventory [--json]   brownfield rules inventory (AR13; deterministic candidates, not a score)',
@@ -183,6 +180,10 @@ export function checkUsageAll() {
     'transition. Weakening or judgment-required findings fail unless --policy-ack names',
     'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
     'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
+    'The same merge profile blocks new UI business-rule files (domain-logic-in-ui) created',
+    'versus that base; leftover design on existing files stays green. Missing base skips',
+    'this check (does not exit 2). --fail-on-new-smells --base-ref remains the full',
+    'new+worsened-on-touched-paths ratchet.',
     'Add --require-write-hook claude|grok|antigravity|cursor|codex to validate a hard local',
     'write boundary for that specific host. Codex covers complete local apply_patch only;',
     'hosted/specialized/direct-write paths and OpenCode remain CI-backed. Merge blocking requires',