arkgate 2.5.0 → 2.6.1

package/bin/ark-shared.mjs

@@ -224,6 +224,10 @@ export function applyFrameworkLayoutOverlays(config, root) {
       'src/services/**',
       'src/use-cases/**',
       'src/lib/**',
+      // Common Next "app core" bags (API clients, hooks, auth, stores) — not UI routes.
+      // Without these, monorepos like */src/core/** stay ungoverned and produce false greens.
+      'src/core/**',
+      '**/core/**',
       'src/actions/**',
       'src/**/actions.ts',
       'src/**/actions.tsx',
@@ -244,6 +248,20 @@ export function applyFrameworkLayoutOverlays(config, root) {
       'src/lib/prisma/**',
       'src/server/db/**',
     ]);
+    // Demo assets, generated public output, and tool configs are not architecture surface.
+    const nextExcludes = [
+      '**/public/**',
+      '**/*.config.js',
+      '**/*.config.ts',
+      '**/*.config.mjs',
+      '**/playwright*.ts',
+      '**/eslint.config.*',
+      '**/postcss.config.*',
+      '**/prettier.config.*',
+      '**/rstest.config.*',
+      '**/scripts/**',
+    ];
+    next.exclude = [...new Set([...(next.exclude ?? []), ...nextExcludes])];
     next.frameworkOverlay = next.frameworkOverlay
       ? `${next.frameworkOverlay}+next`
       : 'next';
@@ -362,137 +380,17 @@ export function collectForbiddenGlobalUses(ts, sourceFile, forbidden) {
   return uses;
 }
 
