arkgate 2.6.0 → 2.7.0

package/docs/agent-guide.md

@@ -64,6 +64,69 @@ npx ark-check --watch                           # debounced re-check when govern
 `enthusiastHint` (plain English). `--doctor --json` exposes `doctor.newHere` with
 `recommendCommand` and `initCommand` when the nudge applies.
 
+### Deploy-path quality (lint/types before the host build)
+
+Some frameworks run **ESLint and/or typecheck inside the production build** (Next.js by
+default: “Linting and checking validity of types”). Architecture can be green while the
+**deploy host** is the first place a `no-explicit-any` or unused-import error appears.
+
+Ark does **not** reimplement general ESLint rules. `--doctor` / adoption gaps **do**
+detect, for **any** consumer repo (framework signals only — deps, scripts, CI files):
+
+| Gap id | When |
+|--------|------|
+| `deploy-path-lint-script-missing` | Build embeds ESLint; no `lint` / `eslint` script |
+| `deploy-path-lint-not-in-ci` | Lint script exists; CI workflows never run it |
+| `deploy-path-lint-no-ci` | Build embeds ESLint; no CI workflows at all |
+| `deploy-path-typecheck-script-missing` | Build typechecks; no `typecheck` script |
+| `deploy-path-typecheck-not-in-ci` | Typecheck script exists; CI never runs it |
+
+Respects `eslint.ignoreDuringBuilds: true` in `next.config.*`. Recommended pre-merge
+order (universal): `lint` → `typecheck` → `arkgate-check` / `check:architecture` → `build`.
+
+### Empty scope, include roots, and contract adopt
+
+When `include` matches **zero** TS/JS files, plan/doctor treat that as **not done**
+(`goal.emptyScope`, adoption gap `empty-scope`) — never “clean architecture.”
+
+```bash
+npx ark-check --suggest-include --json    # workspaces + nested package.json+TS roots
+npx ark-check --adopt-contract --write  # expand include + UI patterns (no rule weakening)
+npx ark-check --coverage
+```
+
+Polyglot repos: Ark only governs TypeScript/JS. Point include at package roots that have sources.
+
+### Presets
+
+- `hexagonal` / `layered` / `feature-sliced` / `monorepo` / **`ui-surface`** (UI/Vite/Remotion-style hooks+lib+routes+components)
+
+### Cycle policy
+
+```json
+{ "cyclePolicy": "strict" }
+```
+
+- `strict` (default): value cycles fail the check  
+- `soft` / `framework-soft`: value cycles are **warnings** only  
+- `off`: skip cycle detection  
+
+Type-only edges never form cycles (codegen-safe).
+
+### Generated files and type-only cycles
+
+By default Ark **does not scan** common codegen paths:
+
+- `**/*.gen.ts`, `**/*.gen.tsx`
+- `**/*.generated.ts`, `**/*.generated.tsx`
+
+Override with `"excludeGenerated": false` or extend with top-level `"exclude": ["**/vendor/**"]`
+in `ark.config.json`.
+
+**Circular dependencies** are computed on **value/runtime** import edges only. A cycle
+closed solely by `import type` (common with generated route trees) is **not** reported as
+`CIRCULAR_DEPENDENCY`. Value cycles still fail.
+
 ### MCP `ark_recommend` and `/ark-architect` (Phase C)
 
 The `ark-mcp` server exposes **`ark_recommend`** — same JSON as
@@ -146,7 +209,7 @@ projections, metadata, workflow engine, and 11-layer architecture profile:
 ```ts
 import {
   createStrictArkKernel,
-} from 'arkgate';
+} from 'arkgate/runtime';
 
 const ark = createStrictArkKernel();
 // ... define intents, event contracts, metadata, projections, and workflows through ark.*
@@ -156,6 +219,9 @@ const contract = ark.manifest().toJSON();
 // contract.observability, projections
 ```
 
+Prefer `arkgate/runtime` for the optional kernel (root `arkgate` still re-exports for
+compat). Package surface policy: [package-surface.md](package-surface.md).
+
 Agents should read `contract` and `ark.observability.report()` before generating or modifying code.
 
 ## Naming Conventions

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

