ark-runtime-kernel 1.0.0 → 1.1.0

package/README.md

@@ -2,126 +2,147 @@
 
 # 🏛️ Ark — Architectural Runtime Kernel
 
-**Make your architecture a machine-readable, enforceable contract** —<br/>
-respected by AI agents at write time, CI at merge time, and the runtime itself.
+**Stop AI agents (and humans) from quietly breaking your architecture.**<br/>
+One machine-readable contract — enforced at write time, merge time, and (optionally) runtime.
 
-[![CI](https://github.com/pedroknigge/ark/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/ark/actions/workflows/ci.yml)
+[![CI](https://github.com/pedroknigge/ark-runtime-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/ark-runtime-kernel/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/ark-runtime-kernel?color=cb3837&label=npm)](https://www.npmjs.com/package/ark-runtime-kernel)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js)
 ![TypeScript](https://img.shields.io/badge/TypeScript-first-3178c6?logo=typescript&logoColor=white)
 ![Zero deps](https://img.shields.io/badge/dependencies-0-success)
 
-**Zero runtime dependencies** · TypeScript-first · Hexagonal + Event-Driven + DDD governance kernel
-
-[Quick Start](#60-second-setup) · [The Three Gates](#the-three-gates-visual) · [AI Write Gate](#ai-write-path-gate-ark-mcp) · [CI Gate](#ark-check--the-ci-gate) · [Docs](#documentation)
+[2-Minute Setup](#2-minute-setup) · [Why Ark](#why-ark-and-not-just-a-linter) · [AI Write Gate](#the-ai-write-gate) · [CI Gate](#ark-check--the-ci-gate) · [Runtime Kernel](#the-runtime-kernel-opt-in) · [Docs](#documentation)
 
 </div>
 
 ---
 
-## The Three Gates (Visual)
-
-```mermaid
-flowchart LR
-    A["✍️  Write Time<br/>AI Agents"] -->|ark-mcp + validate_code| B["🚫 Blocked"]
-    A -->|valid| C["💾 Disk"]
+This is what happens when an agent tries to import a persistence adapter into your domain layer with Ark's write gate active:
 
-    D["🔀 Merge Time<br/>CI / PRs"] -->|ark-check| E["❌ Fail"]
-    D -->|valid| F["✅ Merge"]
+![An AI agent is blocked from importing a persistence adapter into the domain layer, then self-corrects by defining a port](docs/assets/ark-write-gate.svg)
 
-    G["⚙️  Runtime<br/>In-process"] -->|createArkKernel<br/>strict defaults| H["🛡️ Enforce<br/>contracts + layers"]
-    G --> I["📊 Observability<br/>+ Manifest"]
-
-    style A fill:#e0f2fe,color:#0c4a6e
-    style D fill:#fef3c7,color:#92400e
-    style G fill:#dcfce7,color:#166534
-```
-
-**One config. Three enforcement moments.**
-
-| Gate         | Tool          | When it runs                  | What it enforces                              |
-|--------------|---------------|-------------------------------|-----------------------------------------------|
-| **Write**    | `ark-mcp`     | Agent PreToolUse (Write/Edit) | Layer rules, unknown intents, forbidden patterns |
-| **Merge**    | `ark-check`   | CI (GitHub Actions etc.)      | Cross-layer imports + intent references (real TS resolver) |
-| **Runtime**  | `createArkKernel()` | Running process         | Intent registry, event contracts, observed layer flow, policies |
+The agent doesn't just get blocked — it gets the violation as feedback, reads the architecture contract, and **fixes its own approach**. No review round-trip.
 
----
+## 2-Minute Setup
 
-## 60-Second Setup
+No code changes. No new runtime. Just a config and a CI line.
 
 ```bash
 npm install -D ark-runtime-kernel typescript
+npx ark-check --init          # infers layers from your existing folders → ark.config.json
+npx ark-check                 # done: cross-layer imports now fail the check
 ```
 
-### 1. Bootstrap your config from reality
+Adopting on a codebase that already has violations? Freeze them and ratchet down:
 
 ```bash
-npx ark-check --init          # detects your folders and writes ark.config.json
+npx ark-check --update-baseline   # writes .ark-baseline.json — commit it
+npx ark-check --baseline          # only NEW violations fail from now on
 ```
 
-### 2. Gate CI
+Then gate your agents (Claude Code shown; [Cursor / Codex / others](docs/ai-gates.md)):
 
-```bash
-npx ark-check --root . --config ark.config.json --strict-config
+```json
+// .claude/settings.json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Write|Edit|MultiEdit",
+      "hooks": [{ "type": "command",
+        "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json" }]
+    }]
+  }
+}
 ```
 
-### 3. Gate AI agents (write path)
+> The same `ark.config.json` powers every gate.
+
+## Why Ark (and not just a linter)?
+
+If you only need import-boundary linting in CI, [dependency-cruiser](https://github.com/sverweij/dependency-cruiser), [eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries), and Nx module boundaries are solid tools. Ark's reason to exist is the **write-time, agent-native half** they don't cover:
+
+|                                         | Ark | dependency-cruiser | eslint-plugin-boundaries | Nx boundaries |
+|-----------------------------------------|:---:|:---:|:---:|:---:|
+| Cross-layer import checks in CI         | ✅ (TS resolver) | ✅ | ✅ | ✅ |
+| Blocks AI agents **before** code lands (MCP + hook) | ✅ | ❌ | ❌ | ❌ |
+| Machine-readable contract for agents (`ark://manifest`) | ✅ | ❌ | ❌ | ❌ |
+| Event/intent governance (who may publish what) | ✅ | ❌ | ❌ | ❌ |
+| Baseline ratchet for existing codebases | ✅ | ❌ | ➖ (via ESLint) | ❌ |
+| Optional runtime enforcement            | ✅ | ❌ | ❌ | ❌ |
+| Runtime dependencies                    | 0 | many | many | Nx |
+
+**One config. Three enforcement moments:**
+
+| Gate         | Tool          | When it runs                  | What it enforces                              |
+|--------------|---------------|-------------------------------|-----------------------------------------------|
+| **Write**    | `ark-mcp`     | Agent PreToolUse (Write/Edit) | Layer rules, unknown intents, forbidden patterns |
+| **Merge**    | `ark-check`   | CI (GitHub Actions etc.)      | Cross-layer imports + intent references (real TS resolver) |
+| **Runtime**  | `createArkKernel()` | Running process (opt-in) | Intent registry, event contracts, observed layer flow, policies |
+
+## The AI Write Gate
+
+`ark-mcp` is a zero-dependency MCP server + one-shot hook:
+
+- **`ark-mcp --hook`** — PreToolUse gate: computes the **post-edit** file content, validates it against your layers, exits 2 with the violations when the write must be blocked. The agent self-corrects.
+- **`validate_code` tool** — on-demand validation of a snippet, for runtimes without hooks.
+- **`ark://manifest` resource** — the architecture as JSON, so agents read the rules *before* generating code instead of learning by rejection.
+
+Copy-paste setups for **Claude Code, Cursor, and OpenAI Codex**: [docs/ai-gates.md](docs/ai-gates.md).
+
+## `ark-check` — The CI Gate
 
 ```bash
-npx ark-mcp --root . --config ark.config.json
+npx ark-check --root . --config ark.config.json --strict-config   # fail on coverage gaps too
+npx ark-check --json                                              # machine-readable
+npx ark-check --baseline                                          # ratchet mode
 ```
 
-Bind `--hook` mode to your agent's `PreToolUse` for Write/Edit (see full docs below).
+**What it catches (via real TypeScript module resolution — path aliases included):**
 
-> The same `ark.config.json` powers all three gates.
-
----
+- Import/export violations (relative, aliases, packages, dynamic `import()`, `require`)
+- String intent references across forbidden layers
+- Raw `publish()` calls that bypass registered intent creators
+- Missing / mismatched publish `source` metadata
 
-## What Ark Actually Does
+Violations come with the layer edge, the resolved target, and a fix hint:
 
-Ark turns architecture from **diagrams + good intentions** into **executable contracts**.
+```
+✖ LAYER_IMPORT_VIOLATION  src/domain/order.ts:3
+  DomainModel → PersistenceAdapters  (src/adapters/persistence/pg-order-repository.ts)
+  DomainModel must not import PersistenceAdapters.
+  fix: Depend on a port/interface owned by an inner layer instead, or move this code.
+```
 
-### Core Capabilities
+### GitHub Action
 
-- **Intent Registry** — Semantic names (`Domain.Order.OrderPlaced`, `Application.PlaceOrder`) with declared produces/dependsOn relationships.
-- **Policy Engine** — Hard policies (throw) + soft policies (observe). Built-in clean-architecture matrix.
-- **Strict Event Bus** — Registered intents only, known sources, event contracts, add-only interceptors.
-- **Observed Layer Flow** — Runtime enforcement (`'hard' | 'soft' | 'off'`) of *actual* producer → event flows against your layer rules.
-- **Event Contracts** — Payload shape validation (including nested + enums).
-- **11-Layer Profile** — First-class support for proper Hexagonal/Event-Driven boundaries.
-- **Manifest** — `ark.manifest().toJSON()` → complete machine-readable contract for agents and tools.
-- **Observability & Drift** — Declared vs observed flow reports.
-- **Audit / Outbox / Projections / Workflow (Saga)** — Pluggable in-memory defaults + interfaces.
-- **Static + AI Gates** — `ark-check` (deep) + `ark-mcp` + ESLint plugin.
+```yaml
+- uses: pedroknigge/ark-runtime-kernel@main
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}   # comments violations on the PR
+```
 
-### Enforcement Scope (Be Honest With Yourself)
+Inputs: `root`, `config`, `strict-config`, `baseline`, `version`.
 
-**Hard at runtime (governed paths only):**
-- Unregistered intents / bad names
-- Unknown sources
-- Contract violations
-- Hard policy violations
-- Observed layer flow violations (when `hard`)
+### ESLint plugin (in-editor feedback)
 
-**CI (with ark-check):**
-- Cross-layer imports (real module resolution)
-- Intent string references across boundaries
-- Raw `publish()` calls
-- Missing `source` on strict publishes
+```js
+// eslint.config.js
+import ark from 'ark-runtime-kernel/eslint';
+export default [ark.configs.recommended];
+```
 
-**Everything else is out of scope** unless you route it through Ark or cover it with config + CI.
+Rules: `ark/no-domain-infra-imports`, `ark/no-raw-event-publish`, `ark/require-publish-source`.
 
----
+## The Runtime Kernel (opt-in)
 
-## Quick Start — Strict Kernel (Recommended)
+The gates above need **zero changes to your code**. When you also want *runtime* guarantees — registered intents only, payload contracts, observed producer→event layer flows — route your events through the kernel:
 
 ```ts
 import { createArkKernel } from 'ark-runtime-kernel';
 
-const ark = createArkKernel(); // or createStrictArkKernel()
+const ark = createArkKernel(); // strict defaults
 
-// 1. Define intents
 const OrderPlaced = ark.registry.define<
   'Domain.Order.OrderPlaced',
   { orderId: string; amount: number }
@@ -132,7 +153,8 @@ ark.registry.define<'Application.PlaceOrder', { orderId: string }>(
   { produces: ['Domain.Order.OrderPlaced'] }
 );
 
-// 2. Register contracts (optional but powerful)
+// Payload contracts: Ark's own schema format, or any Standard Schema
+// validator (zod, valibot, arktype) via `standardSchema`.
 ark.eventContracts.register({
   intent: 'Domain.Order.OrderPlaced',
   version: '1',
@@ -143,179 +165,60 @@ ark.eventContracts.register({
   },
 });
 
-// 3. Projections (read models)
 ark.projections.register({
   name: 'OrderIds',
   sourceIntents: ['Domain.Order.OrderPlaced'],
   initialState: { ids: [] as string[] },
-  project: (event, state) => ({
-    ids: [...state.ids, event.payload.orderId as string],
-  }),
+  project: (event, state) => ({ ids: [...state.ids, event.payload.orderId as string] }),
 });
 
-// 4. Publish through source-bound publisher (recommended)
 const publisher = ark.publisher('Application.PlaceOrder');
+await publisher.publish(OrderPlaced, { orderId: 'o1', amount: 129 }, { eventVersion: '1' });
 
-await publisher.publish(OrderPlaced, { orderId: 'o1', amount: 129 }, {
-  eventVersion: '1',
-  correlationId: 'corr-xyz',
-});
-
-console.log(await ark.projections.getState('OrderIds'));
-console.log(ark.observability.report());
-console.log(JSON.stringify(ark.manifest().toJSON(), null, 2));
+ark.manifest().toJSON(); // the complete machine-readable contract
 ```
 
-See `examples/basic/` for a runnable version.
-
----
+What it gives you: intent registry with produces/dependsOn, strict event bus (registered intents only, known sources), event contracts, hard/soft policies, observed layer-flow enforcement (`'hard' | 'soft' | 'off'`), projections, observability/drift reports, and pluggable audit/outbox/workflow interfaces (in-memory defaults — see [production hardening](docs/production-hardening.md)).
 
-## AI Write-Path Gate (`ark-mcp`)
+**Honest scope:** runtime enforcement covers governed paths only — what you route through Ark. Everything else is covered by the static gates.
 
-**The killer feature for agentic coding.**
+### NestJS
 
-### Pre-write hook (blocks bad code before disk)
+```ts
+import { ArkModule, InjectArk } from 'ark-runtime-kernel/nestjs';
+import type { ArkKernel } from 'ark-runtime-kernel';
 
-In Claude Code (`.claude/settings.json`):
+@Module({ imports: [ArkModule.forRoot()] })
+export class AppModule {}
 
-```json
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Write|Edit|MultiEdit",
-      "hooks": [{
-        "type": "command",
-        "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\""
-      }]
-    }]
-  }
+@Injectable()
+export class PlaceOrderService {
+  constructor(@InjectArk() private readonly ark: ArkKernel) {}
 }
 ```
 
-When blocked, the agent gets the violations back as feedback and can fix + retry.
-
-### Full MCP server
-
-```bash
-npx ark-mcp --root . --config ark.config.json
-```
-
-Exposes:
-- Resource: `ark://manifest`
-- Tool: `validate_code(source, layer?, filePath?)`
-
-Register in `.mcp.json`.
-
----
-
-## `ark-check` — The CI Gate
-
-```bash
-# Basic
-npx ark-check --root . --config ark.config.json
-
-# Fail on coverage gaps too
-npx ark-check --root . --config ark.config.json --strict-config
-
-# JSON for tools
-npx ark-check --json
-```
-
-**What it catches (via real TypeScript resolution):**
-- Import/export violations (relative, aliases, packages, dynamic import, require)
-- String intent references across forbidden layers
-- Raw publish calls
-- Missing source metadata
-- Source-layer mismatch
-
-`--init` generates a real config from the directories that *actually exist* in your project.
-
----
-
-## ESLint Plugin (dev guardrails)
-
-```js
-// eslint.config.js
-import ark from 'ark-runtime-kernel/eslint';
-
-export default [
-  ark.configs.recommended,
-];
-```
-
-Rules:
-- `ark/no-domain-infra-imports`
-- `ark/no-raw-event-publish`
-- `ark/require-publish-source`
-
----
-
-## What Ark Is / Is Not
-
-| ✅ Ark is                              | ❌ Ark is not                              |
-|---------------------------------------|-------------------------------------------|
-| Runtime + CI + AI governance kernel   | Database or queue                         |
-| Enforceable architectural contract    | Full distributed workflow engine          |
-| Machine-readable manifest for agents  | Replacement for your domain logic         |
-| Zero-dependency TypeScript library    | Complete semantic / type analyzer         |
-| Observable drift + history            | OpenTelemetry implementation              |
-| Focused, explicit, pluggable          | Magic that covers code you never route    |
-
----
-
-## Architecture Profile (11 Layers)
-
-The built-in profile + `ark.config.json` give you a sane default taxonomy:
-
-`DomainModel → ApplicationOrchestration → PersistenceAdapters → ...` (and 8 more)
-
-You can customize freely. Rules are deny-by-default except for a few explicitly allowed flows.
-
----
-
-## Production Notes
-
-All stores (`Audit`, `Outbox`, `Projections`, `Workflow`) default to in-memory.
-
-See [docs/production-hardening.md](./docs/production-hardening.md) for the interface contracts you must implement for durability.
-
----
+`@nestjs/common` is an optional peer dependency — the core stays zero-dependency.
 
 ## Documentation
 
-- [Agent Integration Guide](docs/agent-guide.md) — wiring `ark-mcp` into Claude Code, Cursor, and other agent runtimes
-- [Production Hardening](docs/production-hardening.md) — durable store interfaces to implement (`AuditStore`, `OutboxStore`, …)
-- [Example Config](docs/ark-check-example.json) — a hand-curated `ark.config.json` starting point
-- [Runnable Examples](examples/) — `examples/basic/` (kernel tour) and `examples/publish-smoke/` (consumer smoke test)
-- [Changelog](CHANGELOG.md)
-
----
+- [AI Gates](docs/ai-gates.md) — copy-paste setups for Claude Code, Cursor, Codex, and any hook-capable runtime
+- [Agent Integration Guide](docs/agent-guide.md) — manifest discovery and validation flows for agents
+- [Production Hardening](docs/production-hardening.md) — durable store interfaces (`AuditStore`, `OutboxStore`, …)
+- [Example Config](docs/ark-check-example.json) — a hand-curated `ark.config.json`
+- [Runnable Examples](examples/) — including `examples/hexagonal-order-api/`, a full hexagonal API you can break on purpose
+- [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
 
 ## Development
 
 ```bash
-npm install
+npm ci
+npm run build              # ark-mcp loads dist/
+npx vitest run
 npm run typecheck
-npm run check:architecture
-npm test
-npm run build
+npm run check:architecture # Ark gates itself in CI
 ```
 
-**Release process (already scripted):**
-
-```bash
-npm run release:npm          # full verify + publish
-npm run release:npm -- --dry # dry run
-```
-
-The release script:
-1. Typechecks + runs all tests + self architecture check
-2. Builds
-3. Temporarily swaps in the minimal publish manifest
-4. Publishes
-5. Restores dev manifest
-
----
+Release: `npm run release:npm` (verifies typecheck + tests + architecture gate, then publishes; `-- --dry` for a dry run).
 
 ## License
 
@@ -324,5 +227,3 @@ MIT © Pedro Knigge
 ---
 
 **Ark doesn't generate architecture. It protects the architecture you already have — at the exact moments it matters most.**
-
-Built for teams that use AI heavily and refuse to let entropy win.

package/bin/ark-check.mjs

@@ -23,6 +23,8 @@ function parseArgs(argv) {
     strictConfig: false,
     init: false,
     force: false,
+    baseline: undefined,
+    updateBaseline: false,
   };
   for (let i = 2; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -30,6 +32,12 @@ function parseArgs(argv) {
     else if (arg === '--strict-config') args.strictConfig = true;
     else if (arg === '--init') args.init = true;
     else if (arg === '--force') args.force = true;
+    else if (arg === '--baseline' || arg === '--update-baseline') {
+      if (arg === '--update-baseline') args.updateBaseline = true;
+      // optional path value: consume the next arg only when it isn't another flag
+      const next = argv[i + 1];
+      args.baseline = next && !next.startsWith('-') ? argv[++i] : '.ark-baseline.json';
+    }
     else if (arg === '--root') args.root = path.resolve(argv[++i]);
     else if (arg === '--config') args.config = argv[++i];
     else if (arg === '--manifest') args.manifest = argv[++i];
@@ -42,10 +50,15 @@ function parseArgs(argv) {
 
 function usage() {
   return [
-    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--json]',
+    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--json] [--baseline [file]]',
     '       ark-check --init [--force]',
+    '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',
+    'Adopting Ark in an existing codebase? Run --update-baseline once to freeze existing',
+    'violations, commit the baseline file, and gate CI with --baseline: only NEW violations',
+    'fail the check, so the ratchet only moves toward zero.',
+    '',
     '--init scans the project for the built-in layer directory conventions (src/domain,',
     'src/application, src/adapters/persistence, ...) and writes an ark.config.json covering',
     'only the layers that actually exist, with the default rules filtered to those layers.',
@@ -564,6 +577,71 @@ function publishHasSource(ts, node) {
   );
 }
 
+// ponytail: baseline keys exclude the line number so unrelated edits that shift lines
+// don't resurrect frozen violations; the trade-off is that N identical violations in one
+// file collapse to one key.
+function baselineKey(violation) {
+  return [
+    violation.ruleId,
+    violation.file,
+    violation.fromLayer ?? '',
+    violation.toLayer ?? '',
+    violation.target ?? '',
+  ].join('|');
+}
+
+function readBaseline(root, baselinePath) {
+  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
+  if (!fs.existsSync(fullPath)) return { keys: new Set(), fullPath, exists: false };
+  const raw = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+  return { keys: new Set(raw.violations ?? []), fullPath, exists: true };
+}
+
+function writeBaseline(root, baselinePath, violations) {
+  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
+  const keys = [...new Set(violations.map(baselineKey))].sort();
+  fs.writeFileSync(
+    fullPath,
+    `${JSON.stringify({ version: 1, note: 'Frozen ark-check violations. Only NEW violations fail --baseline runs. Regenerate with: ark-check --update-baseline', violations: keys }, null, 2)}\n`
+  );
+  return { fullPath, count: keys.length };
+}
+
+const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
+const color = {
+  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
+  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+};
+
+const FIX_HINTS = {
+  LAYER_IMPORT_VIOLATION:
+    'Depend on a port/interface owned by an inner layer instead, or move this code to a layer allowed to make this import.',
+  LAYER_INTENT_REFERENCE_VIOLATION:
+    'Reference intents through a layer that owns them (e.g. subscribe from an adapter, not from the domain).',
+  RAW_EVENT_PUBLISH:
+    'Define the intent with ark.registry.define(...) and publish through the returned creator.',
+  PUBLISH_MISSING_SOURCE:
+    'Add metadata.source (the publishing intent name) to the publish call.',
+  PUBLISH_SOURCE_LAYER_MISMATCH:
+    'Use a source intent that belongs to the same layer as the publishing file, or move the file.',
+};
+
+function printViolation(violation) {
+  const location = `${violation.file}:${violation.line}`;
+  console.error(`${color.red('✖')} ${color.bold(violation.ruleId)}  ${location}`);
+  if (violation.fromLayer && violation.toLayer) {
+    const target = violation.target ? `  ${color.dim(`(${violation.target})`)}` : '';
+    console.error(`  ${violation.fromLayer} → ${violation.toLayer}${target}`);
+  }
+  console.error(`  ${violation.message}`);
+  const hint = FIX_HINTS[violation.ruleId];
+  if (hint) console.error(`  ${color.dim(`fix: ${hint}`)}`);
+  console.error('');
+}
+
 function moduleSpecifierFromCall(ts, node) {
   if (!ts.isCallExpression(node)) return undefined;
 
@@ -733,38 +811,82 @@ async function main() {
     visit(sourceFile);
   }
 
+  if (args.updateBaseline) {
+    const { fullPath, count } = writeBaseline(root, args.baseline, violations);
+    console.log(`Wrote ${fullPath} with ${count} frozen violation key(s).`);
+    console.log('Commit it and gate CI with: ark-check --baseline (only NEW violations fail).');
+    return;
+  }
+
+  let suppressed = [];
+  let activeViolations = violations;
+  let staleBaselineKeys = 0;
+  if (args.baseline) {
+    const baseline = readBaseline(root, args.baseline);
+    if (baseline.exists) {
+      suppressed = violations.filter((violation) => baseline.keys.has(baselineKey(violation)));
+      activeViolations = violations.filter(
+        (violation) => !baseline.keys.has(baselineKey(violation))
+      );
+      const currentKeys = new Set(violations.map(baselineKey));
+      staleBaselineKeys = [...baseline.keys].filter((key) => !currentKeys.has(key)).length;
+    } else {
+      warnings.push(
+        configWarning(
+          'BASELINE_NOT_FOUND',
+          `Baseline file not found: ${baseline.fullPath}. Generate it with: ark-check --update-baseline`
+        )
+      );
+    }
+  }
+
+  const ok = activeViolations.length === 0 && (!args.strictConfig || warnings.length === 0);
+
   if (args.json) {
     console.log(JSON.stringify({
-      ok: violations.length === 0 && (!args.strictConfig || warnings.length === 0),
-      violations,
+      ok,
+      violations: activeViolations,
+      suppressedViolations: suppressed.length,
+      staleBaselineKeys,
       warnings,
     }, null, 2));
-  } else if (violations.length === 0) {
+  } else {
     for (const warning of warnings) {
-      console.error(`warning ${warning.ruleId} ${warning.message}`);
+      console.error(`${color.yellow('warning')} ${warning.ruleId} ${warning.message}`);
     }
-    if (warnings.length === 0) {
-      console.log('Ark check passed.');
-    } else if (args.strictConfig) {
-      console.error(`Ark check failed with ${warnings.length} config warning(s).`);
-    } else {
-      console.log(`Ark check passed with ${warnings.length} config warning(s).`);
+    for (const violation of activeViolations) {
+      printViolation(violation);
     }
-  } else {
-    for (const warning of warnings) {
-      console.error(`warning ${warning.ruleId} ${warning.message}`);
+
+    const baselineNote =
+      suppressed.length > 0 ? ` (${suppressed.length} suppressed by baseline)` : '';
+    if (staleBaselineKeys > 0) {
+      console.error(
+        color.dim(
+          `${staleBaselineKeys} baseline entr(y/ies) no longer occur — tighten the ratchet with: ark-check --update-baseline`
+        )
+      );
     }
-    for (const violation of violations) {
+    if (activeViolations.length === 0) {
+      if (warnings.length === 0) {
+        console.log(`${color.green('✔')} Ark check passed.${baselineNote}`);
+      } else if (args.strictConfig) {
+        console.error(
+          `${color.red('✖')} Ark check failed with ${warnings.length} config warning(s).${baselineNote}`
+        );
+      } else {
+        console.log(
+          `${color.green('✔')} Ark check passed with ${warnings.length} config warning(s).${baselineNote}`
+        );
+      }
+    } else {
       console.error(
-        `${violation.file}:${violation.line} ${violation.ruleId} ${violation.message}`
+        `${color.red('✖')} ${activeViolations.length} violation(s).${baselineNote}`
       );
     }
   }
 
-  process.exitCode =
-    violations.length === 0 && (!args.strictConfig || warnings.length === 0)
-      ? 0
-      : 1;
+  process.exitCode = ok ? 0 : 1;
 }
 
 main().catch((error) => {