arkgate 4.8.14 → 4.8.16

package/bin/lib/invariant-tests-path.mjs

@@ -0,0 +1,212 @@
+/**
+ * Adopted-mode domain-invariant tests path (P2 §10 / Contener).
+ * Tooling I/O over Domain collectMissingInvariantTestsPathFindings.
+ * Fail-closed when adopted. Silent when not adopted or the catalog is empty.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  classifyAdopted,
+  isAdopted,
+  readAdoptionStance,
+} from './adoption-stance.mjs';
+import {
+  catalogDemandsInvariantTestsPath,
+  catalogHasEnforcedInvariant,
+  configuredCoverageRoots,
+  configuredInvariantTestsPaths,
+  collectMissingCoverageRootsFindings,
+  collectMissingInvariantTestsPathFindings,
+  hasConfiguredCoverageRoots,
+  hasConfiguredInvariantTestsPath,
+  INVARIANT_COVERAGE_ROOTS_MESSAGE,
+  INVARIANT_TESTS_PATH_MESSAGE,
+} from './invariant-coverage.mjs';
+import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+
+export const INVARIANT_TESTS_PATH_ASK = INVARIANT_TESTS_PATH_MESSAGE;
+
+export const INVARIANT_TESTS_PATH_NEXT =
+  'Add coverage.testGlobs or coverage.coverageRoots in ark.config.json pointing at a real tests folder, then re-run.';
+
+export const INVARIANT_COVERAGE_ROOTS_ASK = INVARIANT_COVERAGE_ROOTS_MESSAGE;
+
+export const INVARIANT_COVERAGE_ROOTS_NEXT =
+  'Add coverage.coverageRoots in ark.config.json pointing at the folder the test runner uses, then re-run.';
+
+/**
+ * --require-gates / --strict-merge, or an explicit advisory-only ack.
+ * GitHub required-merge is known later in doctor; the scan uses this cheap side.
+ *
+ * @param {string} root
+ * @param {{ requireGates?: boolean }} [args]
+ */
+export function scanDemandsInvariantTestsPath(root, args = {}) {
+  if (args.requireGates === true) return true;
+  return isAdopted(classifyAdopted({ stance: readAdoptionStance(root) }));
+}
+
+/**
+ * First concrete path segment exists, or every declared glob is wildcard-only.
+ *
+ * @param {string} root
+ * @param {{ testGlobs?: unknown, coverageRoots?: unknown } | null | undefined} coverage
+ */
+export function declaredInvariantTestsPathPresent(root, coverage) {
+  const declared = configuredInvariantTestsPaths(coverage);
+  if (declared.length === 0) return false;
+  if (typeof root !== 'string' || root.length === 0) return true;
+  let sawConcrete = false;
+  for (const entry of declared) {
+    const prefix = entry.split(/[*?]/)[0].replace(/\/$/, '');
+    if (!prefix) continue;
+    sawConcrete = true;
+    const abs = path.resolve(root, prefix);
+    const rel = path.relative(path.resolve(root), abs).replace(/\\/g, '/');
+    if (!rel || rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) continue;
+    try {
+      if (fs.existsSync(abs)) return true;
+    } catch {
+      continue;
+    }
+  }
+  return !sawConcrete;
+}
+
+/**
+ * Doctor residual when adopted + invariants + missing/empty tests path.
+ *
+ * @param {{
+ *   adopted?: boolean,
+ *   coverage?: { testGlobs?: unknown, coverageRoots?: unknown } | null,
+ *   config?: object,
+ *   invariants?: unknown[],
+ *   hasDomainInvariants?: boolean,
+ *   root?: string,
+ * }} [input]
+ * @returns {{ missing: true, ask: string, nextAction: string } | null}
+ */
+function residualDemandsInvariantTests(input) {
+  if (input.hasDomainInvariants === true) return true;
+  if (input.hasDomainInvariants === false) return false;
+  if (Array.isArray(input.invariants)) return catalogDemandsInvariantTestsPath(input.invariants);
+  if (typeof input.root === 'string' && input.config) {
+    try {
+      const loaded = loadEffectiveArkRulesFromDisk(input.root, input.config);
+      if (loaded.errors?.length) return false;
+      return catalogDemandsInvariantTestsPath(loaded.arkRules?.invariants);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+export function collectInvariantTestsPathResidual(input = {}) {
+  if (input.adopted !== true) return null;
+  const coverage = input.coverage ?? input.config?.coverage;
+  const present =
+    typeof input.root === 'string' && input.root.length > 0
+      ? declaredInvariantTestsPathPresent(input.root, coverage)
+      : hasConfiguredInvariantTestsPath(coverage);
+  const findings = collectMissingInvariantTestsPathFindings({
+    adopted: true,
+    hasDomainInvariants: residualDemandsInvariantTests(input),
+    coverage,
+    declaredPathPresent: present,
+  });
+  if (findings.length === 0) return null;
+  return {
+    missing: true,
+    ask: findings[0]?.message ?? INVARIANT_TESTS_PATH_ASK,
+    nextAction: INVARIANT_TESTS_PATH_NEXT,
+  };
+}
+
+/**
+ * First concrete coverageRoots segment exists, or every declared glob is wildcard-only.
+ *
+ * @param {string} root
+ * @param {{ coverageRoots?: unknown } | null | undefined} coverage
+ */
+export function declaredCoverageRootsPresent(root, coverage) {
+  const declared = configuredCoverageRoots(coverage);
+  if (declared.length === 0) return false;
+  if (typeof root !== 'string' || root.length === 0) return true;
+  let sawConcrete = false;
+  for (const entry of declared) {
+    const prefix = entry.split(/[*?]/)[0].replace(/\/$/, '');
+    if (!prefix) continue;
+    sawConcrete = true;
+    const abs = path.resolve(root, prefix);
+    const rel = path.relative(path.resolve(root), abs).replace(/\\/g, '/');
+    if (!rel || rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) continue;
+    try {
+      if (fs.existsSync(abs)) return true;
+    } catch {
+      continue;
+    }
+  }
+  return !sawConcrete;
+}
+
+function residualHasEnforcedInvariant(input) {
+  if (input.hasEnforcedInvariant === true) return true;
+  if (input.hasEnforcedInvariant === false) return false;
+  if (Array.isArray(input.invariants)) return catalogHasEnforcedInvariant(input.invariants);
+  const refs = input.config?.arkRules;
+  if (!refs || typeof refs !== 'object' || Object.keys(refs).length === 0) return false;
+  if (typeof input.root === 'string' && input.config) {
+    try {
+      const loaded = loadEffectiveArkRulesFromDisk(input.root, input.config);
+      if (loaded.errors?.length) return false;
+      return catalogHasEnforcedInvariant(loaded.arkRules?.invariants);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** One doctor light: roots residual wins when both would fire. */
+export function collectInvariantCoverageResiduals(input = {}) {
+  const invariantCoverageRoots = collectCoverageRootsResidual(input);
+  return {
+    invariantCoverageRoots,
+    invariantTestsPath: invariantCoverageRoots
+      ? null
+      : collectInvariantTestsPathResidual(input),
+  };
+}
+
+/**
+ * Doctor residual when any invariant is enforced and coverageRoots is missing/empty.
+ *
+ * @param {{
+ *   coverage?: { coverageRoots?: unknown } | null,
+ *   config?: object,
+ *   invariants?: unknown[],
+ *   hasEnforcedInvariant?: boolean,
+ *   root?: string,
+ * }} [input]
+ * @returns {{ missing: true, ask: string, nextAction: string } | null}
+ */
+export function collectCoverageRootsResidual(input = {}) {
+  const coverage = input.coverage ?? input.config?.coverage;
+  const present =
+    typeof input.root === 'string' && input.root.length > 0
+      ? declaredCoverageRootsPresent(input.root, coverage)
+      : hasConfiguredCoverageRoots(coverage);
+  const findings = collectMissingCoverageRootsFindings({
+    hasEnforcedInvariant: residualHasEnforcedInvariant(input),
+    coverage,
+    declaredPathPresent: present,
+  });
+  if (findings.length === 0) return null;
+  return {
+    missing: true,
+    ask: findings[0]?.message ?? INVARIANT_COVERAGE_ROOTS_ASK,
+    nextAction: INVARIANT_COVERAGE_ROOTS_NEXT,
+  };
+}

package/bin/lib/layer-description.mjs

@@ -1,8 +1,12 @@
 /**
- * App-context caption from `layers[].description`.
+ * App-context caption, optional trust tag, and optional owners from layer metadata.
  * Metadata only — callers project it; policyHash strips it elsewhere.
- * Present non-empty string is returned; absence/empty/non-string is undefined.
- *
+ * Present values are returned; absence/empty/invalid is omitted.
+ */
+
+export const LAYER_TRUST_BOUNDARIES = Object.freeze(['public', 'auth', 'admin', 'internal']);
+
+/**
  * @param {{ description?: unknown } | null | undefined} layerOrPlacement
  * @returns {string | undefined}
  */
@@ -15,13 +19,91 @@ export function layerDescriptionCaption(layerOrPlacement) {
 }
 
 /**
- * Project the caption onto place / prepare-write / coverage / doctor JSON.
- * Absence omits the field (never empty string).
+ * @param {{ trustBoundary?: unknown } | null | undefined} layerOrPlacement
+ * @returns {'public' | 'auth' | 'admin' | 'internal' | undefined}
+ */
+export function layerTrustBoundary(layerOrPlacement) {
+  const tag =
+    layerOrPlacement && typeof layerOrPlacement === 'object'
+      ? layerOrPlacement.trustBoundary
+      : undefined;
+  return typeof tag === 'string' && LAYER_TRUST_BOUNDARIES.includes(tag) ? tag : undefined;
+}
+
+/**
+ * @param {{ owners?: unknown } | null | undefined} layerOrPlacement
+ * @returns {string[] | undefined}
+ */
+export function layerOwners(layerOrPlacement) {
+  const raw =
+    layerOrPlacement && typeof layerOrPlacement === 'object' ? layerOrPlacement.owners : undefined;
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+  const ids = raw.filter((entry) => typeof entry === 'string' && entry.length > 0);
+  return ids.length > 0 ? ids : undefined;
+}
+
+function formatOwnerMention(id) {
+  return id.includes('@') ? id : `@${id}`;
+}
+
+/**
+ * One guidance fragment: caption and/or `trust: public` and/or `owner: @handle`.
+ * @param {{ description?: unknown, trustBoundary?: unknown, owners?: unknown } | null | undefined} layerOrPlacement
+ * @returns {string | undefined}
+ */
+export function layerGuidanceLine(layerOrPlacement) {
+  const caption = layerDescriptionCaption(layerOrPlacement);
+  const trust = layerTrustBoundary(layerOrPlacement);
+  const owners = layerOwners(layerOrPlacement);
+  const ownerBit = owners ? `owner: ${owners.map(formatOwnerMention).join(', ')}` : undefined;
+  const bits = [caption, trust ? `trust: ${trust}` : undefined, ownerBit].filter(Boolean);
+  return bits.length > 0 ? bits.join(' · ') : undefined;
+}
+
+/**
+ * Project caption + trust tag + owners onto place / prepare-write / coverage / doctor JSON.
+ * Absence omits the field (never empty string / empty array).
  *
- * @param {{ description?: unknown } | null | undefined} layerOrPlacement
- * @returns {{ description: string } | {}}
+ * @param {{ description?: unknown, trustBoundary?: unknown, owners?: unknown } | null | undefined} layerOrPlacement
+ * @returns {{ description?: string, trustBoundary?: string, owners?: string[] }}
  */
 export function placementDescriptionFields(layerOrPlacement) {
   const caption = layerDescriptionCaption(layerOrPlacement);
-  return caption ? { description: caption } : {};
+  const trust = layerTrustBoundary(layerOrPlacement);
+  const owners = layerOwners(layerOrPlacement);
+  return {
+    ...(caption ? { description: caption } : {}),
+    ...(trust ? { trustBoundary: trust } : {}),
+    ...(owners ? { owners } : {}),
+  };
+}
+
+/**
+ * Doctor residual when requireLayerOwners is on and a live house has no owners.
+ * Absent/false require → null (silent). Not a computeDoctorAdvisories key.
+ *
+ * @param {{ requireLayerOwners?: unknown, layers?: Array<{ name?: string, owners?: unknown, optional?: boolean, reserved?: boolean, allowEmpty?: boolean }> } | null | undefined} config
+ * @returns {{ required: true, missingLayers: string[], ask: string, nextAction: string } | null}
+ */
+export function collectLayerOwnerResidual(config) {
+  if (config?.requireLayerOwners !== true || !Array.isArray(config.layers)) return null;
+  const missing = config.layers
+    .filter(
+      (layer) =>
+        layer &&
+        layer.optional !== true &&
+        layer.reserved !== true &&
+        layer.allowEmpty !== true &&
+        !layerOwners(layer)
+    )
+    .map((layer) => layer.name)
+    .filter((name) => typeof name === 'string' && name.length > 0);
+  if (missing.length === 0) return null;
+  const named = missing[0];
+  return {
+    required: true,
+    missingLayers: missing,
+    ask: `${named} has no owner. Add a GitHub handle or email to layers[].owners.`,
+    nextAction: `Add a GitHub handle or email to ${named}'s owners in ark.config.json (/ark-adopt).`,
+  };
 }

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/package-manager.mjs

@@ -91,6 +91,14 @@ export function arkCommand(root, bin, argsStr = '') {
   return `${execRunner(root)} ${bin}${argsStr ? ` ${argsStr}` : ''}`;
 }
 
+/**
+ * Run an Ark binary from package `arkgate` when local bins may be missing.
+ * Bare `npx arkgate-check` 404s — npx treats that bin name as its own package.
+ */
+export function arkPackageRecoveryCommand(bin, argsStr = '') {
+  return `npx --package=arkgate ${bin}${argsStr ? ` ${argsStr}` : ''}`;
+}
+
 /**
  * Split { command, args } form for JSON/TOML configs (.mcp.json, config.toml) that spawn
  * the binary directly. `pnpm exec ark-mcp` becomes command "pnpm" + args ["exec","ark-mcp",…]

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,
+    },
+  };
+}