arkgate 2.8.2 → 2.8.3

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## 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
@@ -112,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)
@@ -160,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

@@ -1053,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',

package/bin/ark.mjs

@@ -498,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',
@@ -945,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
@@ -1005,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 {
@@ -1042,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 || {}),
@@ -1289,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)`,
       });
     }
   }
@@ -1625,7 +1701,15 @@ 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)]);

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(

package/bin/lib/core-ratchet.mjs

@@ -0,0 +1,152 @@
+/**
+ * Core-layer optionality ratchet — pure plan + CLI runner.
+ * Keeps ark-check.mjs orchestration-only (dispatch only).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { computeCoverage } from './doctor-plan.mjs';
+
+/**
+ * Core layers whose optionality matters once they match files (presets share these names).
+ * Used by doctor adoption gaps and `--ratchet-cores`.
+ */
+export const CORE_LAYER_NAMES = new Set([
+  'DomainModel',
+  'ApplicationOrchestration',
+  'PresentationAdapters',
+  'PersistenceAdapters',
+]);
+
+/**
+ * Plan a ratchet of optional→required for core layers that already match files.
+ * Empty cores stay optional (avoids false ENFORCE theatre). Pure — does not write disk.
+ *
+ * @param {object} config ark.config.json shape
+ * @param {{ name: string, files: number }[]} layerRows coverage layer rows
+ */
+export function planPopulatedCoreRatchet(config, layerRows = []) {
+  const countByName = new Map(
+    (Array.isArray(layerRows) ? layerRows : []).map((row) => [row.name, Number(row.files) || 0])
+  );
+  const ratcheted = [];
+  const alreadyStrict = [];
+  const stillOptionalEmpty = [];
+  const nextLayers = (config?.layers ?? []).map((layer) => {
+    if (!CORE_LAYER_NAMES.has(layer.name)) return layer;
+    const files = countByName.get(layer.name) ?? 0;
+    if (layer.optional !== true) {
+      if (files > 0) alreadyStrict.push({ layer: layer.name, files });
+      return layer;
+    }
+    if (files <= 0) {
+      stillOptionalEmpty.push(layer.name);
+      return layer;
+    }
+    ratcheted.push({ layer: layer.name, files });
+    return { ...layer, optional: false };
+  });
+  return {
+    ratcheted,
+    alreadyStrict,
+    stillOptionalEmpty,
+    config: { ...(config ?? {}), layers: nextLayers },
+    changed: ratcheted.length > 0,
+  };
+}
+
+/**
+ * When the architecture is green (raw violations = 0, not baselined), ratchet populated
+ * core layers from optional→required so doctor can honestly report ENFORCE.
+ * Empty cores stay optional. Always writes when changes apply (like --update-baseline).
+ *
+ * @param {string} root
+ * @param {object} config
+ * @param {string[]} files
+ * @param {object[]} rules
+ * @param {object[]} violations raw scan violations (baseline ignored — must be truly clean)
+ * @param {{ json?: boolean, config?: string }} args
+ * @param {{ displayPathFromRoot: (root: string, abs: string) => string }} deps
+ */
+export function runRatchetCores(root, config, files, rules, violations, args, deps) {
+  const displayPathFromRoot = deps.displayPathFromRoot;
+  const cov = computeCoverage(root, config, files, rules);
+  const activeCount = Array.isArray(violations) ? violations.length : 0;
+  const configPath = path.isAbsolute(args.config)
+    ? args.config
+    : path.join(root, args.config || 'ark.config.json');
+
+  const refuse = (code, message, extra = {}) => {
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, error: message, ...extra }, null, 2));
+    } else {
+      console.error(message);
+    }
+    process.exitCode = code;
+  };
+
+  if (activeCount > 0) {
+    refuse(
+      2,
+      `Refusing --ratchet-cores: ${activeCount} active architecture violation(s) (raw graph; baseline does not count). Resolve them first (ark-check --plan), then re-run.`,
+      { activeViolations: activeCount, governed: cov.governed }
+    );
+    return;
+  }
+  if (cov.totalFiles === 0 || (cov.governed?.percent ?? 0) < 50) {
+    refuse(
+      2,
+      `Refusing --ratchet-cores: governed coverage is too low (${cov.governed?.percent ?? 0}% of ${cov.totalFiles} files). Classify ungoverned code first.`,
+      { governed: cov.governed }
+    );
+    return;
+  }
+
+  const plan = planPopulatedCoreRatchet(config, cov.layers);
+  if (!plan.changed) {
+    const payload = {
+      ok: true,
+      changed: false,
+      message: 'No optional core layers with files — nothing to ratchet.',
+      alreadyStrict: plan.alreadyStrict,
+      stillOptionalEmpty: plan.stillOptionalEmpty,
+      governed: cov.governed,
+    };
+    if (args.json) console.log(JSON.stringify(payload, null, 2));
+    else {
+      console.log(payload.message);
+      if (plan.stillOptionalEmpty.length > 0) {
+        console.log(`Still optional (empty patterns): ${plan.stillOptionalEmpty.join(', ')}`);
+      }
+    }
+    return;
+  }
+
+  fs.writeFileSync(configPath, `${JSON.stringify(plan.config, null, 2)}\n`);
+  const payload = {
+    ok: true,
+    changed: true,
+    configPath: displayPathFromRoot(root, configPath),
+    ratcheted: plan.ratcheted,
+    stillOptionalEmpty: plan.stillOptionalEmpty,
+    governed: cov.governed,
+    next: arkCommand(root, 'ark-check', '--doctor'),
+  };
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(
+      `Ratcheted ${plan.ratcheted.length} core layer(s) to optional: false (populated only):`
+    );
+    for (const row of plan.ratcheted) {
+      console.log(`  ${row.layer} (${row.files} file(s))`);
+    }
+    if (plan.stillOptionalEmpty.length > 0) {
+      console.log(
+        `Left optional (empty patterns — avoid false ENFORCE): ${plan.stillOptionalEmpty.join(', ')}`
+      );
+    }
+    console.log(`Wrote ${displayPathFromRoot(root, configPath)}`);
+    console.log(`Confirm: ${payload.next}`);
+  }
+}

package/dist/index.cjs

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