@@ -131,7 +131,8 @@ Or edit `.grok/config.toml` → `args` use `arkgate-mcp`.
 
 ```diff
 - import { createStrictArkKernelFromConfig } from 'ark-runtime-kernel';
-+ import { createStrictArkKernelFromConfig } from 'arkgate';
++ import { createStrictArkKernelFromConfig } from 'arkgate/runtime';
+  // root `arkgate` still re-exports kernel symbols this major (compat)
 
 - import { ArkModule } from 'ark-runtime-kernel/nestjs';
 + import { ArkModule } from 'arkgate/nestjs';
@@ -140,7 +141,8 @@ Or edit `.grok/config.toml` → `args` use `arkgate-mcp`.
 + import ark from 'arkgate/eslint';
 ```
 
-If you only used the CLI + MCP (most projects), **no import changes**.
+If you only used the CLI + MCP (most projects), **no import changes**.  
+Surface policy: [package-surface.md](package-surface.md).
 
 ---
 

package/docs/package-surface.md

@@ -0,0 +1,72 @@
+# ArkGate package surface policy
+
+**Product wedge:** write gate · CI gate · co-pilot (plan / loop / skills).  
+**Not the wedge:** the optional in-process runtime kernel.
+
+This document is the consumer contract for **what is stable** vs **what is opt-in**.
+
+---
+
+## Stable surfaces (semver-supported)
+
+| Surface | How you use it | Stability notes |
+|---------|----------------|-----------------|
+| **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 | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
+| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve. |
+| **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
+| **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | Inputs for running the check stay stable within a major. |
+
+Gates need **no application code imports**. Most projects only use the CLI + MCP + config.
+
+---
+
+## Opt-in surfaces
+
+| Surface | Import path | Notes |
+|---------|-------------|--------|
+| **Runtime kernel** | **`arkgate/runtime`** (preferred) | Event bus, intents, policies, sagas, outbox, projections, `createArkKernel` / strict helpers. Optional. Not required for architecture enforcement. |
+| **Root package barrel** | `arkgate` | Still re-exports the runtime kernel for **compatibility**. Prefer `arkgate/runtime` for new code. Root may be thinned in a future **major**. |
+| **NestJS adapter** | `arkgate/nestjs` | Optional peer `@nestjs/common`. Wires a kernel into Nest DI. |
+
+---
+
+## Recommended imports
+
+```ts
+// Preferred — opt-in runtime kernel
+import {
+  createStrictArkKernel,
+  createStrictArkKernelFromConfig,
+} from 'arkgate/runtime';
+
+// Still works this major (compat; not preferred for new code)
+import { createStrictArkKernel } from 'arkgate';
+
+// Nest adapter
+import { ArkModule, InjectArk } from 'arkgate/nestjs';
+```
+
+See [production-hardening.md](./production-hardening.md) for runtime operational guidance.
+
+---
+
+## Explicitly unstable / internal
+
+- `bin/lib/*` module layout and private helpers  
+- Generated `bin/ark-layer-match.mjs` (edit canonical `src/domain/layerMatch.ts` only)  
+- HTML report DOM structure (unless documented as a machine contract)  
+- Internal MCP diagnostic fields not listed in agent-guide  
+
+---
+
+## Versioning summary
+
+| Change | Version bump |
+|--------|----------------|
+| 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) |

package/docs/production-hardening.md

@@ -1,5 +1,8 @@
 # Production Hardening
 
+The optional runtime kernel is imported from **`arkgate/runtime`** (preferred). See
+[package-surface.md](package-surface.md).
+
 Ark's built-in stores are intentionally in-memory defaults. They are appropriate for tests,
 local development, examples, and single-process demos. Production systems should provide
 stores that match their durability, ordering, retention, and operational requirements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "require": "./dist/runtime/index.cjs"
