arkgate 4.5.0 → 4.5.6

package/bin/lib/deepening-coach.mjs

@@ -0,0 +1,177 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/deepeningCoach.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/deepening-coach.mjs). Zero Node I/O.
+ */
+
+export const ARK_DEEPENING_COACH_SCHEMA_VERSION = '1.0';
+/** Cap on listed deepening candidates (agent-legible; not a ranking score). */
+export const DEEPENING_CANDIDATE_CAP = 5;
+function asString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function firstEvidencePath(evidence) {
+    if (!Array.isArray(evidence))
+        return '';
+    for (const row of evidence) {
+        if (typeof row === 'string' && row.trim())
+            return row.trim().replace(/\\/g, '/');
+        if (row && typeof row === 'object') {
+            const path = asString(row.path)
+                || asString(row.file);
+            if (path)
+                return path.replace(/\\/g, '/');
+        }
+    }
+    return '';
+}
+function evidenceList(source, refs, detail) {
+    const out = [];
+    for (const ref of refs) {
+        const r = asString(ref);
+        if (!r)
+            continue;
+        out.push(detail ? { source, ref: r, detail } : { source, ref: r });
+    }
+    return out;
+}
+/**
+ * Project deepening candidates from existing doctor-side evidence only.
+ * Empty input / no residual → empty `candidates` (honesty: no fake list).
+ */
+export function buildDeepeningCandidates(input = {}) {
+    const candidates = [];
+    const seen = new Set();
+    const push = (candidate) => {
+        if (candidates.length >= DEEPENING_CANDIDATE_CAP)
+            return;
+        const key = `${candidate.target}|${candidate.friction}`.toLowerCase();
+        if (seen.has(key))
+            return;
+        if (!asString(candidate.target) || !asString(candidate.friction))
+            return;
+        seen.add(key);
+        candidates.push(candidate);
+    };
+    const pilot = input.pilotLoop?.active === true && input.pilotLoop.nextPilot
+        ? input.pilotLoop.nextPilot
+        : null;
+    if (pilot) {
+        // Require a real pilot identity — empty shells are not evidence.
+        const target = asString(pilot.pilotTarget) || asString(pilot.pilot) || asString(pilot.smellId);
+        if (target) {
+            push({
+                target,
+                friction: asString(pilot.smellId)
+                    ? `Shape pilot residual (${pilot.smellId}) — one extraction at a time`
+                    : 'Shape pilot residual — one extraction at a time',
+                intent: asString(pilot.move) ||
+                    'Deepen the public seam; hide implementation behind a small interface',
+                benefit: asString(pilot.successSignal) ||
+                    'Locality: change and tests concentrate at the public interface',
+                evidence: evidenceList('pilotLoop', [target], 'nextPilot'),
+            });
+        }
+    }
+    const smells = Array.isArray(input.designSmells) ? input.designSmells : [];
+    for (const smell of smells) {
+        if (!smell || typeof smell !== 'object')
+            continue;
+        const id = asString(smell.id);
+        const path = firstEvidencePath(smell.evidence);
+        // Require non-empty smell id or evidence path — whitespace shells are not evidence.
+        if (!id && !path)
+            continue;
+        const target = path || id;
+        const friction = asString(smell.outcome) || asString(smell.message) || `Design residual (${id || target})`;
+        push({
+            target,
+            friction,
+            intent: asString(smell.fix) ||
+                'Prefer a deep module at a named seam; apply the deletion test before pass-through extracts',
+            benefit: 'Leverage: callers learn a smaller interface; locality of change improves',
+            evidence: evidenceList('designSmells', path ? [path, id].filter(Boolean) : [id], id || undefined),
+        });
+    }
+    const pc = input.physicalCohesion;
+    const reshape = pc?.reshapePilot?.nextPilot;
+    if (reshape) {
+        const target = asString(reshape.pilotTarget) || asString(reshape.pilot);
+        if (target) {
+            push({
+                target,
+                friction: 'Physical cohesion residual — concept concentration across anchors',
+                intent: asString(reshape.move) ||
+                    'One reshape pilot toward locality; never mechanical-safe multi-file batch',
+                benefit: asString(reshape.successSignal) ||
+                    'Related behavior co-located; public seams stay small',
+                evidence: evidenceList('physicalCohesion', [target], 'reshapePilot'),
+            });
+        }
+    }
+    const findings = Array.isArray(pc?.findings) ? pc.findings : [];
+    for (const finding of findings) {
+        if (!finding || typeof finding !== 'object')
+            continue;
+        const concept = asString(finding.concept);
+        const anchors = Array.isArray(finding.anchors)
+            ? finding.anchors.map((a) => asString(a)).filter(Boolean)
+            : [];
+        const target = anchors[0] || concept;
+        if (!target)
+            continue;
+        push({
+            target,
+            friction: asString(finding.message) ||
+                (concept
+                    ? `Concept "${concept}" concentrated across physical anchors`
+                    : 'Physical cohesion residual'),
+            intent: 'Deepen by colocating behavior behind one public interface per concern',
+            benefit: 'Locality of change; fewer cross-anchor edits for one concept',
+            evidence: evidenceList('physicalCohesion', anchors.length > 0 ? anchors.slice(0, 3) : [target], concept || undefined),
+        });
+    }
+    const compass = input.improvementCompass;
+    if (compass && compass.notAScore === true) {
+        const residualIds = Array.isArray(compass.topResidual)
+            ? compass.topResidual.map((id) => asString(id)).filter(Boolean)
+            : [];
+        const lensById = new Map();
+        if (Array.isArray(compass.lenses)) {
+            for (const lens of compass.lenses) {
+                if (lens && typeof lens === 'object' && asString(lens.id)) {
+                    lensById.set(asString(lens.id), { summary: asString(lens.summary) || undefined });
+                }
+            }
+        }
+        for (const id of residualIds) {
+            // Each residual lens id is independent evidence. Cap + target|friction dedupe may
+            // still list both a smell card and lens:<id> — no cross-source suppression.
+            const summary = lensById.get(id)?.summary;
+            push({
+                target: `lens:${id}`,
+                friction: summary
+                    ? `Residual lens ${id}: ${summary}`
+                    : `Residual architecture lens ${id} (not a score)`,
+                intent: 'Process judgment: deepen modules / name seams that clear this lens residual',
+                benefit: 'Clear residual without inventing a depth score or gate fail',
+                evidence: evidenceList('improvementCompass', [id], 'topResidual'),
+            });
+        }
+    }
+    return {
+        schemaVersion: ARK_DEEPENING_COACH_SCHEMA_VERSION,
+        notAScore: true,
+        candidates,
+    };
+}
+/**
+ * True when the pure projection would list zero candidates (honesty helper for tests).
+ */
+export function hasNoDeepeningEvidence(input) {
+    return buildDeepeningCandidates(input).candidates.length === 0;
+}

