arkgate 4.4.0 → 4.5.5

package/bin/lib/managed-upgrade-honesty.mjs

@@ -0,0 +1,201 @@
+/**
+ * DF05 — managed-upgrade self-service honesty (one residual pilot).
+ *
+ * Self-service criterion (must stay answerable from package surfaces without a maintainer):
+ *   After a managed upgrade (or equivalent), can a consumer learn from package surfaces whether
+ *   the write-path is still honestly labeled active/advisory and whether customized install
+ *   content was preserved — without asking a maintainer?
+ *
+ * This module projects that answer onto `ark upgrade` JSON/human output:
+ * - write-path activation labels per selected host (hard | advisory | unavailable)
+ * - customized (and conflicted) content-identity preserve proof
+ *
+ * Soft hosts never claim hard. Upgrade never invents hardWriteActive from disk alone —
+ * hard requires runtime evidence elsewhere (hooks/doctor/status); upgrade labels fail-closed.
+ * Always notAScore; never a gate input.
+ */
+import { getHostSupportProfile } from './host-support-matrix.mjs';
+import { classifyStatusWritePath, defaultHonestLabel } from './status-manifest.mjs';
+
+/**
+ * @param {string} host
+ * @param {{ hardWriteActive?: boolean }} [evidence]
+ * @returns {{
+ *   host: string,
+ *   writePath: 'hard'|'advisory'|'unavailable',
+ *   softWriteHost: boolean,
+ *   hardWriteSupported: boolean,
+ *   hardWriteActive: boolean,
+ *   label: string,
+ * }}
+ */
+export function projectHostWritePathActivation(host, evidence = {}) {
+  const normalized = typeof host === 'string' ? host.trim().toLowerCase() : '';
+  if (!normalized) {
+    return {
+      host: 'unknown',
+      writePath: 'unavailable',
+      softWriteHost: false,
+      hardWriteSupported: false,
+      hardWriteActive: false,
+      label: defaultHonestLabel('unavailable', null),
+    };
+  }
+
+  const profile = getHostSupportProfile(normalized);
+  if (!profile) {
+    return {
+      host: normalized,
+      writePath: 'unavailable',
+      softWriteHost: false,
+      hardWriteSupported: false,
+      hardWriteActive: false,
+      label: defaultHonestLabel('unavailable', normalized),
+    };
+  }
+
+  const hardWriteSupported = profile.capabilities?.['hard-write'] === true;
+  const softWriteHost = !hardWriteSupported;
+  // Fail-closed: soft never hard; hard only when caller supplies proven active evidence.
+  const hardWriteActive =
+    !softWriteHost && hardWriteSupported && evidence.hardWriteActive === true;
+  const writePath = classifyStatusWritePath({
+    softWriteHost,
+    hardWriteActive,
+    activeHost: normalized,
+  });
+  return {
+    host: normalized,
+    writePath,
+    softWriteHost,
+    hardWriteSupported,
+    hardWriteActive,
+    label: defaultHonestLabel(writePath, normalized),
+  };
+}
+
+/**
+ * Project self-service honesty facts from a managed upgrade plan.
+ *
+ * @param {{
+ *   hosts?: string[],
+ *   assets?: Array<{ path?: string, state?: string, willApply?: boolean, blocked?: boolean }>,
+ *   summary?: { customizedPreserved?: number, blocked?: number, states?: Record<string, number> },
+ * }} plan
+ * @param {{
+ *   hardWriteActiveByHost?: Record<string, boolean>,
+ * }} [options]
+ * @returns {{
+ *   schemaVersion: '1.0',
+ *   notAScore: true,
+ *   criterionId: 'df05-upgrade-activation-preserve',
+ *   customizedPreserved: number,
+ *   customizedPaths: string[],
+ *   conflictedPaths: string[],
+ *   customizedContentPreserved: boolean,
+ *   writePathActivation: ReturnType<typeof projectHostWritePathActivation>[],
+ *   writePathHonestlyLabeled: boolean,
+ *   answers: {
+ *     writePathActivationLabeled: boolean,
+ *     customizedContentPreserved: boolean,
+ *   },
+ * }}
+ */
+export function projectManagedUpgradeSelfServiceHonesty(plan, options = {}) {
+  const assets = Array.isArray(plan?.assets) ? plan.assets : [];
+  const hosts = Array.isArray(plan?.hosts) ? plan.hosts : [];
+  const hardByHost =
+    options.hardWriteActiveByHost && typeof options.hardWriteActiveByHost === 'object'
+      ? options.hardWriteActiveByHost
+      : {};
+
+  const customizedPaths = assets
+    .filter((asset) => asset?.state === 'customized' && typeof asset.path === 'string')
+    .map((asset) => asset.path)
+    .sort();
+  const conflictedPaths = assets
+    .filter((asset) => asset?.state === 'conflicted' && typeof asset.path === 'string')
+    .map((asset) => asset.path)
+    .sort();
+
+  // Preserve contract: customized assets must never be scheduled writes without consent.
+  const customizedContentPreserved = assets
+    .filter((asset) => asset?.state === 'customized' || asset?.state === 'conflicted')
+    .every((asset) => asset.willApply !== true);
+
+  const summaryCount =
+    typeof plan?.summary?.customizedPreserved === 'number'
+      ? plan.summary.customizedPreserved
+      : customizedPaths.length;
+
+  const writePathActivation = hosts.map((host) => {
+    const key = typeof host === 'string' ? host.trim().toLowerCase() : '';
+    return projectHostWritePathActivation(host, {
+      hardWriteActive: hardByHost[key] === true,
+    });
+  });
+
+  // Soft hosts never labeled hard; hard only when evidence supplied.
+  const writePathHonestlyLabeled = writePathActivation.every((entry) => {
+    if (entry.softWriteHost && entry.writePath === 'hard') return false;
+    if (entry.softWriteHost && entry.hardWriteActive) return false;
+    if (!entry.hardWriteSupported && entry.writePath === 'hard') return false;
+    if (entry.writePath === 'hard' && !entry.hardWriteActive) return false;
+    return true;
+  });
+
+  const answers = {
+    // Empty host list is not "labeled activation" — only claim labeled when hosts were projected.
+    writePathActivationLabeled:
+      writePathActivation.length > 0 && writePathHonestlyLabeled,
+    customizedContentPreserved,
+  };
+
+  return {
+    schemaVersion: '1.0',
+    notAScore: true,
+    criterionId: 'df05-upgrade-activation-preserve',
+    customizedPreserved: summaryCount,
+    customizedPaths,
+    conflictedPaths,
+    customizedContentPreserved,
+    writePathActivation,
+    writePathHonestlyLabeled,
+    answers,
+  };
+}
+
+/**
+ * Human one-liner block for upgrade preview/apply (stdout).
+ * @param {ReturnType<typeof projectManagedUpgradeSelfServiceHonesty>} honesty
+ */
+export function formatManagedUpgradeSelfServiceHonesty(honesty) {
+  if (!honesty) return [];
+  const lines = ['Self-service honesty (no maintainer required):'];
+  if (honesty.writePathActivation.length === 0) {
+    lines.push('  Write-path: shared/gates only (no host selected) — activation unavailable.');
+  } else {
+    for (const entry of honesty.writePathActivation) {
+      const soft = entry.softWriteHost ? 'soft host' : 'hard-capable';
+      const active = entry.hardWriteActive ? 'active' : 'not proven this invocation';
+      lines.push(
+        `  Write-path ${entry.host}: ${entry.writePath} (${soft}; hard ${active}).`
+      );
+    }
+  }
+  if (honesty.customizedPaths.length > 0) {
+    lines.push(
+      `  Customized preserved: ${honesty.customizedPreserved} (${honesty.customizedPaths.join(', ')}).`
+    );
+  } else {
+    lines.push(
+      `  Customized preserved: ${honesty.customizedPreserved} (no customized managed assets).`
+    );
+  }
+  if (honesty.conflictedPaths.length > 0) {
+    lines.push(
+      `  Conflicted (consent required): ${honesty.conflictedPaths.join(', ')}.`
+    );
+  }
+  return lines;
+}

