arkgate 4.8.14 → 4.8.16

package/bin/ark-shared.mjs

@@ -22,6 +22,7 @@ import {
   normalizeArkgateInstallSpec,
   packageInstallArgv,
   installDevHint,
+  arkPackageRecoveryCommand,
 } from './lib/package-manager.mjs';
 
 /**
@@ -104,10 +105,85 @@ function mergeLayerPatterns(config, layerName, patterns, extras = {}) {
   }
 }
 
+/** Next-flavored start captions — applied only when Next is actually detected. */
+export const NEXT_LAYER_DESCRIPTIONS = Object.freeze({
+  ApplicationOrchestration:
+    'Use cases and services that coordinate the domain through ports. Next App Router API (`app/api/**`) and Pages API (`pages/api/**`) are orchestration shells, not UI.',
+  PresentationAdapters:
+    'Entrypoints — UI, framework app/pages dirs, controllers. Next `app/api` is Application, not this layer. Never bare lib/** (data clients are Persistence).',
+});
+
+/** Library / package-monorepo captions — no framework storefront. */
+export const LIBRARY_LAYER_DESCRIPTIONS = Object.freeze({
+  ApplicationOrchestration:
+    'Use cases and the package public surface that coordinate the domain. No I/O of its own.',
+  PresentationAdapters:
+    'Optional CLIs, docs, or demo UIs — not the published library core.',
+});
+
+function setLayerDescription(config, layerName, description) {
+  const layer = config.layers?.find((entry) => entry.name === layerName);
+  if (!layer || typeof description !== 'string' || description.length === 0) return;
+  layer.description = description;
+}
+
+/** packages/* (or similar) of published libraries — no app/cli units, no web framework. */
+export function isLibraryPackageMonorepo(signals) {
+  if (!signals || signals.nextFramework || signals.nestFramework || signals.expressLike) {
+    return false;
+  }
+  const units = Array.isArray(signals.repoUnits) ? signals.repoUnits : [];
+  const productive = units.filter(
+    (unit) => unit.root !== '.' && !['docs', 'example', 'test'].includes(unit.role)
+  );
+  if (productive.length === 0) return false;
+  return (
+    productive.some((unit) => unit.role === 'library') &&
+    !productive.some((unit) => unit.role === 'application' || unit.role === 'cli')
+  );
+}
+
+function applyFrameworkLayerCaptions(config, signals) {
+  const nextish = Boolean(
+    signals.nextFramework || (signals.ui && signals.toolHints?.includes('next'))
+  );
+  if (nextish) {
+    setLayerDescription(
+      config,
+      'ApplicationOrchestration',
+      NEXT_LAYER_DESCRIPTIONS.ApplicationOrchestration
+    );
+    setLayerDescription(
+      config,
+      'PresentationAdapters',
+      NEXT_LAYER_DESCRIPTIONS.PresentationAdapters
+    );
+    return;
+  }
+  if (
+    (signals.libraryOnly && !signals.nestFramework && !signals.expressLike) ||
+    isLibraryPackageMonorepo(signals)
+  ) {
+    setLayerDescription(
+      config,
+      'ApplicationOrchestration',
+      LIBRARY_LAYER_DESCRIPTIONS.ApplicationOrchestration
+    );
+    setLayerDescription(
+      config,
+      'PresentationAdapters',
+      LIBRARY_LAYER_DESCRIPTIONS.PresentationAdapters
+    );
+  }
+}
+
 /**
  * Framework-aware layout overlays. Detection uses collectRepoShapeSignals (deps + filenames).
- * Pure additive: never removes existing preset patterns. Goal: Nest/Next/express starters
- * reach meaningful governed% under hexagonal/layered without a hand-written adopt pass.
+ * Pure additive for patterns: never removes existing preset globs. Goal: Nest/Next/express
+ * starters reach meaningful governed% under hexagonal/layered without a hand-written adopt pass.
+ * Layer captions are the one replace: Next-flavored copy only when Next is present;
+ * library-native copy on library-only / library-package monorepos. Generic preset
+ * captions stay when neither applies.
  */
 export function applyFrameworkLayoutOverlays(config, root) {
   if (!config || !root) return config;
@@ -427,6 +503,7 @@ export function applyFrameworkLayoutOverlays(config, root) {
       : 'library';
   }
 
+  applyFrameworkLayerCaptions(next, signals);
   return withArkConfigMetadata(next);
 }
 
