arkgate 2.1.0

package/docs/ai-gates.md

@@ -0,0 +1,337 @@
+# Gating AI Agents with Ark
+
+**Ark** is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
+The write-path gate is what makes it different from every other architecture linter:
+generated code is validated against your architecture **before it lands on disk**, not
+after the PR is red.
+
+Everything below uses the same `ark.config.json` as `ark-check` (CI) — one contract, enforced everywhere. Generate it once:
+
+```bash
+npx ark-check --init
+```
+
+For guided setup with prompts, use:
+
+```bash
+npx ark init
+```
+
+For non-interactive defaults, use:
+
+```bash
+npx ark init --yes
+```
+
+You can also generate only the starter gate files for common agent runtimes and CI:
+
+```bash
+npx ark-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
+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.
+
+If your project uses Codex or Grok, treat MCP registration as part of the default
+setup, not an optional extra. Ark works best when the agent can read `ark://manifest`
+before it writes code; that is the fast path to avoiding architecture drift during
+generation.
+
+## Claude Code — hook (recommended, hard block)
+
+`ark-mcp --hook` is a one-shot PreToolUse gate: it reads the hook payload from stdin, computes the **post-edit** file content, validates it, and exits `2` (block, violations on stderr) or `0` (allow). The agent sees the violations and self-corrects.
+
+Like `ark-check --baseline`, the hook ratchets: an edit is blocked only when it **adds**
+violations relative to the file's current on-disk state, so files with pre-existing
+(baselined) violations stay editable — they just can't get worse. New files block on
+every violation.
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+That's the whole setup. Try asking the agent to import a persistence adapter from your domain layer:
+
+```
+Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainModel):
+- [FORBIDDEN_PATTERN] Forbidden pattern matched: /from ['"].*\/(infra|adapters|persistence|db)/i (line 1)
+- [FORBIDDEN_IMPORT] Forbidden import target: "../adapters/persistence/pg-order-repository". (line 1)
+Fix the violations and retry. The architecture contract is available as the ark://manifest MCP resource.
+```
+
+## Claude Code — SessionStart context injection (know the rules before the first token)
+
+The write gate teaches by rejection; the SessionStart hook teaches up front.
+`ark-mcp --session-context` prints a compact contract summary — layers, forbidden
+globals, denied-edge count, baseline state, and the check command — which Claude Code
+injects into the agent's context at session start:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ark-mcp --session-context --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+What the agent sees:
+
+```
+Ark architecture contract governs this project (ark.config.json is authoritative).
+Layers:
+  - DomainModel: src/domain/** — forbidden globals: fetch, process, Date.now, Math.random
+  - PersistenceAdapters: src/adapters/persistence/**
+Rules: 10 denied layer edge(s). Full contract: ark://manifest MCP resource.
+Baseline: 3 frozen violation(s) — only NEW violations fail; do not add to them.
+After edits run: npx ark-check --root . --config ark.config.json --strict-config
+```
+
+The hook belongs in the **project's** `.claude/settings.json` (that's what
+`--install-agent-gates` generates). It is also safe by construction if you prefer it in
+your global settings: without an `ark.config.json` in the project, `--session-context`
+prints nothing and exits 0, so non-Ark projects are untouched.
+
+## Claude Code — MCP server (contract discovery + on-demand validation)
+
+The MCP server exposes a resource and four tools agents can use proactively:
+
+- **`ark://manifest`** (resource) — the machine-readable architecture contract (layers + rules), so the agent can read the architecture before generating code.
+- **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate).
+- **`ark_place`** (tool) — given a target file path, returns its layer, forbidden globals, and which layers it may / must not import. Call it *before* writing a new file so generated code lands in a governed location.
+- **`ark_check`** (tool) — runs the full architecture check and returns structured violations (applies the baseline automatically when one exists).
+- **`ark_coverage`** (tool) — per-layer file counts, the full unclassified-file list, and layers whose patterns match nothing.
+
+Tools appear in the agent's tool list automatically — no skill or doc-reading needed — so the agent can query the contract instead of shelling out and parsing.
+
+```bash
+claude mcp add ark -- npx ark-mcp --root . --config ark.config.json
+```
+
+or in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ark": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+    }
+  }
+}
+```
+
+Use both: the MCP server for discovery, the hook for enforcement.
+
+## Cursor
+
+Cursor supports MCP servers (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ark": {
+      "command": "npx",
+      "args": ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+    }
+  }
+}
+```
+
+Cursor has no pre-write hook, so the gate is advisory at write time — pair it with a rules file so the agent actually calls it. `.cursor/rules/ark.mdc`:
+
+```markdown
+---
+description: Ark architecture contract
+alwaysApply: true
+---
+
+Before writing or editing any TypeScript source file, call the `validate_code`
+tool from the `ark` MCP server with the full post-edit file content and its
+path. If it reports violations, fix them before writing. The architecture
+contract is available as the `ark://manifest` resource.
+```
+
+Your hard backstop in Cursor is CI: `ark-check` fails the PR on anything that slips through.
+
+## OpenAI Codex CLI
+
+Recommended for Ark projects.
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.ark]
+command = "npx"
+args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+```
+
+Same model as Cursor: MCP for discovery/validation, `ark-check` in CI as the hard gate.
+For Ark projects, register the MCP server as soon as the repo is adopted so the agent
+has the contract available from the first edit.
+
+`ark-check --install-agent-gates --tools codex` auto-merges absolute paths into
+`~/.codex/config.toml` and can install `/ark-*` prompts with `--codex-home`.
+
+## Grok Build (xAI)
+
+Grok reads project rules from **`AGENTS.md`**, project MCP from **`.grok/config.toml`**
+(and repo-root `.mcp.json`), skills from **`.grok/skills/<name>/SKILL.md`**, and
+hooks from **`.grok/hooks/*.json`**.
+
+Install everything Ark needs for Grok:
+
+```bash
+npx ark-check --install-agent-gates --tools grok
+```
+
+That writes:
+
+| Path | Role |
+|------|------|
+| `.grok/config.toml` | `[mcp_servers.ark]` → `ark-mcp` (relative `--root .`) |
+| `.grok/hooks/ark-write-gate.json` | SessionStart context + PreToolUse write gate |
+| `.grok/skills/ark-*/SKILL.md` | All `/ark-*` skills (slash-invocable) |
+| `AGENTS.md` + `.mcp.json` + CI | Shared with other hosts |
+
+Grok also loads Claude/Cursor MCP and skill paths when compat is enabled, so a repo
+already wired for Claude often “just works” in Grok — but the native `.grok/*` layout
+is the supported, commit-friendly path.
+
+**Write gate:** Grok’s PreToolUse uses camelCase payloads (`toolName` / `toolInput`)
+and may call `write` / `search_replace`. `ark-mcp --hook` accepts both Claude and Grok
+shapes and returns a Grok-compatible `{ "decision": "deny", "reason": "…" }` on stdout
+when it blocks.
+
+**Trust:** the first time you open a project with hooks, run `/hooks-trust` (or
+`grok --trust`) so project hooks and local MCP are allowed.
+
+Manual MCP only:
+
+```toml
+# .grok/config.toml  (or: grok mcp add --scope project ark -- npx ark-mcp --root . --config ark.config.json)
+[mcp_servers.ark]
+command = "npx"
+args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+```
+
+Then restart Grok or refresh via `/mcps`. Pair with CI `ark-check` as the hard merge gate.
+
+## Instruction-tier agents: Windsurf, Cline, Copilot, Kiro, Roo Code, Continue, Gemini CLI
+
+Agents without MCP or hook support still follow the contract through an always-on
+project rule file. `ark-check --install-agent-gates` generates them (auto-detected
+from `.windsurf/`, `.clinerules/`, `.kiro/`, `.roo/`, `.continue/`, `.gemini/`;
+Copilot is explicit-only):
+
+```bash
+npx ark-check --install-agent-gates --tools windsurf,cline,copilot,kiro,roo,continue,gemini
+```
+
+| Tool | File written |
+|------|--------------|
+| Windsurf | `.windsurf/rules/ark.md` |
+| Cline | `.clinerules/ark.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Kiro | `.kiro/steering/ark.md` |
+| Roo Code | `.roo/rules/ark.md` |
+| Continue | `.continue/rules/ark.md` |
+| Gemini CLI | `GEMINI.md` (its primary context file; also reads `AGENTS.md`) |
+
+All of them derive from the same contract as `AGENTS.md` and the Cursor rule, so the
+steps cannot drift. These are advisory (the agent reads rules; nothing blocks the
+write) — keep `ark-check` in CI as the hard gate.
+
+## 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:
+
+- 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)
+- 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
+
+## ESLint (editor feedback)
+
+For in-editor red squiggles on layer violations, add the ESLint plugin. It ships a
+flat-config preset you can spread directly:
+
+```js
+// eslint.config.js  (flat config)
+import ark from 'arkgate/eslint';
+
+export default [
+  ark.configs.recommended,   // ark/no-domain-infra-imports, no-raw-event-publish, require-publish-source
+];
+```
+
+`recommended` deliberately omits **`ark/no-forbidden-globals`** (domain purity: no
+`fetch`, `Date.now`, `Math.random`, …). That rule is only correct when scoped to your
+domain directories — a global block would flag legitimate infrastructure code. Add it
+as its own block with a `files` glob matching your `DomainModel` layer:
+
+```js
+import ark from 'arkgate/eslint';
+
+export default [
+  ark.configs.recommended,
+  {
+    files: ['packages/*/domain/**', 'src/**/domain/**'],  // your DomainModel layer paths
+    plugins: { ark },
+    rules: {
+      'ark/no-forbidden-globals': [
+        'error',
+        { globals: ['fetch', 'process', 'Date.now', 'Math.random'] },  // match ark.config.json
+      ],
+    },
+  },
+];
+```
+
+Rule ids are `ark/<kebab-name>`. Keep the `globals` list in sync with the
+`forbiddenGlobals` on your `DomainModel` layer in `ark.config.json` so the editor and
+`ark-check` agree. All four rules are exported individually too (`ark.rules`) if you
+prefer to wire them by hand.
+
+## CI backstop
+
+Whatever the agent side does, gate the merge:
+
+```yaml
+- run: npx ark-check --root . --config ark.config.json --strict-config
+```
+
+Adopting Ark on an existing codebase with violations? Freeze them once and ratchet down:
+
+```bash
+npx ark-check --update-baseline   # writes .ark-baseline.json — commit it
+npx ark-check --baseline          # only NEW violations fail
+```

package/docs/ark-check-example.json

@@ -0,0 +1,87 @@
+{
+  "include": ["src"],
+  "layers": [
+    {
+      "name": "DomainModel",
+      "patterns": ["src/domain/**"],
+      "intentPrefixes": ["Domain."]
+    },
+    {
+      "name": "ApplicationOrchestration",
+      "patterns": ["src/application/**"],
+      "intentPrefixes": ["Application."]
+    },
+    {
+      "name": "PersistenceAdapters",
+      "patterns": ["src/adapters/persistence/**"],
+      "intentPrefixes": ["Adapter.Persistence."]
+    },
+    {
+      "name": "IntegrationAdapters",
+      "patterns": ["src/adapters/integration/**"],
+      "intentPrefixes": ["Adapter.Integration."]
+    },
+    {
+      "name": "WorkflowSagaEngine",
+      "patterns": ["src/workflows/**"],
+      "intentPrefixes": ["Workflow."]
+    },
+    {
+      "name": "BackgroundJobsScheduling",
+      "patterns": ["src/jobs/**"],
+      "intentPrefixes": ["Job."]
+    },
+    {
+      "name": "PresentationAdapters",
+      "patterns": ["src/presentation/**"],
+      "intentPrefixes": ["Presentation."]
+    },
+    {
+      "name": "ReportingReadModels",
+      "patterns": ["src/reporting/**"],
+      "intentPrefixes": ["Reporting."]
+    },
+    {
+      "name": "ExtensibilityMetadata",
+      "patterns": ["src/metadata/**"],
+      "intentPrefixes": ["Metadata."]
+    },
+    {
+      "name": "SecurityAuditObservability",
+      "patterns": ["src/security/**", "src/audit/**", "src/observability/**"],
+      "intentPrefixes": ["Security.", "Audit.", "Observability."]
+    },
+    {
+      "name": "Kernel",
+      "patterns": ["src/kernel/**"],
+      "intentPrefixes": ["Kernel."]
+    }
+  ],
+  "rules": [
+    {
+      "from": "DomainModel",
+      "to": "PersistenceAdapters",
+      "allowed": false
+    },
+    {
+      "from": "DomainModel",
+      "to": "IntegrationAdapters",
+      "allowed": false
+    },
+    {
+      "from": "DomainModel",
+      "to": "PresentationAdapters",
+      "allowed": false
+    },
+    {
+      "from": "PresentationAdapters",
+      "to": "PersistenceAdapters",
+      "allowed": false
+    },
+    {
+      "from": "ReportingReadModels",
+      "to": "PersistenceAdapters",
+      "allowed": false
+    }
+  ]
+}

package/docs/assets/ark-write-gate.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="330" viewBox="0 0 760 330" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13">
+  <defs>
+    <clipPath id="window"><rect x="0" y="0" width="760" height="330" rx="10"/></clipPath>
+  </defs>
+  <g clip-path="url(#window)">
+    <rect width="760" height="330" fill="#0d1117"/>
+    <rect width="760" height="34" fill="#161b22"/>
+    <circle cx="20" cy="17" r="6" fill="#ff5f57"/>
+    <circle cx="40" cy="17" r="6" fill="#febc2e"/>
+    <circle cx="60" cy="17" r="6" fill="#28c840"/>
+    <text x="380" y="21" fill="#8b949e" text-anchor="middle" font-size="12">claude — my-hexagonal-app</text>
+
+    <text x="24" y="64" fill="#c9d1d9">&gt; add a findById method to Order that reads straight from postgres</text>
+
+    <text x="24" y="96" fill="#8b949e">● Edit(src/domain/order.ts)</text>
+    <text x="40" y="118" fill="#6e7681">import { PgOrderRepository } from '../adapters/persistence/pg-order-repository';</text>
+
+    <text x="24" y="152" fill="#f85149" font-weight="bold">✗ Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainModel):</text>
+    <text x="40" y="174" fill="#f85149">- [FORBIDDEN_IMPORT] Forbidden import target: "../adapters/persistence/pg-order-repository".</text>
+    <text x="24" y="196" fill="#8b949e">Fix the violations and retry. The architecture contract is available as the</text>
+    <text x="24" y="214" fill="#8b949e">ark://manifest MCP resource.</text>
+
+    <text x="24" y="248" fill="#c9d1d9">● The domain layer can't import persistence adapters. I'll define the port in the</text>
+    <text x="24" y="266" fill="#c9d1d9">domain instead and implement it in src/adapters/persistence/.</text>
+
+    <text x="24" y="300" fill="#28c840">● Edit(src/domain/ports/order-repository.ts)  ✔ allowed</text>
+  </g>
+</svg>

package/docs/brownfield-adoption.md

@@ -0,0 +1,87 @@
+# Brownfield burn-down playbook
+
+Adopting Ark on a large, pre-existing codebase is a different job from a greenfield one: the
+goal is not "make the check green" — it's to get the contract to reflect the real
+architecture, govern most of the tree, and freeze only genuine debt, then burn it down in
+order. This playbook is the sequence that keeps you honest (and is what `/ark-adopt` runs).
+
+The rule underneath all of it: **`ark.config.json` is authoritative.** A green check that
+governs 40% of the tree, or a baseline full of false positives, is worse than no gate — it
+looks safe. Report the truth, then fix it.
+
+## 1. Config — reflect what exists, propose the rest
+
+```bash
+ark-check --init          # detects layer directories; proposes a layer for each ungoverned one
+```
+
+`--init` writes layers for the directories it recognizes and **proposes a canonical layer for
+every ungoverned directory** (harvested from the 11-layer profile + presets; unrecognized
+ones are flagged for you to classify, never guessed). Keep an existing config; don't
+regenerate it unasked.
+
+## 2. Diagnose before you freeze
+
+```bash
+ark-check --root . --config ark.config.json --json   # read `summary`
+ark-check --doctor                                    # or the consolidated health view
+```
+
+Read the violation `summary`. The decisive signal is **concentration**: when most violations
+are a single layer edge, the *contract* is almost always wrong, not the code. The classic
+case is every route "violating" app→kernel because the framework's own entrypoint
+(`defineRoute`, a DI container, etc.) is the sanctioned way in — that's hundreds of false
+positives, not debt. `--update-baseline` will refuse a lopsided freeze for exactly this
+reason. Fix the contract first (step 3).
+
+## 3. Make the contract real (via `/ark-contract`)
+
+- **Classify the ungoverned tree.** `ark-check --coverage` leads with `Governed: N%` and
+  proposes a layer per ungoverned directory. Add the recognized ones; decide the layer for the
+  flagged ones. Get `governed` high before trusting any check.
+- **Protect the border around a framework, not its internals.** If the concentrated edge
+  points into a DI/kernel framework (dcouplr, NestJS, a custom kernel), split the target layer
+  into a **public surface** (the entrypoints app code may import — e.g. `kernel/app/**`,
+  `kernel/events.ts`) and **internals** (denied). Overlapping globs resolve most-specific-first,
+  so the surface wins regardless of layer order. Where app code reaches an internal entrypoint
+  it legitimately needs, add a re-export **barrel** in the surface layer and repoint the
+  imports to it — behavior-preserving, and the imports are now legal.
+
+Re-run the check; the remainder should now be genuine debt.
+
+## 4. Freeze only the genuine debt
+
+```bash
+ark-check --update-baseline    # writes .ark-baseline.json — commit it
+```
+
+If Ark still refuses (a single edge dominates), the contract is still wrong — go back to
+step 3; don't `--force` past it. From now `ark-check --baseline` fails only on NEW
+violations — the ratchet only moves toward zero.
+
+## 5. Burn down, in order
+
+`summary.edges` is the burn-down order. Two patterns cover most of it — and Ark tells you
+which is which via the `typeOnly` tag (value = real coupling, fix first; type-only = placement):
+
+- **Type-only inversion** (a lower layer `import type`s a type that lives in an upper layer):
+  move the type down to the layer that owns it and re-export it from the original module for
+  back-compat. Cosmetic at runtime, `tsc`-verifiable, safe to sweep. (Not mechanical if the
+  type extends a persistence/ORM row — that needs a domain-owned type/port — or if the source
+  file mixes types with logic — split first.)
+- **Raw infrastructure access** (a route/handler running SQL or importing the DB directly):
+  relocate the data-access **verbatim** into a repository/adapter method the route calls. Same
+  query bytes = same behavior; do NOT rewrite the query. This edits the data layer — if your
+  repo reserves that to core maintainers, migrate one route as a demonstrated pattern and hand
+  the bulk over; a route with interleaved transactions isn't a pure relocation, so flag it.
+
+`/ark-fix` resolves each cluster at the root cause; fixing a frozen violation shrinks the
+baseline permanently. Re-freeze lower with `--update-baseline` as you go.
+
+## What Ark does NOT do here
+
+Ark reorganizes and governs code — it never touches your data model. Migrating raw SQL to a
+repository moves the same query to another file; the schema, migrations, and the database are
+untouched. And the burn-down itself is the team's work (or a codemod, or an agent loop) — Ark
+diagnoses, orders it, and gives you the pattern; it doesn't auto-run hundreds of edits against
+your restricted data layer.

package/docs/demos/01-write-gate-self-correction.md

@@ -0,0 +1,74 @@
+# Demo: write-gate self-correction
+
+Reproduce how an agent sees a layer violation, gets a plain-language fix hint, and
+corrects the architecture instead of weakening the contract.
+
+## Prerequisites
+
+- Ark installed in the repo (`ark-check`, agent gates optional for this demo)
+- [examples/hexagonal-order-api](../../examples/hexagonal-order-api/) cloned with dependencies
+
+## Steps
+
+### 1. Confirm the project is green
+
+```bash
+cd examples/hexagonal-order-api
+npm install
+npm run check
+```
+
+Expected:
+
+```
+✔ Ark check passed.
+```
+
+### 2. Introduce a deliberate domain → persistence import
+
+Add to the top of `src/domain/order.ts`:
+
+```ts
+import { createInMemoryOrderRepository } from '../adapters/persistence/in-memory-order-repository.js';
+```
+
+### 3. Run the CI gate (same stimulus as the write-gate hook)
+
+```bash
+npm run check
+```
+
+Expected violation (abbreviated):
+
+```
+✖ LAYER_IMPORT_VIOLATION  src/domain/order.ts
+  DomainModel → PersistenceAdapters
+  DomainModel must not import PersistenceAdapters.
+```
+
+With `--json`, the same violation includes `fixClass: port-inversion` and an
+`enthusiastHint` describing the port pattern.
+
+### 4. Self-correct (architecture fix, not a config edit)
+
+Revert the bad import. Define or use the existing `OrderRepository` port in domain and
+keep the in-memory implementation in `src/adapters/persistence/`.
+
+```bash
+npm run check
+```
+
+Expected:
+
+```
+✔ Ark check passed.
+```
+
+## What this proves
+
+- The gate blocks the common enthusiast mistake (database code in domain).
+- The error message points at the **layer edge**, not a generic lint rule.
+- The fix is a file move or port inversion — not editing `ark.config.json`.
+
+See also: [Break it on purpose](../../examples/hexagonal-order-api/README.md#break-it-on-purpose)
+for two more exercises.

package/docs/demos/02-brownfield-baseline-adoption.md

@@ -0,0 +1,71 @@
+# Demo: brownfield baseline adoption
+
+Walk through honest adoption on an existing repo: diagnose, classify, freeze real debt,
+burn down in order. This demo uses the eval fixture `enthusiast-wrong-layer` as a
+stand-in brownfield tree.
+
+Full playbook: [docs/brownfield-adoption.md](../brownfield-adoption.md).
+
+## Prerequisites
+
+- Ark built or installed from this repository
+
+## Steps
+
+### 1. Copy the brownfield fixture to a temp directory
+
+```bash
+TMP=$(mktemp -d)
+cp -R eval/cases/enthusiast-wrong-layer/* "$TMP/"
+cd "$TMP"
+```
+
+### 2. Diagnose — read the violation summary
+
+```bash
+node /path/to/ark/bin/ark-check.mjs --root . --config ark.config.json --json
+```
+
+Expected: `LAYER_IMPORT_VIOLATION` from domain importing `src/infra/db.ts`.
+
+### 3. Classify — coverage and doctor
+
+```bash
+node /path/to/ark/bin/ark-check.mjs --root . --doctor
+node /path/to/ark/bin/ark-check.mjs --root . --coverage
+```
+
+Note `governed.percent` and any ungoverned directories. Do **not** regenerate
+`ark.config.json` unasked on a real brownfield repo.
+
+### 4. Fix architecture (not the gate)
+
+Move persistence behind a port in domain; relocate `db.ts` under
+`src/adapters/persistence/` (or invert via a repository interface). Re-run:
+
+```bash
+node /path/to/ark/bin/ark-check.mjs --root . --config ark.config.json --strict-config
+```
+
+Expected after a real fix:
+
+```
+✔ Ark check passed.
+```
+
+### 5. Baseline only genuine remaining debt
+
+If violations are widespread but **concentrated on one false edge**, fix the contract
+first (see playbook §3). When the remainder is real legacy debt:
+
+```bash
+node /path/to/ark/bin/ark-check.mjs --root . --update-baseline
+```
+
+New files must still pass without suppression.
+
+## What this proves
+
+- Brownfield adoption starts with truthful diagnosis, not a green check at any cost.
+- `/ark-adopt` and `/ark-contract` align messy trees to the canonical profile.
+- Baselines ratchet down; they do not replace architecture fixes.