arkgate 4.8.14 → 4.8.15

package/bin/lib/mcp-hook-payload.mjs

@@ -308,6 +308,62 @@ export function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
   emitCursorAllow(output, cursorStyle);
 }
 
+/** Host-native deny envelopes. Exit 2 is still set by the caller. */
+export function emitHostDeny(output, { antigravityStyle, cursorStyle, grokStyle, message, file }) {
+  const text = String(message || '').endsWith('\n') ? String(message) : `${message}\n`;
+  output.stderr(text);
+  if (antigravityStyle || grokStyle) {
+    output.stdout(`${JSON.stringify({ decision: 'deny', reason: String(message || '').trim() })}\n`);
+  }
+  if (cursorStyle) {
+    output.stdout(
+      JSON.stringify({
+        permission: 'deny',
+        agent_message: String(message || '').trim(),
+        user_message: `ArkGate blocked write to ${file || 'this file'}`,
+      }) + '\n'
+    );
+  }
+}
+
+/** File-local twin of CONFIG_UNCLASSIFIED_FILES — included, no layer, write must not land. */
+export function unclassifiedIncludedWriteDeny(relativePath) {
+  const file = String(relativePath || 'this file');
+  return {
+    ruleId: 'CONFIG_UNCLASSIFIED_FILES',
+    message: `${file} is included but matches no layer, so import rules will not run on it.`,
+    nextAction:
+      'Put it in a layer folder with /ark-place, or extend layer patterns / narrow include.',
+  };
+}
+
+/** File-local twin of CONFIG_LAYER_MISSING_OWNER — required owners, this house has none. */
+export function unownedLayerWriteDeny(relativePath, layerName) {
+  const file = String(relativePath || 'this file');
+  const house = String(layerName || 'this layer');
+  return {
+    ruleId: 'CONFIG_LAYER_MISSING_OWNER',
+    message: `${file} is in ${house}, and that folder has no owner.`,
+    nextAction: `Add a GitHub handle or email to ${house}'s owners in ark.config.json (/ark-adopt).`,
+  };
+}
+
+/**
+ * Fail-closed write when requireLayerOwners is on and this house has no owners.
+ * Silent when the flag is off, the layer is reserved, or owners are present.
+ */
+export function requiredOwnerWriteDeny(config, layerName, relativePath) {
+  if (config?.requireLayerOwners !== true || !layerName) return null;
+  const layer = (config.layers ?? []).find((entry) => entry?.name === layerName);
+  if (!layer) return null;
+  if (layer.optional === true || layer.reserved === true || layer.allowEmpty === true) return null;
+  const owners = Array.isArray(layer.owners)
+    ? layer.owners.filter((entry) => typeof entry === 'string' && entry.length > 0)
+    : [];
+  if (owners.length > 0) return null;
+  return unownedLayerWriteDeny(relativePath, layerName);
+}
+
 /**
  * Socket-style write-gate deny: two lines first. Pass/fail, no score.
  * Rule id stays on a following line, not the first sentence.

package/bin/lib/no-domain-frontend.mjs

@@ -0,0 +1,91 @@
+/**
+ * Soft no-Domain / all-logic-in-frontend residual (P2 §3 / Guiar).
+ * Tooling I/O. Never a gate fail.
+ *
+ * Projects facts doctor already has: empty Domain-role layer + presentation
+ * file share, or the existing `domain-logic-in-ui` smell. No second tree walk.
+ * Silent when there is no frontend, Domain already has files, or the bag is
+ * too thin to call “all logic in the UI.”
+ */
+
+import { isDomainRoleLayerName } from './arkrules-sensors.mjs';
+
+export const NO_DOMAIN_FRONTEND_ASK =
+  'Business rules live in the UI, and Domain is still empty.';
+
+export const NO_DOMAIN_FRONTEND_NEXT =
+  'Put one pure rule in a Domain file (/ark-place), then one small refactor with /ark-autopilot. Do not pile more rules in pages.';
+
+/** Presentation-role house by name. Align with design-smells presentation heuristic. */
+export function isPresentationRoleLayerName(name) {
+  return typeof name === 'string' && /presentation|ui|view|frontend/i.test(name);
+}
+
+function layerRows(input) {
+  return Array.isArray(input.coverage?.layers) ? input.coverage.layers : [];
+}
+
+function configLayers(input) {
+  return Array.isArray(input.config?.layers) ? input.config.layers : [];
+}
+
+function emptyLayerSet(input) {
+  return new Set(Array.isArray(input.coverage?.emptyLayers) ? input.coverage.emptyLayers : []);
+}
+
+function totalGovernedFiles(input) {
+  const governed = input.coverage?.governed?.totalFiles;
+  if (Number.isFinite(governed) && governed >= 0) return governed;
+  const total = input.coverage?.totalFiles;
+  return Number.isFinite(total) && total >= 0 ? total : 0;
+}
+
+function hasDomainLogicInUiSmell(designSmells) {
+  return (Array.isArray(designSmells) ? designSmells : []).some(
+    (smell) => smell && smell.id === 'domain-logic-in-ui'
+  );
+}
+
+/**
+ * Soft residual when Domain is declared but empty and the UI holds the rules.
+ * Never flips valid / goal.met.
+ *
+ * @param {{ config?: object, coverage?: object, designSmells?: object[] }} [input]
+ * @returns {{ kind: 'ui-logic' | 'presentation-bag', ask: string, nextAction: string, domainLayers: string[], presentationFiles: number } | null}
+ */
+export function collectNoDomainFrontendResidual(input = {}) {
+  const totalFiles = totalGovernedFiles(input);
+  if (totalFiles <= 0) return null;
+
+  const declared = configLayers(input);
+  const domainLayers = declared.filter((layer) =>
+    isDomainRoleLayerName(layer.name, layer.intentPrefixes ?? [])
+  );
+  if (domainLayers.length === 0) return null;
+
+  const rows = layerRows(input);
+  const empty = emptyLayerSet(input);
+  const domainEmpty = domainLayers.every((layer) => {
+    const row = rows.find((entry) => entry.name === layer.name);
+    const files = Number(row?.files) || 0;
+    return files === 0 || empty.has(layer.name);
+  });
+  if (!domainEmpty) return null;
+
+  const presentationFiles = rows
+    .filter((row) => isPresentationRoleLayerName(row.name))
+    .reduce((sum, row) => sum + (Number(row.files) || 0), 0);
+  if (presentationFiles <= 0) return null;
+
+  const uiLogic = hasDomainLogicInUiSmell(input.designSmells);
+  const presentationShare = presentationFiles / totalFiles;
+  if (!uiLogic && (presentationShare < 0.5 || presentationFiles < 3)) return null;
+
+  return {
+    kind: uiLogic ? 'ui-logic' : 'presentation-bag',
+    ask: NO_DOMAIN_FRONTEND_ASK,
+    nextAction: NO_DOMAIN_FRONTEND_NEXT,
+    domainLayers: domainLayers.map((layer) => layer.name),
+    presentationFiles,
+  };
+}

