arkgate 3.9.0 → 3.9.2

package/CHANGELOG.md

@@ -5,6 +5,64 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 3.9.2 — 2026-07-23
+
+**Patch** over 3.9.1. Product honesty for post-validity coaching, coverage/host write paths, and
+advisory analysis precision — **no required config migration**, no gate weakening, no hard-write
+claims on soft hosts. Y07 / Y09 remain **parked** (not promoted).
+
+### Added
+
+- **Enforcement honesty helpers** (`bin/lib/enforcement-honesty.mjs`): coverage honesty
+  (empty / weak <50% worse-than-no-gate / partial / strong; `greenIsNotEnforcement` until 100%;
+  `wholeTreeGoverned`), baseline dirty-freeze risk, write-path honesty with soft hosts derived from
+  `HOST_SUPPORT_MATRIX` (fail-closed: soft never `hardWriteActive`).
+- **Graph blind spots** (`bin/lib/graph-blind.mjs`): advisory scan for unresolvable dynamic
+  import/require edges (template-interpolation + non-literals + import-equals). Never a hard
+  architecture verdict; Y09 direction only.
+- Doctor / plan JSON: `coverageHonesty`, `baseline.honesty`, `writePath.honesty`,
+  `graphBlindSpots`, design-weak honesty flags (`healthyFinishedForbidden`,
+  `multiPilotBatchForbidden`, `autoApplyForbidden` / `autoApplyPlanBForbidden`).
+- Focused unit suite `tests/unit/static-check/enforcementHonesty.test.ts`.
+
+### Changed
+
+- **Post-green path:** placement coaching + shared design-weak honesty flags.
+- **Pilot loop:** one-at-a-time queue (`queuedBets` / `queueNote`); multi-pilot batch and silent
+  plan-B auto-apply forbidden on all return paths.
+- **Ambient sensor (Y07 honesty only):** status vocabulary (`idle` / `active-clean` /
+  `active-findings` / `unavailable`), `blockerGrade: false`, `strictDiagnostics: 'parked-Y07'`;
+  idle/clean/unavailable print honesty lines (not silence-as-done).
+- **Skills** (`ark-coverage`, `ark-explore`, `ark-place`): deepen honesty / one-pilot routing
+  without new skill basenames.
+- **HTML advisories:** graphBlindSpots X01 parity; ambient h2 parked-Y07 wording.
+
+### Notes
+
+- Soft write hosts (Cursor / Codex / OpenCode) remain advisory at write; required CI status is the
+  hard merge boundary.
+- Z09 / residual `RB-11` remain open. Y07 / Y09 not marked done.
+
+## 3.9.1 — 2026-07-23
+
+**Patch** over 3.9.0. Repo hygiene and CI honesty only — **no required config migration**, no gate
+weakening, no product API changes.
+
+### Fixed
+
+- **Onboarding matrix (`o04`):** `ark start --install` may rewrite package-manager lockfiles when the
+  published package is installed; tests compare product mutation paths only (lockfile drift allowed).
+- **Docs post-3.9.0 publish:** CONTRIBUTING / README / release notes / migrate guide match npm truth
+  for the published line (updated again for this patch after 3.9.1 lands on `latest`).
+- **Supply-chain hygiene:** `fast-uri` **3.1.4** (transitive via `ajv`) closes host-confusion advisory
+  GHSA-v2hh-gcrm-f6hx. Eval fixtures pin **Next.js 15.5.21** (patched) so Dependabot Next alerts on
+  `eval/cases/**` corpus close without shipping Next in the `arkgate` npm tarball.
+
+### Notes
+
+- Next bumps are **eval fixture hygiene**, not a consumer-runtime CVE in the published package.
+- Z09 / residual `RB-11` remain open.
+
 ## 3.9.0 — 2026-07-23
 
 **Beautiful Path** minor: one primary flow, doctor as control plane, progressive disclosure, and

package/README.md