-const _regexpCache = new Map();
-
-function escapeLiteral(ch) {
-  return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
-}
-
-/** True only when every `{` has a matching `}` (ignoring backslash-escaped braces). */
-function bracesBalanced(glob) {
-  let depth = 0;
-  for (let i = 0; i < glob.length; i += 1) {
-    const c = glob[i];
-    if (c === '\\') {
-      i += 1; // skip the escaped character
-      continue;
-    }
-    if (c === '{') depth += 1;
-    else if (c === '}') {
-      depth -= 1;
-      if (depth < 0) return false;
-    }
-  }
-  return depth === 0;
-}
-
-/**
- * Convert an ark.config.json layer glob pattern to an anchored RegExp (compiled once per
- * pattern, then cached).
- *
- * IMPORTANT: the double-star is expanded in a SINGLE pass. A chained two-step replace
- * (double-star to dot-star, then single-star to a no-slash class) corrupts the double-star,
- * because the second step re-matches the star inside the substitution the first step just
- * inserted. That made "src/kernel/**" stop matching nested paths, silently unclassifying
- * every file in a subdirectory. Scanning one character at a time also lets us support
- * brace alternation ("*.{ts,tsx}") and backslash escapes ("\\{" → literal brace).
- *
- * Brace alternation is only enabled when braces are balanced; an unbalanced brace (a config
- * typo) is treated as a literal so the gate never crashes on `new RegExp`.
- */
-export function globToRegExp(pattern) {
-  const cached = _regexpCache.get(pattern);
-  if (cached) return cached;
-
-  const glob = pattern.split(path.sep).join('/');
-  const useBraces = bracesBalanced(glob);
-  let out = '';
-  let braceDepth = 0;
-  for (let i = 0; i < glob.length; i += 1) {
-    const c = glob[i];
-    if (c === '\\' && i + 1 < glob.length) {
-      out += escapeLiteral(glob[i + 1]); // backslash escapes the next char to a literal
-      i += 1;
-    } else if (c === '*') {
-      if (glob[i + 1] === '*') {
-        if (glob[i + 2] === '/') {
-          out += '(?:.*/)?'; // `**/` matches zero or more path segments
-          i += 2;
-        } else {
-          out += '.*'; // `**` matches across `/`
-          i += 1;
-        }
-      } else {
-        out += '[^/]*'; // `*` matches within a single segment
-      }
-    } else if (c === '?') {
-      out += '[^/]';
-    } else if (c === '{' && useBraces) {
-      out += '(?:';
-      braceDepth += 1;
-    } else if (c === '}' && useBraces && braceDepth > 0) {
-      out += ')';
-      braceDepth -= 1;
-    } else if (c === ',' && useBraces && braceDepth > 0) {
-      out += '|';
-    } else {
-      out += escapeLiteral(c);
-    }
-  }
-  const re = new RegExp(`^${out}$`);
-  _regexpCache.set(pattern, re);
-  return re;
-}
-
-// Specificity score for a layer glob: more literal path segments before the first wildcard
-// wins, then longer literal text. So `src/kernel/app/**` (3 literal segments) beats
-// `src/kernel/**` (2), and an exact file like `src/kernel/events.ts` beats both. This is what
-// makes a facade split (a KernelApi surface layer overlapping a KernelInternal catch-all)
-// resolve to the surface REGARDLESS of layer declaration order — the intuitive result.
-export function patternSpecificity(pattern) {
-  const glob = String(pattern).split(path.sep).join('/');
-  const beforeWildcard = glob.split('*')[0];
-  const literalSegments = beforeWildcard.split('/').filter(Boolean).length;
-  const literalLength = glob.replace(/\*/g, '').length;
-  return literalSegments * 10000 + literalLength;
-}
-
-/**
- * Resolve a file's architecture layer from ark.config.json layer glob patterns. When more
- * than one layer matches (overlapping globs, e.g. a facade split), the MOST SPECIFIC pattern
- * wins; ties break by declaration order (first wins). Order-independent for non-ambiguous
- * overlaps, so a config author can't silently break a facade by listing the catch-all first.
- *
- * A layer may also declare `exclude` globs. A file matching ANY exclude glob is NOT a
- * candidate for that layer even if a `patterns` glob matches — this lets a broad pattern
- * (e.g. `src/**​/domain/**`) carve out subtrees it should not govern (framework internals
- * like `**​/kernel/**`) without enumerating every include. Excluding a file from its layer
- * also removes it from that layer's rule and `forbiddenGlobals` enforcement, since both key
- * off this classification — which is exactly how a broad domain glob stops mis-flagging
- * `src/kernel/domain` as impure domain code. This is the single file→layer matcher shared by
- * the ark-check CI gate and the ark-mcp write gate, so `exclude` behaves identically in both.
- */
-export function layerForFile(root, file, layers) {
-  const abs = path.isAbsolute(file) ? file : path.resolve(root, file);
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  let bestName;
-  let bestScore = -1;
-  for (const layer of layers ?? []) {
-    if ((layer.exclude ?? []).some((pattern) => globToRegExp(pattern).test(rel))) {
-      continue;
-    }
-    for (const pattern of layer.patterns ?? []) {
-      if (globToRegExp(pattern).test(rel)) {
-        const score = patternSpecificity(pattern);
-        if (score > bestScore) {
-          bestScore = score;
-          bestName = layer.name;
-        }
-      }
-    }
-  }
-  return bestName;
-}
+// Layer glob matching — single source of truth in ark-layer-match.mjs (also used by ESLint).
+export {
+  globToRegExp,
+  patternSpecificity,
+  layerForFile,
+  layerForRelativePath,
+  isEdgeDenied,
+  DEFAULT_GENERATED_FILE_GLOBS,
+  scanExcludePatterns,
+  isScanExcludedRelative,
+} from './ark-layer-match.mjs';
 
 function normalizePrefix(prefix) {
   return prefix.endsWith('.') ? prefix : `${prefix}.`;
@@ -842,7 +740,15 @@ function readPackageJson(root) {
   }
 }
 
