arkgate 3.0.2 → 3.0.4

package/bin/lib/design-smells.mjs

@@ -21,6 +21,51 @@ export const DESIGN_SMELL_IDS = Object.freeze([
   'soft-contract',
 ]);
 
+/**
+ * Q02 — outcome-oriented human language per smell id (newbie / vibecoder).
+ * Stable `id`s never change; technical detail stays in `message`.
+ */
+export const DESIGN_SMELL_OUTCOMES = Object.freeze({
+  'io-under-application':
+    'Business/application code reaches the database or external APIs directly — the AI will keep pasting I/O into the wrong place. Put data access behind a port/adapter.',
+  'handler-in-persistence':
+    'HTTP handlers live under data/repository folders — names look like “storage” but they are routes. Move handlers to the API/UI layer so the AI stops mixing transport and storage.',
+  'god-module':
+    'A few huge files own too many responsibilities — the AI cannot safely edit one concern without breaking others. Split the pilot file by job (one export surface per concern).',
+  'domain-logic-in-ui':
+    'Business rules (can*/calculate*/policy) sit in UI components — the AI will duplicate them in pages. Move pure rules into Domain (or a pure domain module) and import from the UI.',
+  'facade-sql-in-routes':
+    'Routes/controllers import the ORM or SQL client — the AI will keep growing “smart controllers.” Keep queries in a repository/adapter; routes only call that port.',
+  'mixed-pattern-cluster':
+    'The repo mixes several layout styles (features vs services vs hex folders) — the AI does not know where new code goes. Pick one golden pattern and migrate one pilot cluster on touch.',
+  'soft-contract':
+    'Some layers have files but almost no deny rules — the gate looks green while peers can still import freely. Add real layer rules so the AI has hard walls, not soft suggestions.',
+});
+
+/** @param {string} id */
+export function outcomeForSmellId(id) {
+  return (
+    DESIGN_SMELL_OUTCOMES[id] ||
+    'This design residual confuses where the AI should put new code. Clarify one home for this kind of change (see evidence paths) without weakening the gate.'
+  );
+}
+
+/**
+ * @param {{ id: string, severity?: string, message: string, evidence?: string[], fix?: string }} partial
+ */
+export function makeDesignSmell(partial) {
+  const id = partial.id;
+  return {
+    id,
+    severity: partial.severity ?? 'warn',
+    message: partial.message,
+    /** Plain-language outcome (Q02); prefer this for human doctor lines. */
+    outcome: outcomeForSmellId(id),
+    evidence: partial.evidence ?? [],
+    fix: partial.fix ?? '',
+  };
+}
+
 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 =
@@ -133,25 +178,29 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     ? 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.',
-    });
+    smells.push(
+      makeDesignSmell({
+        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,
-    });
+    smells.push(
+      makeDesignSmell({
+        id: 'io-under-application',
+        severity: 'warn',
+        message: falseGreen.message,
+        evidence: (falseGreen.ioPaths || []).slice(0, 12),
+        fix: falseGreen.fix,
+      })
+    );
   }
 
   const godEvidence = [];
@@ -209,53 +258,63 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
   }
 
   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.',
