arkgate 2.13.0 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+No changes are scheduled after the prepared stable release.
+
+## 3.0.0 — 2026-07-13
+
+### Added
+
+- **Compact active-host onboarding:** `ark start` now asks for the active host on a TTY (or
+  detects it non-interactively), writes at most five project files / 25 KB, and uses one
+  package/MCP-backed router instead of copied per-host skill packs. It does not alter
+  `package.json` unless `--install` is explicit; host removal and re-addition are previewed,
+  safe, and reversible.
+
+- **Canonical analysis engine bundle:** graph policy, cycle evaluation, and configuration
+  diagnostics now have one Kernel implementation shared by the library, CLI, and MCP. A documented
+  standalone CLI bundle preserves the package's self-hosted boundary and is protected by a CI drift
+  check and Kernel/bundle parity fixtures.
+- **Symbol-aware semantic analysis:** one Kernel extractor now resolves forbidden ambient
+  capabilities through local symbols, aliases, `globalThis`, static keys, and destructuring, and
+  classifies TS/JS dependency forms across ESM, CommonJS, type-only, and unresolved dynamic edges.
+  CLI, safety diagnostics, and AICodeGate consume the same generated implementation. The supported
+  soundness envelope is documented and guarded by a labeled adversarial corpus plus TypeScript
+  5/6/7 and mutation matrices.
+- **Versioned adapter parity:** CLI JSON, MCP structured results, write hooks, ESLint, and the
+  GitHub Action now expose the same `ark.analysis-result` v1 diagnostics. A generated JSON Schema,
+  committed compatibility fixture, exact golden corpus, and mandatory CI parity job prevent
+  adapter drift; source-policy decisions no longer live privately inside ESLint.
+- **Runtime package isolation:** the next-major `arkgate` root now contains only gate APIs. The
+  optional runtime and NestJS adapter build independently as experimental `@arkgate/runtime`;
+  deprecated subpath shims contain no implementation. The non-atomic store is now presented as
+  `InMemoryEventBuffer`, with production recovery and durability requirements made explicit.
+
+### Fixed
+
+- **Deterministic offline setup tests:** `ark start` fixtures that do not exercise installation now
+  pass `--no-install`, preventing a published current version from turning unit tests into registry
+  installs.
+- **Node 26 watch fallback:** `ark-check --watch` falls back to bounded polling when recursive
+  `fs.watch` fails asynchronously with `EMFILE`, instead of crashing the watcher process.
+
 ## 2.13.0 — 2026-07-11
 
 - Added the stable, deterministic analysis IR and public in-memory API: `loadContract`,

package/README.md

@@ -16,6 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
+> **ArkGate 3.0** passed its independent beta-exit audit. The npm badge reports the version
+> currently available in the registry.
+
 ---
 
 ## The only flow (humans and agents)
@@ -23,8 +26,10 @@ and makes sure a “green” check means something real.
 If you remember nothing else:
 
 ```text
-1.  npx arkgate start          ← walk tree → contract → **day-zero origin** → gates
-2.  /ark-autopilot             ← explore first, dual plan, safe fixes, leave gates on
+1.  npx arkgate start          ← read-only preview: files + commands + projected coverage
+    npx arkgate start --apply  ← apply exactly the previewed mutations
+2.  Compact router             ← MCP/AGENTS routes place, validate, and architecture checks
+    /ark-autopilot             ← optional full guided workflow after its skill pack is installed
 3.  npx arkgate-check --doctor ← “where am I?” anytime (one status screen)
 ```
 
@@ -36,8 +41,8 @@ If you remember nothing else:
 | New ArkGate version | `/ark-upgrade` |
 
 **Everything else is optional.** You do not need to learn “modes”, 11 skills, or the runtime
-kernel to get value. Agents that are unsure should **only** run `/ark-autopilot` (or the three
-commands above).
+kernel to get value. The compact router is enough for normal work; install `/ark-autopilot` only
+when you want the full guided workflow.
 
 ---
 