-/** Workspace roots from package.json workspaces and pnpm-workspace.yaml (no YAML dependency). */
+/**
+ * Workspace / multi-package roots for monorepo include.
+ * Sources (universal — no project-specific names):
+ * 1. package.json workspaces + pnpm-workspace.yaml
+ * 2. rush.json projectFolder top segments (JSONC-tolerant)
+ * 3. lerna.json packages globs
+ * 4. If still empty: conventional multi-package top-level dirs that exist and
+ *    contain at least one package.json (packages, apps, plugins, services, …)
+ */
 export function detectWorkspaces(root) {
   const dirs = new Set();
   const addGlob = (glob) => {
@@ -850,9 +756,16 @@ export function detectWorkspaces(root) {
     const beforeStar = glob.split('*')[0].replace(/\/+$/, '');
     if (beforeStar && beforeStar !== '.') dirs.add(normalizeRel(beforeStar));
   };
+  const addTop = (rel) => {
+    if (typeof rel !== 'string') return;
+    const top = rel.split(/[/\\]/).filter(Boolean)[0];
+    if (top && top !== '.') dirs.add(normalizeRel(top));
+  };
+
   const pkg = readPackageJson(root);
   const ws = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
   if (Array.isArray(ws)) ws.forEach(addGlob);
+
   const pnpmFile = path.join(root, 'pnpm-workspace.yaml');
   if (fs.existsSync(pnpmFile)) {
     let inPackages = false;
@@ -867,9 +780,183 @@ export function detectWorkspaces(root) {
       if (item) addGlob(item[1].trim());
     }
   }
+
+  // Rush monorepos often have no root package.json workspaces — only rush.json.
+  const rushFile = path.join(root, 'rush.json');
+  if (fs.existsSync(rushFile)) {
+    try {
+      let text = fs.readFileSync(rushFile, 'utf8');
+      text = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+      const rush = JSON.parse(text);
+      for (const project of rush.projects || []) {
+        if (typeof project?.projectFolder === 'string') addTop(project.projectFolder);
+      }
+    } catch {
+      /* ignore malformed rush.json */
+    }
+  }
+
+  // Lerna packages globs.
+  const lernaFile = path.join(root, 'lerna.json');
+  if (fs.existsSync(lernaFile)) {
+    try {
+      const lerna = JSON.parse(fs.readFileSync(lernaFile, 'utf8'));
+      if (Array.isArray(lerna.packages)) lerna.packages.forEach(addGlob);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // Conventional multi-package roots when no explicit workspace manifest listed roots.
+  if (dirs.size === 0) {
+    const conventional = [
+      'packages',
+      'apps',
+      'plugins',
+      'services',
+      'server',
+      'servers',
+      'server-plugins',
+      'libs',
+      'lib',
+      'modules',
+      'foundations',
+      'pods',
+      'models',
+      'clients',
+      'sdks',
+      'tools',
+      'tooling',
+      'desktop',
+      'common',
+    ];
+    for (const name of conventional) {
+      const abs = path.join(root, name);
+      if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
+      if (dirContainsPackageJson(abs, 2)) dirs.add(name);
+    }
+  }
+
   return [...dirs];
 }
 
+/** True if dir (or a child within maxDepth) has a package.json — multi-package root signal. */
+function dirContainsPackageJson(dir, maxDepth) {
+  try {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return true;
+    if (maxDepth <= 0) return false;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      if (dirContainsPackageJson(path.join(dir, entry.name), maxDepth - 1)) return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+const SKIP_DIR_NAMES = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  '.git',
+  '.next',
+  '.turbo',
+  '.cache',
+  'vendor',
+  '__pycache__',
+]);
+
+function dirHasTsSources(dir, maxDepth) {
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isFile() && /\.(tsx?|jsx?|mts|cts)$/i.test(entry.name)) return true;
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
+      if (maxDepth > 0 && dirHasTsSources(path.join(dir, entry.name), maxDepth - 1)) return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+/**
+ * Discover package roots that contain TypeScript/JS sources (polyglot-safe).
+ * Returns relative paths (e.g. remotion-composer, packages/ui). Caps depth/count
+ * to avoid scanning huge trees. Universal — no project-specific names.
+ */
+export function detectTsPackageRoots(root, options = {}) {
+  const maxDepth = options.maxDepth ?? 3;
+  const maxRoots = options.maxRoots ?? 40;
+  const found = [];
+
+  const visit = (abs, rel, depth) => {
+    if (found.length >= maxRoots || depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const hasPkg = entries.some((e) => e.isFile() && e.name === 'package.json');
+    if (hasPkg && rel && dirHasTsSources(abs, 3)) {
+      found.push(rel.split(path.sep).join('/'));
+      // Do not descend into nested packages under an already-selected package root
+      // unless maxDepth allows and we want monorepo packages/* children — still scan children
+      // for nested packages (packages/foo).
+    }
+    if (depth >= maxDepth) return;
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
+      // Skip agent skill asset trees (not app code).
+      if (entry.name === 'skills' || entry.name === 'templates' || entry.name === 'fixtures') continue;
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      visit(path.join(abs, entry.name), childRel, depth + 1);
+    }
+  };
+
+  visit(root, '', 0);
+  // Also treat root itself if it has package.json + TS
+  if (fs.existsSync(path.join(root, 'package.json')) && dirHasTsSources(root, 2)) {
+    if (!found.includes('.')) {
+      // Prefer explicit '.' only when no nested packages found
+      if (found.length === 0) found.push('.');
+    }
+  }
+  return [...new Set(found)].sort();
+}
+
+/**
+ * Merge workspace globs with TS package roots. If workspaces alone would miss
+ * all TS (or are empty), fill from detectTsPackageRoots.
+ */
+export function resolveIncludeRoots(root) {
+  const workspaces = detectWorkspaces(root);
+  const tsRoots = detectTsPackageRoots(root);
+  if (workspaces.length === 0) {
+    if (tsRoots.length > 0) return tsRoots.filter((r) => r !== '.');
+    return [];
+  }
+  // Workspaces present: keep them, add TS package roots not covered by a workspace prefix
+  const merged = new Set(workspaces);
+  for (const tr of tsRoots) {
+    if (tr === '.') continue;
+    const covered = workspaces.some(
+      (w) => tr === w || tr.startsWith(`${w}/`) || w.startsWith(`${tr}/`)
+    );
+    if (!covered) merged.add(tr.split('/')[0]); // top segment if nested
+    // Prefer full package path when it's a direct child
+    if (!tr.includes('/') || workspaces.includes(tr.split('/')[0])) {
+      if (fs.existsSync(path.join(root, tr, 'package.json'))) merged.add(tr);
+    }
+  }
+  return [...merged];
+}
+
 function isSourceFile(name) {
   return /\.(tsx?|jsx?|mjsx?|cjsx?|mts|cts)$/i.test(name);
 }
@@ -945,6 +1032,47 @@ function countTsxFiles(files) {
   return files.filter((f) => /\.(tsx|jsx)$/i.test(f)).length;
 }
 
+/**
+ * Merge root + nested package.json dependencies (frontend/, packages/*, apps/*, …).
+ * Hosts that only put `arkgate` at the monorepo root and Next under frontend/ must
+ * still detect nextFramework so layout overlays (src/core/**) apply on day one.
+ */
+export function collectAggregatedDeps(root) {
+  const deps = {};
+  const mergePkg = (pkg) => {
+    if (!pkg || typeof pkg !== 'object') return;
+    for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+      const block = pkg[key];
+      if (block && typeof block === 'object') Object.assign(deps, block);
+    }
+  };
+  mergePkg(readPackageJson(root));
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return deps;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    const childRoot = path.join(root, entry.name);
+    mergePkg(readPackageJson(childRoot));
+    // One level under conventional multi-package roots
+    if (['packages', 'apps', 'services', 'plugins', 'packages-internal'].includes(entry.name)) {
+      try {
+        for (const sub of fs.readdirSync(childRoot, { withFileTypes: true })) {
+          if (sub.isDirectory() && !sub.name.startsWith('.')) {
+            mergePkg(readPackageJson(path.join(childRoot, sub.name)));
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return deps;
+}
+
 /**
  * Collect deterministic repo shape signals for architecture archetype scoring.
  * Vendor packages may appear in toolHints only — never as the primary label.
@@ -953,7 +1081,20 @@ export function collectRepoShapeSignals(root) {
   const pkg = readPackageJson(root);
   const workspaceDirs = detectWorkspaces(root);
   const workspaces = workspaceDirs.length > 0;
-  const srcDirs = ['src', 'lib', 'api', 'packages', 'apps'].filter((d) =>
+  // Include frontend/web/client — common Next monorepo app folders (deer-flow-style).
+  const candidateScanDirs = [
+    'src',
+    'lib',
+    'api',
+    'packages',
+    'apps',
+    'frontend',
+    'web',
+    'client',
+    'app',
+    ...workspaceDirs,
+  ];
+  const srcDirs = [...new Set(candidateScanDirs)].filter((d) =>
     fs.existsSync(path.join(root, d))
   );
   const scanRoots = srcDirs.length > 0 ? srcDirs.map((d) => path.join(root, d)) : [root];
@@ -961,13 +1102,14 @@ export function collectRepoShapeSignals(root) {
   const sourceFileCount = sourceFiles.length;
   const tinyTree = sourceFileCount < 3;
 
-  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  // Nested package.json deps (not root-only) — critical for monorepo Next under frontend/
+  const deps = collectAggregatedDeps(root);
   const hasUiFramework = Object.keys(deps).some((name) =>
     /^(react|react-dom|vue|svelte|preact|solid-js)$/i.test(name.split('/')[0])
   );
   const srcUiFiles = sourceFiles.filter((file) => {
     const rel = path.relative(root, file).split(path.sep).join('/');
-    return rel.startsWith('src/') && /\.(tsx|jsx)$/i.test(file);
+    return (rel.includes('/src/') || rel.startsWith('src/')) && /\.(tsx|jsx)$/i.test(file);
   });
 
   const topNames = new Set(srcDirs.flatMap((d) => listTopLevelDirNames(root, d)));
@@ -983,7 +1125,8 @@ export function collectRepoShapeSignals(root) {
       const rel = path.relative(root, file).split(path.sep).join('/');
       return (
         /(^|\/)next\.config\./.test(rel) ||
-        /(^|\/)app\/.*\/page\.(t|j)sx?$/.test(rel) ||
+        // app/page.tsx OR app/dashboard/page.tsx (middle segment optional)
+        /(^|\/)app\/(?:.*\/)?page\.(t|j)sx?$/.test(rel) ||
         /(^|\/)pages\/.+\.(t|j)sx?$/.test(rel)
       );
     });
@@ -1250,7 +1393,15 @@ export function scoreArchetypes(signals, playbook) {
   const rawConfidence = top.score / top.maxPositive;
   const margin =
     second && second.score > 0 ? (top.score - second.score) / Math.max(top.score, 1) : 0.25;
-  const confidence = Math.min(1, Math.max(0.1, rawConfidence * 0.7 + margin * 0.3));
+  let confidence = Math.min(1, Math.max(0.1, rawConfidence * 0.7 + margin * 0.3));
+  // Thin / zero TS surface: never present a high-confidence archetype as the sole answer.
+  const thinTs =
+    !signals.sourceFileCount ||
+    signals.sourceFileCount < 8 ||
+    signals.tinyTree;
+  if (thinTs) {
+    confidence = Math.min(confidence, 0.28);
+  }
 
   return {
     ranked: scored,
@@ -1258,6 +1409,13 @@ export function scoreArchetypes(signals, playbook) {
     label: top.label,
     preset: top.preset,
     confidence: Math.round(confidence * 1000) / 1000,
+    ...(thinTs
+      ? {
+          thinTsSurface: true,
+          caution:
+            'TypeScript/JS surface is thin or missing — treat the archetype as a weak hint. Prefer ark-check --suggest-include / --adopt-contract on the real package roots before scaffolding.',
+        }
+      : {}),
     phases: top.phases,
     analogy: top.analogy,
     antiPatterns: top.antiPatterns,
@@ -1292,6 +1450,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
     label: result.label,
     preset: result.preset,
     confidence: result.confidence,
+    ...(result.thinTsSurface ? { thinTsSurface: true, caution: result.caution } : {}),
     phases: result.phases,
     adoptInOrder,
     analogy: result.analogy,
@@ -1457,6 +1616,13 @@ export function formatArchitectureRecommendationHuman(recommendation) {
   lines.push('');
   lines.push(`Archetype: ${recommendation.archetype} — ${recommendation.label}`);
   lines.push(`Preset: ${recommendation.preset} (confidence ${recommendation.confidence})`);
+  if (recommendation.thinTsSurface) {
+    lines.push('');
+    lines.push(
+      `⚠ Thin TypeScript surface (${recommendation.signals?.sourceFileCount ?? 0} files) — confidence is capped. Do not treat this as a firm shape.`
+    );
+    if (recommendation.caution) lines.push(recommendation.caution);
+  }
   if (recommendation.runnerUp?.id) {
     lines.push(
       `Runner-up: ${recommendation.runnerUp.id}${recommendation.runnerUp.label ? ` (${recommendation.runnerUp.label})` : ''}`

package/bin/ark.mjs

@@ -10,6 +10,8 @@ import {
   buildArchitectureRecommendation,
   detectPackageManager,
   detectWorkspaces,
+  resolveIncludeRoots,
+  detectTsPackageRoots,
   INIT_WIZARD_CHOICES,
   isValidArchetypeId,
   mapWizardChoiceToArchetype,
@@ -345,16 +347,32 @@ async function start(args) {
     if (!fs.existsSync(configPath)) {
       const initArgs = ['--root', root, '--init'];
       const preset = archetype ? resolveArchetypePreset(archetype).preset : undefined;
+      const includeRoots = resolveIncludeRoots(root);
+      const tsPackages = detectTsPackageRoots(root);
       const workspaces = detectWorkspaces(root);
       const looksLikeMonorepo =
+        includeRoots.length > 0 ||
+        tsPackages.length > 0 ||
         workspaces.length > 0 ||
+        fs.existsSync(path.join(root, 'rush.json')) ||
+        fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) ||
+        fs.existsSync(path.join(root, 'lerna.json')) ||
         fs.existsSync(path.join(root, 'apps')) ||
         fs.existsSync(path.join(root, 'packages'));
-      // Mature multi-package trees must NOT get a thin src/** starter (0 files → false green).
-      // Prefer the monorepo preset so include roots match apps/packages/tooling.
-      if (looksLikeMonorepo && (rec?.mature || workspaces.length > 0)) {
-        initArgs.push('--preset', 'monorepo');
-        console.log('  Multi-package layout detected — using monorepo profile.');
+      // Mature multi-package / nested-TS trees must NOT get a thin src/** starter (0 files).
+      if (looksLikeMonorepo && (rec?.mature || includeRoots.length > 0 || tsPackages.length > 0)) {
+        // UI-heavy TS packages (Remotion/Vite) prefer ui-surface patterns when recommend says so.
+        const useUi =
+          rec?.preset === 'feature-sliced' ||
+          rec?.archetype === 'frontend-surface' ||
+          (tsPackages.length > 0 && includeRoots.length === 0 && !rec?.mature);
+        initArgs.push('--preset', useUi && tsPackages.length <= 3 ? 'ui-surface' : 'monorepo');
+        const shown = includeRoots.length > 0 ? includeRoots : tsPackages;
+        console.log(
+          shown.length > 0
+            ? `  Multi-package / TS package layout detected — profile include: ${shown.join(', ')}.`
+            : '  Multi-package layout detected — using monorepo profile.'
+        );
       } else if (!rec?.mature && preset) {
         initArgs.push('--preset', preset);
       }
@@ -363,7 +381,12 @@ async function start(args) {
     } else {
       console.log('  Found an existing ark.config.json — keeping it.');
     }
-    runArkCheck(['--root', root, '--install-agent-gates'], { cwd: root });
+    {
+      const gateArgs = ['--root', root, '--install-agent-gates'];
+      if (args.tools) gateArgs.push('--tools', args.tools);
+      if (args.force) gateArgs.push('--force');
+      runArkCheck(gateArgs, { cwd: root });
+    }
 
     // 4) Show the plan: what's safe to auto-fix vs what needs a decision.
     console.log('');
@@ -406,49 +429,36 @@ async function start(args) {
       planOk = false;
     }
 
-    // 5) Plain-language wrap-up — three operating modes, one contract.
-    // suggest = greenfield shape proposal; adapt = match real layout / raise coverage;
-    // enforce = contract actually governs code and gates stay on.
+    // 5) Plain-language wrap-up — one next step, status light only.
+    // Modes are detected (Suggest/Adapt/Enforce), not user-picked settings.
     console.log('');
     if (mode === 'enforce' && planOk) {
-      console.log('Done — Ark is in ENFORCE mode: your contract governs the code and the gates stay on.');
+      console.log('Done — status: ENFORCE (gates can honestly protect you).');
       console.log('What happens now:');
       console.log('  • Every edit is checked (in CI and, if wired, at write time).');
-      console.log('  • Carry out remaining plan steps with /ark-autopilot (safe auto + your approvals).');
     } else if (mode === 'suggest') {
-      console.log('Done — Ark is in SUGGEST mode: a starting shape is installed; enforcement grows as you add layers.');
+      console.log('Done — status: SUGGEST (starting shape installed; expand as you grow).');
       console.log('What happens now:');
-      console.log('  • Gates are on for whatever the contract already matches.');
-      console.log('  • Expand coverage as you create real layer folders (see the plan above).');
       if (governedPercent != null) {
-        console.log(`  • Right now Ark governs ~${governedPercent}% of in-scope files — low is normal on a fresh scaffold.`);
+        console.log(`  • Ark governs ~${governedPercent}% of in-scope files — low is normal on a fresh scaffold.`);
       }
-      console.log('  • When you want the agent to drive the plan: /ark-autopilot');
     } else {
-      console.log('Done — Ark is in ADAPT mode: config is in place, but the contract still needs to match your real layout.');
+      console.log('Done — status: ADAPT (contract still aligning with your real layout).');
       console.log('What happens now:');
       if (governedPercent != null) {
         console.log(
-          `  • Governed coverage is ~${governedPercent}% — a "clean" plan with low coverage checks almost nothing.`
+          `  • Governed ~${governedPercent}% — a "clean" plan with low coverage checks almost nothing.`
         );
       }
-      console.log(`  • See what is unmatched:  ${arkCommand(root, 'ark-check', '--coverage')}`);
-      console.log('  • On a mature repo, prefer /ark-adopt over forcing a starter preset.');
-      console.log('  • Drive fixes with /ark-autopilot once the contract matches; until then ENFORCE is not honest.');
-    }
-    console.log(`  • Re-run the plan anytime:   ${arkCommand(root, 'ark-check', '--plan')}`);
-    console.log(`  • Full project check:        ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}`);
-    console.log(`  • Adoption health:           ${arkCommand(root, 'ark-check', '--doctor')}`);
-    console.log(`  • Update Ark later:          ${arkCommand(root, 'ark', 'upgrade')}`);
-    if (fs.existsSync(path.join(root, '.ark-baseline.json'))) {
-      console.log(
-        '  • Baseline file present — keep empty for ratchet-from-clean, or freeze debt with --update-baseline.'
-      );
-    } else {
-      console.log(
-        '  • No baseline yet (fine on clean trees). Adopting dirty code? freeze with --update-baseline.'
-      );
     }
+    console.log('');
+    console.log('Next (the only flow you need):');
+    console.log('  1. In your agent:  /ark-autopilot');
+    console.log('     → origin report, adoption, plan, safe fixes, leave gates on.');
+    console.log(`  2. Status anytime: ${arkCommand(root, 'ark-check', '--doctor')}`);
+    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}`);
+    console.log('');
+    console.log('Optional later: --plan · --coverage · /ark-fix · /ark-place · ark upgrade');
 
     // 6) First architecture report — freezes an origin snapshot under .ark/reports/
     // so later --report runs can show evolution. Idempotent: origin is written only once.