+    },
     "./eslint": {
       "types": "./dist/eslint/index.d.ts",
       "import": "./dist/eslint/index.js",
@@ -46,6 +51,7 @@
     "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
+    "docs/package-surface.md",
     "docs/production-hardening.md",
     "tests/fixtures/ts-consumer",
     "templates",
@@ -63,6 +69,10 @@
     "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-config",
+    "generate:layer-match": "node scripts/generate-layer-match.mjs",
+    "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",
     "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",
     "eval:agent": "node eval/run.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",

package/server.json

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

package/templates/skills/ark-adopt.md

@@ -1,103 +1,59 @@
 ---
 name: ark-adopt
-description: Onboard an existing codebase onto Ark — get the contract to reflect reality, classify ungoverned code, then freeze only genuine debt with a plan. Autonomous.
+description: Brownfield onboarding — match contract to real code, classify ungoverned dirs, mine loose business rules into the Ark manifest/intents, freeze only real debt. Deep source analysis required.
 ---
 
 # /ark-adopt — Bring Ark into an existing codebase
 
-You are onboarding this repository onto Ark. The goal is NOT "make the check
-green" — it is to leave the project with a contract that reflects its real
-architecture, most of the code actually governed, and only genuine debt frozen
-with a plan to burn it down. A green check over a wrong contract or an ungoverned
-tree is a FALSE green — worse than no gate, because it looks safe. Work autonomously.
+Goal: contract reflects reality, most code governed, only genuine debt frozen with a burn-down.
+A green check over a wrong contract is a **false green**.
 
-Commands below are written as `ark-check` / `ark`; run each through the project's
-package manager — `pnpm exec ark-check …` in a pnpm repo, `yarn ark-check …` in a
-yarn repo, `npx ark-check …` under npm. Match the lockfile; never hardcode `npx` in
-a pnpm/yarn repo (AGENTS.md shows the exact runner for this project).
 
-## The guiding principle
+## Related onboarding
+
+- **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+
+## Anti-wrapper rule (mandatory)
+
+**Forbidden:** only running `--init` / `--update-baseline` / coverage JSON without reading the tree.
+
+**Required:**
+1. CLI sensor: `--coverage --json`, check `--json` (`summary`), doctor.
+2. **Read real source** in largest ungoverned dirs and top import edges (min **10 files**).
+3. **“Así te lo re-soluciono”** — concrete layer globs, file moves, and manifest/intent proposals.
+4. Never freeze a concentrated edge without investigating contract smell.
 
-**Ark protects the boundary AROUND a framework, not its internals.** If the repo
-uses a DI/kernel framework (dcouplr, NestJS, a custom kernel), do NOT try to govern
-its inside — declare its PUBLIC SURFACE (the entrypoints app code is meant to
-import) as one layer and treat the rest as a black box. Governing the internals
-duplicates the framework's own wiring and fights it.
+## Guiding principle
+
+Ark protects the **boundary around** a framework, not its internals. Nest/DI public surface = one layer; internals black box.
 
 ## Steps
 
-1. **Config** — if `ark.config.json` is missing, run `ark-check --init`. It detects
-   the layer directories that exist, writes a config for them, and PROPOSES a layer
-   for every ungoverned directory (sourced from the 11-layer profile + presets),
-   flagging the ones it cannot place. If a config exists, keep it — don't regenerate
-   unasked.
-
-2. **Check + DIAGNOSE — before you freeze anything** — run
-   `ark-check --root . --config ark.config.json --json` and read `summary`: it groups
-   violations by edge, ranked. The critical signal is `summary.concentrated` /
-   `dominantShare`: **when most violations are a single edge, the CONTRACT is almost
-   always wrong, not the code.** (Real case: hundreds of API routes "violating"
-   app→kernel because the framework's own `defineRoute` is the sanctioned entrypoint
-   — false positives, not debt.) Investigate the dominant edge:
-   - App-land reaching a framework/kernel through a legitimate entrypoint → fix the
-     contract (step 3), do NOT freeze it.
-   - Unrelated layers genuinely importing each other → real debt for the baseline.
-
-3. **Make the contract reflect reality (via /ark-contract) BEFORE freezing:**
-   - **Classify the ungoverned tree.** Run `ark-check --coverage --json`; read
-     `governed.percent` and `suggestions`. If Ark governs a minority of the code, a
-     green check means almost nothing. Add the proposed layers for the recognized
-     directories; decide a layer for the ones flagged "unrecognized". Get `governed`
-     high before trusting any check.
-   - **Fix a concentrated edge at its source.** If the dominant edge is intended,
-     either allow it or — better — split the target layer into a PUBLIC SURFACE (the
-     entrypoints app code may import) and INTERNALS (denied). The breakdown's target
-     subtrees show where the surface is. This facade split turns a wall of false
-     positives into ~0 while still forbidding reach-arounds into internals.
-   Re-run the check; the remainder should now be the genuine minority.
-
-4. **Freeze the genuine debt** — run `ark-check --update-baseline`. If the set is
-   still lopsided on one edge, Ark REFUSES and tells you the contract still looks
-   wrong — heed it and return to step 3; do NOT `--force` past it just to get green.
-   On success it writes `.ark-baseline.json`; tell the user to commit it (don't commit
-   for them). From now `ark-check --baseline` fails only on NEW violations — the
-   ratchet only moves toward zero (fixing a frozen violation shrinks the baseline).
-
-5. **Gates + skills everywhere** — run `ark-check --install-agent-gates`. It
-   auto-detects the agent CLIs in the repo and writes the write gate, rule files,
-   package-manager-aware CI workflow, and the `/ark-*` skills for each (Kiro gets
-   only its steering rule; Copilot only via `--tools copilot`). If a baseline was
-   created, the generated CI already carries `--baseline`. For Codex, prompts load
-   from `$CODEX_HOME/prompts`, not the repo — install there too with
-   `ark-check --install-agent-gates --codex-home` (writes to their home dir; say so).
-
-6. **Ratchet plan** — from `summary.edges` (ranked), write a short prioritized
-   burn-down: which edge/cluster to fix first (biggest, or the one on the
-   most actively-edited files per `git log`), that `/ark-fix` resolves each, and
-   which items are real debt vs. deferred contract decisions.
-
-## Operating rules
-
-- Explain each step's WHY in one plain sentence — this is often the user's first
-  contact with Ark. Define jargon inline ("baseline = the list of violations that
-  existed before Ark, frozen so they don't block you while you fix them over time").
-- Do NOT chase green by freezing false positives or loosening the contract blindly.
-  The order is: contract reflects reality → classify → freeze only what's left.
-  Getting to green the wrong way is the exact failure this skill exists to prevent.
-- Don't overwrite customized files (`--force`) unless asked. Don't adopt the runtime
-  kernel here (that's `/ark-runtime`) — a repo with its own DI framework should keep it.
+1. **Config** — missing → `ark-check --init` (detection). Keep existing unless asked to regenerate.
+2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
+3. **Classify ungoverned** — use coverage `suggestions`; add layers/patterns via `/ark-contract`.
+4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
+   - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
+   - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used.
+   - Apply config through `/ark-contract` discipline; move pure rules into Domain when safe; validate with ark-check.
+   - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
+5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
+6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
+7. **Ratchet plan** — ranked edges + which are false positives avoided.
 
-## Related onboarding
+## Operating modes
+
+Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
+
+## Verify
 
-- **This skill is for brownfield** — existing messy repos. Do **not** use `/ark-architect` here.
-- Greenfield users: `/ark-architect`, `ark-check --recommend`, gallery starters (`examples/README.md`).
-- Demo: `docs/demos/02-brownfield-baseline-adoption.md`. Playbook: `docs/brownfield-adoption.md`.
-- Violation JSON may include `fixClass`, `effort`, `enthusiastHint` for burn-down ordering.
+`ark-check --root . --config ark.config.json --strict-config` (+ baseline only if non-empty file retained).
+Report: governed% before/after, files written, frozen count, false positives avoided, manifest/intent proposals applied or deferred.
 
-## Verify and report
+## Never
 
-Finish with `ark-check --root . --config ark.config.json --strict-config
---baseline .ark-baseline.json` (omit `--baseline` if none) — it must pass. Report:
-governed % before/after, files written, violations frozen (and how many false
-positives you AVOIDED freezing by fixing the contract), the ratchet plan, and the
-commands the team needs (`check`, `/ark-fix`, `/ark-coverage`).
+- Freeze false positives to get green.
+- Force runtime kernel over existing Nest/DI.
+- Claim Enforce while governed% is low or core bags ungoverned.

package/templates/skills/ark-autopilot.md

@@ -1,97 +1,59 @@
 ---
 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.
+description: End-to-end architecture co-pilot — setup, deep plan from real code, apply mechanical-safe fixes, design and apply judgment fixes when the user asks for full apply. CLI is a sensor; you remediate files.
 ---
 
 # /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."
+Composes **setup + plan + loop**. Safe default: auto-apply only `mechanical-safe`;
+when the user says full apply / “al mango” / apply everything, also execute
+**judgment** fixes you design from reading source (still validate with ark-check,
+never weaken the gate).
 
-**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
+## Related onboarding
 
-**Who is driving** (entry style):
+- **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
-- **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.
+## Anti-wrapper rule (mandatory)
 
-**What Ark is doing right now** (operating mode — read from `ark start` / `--plan` / `--coverage`):
+**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without reading the violating files.
 
-- **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.
+**Required:**
+1. CLI sensor: `ark-check --plan --json`, coverage/doctor as needed.
+2. **Open every file** in the plan’s `steps[]` (and its `target` if present) before classifying a fix.
+3. **“Así te lo re-soluciono”** for each cluster of steps: exact moves (extract type, relocate file, invert dependency).
+4. Apply → re-run ark-check → rollback on regression.
 
-Never tell a user "your architecture is guarded" while `--plan` reports `goal.met: false` or
-`governedPercent` is low.
+## Operating modes (detected, not picked)
 
-## Flow (newbie tier)
+- **Setup (Suggest):** no config → `ark start` / recommend shape.
+- **Align (Adapt):** open debt or low honesty → drive loop; do not claim “guarded”.
+- **Guard (Enforce):** `goal.met` and solid governed% → install/confirm gates and stop.
 
-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.
+## Flow
 
-2. **Freeze / confirm the starting picture.** Always run once before changing code:
+1. **Setup if needed** — `ark start` if no `ark.config.json`.
+2. **Origin report** — `ark-check --report ark-report.html` (do not `--reset-origin` unless asked).
+3. **Plan + code read** — `--plan --json`; read each step’s source/target; group by edge.
+4. **Concentrated edge?** — if one edge dominates, route to `/ark-contract` with a **source-based** diagnosis (not freeze).
+5. **Worktree preferred** — discardable git worktree when possible.
+6. **Mechanical-safe** — only kinds from `/ark-loop` table; one step, validate, rollback.
+7. **Judgment** — default: propose with full “así te lo re-soluciono”. If user authorized full apply: implement the designed fix, validate, rollback on fail.
+8. **Manifiesto** — if loose business rules surface (domain logic in UI/core), propose Domain placement + `intentPrefixes` / intents; apply config only via `/ark-contract` discipline (strict check after).
+9. **Final report** — `--report` again; evolution vs origin; honest summary of auto vs judgment vs deferred.
+10. **Strict check** — `ark-check --strict-config` (dead preset globs are advisory; real violations still fail).
 
-   ```bash
-   npx ark-check --root . --config ark.config.json --report ark-report.html
-   ```
+## Never
 
-   - 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.
+- Disable rules, broaden allows, or baseline **new** debt to “finish”.
+- Claim clean while judgment steps were skipped without user decision.
+- Replace host Nest/DI with the runtime kernel unasked.
 
-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). Safe auto steps are only the three `mechanical-safe` kinds:
-   type-only type move, pure-type **file** relocate, and converting static imports of pure-type
-   modules to `import type` (see `/ark-loop`). Confirm before changing anything.
+## Done criteria
 
-4. **Drive the loop.** Hand off to **`/ark-loop`**: in a discardable git worktree, auto-apply
-   the `mechanical-safe` steps one at a time (match each `remediationKind`; 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.
+- Every applied step validated by real `ark-check`.
+- Final plan `goal.met` true **or** remaining steps listed with file-level proposals and why blocked.
+- Report cites paths you changed and reports HTML paths.