@@ -65,12 +70,13 @@ It is **not** a web framework, ORM, or job runner.
 
 ## Who it’s for
 
-Same start for almost everyone: **`npx arkgate start` → `/ark-autopilot`**.
+Same start for almost everyone: **`npx arkgate start` → compact router** (then
+`/ark-autopilot` when you opt into the full skill pack).
 
 | You are… | Same start, then… |
 |----------|-------------------|
-| Builder with AI | Stay on autopilot until doctor is happy |
-| Tech lead on a messy monorepo | Autopilot (or deeper `/ark-adopt` if you want a focused brownfield pass) |
+| Builder with AI | Use the compact router and doctor; add autopilot when you want guided remediation |
+| Tech lead on a messy monorepo | Add autopilot (or deeper `/ark-adopt` for a focused brownfield pass) |
 | Power user | Same flow; use `ark-check --plan` / `--coverage` when you want the raw sensor |
 
 **Not for:** no TypeScript, “just one lint rule”, or looking for an app framework.
@@ -110,8 +116,9 @@ Full checklist (CI, MCP, Codex, imports): **[docs/migrate-from-ark-runtime-kerne
 
 ```bash
 npm install -D arkgate typescript
-npx arkgate start                 # contract → day-zero origin → gates + plan
-# in agent:
+npx arkgate start                 # read-only preview: exact mutations + projected coverage
+npx arkgate start --apply         # apply the compact contract → active-host router → CI plan
+# optional, after installing the full skill pack:
 #   /ark-autopilot
 npx arkgate-check --doctor        # status light + next action
 ```
@@ -121,7 +128,7 @@ Aliases `ark` / `ark-check` / `ark-mcp` still work. **npm / pnpm / yarn**. No in
 <details>
 <summary>What <code>/ark-autopilot</code> does under the hood (optional detail)</summary>
 
-1. Setup if needed (`ark start` — contract, then **day-zero origin**, then gates).
+1. Setup if needed (`ark start` — compact contract + active-host router + CI gate; create an HTML/origin report explicitly when you need one).
 2. **Explore pass** (decision-grade map of *this* product; field path when demos exist).
 3. **Dual plan:** **A** remediation from `--plan` (mechanical-safe only by default); **B** pattern/evolution bets (never auto-applied as mechanical-safe). Empty plan ≠ “healthy” without explore/B.
 4. Apply A → re-check; judgment only when you ask for full apply.
@@ -150,8 +157,9 @@ npx arkgate-check --coverage
 Install once: `npx arkgate-check --install-agent-gates`
 (`--tools claude,cursor,codex,grok` to pick hosts.)
 
-**Default is always `/ark-autopilot`.** The rest are escapes, not a second curriculum.
-Generated `AGENTS.md` includes a **skill routing table** (trigger → skill). Skills are
+**The compact router is the default; `/ark-autopilot` is the full guided option.** The rest are
+escapes, not a second curriculum. Full-install `AGENTS.md` includes a **skill routing table**
+(trigger → skill). Skills are
 **dual-engine** (CLI sensor + read real source) and end with a fixed **completion contract**;
 critical handoffs say **STOP** and name the next skill (hosts must follow — markdown cannot chain calls).
 When the host allows it, skills may **fan out parallel subagents** (disjoint scopes);
@@ -211,16 +219,18 @@ ark.config.json
   [configuration and editor guide](docs/configuration.md).
 - **Frameworks:** Nest / Next / express / library layouts get sensible globs on init so day-one coverage is real.
 - **Brownfield:** baseline ratchet, refuse to freeze a wrong contract, `/ark-adopt` for mature trees.
-- **Agents:** skills install into Claude / Cursor / Codex / Grok; `ark start` freezes **day-zero origin** under `.ark/reports/` **before** agent docs/CI templates.
+- **Agents:** `ark start` asks for (or detects) one active host and writes one compact router, not copied skill packs, in at most five project files and 25 KB. Use `ark-check --install-agent-gates --skills-only --tools <host>` later when you explicitly want the full `/ark-*` skill set. Reports are opt-in with `ark-check --report`.
 - **Write protocol (2.10 / Track W):** mechanical-safe **autoPatch** on the write gate (`import type`); MCP **`ark_prepare_write`** (place + validate + patch + judgmentBrief); opt-in hook **`--hook-repair`** (`ARK_REPAIR_JSON`); doctor **`writePath`** (repair vs reject-only); loop-cost eval (`npm run eval:loop-cost`). Port-proof inject is **judgment** (arity change), not silent auto-apply.
 - **Fail-closed CI (2.11):** `--strict-merge` combines config coverage, shared gate-file
   presence, and bypass diagnostics for dynamic imports, TypeScript suppressions, explicit `any`
   casts, InMemory runtime defaults, and disabled peer isolation. `--strict` is a compatibility
   alias. Neither requires an editor hook; use `--require-write-hook claude|grok` when that local
   guarantee is part of the check.
-- **Trust / coverage (2.12):** package unit-test floors on the broad product surface
+- **Trust / coverage (3.0 release baseline):** package unit-test floors on the broad product surface
   (statements/lines **≥80%**, branches/functions **≥85%**; enforcement-critical modules **≥95%**
-  branch). Explore dual-plan + day-zero origin first (see above). Roadmap next: Q2 repair dogfood matrix.
+  branch). The V05 beta-exit audit passed with 12 pinned public adoptions, 97% median governed
+  coverage, and zero P0/P1 findings. Stable publication remains the signed-tag, GitHub Release,
+  and provenance-backed npm workflow documented in [the 3.0.0 release notes](docs/releases/3.0.0.md).
 - **TypeScript:** project compilers 5.x / 6.x / 7.x — gate falls back to a nested JS-API TypeScript when TS 7’s main export is version-only ([docs/typescript-support.md](docs/typescript-support.md)).
 
 ### Why not only ESLint / dependency-cruiser / Nx?
