arkgate 2.1.0

package/templates/skills/ark-autopilot.md

@@ -0,0 +1,95 @@
+---
+name: ark-autopilot
+description: The end-to-end architecture co-pilot for non-developers. One flow: look at the project, set up the guardrails, then drive the plan to a clean architecture — auto-applying the safe fixes and proposing the rest, always validated by ark-check, never weakening the gate. Composes setup + plan + the apply loop. Autonomous within those limits.
+---
+
+# /ark-autopilot — Get to a sound architecture, end to end
+
+This is the co-pilot's top-level flow. It composes the three primitives — **plan** (Phase F),
+the guided setup (Phase G), and the **loop** (Phase H) — into one experience that takes a
+non-developer from "I have a project" to "governed, cleaned up, and enforced from now on."
+
+**The rule that keeps it safe:** you (the agent) make edits; **Ark decides what may land.** Only
+`mechanical-safe` changes are auto-applied (validated, with rollback); everything `judgment` is
+PROPOSED for a human decision. Code only — never DB/schema, never weakening the gate.
+
+## Two entry styles, three operating modes, one contract
+
+**Who is driving** (entry style):
+
+- **Newbie (default here):** run the WHOLE flow with plain-language explanations and an
+  approval prompt before anything non-trivial. The user never needs to know a preset or a rule
+  name. This skill is that flow.
+- **Expert:** skip the autopilot and use the pieces directly — `ark init` / `/ark-contract` to
+  shape the contract, `ark-check --plan` to see the work, `/ark-fix` for targeted fixes,
+  `ark-check --strict-config` as the gate. Point them there and stop.
+
+**What Ark is doing right now** (operating mode — read from `ark start` / `--plan` / `--coverage`):
+
+- **Suggest** — thin or greenfield project: propose an application shape and install a starter contract.
+- **Adapt** — brownfield or low `governed%`: match the contract to the real layout, raise coverage,
+  freeze only real debt. A clean plan with ~0% governed is **not** done — route to `--coverage` / `/ark-adopt`.
+- **Enforce** — `goal.met` is true *and* governed coverage is meaningful: write gate + CI hold the line.
+
+Never tell a user "your architecture is guarded" while `--plan` reports `goal.met: false` or
+`governedPercent` is low.
+
+## Flow (newbie tier)
+
+1. **Set up if needed.** If there's no `ark.config.json`, run the guided setup: `ark start`
+   (which itself uses `ark-check --recommend` to suggest a shape in plain language, then writes
+   the config + agent/CI gates, and captures the **origin** architecture report under
+   `.ark/reports/`). On an established codebase it adopts the real structure. If
+   Ark is already set up, skip to step 2.
+
+2. **Freeze / confirm the starting picture.** Always run once before changing code:
+
+   ```bash
+   npx ark-check --root . --config ark.config.json --report ark-report.html
+   ```
+
+   - If `.ark/reports/origin.json` did not exist, this **creates the origin snapshot** (day-one
+     baseline). Do **not** pass `--reset-origin` unless the user explicitly wants a new baseline.
+   - Open / point the user at `ark-report.html` (and `.ark/reports/origin.html` when first created).
+   - This is the “before” picture the autopilot will improve against.
+
+3. **Show the plan.** Run `ark-check --plan` and explain it in outcome terms: how many fixes are
+   _safe to auto-apply_ vs _need your decision_ vs _deferred_, and what the goal is (a clean,
+   enforced architecture). Confirm before changing anything.
+
+4. **Drive the loop.** Hand off to **`/ark-loop`**: in a discardable git worktree, auto-apply
+   the `mechanical-safe` steps one at a time (validate with `ark-check`, roll back regressions),
+   and PROPOSE each `judgment` step in plain language for a yes/no. Loop until the plan's
+   `goal.met` is true or a round makes no progress.
+
+5. **Confirm it stays clean.** Verify the gates are installed and active so the architecture is
+   enforced from now on (in CI, and at write time if the MCP hook is wired) — the
+   "and stays that way" half of the promise. Run the final `ark-check --strict-config`.
+
+6. **Close with the after report + evolution.** Run again:
+
+   ```bash
+   npx ark-check --root . --config ark.config.json --report ark-report.html
+   ```
+
+   The HTML now includes **Evolution vs origin** (score, governed%, violations, files per layer)
+   when origin already existed. Point the user at:
+   - `ark-report.html` / `.ark/reports/latest.html` — **after**
+   - `.ark/reports/origin.html` — **before** (frozen)
+   - `.ark/reports/history/` — optional JSON trail
+
+7. **Report honestly, in plain language.** Summarize what was auto-applied, what you proposed
+   and the user decided, and what's deferred (and why). Tie the narrative to the before/after
+   report numbers. Show the diff. Only merge the worktree back after the user reviews. Never
+   report "done / clean" while steps were skipped.
+
+## Operating rules
+
+- Never weaken the gate to finish: no disabling rules, editing `ark.config.json` to allow a bad
+  edge, or baselining a fresh violation. Fix the code, or propose a contract change via
+  `/ark-contract` with its before/after impact.
+- If most violations concentrate on one edge, that's a contract smell — stop and route to
+  `/ark-contract`, don't grind N fixes.
+- Bias to proposing: when unsure a change preserves behavior, treat it as `judgment`.
+- Everything traces to Ark's own outputs (`ark-check --plan --json`, `--recommend`) — never
+  invent architecture advice.

