arkgate 2.13.0 → 3.0.0

package/docs/agent-guide.md

@@ -25,10 +25,13 @@ Each of the twelve archetypes (`crud-product`, `api-backend`, `frontend-surface`
 - plain-language analogy and anti-patterns,
 - optional book references for depth only.
 
-Scoring is **deterministic**: repo shape signals (workspaces, UI dirs, API surface,
-persistence, jobs, workflows, CLI `bin`, source-file count, …) are matched against the
-playbook. Framework packages may appear as secondary `toolHints` in JSON output — never as
-the primary archetype id.
+Scoring is **deterministic** and source/graph-first. Ark discovers package units and roots from
+workspace manifests, `tsconfig`/`jsconfig` references, package exports and entrypoints, plus
+conventional `src`/`source` directories. Runtime and peer dependencies contribute framework
+signals; dev-only dependencies are reported but do not determine the application shape. Docs,
+examples, and test packages are reported separately and excluded from root-product inference.
+Framework packages may appear as secondary `toolHints` in JSON output — never as the primary
+archetype id.
 
 All playbook labels, analogies, anti-patterns, and `--recommend` prose are **English**
 (`locale: "en"` in the playbook). Agents should present them as-is unless a future locale
@@ -43,7 +46,10 @@ npx ark-check --recommend --json
 
 `--recommend` does not require `ark.config.json`. It exits `0` and prints a progressive
 adoption plan: archetype id, preset, `confidence`, `runnerUp`, `why` (shape signals),
+structured positive/negative `evidence`, discovered `signals.packageUnits`,
 `adoptInOrder.phase1`, `firstCommand` (`ark init --archetype …`), and `checkCommand`.
+When the top two shapes are close or projected governed coverage is below 90%, JSON sets
+`requiresConfirmation: true` and explains why in `confirmationReasons`.
 
 Human output highlights phase-1 layers and the analogy; JSON is the stable contract for
 MCP `ark_recommend` and the `/ark-architect` skill.
@@ -51,7 +57,7 @@ MCP `ark_recommend` and the `/ark-architect` skill.
 ### Terminal onboarding (Phase B)
 
 ```bash
-npx ark start --yes                             # preferred: shape → contract → **day-zero origin** → gates → plan
+npx ark start --yes                             # preferred: shape → compact contract → active host → CI → plan
 npx ark init --archetype crud-product --yes   # non-interactive: shape → preset → origin → gates
 npx ark init                                    # TTY wizard: pick application shape (1–8), not a framework
 npx ark-check --doctor                          # includes "New here?" when coverage is low or config is fresh
@@ -59,14 +65,20 @@ npx ark-check --report beginner.html --beginner # simplified HTML for enthusiast
 npx ark-check --watch                           # debounced re-check when governed files change
 ```
 
-**Day-zero origin (2.12+):** as soon as `ark.config.json` exists, `ark start` / `ark init`
-freeze `.ark/reports/origin.*` **before** writing agent docs, skills, or CI templates.
-Later `--report` shows evolution vs that snapshot. Do not `--reset-origin` unless the user
-explicitly wants a new baseline.
+**Day-zero origin (2.12+):** `ark init` freezes `.ark/reports/origin.*` before writing agent
+docs or CI templates. Compact `ark start` keeps first-run setup under five project files and
+25 KB;
+run `ark-check --report ark-report.html` explicitly when you want to establish an origin/evolution
+baseline. Do not `--reset-origin` unless the user explicitly wants a new baseline.
 
-**Default agent co-pilot:** `/ark-autopilot` (explore-first, dual plan A remediation + B
-pattern bets). Recon without applying: `/ark-explore`. Never treat empty `--plan` as
-“architecture healthy” without the explore pass.
+To remove a compact host integration, preview `ark start --remove-host <host>` and add `--apply`
+only after review. Ark removes only its exact compact artifacts, leaves customized files untouched
+as unresolved decisions, and restores the integration with `ark start --tools <host> --apply`.
+
+**Full-skill agent co-pilot:** after explicitly installing the `/ark-*` pack, use
+`/ark-autopilot` (explore-first, dual plan A remediation + B pattern bets). Recon without
+applying: `/ark-explore`. The default compact router uses MCP/CLI directly. Never treat empty
+`--plan` as “architecture healthy” without the explore pass.
 
 `ark init --archetype <id>` maps playbook ids to named presets (`hexagonal`, `layered`,
 `feature-sliced`, `monorepo`). With `--yes` and no archetype, Ark auto-selects from
@@ -211,7 +223,7 @@ directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`
 
 ## Supported agent hosts
 
-Wire write-gate + MCP + `/ark-*` skills with:
+Wire write-gate + MCP + the full `/ark-*` skill set with:
 
 ```bash
 npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
@@ -239,7 +251,7 @@ projections, metadata, workflow engine, and 11-layer architecture profile:
 ```ts
 import {
   createStrictArkKernel,
-} from 'arkgate/runtime';
+} from '@arkgate/runtime';
 
 const ark = createStrictArkKernel();
 // ... define intents, event contracts, metadata, projections, and workflows through ark.*
@@ -249,8 +261,8 @@ const contract = ark.manifest().toJSON();
 // contract.observability, projections
 ```
 
-Use `arkgate/runtime` when evaluating the experimental kernel (root `arkgate` still re-exports
-for compatibility). Package surface policy: [package-surface.md](package-surface.md).
+Use `@arkgate/runtime` only when evaluating the experimental kernel. The stable `arkgate` gate
+package contains no runtime implementation. Package surface policy: [package-surface.md](package-surface.md).
 
 Agents should read `contract` and `ark.observability.report()` before generating or modifying code.
 

package/docs/ai-gates.md

@@ -3,7 +3,8 @@
 **ArkGate** (`arkgate`) is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
 On Claude Code and Grok Build, an installed and trusted PreToolUse hook can block matched writes
 before they land on disk. Cursor and OpenAI Codex use advisory MCP validation at write time; CI is
-their hard repository check. See the
+their hard repository check. Codex 0.123+ dispatches hooks for its native `apply_patch` handler,
+but Code Mode hosts can execute deferred nested writes without that project hook event. See the
 [canonical host support matrix](../README.md#host-enforcement-support) before installing.
 
 Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
@@ -21,6 +22,11 @@ npx arkgate start
 # or: npx ark init
 ```
 
+`ark start` asks for the active agent on a TTY (or detects it otherwise) and applies a compact
+router setup: at most five project files and no `package.json` change unless you pass `--install`.
+Use `--tools <host>` to select the host explicitly. The broader command below remains the explicit
+way to install the full per-host `/ark-*` skill inventory.
+
 For non-interactive defaults, use:
 
 ```bash
@@ -35,7 +41,7 @@ npx arkgate-check --install-agent-gates
 ```
 
 The command writes templates for `.mcp.json`, Claude hooks, Cursor MCP/rules,
-GitHub Actions, `AGENTS.md`, a Codex TOML snippet under `docs/`, and (when
+GitHub Actions, `AGENTS.md`, Codex `.codex/hooks.json` plus a TOML snippet under `docs/`, and (when
 selected) Grok Build project files under `.grok/`. It skips existing files unless
 you pass `--force`, so review and commit only the templates that match your project.
 
@@ -89,7 +95,7 @@ When no mechanical-safe patch applies, `autoPatch` is `null` (host still re-reas
 `ark_prepare_write` / judgment). Grok deny JSON also includes `autoPatch` + `"repair": true`
 when repair mode is on.
 
-`--install-agent-gates` writes Claude/Grok PreToolUse commands with `--hook-repair` enabled.
+`--install-agent-gates` writes Claude/Grok/Codex PreToolUse commands with `--hook-repair` enabled.
 Reject-only installs: drop `--hook-repair` (or unset `ARK_HOOK_REPAIR`).
 
 Add to your project's `.claude/settings.json`:
@@ -231,6 +237,23 @@ through. It blocks the merge only when that status is required by repository pol
 
 Recommended for Ark projects.
 
+Codex 0.123+ dispatches `PreToolUse` for the native `apply_patch` handler. Ark installs
+`.codex/hooks.json` with `ApplyPatch|apply_patch|Write|Edit|MultiEdit` aliases and reconstructs
+every added or updated file in a multi-file patch before allowing it. The hook root uses
+`${CODEX_PROJECT_DIR:-${PWD:-.}}`; it must not use Claude-only `CLAUDE_PROJECT_DIR`.
+
+This hook is best-effort in Codex Code Mode: some hosts execute deferred nested `apply_patch`
+calls without dispatching the project `PreToolUse` event. ArkGate therefore does not treat the
+presence of `.codex/hooks.json` as a universal hard-write guarantee; MCP remains advisory and the
+required CI status is the hard repository boundary.
+
+```bash
+npx ark-check --install-agent-gates --tools codex
+```
+
+The generated hook includes `--hook-repair`, so a rejected patch carries the same structured
+repair envelope as Claude and Grok. Codex still needs hook trust enabled for the project.
+
 Unlike Claude/Cursor (project-local MCP files), **Codex loads MCP servers only from
 `$CODEX_HOME/config.toml`** (default `~/.codex/config.toml`) — a **global** home file.
 Hand-editing with relative `--root .` is wrong: Codex does not use the project as cwd, so
@@ -253,9 +276,8 @@ args = ["arkgate-mcp", "--root", "/absolute/path/to/project", "--config", "/abso
 Then **restart Codex** — it does not hot-load MCP servers. Expect resource `ark://manifest`
 and tools `validate_code`, `ark_check`, `ark_coverage`, `ark_place`.
 
-Same model as Cursor for enforcement: advisory MCP for discovery/validation and `ark-check` as
-the hard CI check. It becomes a merge block only when the status is required. Register the MCP
-server as soon as the repo is adopted.
+Codex uses the best-effort local patch hook plus advisory MCP for discovery/validation and
+`ark-check` as the hard merge backstop. Register all three as soon as the repo is adopted.
 
 ### Multi-project Codex (home config last-wins)
 
@@ -357,10 +379,11 @@ write). Keep `ark-check` in CI and require its status when it must block merges.
 
 ## Any other agent runtime with shell hooks
 
-If your runtime can run a shell command before file writes and pass the tool payload on stdin (Claude Code or Grok PreToolUse contracts), `ark-mcp --hook` works as-is. The contract:
+If your runtime can run a shell command before file writes and pass the tool payload on stdin, `ark-mcp --hook` works as-is. The contract:
 
 - stdin (Claude): JSON `{ "tool_name": "Write|Edit|MultiEdit", "tool_input": { "file_path": ..., ... } }`
 - stdin (Grok): JSON `{ "toolName": "write|search_replace|…", "toolInput": { "file_path": ..., ... } }` (also accepts Claude names)
+- stdin (Codex): JSON `{ "tool_name": "apply_patch", "tool_input": { "patch": "*** Begin Patch…" } }`
 - exit `0` → allow; exit `2` → block, human-readable violations on stderr
 - Grok payloads also get `{ "decision": "deny", "reason": "…" }` on stdout when blocked
 - plumbing problems (no stdin, non-source files, files outside `--root`) never block

package/docs/migrate-from-ark-runtime-kernel.md

@@ -134,11 +134,10 @@ require adopting them. Static CLI/MCP enforcement remains the supported product
 
 ```diff
 - import { createStrictArkKernelFromConfig } from 'ark-runtime-kernel';
-+ import { createStrictArkKernelFromConfig } from 'arkgate/runtime';
-  // root `arkgate` still re-exports kernel symbols this major (compat)
++ import { createStrictArkKernelFromConfig } from '@arkgate/runtime';
 
 - import { ArkModule } from 'ark-runtime-kernel/nestjs';
-+ import { ArkModule } from 'arkgate/nestjs';
++ import { ArkModule } from '@arkgate/runtime/nestjs';
 
 - import ark from 'ark-runtime-kernel/eslint';
 + import ark from 'arkgate/eslint';

package/docs/package-surface.md

@@ -17,6 +17,7 @@ This document is the consumer contract for **what is stable** vs **what is exper
 | **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
 | **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
 | **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. |
+| **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Versioned JSON Schema; committed v1 compatibility fixture protects rule, severity, location, and evidence fields. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
 | **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. explore dual-plan seed, day-zero origin order). |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
@@ -33,9 +34,9 @@ product claims**. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **Runtime kernel** | **`arkgate/runtime`** (preferred) | Experimental event bus, intents, policies, sagas, outbox, projections, and strict helpers. Not required for architecture enforcement. Built-in stores are **InMemory reference only** (not production durability) — see [production-hardening.md](./production-hardening.md). |
-| **Root package barrel** | `arkgate` | Still re-exports the experimental runtime kernel for **compatibility**. Prefer `arkgate/runtime` when evaluating it. Root may be thinned in a future **major**. |
-| **NestJS adapter** | `arkgate/nestjs` | Experimental optional peer `@nestjs/common`; wires a kernel into Nest DI. |
+| **Runtime kernel** | **`@arkgate/runtime`** | Separate 0.x package, published under the `experimental` tag. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Built-in stores are **InMemory reference only**. |
+| **Runtime migration shim** | `arkgate/runtime` | Deprecated forwarder to `@arkgate/runtime`; contains no implementation and is removed in ArkGate 4. |
+| **NestJS adapter** | `@arkgate/runtime/nestjs` | Experimental optional peer `@nestjs/common`; the deprecated `arkgate/nestjs` path forwards here. |
 
 ---
 
@@ -43,16 +44,10 @@ product claims**. Static architecture enforcement does not depend on them.
 
 ```ts
 // Preferred path when evaluating the experimental runtime kernel
-import {
-  createStrictArkKernel,
-  createStrictArkKernelFromConfig,
-} from 'arkgate/runtime';
-
-// Still works this major (compat; not preferred for new code)
-import { createStrictArkKernel } from 'arkgate';
+import { createStrictArkKernel, createStrictArkKernelFromConfig } from '@arkgate/runtime';
 
 // Nest adapter
-import { ArkModule, InjectArk } from 'arkgate/nestjs';
+import { ArkModule, InjectArk } from '@arkgate/runtime/nestjs';
 ```
 
 See [production-hardening.md](./production-hardening.md) for requirements an eventual
@@ -76,8 +71,8 @@ production deployment would need to satisfy; it is not a readiness certification
 | Break CLI JSON field, MCP tool rename, or required `ark.config` field | **major** |
 | New optional config field, new CLI flag, additive JSON | **minor** |
 | Bugfix with no contract change | **patch** |
-| Prefer `arkgate/runtime` over root (docs only; root still exports) | **patch/minor** |
-| Remove root kernel re-exports | **major** (with migration notes) |
+| Additive experimental runtime API | `@arkgate/runtime` prerelease/minor |
+| Remove deprecated `arkgate/runtime` forwarding shim | ArkGate **4.0** |
 
 ---
 

package/docs/production-hardening.md

@@ -1,7 +1,7 @@
 # Production Hardening
 
 The optional runtime kernel is currently **experimental**. This page is a requirements checklist
-for teams evaluating **`arkgate/runtime`**, not a claim that the runtime is production-ready.
+for teams evaluating **`@arkgate/runtime`**, not a claim that the runtime is production-ready.
 Static ArkGate adoption does not require it. See [package-surface.md](package-surface.md).
 
 ## Durability stance (R9)
@@ -19,11 +19,11 @@ stores that match their durability, ordering, retention, and operational require
 These defaults do not survive process restarts:
 
 - `InMemoryAuditStore`
-- `InMemoryOutboxStore`
+- `InMemoryEventBuffer` (`InMemoryOutboxStore` is a deprecated compatibility alias)
 - `InMemoryReadModelStore`
 - `InMemoryWorkflowStore`
 
-Use them only when losing state is acceptable. JSDoc on `OutboxStore`, `AuditStore`,
+Use them only when losing state is acceptable. JSDoc on `EventBufferStore`, `AuditStore`,
 `ReadModelStore`, and `WorkflowStore` restates this stance at the type level.
 
 ## Production Store Checklist
@@ -55,12 +55,25 @@ completed steps are compensated when handlers exist, and the workflow ends faile
 effects and compensations must therefore be idempotent, and audit/snapshot stores must be
 operational dependencies rather than best-effort telemetry.
 
+### Required recovery semantics (not implemented by built-ins)
+
+| Contract | Required definition before a production claim |
+|----------|-----------------------------------------------|
+| Workflow recovery | Persist the last committed step and effect id; restart resumes only from that checkpoint and never assumes an in-flight effect failed or succeeded without reconciliation. |
+| Optimistic versioning | Every snapshot write carries the previously read version; conflicting writes fail without overwriting and the caller reloads before retrying. |
+| Dispatcher leases | A claim records owner and expiry atomically; only the owner may acknowledge it, and takeover is allowed only after expiry. |
+| Idempotent delivery | Every message/effect has a stable idempotency key retained for the full retry window; duplicate attempts return the prior outcome without repeating the effect. |
+| Atomic handoff | Application state and dispatch record commit in one transaction. Without this guarantee the API must be called an event buffer, not an outbox. |
+
+The experimental package supplies none of these persistence guarantees. Fault/restart matrices
+must cover crashes before and after every transaction, effect, checkpoint, lease, and acknowledgement.
+
 ## Interface Targets
 
 | Concern | Interface |
 |---------|-----------|
 | Audit records | `AuditStore` |
-| Outbox dispatch handoff | `OutboxStore` |
+| Non-atomic dispatch buffer | `EventBufferStore` |
 | Projection state | `ReadModelStore` |
 | Workflow snapshots | `WorkflowStore` |
 

package/docs/typescript-support.md

@@ -131,6 +131,33 @@ node scripts/ts-compat-matrix.mjs 7.0.2
 | Gate uses native Go typechecker API exclusively | Not required; future if 7.1+ exposes a stable Node API we adopt |
 | User tsconfigs with removed options still “just work” | User must migrate tsconfig (TS6/7); Ark reports resolve/parse failures clearly |
 
+## Static-analysis soundness envelope
+
+ArkGate uses the TypeScript compiler API to extract dependency and ambient-capability facts. The
+same Kernel implementation feeds the library, CLI, MCP write gate, and AICodeGate bundle.
+
+Dependency forms enforced when their module specifier is a string literal:
+
+- ESM `import`, `import type`, side-effect imports, and `export ... from` / `export type ... from`;
+- TypeScript `import x = require("...")`;
+- unshadowed CommonJS `require("...")`;
+- dynamic `import("...")`.
+
+Non-literal `import(expr)` and unshadowed `require(expr)` are reported as unresolved. They are
+advisory by default, fail with `--strict-config`, and may be reviewed at file granularity through
+`dynamicImportAllowlist`. A locally declared `require` function is not treated as CommonJS.
+
+Forbidden capabilities are resolved with single-file TypeScript symbols. Local variables,
+parameters, and imports shadow ambient names; aliases such as `const Clock = Date`, explicit
+`globalThis`, static bracket access, and object destructuring remain detectable. Resolution of
+module paths then uses the nearest tsconfig/jsconfig compiler options, including path aliases,
+project-local packages, workspaces, and symlinked workspace entries.
+
+ArkGate intentionally does not claim soundness for runtime-generated module names, `eval`, custom
+loader functions, proxy-based globals, dynamically computed property keys, or aliases mutated
+after declaration. Those constructs must remain absent from governed pure layers or be handled by
+an explicit project policy. Every newly discovered bypass is minimized into the adversarial corpus.
+
 ## Future (7.1+ programmatic API)
 
 When Microsoft ships a stable Node API for native TypeScript 7.1+:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.13.0",
+  "version": "3.0.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -13,9 +13,9 @@
       "require": "./dist/index.cjs"
     },
     "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js",
-      "require": "./dist/runtime/index.cjs"
+      "types": "./compat/runtime.d.ts",
+      "import": "./compat/runtime.js",
+      "require": "./compat/runtime.cjs"
     },
     "./eslint": {
       "types": "./dist/eslint/index.d.ts",
@@ -24,10 +24,12 @@
     },
     "./schema": "./schemas/ark.config.schema.json",
     "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
+    "./schema/analysis-result": "./schemas/ark.analysis-result.schema.json",
+    "./schema/ark.analysis-result.schema.json": "./schemas/ark.analysis-result.schema.json",
     "./nestjs": {
-      "types": "./dist/nestjs/index.d.ts",
-      "import": "./dist/nestjs/index.js",
-      "require": "./dist/nestjs/index.cjs"
+      "types": "./compat/nestjs.d.ts",
+      "import": "./compat/nestjs.js",
+      "require": "./compat/nestjs.cjs"
     },
     "./package.json": "./package.json"
   },
@@ -43,6 +45,7 @@
   "files": [
     "bin",
     "bin/lib",
+    "compat",
     "dist",
     "schemas",
     "docs/agent-guide.md",
@@ -67,13 +70,23 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "node scripts/clean-gate-dist.mjs && tsup",
+    "build:runtime": "tsup --config packages/runtime/tsup.config.ts",
     "dev": "tsup --watch",
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "npm run build && vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
-    "test:mutation": "npm run build && stryker run",
+    "test:mutation": "npm run build && stryker run && npm run check:mutation-groups",
+    "check:mutation-groups": "node scripts/check-mutation-groups.mjs",
+    "test:property": "vitest run tests/property",
+    "test:fuzz": "npm run build && ARK_FUZZ_CAMPAIGN=pr vitest run tests/fuzz",
+    "test:fuzz:extended": "npm run build && ARK_FUZZ_CAMPAIGN=extended vitest run tests/fuzz",
     "test:confidence": "npm run test:coverage && npm run test:mutation",
+    "test:adapter-parity": "vitest run tests/unit/adapters/adapterParity.test.ts tests/unit/eslint/parity.test.ts",
+    "test:onboarding-matrix": "for shard in library/small library/medium library/large api/small api/medium api/large frontend/small frontend/medium frontend/large monorepo/small monorepo/medium monorepo/large; do O04_SHARD=$shard npm run test:onboarding-matrix:shard; done",
+    "test:onboarding-matrix:shard": "vitest run tests/unit/static-check/o04OnboardingMatrix.test.ts",
+    "test:gate-only": "vitest run tests/unit/static-check/arkCheck.test.ts tests/unit/mcp/arkMcp.test.ts tests/unit/eslint",
+    "test:package-isolation": "node scripts/smoke-package-isolation.mjs",
     "typecheck": "tsc --noEmit",
     "security:audit": "npm audit --omit=dev --audit-level=high",
     "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict",
@@ -82,6 +95,8 @@
     "check:layer-match": "node scripts/generate-layer-match.mjs --check",
     "generate:cli-pure": "node scripts/generate-cli-pure.mjs",
     "check:cli-pure": "node scripts/generate-cli-pure.mjs --check",
+    "generate:analysis-engine": "node scripts/generate-analysis-engine.mjs",
+    "check:analysis-engine": "node scripts/generate-analysis-engine.mjs --check",
     "check:gallery-starters": "node scripts/check-gallery-starters.mjs",
     "generate:gallery-starters": "node scripts/check-gallery-starters.mjs --write",
     "test:ts-compat": "node scripts/ts-compat-matrix.mjs 5.9.3 && node scripts/ts-compat-matrix.mjs 6.0.3 && node scripts/ts-compat-matrix.mjs 7.0.2",
@@ -89,9 +104,15 @@
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "eval:loop-cost": "node eval/loop-cost-run.mjs",
+    "eval:adoption": "node eval/adoption-run.mjs",
+    "test:adoption-harness": "vitest run tests/unit/eval/adoptionHarness.test.ts",
     "bench:scale": "node scripts/ark-scale-bench.mjs",
+    "test:scale-bench": "npm run build && vitest run tests/unit/scripts/arkScaleBench.test.ts",
     "check:module-budgets": "node scripts/check-module-budgets.mjs",
     "check:package-files": "node scripts/verify-package-files.mjs",
+    "check:release-artifacts": "node scripts/verify-release-artifacts.mjs",
+    "test:release-artifacts": "vitest run tests/unit/scripts/verifyReleaseArtifacts.test.ts",
+    "audit:beta-exit": "node scripts/beta-exit-audit.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"
@@ -100,11 +121,11 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@nestjs/common": ">=9",
+    "@arkgate/runtime": ">=0.1.0-experimental.0 <1",
     "typescript": ">=5.0.0 <8"
   },
   "peerDependenciesMeta": {
-    "@nestjs/common": {
+    "@arkgate/runtime": {
       "optional": true
     },
     "typescript": {
@@ -127,6 +148,7 @@
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^20.14.0",
     "@vitest/coverage-v8": "^3.2.6",
+    "fast-check": "^4.9.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",

package/schemas/ark.analysis-result.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@2/schemas/ark.analysis-result.schema.json",
+  "title": "ArkGate analysis result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "valid",
+    "diagnostics"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "valid": {
+      "type": "boolean"
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "ruleId",
+          "severity",
+          "message",
+          "location",
+          "evidence"
+        ],
+        "properties": {
+          "ruleId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "severity": {
+            "enum": [
+              "error",
+              "warning"
+            ]
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1
+          },
+          "location": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "file",
+              "line",
+              "column"
+            ],
+            "properties": {
+              "file": {
+                "type": "string",
+                "minLength": 1
+              },
+              "line": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "column": {
+                "type": "integer",
+                "minimum": 1
+              }
+            }
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "target": {
+                "type": "string"
+              },
+              "fromLayer": {
+                "type": "string"
+              },
+              "toLayer": {
+                "type": "string"
+              },
+              "typeOnly": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.13.0",
+  "version": "3.0.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.13.0",
+      "version": "3.0.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-architect.md

@@ -44,8 +44,9 @@ the same files or weaken the gate.
 
 1. **Detect the shape** — call MCP tool **`ark_recommend`** (or run
    `ark-check --recommend --json`). Read `archetype`, `preset`, `confidence`,
-   `adoptInOrder.phase1`, `analogy`, and `why`. Ask at most **two** questions only
-   if `confidence < 0.5`:
+   `adoptInOrder.phase1`, `analogy`, `why`, `evidence`, and `requiresConfirmation`.
+   Ask at most **two** questions only if `requiresConfirmation` is true (or for compatibility
+   with older ArkGate output, `confidence < 0.5`):
    - "Will this app save data between sessions?"
    - "Is this one app or several in one repository?"
 

package/dist/configContract-iBLxx5Tz.d.cts

@@ -1,53 +0,0 @@
-/**
- * Canonical, pure contract for ark.config.json.
- *
- * Tooling adapters own filesystem I/O; this module owns JSON parsing, deterministic
- * migration, defaults, validation, diagnostics, and the published JSON Schema.
- * The standalone CLI artifact is generated into bin/lib/config-contract.mjs.
- */
-declare const ARK_CONFIG_SCHEMA_VERSION: "1.0";
-type ArkConfigCyclePolicy = 'strict' | 'soft' | 'framework-soft' | 'off';
-type ArkConfigLayer = {
-    name: string;
-    patterns: string[];
-    exclude?: string[];
-    intentPrefixes?: string[];
-    description?: string;
-    forbiddenGlobals?: string[];
-    mayImportInfrastructure?: boolean;
-    optional?: boolean;
-};
-type ArkConfigRule = {
-    from: string;
-    to: string;
-    allowed: boolean;
-    message?: string;
-    peerIsolation?: boolean;
-    sliceFolders?: string[];
-};
-type ArkConfigSafety = {
-    maxTsSuppressions?: number;
-    maxAnyCasts?: number;
-    allowInMemory?: boolean;
-    allowDisabledPeerIsolation?: boolean;
-};
-type ArkConfig = {
-    $schema: string;
-    schemaVersion: typeof ARK_CONFIG_SCHEMA_VERSION;
-    name?: string;
-    include: string[];
-    exclude?: string[];
-    excludeGenerated?: boolean;
-    frameworkOverlay?: string;
-    layers: ArkConfigLayer[];
-    rules: ArkConfigRule[];
-    cyclePolicy?: ArkConfigCyclePolicy;
-    dynamicImportAllowlist?: string[];
-    safety?: ArkConfigSafety;
-};
-type ArkConfigLoadResult = {
-    config: ArkConfig;
-    migratedFrom: 'unversioned' | null;
-};
-
-export type { ArkConfig as A, ArkConfigRule as a, ArkConfigLayer as b, ArkConfigLoadResult as c };