@@ -16,9 +16,10 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 3.9.0** is the next prepared release (**Beautiful Path**). **npm `latest` is still
-> 3.8.3** until publication succeeds.
-> [Release notes](docs/releases/3.9.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 3.9.2** is the next prepared patch (enforcement honesty: coverage/host write path,
+> design-weak one-pilot coaching, advisory graph-blind). **npm `latest` is still 3.9.1** until
+> publication succeeds. [3.9.2 notes](docs/releases/3.9.2.md) · [3.9.1](docs/releases/3.9.1.md) ·
+> [Docs hub](docs/README.md)
 
 ---
 
@@ -175,7 +176,7 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Latest release (3.9.0) | [docs/releases/3.9.0.md](docs/releases/3.9.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Latest release (3.9.1 on npm; 3.9.2 prepared) | [3.9.2](docs/releases/3.9.2.md) · [3.9.1](docs/releases/3.9.1.md) · [CHANGELOG](CHANGELOG.md) |
 | History / maintainer evidence | [docs/archive/](docs/archive/README.md) |
 
 ---

package/bin/lib/ambient-state.mjs

@@ -160,19 +160,37 @@ export function detectAmbientState(ts, root, config, files, ackState = { exists:
   };
 }
 
+/**
+ * Status vocabulary for ambient sensor honesty (Y07 strict stays parked).
+ * @param {{ active?: boolean, findingCount?: number }} result
+ */
+export function ambientSensorStatus(result) {
+  if (!result?.active) return 'idle';
+  return (result.findingCount ?? 0) > 0 ? 'active-findings' : 'active-clean';
+}
+
 /** JSON summary for doctor. Advisory only — never a verdict input. */
 export function summarizeAmbientState(result, ackState = { exists: false, acks: [] }) {
+  const findingCount = result.findings.length;
+  const status = ambientSensorStatus({ active: result.active, findingCount });
   return {
     available: true,
     active: result.active,
+    status,
     advisory: true,
-    findingCount: result.findings.length,
+    // Strict (blocker-grade) ambient diagnostics remain parked (Y07) until a real pure corpus.
+    blockerGrade: false,
+    strictDiagnostics: 'parked-Y07',
+    findingCount,
     acknowledged: ackState?.invalid ? 0 : result.acknowledgedCount,
     ...(result.truncated > 0 ? { truncated: result.truncated } : {}),
     ...(result.skippedFiles > 0 ? { skippedFiles: result.skippedFiles } : {}),
-    note: result.active
-      ? 'Module-scope mutable state in pure layers — advisory only; acknowledge deliberate registries in the sidecar or move the state behind a port.'
-      : 'No pure: true layer opted in; the sensor is idle.',
+    note:
+      status === 'idle'
+        ? 'Idle: no pure: true layer opted in. Sensor stays advisory; blocker-grade ambient diagnostics are parked (Y07) until a real pure-layer field corpus exists. Opt in via layer pure: true when ready.'
+        : status === 'active-findings'
+          ? 'Module-scope mutable state in pure layers — advisory only (never a hard verdict). Acknowledge deliberate registries in the sidecar or move state behind a port. Strict diagnostics remain parked (Y07).'
+          : 'Pure layers opted in; no module-scope let/var findings in the MVP envelope. Advisory sensor only — not a pass for blocker-grade ambient enforcement (Y07 parked).',
     ackFile: {
       path: ackState?.path ?? AMBIENT_STATE_ACKS_PATH,
       present: ackState?.exists === true,
@@ -188,11 +206,14 @@ export function computeAmbientState(ts, root, config, files) {
     return {
       available: false,
       active: false,
+      status: 'unavailable',
       advisory: true,
+      blockerGrade: false,
+      strictDiagnostics: 'parked-Y07',
       findings: [],
       findingCount: 0,
       acknowledged: 0,
-      note: 'TypeScript was not available to the doctor run; the ambient-state sensor did not execute.',
+      note: 'TypeScript was not available to the doctor run; the ambient-state sensor did not execute. Advisory only; Y07 strict remains parked.',
     };
   }
   const ackState = loadAmbientStateAcks(root);
@@ -200,9 +221,41 @@ export function computeAmbientState(ts, root, config, files) {
   return { ...summarizeAmbientState(result, ackState), findings: result.findings };
 }
 
-/** Human doctor section (advisory); silent when idle and healthy. */
+/**
+ * Human doctor section (advisory).
+ * Idle prints a single dim honesty line so silence is not misread as "ambient done."
+ */
 export function printAmbientStateSection(state, io) {
-  if (!state.available || (!state.findingCount && !state.ackFile?.invalid)) return;
+  if (!state) return;
+  if (!state.available) {
+    console.log('');
+    console.log(io.color.bold('Ambient state (advisory)'));
+    io.line(' ', io.color.dim(state.note || 'Ambient sensor unavailable.'));
+    return;
+  }
+  if (state.status === 'idle' && !state.ackFile?.invalid) {
+    console.log('');
+    console.log(io.color.bold('Ambient state (advisory)'));
+    io.line(
+      ' ',
+      io.color.dim(
+        'Idle (no pure: true layer) — advisory sensor only; blocker-grade ambient diagnostics parked (Y07).'
+      )
+    );
+    return;
+  }
+  if (state.status === 'active-clean' && !state.ackFile?.invalid && !state.findingCount) {
+    console.log('');
+    console.log(io.color.bold('Ambient state (advisory)'));
+    io.line(
+      ' ',
+      io.color.dim(
+        'Pure layers clean under MVP envelope — still advisory; not Y07 blocker-grade pass.'
+      )
+    );
+    return;
+  }
+  if (!state.findingCount && !state.ackFile?.invalid) return;
   console.log('');
   console.log(io.color.bold('Ambient state (advisory)'));
   if (state.ackFile?.invalid) {
@@ -217,5 +270,8 @@ export function printAmbientStateSection(state, io) {
   if (state.acknowledged > 0) {
     io.line(' ', io.color.dim(`acknowledged module state: ${state.acknowledged}`));
   }
-  io.line(' ', io.color.dim('advisory only — never blocks; move state behind a port or acknowledge it'));
+  io.line(
+    ' ',
+    io.color.dim('advisory only — never blocks; move state behind a port or acknowledge it (Y07 strict parked)')
+  );
 }

package/bin/lib/doctor-advisories.mjs

@@ -1,9 +1,9 @@
 /**
  * Doctor's advisory sensors, aggregated (W01 contract health, U05 ambient
- * state, X04 physical cohesion, Y03 parse health). These sensors do not create
- * architecture violations or designFitness findings; Z02 separately maps
- * parse-health evidence to analysis completeness and fail-closed exits. One
- * seam keeps doctor-plan.mjs inside its module budget as new surfaces land.
+ * state, X04 physical cohesion, Y03 parse health, graph-blind template edges).
+ * These sensors do not create architecture violations or designFitness findings;
+ * Z02 separately maps parse-health evidence to analysis completeness and
+ * fail-closed exits. One seam keeps doctor-plan.mjs inside its module budget.
  */
 import { computeAmbientState, printAmbientStateSection } from './ambient-state.mjs';
 import { computeContractHealth, printContractHealthSection } from './contract-smells.mjs';
@@ -17,6 +17,7 @@ import {
   printReshapeDecisionsSection,
 } from './reshape-decisions.mjs';
 import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
+import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs';
 
 export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth) {
   const physicalCohesion = computePhysicalCohesion(root, files);
@@ -33,6 +34,8 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     ambientState: computeAmbientState(ts, root, config, files),
     physicalCohesion,
     parseHealth: parseHealth ?? summarizeParseHealth(),
+    // Y09 direction: advisory graph-blind spots (template-interpolation); never hard verdict.
+    graphBlindSpots: detectGraphBlindSpots(ts, root, files),
   };
 }
 
@@ -46,4 +49,5 @@ export function printDoctorAdvisories(advisories, io) {
   );
   printReshapeDecisionsSection(advisories.physicalCohesion?.reshapeDecisions, io);
   printParseHealthSection(advisories.parseHealth, io);
+  printGraphBlindSection(advisories.graphBlindSpots, io);
 }

package/bin/lib/doctor-plan.mjs

@@ -35,8 +35,12 @@ import {
   buildPostGreenNextAction,
   mergePostGreenTopActions,
   isDoctorHealthyNothingToDo,
+  DESIGN_WEAK_HONESTY_FLAGS,
 } from './post-green-path.mjs';
-import { doctorWritePathHonestyMessage } from './host-support-matrix.mjs';
+import {
+  buildCoverageHonesty,
+  computeDoctorEnforcementHonesty,
+} from './enforcement-honesty.mjs';
 import {
   computePureLayerOptInNudge,
   loadGoldenPattern,
@@ -129,10 +133,12 @@ export function runCoverage(root, config, files, rules, asJson) {
   if (files.length > 0 && governed.percent < 50) {
     console.log('');
     console.log(
-      `⚠ Ark governs a MINORITY of your code (${governed.percent}%). A green check here does NOT`
+      `⚠ Ark governs a MINORITY of your code (${governed.percent}%). A green check on ~${governed.percent}%`
+    );
+    console.log(
+      '  is worse than no gate — it looks safe while most code is ungoverned. Classify the'
     );
-    console.log('  mean the codebase is checked — the rest is ungoverned. Classify the directories');
-    console.log('  below to actually cover it.');
+    console.log('  directories below before treating green as enforcement.');
   }
   if (suggestions.length > 0) {
     console.log('');
@@ -236,6 +242,11 @@ export function buildRemediationPlan(
     patternBets,
     designSmells,
   });
+  const coverageHonesty = buildCoverageHonesty({
+    percent: governedPercent,
+    totalFiles,
+    emptyScope,
+  });
 
   let statement =
     activeViolations.length > 0
@@ -264,6 +275,7 @@ export function buildRemediationPlan(
         ? {
             designWeakLabel:
               'ENFORCE · design-weak — use patternBets / dual-plan B; never auto-apply as mechanical-safe',
+            ...DESIGN_WEAK_HONESTY_FLAGS,
           }
         : {}),
       ...(governedPercent != null ? { governedPercent } : {}),
@@ -282,6 +294,7 @@ export function buildRemediationPlan(
     designSmells,
     // Q04: one-pilot loop step (extraction card); never mechanical-safe.
     pilotLoop,
+    coverageHonesty,
   };
 }
 
@@ -435,6 +448,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     designSmells,
   });
   const doctorAdvisories = computeDoctorAdvisories(root, config, cov, rules, files, options.ts, options.parseHealth);
+  const { coverageHonesty, baselineHonesty, writePathHonesty } = computeDoctorEnforcementHonesty({
+    governedPercent: cov.governed.percent,
+    totalFiles: cov.governed.totalFiles,
+    emptyScope: cov.emptyScope === true || cov.governed.totalFiles === 0,
+    baselineExists: baseline.exists,
+    frozenKeys: baseline.exists ? baseline.keys.size : 0,
+    activeViolations: activeCount,
+    suppressed,
+    totalViolations: violations.length,
+    activeHost: writePath.activeHost,
+    hardWriteActive: writePath.capabilities?.['hard-write'] === true,
+  });
 
   if (asJson) {
     (options.writeJson ?? console.log)(
@@ -464,10 +489,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
             ...(postGreenPath
-              ? {
-                  primaryNextAction: postGreenPath.action,
-                  healthyFinishedForbidden: true,
-                }
+              ? { primaryNextAction: postGreenPath.action, ...DESIGN_WEAK_HONESTY_FLAGS }
               : {}),
             // Q03: advisory golden for new-code placement (absent = no claim).
             goldenPattern,
@@ -475,10 +497,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             pureLayerOptIn,
             // Q04: one-pilot loop (extraction card → re-doctor).
             pilotLoop,
-            // Advisories, never a verdict: W01 contract health, U05 ambient state,
-            // X04 physical cohesion/reshape pilot, Y03 parse health.
+            // Advisories, never a verdict: W01/U05/X04/Y03 + graph-blind spots.
             ...doctorAdvisories,
             governed: cov.governed,
+            coverageHonesty,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
             ungovernedDirs: cov.suggestions.length,
@@ -497,6 +519,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               frozen: baseline.exists ? baseline.keys.size : 0,
               stale: analysisComplete ? staleBaseline : null,
               policy: adoption.baseline,
+              honesty: baselineHonesty,
             },
             gatesMissing,
             skillGaps,
@@ -517,6 +540,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               hookRepair: writePath.hookRepair,
               mcpPresent: writePath.mcpPresent,
               evidence: writePath.evidence,
+              honesty: writePathHonesty,
               ...(writePath.sessionNote ? { sessionNote: writePath.sessionNote } : {}),
               ...(writePath.gap
                 ? {
@@ -688,6 +712,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         ? 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 (coverageHonesty.worseThanNoGate) {
+      actions.push('raise governed coverage above a minority slice before treating green as enforcement');
+    }
+  }
   if (cov.suggestions.length > 0) {
     line(warn, `${cov.suggestions.length} ungoverned director(y/ies) — proposals: ${arkCommand(root, 'ark-check', '--coverage')}`);
     actions.push('classify the ungoverned directories (/ark-contract)');
@@ -770,8 +800,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   line(' ', `Active host: ${writePath.activeHost}`);
   line(' ', `Supported profile: ${writePath.supportSummary}`);
   line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
-  const honestyLine = doctorWritePathHonestyMessage(writePath.activeHost, capabilities['hard-write']);
-  if (honestyLine) line(warn, honestyLine);
+  if (writePathHonesty.message) line(warn, writePathHonesty.message);
   if (writePath.sessionNote) {
     line(warn, writePath.sessionNote);
   }
@@ -850,7 +879,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   } 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.
-    line(analysisComplete ? ok : warn, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
+    const baseMark = !analysisComplete || baselineHonesty.dirtyBaselineRisk ? warn : ok;
+    line(baseMark, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
+    if (analysisComplete && baselineHonesty.dirtyBaselineRisk) {
+      line(warn, baselineHonesty.message);
+      actions.push('review dirty baseline freezes — fix the contract before trusting green-via-freeze');
+    }
     if (analysisComplete && staleBaseline > 0) {
       line(warn, `${staleBaseline} stale entr(y/ies) no longer occur — tighten with --update-baseline`);
       actions.push('tighten the baseline (--update-baseline)');

package/bin/lib/enforcement-honesty.mjs

@@ -0,0 +1,225 @@
+/**
+ * Product honesty helpers — weak coverage, dirty baseline, soft write hosts.
+ *
+ * Pure / fail-closed: never invent hard write guarantees; never paint thin
+ * coverage or a dirty freeze as "done." Advisory labels only.
+ */
+import {
+  doctorWritePathHonestyMessage,
+  HOST_SUPPORT_MATRIX,
+  HOST_SUPPORT_HOSTS,
+} from './host-support-matrix.mjs';
+
+/** Soft = matrix hard-write false; hard-capable = matrix hard-write true. Single source of truth. */
+function hostWriteClassSets() {
+  const soft = new Set();
+  const hard = new Set();
+  for (const host of HOST_SUPPORT_HOSTS) {
+    const profile = HOST_SUPPORT_MATRIX[host];
+    if (profile?.capabilities?.['hard-write']) hard.add(host);
+    else soft.add(host);
+  }
+  return { soft, hard };
+}
+
+const { soft: SOFT_WRITE_HOSTS, hard: HARD_WRITE_HOSTS } = hostWriteClassSets();
+
+/**
+ * Coverage honesty: green on a minority of the tree is worse than no gate.
+ * `greenIsNotEnforcement` stays true until the whole in-scope tree is governed (100%).
+ * @param {{ percent?: number|null, totalFiles?: number|null, emptyScope?: boolean }} input
+ */
+export function buildCoverageHonesty(input = {}) {
+  const total = Number(input.totalFiles) || 0;
+  const empty = input.emptyScope === true || total === 0;
+  const percent = Number.isFinite(Number(input.percent)) ? Number(input.percent) : 0;
+
+  if (empty) {
+    return {
+      status: 'empty-scope',
+      advisory: true,
+      greenIsNotEnforcement: true,
+      worseThanNoGate: true,
+      wholeTreeGoverned: false,
+      governedPercent: 0,
+      // Always 0 when empty-scope so payload cannot contradict the message.
+      totalFiles: 0,
+      message:
+        'Empty scope: a green check matches 0 files and is worse than no gate until include/layers cover real code.',
+    };
+  }
+  if (percent < 50) {
+    return {
+      status: 'weak',
+      advisory: true,
+      greenIsNotEnforcement: true,
+      worseThanNoGate: true,
+      wholeTreeGoverned: false,
+      governedPercent: percent,
+      totalFiles: total,
+      message: `Weak coverage (${percent}%): a green check on a minority of the tree is worse than no gate — most code is ungoverned.`,
+    };
+  }
+  if (percent < 80) {
+    return {
+      status: 'partial',
+      advisory: true,
+      greenIsNotEnforcement: true,
+      worseThanNoGate: false,
+      wholeTreeGoverned: false,
+      governedPercent: percent,
+      totalFiles: total,
+      message: `Partial coverage (${percent}%): green means edges on the governed slice only, not the whole tree.`,
+    };
+  }
+  const wholeTree = percent >= 100;
+  return {
+    status: 'strong',
+    advisory: true,
+    // Strong slice ≠ full-tree enforcement; boolean consumers must not oversell.
+    greenIsNotEnforcement: !wholeTree,
+    worseThanNoGate: false,
+    wholeTreeGoverned: wholeTree,
+    governedPercent: percent,
+    totalFiles: total,
+    message: wholeTree
+      ? `Governed 100% of in-scope files — green is meaningful for the full in-scope tree.`
+      : `Governed ${percent}% of in-scope files — green is meaningful only for that governed slice; ${100 - percent}% remains ungoverned.`,
+  };
+}
+
+/**
+ * Baseline honesty: a large freeze that zeros active violations can look safe
+ * while hiding false-positive debt.
+ * @param {{
+ *   exists?: boolean,
+ *   frozenKeys?: number,
+ *   activeViolations?: number,
+ *   suppressed?: number,
+ *   totalViolations?: number,
+ * }} input
+ */
+export function buildBaselineHonesty(input = {}) {
+  const exists = input.exists === true;
+  const frozen = Number(input.frozenKeys) || 0;
+  const active = Number(input.activeViolations) || 0;
+  const suppressed = Number(input.suppressed) || 0;
+  const total = Number(input.totalViolations) || 0;
+
+  if (!exists) {
+    return {
+      status: total > 0 ? 'missing-with-debt' : 'absent',
+      advisory: true,
+      dirtyBaselineRisk: false,
+      frozenKeys: 0,
+      activeViolations: active,
+      suppressed: 0,
+      message:
+        total > 0
+          ? 'No baseline while violations exist — freeze only real debt after the contract is honest.'
+          : 'No baseline (nothing to freeze).',
+    };
+  }
+
+  const suppressShare = total > 0 ? suppressed / total : 0;
+  // Dirty: green-via-freeze with material frozen debt (false-positive risk).
+  const dirty =
+    active === 0 &&
+    frozen > 0 &&
+    (frozen >= 10 || (frozen >= 5 && suppressed > 0) || (total >= 3 && suppressShare >= 0.5));
+
+  if (dirty) {
+    return {
+      status: 'dirty-freeze',
+      advisory: true,
+      dirtyBaselineRisk: true,
+      frozenKeys: frozen,
+      activeViolations: active,
+      suppressed,
+      message: `Baseline freezes ${frozen} key(s) while active violations are ${active} — green may hide false-positive debt. Prefer contract fixes over a dirty freeze.`,
+    };
+  }
+  if (frozen > 0) {
+    return {
+      status: 'active-freeze',
+      advisory: true,
+      dirtyBaselineRisk: false,
+      frozenKeys: frozen,
+      activeViolations: active,
+      suppressed,
+      message: `${frozen} frozen key(s); new distinct violations still fail. Ratchet down; do not reopen.`,
+    };
+  }
+  return {
+    status: 'empty-freeze',
+    advisory: true,
+    dirtyBaselineRisk: false,
+    frozenKeys: 0,
+    activeViolations: active,
+    suppressed,
+    message: 'Baseline present with 0 frozen keys — every violation is active (honest).',
+  };
+}
+
+/**
+ * Write-path honesty for the active host (fail-closed).
+ * Soft hosts never claim hard local write; hard hosts without proof stay unverified.
+ * @param {string|null|undefined} activeHost
+ * @param {boolean} hardWriteActive
+ */
+export function buildWritePathHonesty(activeHost, hardWriteActive = false) {
+  const host = typeof activeHost === 'string' ? activeHost.trim().toLowerCase() : '';
+  const softWriteHost = SOFT_WRITE_HOSTS.has(host);
+  const hardCapable = HARD_WRITE_HOSTS.has(host);
+  const message = doctorWritePathHonestyMessage(host, hardWriteActive);
+
+  return {
+    advisory: true,
+    activeHost: host || null,
+    softWriteHost,
+    hardWriteSupported: hardCapable,
+    hardWriteActive: Boolean(hardWriteActive) && hardCapable && !softWriteHost,
+    hardWriteUnverified: hardCapable && !hardWriteActive,
+    hardMergeBoundary: 'required-ci-status (arkgate-check --strict-merge)',
+    message,
+    // Explicit product rule for soft hosts.
+    ...(softWriteHost
+      ? {
+          note: 'Local write is advisory / best-effort — not a hard PreToolUse boundary. Required CI status is the hard merge boundary.',
+        }
+      : {}),
+  };
+}
+
+/**
+ * One-shot doctor honesty bundle (coverage + baseline + write path).
+ * Keeps doctor-plan.mjs under its module budget.
+ */
+export function computeDoctorEnforcementHonesty({
+  governedPercent,
+  totalFiles,
+  emptyScope,
+  baselineExists,
+  frozenKeys,
+  activeViolations,
+  suppressed,
+  totalViolations,
+  activeHost,
+  hardWriteActive,
+} = {}) {
+  return {
+    coverageHonesty: buildCoverageHonesty({
+      percent: governedPercent,
+      totalFiles,
+      emptyScope,
+    }),
+    baselineHonesty: buildBaselineHonesty({
+      exists: baselineExists,
+      frozenKeys,
+      activeViolations,
+      suppressed,
+      totalViolations,
+    }),
+    writePathHonesty: buildWritePathHonesty(activeHost, hardWriteActive),
+  };
+}