-    });
+    smells.push(
+      makeDesignSmell({
+        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).',
-    });
+    smells.push(
+      makeDesignSmell({
+        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.',
-    });
+    smells.push(
+      makeDesignSmell({
+        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.',
-    });
+    smells.push(
+      makeDesignSmell({
+        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.',
-    });
+    smells.push(
+      makeDesignSmell({
+        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
@@ -265,20 +324,25 @@ export function detectDesignSmells(root, config, files = [], coverage = null) {
     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.',
-    });
+    smells.push(
+      makeDesignSmell({
+        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;
+  // Ensure every smell carries outcome (defensive for partial callers).
+  return smells.map((s) =>
+    s.outcome ? s : makeDesignSmell({ id: s.id, severity: s.severity, message: s.message, evidence: s.evidence, fix: s.fix })
+  );
 }
 
 /**

package/bin/lib/doctor-plan.mjs

@@ -31,6 +31,13 @@ import {
   summarizeDesignFitness,
   isDesignWeak,
 } from './design-smells.mjs';
+import {
+  buildPostGreenNextAction,
+  mergePostGreenTopActions,
+  isDoctorHealthyNothingToDo,
+} from './post-green-path.mjs';
+import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
+import { summarizePilotLoop } from './pilot-loop.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -221,6 +228,12 @@ export function buildRemediationPlan(
     governedPercent,
     totalFiles,
   });
+  // Q04 — single next pilot extraction card (one at a time → re-doctor).
+  const pilotLoop = summarizePilotLoop({
+    designWeak,
+    patternBets,
+    designSmells,
+  });
 
   let statement =
     activeViolations.length > 0
@@ -263,6 +276,8 @@ export function buildRemediationPlan(
     // Additive: pattern evolution bets derived from design smells (never auto).
     patternBets,
     designSmells,
+    // Q04: one-pilot loop step (extraction card); never mechanical-safe.
+    pilotLoop,
   };
 }
 
@@ -318,6 +333,21 @@ export function runPlan(
       console.log(color.dim(`           success: ${bet.successSignal}`));
     }
   }
+  // Q04 — single next pilot (one at a time → re-doctor).
+  if (plan.pilotLoop?.active && plan.pilotLoop.nextPilot) {
+    console.log('');
+    console.log(color.bold('Next pilot (one at a time → re-doctor)'));
+    const np = plan.pilotLoop.nextPilot;
+    console.log(`  Pilot: ${np.pilotTarget || np.pilot}  [${np.smellId}]`);
+    console.log(color.dim(`  Move: ${np.move}`));
+    console.log(color.dim(`  Success: ${np.successSignal}`));
+    console.log(color.dim(`  Kill-switch: ${np.killSwitch}`));
+    console.log(
+      color.dim(
+        '  Apply this ONE pilot, then ark-check --doctor — never multi-pilot batch; never mechanical-safe.'
+      )
+    );
+  }
   if (activeViolations.length === 0) return plan;
   console.log('');
   console.log(
@@ -383,6 +413,17 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     governedPercent: cov.governed.percent,
     totalFiles: cov.governed.totalFiles,
   });
+  // Q01 — single post-green door when design-weak (map → B; no skill shopping).
+  const postGreenPath = buildPostGreenNextAction(designFitness);
+  // Q03 — optional golden pattern for NEW code (advisory; never clears design-weak).
+  const goldenPattern = summarizeGoldenPattern(loadGoldenPattern(root));
+  // Q04 — one next pilot (extraction card) when design-weak.
+  const patternBetsForLoop = buildPatternBetsFromSmells(designSmells);
+  const pilotLoop = summarizePilotLoop({
+    designWeak: designFitness.designWeak,
+    patternBets: patternBetsForLoop,
+    designSmells,
+  });
 
   if (asJson) {
     console.log(
@@ -407,6 +448,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Path-correct ENFORCE can still be design-weak (P02).
             designFitness,
             designSmells,
+            // Q01: primary next action when Shape residual dominates (null if not design-weak).
+            postGreenPath,
+            ...(postGreenPath
+              ? {
+                  primaryNextAction: postGreenPath.action,
+                  healthyFinishedForbidden: true,
+                }
+              : {}),
+            // Q03: advisory golden for new-code placement (absent = no claim).
+            goldenPattern,
+            // Q04: one-pilot loop (extraction card → re-doctor).
+            pilotLoop,
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
@@ -523,7 +576,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     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.'
+        ? 'Guard on edges is honest, but design smells remain (Shape residual). You do not pick this mode. Next: single path — /ark-explore shape-focus → dual-plan B, then /ark-autopilot only to apply B with your OK. Never empty plan A = done.'
         : modeHelp[mode]
     }`
   );
@@ -541,18 +594,52 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   } else {
     line(designFitness.designWeak ? warn : warn, designFitness.label);
     for (const smell of designSmells.slice(0, 5)) {
-      line(' ', color.dim(`[${smell.id}] ${smell.message}`));
+      // Q02: outcome-first (plain language); technical message stays in JSON + dim detail.
+      const outcome = smell.outcome || smell.message;
+      line(' ', `[${smell.id}] ${outcome}`);
+      if (smell.outcome && smell.message && smell.message !== smell.outcome) {
+        line(' ', color.dim(`detail: ${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'
+    if (postGreenPath) {
+      // Rank first via mergePostGreenTopActions at the end (Q01 single door).
+      actions.push(postGreenPath.action);
+    }
+    // Q04 — surface one next pilot under design-weak.
+    if (pilotLoop?.active && pilotLoop.nextPilot) {
+      const np = pilotLoop.nextPilot;
+      line(
+        warn,
+        `Next pilot (one at a time): ${np.pilotTarget || np.pilot} [${np.smellId}] → re-doctor after change`
       );
+      line(' ', color.dim(`success: ${np.successSignal}`));
+      line(' ', color.dim('never multi-pilot batch; patternBets never mechanical-safe'));
     }
   }
 
+  // Q03 — optional golden pattern note (advisory for new code only).
+  if (goldenPattern.present) {
+    console.log('');
+    console.log(color.bold('Golden pattern (new code)'));
+    line(
+      ok,
+      `"${goldenPattern.name}" — ${goldenPattern.norm}` +
+        (goldenPattern.newCodeHome ? ` Prefer: ${goldenPattern.newCodeHome}.` : '') +
+        ' Advisory only — does not clear design-weak or replace the gate.'
+    );
+  } else if (goldenPattern.invalid) {
+    console.log('');
+    console.log(color.bold('Golden pattern (new code)'));
+    line(
+      warn,
+      `${goldenPattern.path} is present but invalid (${goldenPattern.error || 'invalid'}). ` +
+        'Fix or remove it — absence is fine; a bad file is not guidance.'
+    );
+  }
+
   console.log('');
   console.log(color.bold('Coverage'));
   const govMark =
@@ -776,11 +863,21 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
 
   console.log('');
-  if (actions.length === 0) {
+  const uniqueActions = mergePostGreenTopActions(actions, postGreenPath);
+  if (isDoctorHealthyNothingToDo(designFitness, uniqueActions)) {
     console.log(color.green('✔ Healthy — nothing to do.'));
   } else {
-    const uniqueActions = [...new Set(actions.filter(Boolean))];
+    if (designFitness.designWeak && uniqueActions.length === 0 && postGreenPath) {
+      uniqueActions.push(postGreenPath.action);
+    }
     console.log(color.bold(`Top actions (${uniqueActions.length}):`));
     uniqueActions.forEach((action, index) => console.log(`  ${index + 1}. ${action}`));
+    if (postGreenPath) {
+      console.log(
+        color.dim(
+          '  (post-green path is primary when ENFORCE · design-weak — do not skill-shop explore vs coverage vs think)'
+        )
+      );
+    }
   }
 }

package/bin/lib/golden-pattern.mjs

@@ -0,0 +1,184 @@
+/**
+ * Q03 — optional golden pattern artifact for *new* code guidance.
+ *
+ * Path: `.ark/golden-pattern.json` (side-car under existing local-state convention).
+ * Absent is normal. Presence is advisory only — never ENFORCE, never clears design-weak.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Relative path from project root (stable contract). */
+export const GOLDEN_PATTERN_REL = '.ark/golden-pattern.json';
+
+export const GOLDEN_PATTERN_SCHEMA_VERSION = '1';
+
+/**
+ * @typedef {{
+ *   schemaVersion?: string,
+ *   name: string,
+ *   norm: string,
+ *   newCodeHome?: string,
+ *   examplePath?: string,
+ * }} GoldenPattern
+ */
+
+/**
+ * @typedef {{
+ *   ok: boolean,
+ *   present: boolean,
+ *   path: string,
+ *   golden?: GoldenPattern,
+ *   invalid?: boolean,
+ *   error?: string,
+ * }} GoldenPatternLoadResult
+ */
+
+/**
+ * Load optional golden pattern from the consumer tree.
+ * Never throws. Malformed → invalid, not present, ok:false.
+ *
+ * @param {string} root
+ * @returns {GoldenPatternLoadResult}
+ */
+export function loadGoldenPattern(root) {
+  const rel = GOLDEN_PATTERN_REL;
+  if (typeof root !== 'string' || !root) {
+    return { ok: true, present: false, path: rel };
+  }
+  const abs = path.join(root, '.ark', 'golden-pattern.json');
+  let raw;
+  try {
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      return { ok: true, present: false, path: rel };
+    }
+    raw = fs.readFileSync(abs, 'utf8');
+  } catch {
+    return {
+      ok: false,
+      present: false,
+      invalid: true,
+      error: 'unreadable',
+      path: rel,
+    };
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return {
+      ok: false,
+      present: false,
+      invalid: true,
+      error: 'invalid-json',
+      path: rel,
+    };
+  }
+
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return {
+      ok: false,
+      present: false,
+      invalid: true,
+      error: 'not-object',
+      path: rel,
+    };
+  }
+
+  const name = typeof data.name === 'string' ? data.name.trim() : '';
+  const norm = typeof data.norm === 'string' ? data.norm.trim() : '';
+  if (!name || !norm) {
+    return {
+      ok: false,
+      present: false,
+      invalid: true,
+      error: 'missing-name-or-norm',
+      path: rel,
+    };
+  }
+
+  /** @type {GoldenPattern} */
+  const golden = {
+    schemaVersion:
+      typeof data.schemaVersion === 'string' && data.schemaVersion.trim()
+        ? data.schemaVersion.trim()
+        : GOLDEN_PATTERN_SCHEMA_VERSION,
+    name,
+    norm,
+  };
+  if (typeof data.newCodeHome === 'string' && data.newCodeHome.trim()) {
+    golden.newCodeHome = data.newCodeHome.trim();
+  }
+  if (typeof data.examplePath === 'string' && data.examplePath.trim()) {
+    golden.examplePath = data.examplePath.trim();
+  }
+
+  return { ok: true, present: true, path: rel, golden };
+}
+
+/**
+ * One-line guidance for agents / placement notes.
+ * @param {GoldenPatternLoadResult} result
+ * @returns {string | null}
+ */
+export function formatGoldenPatternNote(result) {
+  if (!result?.present || !result.golden) return null;
+  const g = result.golden;
+  let s = `Golden pattern (advisory for NEW code only): "${g.name}" — ${g.norm}`;
+  if (g.newCodeHome) s += ` Prefer new files under ${g.newCodeHome}.`;
+  if (g.examplePath) s += ` Example: ${g.examplePath}.`;
+  s += ' Does not clear design-weak or replace the gate.';
+  return s;
+}
+
+/**
+ * Compact JSON-safe summary for doctor / prepare_write.
+ * @param {GoldenPatternLoadResult} result
+ */
+export function summarizeGoldenPattern(result) {
+  if (!result) {
+    return { present: false, path: GOLDEN_PATTERN_REL };
+  }
+  if (result.invalid) {
+    return {
+      present: false,
+      path: result.path || GOLDEN_PATTERN_REL,
+      invalid: true,
+      error: result.error || 'invalid',
+    };
+  }
+  if (!result.present || !result.golden) {
+    return { present: false, path: result.path || GOLDEN_PATTERN_REL };
+  }
+  return {
+    present: true,
+    path: result.path || GOLDEN_PATTERN_REL,
+    name: result.golden.name,
+    norm: result.golden.norm,
+    ...(result.golden.newCodeHome ? { newCodeHome: result.golden.newCodeHome } : {}),
+    ...(result.golden.examplePath ? { examplePath: result.golden.examplePath } : {}),
+    advisoryOnly: true,
+    doesNotClearDesignWeak: true,
+  };
+}
+
+/**
+ * Attach golden guidance to a placement object (ark_place / prepare_write).
+ * @param {object} placement
+ * @param {GoldenPatternLoadResult} goldenResult
+ */
+export function attachGoldenToPlacement(placement, goldenResult) {
+  if (!placement || typeof placement !== 'object') return placement;
+  if (placement.error) return placement;
+
+  const summary = summarizeGoldenPattern(goldenResult);
+  const note = formatGoldenPatternNote(goldenResult);
+  const next = {
+    ...placement,
+    goldenPattern: summary,
+  };
+  if (note) {
+    next.note = placement.note ? `${placement.note} ${note}` : note;
+  }
+  return next;
+}