arkgate 2.8.1 → 2.8.3

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here.
 
+## Unreleased
+
+## 2.8.3 — 2026-07-09
+
+Field residuals + official site: core ratchet to honest ENFORCE, typecheck bootstrap,
+host-token scrub, arkgate.online homepage. **No intentional CLI flag or JSON shape breaks.**
+
+### Added
+
+- **`--ratchet-cores`:** when architecture is green (0 active violations, governed ≥ 50%),
+  set `optional: false` on **populated** core layers only so doctor can report **ENFORCE**
+  honestly. Empty cores stay optional (no false-ENFORCE theatre). Doctor core-optional gaps
+  point at this command; `/ark-autopilot` documents the step after goal.met.
+- **Typecheck bootstrap:** `ark start` / `--install-agent-gates` add `"typecheck": "tsc --noEmit"`
+  when `tsconfig.json`/`jsconfig.json` exists and no typecheck-like script is present; generated
+  CI includes the typecheck step. Existing scripts are never overwritten.
+
+### Changed
+
+- **Official website:** product homepage is [arkgate.online](https://www.arkgate.online/)
+  (`package.json` `homepage`, README badges/footer, ROADMAP identity). npm package page
+  and GitHub remain source + distribution links.
+- **Repo hygiene:** scrub named field-probe host identities from docs, comments, tests, and
+  historical changelog wording; fixtures stay framework-generic (Nest/Next only).
+- **Maintainability:** `--ratchet-cores` lives in `bin/lib/core-ratchet.mjs` (not the ark-check
+  entry); typecheck detection uses shared `packageScriptsHaveTypecheck` (not full deploy-path
+  scan); typecheck bootstrap is skipped under `--skills-only`.
+
+
+## 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
@@ -84,7 +139,7 @@ shape breaks** for the gate/co-pilot path.
 
 ## 2.6.1 — 2026-07-09
 
-Field-test release: Next/monorepo honesty (deer-flow-style hosts), simplified **one-flow** UX for
+Field-test release: Next/monorepo honesty (frontend monorepo hosts), simplified **one-flow** UX for
 humans and autonomous agents, and skills that require real source remediation—not CLI paraphrase.
 
 ### Fixed — false greens & strict CI noise (Next / monorepo)
@@ -132,7 +187,7 @@ Templates under `templates/skills/` (and project `.grok/skills` copies) for at l
 
 ### Tests
 
-- Fixture-style unit tests drive real `bin/ark-check.mjs`: Next core governance; deer-flow-like
+- Fixture-style unit tests drive real `bin/ark-check.mjs`: Next core governance; frontend monorepo-like
   monorepo (`frontend` + `core/**/types.ts` not Domain); strict-config with dead globs;
   empty baseline removal.
 

package/README.md

@@ -7,6 +7,7 @@
 Your AI writes most of the code. ArkGate keeps that code inside an architecture you can trust —
 and makes sure a “green” check means something real.
 
+[![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
 [![CI](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/arkgate?color=cb3837&label=npm)](https://www.npmjs.com/package/arkgate)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -267,10 +268,12 @@ npm run typecheck
 npm run check:architecture   # Ark gates itself
 ```
 
+**Website:** [arkgate.online](https://www.arkgate.online/)  
 **npm:** [`arkgate`](https://www.npmjs.com/package/arkgate) · formerly `ark-runtime-kernel`  
 **Product:** **ArkGate** — architecture co-pilot / gate for AI TypeScript (not a runtime kernel).  
 CLI: `arkgate` · `arkgate-check` · `arkgate-mcp` (aliases `ark` / `ark-check` / `ark-mcp` still work for one major).  
-MCP registry: `io.github.pedroknigge/arkgate`.
+MCP registry: `io.github.pedroknigge/arkgate`.  
+**Source:** [github.com/pedroknigge/arkgate](https://github.com/pedroknigge/arkgate)
 
 Node ≥ 18 · **MIT**.
 

package/bin/ark-check.mjs

@@ -60,6 +60,7 @@ import {
   runPlan,
   runDoctor,
 } from './lib/doctor-plan.mjs';
+import { runRatchetCores } from './lib/core-ratchet.mjs';
 import {
   baselineKey,
   readBaseline,
@@ -153,6 +154,7 @@ function parseArgs(argv) {
     else if (arg === '--apply-policy-pack') args.applyPolicyPack = argv[++i];
     else if (arg === '--suggest-include') args.suggestInclude = true;
     else if (arg === '--adopt-contract') args.adoptContract = true;
+    else if (arg === '--ratchet-cores') args.ratchetCores = true;
     else if (arg === '--write') args.write = true;
     else if (arg === '--watch') args.watch = true;
     else if (arg === '--beginner') args.beginner = true;
@@ -203,6 +205,7 @@ function usage() {
     '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',
     '       ark-check --suggest-include [--json]   propose include roots (TS packages / workspaces)',
     '       ark-check --adopt-contract [--write]   expand include + UI patterns from ungoverned dirs (contract adopt)',
+    '       ark-check --ratchet-cores              when raw graph is green (0 violations; baseline ignored), set optional:false on populated cores only (writes ark.config.json)',
     '       ark-check --watch                      re-run the check when governed files change (debounced)',
     '       ark-check --report [file.html] [--beginner] [--reset-origin] [--no-archive]',
     '           HTML report + snapshots under .ark/reports/ (origin once, latest each run, history JSON)',
@@ -1046,6 +1049,11 @@ async function main() {
     return;
   }
 
+  if (args.ratchetCores) {
+    runRatchetCores(root, config, files, rules, violations, args, { displayPathFromRoot });
+    return;
+  }
+
   if (args.updateBaseline) {
     const summary = summarizeViolations(violations);
     // Bloquear y avisar: a lopsided freeze buries a likely contract bug as "debt". Refuse it

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';
@@ -994,7 +1053,7 @@ export function collectRepoShapeSignals(root) {
   const pkg = readPackageJson(root);
   const workspaceDirs = detectWorkspaces(root);
   const workspaces = workspaceDirs.length > 0;
-  // Include frontend/web/client — common Next monorepo app folders (deer-flow-style).
+  // Include frontend/web/client — common Next monorepo app folders.
   const candidateScanDirs = [
     'src',
     'lib',
@@ -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';
@@ -457,6 +498,11 @@ async function start(args) {
     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) {
+      console.log(
+        `  4. When green but cores still optional: ${arkCommand(root, 'ark-check', '--ratchet-cores')} → honest ENFORCE`
+      );
+    }
     console.log('');
     console.log('Optional later: --plan · --coverage · /ark-fix · /ark-place · ark upgrade');
 

package/bin/lib/agent-gates.mjs

@@ -20,8 +20,9 @@ import {
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   DEFAULT_RULES,
   createElevenLayerConfig,
-  applyFrameworkLayoutOverlays
+  applyFrameworkLayoutOverlays,
 } from '../ark-shared.mjs';
+import { CORE_LAYER_NAMES } from './core-ratchet.mjs';
 import {
   assessCodexHomeMcp,
   codexArkBlockHasPreferredBin,
@@ -76,6 +77,97 @@ export function hasCheckArchitectureScript(root) {
   return Boolean(pkg?.scripts?.['check:architecture']);
 }
 
+/**
+ * Whether package.json scripts already expose a typecheck-like command.
+ * Shared by deploy-path quality + typecheck bootstrap (single definition).
+ * @param {Record<string, unknown>|null|undefined} scripts
+ */
+export function packageScriptsHaveTypecheck(scripts) {
+  if (!scripts || typeof scripts !== 'object') return false;
+  return Boolean(
+    (typeof scripts.typecheck === 'string' && scripts.typecheck.trim()) ||
+      (typeof scripts['type-check'] === 'string' && scripts['type-check'].trim()) ||
+      (typeof scripts['check:types'] === 'string' && scripts['check:types'].trim()) ||
+      (typeof scripts.tsc === 'string' && /\btsc\b/.test(scripts.tsc))
+  );
+}
+
+/**
+ * Root package (and shallow nested packages) already have a typecheck script.
+ * Does not scan CI or framework configs — only package.json scripts.
+ * @param {string} root
+ */
+export function treeHasTypecheckScript(root) {
+  const pkg = readPackageJson(root);
+  if (packageScriptsHaveTypecheck(pkg?.scripts)) return true;
+  try {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const candidates = [path.join(root, entry.name)];
+      try {
+        for (const child of fs.readdirSync(path.join(root, entry.name), { withFileTypes: true })) {
+          if (child.isDirectory() && !child.name.startsWith('.')) {
+            candidates.push(path.join(root, entry.name, child.name));
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+      for (const dir of candidates) {
+        const pj = path.join(dir, 'package.json');
+        if (!fs.existsSync(pj)) continue;
+        try {
+          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
+          if (packageScriptsHaveTypecheck(nested.scripts)) return true;
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return false;
+}
+
+/**
+ * Add a conservative `typecheck` script when the host has a TS/JS project config
+ * but no typecheck-like script yet. Never overwrites an existing script.
+ *
+ * @param {string} root
+ * @param {{ write?: boolean }} [opts]
+ * @returns {{
+ *   changed: boolean,
+ *   reason: 'added' | 'already' | 'no-tsconfig' | 'no-package-json',
+ *   script?: string,
+ * }}
+ */
+export function ensureTypecheckScript(root, opts = {}) {
+  const write = opts.write !== false;
+  const hasTsconfig =
+    fs.existsSync(path.join(root, 'tsconfig.json')) ||
+    fs.existsSync(path.join(root, 'jsconfig.json'));
+  if (!hasTsconfig) return { changed: false, reason: 'no-tsconfig' };
+
+  const pkgPath = path.join(root, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { changed: false, reason: 'no-package-json' };
+
+  if (treeHasTypecheckScript(root)) {
+    return { changed: false, reason: 'already' };
+  }
+
+  const pkg = readPackageJson(root) || {};
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === 'object' ? { ...pkg.scripts } : {};
+  const script = 'tsc --noEmit';
+  scripts.typecheck = script;
+  if (write) {
+    const next = { ...pkg, scripts };
+    fs.writeFileSync(pkgPath, `${JSON.stringify(next, null, 2)}\n`);
+  }
+  return { changed: true, reason: 'added', script };
+}
+
 export const REQUIRED_GATE_FILES = [
   'AGENTS.md',
   '.mcp.json',
@@ -483,7 +575,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 +597,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 +635,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}
 `;
 }
@@ -922,14 +1037,6 @@ export function brokenMcpGateFiles(root) {
   return bad;
 }
 
-/** Core layers whose optionality matters once they match files (presets share these names). */
-const CORE_LAYER_NAMES = new Set([
-  'DomainModel',
-  'ApplicationOrchestration',
-  'PresentationAdapters',
-  'PersistenceAdapters',
-]);
-
 /**
  * Production deploy path quality (universal — any consumer repo).
  * Detects when the production build host runs ESLint / typecheck as part of
@@ -982,17 +1089,9 @@ export function detectDeployPathQuality(root) {
           (typeof s['lint:ci'] === 'string' && s['lint:ci'].trim()) ||
           (typeof s['check:lint'] === 'string' && s['check:lint'].trim()))
     );
-  const scriptHasTypecheck = (s) =>
-    Boolean(
-      s &&
-        ((typeof s.typecheck === 'string' && s.typecheck.trim()) ||
-          (typeof s['type-check'] === 'string' && s['type-check'].trim()) ||
-          (typeof s['check:types'] === 'string' && s['check:types'].trim()) ||
-          (typeof s.tsc === 'string' && /\btsc\b/.test(s.tsc)))
-    );
 
   let hasLintScript = scriptHasLint(scripts);
-  let hasTypecheckScript = scriptHasTypecheck(scripts);
+  let hasTypecheckScript = packageScriptsHaveTypecheck(scripts);
   const packageLintScripts = [];
   // Monorepo: package-level scripts count (apps/web, packages/ui, …).
   try {
@@ -1019,7 +1118,7 @@ export function detectDeployPathQuality(root) {
             hasLintScript = true;
             packageLintScripts.push(path.relative(root, dir).split(path.sep).join('/'));
           }
-          if (scriptHasTypecheck(ns)) hasTypecheckScript = true;
+          if (packageScriptsHaveTypecheck(ns)) hasTypecheckScript = true;
           const nd = {
             ...(nested.dependencies || {}),
             ...(nested.devDependencies || {}),
@@ -1266,7 +1365,7 @@ export function collectAdoptionGaps(root, config, coverage) {
         id: `core-optional-${layer.name}`,
         severity: 'info',
         message: `Core layer ${layer.name} has ${files} file(s) but is still optional: true — contract is weaker than the tree`,
-        fix: `Edit ark.config.json: remove optional on ${layer.name} (or set false), then ${arkCommand(root, 'ark-check', '--strict-config')}`,
+        fix: `${arkCommand(root, 'ark-check', '--ratchet-cores')} (when architecture is green: 0 active violations)`,
       });
     }
   }
@@ -1602,13 +1701,27 @@ export function runInstallAgentGates(args) {
   // overwrite (they track the package). The gate/instruction files (AGENTS.md,
   // settings.json, CI workflow, rules) are the ones users customize, so a plain
   // `--force` clobbers them — this is the safe way to pick up new skill versions.
+  // Do not mutate package.json under --skills-only (typecheck bootstrap is gates/CI).
   if (!args.skillsOnly) {
+    // Bootstrap typecheck before CI template so generated workflow includes the step.
+    const typecheckBootstrap = ensureTypecheckScript(root, { write: true });
+    if (typecheckBootstrap.changed && !args.json) {
+      console.log(
+        `Added package.json script "typecheck": "${typecheckBootstrap.script}" (tsconfig present; local/CI parity).`
+      );
+    }
     // Base gates: tool-agnostic contract + CI backstop, always written.
     templates.push(['AGENTS.md', agentInstructions(root)]);
     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/config-warnings.mjs

@@ -127,7 +127,7 @@ export function collectConfigWarnings(root, config, files, rules, manifest) {
         // Advisory only under --strict-config: monorepo/Next presets ship many optional-looking
         // globs (e.g. src/layouts/**, app/**) that never match when include is ["frontend"].
         // Failing the release gate on dead preset globs caused false CI red while architecture
-        // edges were clean (deer-flow host validation). Real safety is import violations +
+        // edges were clean on multi-package hosts. Real safety is import violations +
         // CONFIG_UNCLASSIFIED_FILES / invalid patterns.
         warnings.push(
           configWarning(