arkgate 4.0.0 → 4.1.0

package/bin/lib/html-report-depth.mjs

@@ -12,6 +12,15 @@ import { summarizePilotLoop } from './pilot-loop.mjs';
 import { buildPostGreenNextAction } from './post-green-path.mjs';
 import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
 import { collectAdoptionGaps } from './mcp-adoption.mjs';
+import {
+  buildCoverageHonesty,
+  buildBaselineHonesty,
+  buildWritePathHonesty,
+  buildProductHonesty,
+} from './enforcement-honesty.mjs';
+import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
+import { describePackageVersionDualTruth } from './field-install.mjs';
 
 function esc(value) {
   return String(value)
@@ -27,12 +36,33 @@ function esc(value) {
  * @param {object} config
  * @param {string[]} files
  * @param {object} coverage
- * @param {object[]} activeViolations
+ * @param {object[]} activeViolations already baseline-filtered active findings
+ * @param {{
+ *   suppressedCount?: number,
+ *   totalViolationCount?: number,
+ *   frozenKeys?: number,
+ *   activeCount?: number,
+ *   activeBlockingCount?: number,
+ * }} [baselineSplit] same numbers doctor uses (do not recompute from active-only list)
  */
-export function buildReportDepthPayload(root, config, files, coverage, activeViolations = []) {
+export function buildReportDepthPayload(
+  root,
+  config,
+  files,
+  coverage,
+  activeViolations = [],
+  baselineSplit = {}
+) {
+  // Blocking = failsStrict !== false only (type-only placement debt is non-blocking).
+  // Prefer caller-supplied count for doctor parity; else derive from active list.
+  const activeBlockingCount =
+    typeof baselineSplit.activeBlockingCount === 'number'
+      ? baselineSplit.activeBlockingCount
+      : activeViolations.filter((v) => v?.failsStrict !== false).length;
   const designSmells = detectDesignSmells(root, config, files, coverage);
   const designFitness = summarizeDesignFitness(designSmells, {
-    activeViolations: activeViolations.length,
+    // Doctor parity: fitness uses blocking count, not raw active (incl. type-only).
+    activeViolations: activeBlockingCount,
     governedPercent: coverage?.governed?.percent,
     totalFiles: coverage?.governed?.totalFiles,
   });
@@ -45,6 +75,86 @@ export function buildReportDepthPayload(root, config, files, coverage, activeVio
   });
   const goldenPattern = summarizeGoldenPattern(loadGoldenPattern(root));
   const adoption = collectAdoptionGaps(root, config, coverage);
+  const baseline = readBaseline(root, '.ark-baseline.json');
+  // Prefer caller-supplied baseline split (doctor parity). Recomputing suppressed from an
+  // already-filtered activeViolations list always yields 0 and hides dirty-freeze.
+  const suppressed =
+    typeof baselineSplit.suppressedCount === 'number'
+      ? baselineSplit.suppressedCount
+      : baseline.exists
+        ? baselineOccurrenceKeys(activeViolations).filter((key) => baseline.keys.has(key)).length
+        : 0;
+  const frozenKeys =
+    typeof baselineSplit.frozenKeys === 'number'
+      ? baselineSplit.frozenKeys
+      : baseline.exists
+        ? baseline.keys.size
+        : 0;
+  const activeCount =
+    typeof baselineSplit.activeCount === 'number'
+      ? baselineSplit.activeCount
+      : Math.max(0, activeViolations.length - suppressed);
+  const totalViolations =
+    typeof baselineSplit.totalViolationCount === 'number'
+      ? baselineSplit.totalViolationCount
+      : activeViolations.length + suppressed;
+  const coverageHonesty = buildCoverageHonesty({
+    percent: coverage?.governed?.percent,
+    totalFiles: coverage?.governed?.totalFiles,
+    emptyScope: coverage?.emptyScope === true || (coverage?.governed?.totalFiles ?? 0) === 0,
+  });
+  const baselineHonesty = buildBaselineHonesty({
+    exists: baseline.exists || frozenKeys > 0,
+    frozenKeys,
+    activeViolations: activeCount,
+    suppressed,
+    totalViolations,
+  });
+  const writePath = adoption.writePath;
+  const packageVersionTruth = describePackageVersionDualTruth(root);
+  const hardWriteActive = writePath?.enforcementState?.localWrite?.hard === true;
+  const packageInstalled = writePath?.enforcementState?.localWrite?.installed === true;
+  const writePathHonesty = buildWritePathHonesty(writePath?.activeHost, hardWriteActive, {
+    packageInstalled,
+    packagePinCode: packageVersionTruth?.code,
+    packagePinAbsent: packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT',
+    selfHost:
+      packageVersionTruth?.selfHost === true ||
+      packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
+  });
+  const rulesUnderContract = summarizeRulesUnderContract(root, config, undefined, {
+    governedPercent: coverage?.governed?.percent ?? null,
+    populatedLayerCount: Array.isArray(coverage?.layers)
+      ? coverage.layers.filter((row) => (row?.files ?? 0) > 0).length
+      : null,
+    classifiedFiles: coverage?.governed?.classifiedFiles ?? null,
+  });
+  // Single residual expression (parity with doctor): nextPilot || extractionCard.
+  const residualPilot =
+    pilotLoop?.nextPilot || pilotLoop?.extractionCard || null;
+  const dualTruthNext =
+    packageVersionTruth?.dualTruth === true
+      ? `Bump package.json arkgate pin to ${packageVersionTruth.cliVersion || 'this CLI'} (or re-run install without --no-install)`
+      : packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT'
+        ? 'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'
+        : null;
+  const productHonesty = buildProductHonesty({
+    coverageHonesty,
+    baselineHonesty,
+    writePathHonesty,
+    designWeak: designFitness.designWeak === true,
+    designWeakLabel: designFitness.label,
+    designSmellCount: designSmells.length,
+    designSmellsWithOpenEdges: designSmells.length > 0 && activeBlockingCount > 0,
+    packageVersionTruth,
+    residualPilots: Boolean(residualPilot) && designFitness.designWeak === true,
+    pilotTarget: residualPilot?.pilotTarget ?? residualPilot?.pilot ?? null,
+    arkRulesMergeHonesty: rulesUnderContract?.mergePlanes
+      ? { active: rulesUnderContract.active === true, ...rulesUnderContract.mergePlanes }
+      : null,
+    primaryNextAction: postGreenPath?.action ?? dualTruthNext,
+    activeBlockingViolations: activeBlockingCount,
+  });
   return {
     adoption,
     designDepth: {
@@ -53,6 +163,9 @@ export function buildReportDepthPayload(root, config, files, coverage, activeVio
       pilotLoop,
       postGreenPath,
       goldenPattern,
+      // P0-B / P1-M — folded into designDepth so --report stays a single payload.
+      productHonesty,
+      mergePlanes: rulesUnderContract?.mergePlanes ?? null,
     },
   };
 }
@@ -167,6 +280,57 @@ function baselineLegendBody(signal) {
  *   mode?: string,
  * }} depth
  */
+/**
+ * P0-B — prominent anti-false-green honesty card (never a score).
+ * @param {object|null|undefined} productHonesty
+ * @param {object|null|undefined} [mergePlanes]
+ */
+export function renderProductHonestyCard(productHonesty, mergePlanes = null) {
+  if (!productHonesty || typeof productHonesty !== 'object') return '';
+  const unfinished = productHonesty.unfinished === true;
+  const headline = productHonesty.headline || (unfinished ? 'Not finished' : 'Honesty clear');
+  const primary = productHonesty.primaryMessage || '';
+  // Avoid repeating the same status label in title and body (past-issue pattern).
+  let body = primary;
+  if (primary && headline) {
+    const h = String(headline).trim();
+    const p = String(primary).trim();
+    if (p === h) {
+      body = unfinished
+        ? 'Residual honesty signals remain — not a whole-tree guarantee and not a score.'
+        : 'No residual honesty blockers on this slice — still not a numeric architecture score.';
+    } else if (p.toLowerCase().startsWith(h.toLowerCase())) {
+      const stripped = p.slice(h.length).replace(/^[\s—–:-]+/, '').trim();
+      body = stripped || p;
+    }
+  }
+  const reasons = Array.isArray(productHonesty.reasonIds) ? productHonesty.reasonIds : [];
+  const reasonHtml =
+    reasons.length > 0
+      ? `<p class="dim" style="margin:.35rem 0 0;font-size:.86rem">signals: ${reasons
+          .map((id) => `<code>${esc(id)}</code>`)
+          .join(' · ')} · <code>notAScore</code></p>`
+      : '';
+  const mergeHtml =
+    mergePlanes?.failMergeWhen
+      ? `<p class="dim" style="margin:.35rem 0 0;font-size:.86rem">merge planes: ${esc(mergePlanes.failMergeWhen)}</p>`
+      : '';
+  const dual =
+    mergePlanes?.dualPlaneStamp
+      ? `<p class="dim" style="margin:.25rem 0 0;font-size:.84rem">${esc(mergePlanes.dualPlaneStamp)}</p>`
+      : '';
+  return `<div class="section card design-strip ${unfinished ? 'is-weak' : 'is-clean'}" id="product-honesty" data-product-honesty="1">
+    <div class="design-head">
+      <span class="badge design" title="Product honesty — not a score">${esc(headline)}</span>
+      <span class="dim" style="font-size:.86rem">${unfinished ? 'residual honesty signals' : 'no residual honesty blockers'}</span>
+    </div>
+    <p style="margin:.45rem 0 0">${esc(body)}</p>
+    ${reasonHtml}
+    ${mergeHtml}
+    ${dual}
+  </div>`;
+}
+
 export function renderDesignDepthStrip(depth = {}) {
   const fitness = depth.designFitness;
   const smells = Array.isArray(depth.designSmells) ? depth.designSmells : [];

package/bin/lib/html-report.mjs

@@ -16,6 +16,7 @@ import {
   renderBaselineSignalLegend,
   renderDesignCleanNote,
   renderDesignDepthStrip,
+  renderProductHonestyCard,
   renderWritePathAdoptionBlock,
 } from './html-report-depth.mjs';
 import { FIX_HINTS } from './violations.mjs';
@@ -222,13 +223,13 @@ export function computeReportFitness({ coverage, violations, ok, enforcement, co
     const row = (coverage?.layers ?? []).find((r) => r.name === layer.name);
     return (row?.files ?? 0) > 0;
   }).length;
+  // planMet: blocking (failsStrict !== false) only — type-only alone must not force ADAPT.
+  const blockingCount = Array.isArray(violations)
+    ? violations.filter((v) => v?.failsStrict !== false).length
+    : 0;
   const mode = resolveOperatingMode({
     governedPercent: totalFiles === 0 ? 0 : governedPercent,
-    planMet:
-      ok &&
-      (violations?.length ?? 0) === 0 &&
-      totalFiles > 0 &&
-      (governedPercent == null || governedPercent >= 50),
+    planMet: ok && blockingCount === 0 && totalFiles > 0 && (governedPercent == null || governedPercent >= 50),
     mature: totalFiles >= 150,
     totalFiles,
     emptyLayers,
@@ -531,6 +532,11 @@ export function renderHtmlReport({
       ok,
       mode,
     });
+  // P0-B product honesty card — prefer payload from buildReportDepthPayload when present.
+  const productHonestyHtml = renderProductHonestyCard(
+    depth.productHonesty ?? null,
+    depth.mergePlanes ?? null
+  );
   const writePathHtml = renderWritePathAdoptionBlock(adoptionView.writePath);
   const baselineLegendHtml = renderBaselineSignalLegend();
 
@@ -1111,6 +1117,7 @@ export function renderHtmlReport({
   </div>
 
   ${designStripHtml}
+  ${productHonestyHtml}
 
   <div class="section card" id="adoption">
     <h2>Adoption</h2>

package/bin/lib/install-migrate.mjs

@@ -49,7 +49,15 @@ import {
   codexTomlSnippet,
   arkCheckCommand,
   checkArchitectureScriptSnippet,
+  ensureCheckArchitectureScript,
 } from './ci-and-commands.mjs';
+// Break cycle with managed-upgrade (it imports buildManagedAssetCatalog from here).
+// Static import would form CIRCULAR_DEPENDENCY under mother --strict.
+import { createRequire } from 'node:module';
+const requireFromHere = createRequire(import.meta.url);
+function loadManagedUpgrade() {
+  return requireFromHere('./managed-upgrade.mjs');
+}
 import {
   resolveTools,
   SKILL_TOOL_TARGETS,
@@ -351,6 +359,28 @@ export function runInstallAgentGates(args) {
     return;
   }
   const hasCheckScript = hasCheckArchitectureScript(root);
+  // S4.2: when a managed-upgrade manifest is already present, a bare
+  // --install-agent-gates (no --force / --compact) defaults to skills-only so a
+  // refresh cannot clobber customized gates or invalidate upgrade planDigest.
+  // Missing AGENTS still gets a full install (gates need repair).
+  const {
+    MANAGED_MANIFEST_PATH,
+    tryReadManagedManifest,
+    isManagedAssetCustomizedOnDisk,
+    syncManagedManifestFromDisk,
+  } = loadManagedUpgrade();
+  const managedPresent = Boolean(tryReadManagedManifest(root));
+  let defaultedSkillsOnly = false;
+  if (
+    managedPresent &&
+    !args.skillsOnly &&
+    !args.compact &&
+    !args.force &&
+    fs.existsSync(path.join(root, 'AGENTS.md'))
+  ) {
+    args.skillsOnly = true;
+    defaultedSkillsOnly = true;
+  }
   const { tools, source } = args.compact && args.tools == null
     ? { tools: new Set(), source: 'compact-none' }
     : resolveTools(args);
@@ -373,7 +403,12 @@ export function runInstallAgentGates(args) {
     const host = [...tools][0];
     const later = host ? ` --tools ${host}` : '';
     if (args.compact) console.log(`Profile: compact router. Expert skills later: ${arkCommand(root, 'ark-check', `--install-agent-gates --skills-only${later} --force`)}`);
-    else if (args.skillsOnly) console.log('Profile: expert skill pack only (refreshes /ark-*; leaves customized gates).');
+    else if (defaultedSkillsOnly) {
+      console.log(
+        `Profile: skills-only refresh (default — ${MANAGED_MANIFEST_PATH} present). ` +
+          'Full gate rewrite: re-run with --force (preserves customized content-identity assets and recomputes managed digest).'
+      );
+    } else if (args.skillsOnly) console.log('Profile: expert skill pack only (refreshes /ark-*; leaves customized gates).');
     else console.log('Profile: full agent gates. Compact-only onboarding: ark start.');
   }
   // --skills-only refreshes just the canonical /ark-* skills, which are safe to
@@ -382,6 +417,13 @@ export function runInstallAgentGates(args) {
   // `--force` clobbers them — this is the safe way to pick up new skill versions.
   // Do not mutate package.json under --skills-only (typecheck bootstrap is gates/CI).
   if (!args.skillsOnly) {
+    // S4.4: always write check:architecture on gate install / start (including compact).
+    const checkBootstrap = ensureCheckArchitectureScript(root, { write: true });
+    if (checkBootstrap.changed && !args.json) {
+      console.log(
+        `Added package.json script "check:architecture": "${checkBootstrap.script}" (local/CI parity).`
+      );
+    }
     // Bootstrap typecheck before CI template so generated workflow includes the step.
     const typecheckBootstrap = ensureTypecheckScript(root, { write: !args.compact });
     if (typecheckBootstrap.changed && !args.compact && !args.json) {
@@ -397,6 +439,9 @@ export function runInstallAgentGates(args) {
     skillsOnly: args.skillsOnly,
   });
   const { skills, skillPaths, version } = catalog;
+  const assetKindByPath = new Map(
+    catalog.assets.map((asset) => [asset.relativePath, asset.kind ?? 'gate'])
+  );
   const templates = catalog.assets.map(({ relativePath, content }) => [relativePath, content]);
 
   // A compact router can be moved back from an explicit host removal. Delete the
@@ -412,6 +457,16 @@ export function runInstallAgentGates(args) {
   }
 
   const results = templates.map(([relativePath, content]) => {
+    // S4.1: preserve content-identity customized/conflicted managed assets even under --force.
+    const kind = assetKindByPath.get(relativePath) ?? 'gate';
+    if (
+      args.force &&
+      managedPresent &&
+      kind !== 'skill' &&
+      isManagedAssetCustomizedOnDisk(root, relativePath, content, kind)
+    ) {
+      return { relativePath, status: 'skipped-customized' };
+    }
     if (relativePath === '.codex/config.toml') {
       const fullPath = path.join(root, relativePath);
       let existing = '';
@@ -474,6 +529,7 @@ export function runInstallAgentGates(args) {
 
   console.log('Ark agent gate templates:');
   let staleSkipped = 0;
+  let preservedCustomized = 0;
   for (const result of results) {
     const marker =
       result.status === 'written'
@@ -482,13 +538,18 @@ export function runInstallAgentGates(args) {
           ? 'merged'
           : result.status === 'skipped-non-ark'
             ? 'kept'
-            : result.status === 'failed'
-              ? 'FAILED'
-              : 'skipped';
+            : result.status === 'skipped-customized'
+              ? 'kept'
+              : result.status === 'failed'
+                ? 'FAILED'
+                : 'skipped';
     // A skipped skill reads as "you're fine" — but it may be a version behind.
     // Say which, so the user isn't left guessing (and knows the safe refresh cmd).
     let note = '';
-    if (result.status === 'skipped' && skillPaths.has(result.relativePath) && version) {
+    if (result.status === 'skipped-customized') {
+      preservedCustomized += 1;
+      note = '  (customized — content-identity preserved)';
+    } else if (result.status === 'skipped' && skillPaths.has(result.relativePath) && version) {
       const installed = installedSkillVersion(path.join(root, result.relativePath));
       if (installed === null || isVersionOlder(installed, version)) {
         staleSkipped += 1;
@@ -499,6 +560,11 @@ export function runInstallAgentGates(args) {
     }
     console.log(`  ${marker.padEnd(7)} ${result.relativePath}${note}`);
   }
+  if (preservedCustomized > 0 && !args.json) {
+    console.log(
+      `  ${preservedCustomized} customized managed asset(s) preserved (use ark upgrade --accept-conflicts to overwrite deliberately).`
+    );
+  }
   if (staleSkipped > 0 && !args.skillsOnly) {
     console.log('');
     console.log(
@@ -605,11 +671,48 @@ export function runInstallAgentGates(args) {
     }
     console.log(`\nHard-write hook verified for ${writeRequest.host}.`);
   }
+  // S4.1: after --force, recompute ark.managed.json so a prior upgrade planDigest
+  // is not left silently broken (field: force clobber → digest mismatch).
+  const wroteManaged =
+    results.some((r) => r.status === 'written' || r.status === 'merged') ||
+    homeResults.some((r) => r.status === 'written');
+  if (args.force && managedPresent) {
+    try {
+      const sync = syncManagedManifestFromDisk(root, {
+        tools: [...tools],
+        profile: args.compact ? 'compact' : 'full',
+      });
+      if (!args.json) {
+        console.log('');
+        console.log(
+          sync.wrote
+            ? `Recomputed ${MANAGED_MANIFEST_PATH} after --force (planDigest ${sync.planDigest.slice(0, 18)}…). Run a fresh ark upgrade preview before --apply.`
+            : `${MANAGED_MANIFEST_PATH} already matches on-disk content after --force.`
+        );
+      }
+    } catch (error) {
+      if (!args.json) {
+        console.log('');
+        console.log(
+          `Warning: could not recompute ${MANAGED_MANIFEST_PATH} after --force (${error instanceof Error ? error.message : String(error)}). Run a new ark upgrade preview before --apply.`
+        );
+      }
+    }
+  } else if (args.force && wroteManaged && !args.skillsOnly) {
+    // No prior manifest: still warn that any in-flight upgrade preview is stale.
+    if (!args.json) {
+      console.log('');
+      console.log(
+        'Note: --force rewrote gate files. If you had an ark upgrade preview open, run a new preview (planDigest changed).'
+      );
+    }
+  }
+
   console.log('');
   console.log('Next steps:');
   console.log('  1. Review the generated files and commit the ones that match your tools.');
   console.log(`  2. Run: ${arkCheckCommand(root)}`);
-  if (!hasCheckScript) {
+  if (!hasCheckScript && !hasCheckArchitectureScript(root)) {
     console.log('  3. Add the package.json alias if you want `run check:architecture`:');
     console.log(`     ${checkArchitectureScriptSnippet(root)}`);
   }

package/bin/lib/managed-upgrade.mjs

@@ -180,6 +180,105 @@ function readManifest(root) {
   return { file, content, value };
 }
 
+/**
+ * Best-effort managed manifest load for install-agent-gates force/preserve paths.
+ * Returns null when missing or invalid (never throws).
+ * @param {string} root
+ * @returns {{ schemaVersion: string, profile: string, hosts: string[], assets: object[] } | null}
+ */
+export function tryReadManagedManifest(root) {
+  try {
+    const { value } = readManifest(path.resolve(root));
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Recompute `ark.managed.json` identities from on-disk content after a force
+ * gate install (or any out-of-band rewrite of managed assets). Without this,
+ * a prior upgrade planDigest is silently invalidated and apply fails with
+ * "managed upgrade plan digest mismatch".
+ *
+ * @param {string} root
+ * @param {{ tools?: string[]|string|Set<string>, profile?: 'compact'|'full' }} [options]
+ * @returns {{ planDigest: string, profile: string, hosts: string[], assetCount: number, wrote: boolean }}
+ */
+export function syncManagedManifestFromDisk(root, options = {}) {
+  const resolvedRoot = path.resolve(root);
+  const plan = planManagedUpgrade(resolvedRoot, {
+    tools: options.tools,
+    profile: options.profile,
+    acceptConflicts: options.acceptConflicts === true,
+  });
+  const file = assertSafeTarget(resolvedRoot, MANAGED_MANIFEST_PATH);
+  const previous = readFile(file);
+  const next = Buffer.from(plan.manifestContent);
+  if (previous && hash(previous) === hash(next)) {
+    return {
+      planDigest: plan.planDigest,
+      profile: plan.profile,
+      hosts: plan.hosts,
+      assetCount: plan.assets.length,
+      wrote: false,
+    };
+  }
+  ensureParentDirectories(resolvedRoot, MANAGED_MANIFEST_PATH, []);
+  fs.writeFileSync(file, plan.manifestContent);
+  return {
+    planDigest: plan.planDigest,
+    profile: plan.profile,
+    hosts: plan.hosts,
+    assetCount: plan.assets.length,
+    wrote: true,
+  };
+}
+
+/**
+ * True when an existing managed asset is customized/conflicted vs the recorded
+ * identity — install-agent-gates --force must preserve these (same contract as
+ * content-identity upgrade).
+ *
+ * Force preserve also applies by content-identity when the asset is missing from
+ * ark.managed.json (incomplete manifest must not clobber customized AGENTS.md).
+ */
+export function isManagedAssetCustomizedOnDisk(root, relativePath, desiredContent, kind = 'gate') {
+  const file = path.join(path.resolve(root), relativePath);
+  const currentFile = readFile(file);
+  if (currentFile == null) return false;
+  let currentScoped = currentFile.toString('utf8');
+
+  const manifest = tryReadManagedManifest(root);
+  const recorded = manifest
+    ? (manifest.assets ?? []).find((asset) => asset.path === relativePath)
+    : null;
+
+  if (recorded) {
+    // Whole-file gates: compare full file bytes. Toml-section uses primary table only.
+    if (recorded.scope === 'toml-section') {
+      currentScoped = codexPrimaryTable(currentScoped)?.block ?? currentScoped;
+    }
+    const classified = classifyManagedAsset({
+      recorded,
+      currentContent: currentScoped,
+      targetContent: desiredContent,
+      kind,
+    });
+    return classified.state === 'customized' || classified.state === 'conflicted';
+  }
+
+  // Incomplete / missing managed list: still preserve when on-disk content differs
+  // from the desired template (content-identity force preserve, especially AGENTS.md).
+  if (kind === 'skill') return false;
+  const desiredNorm = normalizedIdentityContent(desiredContent ?? '');
+  const currentNorm = normalizedIdentityContent(currentScoped);
+  if (!currentNorm.trim()) return false;
+  if (currentNorm === desiredNorm) return false;
+  // AGENTS.md and other whole-file gates: any divergence from desired template is customized.
+  return managedContentIdentity(currentNorm, kind) !== managedContentIdentity(desiredNorm, kind);
+}
+
 function resolveSelection(root, options, manifest) {
   const explicit = normalizeToolsList(options.tools);
   const compactHost = compactRouterHost(root);
@@ -689,5 +788,5 @@ export function renderManagedUpgrade(plan, options = {}) {
   }
   console.log(`Planned writes: ${wouldWrite}; blocked conflicts/deletions: ${blocked}.`);
   if (options.next) console.log(options.next);
-  else console.log('Apply the exact preview with: ark upgrade --apply --no-install');
+  else console.log('Apply the exact preview with: npx arkgate upgrade --apply --no-install');
 }