arkgate 2.9.0 → 2.9.2

package/CHANGELOG.md

@@ -4,6 +4,68 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 2.9.2 — 2026-07-09
+
+Skill surface hardening: dual-engine, explore, STOP handoffs, AGENTS routing, subagent fan-out.
+**No intentional CLI flag or JSON shape breaks.**
+
+### Added
+
+- **`/ark-explore` skill:** exploratory architecture reconnaissance — product map, entry
+  points, coupling hotspots, false-green risk, ranked *suggestions* (not only residual
+  violations). CLI remains a sensor; host agent reads the real tree.
+- **Skill completion contract:** every `/ark-*` template ends with fixed
+  `### Completion` fields (Sensor / Opened / Result / Handoff / Incomplete?) —
+  **skill incomplete if missing**.
+- **Hard STOP handoffs:** critical paths (false-green, concentrated edge, bulk debt,
+  wrong skill) use `STOP — do not continue this skill as complete` + named next skill.
+- **AGENTS skill routing table:** trigger → skill map in generated `AGENTS.md` while
+  keeping `/ark-autopilot` as the default when unsure.
+- **Subagent fan-out protocol:** every `/ark-*` skill documents optional **parallel
+  subagents** when the host supports them (disjoint read-only scopes + parent merge);
+  otherwise **fall back to sequential**. AGENTS.md repeats the rule.
+
+### Changed
+
+- **Skills dual-engine (deterministic + exploratory):** **all** shipped skill templates
+  require dual-engine behavior (CLI sensor + real source/product pass where applicable).
+  Plan empty ≠ architecture healthy without explore. Refresh installed skills with
+  `ark-check --install-agent-gates --skills-only --force`.
+
+## 2.9.1 — 2026-07-09
+
+Field-install honesty: non-TTY start, baseline→CI sync, pin, false-green soft block, Grok defaults.
+**No intentional CLI flag or JSON shape breaks.**
+
+### Fixed
+
+- **Non-TTY `ark start` / `ark init`:** when stdin/stdout are not a TTY and `--yes` was
+  omitted, guided setup no longer throws on a null readline interface. Non-interactive
+  sessions use the same defaults as `--yes` (agents never hang on prompts).
+- **Baseline → CI/scripts sync:** after a successful `--update-baseline`, existing
+  `package.json` scripts and GitHub Actions workflows that already run `ark-check` gain
+  `--baseline .ark-baseline.json` without a full `--force` reinstall of gate templates.
+- **Grok in default agent tools:** no-signal `--install-agent-gates` now installs
+  claude + cursor + codex + **grok**; `GROK_BUILD` / `XAI_GROK` env also adds Grok when
+  other hosts are detected.
+
+### Added
+
+- **`start` pins `arkgate` as a devDependency** (opt out with `--no-install`) so CI/`npx`
+  are not forced to rely on a stale global install.
+- **False-green contract soft block:** doctor adoption gap
+  `contract-false-green-io-under-application` when Domain/Persistence are empty while
+  Application globs still cover I/O dirs (airtable/supabase/prisma/…). `ark start`
+  wrap-up and `/ark-autopilot` steer to `/ark-adopt` / `/ark-contract` instead of pure
+  ENFORCE victory.
+- **`bin/lib/field-install.mjs`:** field-install helpers (baseline sync, pin, false-green)
+  extracted from the agent-gates surface for scannability; re-exported from `agent-gates.mjs`.
+
+### Changed
+
+- **Public ROADMAP:** active backlog is **Track W** (constrained write → verified repair:
+  W1–W6). Finished foundation tracks live under Shipped.
+
 ## 2.9.0 — 2026-07-09
 
 Track P: slice isolation, vertical-slice + DDD presets, skill surface, and adoption depth.

package/README.md

@@ -144,19 +144,25 @@ npx arkgate-check --coverage
 Install once: `npx arkgate-check --install-agent-gates`  
 (`--tools claude,cursor,codex,grok` to pick hosts.)
 
-**Default is always `/ark-autopilot`.** The rest are escapes, not a second curriculum:
+**Default is always `/ark-autopilot`.** The rest are escapes, not a second curriculum.
+Generated `AGENTS.md` includes a **skill routing table** (trigger → skill). Skills are
+**dual-engine** (CLI sensor + read real source) and end with a fixed **completion contract**;
+critical handoffs say **STOP** and name the next skill (hosts must follow — markdown cannot chain calls).
+When the host allows it, skills may **fan out parallel subagents** (disjoint scopes);
+otherwise they **fall back to sequential**.
 
 | Need | Skill |
 |------|--------|
 | Only the apply loop (plan already exists) | `/ark-loop` |
 | Empty greenfield shape/scaffold | `/ark-architect` |
 | Deep brownfield / manifest mining alone | `/ark-adopt` |
+| Exploratory map of the real product (no apply) | `/ark-explore` |
 | New file placement | `/ark-place` |
 | Gate violation on a change | `/ark-fix` |
 | Design trade-offs within the contract (no package LLM) | `/ark-think` |
 | Edit `ark.config.json` safely | `/ark-contract` |
 | Plain-language tour of the report | `/ark-explain` |