package/bin/lib/presets.mjs

@@ -670,8 +670,7 @@ export const ARCHITECTURE_PRESETS = {
           },
           {
             name: 'ApplicationOrchestration',
-            description:
-              'Use cases and services that coordinate the domain through ports. Next App Router API (`app/api/**`) and Pages API (`pages/api/**`) are orchestration shells, not UI.',
+            description: 'Use cases and services that coordinate the domain through ports.',
             patterns: [
               '**/application/**',
               '**/use-cases/**',
@@ -687,7 +686,7 @@ export const ARCHITECTURE_PRESETS = {
           {
             name: 'PresentationAdapters',
             description:
-              'Entrypoints — UI, framework app/pages dirs, controllers. Next `app/api` is Application, not this layer. Never bare lib/** (data clients are Persistence).',
+              'Entrypoints — UI, pages, controllers when present. Never bare lib/** (data clients are Persistence).',
             patterns: [
               '**/app/**',
               '**/pages/**',
@@ -760,7 +759,7 @@ export const ARCHITECTURE_PRESETS = {
           {
             name: 'ApplicationOrchestration',
             description:
-              'Server actions, features, Next API routes (`app/api/**` / `pages/api/**`), and non-UI lib orchestration (when present).',
+              'Server actions, features, and non-UI lib orchestration (when present).',
             patterns: [
               'src/features/**',
               'src/server/**',

package/bin/lib/product-copy.mjs

@@ -10,6 +10,21 @@
 export const NORTH_STAR_ONE_LINE =
   'Contener · Guiar · Ordenar — contain the write, guide the next step, order leftover mess.';
 
+/**
+ * Compact doctor / details — only when `arkRules` is on.
+ * Absence stays silent (unlike ArkOrder, which speaks when off).
+ */
+export const ARKRULES_ONE_BREATH =
+  'Layers stop a bad import. ArkRules is optional policies inside one folder.';
+
+/** Next step when the map is on and something still needs a human. */
+export const ARKRULES_FIRST_CONTACT_NEXT =
+  'Next: ark-check --rules-inventory — then /ark-adopt to write one rule, or /ark-autopilot to promote.';
+
+/** Next step when Domain has code but invariants[] is empty. */
+export const ARKRULES_EMPTY_CATALOG_NEXT =
+  'Next: add 1–2 short phrases to invariants[] in the Domain rules file, then ark-check --doctor.';
+
 /** Status-light leftover-design qualifier (was “design-weak”). */
 export const LEFTOVER_DESIGN_LABEL = 'leftover design work';
 

package/bin/lib/projected-governed-coverage.mjs

@@ -0,0 +1,114 @@
+/**
+ * One definition of projected governed coverage: include-scoped files that
+ * match a layer glob, via computeCoverage. Shared by start, --recommend, and
+ * doctor so the same tree cannot advertise two "projected" percents.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { collectGovernedFiles } from './scan-files.mjs';
+import { computeCoverage } from './doctor-plan.mjs';
+import { ARCHITECTURE_PRESETS } from './presets.mjs';
+import {
+  detectWorkspaces,
+  resolveIncludeRoots,
+  resolveStartInitPreset,
+} from '../ark-shared.mjs';
+
+export function measureGovernedCoverage(root, config) {
+  const files = collectGovernedFiles(root, config);
+  return computeCoverage(root, config, files, config.rules ?? []);
+}
+
+export function summarizeGovernedCoverage(coverage) {
+  const governed = coverage?.governed ?? {};
+  return {
+    percent: typeof governed.percent === 'number' ? governed.percent : 0,
+    classifiedFiles: governed.classifiedFiles ?? 0,
+    totalFiles: governed.totalFiles ?? coverage?.totalFiles ?? 0,
+    emptyScope: coverage?.emptyScope === true,
+  };
+}
+
+export function starterConfigForPreset(root, preset) {
+  const factory = ARCHITECTURE_PRESETS[preset];
+  if (typeof factory !== 'function') return null;
+  const workspacesOrInclude =
+    preset === 'monorepo' || preset === 'ui-surface'
+      ? resolveIncludeRoots(root)
+      : detectWorkspaces(root);
+  return factory(workspacesOrInclude, root);
+}
+
+/**
+ * Contract start/recommend/doctor should score: existing ark.config.json, else
+ * the starter --init would write for this tree (same preset resolution as start).
+ */
+export function resolveProjectedCoverageConfig(root, recommendation = {}) {
+  const configPath = path.join(root, 'ark.config.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (parsed && typeof parsed === 'object') {
+        return { config: parsed, source: 'existing-config' };
+      }
+    } catch {
+      /* fall through to starter */
+    }
+  }
+  const preset = resolveStartInitPreset(root, recommendation);
+  if (!preset) return { config: null, source: 'none', preset: null };
+  return { config: starterConfigForPreset(root, preset), source: 'start-starter', preset };
+}
+
+export function measureProjectedGovernedCoverage(root, recommendation = {}) {
+  const resolved = resolveProjectedCoverageConfig(root, recommendation);
+  if (!resolved.config) {
+    return {
+      percent: 0,
+      classifiedFiles: 0,
+      totalFiles: 0,
+      emptyScope: true,
+      source: resolved.source,
+      preset: resolved.preset ?? null,
+    };
+  }
+  return {
+    ...summarizeGovernedCoverage(measureGovernedCoverage(root, resolved.config)),
+    source: resolved.source,
+    preset: resolved.preset ?? recommendation.preset ?? null,
+  };
+}
+
+const PROJECTED_COVERAGE_REASON = /projected governed coverage is \d+% \(below 90%\)/;
+
+export function withProjectedGovernedCoverage(recommendation, root) {
+  if (!recommendation || typeof recommendation !== 'object') return recommendation;
+  const measured = measureProjectedGovernedCoverage(root, recommendation);
+  const percent = measured.percent;
+  const confirmationReasons = (recommendation.confirmationReasons ?? []).filter(
+    (reason) => !PROJECTED_COVERAGE_REASON.test(String(reason))
+  );
+  if (percent < 90) {
+    confirmationReasons.push(`projected governed coverage is ${percent}% (below 90%)`);
+  }
+  return {
+    ...recommendation,
+    requiresConfirmation:
+      Boolean(recommendation.requiresConfirmation) ||
+      percent < 90 ||
+      Boolean(recommendation.thinTsSurface),
+    confirmationReasons,
+    signals: {
+      ...recommendation.signals,
+      projectedGovernedCoverage: percent,
+      projectedGovernedClassifiedFiles: measured.classifiedFiles,
+      projectedGovernedTotalFiles: measured.totalFiles,
+      projectedGovernedSource: measured.source,
+    },
+    projectedCoverage: {
+      percent,
+      classifiedFiles: measured.classifiedFiles,
+      totalFiles: measured.totalFiles,
+    },
+  };
+}

package/bin/lib/recommend-cli.mjs

@@ -0,0 +1,54 @@
+/**
+ * `--recommend` presentation. Lives here so ark-check-runtime stays under the
+ * orchestration LOC budget and doctor does not parse this path.
+ */
+import path from 'node:path';
+import {
+  ADOPTION_PLAN_FILENAME,
+  buildArchitectureRecommendation,
+  formatArchitectureRecommendationHuman,
+  writeAdoptionPlan,
+} from '../ark-shared.mjs';
+import { withProjectedGovernedCoverage } from './projected-governed-coverage.mjs';
+
+export function runRecommend(args) {
+  try {
+    const recommendation = withProjectedGovernedCoverage(
+      buildArchitectureRecommendation(args.root),
+      args.root
+    );
+    let planWritten;
+    if (args.writePlan) {
+      const result = writeAdoptionPlan(args.root, recommendation);
+      planWritten = result.path;
+    }
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ...recommendation,
+            ...(planWritten
+              ? { adoptionPlanPath: path.relative(args.root, planWritten) || ADOPTION_PLAN_FILENAME }
+              : {}),
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(formatArchitectureRecommendationHuman(recommendation));
+      if (planWritten) {
+        console.log('');
+        console.log(`Wrote ${path.relative(args.root, planWritten) || ADOPTION_PLAN_FILENAME}`);
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.error(`ark-check --recommend failed: ${message}`);
+    }
+    process.exitCode = 2;
+  }
+}

package/bin/lib/remediation.mjs

@@ -216,6 +216,10 @@ export function deterministicNextAction(violation) {
             return 'Add metadata.source to the publish call, then run Ark again.';
         case 'INVARIANT_COVERAGE_OUTSIDE_ROOTS':
             return `Move the covering test under a declared coverage root, or add its root to coverage.coverageRoots in ark.config.json, then run Ark again.`;
+        case 'INVARIANT_CATALOG_EMPTY':
+            return typeof violation.file === 'string' && violation.file.length > 0
+                ? `Add 1–2 short phrases to invariants[] in ${violation.file}, then run ark-check --doctor. Starters show the shape.`
+                : 'Add 1–2 short phrases to invariants[] in arkrules/<Domain>.json, then run ark-check --doctor. Starters show the shape.';
         case 'ARKRULE_STRUCTURE':
         case 'ARKRULE_INVARIANT':
         case 'INVARIANT_UNCOVERED':

package/bin/lib/resolved-candidate-facts.mjs

@@ -1168,9 +1168,17 @@ export function resolveCandidateFacts({
   const arkOrderXiFieldWrites = [];
   const arkOrderIngestWritesXi = [];
   const arkOrderReleaseKeyCounts = [];
-  const xiKeys = [...(config.arkOrder?.xiKeys ?? [])];
-  const compositionRootPatterns = [...(config.arkRun?.compositionRoots ?? [])];
-  const planeRootPatterns = [...(config.arkOrder?.planeRoots ?? [])];
+  const arkRunActive = config.arkRun != null && typeof config.arkRun === 'object';
+  const arkOrderActive = config.arkOrder != null && typeof config.arkOrder === 'object';
+  const arkRulesActive =
+    config.arkRules != null &&
+    typeof config.arkRules === 'object' &&
+    Object.keys(config.arkRules).length > 0;
+  const xiKeys = arkOrderActive ? [...(config.arkOrder?.xiKeys ?? [])] : [];
+  const compositionRootPatterns = arkRunActive
+    ? [...(config.arkRun?.compositionRoots ?? [])]
+    : [];
+  const planeRootPatterns = arkOrderActive ? [...(config.arkOrder?.planeRoots ?? [])] : [];
 
   const seedPathSet = new Set(candidateFiles.map((file) => file.path));
   const ingest = (candidate, fullExtract) => {
@@ -1256,60 +1264,67 @@ export function resolveCandidateFacts({
     );
     // Class-shape extraction is text-conservative (false negatives over false positives).
     // Only TS/TSX candidates; sensors consume the same shape via facts.classShapes.
+    // Extra-plane and ArkRules extractors stay silent when that plane is off (#212).
     if (/\.(tsx?|mts|cts)$/i.test(candidate.path)) {
-      try {
-        classShapes.push(...extractClassShapesFromSource(candidate.path, candidate.content));
-      } catch {
-        // Never fail the resolver for shape extraction; sensors stay silent on this file.
-      }
-      try {
-        arkRunKernelCalls.push(
-          ...extractArkRunKernelCallsFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkRun call extraction.
-      }
-      try {
-        arkRunDeclarations.push(
-          ...extractArkRunDeclarationsFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkRun declaration extraction.
-      }
-      try {
-        arkOrderPlaneCalls.push(
-          ...extractArkOrderPlaneCallsFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder factory extraction.
-      }
-      try {
-        arkOrderGenericUpdates.push(
-          ...extractArkOrderGenericUpdatesFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder generic-update extraction.
-      }
-      try {
-        arkOrderXiFieldWrites.push(
-          ...extractArkOrderXiFieldWritesFromSource(candidate.path, candidate.content, xiKeys)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder xi-field-write extraction.
+      if (arkRulesActive || arkRunActive) {
+        try {
+          classShapes.push(...extractClassShapesFromSource(candidate.path, candidate.content));
+        } catch {
+          // Never fail the resolver for shape extraction; sensors stay silent on this file.
+        }
       }
-      try {
-        arkOrderIngestWritesXi.push(
-          ...extractArkOrderIngestWritesXiFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder ingest-writes-ξ extraction.
+      if (arkRunActive) {
+        try {
+          arkRunKernelCalls.push(
+            ...extractArkRunKernelCallsFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkRun call extraction.
+        }
+        try {
+          arkRunDeclarations.push(
+            ...extractArkRunDeclarationsFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkRun declaration extraction.
+        }
       }
-      try {
-        arkOrderReleaseKeyCounts.push(
-          ...extractArkOrderReleaseKeyCountsFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder release key-count extraction.
+      if (arkOrderActive) {
+        try {
+          arkOrderPlaneCalls.push(
+            ...extractArkOrderPlaneCallsFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder factory extraction.
+        }
+        try {
+          arkOrderGenericUpdates.push(
+            ...extractArkOrderGenericUpdatesFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder generic-update extraction.
+        }
+        try {
+          arkOrderXiFieldWrites.push(
+            ...extractArkOrderXiFieldWritesFromSource(candidate.path, candidate.content, xiKeys)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder xi-field-write extraction.
+        }
+        try {
+          arkOrderIngestWritesXi.push(
+            ...extractArkOrderIngestWritesXiFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder ingest-writes-ξ extraction.
+        }
+        try {
+          arkOrderReleaseKeyCounts.push(
+            ...extractArkOrderReleaseKeyCountsFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder release key-count extraction.
+        }
       }
     }
   };
@@ -1355,18 +1370,20 @@ export function resolveCandidateFacts({
     ? candidateFiles.filter((file) => seedPathSet.has(file.path))
     : candidateFiles;
   const admittedTypeNames = new Set(classShapes.map((shape) => shape.className));
-  for (const candidate of extractCandidates) {
-    if (!/\.(tsx?|mts|cts)$/i.test(candidate.path)) continue;
-    try {
-      arkRunManagedNews.push(
-        ...extractArkRunManagedNewsFromSource(
-          candidate.path,
-          candidate.content,
-          admittedTypeNames
-        )
-      );
-    } catch {
-      // Never fail the resolver for managed-new extraction.
+  if (arkRunActive) {
+    for (const candidate of extractCandidates) {
+      if (!/\.(tsx?|mts|cts)$/i.test(candidate.path)) continue;
+      try {
+        arkRunManagedNews.push(
+          ...extractArkRunManagedNewsFromSource(
+            candidate.path,
+            candidate.content,
+            admittedTypeNames
+          )
+        );
+      } catch {
+        // Never fail the resolver for managed-new extraction.
+      }
     }
   }