@@ -598,6 +675,7 @@ export {
   normalizeArkgateInstallSpec,
   packageInstallArgv,
   installDevHint,
+  arkPackageRecoveryCommand,
 };
 
 // FX01–FX02: registry-aware skip lives in upgrade-package-decision (injectable probe).
@@ -1082,7 +1160,9 @@ export function collectRepoShapeSignals(root) {
     return !excludedUnitRoots.some((prefix) => rel.startsWith(prefix));
   });
   const discoveredFileSet = new Set(sourceFiles.map((file) => path.resolve(file)));
-  const projectedGovernedCoverage = productionFiles.length === 0
+  // Files under detected source roots — NOT layer-governed coverage. User-facing
+  // "projected governed coverage" is computeCoverage (see projected-governed-coverage.mjs).
+  const discoveredSourceCoverage = productionFiles.length === 0
     ? 0
     : Math.round((productionFiles.filter((file) => discoveredFileSet.has(path.resolve(file))).length / productionFiles.length) * 100);
   const tinyTree = sourceFileCount < 3;
@@ -1261,7 +1341,7 @@ export function collectRepoShapeSignals(root) {
     libraryOnly,
     tinyTree,
     sourceFileCount,
-    projectedGovernedCoverage,
+    discoveredSourceCoverage,
     domain,
     application,
     domainHeavy,
@@ -1529,7 +1609,6 @@ export function scoreArchetypes(signals, playbook) {
       confidence,
       requiresConfirmation: true,
       confirmationReasons: [
-        `projected governed coverage is ${signals.projectedGovernedCoverage ?? 0}% (below 90%)`,
         'no archetype received a positive score',
       ],
       phases: fallback.phases,
@@ -1554,9 +1633,7 @@ export function scoreArchetypes(signals, playbook) {
     confidence = Math.min(confidence, 0.28);
   }
   const closeRecommendations = Boolean(second && top.score - second.score <= 2);
-  const lowProjectedCoverage = (signals.projectedGovernedCoverage ?? 0) < 90;
   if (closeRecommendations) confidence = Math.min(confidence, 0.49);
-  if (lowProjectedCoverage) confidence = Math.min(confidence, 0.49);
 
   return {
     ranked: scored,
@@ -1571,10 +1648,9 @@ export function scoreArchetypes(signals, playbook) {
             '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.',
         }
       : {}),
-    requiresConfirmation: closeRecommendations || thinTs || lowProjectedCoverage,
+    requiresConfirmation: closeRecommendations || thinTs,
     confirmationReasons: [
       ...(closeRecommendations ? ['top recommendations are within 2 score points'] : []),
-      ...(lowProjectedCoverage ? [`projected governed coverage is ${signals.projectedGovernedCoverage}% (below 90%)`] : []),
       ...(thinTs ? ['the discovered source surface is thin'] : []),
     ],
     phases: top.phases,
@@ -1631,7 +1707,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
     policyPack: policyPackId,
     signals: {
       sourceFileCount: signals.sourceFileCount,
-      projectedGovernedCoverage: signals.projectedGovernedCoverage,
+      discoveredSourceCoverage: signals.discoveredSourceCoverage,
       discoveredRoots: signals.discoveredRoots,
       packageUnits: signals.repoUnits.map((unit) => ({
         root: unit.root,
@@ -1664,7 +1740,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
     // a thin slice and can mis-flag framework internals, so steer these to the adoption flow.
     mature: signals.sourceFileCount >= MATURE_REPO_FILE_THRESHOLD,
     initCommand: `${arkCommand(root, 'ark', `init --archetype ${result.archetype} --yes`)}`,
-    firstCommand: `${arkCommand(root, 'ark', `init --archetype ${result.archetype} --yes`)}`,
+    firstCommand: `${arkCommand(root, 'ark', `start --apply --archetype ${result.archetype}`)}`,
     adoptCommand: arkCommand(root, 'ark-check', '--recommend --write-plan'),
     recommendCommand: arkCommand(root, 'ark-check', '--recommend'),
     checkCommand: arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config'),
@@ -1705,6 +1781,49 @@ export function resolveArchetypePreset(archetypeId, playbookPath = defaultPlaybo
   };
 }
 
+/**
+ * Preset `ark start --internal-apply` / `--init` would write. Shared so recommend
+ * can project the same governed % start and doctor measure after that write.
+ */
+export function resolveStartInitPreset(root, rec = {}, archetype = rec.archetype) {
+  const presetFromArchetype =
+    archetype && isValidArchetypeId(archetype)
+      ? resolveArchetypePreset(archetype).preset
+      : undefined;
+  const preset = rec.preset || presetFromArchetype;
+  const includeRoots = resolveIncludeRoots(root);
+  const tsPackages = detectTsPackageRoots(root);
+  const nestedTsPackages = tsPackages.filter((entry) => entry !== '.');
+  const workspaces = detectWorkspaces(root);
+  const looksLikeMonorepo =
+    includeRoots.length > 0 ||
+    nestedTsPackages.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'));
+  if (rec.preset === 'vite-vercel-spa' || preset === 'vite-vercel-spa') {
+    return 'vite-vercel-spa';
+  }
+  if (looksLikeMonorepo && (rec.mature || includeRoots.length > 0 || tsPackages.length > 0)) {
+    const useUi =
+      rec.preset === 'feature-sliced' ||
+      rec.archetype === 'frontend-surface' ||
+      (nestedTsPackages.length > 0 && includeRoots.length === 0 && !rec.mature);
+    return useUi && nestedTsPackages.length <= 3 ? 'ui-surface' : 'monorepo';
+  }
+  return preset ?? null;
+}
+
+/** One-minute / preview footer when the coverage·confidence gate may refuse apply. */
+export const START_APPLY_REFUSE_FOOTER = [
+  'If apply refuses (coverage below 50% or weak shape), that lock is deliberate.',
+  'Lock the shape: --archetype <id>  ·  --preset <name>  ·  --force',
+  'Inspect ranked shapes: arkgate-check --recommend',
+].join('\n');
+
 export function mapWizardChoiceToArchetype(choiceKey) {
   const entry = INIT_WIZARD_CHOICES.find((c) => c.key === String(choiceKey).trim());
   if (!entry) return null;
@@ -1753,6 +1872,18 @@ export function formatArchitectureRecommendationHuman(recommendation) {
   lines.push('');
   lines.push(`Archetype: ${recommendation.archetype} — ${recommendation.label}`);
   lines.push(`Preset: ${recommendation.preset} (confidence ${recommendation.confidence})`);
+  const projected =
+    recommendation.projectedCoverage?.percent ??
+    recommendation.signals?.projectedGovernedCoverage;
+  if (typeof projected === 'number') {
+    const classified = recommendation.projectedCoverage?.classifiedFiles;
+    const total = recommendation.projectedCoverage?.totalFiles;
+    const counts =
+      typeof classified === 'number' && typeof total === 'number'
+        ? ` (${classified}/${total} files)`
+        : '';
+    lines.push(`Projected governed coverage: ${projected}%${counts}`);
+  }
   if (recommendation.requiresConfirmation) {
     lines.push('⚠ Confirmation required before applying this recommendation.');
     for (const reason of recommendation.confirmationReasons ?? []) lines.push(`  - ${reason}`);

package/bin/ark.mjs

@@ -8,10 +8,10 @@ import {
   arkCommand,
   buildArchitectureRecommendation,
   detectPackageManager,
-  detectWorkspaces,
   evaluateStartShapeConfidenceGate,
   resolveIncludeRoots,
   detectTsPackageRoots,
+  resolveStartInitPreset,
   INIT_WIZARD_CHOICES,
   isValidArchetypeId,
   mapWizardChoiceToArchetype,
@@ -22,7 +22,12 @@ import {
 } from './ark-shared.mjs';
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
-import { applyStartPreview, planStart, renderStartPreview } from './lib/start-preview.mjs';
+import {
+  applyStartPreview,
+  formatStartPackageInstallFailure,
+  planStart,
+  renderStartPreview,
+} from './lib/start-preview.mjs';
 import { runUpgradeCommand } from './lib/upgrade-command.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
@@ -489,7 +494,8 @@ async function start(args) {
       const skip = shouldSkipArkgateInstall(args.root, cliVersion());
       if (!skip.skip) {
         const [command, commandArgs] = packageInstallArgv(args.root, `^${cliVersion()}`);
-        if (!args.json) console.log(`Installing package: ${command} ${commandArgs.join(' ')}`);
+        const installCommand = `${command} ${commandArgs.join(' ')}`;
+        if (!args.json) console.log(`Installing package: ${installCommand}`);
         // Keep stdout clean for --json consumers (package managers are chatty on stdout).
         const status = args.json
           ? (spawnSync(command, commandArgs, {
@@ -498,10 +504,9 @@ async function start(args) {
               encoding: 'utf8',
             }).status ?? 1)
           : runCommand(command, commandArgs, args.root);
-        if (status !== 0 && !args.json) {
-          console.log(
-            `Package manager exited ${status}. package.json is pinned; run the install command when online.`
-          );
+        if (status !== 0) {
+          console.error(formatStartPackageInstallFailure({ exitStatus: status, installCommand }));
+          return status;
         }
       }
     }
@@ -568,8 +573,12 @@ async function start(args) {
       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.`
+          const [command, commandArgs] = packageInstallArgv(root, pinned.version);
+          console.error(
+            formatStartPackageInstallFailure({
+              exitStatus: installStatus,
+              installCommand: `${command} ${commandArgs.join(' ')}`,
+            })
           );
         }
       } else if (pinned.reason === 'already-present') {
@@ -586,41 +595,23 @@ async function start(args) {
     const configPath = path.join(root, 'ark.config.json');
     if (!fs.existsSync(configPath)) {
       const initArgs = ['--root', root, '--init'];
-      const preset = archetype ? resolveArchetypePreset(archetype).preset : undefined;
+      const startPreset = resolveStartInitPreset(root, rec ?? {}, archetype);
       const includeRoots = resolveIncludeRoots(root);
       const tsPackages = detectTsPackageRoots(root);
       const nestedTsPackages = tsPackages.filter((entry) => entry !== '.');
-      const workspaces = detectWorkspaces(root);
-      const looksLikeMonorepo =
-        includeRoots.length > 0 ||
-        nestedTsPackages.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'));
-      // SPA (Vite + root api/lib) wins over monorepo heuristics (NEW-SPA-DEFAULT-LAYOUT).
-      if (rec?.preset === 'vite-vercel-spa' || preset === 'vite-vercel-spa') {
+      if (startPreset === 'vite-vercel-spa') {
         initArgs.push('--preset', 'vite-vercel-spa');
         console.log('  Vite/Vercel SPA layout detected — include src,api,lib; api→Application; db clients→Persistence.');
-      } else if (looksLikeMonorepo && (rec?.mature || includeRoots.length > 0 || tsPackages.length > 0)) {
-        // Mature multi-package / nested-TS trees must NOT get a thin src/** starter (0 files).
-        // UI-heavy TS packages (Remotion/Vite) prefer ui-surface patterns when recommend says so.
-        const useUi =
-          rec?.preset === 'feature-sliced' ||
-          rec?.archetype === 'frontend-surface' ||
-          (nestedTsPackages.length > 0 && includeRoots.length === 0 && !rec?.mature);
-        initArgs.push('--preset', useUi && nestedTsPackages.length <= 3 ? 'ui-surface' : 'monorepo');
+      } else if (startPreset === 'monorepo' || startPreset === 'ui-surface') {
+        initArgs.push('--preset', startPreset);
         const shown = includeRoots.length > 0 ? includeRoots : nestedTsPackages;
         console.log(
           shown.length > 0
             ? `  Multi-package / TS package layout detected — profile include: ${shown.join(', ')}.`
             : '  Multi-package layout detected — using monorepo profile.'
         );
-      } else if (preset) {
-        // Prefer recommended preset even on mature single-package trees (avoid vacuum hexagonal).
-        initArgs.push('--preset', preset);
+      } else if (startPreset) {
+        initArgs.push('--preset', startPreset);
       }
       const status = runArkCheck(initArgs, { cwd: root });
       if (status !== 0) return status;

package/bin/lib/adr-presence.mjs

@@ -0,0 +1,97 @@
+/**
+ * Soft ADR / decision-note presence when gates are demanded.
+ * Tooling I/O. Never a gate fail. Absence is silent unless require-gates
+ * or adopted-strict (required-merge) is on.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Conventional homes a human already uses. First hit wins. No config key. */
+export const ADR_PRESENCE_HOMES = Object.freeze([
+  'docs/adr',
+  'docs/decisions',
+  'docs/adr.md',
+  'docs/decision-log.md',
+  'ADR.md',
+  'DECISIONS.md',
+]);
+
+export const ADR_PRESENCE_ASK =
+  'Gates are required here, but there is no short decision note yet.';
+
+export const ADR_PRESENCE_NEXT =
+  'Add a short note under docs/adr/ (or docs/decisions/) when you loosen a rule or add a real gate. Not every change.';
+
+function isNonEmptyMarkdownFile(file) {
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return false;
+  try {
+    return fs.readFileSync(file, 'utf8').trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function directoryHasMarkdown(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
+  try {
+    return fs.readdirSync(dir).some((name) => {
+      if (!name.toLowerCase().endsWith('.md')) return false;
+      return isNonEmptyMarkdownFile(path.join(dir, name));
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * First conventional decision-note home that already has a note.
+ * Empty folders and empty files do not count.
+ *
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function findAdrPresenceHome(root) {
+  if (typeof root !== 'string' || root.length === 0) return null;
+  for (const rel of ADR_PRESENCE_HOMES) {
+    const abs = path.join(root, rel);
+    if (rel.endsWith('.md')) {
+      if (isNonEmptyMarkdownFile(abs)) return rel;
+      continue;
+    }
+    if (directoryHasMarkdown(abs)) return rel;
+  }
+  return null;
+}
+
+/**
+ * Soft residual when gates are demanded and no decision-note home exists.
+ * `demanded` is --require-gates / --strict / --strict-merge, or doctor
+ * adopted === 'required-merge'. Off → null (silent).
+ *
+ * @param {{ root?: string, demanded?: boolean }} [input]
+ * @returns {{ missing: true, ask: string, nextAction: string } | null}
+ */
+export function collectAdrPresenceResidual(input = {}) {
+  if (input.demanded !== true) return null;
+  const home = findAdrPresenceHome(input.root ?? '');
+  if (home) return null;
+  return {
+    missing: true,
+    ask: ADR_PRESENCE_ASK,
+    nextAction: ADR_PRESENCE_NEXT,
+  };
+}
+
+/**
+ * Human hint for --require-gates. Never changes exit code.
+ *
+ * @param {string} root
+ * @param {(line: string) => void} write
+ */
+export function printAdrPresenceHint(root, write) {
+  const residual = collectAdrPresenceResidual({ root, demanded: true });
+  if (!residual || typeof write !== 'function') return;
+  write(residual.ask);
+  write(`Next: ${residual.nextAction}`);
+}

package/bin/lib/agent-skills-package.mjs

@@ -51,7 +51,9 @@ export const ARK_SKILL_STUB_REDIRECTS = Object.freeze({
 });
 /**
  * Product surface → first-class doors that exercise it.
- * Standing check: every surface has at least one first-class door.
+ * Standing check: every surface has at least one first-class door whose
+ * body mentions that surface. Table keys must match
+ * {@link ARK_SKILL_REQUIRED_SURFACES}.
  */
 export const ARK_SKILL_CAPACITY = Object.freeze({
     Layers: ['ark-adopt', 'ark-place', 'ark-explore', 'ark-autopilot', 'ark-coverage', 'ark-explain'],
@@ -62,6 +64,27 @@ export const ARK_SKILL_CAPACITY = Object.freeze({
     Guiar: ['ark-explore', 'ark-autopilot', 'ark-explain', 'ark-coverage', 'ark-runtime'],
     Ordenar: ['ark-order'],
 });
+/**
+ * Closed product + north-star surfaces the skill *set* must exercise.
+ * Independent of {@link ARK_SKILL_CAPACITY} so deleting a table key fails closed.
+ */
+export const ARK_SKILL_REQUIRED_SURFACES = Object.freeze([
+    'Layers',
+    'ArkRules',
+    'ArkRun',
+    'ArkOrder',
+    'Contener',
+    'Guiar',
+    'Ordenar',
+]);
+/** Named first-class door that must stay on these surfaces (no leftover substitute). */
+export const ARK_SKILL_CAPACITY_DEDICATED_DOORS = Object.freeze({
+    ArkRun: 'ark-runtime',
+    ArkOrder: 'ark-order',
+    Ordenar: 'ark-order',
+});
+const NORTH_STAR_PHRASE = 'Contener · Guiar · Ordenar';
+const FORBIDDEN_ORDER_FREEZE = 'Do not invent `/ark-order`';
 /**
  * Closed shipped catalog (first-class + one-release stubs).
  * Sorted alphabetically for deterministic inventory diffs.
@@ -289,6 +312,161 @@ export function validateAgentSkillsPackage(entries) {
         presentCount: names.length,
     };
 }
+function pushCapacityIssue(issues, issue) {
+    issues.push(issue);
+}
+function skillMentionsSurface(body, surface) {
+    return body.includes(surface);
+}
+/**
+ * Observe skill bodies (and optional hubs) against the closed product surfaces.
+ * Inventory/layout stay on {@link validateAgentSkillsPackage}. This is the
+ * fail-closed tooth so a plane cannot silently drop out of the skill set.
+ */
+export function validateSkillProductCapacity(input) {
+    const issues = [];
+    const skills = input.skills ?? {};
+    const tableKeys = Object.keys(ARK_SKILL_CAPACITY);
+    for (const surface of ARK_SKILL_REQUIRED_SURFACES) {
+        if (!tableKeys.includes(surface)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_SURFACE_MISSING',
+                surface,
+                message: `The capacity table dropped ${surface}. Skills must keep covering ` +
+                    `Layers, ArkRules, ArkRun, ArkOrder plus Contener · Guiar · Ordenar. ` +
+                    `Put ${surface} back on ARK_SKILL_CAPACITY.`,
+            });
+        }
+    }
+    for (const key of tableKeys) {
+        if (!ARK_SKILL_REQUIRED_SURFACES.includes(key)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_SURFACE_UNMAPPED',
+                surface: key,
+                message: `The capacity table lists ${key}, which is not a product surface. ` +
+                    `Keep the table to Layers, ArkRules, ArkRun, ArkOrder and Contener · Guiar · Ordenar.`,
+            });
+        }
+    }
+    for (const surface of ARK_SKILL_REQUIRED_SURFACES) {
+        const doors = ARK_SKILL_CAPACITY[surface];
+        if (!doors || doors.length === 0)
+            continue;
+        for (const door of doors) {
+            if (!isFirstClassArkSkillName(door)) {
+                pushCapacityIssue(issues, {
+                    code: 'CAPACITY_DOOR_NOT_FIRST_CLASS',
+                    surface,
+                    skillName: door,
+                    message: `/${door} is listed for ${surface} but is not a first-class door. ` +
+                        `Leftover names are shortcuts. Point ${surface} at a first-class skill.`,
+                });
+            }
+        }
+        const covering = doors.filter((door) => {
+            const body = skills[door];
+            return typeof body === 'string' && skillMentionsSurface(body, surface);
+        });
+        if (covering.length === 0) {
+            const hint = surface === 'ArkOrder' || surface === 'Ordenar'
+                ? ' — usually /ark-order'
+                : surface === 'ArkRun'
+                    ? ' — usually /ark-runtime'
+                    : '';
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_BODY_GAP',
+                surface,
+                message: `Skills no longer cover ${surface}. The product has four parts ` +
+                    `(Layers, ArkRules, ArkRun, ArkOrder) plus Contener · Guiar · Ordenar. ` +
+                    `Put ${surface} back in a first-class skill${hint} so agents still know when to use it.`,
+            });
+        }
+    }
+    for (const [surface, door] of Object.entries(ARK_SKILL_CAPACITY_DEDICATED_DOORS)) {
+        const doors = ARK_SKILL_CAPACITY[surface];
+        if (!doors?.includes(door) || !isFirstClassArkSkillName(door)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_DEDICATED_DOOR',
+                surface,
+                skillName: door,
+                message: `/${door} is the first-class door for ${surface}. Keep it on that surface. ` +
+                    `Leftover names like /ark-think are shortcuts, not a replacement.`,
+            });
+            continue;
+        }
+        const body = skills[door];
+        if (typeof body !== 'string' || !skillMentionsSurface(body, surface)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_DEDICATED_DOOR',
+                surface,
+                skillName: door,
+                message: `/${door} no longer talks about ${surface}. That door is how agents reach ` +
+                    `this part of the product. Put ${surface} back in the skill body.`,
+            });
+        }
+    }
+    for (const name of ARK_FIRST_CLASS_SKILL_NAMES) {
+        const body = skills[name];
+        if (typeof body !== 'string') {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_ROUTING_GAP',
+                skillName: name,
+                message: `/${name} is a first-class door but has no skill body in this check. ` +
+                    `Ship the template so agents know when to use it.`,
+            });
+            continue;
+        }
+        const hasNorthStar = body.includes(NORTH_STAR_PHRASE);
+        const hasWhen = /When \/ not when|\*\*When:\*\*/.test(body);
+        const hasNotWhen = /Not when|Do \*\*not\*\* use|Prefer instead/.test(body);
+        const hasHandoff = /Handoff|hand off|`\/ark-/i.test(body);
+        if (!hasNorthStar || !hasWhen || !hasNotWhen || !hasHandoff) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_ROUTING_GAP',
+                skillName: name,
+                message: `/${name} is missing when / not when / handoff or Contener · Guiar · Ordenar. ` +
+                    `First-class skills must say when to use them and which sibling to call next.`,
+            });
+        }
+        if (body.includes(FORBIDDEN_ORDER_FREEZE)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_ROUTING_GAP',
+                skillName: name,
+                message: `/${name} still says not to invent /ark-order. That freeze is outdated — ` +
+                    `/ark-order is a first-class door.`,
+            });
+        }
+    }
+    const hubs = input.hubs ?? {};
+    for (const [hub, text] of Object.entries(hubs)) {
+        const body = String(text ?? '');
+        if (!body.includes('/ark-order')) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_HUB_GAP',
+                hub,
+                message: `${hub} no longer names /ark-order. Host instructions must stay at 100% of ` +
+                    `the product. Add /ark-order back, or you left the order plane behind.`,
+            });
+        }
+        if (!body.includes(NORTH_STAR_PHRASE)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_HUB_GAP',
+                hub,
+                message: `${hub} no longer says Contener · Guiar · Ordenar. Keep that filter in the ` +
+                    `living docs so agents pick the right sibling.`,
+            });
+        }
+        if (body.includes(FORBIDDEN_ORDER_FREEZE)) {
+            pushCapacityIssue(issues, {
+                code: 'CAPACITY_HUB_GAP',
+                hub,
+                message: `${hub} still says not to invent /ark-order. That freeze is outdated — ` +
+                    `/ark-order is a first-class door.`,
+            });
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
 /**
  * Visible package stamp at the start of Agent Skills `description`.
  * Hosts show `description` in the picker; `arkVersion:` in YAML is invisible there.