arkgate 2.8.1 → 2.8.2

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here.
 
+## Unreleased
+
+## 2.8.2 — 2026-07-09
+
+Field-honesty patch (Next/UI host probe): no Nest false positives, no false ENFORCE on
+ui-surface bags, honest `ark start` mode, Next proxy/middleware classification.
+**No intentional CLI flag or JSON shape breaks.**
+
+### Fixed
+
+- **Nest detection false positive:** bare `*.service.ts` / similar names no longer set
+  `nestFramework` without `@nestjs/*` or controller/module/gateway/resolver files (Next/Node
+  apps no longer get a spurious `nestjs+next` overlay).
+- **False ENFORCE on UI bags:** doctor/report mode stays **ADAPT** when Domain+Persistence are
+  empty while Presentation dominates, or when core layers with files remain `optional: true`.
+- **ui-surface / Next defaults:** drop whole-`src` and bare `**/lib/**` presentation bags;
+  classify conventional data clients (`lib/supabase`, `lib/airtable`, `lib/prisma`, …) as
+  **Persistence**; add Application patterns for actions/services.
+- **Generated CI:** when `package.json` has `lint` / `typecheck` scripts, the installed
+  GitHub Actions workflow runs them before ark-check (closes deploy-path gaps for Next hosts).
+- **`ark start` wrap-up mode:** prefers `ark-check --doctor` `operatingMode` over plan-only
+  `resolveOperatingMode` (default **adapt**, double-lock against false **ENFORCE**).
+- **Next middleware / proxy:** ui-surface + Next overlay classify `src/proxy.ts`, root
+  `proxy.ts`, and classic `middleware.ts` as **Presentation** (Next 16 rename no longer
+  leaves the edge entry ungoverned).
+- **Idempotent Next overlay:** re-applying framework overlays no longer yields
+  `frameworkOverlay: "next+next"`.
+
 ## 2.8.1 — 2026-07-09
 
 Runtime honesty release (roadmap **R8–R9**): EventBus publish pipeline decomposition and

package/bin/ark-shared.mjs