@@ -242,7 +252,11 @@ ark.config.json
 ## Common commands
 
 ```bash
-npx arkgate start                         # guided setup: contract → origin → gates → plan
+npx arkgate start                         # guided read-only preview
+npx arkgate start --apply                 # apply the compact active-host setup (≤5 files)
+npx arkgate start --tools codex --apply   # select the host explicitly
+npx arkgate start --install --apply       # also add arkgate to package.json (explicit only)
+npx arkgate start --remove-host codex     # preview compact-host removal; add --apply to confirm
 npx arkgate-check --doctor                # health + Adoption gaps (not just fitness)
 npx arkgate-check --doctor --json         # machine-readable doctor.adoption
 npx arkgate-check --strict                # fail-closed CI + installed-gate/safety checks
@@ -266,21 +280,21 @@ CI (example):
 
 Gates need **no app code changes**. The runtime API is currently **experimental** and is not a
 production-readiness claim. If you want to evaluate runtime intent/event contracts, use the
-opt-in subpath (preferred):
+separate experimental package:
 
 ```ts
-import { createStrictArkKernelFromConfig } from 'arkgate/runtime';
+import { createStrictArkKernelFromConfig } from '@arkgate/runtime';
 // see docs/production-hardening.md and docs/package-surface.md
 ```
 
-Root `import { … } from 'arkgate'` still re-exports kernel symbols for compatibility
-in this major; use `arkgate/runtime` when evaluating the experimental surface.
+The stable `arkgate` package does not bundle runtime implementation. The deprecated
+`arkgate/runtime` forwarding shim requires `@arkgate/runtime` and is removed in ArkGate 4.
 
-NestJS: `arkgate/nestjs` (optional peer `@nestjs/common`).
+NestJS: `@arkgate/runtime/nestjs` (optional peer `@nestjs/common`).
 
 ### Durability stance (built-in stores)
 
-The kernel’s default stores (`InMemoryOutboxStore`, `InMemoryAuditStore`,
+The kernel’s default stores (`InMemoryEventBuffer`, `InMemoryAuditStore`,
 `InMemoryReadModelStore`, `InMemoryWorkflowStore`) are **reference in-memory only**:
 fine for tests, demos, and single-process local work — they **do not** survive restarts
 and are **not** production durability. Implement the store interfaces (or inject your own)
@@ -301,6 +315,7 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Agent / MCP tools | [docs/agent-guide.md](docs/agent-guide.md) |
 | Demos | [docs/demos/](docs/demos/) |
 | Examples | [examples/](examples/README.md) |
+| Release 3.0.0 | [release notes and publication checklist](docs/releases/3.0.0.md) |
 | Roadmap | [ROADMAP.md](ROADMAP.md) · [Changelog](CHANGELOG.md) |
 
 ---

package/bin/ark-check.mjs

@@ -42,6 +42,7 @@ import {
   checkArchitectureScriptSnippet,
   arkCheckCommand,
   arkPackageVersion,
+  compactRouterHost,
   REQUIRED_GATE_FILES,
   codexPromptsDir,
   detectWritePathCapabilities,
@@ -84,6 +85,7 @@ import {
   ARCHITECTURE_PRESETS,
 } from './lib/presets.mjs';
 import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
+import { createAdapterResult } from './lib/adapter-contract.mjs';
 
 import {
   collectGovernedFiles,
@@ -110,6 +112,7 @@ function parseArgs(argv) {
     requireWriteHook: undefined,
     init: false,
     installAgentGates: false,
+    compact: false,
     tools: undefined,
     force: false,
     skillsOnly: false,
@@ -153,6 +156,7 @@ function parseArgs(argv) {
     else if (arg === '--init') args.init = true;
     else if (arg === '--preset') args.preset = requireValue(arg, i++);
     else if (arg === '--install-agent-gates') args.installAgentGates = true;
+    else if (arg === '--compact') args.compact = true;
     else if (arg === '--tools') {
       // Consume the next arg only when it isn't another flag (same rule as --baseline),
       // so `--tools --force` can't silently eat --force as a "tool name".
@@ -1038,7 +1042,13 @@ async function main() {
     // callers still get a clear signal from the exit code and the human-mode line.
     if (!args.json) {
       if (args.requireGates) {
-        console.log('Ark gates present (merge profile): ' + REQUIRED_GATE_FILES.join(', '));
+        const compactHost = compactRouterHost(args.root);
+        console.log(
+          'Ark gates present (merge profile): ' +
+            (compactHost
+              ? `AGENTS.md, compact host registration (${compactHost})`
+              : REQUIRED_GATE_FILES.join(', '))
+        );
       }
       if (writeRequest?.host) {
         console.log(`Ark hard-write hook present for ${writeRequest.host}.`);
@@ -1330,7 +1340,13 @@ async function main() {
   }
 
   if (args.json) {
+    const adapterResult = createAdapterResult({
+      valid: ok,
+      violations: activeViolations.map(enrichViolationWithFixClass),
+      warnings,
+    });
     console.log(JSON.stringify({
+      ...adapterResult,
       ok,
       violations: activeViolations.map(enrichViolationWithFixClass),
       suppressedViolations: suppressed.length,
@@ -1489,9 +1505,13 @@ async function runWatchMode(args) {
     const target = path.join(args.root, entry);
     if (!fs.existsSync(target)) continue;
     try {
-      fs.watch(target, { recursive: true }, rerun);
+      const watcher = fs.watch(target, { recursive: true }, rerun);
+      watcher.on('error', () => {
+        watcher.close();
+        watchByPolling(target, rerun);
+      });
     } catch {
-      fs.watch(target, rerun);
+      watchByPolling(target, rerun);
     }
   }
 
@@ -1499,7 +1519,45 @@ async function runWatchMode(args) {
   await new Promise(() => {});
 }
 
+function watchByPolling(target, onChange) {
+  let previous = watchFingerprint(target);
+  setInterval(() => {
+    const current = watchFingerprint(target);
+    if (current === previous) return;
+    previous = current;
+    onChange();
+  }, 250);
+}
+
+function watchFingerprint(target) {
+  const pending = [target];
+  const entries = [];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    let stat;
+    try {
+      stat = fs.statSync(current);
+    } catch {
+      continue;
+    }
+    entries.push(`${current}:${stat.mtimeMs}:${stat.size}`);
+    if (!stat.isDirectory()) continue;
+    try {
+      for (const name of fs.readdirSync(current)) pending.push(path.join(current, name));
+    } catch {
+      // A concurrent delete is represented by the next fingerprint.
+    }
+  }
+  return entries.sort().join('|');
+}
+
 main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
+  console.error(
+    process.env.ARK_DEBUG_STACK === '1' && error instanceof Error
+      ? error.stack
+      : error instanceof Error
+        ? error.message
+        : String(error)
+  );
   process.exitCode = 2;
 });

package/bin/ark-mcp.mjs

@@ -59,6 +59,7 @@ import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
+import { ARK_ANALYSIS_RESULT_SCHEMA, createAdapterResult } from './lib/adapter-contract.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 
@@ -179,6 +180,8 @@ function normalizeHookPayload(payload) {
     Edit: 'Edit',
     search_replace: 'Edit',
     MultiEdit: 'MultiEdit',
+    ApplyPatch: 'ApplyPatch',
+    apply_patch: 'ApplyPatch',
   };
   const toolName = nameMap[rawName] ?? rawName;
   const filePath =
@@ -193,6 +196,70 @@ function normalizeHookPayload(payload) {
   };
 }
 
+function applyCodexUpdatePatch(current, lines) {
+  let source = current.split('\n');
+  let cursor = 0;
+  const hunks = [];
+  let hunk = [];
+  for (const line of lines) {
+    if (line.startsWith('@@')) {
+      if (hunk.length > 0) hunks.push(hunk);
+      hunk = [];
+    } else if (/^[ +\-]/.test(line)) {
+      hunk.push(line);
+    }
+  }
+  if (hunk.length > 0) hunks.push(hunk);
+  for (const entries of hunks) {
+    const oldLines = entries.filter((line) => !line.startsWith('+')).map((line) => line.slice(1));
+    const newLines = entries.filter((line) => !line.startsWith('-')).map((line) => line.slice(1));
+    let found = -1;
+    for (let at = cursor; at <= source.length - oldLines.length; at += 1) {
+      if (oldLines.every((line, index) => source[at + index] === line)) {
+        found = at;
+        break;
+      }
+    }
+    if (found < 0) return null;
+    source.splice(found, oldLines.length, ...newLines);
+    cursor = found + newLines.length;
+  }
+  return source.join('\n');
+}
+
+function codexPatchWrites(patch, root) {
+  if (typeof patch !== 'string' || !patch.includes('*** Begin Patch')) return [];
+  const lines = patch.split('\n');
+  const writes = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^\*\*\* (Add|Update|Delete) File: (.+)$/);
+    if (!match) continue;
+    const [, action, relativePath] = match;
+    const body = [];
+    for (index += 1; index < lines.length && !lines[index].startsWith('*** '); index += 1) {
+      body.push(lines[index]);
+    }
+    index -= 1;
+    if (action === 'Delete') continue;
+    const filePath = path.resolve(root, relativePath);
+    let content;
+    if (action === 'Add') {
+      content = body.filter((line) => line.startsWith('+')).map((line) => line.slice(1)).join('\n');
+      if (body.some((line) => line.startsWith('+'))) content += '\n';
+    } else {
+      let current;
+      try {
+        current = fs.readFileSync(filePath, 'utf8');
+      } catch {
+        continue;
+      }
+      content = applyCodexUpdatePatch(current, body);
+    }
+    if (typeof content === 'string') writes.push({ filePath, content });
+  }
+  return writes;
+}
+
 /**
  * Compute the file content a Write/Edit/MultiEdit is about to produce. Edits are applied
  * to the CURRENT on-disk file so the gate judges the real post-edit state, not the edit
@@ -237,7 +304,27 @@ function runHook(gate, config, args, ts) {
     return;
   }
 
+  runHookPayload(payload, gate, config, args, ts);
+}
+
+function runHookPayload(payload, gate, config, args, ts) {
   const { toolName, toolInput, grokStyle } = normalizeHookPayload(payload);
+  if (toolName === 'ApplyPatch') {
+    const patch = toolInput.patch ?? toolInput.input ?? toolInput.content;
+    for (const write of codexPatchWrites(patch, args.root)) {
+      runHookPayload(
+        {
+          tool_name: 'Write',
+          tool_input: { file_path: write.filePath, content: write.content },
+        },
+        gate,
+        config,
+        args,
+        ts
+      );
+    }
+    return;
+  }
   const filePath = toolInput.file_path;
   if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) return;
   if (typeof filePath !== 'string' || !SOURCE_FILE.test(filePath) || filePath.endsWith('.d.ts')) {
@@ -298,6 +385,11 @@ function runHook(gate, config, args, ts) {
     return false;
   });
   if (newViolations.length === 0) return;
+  const normalizedRel = rel.split(path.sep).join('/');
+  const adapterResult = createAdapterResult({
+    valid: false,
+    violations: newViolations.map((violation) => ({ ...violation, file: normalizedRel })),
+  });
 
   const lines = newViolations.map(
     (violation) =>
@@ -339,9 +431,10 @@ function runHook(gate, config, args, ts) {
   if (repair) {
     // Structured envelope for any host that can re-inject. Never writes the file.
     const repairPayload = {
+      ...adapterResult,
       mode: 'repair',
       decision: 'deny',
-      filePath: rel.split(path.sep).join('/'),
+      filePath: normalizedRel,
       ...(layer ? { layer } : {}),
       ...(autoPatch
         ? {
@@ -367,6 +460,7 @@ function runHook(gate, config, args, ts) {
       JSON.stringify({
         decision: 'deny',
         reason: message,
+        analysis: adapterResult,
         ...(repair && autoPatch ? { autoPatch } : {}),
         ...(repair ? { repair: true } : {}),
       }) + '\n'
@@ -616,6 +710,7 @@ async function main() {
         },
         required: ['source'],
       },
+      outputSchema: ARK_ANALYSIS_RESULT_SCHEMA,
     },
     {
       name: 'ark_check',
@@ -638,6 +733,7 @@ async function main() {
           },
         },
       },
+      outputSchema: ARK_ANALYSIS_RESULT_SCHEMA,
     },
     {
       name: 'ark_coverage',
@@ -826,12 +922,17 @@ async function main() {
       validate: validateOnce,
       resolveTargetAbs: resolveImportFileAbs,
     });
+    const adapterResult = createAdapterResult({
+      valid: result.valid,
+      violations: result.violations,
+    });
     return {
       content: [
         {
           type: 'text',
           text: JSON.stringify(
             {
+              ...adapterResult,
               valid: result.valid,
               violations: result.violations,
               ...(result.autoPatch ? { autoPatch: result.autoPatch } : {}),
@@ -842,6 +943,7 @@ async function main() {
           ),
         },
       ],
+      structuredContent: adapterResult,
       isError: !result.valid,
     };
   }
@@ -868,6 +970,11 @@ async function main() {
     }
     return {
       content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+      structuredContent: {
+        schemaVersion: data.schemaVersion,
+        valid: data.valid,
+        diagnostics: data.diagnostics,
+      },
       isError: data.ok === false,
     };
   }