arkgate 2.8.3 → 2.9.1

package/bin/ark.mjs

@@ -18,6 +18,7 @@ import {
   resolveArchetypePreset,
   resolveOperatingMode,
 } from './ark-shared.mjs';
+import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -55,7 +56,7 @@ function parseArgs(argv) {
 function usage() {
   return `Usage:
   ark start   [--root <project>] [--yes]
-  ark init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo]
+  ark init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture]
               [--archetype <playbook-id>] [--tools <list>] [--yes] [--force] [--no-strict]
   ark upgrade [--root <project>] [--no-install] [--no-strict]
 
@@ -70,23 +71,32 @@ Commands:
 
 Options:
   --yes        Non-interactive defaults: create config if needed, install gate templates, run strict check.
+               (Also the implicit default when stdin/stdout are not a TTY — agents never hang on prompts.)
   --force      Allow generated files to overwrite existing files.
   --no-strict  Skip the final strict ark-check run.
-  --no-install (upgrade) Refresh gates/skills only; don't reinstall the package.
+  --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
   --preset     Start from a named architecture preset instead of detection.
   --archetype  Application shape from templates/architecture-playbook.json (maps to the matching preset).
                Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
-               worker-pipeline, event-coordinator, integration-bridge, multi-app-workspace, prototype-spike.
-  --tools      Comma-separated agents to gate (claude,cursor,codex,windsurf,cline,copilot,kiro,roo,continue,gemini).
-               Omit to auto-detect from each tool's config dir, falling back to claude+cursor+codex.
+               worker-pipeline, event-coordinator, integration-bridge, multi-app-workspace, prototype-spike,
+               vertical-slice-product, ddd-bounded-contexts.
+  --tools      Comma-separated agents to gate (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
+               Omit to auto-detect from each tool's config dir, falling back to claude+cursor+codex+grok.
 
 Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
+Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.
 `;
 }
 
-// The package-manager command that adds arkgate@latest as a dev dependency.
-function packageInstallArgv(root) {
-  const spec = 'arkgate@latest';
+// The package-manager command that adds arkgate as a dev dependency.
+// Prefer an explicit version/range when pin already chose one (avoid pin=^2.9.0 then
+// `npm i arkgate@latest` rewriting package.json to a different range).
+function packageInstallArgv(root, versionSpec) {
+  const range =
+    typeof versionSpec === 'string' && versionSpec.trim()
+      ? versionSpec.trim()
+      : 'latest';
+  const spec = range.startsWith('arkgate@') ? range : `arkgate@${range}`;
   const pm = detectPackageManager(root);
   if (pm === 'pnpm') return ['pnpm', ['add', '-D', spec]];
   if (pm === 'yarn') return ['yarn', ['add', '-D', spec]];
@@ -165,13 +175,49 @@ function isInteractiveTty() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
+/**
+ * True when prompts should be skipped and guided defaults applied.
+ * Agents typically have no TTY — never call readline on a null interface.
+ */
+export function shouldUseNonInteractiveDefaults(args, tty = isInteractiveTty()) {
+  return Boolean(args?.yes || !tty);
+}
+
 async function askYesNo(rl, question, defaultYes = true) {
+  if (!rl) {
+    // Defensive: non-TTY callers must not reach here; return the default rather than throw.
+    return defaultYes;
+  }
   const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] ';
   const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase();
   if (!answer) return defaultYes;
   return answer === 'y' || answer === 'yes';
 }
 
+/**
+ * Pin arkgate in package.json (and optionally run the package manager).
+ * start calls this so CI/`npx` is not forced to rely on a stale global install.
+ *
+ * @param {string} root
+ * @param {{ install?: boolean, runPackageManager?: boolean }} [opts]
+ */
+export function ensureProjectArkgateDependency(root, opts = {}) {
+  const install = opts.install !== false;
+  const runPm = opts.runPackageManager === true;
+  if (!install) {
+    return { pinned: { changed: false, reason: 'skipped-no-install' }, installStatus: null };
+  }
+  const pinned = pinArkgateDevDependency(root);
+  let installStatus = null;
+  // Only run the package manager after a successful pin change — avoid surprise
+  // network on every start when arkgate is already listed.
+  if (runPm && pinned.changed) {
+    const [command, commandArgs] = packageInstallArgv(root, pinned.version);
+    installStatus = runCommand(command, commandArgs, root);
+  }
+  return { pinned, installStatus };
+}
+
 async function resolveArchetypeInteractive(rl, root) {
   console.log('');
   console.log('What are you building? (application shape — not a framework name)');
@@ -213,12 +259,19 @@ function resolveInitPreset(args) {
 async function init(args) {
   const root = args.root;
   const configPath = path.join(root, 'ark.config.json');
-  const interactive = !args.yes && isInteractiveTty();
+  const nonInteractive = shouldUseNonInteractiveDefaults(args);
+  const interactive = !nonInteractive;
   const rl = interactive
     ? readline.createInterface({ input: process.stdin, output: process.stdout })
     : null;
 
   try {
+    if (nonInteractive && !args.yes) {
+      console.log(
+        'Non-interactive session (no TTY) — using guided defaults (same as --yes). Pass flags to override.'
+      );
+    }
+
     let archetype = args.archetype;
     let preset = args.preset;
 
@@ -230,9 +283,8 @@ async function init(args) {
       const resolved = resolveArchetypePreset(archetype);
       preset = resolved.preset;
       console.log(`Using archetype ${archetype} → preset ${preset} (${resolved.label})`);
-    } else if (!preset && !interactive && !args.yes) {
-      // non-TTY without --yes/--preset/--archetype: fall back to detection init
-    } else if (!preset && args.yes && !archetype) {
+    } else if (!preset && nonInteractive && !archetype) {
+      // non-TTY / --yes without explicit shape: recommend → preset
       const rec = buildArchitectureRecommendation(root);
       preset = rec.preset;
       archetype = rec.archetype;
@@ -243,7 +295,7 @@ async function init(args) {
     if (fs.existsSync(configPath)) {
       shouldInit = args.force
         ? true
-        : args.yes
+        : nonInteractive
           ? false
           : await askYesNo(rl, 'ark.config.json already exists. Regenerate it?', false);
     }
@@ -258,7 +310,8 @@ async function init(args) {
       console.log('Skipped ark.config.json generation.');
     }
 
-    const installGates = args.yes || (await askYesNo(rl, 'Configure agent and CI gate templates?', true));
+    const installGates =
+      nonInteractive || (await askYesNo(rl, 'Configure agent and CI gate templates?', true));
     if (installGates) {
       const gateArgs = ['--root', root, '--install-agent-gates'];
       if (args.tools) gateArgs.push('--tools', args.tools);
@@ -268,7 +321,8 @@ async function init(args) {
     }
 
     const runStrict =
-      args.strict && (args.yes || (await askYesNo(rl, 'Run strict architecture check now?', true)));
+      args.strict &&
+      (nonInteractive || (await askYesNo(rl, 'Run strict architecture check now?', true)));
     if (runStrict) {
       return runArkCheck(
         ['--root', root, '--config', 'ark.config.json', '--strict-config'],
@@ -298,7 +352,8 @@ async function init(args) {
 // orchestrates existing steps (recommend → init → --plan) and frames each in outcome terms.
 async function start(args) {
   const root = args.root;
-  const interactive = !args.yes && isInteractiveTty();
+  const nonInteractive = shouldUseNonInteractiveDefaults(args);
+  const interactive = !nonInteractive;
   const rl = interactive
     ? readline.createInterface({ input: process.stdin, output: process.stdout })
     : null;
@@ -309,6 +364,11 @@ async function start(args) {
       "I'll look at your code, suggest a shape, set up the guardrails, and show you a plan."
     );
     console.log('Nothing in your code is changed — this only adds Ark configuration.');
+    if (nonInteractive && !args.yes) {
+      console.log(
+        'Non-interactive session (no TTY) — using guided defaults (same as --yes). Pass flags to override.'
+      );
+    }
 
     // 1) Look at the project.
     let rec;
@@ -331,7 +391,8 @@ async function start(args) {
         );
         console.log('match the contract to how your code is already organized, and flag only genuine issues.');
       }
-      const proceed = args.yes || (await askYesNo(rl, '\nSet Ark up for this shape?', true));
+      const proceed =
+        nonInteractive || (await askYesNo(rl, '\nSet Ark up for this shape?', true));
       if (!proceed) {
         archetype = interactive ? await resolveArchetypeInteractive(rl, root) : rec.archetype;
       }
@@ -339,6 +400,26 @@ async function start(args) {
       archetype = await resolveArchetypeInteractive(rl, root);
     }
 
+    // 2b) Pin arkgate as a project devDependency so CI/npx do not depend on a stale global.
+    if (args.install !== false && fs.existsSync(path.join(root, 'package.json'))) {
+      const { pinned, installStatus } = ensureProjectArkgateDependency(root, {
+        install: true,
+        runPackageManager: true,
+      });
+      if (pinned.changed) {
+        console.log(`  Pinned arkgate@${pinned.version} in package.json devDependencies.`);
+        if (installStatus !== null && installStatus !== 0) {
+          console.log(
+            `  Package manager install exited ${installStatus} — package.json is still pinned; run install when online.`
+          );
+        }
+      } else if (pinned.reason === 'already-present') {
+        console.log(`  arkgate already in package.json (${pinned.version}).`);
+      }
+    } else if (args.install === false) {
+      console.log('  Skipping arkgate package pin (--no-install).');
+    }
+
     // 3) Set up config + gates. Greenfield → the shape's preset; an established repo → detection,
     // so the contract anchors to the directories you already have instead of aspirational globs.
     console.log('');
@@ -472,8 +553,28 @@ async function start(args) {
 
     // 5) Plain-language wrap-up — one next step, status light only.
     // Modes are detected (Suggest/Adapt/Enforce), not user-picked settings.
+    // Soft-block false-green using the same doctor adoption gap (no second detector).
+    let falseGreenGap = null;
+    try {
+      const doc = JSON.parse(doctorCapture.stdout || '{}');
+      falseGreenGap = (doc.doctor?.adoption?.gaps ?? []).find(
+        (g) => g?.id === FALSE_GREEN_GAP_ID
+      );
+    } catch {
+      falseGreenGap = null;
+    }
+    if (falseGreenGap && mode === 'enforce') {
+      mode = 'adapt';
+      planOk = false;
+    }
+
     console.log('');
-    if (mode === 'enforce' && planOk) {
+    if (falseGreenGap) {
+      console.log('Done — status: ADAPT (contract may be a false green — do not stop at a clean plan).');
+      console.log('What happens now:');
+      console.log(`  • ${falseGreenGap.message}`);
+      console.log(`  • Next: ${falseGreenGap.fix}`);
+    } else if (mode === 'enforce' && planOk) {
       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).');
@@ -494,11 +595,16 @@ async function start(args) {
     }
     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.');
+    if (falseGreenGap) {
+      console.log('  1. In your agent:  /ark-adopt  (or /ark-contract) — fix the contract first');
+      console.log('     → reclassify I/O dirs out of Application; then /ark-autopilot for residual debt.');
+    } else {
+      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')}`);
-    if (mode === 'adapt' && planOk) {
+    if (mode === 'adapt' && planOk && !falseGreenGap) {
       console.log(
         `  4. When green but cores still optional: ${arkCommand(root, 'ark-check', '--ratchet-cores')} → honest ENFORCE`
       );
@@ -559,4 +665,10 @@ async function main() {
   return 2;
 }
 
-process.exitCode = await main();
+// Only run when executed as the CLI entry (not when imported by unit tests).
+const isMain =
+  Boolean(process.argv[1]) &&
+  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isMain) {
+  process.exitCode = await main();
+}

package/bin/lib/agent-gates.mjs

@@ -23,6 +23,7 @@ import {
   applyFrameworkLayoutOverlays,
 } from '../ark-shared.mjs';
 import { CORE_LAYER_NAMES } from './core-ratchet.mjs';
+import { falseGreenAdoptionGap } from './field-install.mjs';
 import {
   assessCodexHomeMcp,
   codexArkBlockHasPreferredBin,
@@ -365,6 +366,18 @@ export function checkArgsForRoot(root, { requireGates = false } = {}) {
   return `--root . --config ark.config.json --strict-config${baselineFlag}${gatesFlag}`;
 }
 
+// Field-install helpers live in field-install.mjs (keep agent-gates scannable).
+// Re-export for callers that already import from this module.
+export {
+  ensureBaselineFlagInCheckCommand,
+  syncBaselineIntoCheckSurfaces,
+  pinArkgateDevDependency,
+  IO_DIR_SEGMENTS,
+  detectContractFalseGreenRisk,
+  FALSE_GREEN_GAP_ID,
+  falseGreenAdoptionGap,
+} from './field-install.mjs';
+
 export function packageManager(root) {
   // CI always require-gates; baseline follows checkArgsForRoot.
   const checkArgs = checkArgsForRoot(root, { requireGates: true });
@@ -769,10 +782,20 @@ export function resolveTools(args) {
   if (fs.existsSync(path.join(root, '.gemini'))) detected.add('gemini');
   // copilot has no reliable directory signal (.github exists in most repos),
   // so it is explicit-only via --tools.
-  // No signal at all: fall back to writing the primary tools' templates so a fresh
-  // project still gets a complete, reviewable starter set.
+  // Host signals: Grok Build / xAI agents often have no project `.grok/` yet but
+  // set an env marker (or run with GROK_*). Include Grok so skills install there.
+  if (
+    process.env.GROK_BUILD === '1' ||
+    process.env.GROK_BUILD === 'true' ||
+    process.env.XAI_GROK === '1' ||
+    process.env.XAI_GROK === 'true'
+  ) {
+    detected.add('grok');
+  }
+  // No signal at all: fall back to a complete starter set including Grok (field
+  // log: default claude+cursor+codex silently omitted Grok skills for Grok hosts).
   if (detected.size === 0) {
-    return { tools: new Set(['claude', 'cursor', 'codex']), source: 'default' };
+    return { tools: new Set(['claude', 'cursor', 'codex', 'grok']), source: 'default' };
   }
   return { tools: detected, source: 'detected' };
 }
@@ -1539,6 +1562,16 @@ export function collectAdoptionGaps(root, config, coverage) {
     }
   }
 
+  // --- False-green contract (field-install detector; doctor skillGaps already cover missing skills) ---
+  let contractFalseGreen = null;
+  if (!isProducer && config) {
+    const gap = falseGreenAdoptionGap(root, config, coverage);
+    if (gap) {
+      contractFalseGreen = { risk: true, message: gap.message, fix: gap.fix };
+      gaps.push(gap);
+    }
+  }
+
   return {
     gaps,
     hosts,
@@ -1549,6 +1582,7 @@ export function collectAdoptionGaps(root, config, coverage) {
     baseline,
     layerBalance,
     deployPath,
+    contractFalseGreen,
   };
 }
 

package/bin/lib/architecture-scan.mjs

@@ -237,10 +237,16 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
           importGraph.get(relFile).add(relTarget);
         }
       }
-      const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
+      const relTarget = target ? normalize(path.relative(root, target)) : undefined;
+      const rule = targetLayer
+        ? isBlocked(rules, sourceLayer, targetLayer, {
+            fromPath: relFile,
+            toPath: relTarget,
+            layers: config.layers,
+          })
+        : undefined;
       if (rule) {
-        const relTarget = normalize(path.relative(root, target));
-        const targetCached = nextCacheFiles[relTarget];
+        const targetCached = relTarget ? nextCacheFiles[relTarget] : undefined;
         const staticEdge = edge.kind === 'import' || edge.kind === 'export';
         const targetTypeOnlyExports =
           staticEdge && Boolean(targetCached?.exportsOnlyTypes) && !edge.typeOnly;
@@ -257,6 +263,7 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
           targetTypeNames.size > 0 &&
           !targetCached?.hasTopLevelSideEffects &&
           named.every((n) => targetTypeNames.has(n));
+        const peerIsolation = Boolean(rule.peerIsolation);
         violations.push({
           ruleId: 'LAYER_IMPORT_VIOLATION',
           file: relFile,
@@ -269,7 +276,12 @@ export function runArchitectureScan({ root, config, manifest, rules, files, ts,
           ...(sourcePureTypeModule ? { sourcePureTypeModule: true } : {}),
           ...(namedBindingsTypeOnly ? { namedBindingsTypeOnly: true } : {}),
           ...(edge.kind ? { edgeKind: edge.kind } : {}),
-          message: rule.message ?? `${sourceLayer} must not ${edge.kind} ${targetLayer}.`,
+          ...(peerIsolation ? { peerIsolation: true } : {}),
+          message:
+            rule.message ??
+            (peerIsolation
+              ? `${sourceLayer} must not ${edge.kind} another slice of ${targetLayer} (${relFile} → ${relTarget}). Extract shared code or use events/ports across slices.`
+              : `${sourceLayer} must not ${edge.kind} ${targetLayer}.`),
         });
       }
     }

package/bin/lib/config-warnings.mjs

@@ -10,6 +10,7 @@ import {
   patternSpecificity,
   resolveIntentLayer,
 } from '../ark-shared.mjs';
+import { findDeniedEdgeRule } from '../ark-layer-match.mjs';
 import { normalize } from './scan-files.mjs';
 
 export function intentLayersFromManifest(manifest) {
@@ -36,8 +37,16 @@ export function layerForIntent(intent, layers, manifestIntentLayers) {
   return resolveIntentLayer(intent, source);
 }
 
-export function isBlocked(rules, from, to) {
-  return rules.find((rule) => !rule.allowed && rule.from === from && rule.to === to);
+/**
+ * First denying edge rule for from→to, or undefined.
+ * Path-aware when options.fromPath / options.toPath are set (peerIsolation).
+ * @param {object[]} rules
+ * @param {string} from
+ * @param {string} to
+ * @param {{ fromPath?: string, toPath?: string, layers?: object[] }} [options]
+ */
+export function isBlocked(rules, from, to, options) {
+  return findDeniedEdgeRule(rules, from, to, options);
 }
 
 export function configWarning(ruleId, message, extra = {}) {

package/bin/lib/doctor-plan.mjs

@@ -330,6 +330,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
                   archetype: recommendation?.archetype,
                   label: recommendation?.label,
                   preset: recommendation?.preset,
+                  galleryStarter: recommendation?.galleryStarter,
+                  policyPack: recommendation?.policyPack,
                   recommendCommand: arkCommand(root, 'ark-check', '--recommend'),
                   initCommand: recommendation?.archetype
                     ? arkCommand(root, 'ark', `init --archetype ${recommendation.archetype} --yes`)
@@ -409,6 +411,24 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     console.log(color.bold('New here?'));
     if (recommendation) {
       line(warn, `Suggested application shape: ${recommendation.archetype} — ${recommendation.label} (preset ${recommendation.preset})`);
+      if (recommendation.galleryStarter) {
+        line(ok, `Gallery starter: ${recommendation.galleryStarter}`);
+      }
+      if (recommendation.policyPack) {
+        line(ok, `Policy pack: ${arkCommand(root, 'ark-check', `--apply-policy-pack ${recommendation.policyPack}`)}`);
+      }
+      if (recommendation.signals?.nestFramework) {
+        line(
+          ok,
+          'Nest modular monolith → prefer hexagonal (or ddd-bounded-contexts if you have src/contexts/*)'
+        );
+      }
+      if (recommendation.signals?.monorepoTooling?.length) {
+        line(
+          ok,
+          `Monorepo tooling (${recommendation.signals.monorepoTooling.join(', ')}) → preset monorepo (apps/packages/libs)`
+        );
+      }
     } else {
       line(warn, 'Low governed coverage or fresh config — pick an application shape before adding code.');
     }