package/bin/lib/managed-upgrade.mjs

@@ -4,6 +4,14 @@ import path from 'node:path';
 
 import { codexPrimaryTable, upsertCodexMcpTable } from './codex-home.mjs';
 import { buildManagedAssetCatalog } from './install-migrate.mjs';
+import {
+  formatManagedUpgradeSelfServiceHonesty,
+  projectManagedUpgradeSelfServiceHonesty,
+} from './managed-upgrade-honesty.mjs';
+import {
+  buildUpgradeWhatsNewSuggestions,
+  formatUpgradeWhatsNewSuggestions,
+} from './upgrade-whats-new.mjs';
 import {
   KNOWN_TOOLS,
   arkPackageVersion,
@@ -12,6 +20,17 @@ import {
   skillContentIdentity,
 } from './skill-install.mjs';
 
+export {
+  formatManagedUpgradeSelfServiceHonesty,
+  projectHostWritePathActivation,
+  projectManagedUpgradeSelfServiceHonesty,
+} from './managed-upgrade-honesty.mjs';
+export {
+  buildUpgradeWhatsNewSuggestions,
+  formatUpgradeWhatsNewSuggestions,
+  UPGRADE_WHATS_NEW_SCHEMA_VERSION,
+} from './upgrade-whats-new.mjs';
+
 export const MANAGED_MANIFEST_PATH = 'ark.managed.json';
 const MANIFEST_VERSION = '1.0';
 const AFTER_CONTENT = Symbol('managed-after-content');
@@ -534,7 +553,10 @@ export function planManagedUpgrade(root, options = {}) {
 }
 
 function publicPlan(plan, overrides = {}) {
-  return {
+  const assets = plan.assets.map(
+    ({ containerBeforeHash: _container, [AFTER_CONTENT]: _content, ...asset }) => asset
+  );
+  const base = {
     schemaVersion: plan.schemaVersion,
     root: plan.root,
     readOnly: overrides.readOnly ?? plan.readOnly,
@@ -544,11 +566,25 @@ function publicPlan(plan, overrides = {}) {
     profile: plan.profile,
     hosts: plan.hosts,
     acceptConflicts: plan.acceptConflicts,
-    assets: plan.assets.map(
-      ({ containerBeforeHash: _container, [AFTER_CONTENT]: _content, ...asset }) => asset
-    ),
+    assets,
     summary: plan.summary,
+  };
+  // DF05: self-service honesty (write-path labels + customized preserve) on every public plan.
+  // Not part of planDigest — advisory projection only; never invents hard write on soft hosts.
+  const selfService = projectManagedUpgradeSelfServiceHonesty({
+    hosts: base.hosts,
+    assets,
+    summary: base.summary,
+  });
+  // Suggested improvements / what’s new — product capabilities to try after install/upgrade.
+  // Always notAScore; never a gate input; not part of planDigest.
+  const whatsNew = buildUpgradeWhatsNewSuggestions();
+  return {
+    ...base,
     ...overrides,
+    // DF05 projection always present unless an override supplies a replacement.
+    selfService: overrides.selfService ?? selfService,
+    whatsNew: overrides.whatsNew ?? whatsNew,
   };
 }
 
@@ -738,6 +774,20 @@ export function renderManagedUpgrade(plan, options = {}) {
     `Managed assets: ${managedAssets}; would write: ${wouldWrite}; ` +
       `customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
   );
+  const honesty =
+    plan.selfService ??
+    projectManagedUpgradeSelfServiceHonesty({
+      hosts: plan.hosts,
+      assets: plan.assets,
+      summary: plan.summary,
+    });
+  for (const line of formatManagedUpgradeSelfServiceHonesty(honesty)) {
+    console.log(line);
+  }
+  const whatsNew = plan.whatsNew ?? buildUpgradeWhatsNewSuggestions();
+  for (const line of formatUpgradeWhatsNewSuggestions(whatsNew)) {
+    console.log(line);
+  }
   if (plan.applied) {
     console.log(
       `Applied ${wouldWrite} content write(s)` +

package/bin/lib/remediation.mjs

@@ -49,15 +49,15 @@ export function deterministicNextAction(violation) {
                 return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
             }
             if (violation.peerIsolation) {
-                return 'Extract the shared dependency to a shared layer, then preflight again.';
+                return 'Extract the shared dependency to a shared layer, test at the public interface, then preflight again.';
             }
-            return `Define a port in ${violation.fromLayer ?? 'the source layer'}, inject the ${violation.toLayer ?? 'outer-layer'} implementation, then preflight again.`;
+            return `Define a port in ${violation.fromLayer ?? 'the source layer'}, inject the ${violation.toLayer ?? 'outer-layer'} implementation, test at the public interface, then preflight again.`;
         case 'FORBIDDEN_GLOBAL':
-            return `Inject ${violation.target ?? 'the capability'} through a port, then preflight again.`;
+            return `Inject ${violation.target ?? 'the capability'} through a port, test at the public interface, then preflight again.`;
         case 'CAPABILITY_VIOLATION':
-            return `Define a ${String(violation.capability ?? 'capability')} port in ${violation.fromLayer ?? 'the walled layer'}, bind the implementation outside it, then preflight again.`;
+            return `Define a ${String(violation.capability ?? 'capability')} port in ${violation.fromLayer ?? 'the walled layer'}, bind the implementation outside it, test at the public interface, then preflight again.`;
         case 'CIRCULAR_DEPENDENCY':
-            return 'Extract the shared dependency into a third module, then preflight again.';
+            return 'Extract the shared dependency into a third module, test at the public interface, then preflight again.';
         case 'RAW_EVENT_PUBLISH':
             return 'Publish through a registered intent creator, then run Ark again.';
         case 'PUBLISH_MISSING_SOURCE':

package/bin/lib/status-command.mjs

@@ -1,15 +1,21 @@
 /**
- * ACS03 — gather session/project evidence for `ark status` / MCP `ark_status`.
+ * ACS03 + DF02 — gather session/project evidence for `ark status` / MCP `ark_status`.
  *
  * Fail-closed and CI-safe: never prompts (no readline), never invents hard write,
  * never invents a numeric score. Pure assembly lives in Domain statusManifest.
+ * Improvement compass carries explicit honesty mode (full|subset|unavailable).
  */
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { buildStatusManifest } from './status-manifest.mjs';
+import {
+  buildStatusManifest,
+  normalizeStatusImprovementCompass,
+  projectStatusImprovementCompass,
+  unavailableStatusImprovementCompass,
+} from './status-manifest.mjs';
 import { createProjectId } from './project-identity.mjs';
 import { resolveEffectiveProjectRoot } from './project-root.mjs';
 import { detectWritePathCapabilities } from './write-path-detect.mjs';
@@ -130,6 +136,94 @@ export function lastCheckFactsFromSnapshot(latest, baseline) {
   };
 }
 
+/**
+ * Project status improvementCompass honesty from a report/session snapshot (DF02).
+ * Prefer stored thin slice; never invent green residual when facts are missing.
+ *
+ * @param {object|null|undefined} latest
+ * @param {{ contractHash?: string|null }} [opts]
+ * @returns {import('./status-manifest.mjs').StatusImprovementCompassSlice}
+ */
+export function statusCompassFromSnapshot(latest, opts = {}) {
+  const contractHash =
+    typeof opts.contractHash === 'string' && opts.contractHash.length > 0
+      ? opts.contractHash
+      : null;
+
+  if (!latest || typeof latest !== 'object') {
+    return unavailableStatusImprovementCompass({
+      reasonCode: 'NO_SESSION_SNAPSHOT',
+      reason:
+        'No session report snapshot yet — run ark-check --doctor or --report for residual lenses. Status never invents green.',
+      contractHash,
+    });
+  }
+
+  // Prefer explicit thin status slice on the snapshot (report path stores mode+residual).
+  if (latest.improvementCompass && typeof latest.improvementCompass === 'object') {
+    const normalized = normalizeStatusImprovementCompass({
+      ...latest.improvementCompass,
+      ...(contractHash && !latest.improvementCompass.contractHash
+        ? { contractHash }
+        : {}),
+      factsSource: latest.improvementCompass.factsSource || 'report-snapshot',
+    });
+    if (normalized) return normalized;
+  }
+
+  // Doctor-equivalent residual ids stored without honesty wrapper → full if complete flag set.
+  if (
+    latest.doctorImprovementCompass &&
+    typeof latest.doctorImprovementCompass === 'object' &&
+    latest.doctorImprovementCompass.notAScore === true &&
+    Array.isArray(latest.doctorImprovementCompass.topResidual)
+  ) {
+    const complete = latest.compassFactsComplete === true || latest.completeness === 'complete';
+    return projectStatusImprovementCompass({
+      mode: complete ? 'full' : 'subset',
+      topResidual: latest.doctorImprovementCompass.topResidual,
+      reasonCode: complete ? undefined : 'FACTS_PARTIAL',
+      reason: complete
+        ? undefined
+        : 'Session snapshot residual is partial — re-run doctor/report for full compass.',
+      factsSource: 'report-snapshot',
+      contractHash,
+    });
+  }
+
+  return unavailableStatusImprovementCompass({
+    reasonCode: 'NO_SESSION_SNAPSHOT',
+    reason:
+      'Session snapshot has no improvement compass facts — run ark-check --doctor or --report. Status never invents green.',
+    contractHash,
+  });
+}
+
+/**
+ * Build a storeable thin status compass from a full doctor ImprovementCompass (DF02).
+ * Used by report snapshot so status residual ⊆ doctor residual for the same tree.
+ *
+ * @param {{ notAScore?: boolean, topResidual?: string[] }|null|undefined} doctorCompass
+ * @param {{ mode?: 'full'|'subset', contractHash?: string|null, reasonCode?: string, reason?: string }} [opts]
+ */
+export function thinStatusCompassFromDoctor(doctorCompass, opts = {}) {
+  if (!doctorCompass || doctorCompass.notAScore !== true) {
+    return unavailableStatusImprovementCompass({
+      reasonCode: 'FACTS_UNAVAILABLE',
+      contractHash: opts.contractHash,
+    });
+  }
+  const mode = opts.mode === 'subset' ? 'subset' : 'full';
+  return projectStatusImprovementCompass({
+    mode,
+    topResidual: Array.isArray(doctorCompass.topResidual) ? doctorCompass.topResidual : [],
+    reasonCode: opts.reasonCode,
+    reason: opts.reason,
+    factsSource: 'report-snapshot',
+    contractHash: opts.contractHash,
+  });
+}
+
 /**
  * Collect status facts from disk (no prompts).
  * @param {{
@@ -140,6 +234,8 @@ export function lastCheckFactsFromSnapshot(latest, baseline) {
  *   host?: string,
  *   arkgateVersion?: string,
  *   env?: NodeJS.ProcessEnv,
+ *   improvementCompass?: object | null,
+ *   contractHash?: string | null,
  * }} [options]
  */
 export function collectStatusFacts(options = {}) {
@@ -242,6 +338,22 @@ export function collectStatusFacts(options = {}) {
 
   const arkruleFrozenFallback = countArkruleFrozenKeys(baseline);
 
+  // DF02 — always project compass with honesty mode (never invent green residual).
+  // Prefer explicit override (tests/MCP inject doctor-facts); else report snapshot.
+  let improvementCompass = null;
+  if (options.improvementCompass != null) {
+    improvementCompass = normalizeStatusImprovementCompass(options.improvementCompass);
+  }
+  if (!improvementCompass) {
+    const contractHash =
+      typeof options.contractHash === 'string' && options.contractHash.length > 0
+        ? options.contractHash
+        : configExists && config
+          ? sha256Hex(JSON.stringify(config))
+          : null;
+    improvementCompass = statusCompassFromSnapshot(latest, { contractHash });
+  }
+
   return {
     arkgateVersion: options.arkgateVersion || packageVersion(),
     resolvedRoot: realpathOrResolve(resolvedRoot),
@@ -269,6 +381,7 @@ export function collectStatusFacts(options = {}) {
           : arkRulesLoaded
             ? 0
             : null,
+    improvementCompass,
   };
 }
 
@@ -346,6 +459,18 @@ export function runStatusCommand(args = {}) {
             ? ` · frozen=${manifest.rules.frozenResidual}`
             : '')
       );
+      const ic = manifest.improvementCompass;
+      if (ic) {
+        const residual =
+          Array.isArray(ic.topResidual) && ic.topResidual.length > 0
+            ? ic.topResidual.join(', ')
+            : '(none)';
+        write(
+          `  compass: mode=${ic.mode}` +
+            (ic.mode === 'unavailable' ? '' : ` · residual=${residual}`) +
+            ' · not a score'
+        );
+      }
       write(`  next: [${manifest.nextAction.id}] ${manifest.nextAction.summary}`);
     }