arkgate 4.0.0 → 4.1.0

package/bin/lib/rules-under-contract.mjs

@@ -1,17 +1,69 @@
 /**
- * AR12 — doctor/HTML "Rules under contract" counts (not a score).
+ * AR12 — doctor/HTML "Rules under contract" (ArkRules plane — counts, never a score).
  * Uses real file I/O for coverage evidence (never empty-fileContents stub).
+ * Summary includes per-layer + structure/invariant detail so showcase HTML /ark-explain
+ * can teach what is under contract, not only aggregate numbers.
  */
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
 
+/**
+ * Cap long catalogs in doctor JSON (and HTML, which consumes the same summary).
+ * Covered is a sample; structure/uncovered are truncated with *Truncated counters.
+ */
+const COVERED_SAMPLE_MAX = 24;
+const STRUCTURE_CATALOG_MAX = 40;
+const UNCOVERED_CATALOG_MAX = 30;
+
+/** Minimum governed % before enforced ArkRules may arm extra merge teeth (P1M / FG-EXTRATEETH). */
+export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
+
+/**
+ * P1M / extraMergeTeeth: under the classification floor, demote enforced ArkRules
+ * structure/invariant findings so merge matches doctor stamp (layer graph only).
+ * Unknown classification (null/null) → do not demote (contract-only callers).
+ *
+ * @param {object[]} violations
+ * @param {{ governedPercent?: number|null, populatedLayerCount?: number|null }} classification
+ * @returns {object[]}
+ */
+export function demoteArkRuleTeethUnderClassificationFloor(violations, classification = {}) {
+  if (!Array.isArray(violations)) return violations;
+  const governed =
+    typeof classification.governedPercent === 'number' ? classification.governedPercent : null;
+  const populated =
+    typeof classification.populatedLayerCount === 'number'
+      ? classification.populatedLayerCount
+      : null;
+  if (governed == null && populated == null) return violations;
+  const allowsTeeth =
+    (governed ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR && (populated ?? 0) >= 1;
+  if (allowsTeeth) return violations;
+  for (const v of violations) {
+    const isArkRule =
+      v?.arkruleId != null ||
+      (typeof v?.ruleId === 'string' &&
+        (v.ruleId.startsWith('ARKRULE') || v.ruleId.startsWith('arkrule')));
+    if (isArkRule && v.failsStrict !== false) {
+      v.failsStrict = false;
+      if (v.severity === 'error') v.severity = 'warning';
+    }
+  }
+  return violations;
+}
+
 /**
  * @param {string} root
  * @param {Record<string, unknown>} config
  * @param {{ files?: Array<{ path: string }> }} [facts] optional facts for path set
+ * @param {{
+ *   governedPercent?: number | null,
+ *   populatedLayerCount?: number | null,
+ *   classifiedFiles?: number | null,
+ * }} [classification] layer-plane coverage (when known)
  */
-export function summarizeRulesUnderContract(root, config, facts) {
+export function summarizeRulesUnderContract(root, config, facts, classification) {
   if (!config?.arkRules || Object.keys(config.arkRules).length === 0) {
     return {
       active: false,
@@ -45,16 +97,157 @@ export function summarizeRulesUnderContract(root, config, facts) {
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
     });
+    const covById = new Map(
+      (coverage.coverage ?? []).map((row) => [row.invariantId, row])
+    );
+    const byLayer = loaded.arkRules.byLayer ?? {};
+    const layers = Object.keys(byLayer)
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => {
+        const part = byLayer[name] ?? {};
+        const layerInvariants = part.invariants ?? [];
+        let covered = 0;
+        for (const inv of layerInvariants) {
+          if (covById.get(inv.id)?.covered) covered += 1;
+        }
+        return {
+          name,
+          sourceFile: part.sourceFile ?? null,
+          structureRules: (part.structure ?? []).length,
+          invariants: layerInvariants.length,
+          coveredInvariants: covered,
+          uncoveredInvariants: layerInvariants.length - covered,
+        };
+      });
+
+    const structureAll = (loaded.arkRules.structure ?? []).map((entry) => ({
+      id: entry.id,
+      sensor: entry.sensor,
+      mode: entry.mode ?? 'advisory',
+      layer: entry.provenance?.layer ?? null,
+      description: entry.description ?? null,
+      sourceFile: entry.provenance?.sourceFile ?? null,
+    }));
+    const structureTruncated = Math.max(0, structureAll.length - STRUCTURE_CATALOG_MAX);
+    const structure = structureAll.slice(0, STRUCTURE_CATALOG_MAX);
+
+    const uncoveredAll = (coverage.coverage ?? [])
+      .filter((row) => !row.covered)
+      .map((row) => ({
+        id: row.invariantId,
+        layer: row.layer ?? null,
+        mode: row.mode ?? null,
+        description: row.description ?? null,
+        sourceFile: row.sourceFile ?? null,
+      }));
+    const uncoveredTruncated = Math.max(0, uncoveredAll.length - UNCOVERED_CATALOG_MAX);
+    const uncovered = uncoveredAll.slice(0, UNCOVERED_CATALOG_MAX);
+
+    const coveredAll = (coverage.coverage ?? [])
+      .filter((row) => row.covered)
+      .map((row) => ({
+        id: row.invariantId,
+        layer: row.layer ?? null,
+        mode: row.mode ?? null,
+        description: row.description ?? null,
+      }));
+    const coveredTruncated = Math.max(0, coveredAll.length - COVERED_SAMPLE_MAX);
+    const coveredSample = coveredAll.slice(0, COVERED_SAMPLE_MAX);
+
+    const structureEnforced = structureAll.filter((s) => s.mode === 'enforced').length;
+    const structureAdvisory = structureAll.length - structureEnforced;
+    const invariantEnforced = (loaded.arkRules.invariants ?? []).filter(
+      (inv) => inv.mode === 'enforced'
+    ).length;
+    const invariantAdvisory = invariants - invariantEnforced;
+    const coveredInvariants = coverage.coverage.filter((c) => c.covered).length;
+    const uncoveredInvariants = coverage.coverage.filter((c) => !c.covered).length;
+    const hasEnforcedTeeth = structureEnforced > 0 || invariantEnforced > 0;
+    // P1M-EXTRATEETH-EMPTY-GRAPH / FG-EXTRATEETH-EMPTY-CLASSIFICATION:
+    // Do not arm structure/invariant merge teeth when the layer plane is empty or
+    // barely classified (e.g. 0% governed). Classification unknown → allow teeth
+    // (contract-only callers / unit tests without coverage).
+    const governedPercent =
+      classification && typeof classification.governedPercent === 'number'
+        ? classification.governedPercent
+        : null;
+    const populatedLayerCount =
+      classification && typeof classification.populatedLayerCount === 'number'
+        ? classification.populatedLayerCount
+        : classification && typeof classification.classifiedFiles === 'number'
+          ? classification.classifiedFiles > 0
+            ? 1
+            : 0
+          : null;
+    const classificationKnown = governedPercent != null || populatedLayerCount != null;
+    const classificationAllowsTeeth = !classificationKnown
+      ? true
+      : (governedPercent ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR &&
+        (populatedLayerCount ?? 0) >= 1;
+    const extraMergeTeeth = hasEnforcedTeeth && classificationAllowsTeeth;
+    const teethDeferredForClassification =
+      hasEnforcedTeeth && classificationKnown && !classificationAllowsTeeth;
+    // P1-M — which plane can fail merge (layers vs enforced structure vs invariants).
+    const mergePlanes = {
+      layers: {
+        role: 'inter-layer-edges',
+        alwaysOnGate: true,
+        note: 'Import/export layer graph — the default merge plane. Absent arkRules changes nothing here.',
+      },
+      structureSensors: {
+        role: 'intra-layer-heuristics',
+        total: structureRules,
+        enforced: structureEnforced,
+        advisory: structureAdvisory,
+        note: 'Structure sensors are heuristics (prefer false negatives). Only mode:enforced fails merge; noisy sensors stay advisory by default. Advisory-only packs never add merge teeth (FG-ARKRULES-ADVISORY-ONLY).',
+      },
+      invariants: {
+        role: 'catalog-plus-coverage',
+        total: invariants,
+        enforced: invariantEnforced,
+        advisory: invariantAdvisory,
+        covered: coveredInvariants,
+        uncovered: uncoveredInvariants,
+        note: 'Invariants are catalog + coverage evidence, not a business runtime. Enforced + proven-uncovered fails merge; absence of enforced rules adds no extra teeth.',
+      },
+      dualPlaneStamp:
+        'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime). The two planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth.',
+      extraMergeTeeth,
+      ...(classificationKnown
+        ? {
+            classificationGate: {
+              governedPercent: governedPercent ?? null,
+              populatedLayerCount: populatedLayerCount ?? null,
+              floorPercent: EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
+              allowsTeeth: classificationAllowsTeeth,
+            },
+          }
+        : {}),
+      failMergeWhen: extraMergeTeeth
+        ? 'Layer graph failures plus enforced structure/invariant findings (advisory sensors never fail merge alone).'
+        : teethDeferredForClassification
+          ? `Layer graph only — enforced ArkRules structure/invariant findings are demoted under the teeth floor (need ≥${EXTRA_MERGE_TEETH_GOVERNED_FLOOR}% governed and ≥1 populated layer); they do not merge-block until classification is honest.`
+          : 'Layer graph only — no enforced ArkRules structure/invariant teeth on this tree. Advisory packs do not arm merge teeth.',
+    };
+
     return {
       active: true,
       structureRules,
       invariants,
-      coveredInvariants: coverage.coverage.filter((c) => c.covered).length,
-      uncoveredInvariants: coverage.coverage.filter((c) => !c.covered).length,
+      coveredInvariants,
+      uncoveredInvariants,
       partialCoverage: coverage.partial,
       testFilesScanned: coverageInputs.testFiles.length,
+      layers,
+      structure,
+      structureTruncated,
+      uncovered,
+      uncoveredTruncated,
+      coveredSample,
+      coveredTruncated,
+      mergePlanes,
       notAScore: true,
-      note: 'Counts only — never a score. Green with uncovered residual must say so.',
+      note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so. Structure sensors are heuristics; invariants are catalog+coverage evidence, not a business runtime.',
     };
   } catch (error) {
     return {
@@ -64,3 +257,194 @@ export function summarizeRulesUnderContract(root, config, facts) {
     };
   }
 }
+
+/**
+ * Showcase HTML for the ArkRules plane (used by html-report-advisories).
+ * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
+ * @param {(v: unknown) => string} esc
+ */
+export function formatRulesUnderContractHtml(section, esc) {
+  if (!section || typeof section !== 'object') return '';
+  const escape = typeof esc === 'function' ? esc : (v) => String(v);
+  const note = section.note ? `<p class="muted">${escape(section.note)}</p>` : '';
+
+  if (section.active === false) {
+    return `
+  <section class="section card" data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(ArkRules opt-in)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      Intra-layer plane (structure sensors + domain invariants as data). Separate from inter-layer import edges.
+      Absence of arkRules adds no extra merge teeth beyond the layer graph.
+    </p>
+    ${note}
+  </section>`;
+  }
+
+  if (Array.isArray(section.loadErrors) && section.loadErrors.length) {
+    const errs = section.loadErrors
+      .slice(0, 8)
+      .map((e) => `<li><code>${escape(e.path ?? '')}</code> — ${escape(e.message ?? e)}</li>`)
+      .join('');
+    return `
+  <section class="section card" data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(load errors)</span></h2>
+    ${note}
+    <ul class="senior-list">${errs}</ul>
+  </section>`;
+  }
+
+  const layers = Array.isArray(section.layers) ? section.layers : [];
+  const structure = Array.isArray(section.structure) ? section.structure : [];
+  const uncovered = Array.isArray(section.uncovered) ? section.uncovered : [];
+  const coveredSample = Array.isArray(section.coveredSample) ? section.coveredSample : [];
+  const coveredTruncated = Number(section.coveredTruncated) || 0;
+  const structureTruncated = Number(section.structureTruncated) || 0;
+  const uncoveredTruncated = Number(section.uncoveredTruncated) || 0;
+
+  const layerRows = layers
+    .map((row) => {
+      const cov =
+        row.invariants > 0
+          ? `${row.coveredInvariants}/${row.invariants} inv covered`
+          : 'no invariants';
+      return `<tr>
+        <td class="ln">${escape(row.name)}${
+          row.sourceFile ? `<div class="tags"><span class="tag"><code>${escape(row.sourceFile)}</code></span></div>` : ''
+        }</td>
+        <td class="num">${Number(row.structureRules) || 0}</td>
+        <td class="num">${Number(row.invariants) || 0}</td>
+        <td>${escape(cov)}${
+          row.uncoveredInvariants > 0
+            ? ` <span class="tag warn">${row.uncoveredInvariants} uncovered</span>`
+            : ''
+        }</td>
+      </tr>`;
+    })
+    .join('\n');
+
+  const layerTable = layers.length
+    ? `<table class="layers" style="margin-top:.55rem">
+        <thead><tr><th>Layer</th><th>Structure</th><th>Invariants</th><th>Coverage</th></tr></thead>
+        <tbody>${layerRows}</tbody>
+      </table>`
+    : '';
+
+  // Doctor JSON already caps catalogs; slice again only if a caller passed untruncated arrays.
+  const structureShown = structure.slice(0, STRUCTURE_CATALOG_MAX);
+  const structureOverflow =
+    structureTruncated > 0
+      ? structureTruncated
+      : Math.max(0, structure.length - STRUCTURE_CATALOG_MAX);
+  const structureItems = structureShown
+    .map((s) => {
+      const mode = s.mode === 'enforced' ? 'enforced' : s.mode === 'advisory' ? 'advisory' : String(s.mode ?? '');
+      const modeTag =
+        mode === 'enforced'
+          ? '<span class="tag">enforced</span>'
+          : `<span class="tag warn">${escape(mode || 'mode?')}</span>`;
+      return `<li>
+        <code>${escape(s.id)}</code>
+        ${modeTag}
+        <span class="dim">· ${escape(s.layer || '?')} · sensor <code>${escape(s.sensor || '')}</code></span>
+        ${s.description ? `<div class="msg">${escape(s.description)}</div>` : ''}
+      </li>`;
+    })
+    .join('\n');
+  const structureMore =
+    structureOverflow > 0
+      ? `<p class="muted">…(+${structureOverflow} more structure rule(s) in arkrules/*)</p>`
+      : '';
+
+  const uncoveredShown = uncovered.slice(0, UNCOVERED_CATALOG_MAX);
+  const uncoveredOverflow =
+    uncoveredTruncated > 0
+      ? uncoveredTruncated
+      : Math.max(0, uncovered.length - UNCOVERED_CATALOG_MAX);
+  const uncoveredItems = uncoveredShown
+    .map(
+      (u) => `<li>
+        <code>${escape(u.id)}</code>
+        <span class="tag warn">uncovered</span>
+        <span class="dim">· ${escape(u.layer || '?')}</span>
+        ${u.description ? `<div class="msg">${escape(u.description)}</div>` : ''}
+      </li>`
+    )
+    .join('\n');
+  const uncoveredMore =
+    uncoveredOverflow > 0
+      ? `<p class="muted">…(+${uncoveredOverflow} more uncovered)</p>`
+      : '';
+  const uncoveredBlock =
+    // Aggregate total (not the truncated array length) decides "all covered".
+    Number(section.uncoveredInvariants) === 0 && uncovered.length === 0
+      ? `<p class="clean-body" style="margin-top:.55rem">All catalogued invariants have coverage evidence (test/symbol scan) — residual inventory may still suggest new candidates via <code>--rules-inventory</code>.</p>`
+      : `<h3 style="margin-top:.9rem;font-size:.95rem">Uncovered invariants</h3>
+      <ul class="senior-list">${uncoveredItems}</ul>${uncoveredMore}`;
+
+  const coveredItems = coveredSample
+    .map(
+      (c) => `<li>
+        <code>${escape(c.id)}</code>
+        <span class="tag">covered</span>
+        <span class="dim">· ${escape(c.layer || '?')}</span>
+        ${c.description ? `<div class="msg">${escape(c.description)}</div>` : ''}
+      </li>`
+    )
+    .join('\n');
+  const coveredBlock =
+    coveredSample.length === 0
+      ? ''
+      : `<h3 style="margin-top:.9rem;font-size:.95rem">Covered invariants${
+          coveredTruncated > 0 ? ` <span class="dim">(sample of ${coveredSample.length})</span>` : ''
+        }</h3>
+      <ul class="senior-list">${coveredItems}</ul>
+      ${
+        coveredTruncated > 0
+          ? `<p class="muted">…(+${coveredTruncated} more covered — full catalog in <code>arkrules/*</code>)</p>`
+          : ''
+      }`;
+
+  const mergePlanes = section.mergePlanes;
+  const mergeHtml =
+    mergePlanes && typeof mergePlanes === 'object'
+      ? `<p class="muted" style="margin:.35rem 0 .55rem;font-size:.86rem">
+          <b>Merge planes:</b> ${escape(mergePlanes.failMergeWhen || '')}
+          ${mergePlanes.dualPlaneStamp ? `<br/>${escape(mergePlanes.dualPlaneStamp)}` : ''}
+        </p>`
+      : '';
+
+  return `
+  <section class="section card" data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(ArkRules — not a score)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      <b>[ArkRules]</b> Intra-layer plane — separate from <b>[Layer]</b> import edges above.
+      <b>Structure</b> = module-shape heuristics (not proof of Domain extraction).
+      <b>Invariants</b> = named policies + coverage evidence (symbol/test), not a business runtime
+      and not a fitness score.
+    </p>
+    ${mergeHtml}
+    <div class="kpis" style="margin-bottom:.55rem">
+      <div class="kpi"><b>${Number(section.structureRules) || 0}</b><span>Structure rules</span></div>
+      <div class="kpi"><b>${Number(section.invariants) || 0}</b><span>Invariants</span></div>
+      <div class="kpi"><b>${Number(section.coveredInvariants) || 0}</b><span>Covered</span></div>
+      <div class="kpi"><b>${Number(section.uncoveredInvariants) || 0}</b><span>Uncovered</span></div>
+    </div>
+    ${layers.length ? `<p class="dim" style="margin:0 0 .35rem;font-size:.86rem">${layers.length} layer(s) with an <code>arkRules</code> map entry · tests scanned: ${Number(section.testFilesScanned) || 0}</p>` : ''}
+    ${layerTable}
+    ${
+      structure.length
+        ? `<h3 style="margin-top:.9rem;font-size:.95rem">Structure sensors</h3>
+      <p class="muted" style="margin:.15rem 0 .4rem;font-size:.84rem">Heuristics of module shape. Enforced fails the check; it does not prove extraction to Domain.</p>
+      <ul class="senior-list">${structureItems}</ul>${structureMore}`
+        : '<p class="muted" style="margin-top:.55rem">No structure sensors in loaded ArkRules files.</p>'
+    }
+    ${uncoveredBlock}
+    ${coveredBlock}
+    ${
+      coveredSample.length || uncovered.length
+        ? `<p class="muted" style="margin-top:.65rem;font-size:.84rem">Covered = catalog evidence found (symbol and/or test title). Not a claim that business semantics are fully proven end-to-end.</p>`
+        : ''
+    }
+    ${note}
+  </section>`;
+}

package/bin/lib/start-preview.mjs

@@ -122,8 +122,21 @@ function commands(root, args, helpers) {
   return result;
 }
 
-export function renderStartPreview(preview) {
-  console.log('Ark start preview — no files were changed.');
+/**
+ * @param {object} preview
+ * @param {{ applying?: boolean }} [options] when applying=true, do not claim “no files were changed”
+ */
+export function renderStartPreview(preview, options = {}) {
+  const applying = options.applying === true;
+  if (applying) {
+    console.log(
+      preview.changes.length === 0
+        ? 'Ark start apply — reviewing plan (no mutations pending).'
+        : `Ark start apply — writing ${preview.changes.length} planned mutation(s).`
+    );
+  } else {
+    console.log('Ark start preview — no files were changed.');
+  }
   if (preview.analysis) {
     console.log(`Your project looks like: ${preview.analysis.label} (${preview.analysis.archetype}, confidence ${preview.analysis.confidence}).`);
   }
@@ -135,20 +148,24 @@ export function renderStartPreview(preview) {
   console.log(
     `Compact setup budget: ${gateCount}/${budget.maxFiles} gate files${arkrulesNote}, ${budget.bytes}/${budget.maxBytes} bytes${budget.ok ? '' : ' (exceeded)'}.`
   );
-  console.log('Files to create/edit/delete:');
+  console.log(applying ? 'Files create/edit/delete:' : 'Files to create/edit/delete:');
   if (preview.changes.length === 0) console.log('  (none)');
   for (const change of preview.changes) {
     console.log(`  ${change.action.padEnd(6)} ${change.path}  ${change.afterHash ?? '(deleted)'}`);
   }
-  console.log('Commands in the approved setup plan:');
-  for (const command of preview.commands) console.log(`  ${command}`);
+  if (!applying) {
+    console.log('Commands in the approved setup plan:');
+    for (const command of preview.commands) console.log(`  ${command}`);
+  }
   console.log('Host guarantees:');
   for (const guarantee of preview.hostGuarantees) console.log(`  ${guarantee}`);
   if (preview.unresolvedDecisions.length > 0) {
     console.log('Unresolved decisions:');
     for (const decision of preview.unresolvedDecisions) console.log(`  ${decision}`);
   }
-  console.log('Review complete file contents with --json. Apply this plan with: ark start --apply');
+  if (!applying) {
+    console.log('Review complete file contents with --json. Apply this plan with: ark start --apply');
+  }
 }
 
 export function applyStartPreview(root, preview) {
@@ -224,16 +241,30 @@ export async function planStart(args, helpers) {
   const root = args.root;
   const before = treeFiles(root);
   let recommendation = null;
-  try {
-    const rec = buildArchitectureRecommendation(root);
+  // Wire --archetype / --preset into the plan so apply locks the chosen shape (not just recommend).
+  if (args.archetype || args.preset) {
     recommendation = {
-      archetype: rec.archetype,
-      label: rec.label,
-      confidence: rec.confidence,
-      mature: rec.mature,
+      archetype: args.archetype || args.preset,
+      label: args.archetype
+        ? `explicit archetype ${args.archetype}`
+        : `explicit preset ${args.preset}`,
+      confidence: 1,
+      mature: false,
+      explicitShape: true,
+      preset: args.preset || null,
     };
-  } catch {
-    recommendation = null;
+  } else {
+    try {
+      const rec = buildArchitectureRecommendation(root);
+      recommendation = {
+        archetype: rec.archetype,
+        label: rec.label,
+        confidence: rec.confidence,
+        mature: rec.mature,
+      };
+    } catch {
+      recommendation = null;
+    }
   }
   const shadowRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ark-start-preview-'));
   try {
@@ -253,6 +284,9 @@ export async function planStart(args, helpers) {
     else childArgs.push('--install');
     if (args.tools) childArgs.push('--tools', args.tools);
     if (args.requireWriteHook) childArgs.push('--require-write-hook', args.requireWriteHook);
+    // Lock archetype/preset into the shadow apply so the plan matches the gate bypass.
+    if (args.archetype) childArgs.push('--archetype', args.archetype);
+    if (args.preset) childArgs.push('--preset', args.preset);
     const planned = spawnSync(process.execPath, [helpers.cliPath, ...childArgs], {
       cwd: shadowRoot,
       encoding: 'utf8',

package/bin/lib/suggestions.mjs

@@ -15,6 +15,68 @@ export function dirSegmentsFromGlob(pattern) {
     .filter((segment) => segment && !segment.includes('*'));
 }
 
+/**
+ * Basename / path tokens that score as Persistence (data clients, auth, CRM).
+ * Used so adopt never maps lib/turso → Presentation (NEW-ADOPT-LIB-AS-PRESENTATION).
+ */
+export const PERSISTENCE_PATH_TOKENS = Object.freeze([
+  'turso',
+  'prisma',
+  'supabase',
+  'airtable',
+  'drizzle',
+  'kysely',
+  'mongoose',
+  'mongodb',
+  'firebase',
+  'firestore',
+  'planetscale',
+  'neon',
+  'pipedrive',
+  'repository',
+  'repositories',
+  'persistence',
+  'infrastructure',
+  'infra',
+  'db',
+  'auth',
+  'session',
+]);
+
+/** True when a path/basename looks like a data or auth client (not UI). */
+export function isPersistenceClientPath(relPath) {
+  const posix = String(relPath || '')
+    .split(/[/\\]/)
+    .filter(Boolean)
+    .join('/');
+  if (!posix) return false;
+  const lower = posix.toLowerCase();
+  const base = path.posix.basename(lower).replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/i, '');
+  for (const token of PERSISTENCE_PATH_TOKENS) {
+    if (base === token || base.startsWith(`${token}.`) || base.startsWith(`${token}-`) || base.startsWith(`${token}_`)) {
+      return true;
+    }
+    if (lower.includes(`/${token}/`) || lower.endsWith(`/${token}`) || lower.startsWith(`${token}/`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** True when a path looks like pure domain folders. */
+export function isDomainPath(relPath) {
+  const posix = String(relPath || '')
+    .split(/[/\\]/)
+    .filter(Boolean)
+    .join('/')
+    .toLowerCase();
+  return (
+    /(?:^|\/)domain(?:\/|$)/.test(posix) ||
+    /(?:^|\/)entities(?:\/|$)/.test(posix) ||
+    /(?:^|\/)kernel\/domain(?:\/|$)/.test(posix)
+  );
+}
+
 let _layerByDir;
 // Map<dirBasename, string[] layers>. A basename mapping to >1 layer (e.g. `app` — Application
 // orchestration in the 11-layer defaults, but Presentation in the monorepo/Next preset) is
@@ -58,11 +120,64 @@ export function suggestLayerForDir(name) {
 
 // Suggest a layer for a directory PATH by finding the deepest segment Ark recognizes, so
 // `src/lib/repositories` proposes PersistenceAdapters even though `lib` itself is unknown.
+// Next App Router / Pages API shells (`…/app/api`, `…/pages/api`) are Application, not Presentation.
+// Never map bare `lib` alone to Presentation (NEW-ADOPT-LIB-AS-PRESENTATION).
 export function suggestLayerForPath(relDir) {
-  const segments = relDir.split('/').filter(Boolean);
+  const posix = String(relDir || '')
+    .split(/[/\\]/)
+    .filter(Boolean)
+    .join('/');
+  // Prefer the API orchestration shell over a bare `app` / `pages` Presentation match.
+  // Direct api/ and route-group shells: app/(marketing)/api/**
+  if (
+    /(?:^|\/)(?:src\/)?app(?:\/[^/]+)*\/api(?:\/|$)/.test(posix) ||
+    /(?:^|\/)(?:src\/)?pages(?:\/[^/]+)*\/api(?:\/|$)/.test(posix)
+  ) {
+    return {
+      layer: 'ApplicationOrchestration',
+      alternatives: [],
+      matchedDir: posix.includes('pages') && posix.includes('/api') ? 'pages/…/api' : 'app/…/api',
+    };
+  }
+  // Root / Vercel serverless api handlers (SPA layout).
+  if (/(?:^|\/)api(?:\/|$)/.test(posix) && !/(?:^|\/)app(?:\/|$)/.test(posix)) {
+    return {
+      layer: 'ApplicationOrchestration',
+      alternatives: [],
+      matchedDir: 'api',
+    };
+  }
+  if (isDomainPath(posix)) {
+    return { layer: 'DomainModel', alternatives: [], matchedDir: 'domain' };
+  }
+  if (isPersistenceClientPath(posix)) {
+    return {
+      layer: 'PersistenceAdapters',
+      alternatives: [],
+      matchedDir: path.posix.basename(posix) || 'persistence',
+    };
+  }
+  const segments = posix.split('/').filter(Boolean);
   for (let i = segments.length - 1; i >= 0; i -= 1) {
-    const hit = suggestLayerForDir(segments[i]);
-    if (hit) return { ...hit, matchedDir: segments[i] };
+    const seg = segments[i];
+    // Bare `lib` is not Presentation — leave unrecognized so agents classify children.
+    if (seg === 'lib' || seg === 'src') continue;
+    const hit = suggestLayerForDir(seg);
+    if (hit) {
+      // Never promote Presentation solely because a parent was `lib`.
+      if (hit.layer === 'PresentationAdapters' && segments.includes('lib')) {
+        // Prefer Persistence when any sibling token smells like data; else skip.
+        if (isPersistenceClientPath(posix)) {
+          return {
+            layer: 'PersistenceAdapters',
+            alternatives: [],
+            matchedDir: seg,
+          };
+        }
+        continue;
+      }
+      return { ...hit, matchedDir: seg };
+    }
   }
   return null;
 }

package/bin/lib/unavailable-analysis.mjs

@@ -41,6 +41,8 @@ export function reportUnavailableAnalysis({
     runDoctor(root, config, files, rules, [], args.json, {
       configPath,
       configMissing: !fs.existsSync(configPath),
+      configRoot: args.configRoot ?? root,
+      configWalkedUp: args.configWalkedUp === true,
       parseHealth,
       completeness,
     });