package/bin/lib/doctor-plan.mjs

@@ -66,6 +66,10 @@ import {
   buildDoctorImprovementCompass,
   printImprovementCompassSection,
 } from './improvement-compass-doctor.mjs';
+import {
+  buildDeepModuleCoachAdvisory,
+  printDeepModuleCoachSection,
+} from './deep-module-coach.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -660,6 +664,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     goldenPatternPresent: goldenPattern.present === true,
     arkRulesLoaded: rulesUnderContract?.active === true,
   });
+  // Deep-module coach: hot paths + deepening candidates — advisory only (notAScore).
+  const deepModuleCoach = buildDeepModuleCoachAdvisory(root, {
+    designSmells,
+    physicalCohesion: doctorAdvisories.physicalCohesion,
+    improvementCompass,
+    pilotLoop,
+  });
 
   if (asJson) {
     (options.writeJson ?? console.log)(
@@ -677,6 +688,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             designSmells,
             // Improvement compass (lenses; notAScore; never a gate input).
             improvementCompass,
+            // Deep-module coach (hot paths + deepening; notAScore; never a gate input).
+            deepModuleCoach,
             ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
@@ -870,6 +883,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
 
   printImprovementCompassSection(improvementCompass, { line, warn, ok, color });
+  printDeepModuleCoachSection(deepModuleCoach, { line, warn, ok, color });
 
   console.log('');
   console.log(color.bold('Design fitness'));

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

@@ -279,11 +279,44 @@ function improvementCompassHtml(compass) {
   </section>`;
 }
 
+/** Deep-module coach — hot paths + deepening candidates; never a gate input. */
+function deepModuleCoachHtml(coach) {
+  if (!coach || coach.notAScore !== true) return '';
+  const hot = coach.hotPaths;
+  const candidates = Array.isArray(coach.deepeningCandidates) ? coach.deepeningCandidates : [];
+  let hotBlock = '';
+  if (hot?.status === 'unavailable') {
+    hotBlock = `<p class="muted">Hot paths: unavailable — ${esc(hot.reason || 'no git history')}; never invented.</p>`;
+  } else if (hot?.available === true && Array.isArray(hot.paths) && hot.paths.length > 0) {
+    hotBlock = `<p><span class="tag warn">hot paths</span> ${hot.paths
+      .slice(0, 8)
+      .map((p) => `<code>${esc(p.path)}</code> (${esc(String(p.changeCount))})`)
+      .join(' · ')}</p>`;
+  } else {
+    hotBlock = '<p class="muted">Hot paths: none above churn threshold (advisory).</p>';
+  }
+  const deepenBlock =
+    candidates.length === 0
+      ? '<p class="muted">Deepening candidates: none from existing evidence (not a score).</p>'
+      : `<p><span class="tag warn">deepening</span> ${candidates
+          .slice(0, 5)
+          .map((c) => `<code>${esc(c.target)}</code> — ${esc(c.friction)}`)
+          .join('<br/>')}</p>`;
+  return `
+  <section class="section card" data-advisory="deepModuleCoach">
+    <h2>Deep-module coach <span class="muted">(advisory — never changes the verdict)</span></h2>
+    ${hotBlock}
+    ${deepenBlock}
+    <p class="muted">Prefer deep modules; name seams; test at the public interface. Always <code>notAScore</code>.</p>
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
   return [
     improvementCompassHtml(advisories.improvementCompass),
+    deepModuleCoachHtml(advisories.deepModuleCoach),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

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

@@ -22,6 +22,7 @@ import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
+import { buildDeepModuleCoachAdvisory } from './deep-module-coach.mjs';
 import { computePhysicalCohesion } from './physical-cohesion.mjs';
 
 function esc(value) {
@@ -178,6 +179,13 @@ export function buildReportDepthPayload(
     goldenPatternPresent: goldenPattern.present === true,
     arkRulesLoaded: rulesUnderContract?.active === true,
   });
+  // Deep-module coach — same advisory as doctor; never a gate input.
+  const deepModuleCoach = buildDeepModuleCoachAdvisory(root, {
+    designSmells,
+    physicalCohesion,
+    improvementCompass,
+    pilotLoop,
+  });
   return {
     adoption,
     designDepth: {
@@ -190,6 +198,7 @@ export function buildReportDepthPayload(
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
       improvementCompass,
+      deepModuleCoach,
     },
   };
 }

package/bin/lib/managed-upgrade.mjs

@@ -8,6 +8,10 @@ import {
   formatManagedUpgradeSelfServiceHonesty,
   projectManagedUpgradeSelfServiceHonesty,
 } from './managed-upgrade-honesty.mjs';
+import {
+  buildUpgradeWhatsNewSuggestions,
+  formatUpgradeWhatsNewSuggestions,
+} from './upgrade-whats-new.mjs';
 import {
   KNOWN_TOOLS,
   arkPackageVersion,
@@ -21,6 +25,11 @@ export {
   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';
@@ -456,11 +465,19 @@ export function planManagedUpgrade(root, options = {}) {
           kind: catalogAsset.kind,
         });
     const accepted = options.acceptConflicts === true;
+    // FX04: --refresh-skills opt-in rewrites customized *skill* assets to package
+    // templates. Conflicted still needs --accept-conflicts. Never silent default.
+    const refreshSkills = options.refreshSkills === true;
+    const skillRefresh =
+      refreshSkills &&
+      catalogAsset.kind === 'skill' &&
+      classified.state === 'customized';
     const canApply =
       classified.state === 'stale' ||
+      skillRefresh ||
       (classified.state === 'missing' && (!recorded || accepted)) ||
       (classified.state === 'conflicted' && accepted);
-    const blocked = classified.requiresConsent && !accepted;
+    const blocked = classified.requiresConsent && !accepted && !skillRefresh;
     const desiredFile = afterFileContent(catalogAsset, currentFile, desiredScoped);
     const asset = {
       path: catalogAsset.relativePath,
@@ -533,6 +550,7 @@ export function planManagedUpgrade(root, options = {}) {
     profile: selection.profile,
     hosts: selection.hosts,
     acceptConflicts: options.acceptConflicts === true,
+    refreshSkills: options.refreshSkills === true,
     assets,
     summary,
     nextManifest,
@@ -543,6 +561,183 @@ export function planManagedUpgrade(root, options = {}) {
   return plan;
 }
 
+/**
+ * FX03 — skill content drift honesty (counts by state + sample paths).
+ * Skills only; never claims "skills upgraded" when only package pin moved.
+ */
+export function buildSkillDriftSummary(plan) {
+  const assets = Array.isArray(plan?.assets) ? plan.assets : [];
+  const skills = assets.filter((a) => a?.kind === 'skill');
+  const byState = {};
+  for (const skill of skills) {
+    const state = typeof skill.state === 'string' ? skill.state : 'unknown';
+    byState[state] = (byState[state] ?? 0) + 1;
+  }
+  const sample = (state, limit = 5) =>
+    skills
+      .filter((s) => s.state === state)
+      .map((s) => s.path)
+      .sort()
+      .slice(0, limit);
+  const customized = byState.customized ?? 0;
+  const stale = byState.stale ?? 0;
+  const missing = byState.missing ?? 0;
+  const current = byState.current ?? 0;
+  const wouldRefresh = skills.filter((s) => s.willApply === true).length;
+  return {
+    schemaVersion: '1.0',
+    notAScore: true,
+    skillCount: skills.length,
+    byState,
+    stale,
+    customized,
+    missing,
+    current,
+    wouldRefresh,
+    samplePaths: {
+      stale: sample('stale'),
+      customized: sample('customized'),
+      missing: sample('missing'),
+    },
+    note:
+      customized > 0 && wouldRefresh === 0
+        ? 'Skills on disk differ from package templates (customized preserved). Use --refresh-skills to opt in to rewrite customized skills; never silent overwrite.'
+        : stale > 0
+          ? 'Some skills are stale vs package templates and will refresh on apply.'
+          : skills.length === 0
+            ? 'No managed skill assets in this upgrade selection.'
+            : 'Skill content matches package templates or is scheduled for write.',
+  };
+}
+
+/**
+ * FX07 — active host vs managed --tools / manifest hosts.
+ */
+export function buildHostSelectionHonesty(plan) {
+  const hosts = Array.isArray(plan?.hosts) ? plan.hosts.map((h) => String(h).toLowerCase()) : [];
+  let active = null;
+  try {
+    active = detectActiveAgentHost();
+  } catch {
+    active = null;
+  }
+  const activeNorm =
+    typeof active === 'string' && active.trim() ? active.trim().toLowerCase() : null;
+  const known = activeNorm && KNOWN_TOOLS.includes(activeNorm);
+  const inSelection = Boolean(activeNorm && hosts.includes(activeNorm));
+  const note =
+    known && !inSelection
+      ? `Detected host "${activeNorm}" is not in managed tools [${hosts.join(', ') || 'none'}]. Re-run with --tools ${[...new Set([...hosts, activeNorm])].sort().join(',')} so that host's skills/hooks are in the plan.`
+      : known && inSelection
+        ? `Detected host "${activeNorm}" is in the managed selection.`
+        : activeNorm
+          ? `Detected host "${activeNorm}" is outside the known managed tool set.`
+          : 'No active agent host detected for this process.';
+  return {
+    schemaVersion: '1.0',
+    notAScore: true,
+    activeHost: activeNorm,
+    managedHosts: hosts,
+    activeInSelection: inSelection,
+    suggestTools:
+      known && !inSelection
+        ? [...new Set([...hosts, activeNorm])].sort().join(',')
+        : null,
+    note,
+  };
+}
+
+/**
+ * FX05 — post-upgrade verification block (advisory sensors only).
+ */
+export function buildPostUpgradeChecks(root, options = {}) {
+  const resolvedRoot = path.resolve(root);
+  const checks = [];
+  let projectVersion = null;
+  try {
+    const pkgPath = path.join(resolvedRoot, 'node_modules', 'arkgate', 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      projectVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version ?? null;
+    }
+  } catch {
+    projectVersion = null;
+  }
+  const cli = typeof options.cliVersion === 'string' ? options.cliVersion : arkPackageVersion();
+  const pinOk =
+    projectVersion != null && cli != null ? projectVersion === cli : null;
+  checks.push({
+    id: 'package-pin-cli',
+    ok: pinOk,
+    detail:
+      pinOk === true
+        ? `Installed arkgate@${projectVersion} matches CLI ${cli}.`
+        : pinOk === false
+          ? `Installed arkgate@${projectVersion} ≠ CLI ${cli}; re-run install or restart using project-local CLI.`
+          : `Could not compare pin (installed=${projectVersion ?? 'missing'}, cli=${cli ?? 'unknown'}).`,
+  });
+  checks.push({
+    id: 'architecture-verification',
+    ok:
+      options.verification?.mode === 'skipped'
+        ? null
+        : options.verification?.exitCode === 0,
+    detail:
+      options.verification?.mode === 'skipped'
+        ? 'Strict architecture verification was skipped (--no-strict).'
+        : options.verification?.exitCode === 0
+          ? 'Strict-merge architecture verification passed.'
+          : `Architecture verification exit ${options.verification?.exitCode ?? 'unknown'}.`,
+  });
+  checks.push({
+    id: 'package-version-truth',
+    ok: options.dualTruth?.dualTruth === true ? false : options.dualTruth ? true : null,
+    detail:
+      options.dualTruth?.dualTruth === true
+        ? options.dualTruth.note || 'Package pin dual-truth detected.'
+        : options.dualTruth
+          ? 'Package pin truth is consistent for this apply.'
+          : 'Package version truth not evaluated.',
+  });
+  checks.push({
+    id: 'doctor-compass-coach',
+    ok: null,
+    detail:
+      'Run `npx arkgate-check --doctor --json` and confirm doctor.improvementCompass + doctor.deepModuleCoach (notAScore).',
+  });
+  checks.push({
+    id: 'agents-md-projection',
+    ok: null,
+    detail: 'Run `npx arkgate agents-md --check` (or --write) so AGENTS.md matches the package projection.',
+  });
+  checks.push({
+    id: 'status-mode',
+    ok: null,
+    detail: 'Run `npx arkgate status --json` and read honesty mode; incomplete facts never invent green residual.',
+  });
+  return {
+    schemaVersion: '1.0',
+    notAScore: true,
+    neverGateInput: true,
+    checks,
+    mcpNote:
+      'If you used Ark MCP this session: restart/retarget MCP after package bump so process arkgateVersion matches project install; always pass project.expectedRoot + expectedProjectId (WI01). Prefer project-local CLI until identity matched and versions align.',
+  };
+}
+
+export function formatSkillDriftHuman(skillDrift) {
+  if (!skillDrift) return [];
+  const lines = [
+    `Skill drift: ${skillDrift.skillCount} skill(s) — current ${skillDrift.current}, stale ${skillDrift.stale}, customized ${skillDrift.customized}, missing ${skillDrift.missing}, would refresh ${skillDrift.wouldRefresh}.`,
+  ];
+  if (skillDrift.note) lines.push(`  ${skillDrift.note}`);
+  return lines;
+}
+
+export function formatHostSelectionHuman(hostSelection) {
+  if (!hostSelection?.note) return [];
+  return [`Host selection: ${hostSelection.note}`];
+}
+
 function publicPlan(plan, overrides = {}) {
   const assets = plan.assets.map(
     ({ containerBeforeHash: _container, [AFTER_CONTENT]: _content, ...asset }) => asset
@@ -567,11 +762,15 @@ function publicPlan(plan, overrides = {}) {
     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,
   };
 }
 
@@ -771,6 +970,21 @@ export function renderManagedUpgrade(plan, options = {}) {
   for (const line of formatManagedUpgradeSelfServiceHonesty(honesty)) {
     console.log(line);
   }
+  const skillDrift =
+    options.skillDrift ?? plan.skillDrift ?? buildSkillDriftSummary(plan);
+  for (const line of formatSkillDriftHuman(skillDrift)) {
+    console.log(line);
+  }
+  const hostSelection =
+    options.hostSelection ?? plan.hostSelection ?? buildHostSelectionHonesty(plan);
+  for (const line of formatHostSelectionHuman(hostSelection)) {
+    console.log(line);
+  }
+  // FX08: whatsNew always on preview/apply human path (including nothing-to-apply).
+  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/rules-inventory.mjs

@@ -136,8 +136,29 @@ export function buildRulesInventory(input) {
             /_(?:OID|OIDS)$/i.test(name) ||
             /^(?:INT2|INT4|INT8|FLOAT4|FLOAT8|NUMERIC|DATE|TIME|TIMESTAMP|TIMESTAMPTZ|JSON|JSONB|UUID)OID$/i.test(name) ||
             /(?:^|_)(?:SCHEMA|PROTOCOL|RESOLVER|FORMAT)_(?:URL|URI|VERSION|ID|IDENTITY)$/i.test(name);
+        /**
+         * FX09 — pure UX copy / error-message string constants crowd inventory pilots.
+         * Downrank (skip) sentence-like strings and message-named identifiers; keep
+         * numeric thresholds and domain status tokens for adopt/contract pilots.
+         */
+        const isUxMessageConstant = (name, rawValue) => {
+            if (/^(?:ERROR|SUCCESS|WARNING|INFO|HINT|HELP|EMPTY|TOAST|SNACK|ALERT|BANNER|DIALOG|MODAL|TOOLTIP|CAPTION|SUBTITLE|HEADLINE|USER|UI|DISPLAY|FEEDBACK)_(?:MSG|MESSAGE|TEXT|COPY|LABEL|TITLE|BODY|DESC|DESCRIPTION|HINT|HELP)?/i.test(name) ||
+                /_(?:MSG|MESSAGE|TEXT|COPY|TOAST|SNACK|ALERT|BANNER|CAPTION|HINT|HELP_TEXT|ERROR_TEXT|EMPTY_TEXT|PLACEHOLDER_TEXT|USER_MESSAGE|FEEDBACK)$/i.test(name)) {
+                return true;
+            }
+            const unquoted = rawValue.replace(/^['"]|['"]$/g, '');
+            // Sentence-like string values (spaces or terminal punctuation) are UX copy,
+            // not behavioral business limits — unless the name is a clear domain status seed.
+            if (/^['"]/.test(rawValue) &&
+                (/\s/.test(unquoted) || /[.!?…]$/.test(unquoted)) &&
+                !/^(?:STATUS|STATE|PHASE|ROLE|TYPE|KIND|ORDER|PAYMENT|CART|INVOICE|POLICY)_[A-Z0-9_]+$/i.test(name)) {
+                return true;
+            }
+            return false;
+        };
         while ((magic = magicRe.exec(content)) !== null) {
             const name = magic[2];
+            const rawValue = magic[3] ?? '';
             // With governed layer evidence, generic Tooling/Kernel constants are not
             // business-rule candidates. Controller-shaped boundaries stay eligible
             // because business policy can leak into them.
@@ -145,6 +166,8 @@ export function buildRulesInventory(input) {
                 continue;
             if (isInfraMagicName(name))
                 continue;
+            if (isUxMessageConstant(name, rawValue))
+                continue;
             // P2-N: skip remaining ALL_CAPS noise only on clear UI chrome (not all of app/).
             if (isUiChrome && !isDomain)
                 continue;