package/templates/skills/ark-contract.md

@@ -0,0 +1,98 @@
+---
+name: ark-contract
+description: Safely edit ark.config.json (layers, rules, forbiddenGlobals, intent prefixes), validated with strict ark-check. The one sanctioned way to change the architecture contract.
+---
+
+# /ark-contract — Evolve the architecture contract safely
+
+You are editing `ark.config.json` — the machine-readable contract every gate
+(write gate, CI, ESLint, runtime) enforces. Changes here alter what ALL agents
+and humans are allowed to write, so the bar is: smallest change, validated,
+explained.
+
+**No change described?** If invoked with no specific edit, don't guess and don't
+edit anything — the intent is the user's to give. Take the snapshot (step 1) and
+present the evolution options grounded in THIS contract: adopt a `suggestedLayers`
+layer, tighten a permitted/implicit edge to denied, add `forbiddenGlobals` to a
+pure layer, or move a file between layers. While reading the config, surface any
+real classification inconsistency you notice (e.g. an HTTP-client file sitting in
+a non-integration layer via a fallback pattern) — but before calling a move a
+"clean config change", check the file's actual imports against the target layer's
+rules (see step 2's move bullet). Then ask which change to make. Reading the
+contract to produce that is real work, not a stalling question.
+
+## Steps
+
+1. **Snapshot first** — run `ark-check --root . --config ark.config.json
+   --json` and save the result. You must be able to show what the change
+   legalized or newly forbids.
+2. **Make the smallest edit** that achieves the user's intent:
+   - **New layer**: add `{ name, patterns }`; add `intentPrefixes` if the
+     project uses intent naming; wire explicit `rules` edges to its neighbors —
+     a layer with no rules is ungoverned, so default to denying edges that match
+     the project's existing direction of dependencies.
+   - **New rule**: prefer adding a DENIED edge (tightening). For an ALLOWED
+     edge (loosening), first check whether any current code depends on it — if
+     nothing needs it, don't add it (a permission nobody uses is future debt).
+   - **Split a layer into a public surface + internals (the facade fix)**: when a
+     check's `summary` shows most violations are ONE edge into a layer (e.g. all of
+     app-land importing a kernel/framework), the contract — not the code — is wrong.
+     Split the target layer in two: a `<Layer>Api` layer whose patterns cover the
+     sanctioned entrypoints app code is meant to import (the target subtrees the
+     breakdown points at, e.g. `kernel/app/**`, `kernel/events.ts`), and keep the rest
+     as `<Layer>Internal`. Allow the edge into the surface, deny it into internals.
+     This legalizes the intended dependency while still forbidding reach-arounds — it
+     collapses a wall of false positives to ~0. This is how Ark stays compatible with a
+     DI framework: it guards the border, not the framework's insides.
+     The surface patterns overlap the internal catch-all, and that is fine: ark-check
+     resolves the MOST SPECIFIC pattern per file, so `kernel/app/**` wins over
+     `kernel/**` regardless of layer order. Where app code today reaches into internals
+     for a legitimate entrypoint, do NOT rewrite every call site: add a barrel module
+     inside the surface layer (e.g. `src/kernel/app/facade.ts`) that re-exports exactly
+     those entrypoints, then repoint the reach-around imports to the barrel. It is
+     behavior-preserving (verify with `tsc --noEmit`) and the imports are now legal.
+   - **forbiddenGlobals**: adding one to a domain layer may reveal existing
+     violations — run the check, and if there are hits, fix them (`/ark-fix`
+     patterns). If they are too numerous to fix now, freezing them in the
+     baseline is a valid stopgap but requires explicit user approval first (it
+     silences the new violations); never skip the guard because the code is
+     dirty today.
+   - **Move a file to another layer**: only a config change if the file's
+     imports are ALREADY legal under the target layer's rules. Read the file's
+     imports, resolve each to its layer, and check the target may import that
+     layer. If the file mixes concerns the target can't reach (e.g. an HTTP
+     client that also reads a persistence-layer cache, where
+     `Integration → Persistence` is denied), moving it BREAKS the contract —
+     that's a refactor (split the file so the pure part moves), not a config
+     edit. Say so instead of recommending the move; don't discover it only after
+     editing the config.
+3. **Validate** — `ark-check --root . --config ark.config.json
+   --strict-config` (strict makes config warnings fail; that's intended here).
+4. **Diff the impact** — compare violations before/after. New violations from a
+   tightening are expected: list them and fix them now if the set is small; if
+   it's large, the baseline stopgap from step 2 applies (approval required).
+
+## Related onboarding
+
+- Greenfield: adopt shape first via `/ark-architect`, `ark init --archetype`, or
+  `ark-check --apply-policy-pack enthusiast-<preset>`.
+- `ark-check --recommend --write-plan` may suggest a `policyPack` in `ark-adoption-plan.json`.
+- Brownfield: prefer `/ark-adopt` before large contract edits.
+
+## Operating rules
+
+- **Loosening the contract to silence a violation is refused by default.** If
+  the user asks for an allowed-edge whose only motivation is one red check,
+  explain the port/adapter alternative first (one plain-language paragraph) and
+  only proceed if they confirm they want the architectural exception.
+- Keep rules explicit: when adding a layer, state in the report which edges you
+  denied and why, so a novice reading it learns the dependency direction.
+- Update generated rule files if the contract summary embedded in them changed:
+  re-run `ark-check --install-agent-gates` (no `--force`; mention any
+  skipped-because-customized files).
+
+## Verify and report
+
+End with a passing strict check (or a committed baseline decision). Report:
+the exact config diff, before/after violation counts, what is now
+possible/forbidden in one sentence each, and any follow-ups.

package/templates/skills/ark-coverage.md

@@ -0,0 +1,96 @@
+---
+name: ark-coverage
+description: Audit which Ark capabilities this project isn't using and report how to close each gap, ranked by value. Autonomous — reads the repo, decides, reports.
+---
+
+# /ark-coverage — What Ark can do for you that you're not using
+
+You are auditing this project's use of the `arkgate` package. Work
+autonomously: read everything from the repo, never ask questions you can answer
+from files, and end with a ranked report.
+
+## Related onboarding
+
+- **Greenfield** (new or empty repo): low `governed.percent` → suggest `/ark-architect` or
+  `ark-check --recommend`; `ark-check --doctor` includes a "New here?" nudge with
+  `recommendCommand` / `initCommand`. Enthusiast track: `docs/enthusiast/how-to-agent-gates.md`.
+- **Brownfield** (existing messy repo): use `/ark-adopt` and `docs/brownfield-adoption.md` —
+  diagnose → classify → freeze only real debt. Do **not** send brownfield users to `/ark-architect`.
+
+## Operating rules
+
+- Gather inputs yourself: `ark.config.json`, `package.json`, `.ark-baseline.json`,
+  `.mcp.json`, `AGENTS.md`, agent config dirs (`.claude/`, `.cursor/`, `.codex/`,
+  `.windsurf/`, `.clinerules/`, `.kiro/`, `.github/`), CI workflows, and the source tree.
+  Read files with the Read tool and use targeted commands — do NOT `cat` whole
+  configs or dump the full source tree to the terminal; the report is the output,
+  not the raw files. Keep discovery quiet so the run stays readable.
+- This skill makes no changes to project files by default: produce the report,
+  then offer to apply the top recommendations. Do not modify files unless the
+  user then says yes. (Running `ark-check` may write its own scan cache under
+  `node_modules/.cache/` — that's fine; it never touches your source.)
+- Explain each gap in plain language a developer new to architecture governance
+  can follow — one sentence of "why this matters" per finding, no jargon without
+  a one-line definition.
+
+## Checklist to audit (compare repo reality against each capability)
+
+1. **Config exists and is strict-clean** — is there an `ark.config.json`? Does
+   `ark-check --root . --config ark.config.json --strict-config` pass? Run it.
+2. **Baseline ratchet** — if the check reports violations, is `.ark-baseline.json`
+   in use (`--baseline`)? An adopting codebase without a baseline blocks CI or,
+   worse, runs without the gate.
+3. **AI write gate per tool** — for every agent config dir that exists, is the Ark
+   gate wired? Claude: `PreToolUse` hook calling `ark-mcp --hook` in
+   `.claude/settings.json`. Cursor: `.cursor/mcp.json` + `.cursor/rules/ark.mdc`.
+   Codex: MCP server registered. Windsurf/Cline/Copilot/Kiro: rule file present.
+4. **Ark skills installed per tool** — do the detected tools have the `/ark-*`
+   skills (`.claude/skills/ark-*`, `.cursor/commands/ark-*.md`, etc.)? If not:
+   `ark-check --install-agent-gates`.
+5. **CI gate** — `.github/workflows/ark-check.yml` (or equivalent) present and
+   running `ark-check`? Is `--require-gates` used so missing gates fail CI?
+6. **ESLint plugin** — is `arkgate/eslint` configured for in-editor
+   feedback? (Check eslint config files.)
+7. **Domain purity** — do domain-model layers declare `forbiddenGlobals`
+   (e.g. `fetch`, `process`, `Date.now`, `Math.random`)? If domain code calls these
+   directly, recommend adding the guard.
+8. **Governed fraction (the headline honesty number)** — call the **`ark_coverage`**
+   MCP tool if the `ark` server is available, else run
+   `ark-check --root . --config ark.config.json --coverage --json`. It returns
+   `governed` (`{ classifiedFiles, totalFiles, percent }`), per-layer file counts, the
+   FULL `unclassified` list, `emptyLayers` (patterns matching nothing — usually wrong
+   globs, the #1 monorepo mistake), and `suggestions` (each ungoverned directory with a
+   PROPOSED canonical layer, or flagged as unrecognized). Lead your report with
+   `governed.percent`: **a green check over a low fraction is a false green — the
+   codebase is mostly UNCHECKED, not clean.** For every ungoverned directory, give the
+   `suggestions` layer as the fix ("classify `src/lib/repositories` → PersistenceAdapters
+   via /ark-contract"); for `unrecognized` ones, say it's the user's call. Do NOT
+   hand-roll this with `find`/`readdir`.
+9. **Concentrated violations = a contract smell, not debt** — run a normal check
+   (`ark-check … --json`) and read `summary`. If `summary.concentrated` is true (most
+   violations on one edge), flag it: the contract is probably wrong, not the code — e.g.
+   app-land reaching a framework/kernel through a sanctioned entrypoint. Recommend fixing
+   the contract (allow the edge, or split the target layer into a public surface +
+   internals — /ark-contract) over freezing the false positives.
+10. **Rule coverage** — the `--coverage --json` output lists `layersWithoutRules`:
+    layers with no rule edge at all can import anything. Flag those where the
+    dependency direction is obvious (e.g. domain → adapters should be denied).
+11. **Runtime kernel** — does the app hand-roll things the kernel ships? Grep for
+    homemade event buses, outbox tables, audit logs, workflow/saga orchestration,
+    projections. If found, point to the matching `arkgate` module
+    (event-bus, outbox, audit, workflow, projections) and `/ark-runtime`. But if the
+    repo already runs a DI/kernel framework (dcouplr, NestJS), do NOT recommend
+    replacing it — Ark governs the border around it, it doesn't supplant it.
+12. **NestJS adapters** — if `@nestjs/common` is a dependency and
+    `arkgate/nestjs` is unused, flag it.
+
+## Output format
+
+A ranked table (highest value first), then a one-paragraph summary:
+
+| # | Unused capability | Evidence in this repo | How to enable (exact command or file) |
+
+Close with: "Want me to apply the top N? I'll run the commands/diffs and finish
+with a strict `ark-check`." Apply only what the user approves, then verify with
+`ark-check --root . --config ark.config.json --strict-config` and report the
+final state.

package/templates/skills/ark-explain.md

@@ -0,0 +1,78 @@
+---
+name: ark-explain
+description: Explain this project's architecture in plain language and generate the showcase HTML report — layers, rules, coverage, gates, and why the contract exists.
+---
+
+# /ark-explain — Understand this project's architecture
+
+The user wants to understand the architecture, a specific rule, or why the gate blocked them.
+Your job is to **teach with this repo's real data** and leave a shareable visual artifact.
+
+## Always do this first (showcase report)
+
+1. Run the full HTML report (uses the real contract + coverage + gates):
+
+   ```bash
+   npx ark-check --root . --config ark.config.json --report ark-report.html
+   ```
+
+   Prefer the project's package-manager runner if gates already emit one
+   (`pnpm … exec ark-check` / `yarn` / `npx`).
+
+   This also maintains snapshots under **`.ark/reports/`**:
+   - `origin.json` / `origin.html` — frozen **first** report (start of the journey)
+   - `latest.json` / `latest.html` — every run
+   - `history/*.json` — last ~20 machine-readable points for later tooling
+
+   If origin already exists, the HTML includes **Evolution vs origin** (score, governed%,
+   violations, files per layer). Do not delete origin unless the user explicitly wants a
+   new baseline (`--reset-origin`).
+
+2. Tell the user the path to `ark-report.html` and `.ark/reports/origin.html`.
+   Mention `.ark/` should stay gitignored (Ark appends that on first report when possible).
+
+3. Optionally also run:
+
+   ```bash
+   npx ark-check --coverage
+   npx ark-check --doctor
+   ```
+
+   so your spoken explanation matches the report's governed% and operating mode
+   (SUGGEST / ADAPT / ENFORCE).
+
+The HTML report is the visual twin of this skill: architecture map, files per layer,
+dependency direction, matrix, violations, enforcement points, Ark fitness score, and a
+**Senior diagnostics** block (coupling fan-in/out, deny density, purity surface, pattern
+forensics, baseline taxonomy) for tech leads.
+
+## Spoken / written explanation
+
+1. **Load the real contract**: `ark.config.json`, `ark://manifest` if available, `AGENTS.md`.
+2. **If asked generally** ("explain the architecture"), produce a guided tour:
+   - Operating mode + governed% (honest: low coverage means green checks almost nothing).
+   - Each major layer: name, purpose, one real file from this repo, file count if known.
+   - Dependency direction in one short diagram (ASCII is fine).
+   - Enforcement points that are actually on: write gate, CI, ESLint, baseline.
+   - If a DI/kernel framework border exists, explain public surface vs internals.
+3. **If asked about a specific rule or block**, answer with: the rule, the consequence it
+   prevents, and the sanctioned fix (usually a port) — offer `/ark-fix`.
+4. **If asked "what's a port/adapter/saga…"**, two sentences + this-repo example or conventional path.
+
+## Operating rules
+
+- Prefer generating the HTML report even when the question is narrow — then zoom the prose.
+- Read-only for source code: this skill does not refactor product files (writing the report
+  HTML is fine).
+- Calibrate depth: one-rule questions get a paragraph; full tours get structure + report.
+- Every jargon term gets a one-line plain definition on first use.
+- End with:
+  - the strict check from `package.json` (or `ark-check --root . --config ark.config.json --strict-config`)
+  - `/ark-place` for "where does new code go?"
+  - the path to `ark-report.html`
+
+## Related
+
+- Onboarding: `/ark-architect`, `ark-check --recommend`, `docs/enthusiast/README.md`
+- Brownfield: `/ark-adopt`, `docs/brownfield-adoption.md`
+- Autopilot: `/ark-autopilot` after the user understands the contract

package/templates/skills/ark-fix.md

@@ -0,0 +1,96 @@
+---
+name: ark-fix
+description: Resolve Ark architecture violations at the root cause — fix the code (ports, adapters, moves), never weaken the contract. Runs ark-check, fixes, verifies.
+---
+
+# /ark-fix — Fix architecture violations properly
+
+You are resolving violations reported by `ark-check` or by the Ark write gate.
+Work autonomously end to end: diagnose, fix, verify. Do not ask the user to
+paste output you can generate yourself.
+
+## Operating rules
+
+- First action: run `ark-check --root . --config ark.config.json --json`
+  (add `--baseline .ark-baseline.json` if that file exists) to get the current
+  violation list. If the user quoted a specific gate block, start from that one.
+- **Check `summary` before fixing code.** If `summary.concentrated` is true — most
+  violations are ONE edge — the fix is almost certainly the CONTRACT, not N code
+  changes: app-land is reaching a framework/kernel through a sanctioned entrypoint,
+  or a layer needs splitting into a public surface + internals. Stop and hand off to
+  `/ark-contract`; don't port-and-adapter your way through hundreds of false
+  positives. Fix code only for the genuine, scattered minority.
+- **Fix value edges before type-only ones.** `summary` splits `valueCount` (real
+  runtime coupling) from `typeOnlyCount` (`import type …` — erased at compile time, no
+  runtime dependency). Prioritize the value edges; a `typeOnly: true` violation almost
+  always just means a type lives in the wrong layer (see the type-only pattern below).
+- **Never weaken the gate.** Do not edit `ark.config.json`, add allowed edges,
+  delete rules, or regenerate the baseline to make a violation disappear. The fix
+  lives in the code. If you become convinced the contract itself is wrong, stop
+  and say so with your reasoning — changing the contract is `/ark-contract` and a
+  human decision.
+- Take defaults silently and list them at the end. Stop only for destructive
+  moves (deleting files, rewriting public APIs).
+
+## How to fix each violation class
+
+- **Forbidden cross-layer import** (e.g. domain imports a persistence adapter):
+  invert the dependency. Define a port (interface) in the layer that needs the
+  capability, implement it in the layer that has it, and inject the
+  implementation at composition time. Read `ark://manifest` (MCP) or
+  `ark.config.json` to see which layers may see which.
+- **File in the wrong layer**: if the import is legitimate but the file lives in
+  the wrong directory, move the file to the layer it behaves like and update
+  imports. Prefer the smallest move that makes the graph legal.
+- **Forbidden global in domain** (`fetch`, `process`, `Date.now`, `Math.random`, …):
+  inject the capability. Add a port (e.g. `Clock`, `IdGenerator`, `HttpPort`)
+  with the impure implementation outside the domain, and pass it in.
+- **Intent prefix mismatch**: rename the intent to the layer's declared prefix,
+  or move the handler to the layer that owns that prefix.
+- **Type-only inversion** (a lower layer `import type`s something from an upper layer,
+  e.g. a domain module importing a type that happens to live in a UI hook): move the
+  TYPE down to the layer that owns it (e.g. `src/lib/<domain>/types.ts`), and re-export
+  it from the original module for back-compat (`export type { X } from "@/lib/<domain>/types"`)
+  so no consumer breaks. This is the highest-volume, safest adoption fix — verify with
+  `tsc --noEmit`. It often also breaks a circular dependency that ran through the hook.
+  Two cases where the move is NOT mechanical — stop and flag instead of forcing it:
+  (a) the type extends a persistence/ORM row (e.g. a Drizzle schema type) — moving it to a
+  domain layer would couple domain→Persistence (the write gate will block it), so it needs a
+  domain-owned type or port, not a move; (b) the source file mixes the type with runtime
+  logic (stubs, helpers, mock builders) — split the types into their own module first, then
+  move.
+- **Raw infrastructure access in an orchestration/UI layer** (a route/handler or component
+  that runs SQL or imports the DB client directly — e.g. `sqlClient\`SELECT …\`` or
+  `import { db } from "@/lib/db"` inside `src/app/**`): this is the value-import counterpart
+  to the type-only inversion, and the biggest brownfield cluster. Relocate the data-access
+  VERBATIM into a repository/adapter layer: add a business-named method to the repository
+  (`ordersRepository.listOpen(projectId)`) containing the SAME query byte-for-byte, and have
+  the route call it. Same SQL = same behavior by construction — do NOT rewrite the query
+  (`tsc` can't prove two queries return the same rows; a reworded `WHERE` silently changes
+  results). Prefer extending an existing domain repository over creating a new one. Two
+  cautions: (a) this edits the data layer, which many repos reserve to core maintainers —
+  if a `CLAUDE.md`/CODEOWNERS rule restricts it, migrate one route as a demonstrated pattern
+  and hand the bulk to a maintainer rather than sweeping hundreds autonomously; (b) a route
+  with interleaved transactions / 10+ queries is not a pure relocation — flag it for review.
+  See the brownfield burn-down playbook (`docs/brownfield-adoption.md`) for the full sequence.
+
+Fix ALL reported violations that share a root cause in one pass — one port in a
+shared module beats N per-file patches. Match the codebase's existing naming and
+port conventions before inventing new ones.
+
+## Related onboarding
+
+- Prefer `fixClass` / `enthusiastHint` from `ark-check --json` when present.
+- Brownfield burn-down: `/ark-adopt` first; demo `docs/demos/02-brownfield-baseline-adoption.md`.
+- Greenfield: `/ark-architect` prevents many violations before they exist.
+
+## Verify and report
+
+After edits, run `ark-check --root . --config ark.config.json --strict-config`
+(plus the project's test command if one exists in `package.json`). If the check
+still fails, keep fixing — do not end the turn with a red check unless you are
+blocked on a genuine contract question.
+
+Report: violations fixed (before → after count), what pattern you applied
+(in plain language — assume the reader may not know what a "port" is: one line
+of definition), defaults taken, anything intentionally left for the user.

package/templates/skills/ark-loop.md

@@ -0,0 +1,69 @@
+---
+name: ark-loop
+description: Drive Ark's remediation plan to a clean architecture — a safe, reversible apply loop. Auto-applies only the changes Ark classes mechanical-safe (validating each with ark-check and rolling back regressions), proposes the judgment ones for your decision, and never weakens the gate. Autonomous within those limits.
+---
+
+# /ark-loop — Drive the plan to a clean architecture (safely)
+
+This is the co-pilot's **loop** primitive: read Ark's classified **plan**, work toward the
+**goal** (zero active violations without weakening the contract), one small step at a time,
+validating every change with `ark-check` and rolling back anything that fails or regresses.
+
+**The rule that makes this safe:** you (the agent) make edits; **Ark decides whether they're
+allowed to land.** Only changes Ark classed `mechanical-safe` are auto-applied. Everything
+`judgment` is PROPOSED for a human decision — never applied silently. Code only: never touch
+DB schemas, migrations, or generated files.
+
+If Ark isn't set up yet, run `ark start` (or `ark-check --recommend` then `ark init`) first.
+
+## Steps
+
+1. **Read the plan.** Run `ark-check --plan --json` (add `--baseline .ark-baseline.json` if the
+   repo uses a baseline). It returns `goal` (with `met`, `activeViolations`, `autoApplicable`,
+   `needsDecision`, `deferred`) and `steps[]`, each tagged `class` (`mechanical-safe` /
+   `judgment` / `deferred`) with a `confidence` and a plain-language `rationale`. If
+   `goal.met` is already true, report "nothing to do" and stop.
+
+2. **Work in a discardable git worktree.** Create one (`git worktree add`) so the entire run is
+   reversible and never disturbs the user's working tree. Do all edits there. Nothing is
+   permanent until the user reviews the final diff.
+
+3. **Apply the `mechanical-safe` steps, one at a time, validated.** For each such step
+   (e.g. a type-only import moved to the layer that owns it + a re-export for back-compat):
+   - Record the current active-violation count from the plan.
+   - Make the edit at the SOURCE (fix the placement; don't add an `ark-*-disable` or edit the
+     baseline/config to hide it).
+   - Re-run the gate: `ark-check --root . --config ark.config.json --strict-config`
+     (or `ark-check --baseline` in ratchet repos). **Keep** the change only if the targeted
+     violation is gone AND no NEW violation appeared. Otherwise **roll it back**
+     (`git checkout -- <files>`) and mark the step deferred with a one-line reason.
+
+4. **Propose the `judgment` steps — do not auto-apply.** For each, present in plain language:
+   what it is, the `rationale`, and a concrete proposed approach (e.g. "move this data access
+   into a repository," "inject a Clock port"). Apply only the ones the user approves, each with
+   the same validate-or-rollback discipline. Repository organization and cross-module refactors
+   are the user's call.
+
+5. **Loop until dry.** Re-read `ark-check --plan --json` after a round — fixing one edge can
+   change others. Repeat step 3 while new `mechanical-safe` steps appear and progress is being
+   made. Stop when `goal.met` is true, or when a round applies nothing new (no-progress), or
+   when only `judgment`/`deferred` steps remain.
+
+6. **Report honestly.** Show the final diff and a summary: what was AUTO-APPLIED (validated),
+   what is PROPOSED (awaiting your decision), and what was DEFERRED (and why). Never report a
+   clean/green result while steps were skipped. Only merge the worktree back after the user
+   reviews. When invoked from **`/ark-autopilot`**, the parent skill already owns the
+   before/after HTML reports (`--report` + `.ark/reports/` origin/latest). If you are running
+   standalone and the user wants a visual close-out, end with
+   `ark-check --report ark-report.html` so evolution vs origin is updated.
+
+## Operating rules
+
+- Never weaken the gate to make the loop finish: no disabling rules, editing
+  `ark.config.json` to allow a bad edge, or baselining a fresh violation. Fix the code, or
+  propose a contract change via `/ark-contract` with its before/after impact.
+- If most violations concentrate on one edge, that's a contract smell, not N fixes — stop the
+  loop and hand off to `/ark-contract` (a broad `--plan` will show the concentration).
+- `mechanical-safe` is deliberately narrow. When unsure whether a change preserves behavior,
+  treat it as `judgment` and propose it. A wrong auto-apply costs more than an extra click.
+- Verify with the gate, not by eye: a step counts as done only when `ark-check` confirms it.

package/templates/skills/ark-place.md

@@ -0,0 +1,68 @@
+---
+name: ark-place
+description: "Where does new code go? Names the layer, directory, and naming for a new artifact from the contract, and scaffolds it there. Autonomous."
+---
+
+# /ark-place — Where does this code go?
+
+The user describes something they need to build (a saga, a background job, an
+event handler, a repository, an HTTP client, a use case, a projection, …).
+Your job: name the layer it belongs to, the directory, the naming convention,
+and — if they asked to build it — scaffold it there correctly.
+
+**No artifact given?** If the skill is invoked with nothing to place, don't error
+and don't guess — the artifact is the one thing only the user knows. Read the
+contract (step 1) and print the placement map from it: one row per declared layer
+with what belongs there, its directory, and which layers it may/may not import,
+plus the not-yet-adopted `suggestedLayers` as a footnote. Then ask what they want
+to place. That map is derived entirely from the repo, so producing it is real work,
+not a stalling question.
+
+## Steps
+
+1. **Read the contract, not your intuition.** If the `ark` MCP server is available,
+   call the **`ark_place`** tool with the target file path — it returns the layer,
+   its forbidden globals, and exactly which layers the file may / must not import,
+   straight from the contract (no guessing). Otherwise load `ark.config.json` and the
+   `ark://manifest` MCP resource (it includes `suggestedLayers` with conventional
+   directories for layers not yet adopted). The project's `AGENTS.md` placement table,
+   if present, is authoritative too.
+2. **Classify the artifact** by what it does, not what it's called:
+   - Pure business rules/entities/value objects → domain-model layer.
+   - Orchestrates a use case, no I/O of its own → application layer.
+   - Talks to a database, queue, API, filesystem → an adapter layer on the side
+     that matches the direction (driven/persistence vs driving/http).
+   - Reacts to events, long-running coordination (saga/workflow), scheduled
+     jobs, projections → the event/workflow layers if the config declares them.
+3. **Answer concretely**: layer name, target directory (from the layer's
+   `patterns`), intent-name prefix if the layer declares `intentPrefixes`, and
+   which layers it may/may not import (from `rules`).
+4. **If the layer isn't adopted yet** (suggested but no directory): say so,
+   give the conventional directory from `suggestedLayers`, and offer
+   `/ark-contract` to adopt it — don't silently drop the code into a
+   wrong-but-existing layer.
+5. **If asked to create it**: scaffold the file(s) in place, following the
+   nearest existing sibling's style, and any port/adapter split the rules force.
+
+## Operating rules
+
+- Never ask "which layer do you prefer?" — the contract decides; you translate.
+  Only surface a question when the artifact genuinely spans two legal designs
+  with different trade-offs, and then recommend one.
+- Explain the placement in one plain-language sentence ("this goes in
+  `src/domain` because it's a business rule that shouldn't know about the
+  database") — assume the user may be new to layered architecture.
+
+## Related onboarding
+
+- Run **after** shape adoption: `/ark-architect` or `ark init --archetype` on greenfield;
+  `/ark-adopt` on brownfield.
+- `ark-check --recommend` / MCP `ark_recommend` picks phase-1 dirs; gallery starters in
+  `examples/*-starter/` show correct placement per archetype.
+- Related demos: `docs/demos/` (write-gate self-correction, brownfield, autopilot).
+
+## Verify and report
+
+If you created files, run `ark-check --root . --config ark.config.json
+--strict-config` and make it pass. Report: placement + why, files created (if
+any), and the import rules the new code must respect going forward.