arkgate 2.13.0 → 3.0.1

package/bin/lib/design-smells.mjs

@@ -0,0 +1,434 @@
+/**
+ * Deterministic design-smell sensors (Phase P / P02).
+ *
+ * Pure-ish filesystem heuristics: contract edges can be clean while lived design
+ * is weak (god modules, I/O in routes, concurrent layouts). Never invents
+ * mechanical-safe remediations — smells feed doctor honesty + plan B only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { layerForFile } from '../ark-shared.mjs';
+import { detectContractFalseGreenRisk } from './field-install.mjs';
+
+/** Stable smell ids (doctor JSON + plan B + skills). */
+export const DESIGN_SMELL_IDS = Object.freeze([
+  'io-under-application',
+  'handler-in-persistence',
+  'god-module',
+  'domain-logic-in-ui',
+  'facade-sql-in-routes',
+  'mixed-pattern-cluster',
+  'soft-contract',
+]);
+
+const IO_IMPORT_RE =
+  /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|better-sqlite3|ioredis|redis)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm)/;
+const HANDLER_CONTENT_RE =
+  /\b(?:@Controller|@Get|@Post|@Put|@Delete|Router\(\)|createRouter|express\.Router|fastify\.(?:get|post)|export\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b|export\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=)/;
+const DOMAIN_LOGIC_UI_RE =
+  /\b(?:export\s+)?(?:async\s+)?function\s+(?:can|calculate|compute|should)[A-Z]\w*|\b(?:export\s+)?const\s+(?:can|calculate|compute|should)[A-Z]\w*\s*=/;
+const EXPORT_RE =
+  /\bexport\s+(?:async\s+)?(?:function|class|const|let|var|type|interface|enum|default)\b|\bexport\s*\{/g;
+
+const PERSISTENCE_PATH_RE =
+  /(?:^|\/)(?:repositories?|persistence|infra\/(?:db|data|persistence)|adapters\/(?:persistence|repository)|data-access)(?:\/|$)/i;
+const UI_PATH_RE =
+  /(?:^|\/)(?:components?|pages|hooks|ui|views|screens|app\/(?:\(.*\)\/)?[^/]+\/page\.|app\/.*\/page\.)/i;
+const ROUTE_PATH_RE =
+  /(?:^|\/)(?:routes?|controllers?|api\/|pages\/api\/|app\/api\/|handlers?)(?:\/|$)|(?:route|controller|handler)\.(?:ts|tsx|js|jsx)$/i;
+
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_SCAN_FILES = 800;
+const GOD_LOC = 400;
+const GOD_EXPORTS = 12;
+
+function normalizeRel(root, filePath) {
+  const abs = path.isAbsolute(filePath) ? filePath : path.join(root, filePath);
+  let rel = path.relative(root, abs).split(path.sep).join('/');
+  if (rel.startsWith('./')) rel = rel.slice(2);
+  return rel;
+}
+
+function readTextLimited(absPath) {
+  try {
+    const st = fs.statSync(absPath);
+    if (!st.isFile() || st.size === 0 || st.size > MAX_FILE_BYTES) return null;
+    return fs.readFileSync(absPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function countExports(source) {
+  if (!source) return 0;
+  const matches = source.match(EXPORT_RE);
+  return matches ? matches.length : 0;
+}
+
+function countLines(source) {
+  if (!source) return 0;
+  let n = 1;
+  for (let i = 0; i < source.length; i += 1) {
+    if (source.charCodeAt(i) === 10) n += 1;
+  }
+  return n;
+}
+
+function layerNameFor(root, rel, config) {
+  try {
+    // CLI layerForFile(root, file, layers) — file may be absolute or relative.
+    return layerForFile(root, rel, config?.layers ?? []) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isApplicationLayer(name) {
+  return typeof name === 'string' && /application|orchestr/i.test(name);
+}
+
+function isPresentationLayer(name) {
+  return typeof name === 'string' && /presentation|ui|view/i.test(name);
+}
+
+function isPersistenceLayer(name) {
+  return (
+    typeof name === 'string' &&
+    (/persist|repository|infra|data.?access/i.test(name) || name === 'PersistenceAdapters')
+  );
+}
+
+/**
+ * @typedef {object} DesignSmell
+ * @property {string} id
+ * @property {'warn'|'info'} severity
+ * @property {string} message
+ * @property {string[]} evidence
+ * @property {string} fix
+ */
+
+/**
+ * Detect design smells for a project tree.
+ *
+ * @param {string} root
+ * @param {object} config ark.config
+ * @param {string[]} files absolute or root-relative source paths
+ * @param {object|null} coverage computeCoverage result (optional)
+ * @returns {DesignSmell[]}
+ */
+export function detectDesignSmells(root, config, files = [], coverage = null) {
+  const smells = [];
+  const resolvedRoot = path.resolve(root);
+  const relFiles = [];
+  for (const f of files.slice(0, MAX_SCAN_FILES)) {
+    const rel = normalizeRel(resolvedRoot, f);
+    if (!rel || rel.startsWith('..')) continue;
+    if (!/\.(ts|tsx|js|jsx|mts|cts)$/.test(rel)) continue;
+    if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
+    relFiles.push(rel);
+  }
+
+  // soft-contract: layers with files but no rule edges
+  const withoutRules = Array.isArray(coverage?.layersWithoutRules)
+    ? coverage.layersWithoutRules
+    : [];
+  if (withoutRules.length > 0) {
+    smells.push({
+      id: 'soft-contract',
+      severity: 'warn',
+      message: `Layers classify files but have no deny/allow rule edges: ${withoutRules.join(', ')}. Soft green — peer leaks may go unchecked.`,
+      evidence: withoutRules.map((n) => `layer:${n}`),
+      fix: 'Add rules via /ark-contract (or a policy pack) so every populated layer participates in enforcement.',
+    });
+  }
+
+  // Classic false-green I/O under Application (reuse detector when coverage present)
+  const falseGreen = detectContractFalseGreenRisk(resolvedRoot, config, coverage ?? {});
+  if (falseGreen?.risk) {
+    smells.push({
+      id: 'io-under-application',
+      severity: 'warn',
+      message: falseGreen.message,
+      evidence: (falseGreen.ioPaths || []).slice(0, 12),
+      fix: falseGreen.fix,
+    });
+  }
+
+  const godEvidence = [];
+  const handlerInPersist = [];
+  const domainInUi = [];
+  const facadeSql = [];
+  const ioUnderAppFiles = [];
+
+  let hasFeaturesLayout = false;
+  let hasFlatServices = false;
+  let hasHexPorts = false;
+
+  for (const rel of relFiles) {
+    if (/\/features\/[^/]+\//.test(rel) || /^features\//.test(rel)) hasFeaturesLayout = true;
+    if (/\/(?:services|modules)\/[^/]+\//.test(rel) || /(?:^|\/)services\/[^/]+\.(?:ts|tsx)$/.test(rel)) {
+      hasFlatServices = true;
+    }
+    if (/\/(?:domain|application|infrastructure|adapters)\//.test(rel)) hasHexPorts = true;
+
+    const abs = path.join(resolvedRoot, rel);
+    const source = readTextLimited(abs);
+    if (source == null) continue;
+
+    const layer = layerNameFor(resolvedRoot, rel, config);
+    const loc = countLines(source);
+    const exportsCount = countExports(source);
+
+    if (loc >= GOD_LOC && exportsCount >= GOD_EXPORTS) {
+      godEvidence.push(rel);
+    }
+
+    if (
+      (PERSISTENCE_PATH_RE.test(rel) || isPersistenceLayer(layer)) &&
+      HANDLER_CONTENT_RE.test(source)
+    ) {
+      handlerInPersist.push(rel);
+    }
+
+    if ((UI_PATH_RE.test(rel) || isPresentationLayer(layer)) && DOMAIN_LOGIC_UI_RE.test(source)) {
+      domainInUi.push(rel);
+    }
+
+    if (ROUTE_PATH_RE.test(rel) && IO_IMPORT_RE.test(source)) {
+      facadeSql.push(rel);
+    }
+
+    if (
+      !falseGreen?.risk &&
+      isApplicationLayer(layer) &&
+      IO_IMPORT_RE.test(source) &&
+      !/port|adapter|repository/i.test(path.basename(rel))
+    ) {
+      ioUnderAppFiles.push(rel);
+    }
+  }
+
+  if (!falseGreen?.risk && ioUnderAppFiles.length > 0) {
+    smells.push({
+      id: 'io-under-application',
+      severity: 'warn',
+      message: `Application-layer files import database/client SDKs directly (${ioUnderAppFiles.length} file(s)). Prefer ports in Domain + adapters outside Application.`,
+      evidence: ioUnderAppFiles.slice(0, 12),
+      fix: 'Extract a port + adapter (extraction card); do not weaken ark.config to silence the smell.',
+    });
+  }
+
+  if (handlerInPersist.length > 0) {
+    smells.push({
+      id: 'handler-in-persistence',
+      severity: 'warn',
+      message: `HTTP/route handler shape found under persistence/repository paths (${handlerInPersist.length} file(s)) — semantic false-green risk.`,
+      evidence: handlerInPersist.slice(0, 12),
+      fix: 'Move handlers to Presentation/API; keep Persistence as data access only (/ark-explore shape-focus).',
+    });
+  }
+
+  if (godEvidence.length > 0) {
+    smells.push({
+      id: 'god-module',
+      severity: 'warn',
+      message: `God-module candidates: large files with wide export surfaces (${godEvidence.length} file(s), ≥${GOD_LOC} LOC and ≥${GOD_EXPORTS} exports).`,
+      evidence: godEvidence.slice(0, 12),
+      fix: 'Split by concern with a pilot cluster; keep gate rules; use dual-plan B extraction card.',
+    });
+  }
+
+  if (domainInUi.length > 0) {
+    smells.push({
+      id: 'domain-logic-in-ui',
+      severity: 'warn',
+      message: `Business-style can*/calculate*/compute* helpers live under UI/presentation paths (${domainInUi.length} file(s)).`,
+      evidence: domainInUi.slice(0, 12),
+      fix: 'Move pure rules into Domain (or shared pure module under Domain globs) and import from UI.',
+    });
+  }
+
+  if (facadeSql.length > 0) {
+    smells.push({
+      id: 'facade-sql-in-routes',
+      severity: 'warn',
+      message: `Route/controller files import ORM/SQL clients directly (${facadeSql.length} file(s)).`,
+      evidence: facadeSql.slice(0, 12),
+      fix: 'Relocate query bytes into a repository/adapter; routes call a port — extraction card; no schema rewrite.',
+    });
+  }
+
+  // mixed-pattern: vertical-slice features coexisting with flat services and/or hex folders
+  const patternHits = [hasFeaturesLayout, hasFlatServices, hasHexPorts].filter(Boolean).length;
+  if (patternHits >= 2 && relFiles.length >= 8) {
+    const evidence = [];
+    if (hasFeaturesLayout) evidence.push('layout:features/*');
+    if (hasFlatServices) evidence.push('layout:services/*');
+    if (hasHexPorts) evidence.push('layout:hex-domain-application-infra');
+    smells.push({
+      id: 'mixed-pattern-cluster',
+      severity: 'info',
+      message:
+        'Concurrent design patterns detected in the tree (slice features vs flat services vs hex folders). Pick a golden pattern and pilot migrate-on-touch.',
+      evidence,
+      fix: 'Run /ark-explore shape-focus; mark golden vs legacy; dual-plan B with pilot + kill-switch.',
+    });
+  }
+
+  // Stable order by id for snapshots
+  const order = new Map(DESIGN_SMELL_IDS.map((id, i) => [id, i]));
+  smells.sort((a, b) => (order.get(a.id) ?? 99) - (order.get(b.id) ?? 99));
+  return smells;
+}
+
+/**
+ * Whether edge-clean ENFORCE should still report design-weak residual.
+ *
+ * @param {DesignSmell[]} smells
+ * @param {{ activeViolations?: number, governedPercent?: number|null, totalFiles?: number|null }} ctx
+ */
+export function isDesignWeak(smells, ctx = {}) {
+  const active = ctx.activeViolations ?? 0;
+  const total = ctx.totalFiles ?? null;
+  const gov = ctx.governedPercent ?? null;
+  if (active > 0) return false;
+  if (total === 0) return false;
+  if (gov != null && gov < 50) return false;
+  return Array.isArray(smells) && smells.length > 0;
+}
+
+/**
+ * Design fitness summary for doctor JSON / human.
+ */
+export function summarizeDesignFitness(smells, ctx = {}) {
+  const designWeak = isDesignWeak(smells, ctx);
+  return {
+    status: designWeak ? 'design-weak' : smells.length > 0 ? 'smells-with-open-edges' : 'ok',
+    designWeak,
+    smellCount: Array.isArray(smells) ? smells.length : 0,
+    ids: (smells || []).map((s) => s.id),
+    label: designWeak
+      ? 'ENFORCE · design-weak — edges clean; Shape residual remains (see designSmells / plan B)'
+      : smells.length > 0
+        ? 'Design smells present alongside open edge debt'
+        : 'No deterministic design smells detected',
+  };
+}
+
+/**
+ * Build plan-B pattern bets from smells (P03). Never mechanical-safe.
+ *
+ * @param {DesignSmell[]} smells
+ * @returns {object[]}
+ */
+export function buildPatternBetsFromSmells(smells = []) {
+  const bets = [];
+  for (const smell of smells) {
+    const pilot =
+      (smell.evidence || []).find((e) => e && !e.startsWith('layer:') && !e.startsWith('layout:')) ||
+      (smell.evidence || [])[0] ||
+      'src/**';
+    bets.push({
+      id: `pattern-b:${smell.id}`,
+      smellId: smell.id,
+      pilot: typeof pilot === 'string' ? pilot.replace(/\/[^/]+$/, '/**') : 'src/**',
+      evidence: (smell.evidence || []).slice(0, 8),
+      successSignal: successSignalFor(smell.id),
+      killSwitch: killSwitchFor(smell.id),
+      neverMechanicalSafe: true,
+      class: 'judgment',
+      fix: smell.fix,
+      message: smell.message,
+    });
+  }
+  // Cap at 5 (explore dual-plan B limit)
+  return bets.slice(0, 5);
+}
+
+function successSignalFor(id) {
+  switch (id) {
+    case 'io-under-application':
+      return '0 Application-layer files import prisma/supabase/drizzle/pg clients; I/O behind ports';
+    case 'handler-in-persistence':
+      return '0 HTTP handler shapes under persistence/repository globs';
+    case 'god-module':
+      return 'Pilot god module split; fan-in and export surface reduced without new edge violations';
+    case 'domain-logic-in-ui':
+      return 'can*/calculate* pure rules live under Domain; UI imports them only';
+    case 'facade-sql-in-routes':
+      return '0 route/controller files import ORM/SQL clients; queries in adapters';
+    case 'mixed-pattern-cluster':
+      return 'Golden pattern named; pilot cluster migrated; legacy migrate-on-touch';
+    case 'soft-contract':
+      return 'Every populated layer has at least one rule edge in ark.config.json';
+    default:
+      return 'Smell evidence paths cleared on pilot without weakening the contract';
+  }
+}
+
+function killSwitchFor(id) {
+  switch (id) {
+    case 'mixed-pattern-cluster':
+      return 'If pilot does not reduce confusion in 2 real PRs, keep one layout without adding a layer wall';
+    case 'god-module':
+      return 'If split increases coupling, stop after one pilot and prefer seam extraction only';
+    default:
+      return 'If pilot increases edge violations without design clarity, stop and re-map with /ark-explore';
+  }
+}
+
+/**
+ * Honesty guard (P03/P04): refuse “healthy finished” claims when design residual remains.
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
+export function assertNotHealthyFinishedIgnoringDesign(planOrDoctor) {
+  const designWeak =
+    planOrDoctor?.goal?.designWeak === true ||
+    planOrDoctor?.designFitness?.designWeak === true;
+  const bets =
+    planOrDoctor?.patternBets?.length ??
+    planOrDoctor?.goal?.patternBetCount ??
+    0;
+  const smells =
+    planOrDoctor?.designSmells?.length ?? planOrDoctor?.designFitness?.smellCount ?? 0;
+  const edgesMet =
+    planOrDoctor?.goal?.met === true ||
+    (planOrDoctor?.operatingMode === 'enforce' &&
+      (planOrDoctor?.violations?.active ?? 0) === 0);
+
+  if (edgesMet && (designWeak || bets > 0 || smells > 0)) {
+    return {
+      ok: false,
+      error:
+        'Cannot claim architecture healthy finished: edge goal.met/ENFORCE coexists with design-weak residual (designSmells / patternBets). Use dual-plan B; never auto-apply pattern bets.',
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * patternBets must never appear as mechanical-safe kinds (loop / autoPatch).
+ * @param {object[]} patternBets
+ * @param {string[]} mechanicalSafeKinds from remediation.MECHANICAL_SAFE_KINDS
+ */
+export function assertPatternBetsNeverMechanicalSafe(patternBets, mechanicalSafeKinds = []) {
+  const safe = new Set(mechanicalSafeKinds);
+  for (const bet of patternBets || []) {
+    if (bet.neverMechanicalSafe !== true) {
+      return {
+        ok: false,
+        error: `patternBet ${bet.id} missing neverMechanicalSafe: true`,
+      };
+    }
+    if (bet.class === 'mechanical-safe') {
+      return { ok: false, error: `patternBet ${bet.id} has class mechanical-safe` };
+    }
+    if (bet.remediationKind && safe.has(bet.remediationKind)) {
+      return {
+        ok: false,
+        error: `patternBet ${bet.id} uses mechanical-safe remediationKind ${bet.remediationKind}`,
+      };
+    }
+  }
+  return { ok: true };
+}

package/bin/lib/doctor-plan.mjs

@@ -25,6 +25,12 @@ import {
   violationEdge,
 } from './violations.mjs';
 import { buildUnclassifiedSuggestions } from './suggestions.mjs';
+import {
+  detectDesignSmells,
+  buildPatternBetsFromSmells,
+  summarizeDesignFitness,
+  isDesignWeak,
+} from './design-smells.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -142,7 +148,25 @@ export function runCoverage(root, config, files, rules, asJson) {
 // Co-pilot Phase F — turn active violations into a classified, ordered remediation PLAN with an
 // embedded GOAL. This is the `plan` primitive the future apply-loop (Phase H, `loop`) consumes
 // and the autopilot (Phase I) drives toward the `goal`. Read-only: it changes no files.
-export function buildRemediationPlan(root, activeViolations, governedPercent = null, totalFiles = null) {
+/**
+ * @param {string} root
+ * @param {object[]} activeViolations
+ * @param {number|null} [governedPercent]
+ * @param {number|null} [totalFiles]
+ * @param {object} [options]
+ * @param {object[]} [options.designSmells]
+ * @param {object[]} [options.patternBets]
+ * @param {object} [options.config]
+ * @param {string[]} [options.files]
+ * @param {object} [options.coverage]
+ */
+export function buildRemediationPlan(
+  root,
+  activeViolations,
+  governedPercent = null,
+  totalFiles = null,
+  options = {}
+) {
   // A plan with 0 violations but ~0% governed (or ZERO files in scope) is a FALSE green:
   // nothing is actually being checked. Treat as "not done — classify / fix include first."
   const governedLow = governedPercent != null && governedPercent < 50;
@@ -177,20 +201,54 @@ export function buildRemediationPlan(root, activeViolations, governedPercent = n
     judgment: countOf('judgment'),
     deferred: countOf('deferred'),
   };
+
+  // Plan B (pattern bets) — never mechanical-safe; additive within major (P03).
+  let designSmells = options.designSmells;
+  if (!designSmells && options.config && options.files) {
+    designSmells = detectDesignSmells(
+      root,
+      options.config,
+      options.files,
+      options.coverage ?? null
+    );
+  }
+  designSmells = designSmells ?? [];
+  const patternBets =
+    options.patternBets ?? buildPatternBetsFromSmells(designSmells);
+  const edgesMet = activeViolations.length === 0 && !notHonestlyEnforced;
+  const designWeak = isDesignWeak(designSmells, {
+    activeViolations: activeViolations.length,
+    governedPercent,
+    totalFiles,
+  });
+
+  let statement =
+    activeViolations.length > 0
+      ? `Resolve ${activeViolations.length} architecture violation(s) without weakening the contract.`
+      : emptyScope
+        ? 'No source files matched the contract include paths — this "clean" result checks nothing. Fix include/layers (monorepo → apps/packages, or /ark-adopt) so Ark has real code to govern.'
+        : governedLow
+          ? `No violations — but Ark governs only ${governedPercent}% of your code, so this "clean" result checks almost nothing. Classify the rest (ark-check --coverage, then /ark-adopt) so it's actually enforced.`
+          : 'No active violations — the architecture already meets its contract.';
+  if (designWeak) {
+    statement =
+      'No active edge violations — contract edges are clean, but design smells remain (ENFORCE · design-weak). Shape residual is plan B only; not healthy finished.';
+  }
+
   return {
     version: '1',
     goal: {
-      statement:
-        activeViolations.length > 0
-          ? `Resolve ${activeViolations.length} architecture violation(s) without weakening the contract.`
-          : emptyScope
-            ? 'No source files matched the contract include paths — this "clean" result checks nothing. Fix include/layers (monorepo → apps/packages, or /ark-adopt) so Ark has real code to govern.'
-            : governedLow
-              ? `No violations — but Ark governs only ${governedPercent}% of your code, so this "clean" result checks almost nothing. Classify the rest (ark-check --coverage, then /ark-adopt) so it's actually enforced.`
-              : 'No active violations — the architecture already meets its contract.',
-      // The loop's termination signal (Phase H): nothing left to remediate AND the contract
-      // actually governs real code. Empty scope or low coverage is not "met".
-      met: activeViolations.length === 0 && !notHonestlyEnforced,
+      statement,
+      // Edge remediation termination (Phase H). Design-weak does NOT flip met false
+      // (would break loop semantics) — it is reported separately for honesty.
+      met: edgesMet,
+      designWeak,
+      ...(designWeak
+        ? {
+            designWeakLabel:
+              'ENFORCE · design-weak — use patternBets / dual-plan B; never auto-apply as mechanical-safe',
+          }
+        : {}),
       ...(governedPercent != null ? { governedPercent } : {}),
       ...(totalFiles != null ? { totalFiles } : {}),
       ...(emptyScope ? { emptyScope: true } : {}),
@@ -198,17 +256,38 @@ export function buildRemediationPlan(root, activeViolations, governedPercent = n
       autoApplicable: counts.mechanicalSafe,
       needsDecision: counts.judgment,
       deferred: counts.deferred,
+      patternBetCount: patternBets.length,
     },
     counts,
     steps,
+    // Additive: pattern evolution bets derived from design smells (never auto).
+    patternBets,
+    designSmells,
   };
 }
 
 // `--plan`: print the classified remediation plan. Dual-focus output — a one-line headline
 // anyone can read, then the per-step detail a developer acts on. Read-only.
-export function runPlan(root, activeViolations, asJson, governedPercent = null, totalFiles = null) {
-  const plan = buildRemediationPlan(root, activeViolations, governedPercent, totalFiles);
+/**
+ * @param {object} [options] optional { config, files, coverage, designSmells, patternBets }
+ */
+export function runPlan(
+  root,
+  activeViolations,
+  asJson,
+  governedPercent = null,
+  totalFiles = null,
+  options = {}
+) {
+  const plan = buildRemediationPlan(
+    root,
+    activeViolations,
+    governedPercent,
+    totalFiles,
+    options
+  );
   // Honesty: a zero-violation plan with almost nothing governed is NOT "ok".
+  // design-weak still ok:true for edge goal.met, but JSON carries designWeak + patternBets.
   const planOk = plan.goal.met === true;
   if (asJson) {
     console.log(JSON.stringify({ ok: planOk, plan }, null, 2));
@@ -217,6 +296,13 @@ export function runPlan(root, activeViolations, asJson, governedPercent = null,
   console.log(color.bold(`Ark plan — ${path.basename(path.resolve(root)) || '.'}`));
   console.log('');
   console.log(plan.goal.statement);
+  if (plan.goal.designWeak) {
+    console.log(
+      color.yellow(
+        `  ENFORCE · design-weak — ${plan.patternBets?.length ?? 0} pattern bet(s) (never auto-apply)`
+      )
+    );
+  }
   if (governedPercent != null) {
     const pctLabel =
       governedPercent < 50
@@ -224,6 +310,14 @@ export function runPlan(root, activeViolations, asJson, governedPercent = null,
         : color.dim(`Governed: ${governedPercent}% of in-scope files`);
     console.log(pctLabel);
   }
+  if (plan.patternBets?.length && activeViolations.length === 0) {
+    console.log('');
+    console.log(color.bold('Pattern bets (B) — judgment only'));
+    for (const bet of plan.patternBets.slice(0, 5)) {
+      console.log(`  [decide] ${bet.smellId}  ${color.dim(bet.pilot)}`);
+      console.log(color.dim(`           success: ${bet.successSignal}`));
+    }
+  }
   if (activeViolations.length === 0) return plan;
   console.log('');
   console.log(
@@ -245,7 +339,7 @@ export function runPlan(root, activeViolations, asJson, governedPercent = null,
   console.log('');
   console.log(
     color.dim(
-      'Plan only — no files changed. "auto" = an agent can safely apply it; "decide" = your call.'
+      'Plan only — no files changed. "auto" = an agent can safely apply it; "decide" = your call. patternBets are never auto.'
     )
   );
   return plan;
@@ -283,6 +377,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const activeCount = violations.length - suppressed;
   const missingSkills = skillGaps.reduce((sum, gap) => sum + gap.missing, 0);
   const staleSkills = skillGaps.reduce((sum, gap) => sum + gap.stale, 0);
+  const designSmells = detectDesignSmells(root, config, files, cov);
+  const designFitness = summarizeDesignFitness(designSmells, {
+    activeViolations: activeCount,
+    governedPercent: cov.governed.percent,
+    totalFiles: cov.governed.totalFiles,
+  });
 
   if (asJson) {
     console.log(
@@ -304,6 +404,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
                 return p ? p.files / total : null;
               })(),
             }),
+            // Path-correct ENFORCE can still be design-weak (P02).
+            designFitness,
+            designSmells,
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
@@ -412,7 +515,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     enforce:
       'Guard — contract coverage is honest and checked edges are clean. You do not pick this mode; you arrived here. Next: keep the host-appropriate write path and CI check on; only NEW violations should fail.',
   };
-  line(modeMark, `${mode.toUpperCase()} — ${modeHelp[mode]}`);
+  const modeTitle =
+    mode === 'enforce' && designFitness.designWeak
+      ? 'ENFORCE · design-weak'
+      : mode.toUpperCase();
+  line(
+    modeMark,
+    `${modeTitle} — ${
+      designFitness.designWeak
+        ? 'Guard on edges is honest, but design smells remain (Shape residual). You do not pick this mode. Next: /ark-explore dual-plan B or /ark-autopilot for pattern bets — never treat empty plan A as healthy finished.'
+        : modeHelp[mode]
+    }`
+  );
   if (emptyScope) {
     line(
       bad,
@@ -420,6 +534,25 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   }
 
+  console.log('');
+  console.log(color.bold('Design fitness'));
+  if (designSmells.length === 0) {
+    line(ok, designFitness.label);
+  } else {
+    line(designFitness.designWeak ? warn : warn, designFitness.label);
+    for (const smell of designSmells.slice(0, 5)) {
+      line(' ', color.dim(`[${smell.id}] ${smell.message}`));
+      if (smell.evidence?.length) {
+        line(' ', color.dim(`evidence: ${smell.evidence.slice(0, 4).join(', ')}`));
+      }
+    }
+    if (designFitness.designWeak) {
+      actions.push(
+        'shape residual: /ark-explore (shape-focus) or /ark-autopilot dual-plan B — pattern bets are never mechanical-safe'
+      );
+    }
+  }
+
   console.log('');
   console.log(color.bold('Coverage'));
   const govMark =