-| Deep “what am I not using?” audit | `/ark-coverage` |
+| Deep coverage + opportunities audit | `/ark-coverage` |
 | Migrate hand-rolled bus/outbox (TS) | `/ark-runtime` |
 | Bump ArkGate + refresh all agent hosts | `/ark-upgrade` |
 

package/bin/ark-check.mjs

@@ -44,6 +44,7 @@ import {
   REQUIRED_GATE_FILES,
   codexPromptsDir,
 } from './lib/agent-gates.mjs';
+import { syncBaselineIntoCheckSurfaces } from './lib/field-install.mjs';
 import {
   detectEnforcement,
   renderHtmlReport,
@@ -1087,8 +1088,25 @@ async function main() {
       console.log('Gate with: ark-check --root . --config ark.config.json --strict-config');
       return;
     }
-    const { fullPath, count } = writeBaseline(root, args.baseline, violations);
+    const { fullPath, count } = writeBaseline(root, baselineName, violations);
     console.log(`Wrote ${fullPath} with ${count} frozen violation key(s).`);
+    // Keep existing package.json scripts + CI workflows on the ratchet without a
+    // full --force reinstall (field log: baseline after start left CI without --baseline).
+    const baselineRel = path.isAbsolute(baselineName)
+      ? path.relative(root, baselineName).split(path.sep).join('/')
+      : String(baselineName).replace(/^\.\/+/, '');
+    const sync = syncBaselineIntoCheckSurfaces(root, {
+      baselineRel: baselineRel || '.ark-baseline.json',
+    });
+    if (sync.changed.length > 0) {
+      console.log(
+        `Synced --baseline into: ${sync.changed.map((c) => c.file).join(', ')}`
+      );
+    } else {
+      console.log(
+        'No existing check scripts/workflows needed a --baseline patch (add check:architecture or re-run --install-agent-gates).'
+      );
+    }
     console.log('Commit it and gate CI with: ark-check --baseline (only NEW violations fail).');
     if (summary.total > 0) printViolationBreakdown(summary);
     return;

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');
@@ -70,24 +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,
                vertical-slice-product, ddd-bounded-contexts.
-  --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.
+  --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]];
@@ -166,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)');
@@ -214,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;
 
@@ -231,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;
@@ -244,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);
     }
@@ -259,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);
@@ -269,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'],
@@ -299,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;
@@ -310,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;
@@ -332,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;
       }
@@ -340,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('');
@@ -473,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).');
@@ -495,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`
       );
@@ -560,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 });
@@ -452,13 +465,39 @@ export function agentInstructions(root) {
 
 1. If \`ark.config.json\` is missing: run \`${startCmd}\` once.
 2. For adoption / cleanup / “make architecture sound”: run the **\`/ark-autopilot\`** skill
-   (origin report → adopt → plan → safe fixes → gates). Do **not** invent a parallel workflow
-   from the long skill list.
+   (origin report → adopt → plan → safe fixes → gates). Do **not** invent a second
+   architecture curriculum outside the routing table below — when a trigger matches, use
+   that skill; when unsure, stay on autopilot.
 3. Status anytime: \`${doctorCmd}\` (status light + next action — not a mode picker).
 4. After ordinary feature edits: run \`${checkCmd}\`. On violations → **\`/ark-fix\`** (or
    \`/ark-place\` for new files, \`/ark-contract\` only if the contract itself is wrong).
 
-Other \`/ark-*\` skills are optional escapes (adopt, coverage, runtime, …), not required steps.
+Skills are **dual-engine**: deterministic CLI sensors + exploratory read of *this* repo — not JSON-only wrappers.
+When a skill says **STOP — do not continue this skill as complete**, stop and invoke the named handoff skill.
+
+### Subagent fan-out
+If the host supports **parallel subagents**, skills may ask you to fan out **read-only**
+scouts (disjoint path scopes) and merge in the parent. If the host does **not**,
+**fall back to sequential** — one cluster/step at a time. Never parallel-write the same
+files; never weaken the gate via subagents.
+
+## Skill routing (triggers → skill)
+
+| When | Invoke |
+|------|--------|
+| Unsure / make architecture sound | **/ark-autopilot** (default) |
+| Need map / opportunities only (no apply) | \`/ark-explore\` |
+| Greenfield shape / empty tree | \`/ark-architect\` |
+| Brownfield / wrong contract / false-green | \`/ark-adopt\` then \`/ark-contract\` if globs wrong |
+| Edit \`ark.config.json\` layers/rules/intents | \`/ark-contract\` |
+| New file “where does this go?” | \`/ark-place\` |
+| Gate violation on a change | \`/ark-fix\` |
+| Drive plan to goal.met | \`/ark-loop\` |
+| Deep coverage + ranked audit | \`/ark-coverage\` |
+| Design trade-offs (no package LLM) | \`/ark-think\` |
+| Explain / HTML report tour | \`/ark-explain\` |
+| Bump arkgate + refresh hosts | \`/ark-upgrade\` |
+| Optional runtime kernel migrate | \`/ark-runtime\` |
 
 ## Before editing TypeScript or JavaScript source files
 
@@ -769,10 +808,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 +1588,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 +1608,7 @@ export function collectAdoptionGaps(root, config, coverage) {
     baseline,
     layerBalance,
     deployPath,
+    contractFalseGreen,
   };
 }