@@ -217,6 +217,15 @@ export function applyFrameworkLayoutOverlays(config, root) {
       'src/**/error.tsx',
       'src/**/route.ts',
       'src/**/route.tsx',
+      // Next middleware edge entry (classic + Next 16 proxy rename)
+      'src/middleware.ts',
+      'src/middleware.js',
+      'middleware.ts',
+      'middleware.js',
+      'src/proxy.ts',
+      'src/proxy.js',
+      'proxy.ts',
+      'proxy.js',
     ]);
     mergeLayerPatterns(next, 'ApplicationOrchestration', [
       'src/features/**',
@@ -247,6 +256,21 @@ export function applyFrameworkLayoutOverlays(config, root) {
       'src/lib/db/**',
       'src/lib/prisma/**',
       'src/server/db/**',
+      // Conventional client data bags under lib/ (higher specificity than bare src/lib/**).
+      'src/lib/supabase/**',
+      'src/lib/airtable/**',
+      'src/lib/firebase/**',
+      'src/lib/firestore/**',
+      'src/lib/mongodb/**',
+      'src/lib/mongoose/**',
+      'src/lib/drizzle/**',
+      'src/lib/kysely/**',
+      'src/lib/planetscale/**',
+      'src/lib/neon/**',
+      '**/lib/supabase/**',
+      '**/lib/airtable/**',
+      '**/lib/prisma/**',
+      '**/lib/db/**',
     ]);
     // Demo assets, generated public output, and tool configs are not architecture surface.
     const nextExcludes = [
@@ -262,9 +286,12 @@ export function applyFrameworkLayoutOverlays(config, root) {
       '**/scripts/**',
     ];
     next.exclude = [...new Set([...(next.exclude ?? []), ...nextExcludes])];
-    next.frameworkOverlay = next.frameworkOverlay
-      ? `${next.frameworkOverlay}+next`
-      : 'next';
+    // Idempotent: re-applying overlays (e.g. re-init / re-start) must not yield "next+next".
+    if (!String(next.frameworkOverlay || '').split('+').includes('next')) {
+      next.frameworkOverlay = next.frameworkOverlay
+        ? `${next.frameworkOverlay}+next`
+        : 'next';
+    }
   }
 
   if (signals.expressLike && !signals.nestFramework) {
@@ -323,15 +350,47 @@ export function applyFrameworkLayoutOverlays(config, root) {
 /**
  * Operating mode for the co-pilot surfaces (not "who the user is"):
  *   suggest | adapt | enforce
+ *
+ * ENFORCE means gates can honestly protect the tree. High governed% alone is not
+ * enough when core layers are empty (presentation bag false-green) or core layers
+ * with real files remain optional: true.
+ *
+ * @param {object} opts
+ * @param {number|null} [opts.governedPercent]
+ * @param {boolean|null} [opts.planMet]
+ * @param {boolean} [opts.mature]
+ * @param {number|null} [opts.totalFiles]
+ * @param {string[]} [opts.emptyLayers] layer names with zero matched files
+ * @param {number} [opts.coreOptionalWithFiles] count of core layers that have files but optional:true
+ * @param {number|null} [opts.presentationShare] PresentationAdapters file share 0..1 when known
  */
 export function resolveOperatingMode({
   governedPercent = null,
   planMet = null,
   mature = false,
   totalFiles = null,
+  emptyLayers = null,
+  coreOptionalWithFiles = 0,
+  presentationShare = null,
 } = {}) {
   // Zero files in scope is never ENFORCE — the contract is not looking at any code.
   if (totalFiles === 0) return 'adapt';
+  // Core layers still optional while holding real files → contract weaker than the tree.
+  if (coreOptionalWithFiles > 0) return 'adapt';
+  // Presentation-bag false green: almost everything is Presentation, Domain+Persistence empty.
+  const empty = Array.isArray(emptyLayers) ? emptyLayers : [];
+  const domainEmpty = empty.includes('DomainModel');
+  const persistenceEmpty = empty.includes('PersistenceAdapters');
+  if (
+    planMet === true &&
+    domainEmpty &&
+    persistenceEmpty &&
+    presentationShare != null &&
+    presentationShare >= 0.5 &&
+    (governedPercent ?? 0) >= 50
+  ) {
+    return 'adapt';
+  }
   if (planMet === true && (governedPercent == null || governedPercent >= 50)) return 'enforce';
   if (governedPercent != null && governedPercent < 50) return 'adapt';
   if (mature) return 'adapt';
@@ -1027,10 +1086,13 @@ export function collectRepoShapeSignals(root) {
 
   const topNames = new Set(srcDirs.flatMap((d) => listTopLevelDirNames(root, d)));
   // Framework / filename signals — strong enough that a tiny Nest starter is not a "prototype".
+  // Nest detection: require real Nest surface (@nestjs/* or controller/module/gateway/resolver).
+  // Do NOT treat bare `*.service.ts` / `*.guard.ts` as Nest — many Next/Node apps use those
+  // names without Nest (false nestjs overlay + wrong doctor toolHints).
   const nestFramework =
     Object.keys(deps).some((name) => name.startsWith('@nestjs/')) ||
     sourceFiles.some((file) =>
-      /\.(controller|module|service|guard|interceptor|pipe)\.ts$/i.test(file)
+      /\.(controller|module|gateway|resolver)\.ts$/i.test(file)
     );
   const nextFramework =
     Boolean(deps.next) ||

package/bin/ark.mjs

@@ -393,27 +393,64 @@ async function start(args) {
     console.log('Your architecture plan:');
     runArkCheck(['--root', root, '--config', 'ark.config.json', '--plan'], { cwd: root });
 
-    // Capture plan JSON for an honest wrap-up (governed% + goal.met) without re-printing.
+    // Capture plan + doctor JSON for an honest wrap-up. Mode MUST match --doctor
+    // (emptyLayers, core-optional, presentation bag) — never claim ENFORCE from plan alone.
     const planCapture = spawnSync(
       process.execPath,
       [arkCheck, '--root', root, '--config', 'ark.config.json', '--plan', '--json'],
       { cwd: root, encoding: 'utf8' }
     );
+    const doctorCapture = spawnSync(
+      process.execPath,
+      [arkCheck, '--root', root, '--config', 'ark.config.json', '--doctor', '--json'],
+      { cwd: root, encoding: 'utf8' }
+    );
     let planOk = true;
     let governedPercent = null;
-    let mode = 'enforce'; // suggest | adapt | enforce
+    let mode = 'adapt'; // conservative default — never default to enforce
     try {
       const parsed = JSON.parse(planCapture.stdout || '{}');
       planOk = parsed.ok === true && parsed.plan?.goal?.met === true;
       governedPercent = parsed.plan?.goal?.governedPercent ?? null;
       const totalFiles = parsed.plan?.goal?.totalFiles ?? null;
-      mode = resolveOperatingMode({
-        governedPercent:
-          totalFiles === 0 ? 0 : governedPercent,
-        planMet: parsed.plan?.goal?.met === true,
-        mature: Boolean(rec?.mature),
-        totalFiles,
-      });
+
+      let doctorMode = null;
+      try {
+        const doc = JSON.parse(doctorCapture.stdout || '{}');
+        doctorMode = doc.doctor?.operatingMode ?? null;
+        // Prefer doctor's mode (includes emptyLayers + coreOptional + presentation-bag honesty).
+        if (doctorMode === 'suggest' || doctorMode === 'adapt' || doctorMode === 'enforce') {
+          mode = doctorMode;
+        } else {
+          // Fallback: recompute with honesty inputs from doctor payload when present.
+          const emptyLayers = doc.doctor?.emptyLayers ?? [];
+          const coreOptionalWithFiles = Array.isArray(doc.doctor?.adoption?.coreOptional)
+            ? doc.doctor.adoption.coreOptional.length
+            : 0;
+          const total = totalFiles || doc.doctor?.governed?.totalFiles || 0;
+          const presentationShare =
+            total > 0 && typeof doc.doctor?.governed?.percent === 'number'
+              ? null // presentationShare only from coverage layers when available
+              : null;
+          mode = resolveOperatingMode({
+            governedPercent: totalFiles === 0 ? 0 : governedPercent,
+            planMet: parsed.plan?.goal?.met === true,
+            mature: Boolean(rec?.mature),
+            totalFiles: totalFiles ?? total,
+            emptyLayers,
+            coreOptionalWithFiles,
+            presentationShare,
+          });
+        }
+      } catch {
+        mode = resolveOperatingMode({
+          governedPercent: totalFiles === 0 ? 0 : governedPercent,
+          planMet: parsed.plan?.goal?.met === true,
+          mature: Boolean(rec?.mature),
+          totalFiles,
+        });
+      }
+
       // Fresh greenfield with good coverage but no real tree yet → suggest, not enforce theatre.
       if (mode === 'enforce' && rec && !rec.mature && (governedPercent ?? 0) < 80) {
         mode = 'suggest';
@@ -423,6 +460,10 @@ async function start(args) {
         mode = 'adapt';
         planOk = false;
       }
+      // Never claim ENFORCE wrap-up if doctor would not (double-lock).
+      if (mode === 'enforce' && doctorMode && doctorMode !== 'enforce') {
+        mode = doctorMode;
+      }
     } catch {
       // If capture fails, stay conservative: don't claim full enforcement.
       mode = 'adapt';

package/bin/lib/agent-gates.mjs

@@ -483,7 +483,12 @@ export function detectCiNode(root) {
   return { kind: 'default', value: DEFAULT_CI_NODE_VERSION };
 }
 
-export function githubWorkflow(pm, ciNode) {
+/**
+ * @param {{ name: string, install: string, run: string, cache: string, setup: string[] }} pm
+ * @param {{ kind: string, value: string }} ciNode
+ * @param {{ hasLintScript?: boolean, hasTypecheckScript?: boolean }} [quality]
+ */
+export function githubWorkflow(pm, ciNode, quality = {}) {
   // pnpm/yarn setup (corepack enable) MUST run before actions/setup-node so the package
   // manager is on PATH when setup-node's `cache: pnpm|yarn` tries to resolve the store —
   // otherwise the cache step fails on a fresh runner ("Unable to locate executable file: pnpm").
@@ -500,6 +505,24 @@ export function githubWorkflow(pm, ciNode) {
           # of sync, your local package manager is newer than this Node's — add a
           # .nvmrc with your Node version so CI matches the dev environment.
           node-version: '${ciNode.value}'`;
+  // When package.json already has lint/typecheck, emit CI steps so deploy-path
+  // honesty matches local scripts (Next/CRA often run these in production build).
+  const install = pm.install || '';
+  const runPrefix = install.startsWith('pnpm')
+    ? 'pnpm run'
+    : install.startsWith('yarn')
+      ? 'yarn'
+      : install.startsWith('bun')
+        ? 'bun run'
+        : 'npm run';
+  const qualityBlock = [
+    quality.hasTypecheckScript
+      ? `      - name: Typecheck\n        run: ${runPrefix} typecheck`
+      : '',
+    quality.hasLintScript ? `      - name: Lint\n        run: ${runPrefix} lint` : '',
+  ]
+    .filter(Boolean)
+    .join('\n');
   return `name: Ark architecture gate
 
 on:
@@ -520,7 +543,7 @@ ${nodeSetup}
           cache: ${pm.cache}
       - name: Install dependencies
         run: ${pm.install}
-      - name: Ark architecture check
+${qualityBlock ? `${qualityBlock}\n` : ''}      - name: Ark architecture check
         run: ${pm.run}
 `;
 }
@@ -1608,7 +1631,13 @@ export function runInstallAgentGates(args) {
     templates.push(['.mcp.json', mcpJson(root)]);
     templates.push([
       '.github/workflows/ark-check.yml',
-      githubWorkflow(pm, detectCiNode(root)),
+      (() => {
+        const deploy = detectDeployPathQuality(root);
+        return githubWorkflow(pm, detectCiNode(root), {
+          hasLintScript: deploy.hasLintScript,
+          hasTypecheckScript: deploy.hasTypecheckScript,
+        });
+      })(),
     ]);
     if (tools.has('cursor')) {
       templates.push(['.cursor/mcp.json', mcpJson(root)]);

package/bin/lib/doctor-plan.mjs

@@ -290,6 +290,15 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               governedPercent: cov.governed.percent,
               planMet: activeCount === 0 && cov.governed.percent >= 50,
               mature: cov.governed.totalFiles >= 150,
+              totalFiles: cov.governed.totalFiles,
+              emptyLayers: cov.emptyLayers,
+              coreOptionalWithFiles: adoption.coreOptional?.length ?? 0,
+              presentationShare: (() => {
+                const total = cov.governed.totalFiles || 0;
+                if (total <= 0) return null;
+                const p = cov.layers.find((r) => r.name === 'PresentationAdapters');
+                return p ? p.files / total : null;
+              })(),
             }),
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
@@ -345,11 +354,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   console.log(color.bold(`Ark doctor — ${path.basename(path.resolve(root)) || '.'}`));
 
   const emptyScope = cov.governed.totalFiles === 0;
+  const totalFiles = cov.governed.totalFiles || 0;
+  const presentationRow = cov.layers.find((r) => r.name === 'PresentationAdapters');
   const mode = resolveOperatingMode({
     governedPercent: emptyScope ? 0 : cov.governed.percent,
     planMet:
       activeCount === 0 && !emptyScope && cov.governed.percent >= 50,
     mature: cov.governed.totalFiles >= 150,
+    totalFiles: cov.governed.totalFiles,
+    emptyLayers: cov.emptyLayers,
+    coreOptionalWithFiles: adoption.coreOptional?.length ?? 0,
+    presentationShare:
+      totalFiles > 0 && presentationRow ? presentationRow.files / totalFiles : null,
   });
   console.log('');
   console.log(color.bold('Operating mode'));

package/bin/lib/html-report.mjs

@@ -153,6 +153,17 @@ export function computeReportFitness({ coverage, violations, ok, enforcement, co
   const governedPercent = coverage?.governed?.percent ?? null;
   const totalFiles = coverage?.governed?.totalFiles ?? 0;
   const classifiedFiles = coverage?.governed?.classifiedFiles ?? 0;
+  const emptyLayers = (coverage?.layers ?? [])
+    .filter((r) => (r.files ?? 0) === 0)
+    .map((r) => r.name);
+  const presentationRow = (coverage?.layers ?? []).find(
+    (r) => r.name === 'PresentationAdapters'
+  );
+  const coreOptionalWithFiles = (config?.layers ?? []).filter((layer) => {
+    if (layer.optional !== true) return false;
+    const row = (coverage?.layers ?? []).find((r) => r.name === layer.name);
+    return (row?.files ?? 0) > 0;
+  }).length;
   const mode = resolveOperatingMode({
     governedPercent: totalFiles === 0 ? 0 : governedPercent,
     planMet:
@@ -162,6 +173,10 @@ export function computeReportFitness({ coverage, violations, ok, enforcement, co
       (governedPercent == null || governedPercent >= 50),
     mature: totalFiles >= 150,
     totalFiles,
+    emptyLayers,
+    coreOptionalWithFiles,
+    presentationShare:
+      totalFiles > 0 && presentationRow ? presentationRow.files / totalFiles : null,
   });
   const modeLabel = { suggest: 'SUGGEST', adapt: 'ADAPT', enforce: 'ENFORCE' }[mode] || String(mode).toUpperCase();
   const modeBlurb = {

package/bin/lib/presets.mjs

@@ -267,22 +267,29 @@ export const ARCHITECTURE_PRESETS = {
             name: 'DomainModel',
             description: 'Shared types and pure view-models (optional on UI-first trees).',
             // Avoid bare **/types.ts — see monorepo DomainModel note (false Domain on core/**/types.ts).
-            patterns: ['**/domain/**', '**/cinematic/types.ts'],
+            patterns: [
+              '**/domain/**',
+              '**/cinematic/types.ts',
+              // Common pure types bag (not **/types.ts — that traps core/**/types.ts).
+              'src/lib/types.ts',
+            ],
             exclude: FRAMEWORK_INTERNAL_EXCLUDE,
             forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
             optional: true,
           },
           {
-            name: 'PresentationAdapters',
-            description: 'UI, routes, hooks, components, compositions.',
+            name: 'ApplicationOrchestration',
+            description: 'Server actions, features, and non-UI lib orchestration (when present).',
             patterns: [
-              '**/src/**',
-              '**/components/**',
-              '**/hooks/**',
-              '**/lib/**',
-              '**/routes/**',
-              '**/app/**',
-              '**/pages/**',
+              'src/features/**',
+              'src/server/**',
+              'src/services/**',
+              'src/use-cases/**',
+              'src/actions/**',
+              'src/lib/actions/**',
+              'src/lib/services/**',
+              '**/lib/actions/**',
+              '**/lib/services/**',
             ],
             exclude: FRAMEWORK_INTERNAL_EXCLUDE,
             optional: true,
@@ -290,7 +297,61 @@ export const ARCHITECTURE_PRESETS = {
           {
             name: 'PersistenceAdapters',
             description: 'Client data access and external API adapters (when present).',
-            patterns: ['**/infrastructure/**', '**/adapters/**', '**/repositories/**'],
+            // Prefer specific data-client bags over a presentation catch-all on **/lib/**
+            patterns: [
+              '**/infrastructure/**',
+              '**/adapters/**',
+              '**/repositories/**',
+              '**/persistence/**',
+              'src/db/**',
+              'src/data/**',
+              'src/lib/db/**',
+              'src/lib/prisma/**',
+              'src/lib/supabase/**',
+              'src/lib/airtable/**',
+              'src/lib/firebase/**',
+              'src/lib/firestore/**',
+              'src/lib/mongodb/**',
+              'src/lib/mongoose/**',
+              'src/lib/drizzle/**',
+              'src/lib/kysely/**',
+              '**/lib/supabase/**',
+              '**/lib/airtable/**',
+              '**/lib/prisma/**',
+              '**/lib/db/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'PresentationAdapters',
+            description: 'UI, routes, hooks, components (not a whole-src bag).',
+            // No **/src/** or bare **/lib/** — those swallowed data clients and forced false ENFORCE.
+            patterns: [
+              '**/components/**',
+              '**/hooks/**',
+              '**/routes/**',
+              '**/app/**',
+              '**/pages/**',
+              'src/app/**',
+              'src/pages/**',
+              'src/components/**',
+              'src/hooks/**',
+              'src/ui/**',
+              'src/layouts/**',
+              'app/**',
+              'pages/**',
+              'components/**',
+              // Next middleware edge entry (classic + Next 16 proxy rename)
+              'src/middleware.ts',
+              'src/middleware.js',
+              'middleware.ts',
+              'middleware.js',
+              'src/proxy.ts',
+              'src/proxy.js',
+              'proxy.ts',
+              'proxy.js',
+            ],
             exclude: FRAMEWORK_INTERNAL_EXCLUDE,
             optional: true,
           },
@@ -298,7 +359,20 @@ export const ARCHITECTURE_PRESETS = {
         rules: [
           { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
           { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
+          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
+          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
+          // Next RSC often imports data clients from routes; deny is ideal but day-one
+          // ui-surface keeps this as a soft guidance edge (allowed) until ports exist —
+          // Persistence → Presentation stays denied when that edge appears.
+          {
+            from: 'PresentationAdapters',
+            to: 'PersistenceAdapters',
+            allowed: true,
+            message:
+              'UI/routes may reach data clients on day one (RSC); prefer application ports as the product grows.',
+          },
+          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
         ],
       },
       root

package/dist/index.cjs

@@ -80,7 +80,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var version = "2.8.1";
+var version = "2.8.2";
 
 // src/kernel/intent/IntentRegistry.ts
 var IntentRegistry = class {