arkgate 2.6.0 → 2.6.1

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.6.0",
+  "version": "2.6.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.6.0",
+      "version": "2.6.1",
       "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.

package/templates/skills/ark-contract.md

@@ -1,98 +1,57 @@
 ---
 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.
+description: Safely edit ark.config.json (layers, rules, forbiddenGlobals, intent prefixes) and land business rules into the Ark manifest. Validated with strict ark-check. Deep source evidence required.
 ---
 
-# /ark-contract — Evolve the architecture contract safely
+# /ark-contract — Change 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.
+The **one sanctioned way** to change layers/rules/`intentPrefixes`/includes.
+Also used to **land mined business rules** into the executable manifest (`ark.config.json` + intent naming that `ark://manifest` exposes).
 
-**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
+## Related onboarding
 
-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).
+- **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`.
 
-## Related onboarding
+## Anti-wrapper rule (mandatory)
+
+**Forbidden:** editing globs from vibes without reading the directories those globs claim to cover.
+
+**Required:**
+1. Snapshot before using CLI as **sensor**: coverage + check JSON.
+2. **Read source** in dirs you reclassify (sample files).
+3. **“Así te lo re-soluciono”** — exact JSON fields + which files become governed/ungoverned.
+4. After write: `ark-check --strict-config` must be the validation gate (dead pattern noise is advisory; unclassified + real violations still matter).
+
+## What you may edit
+
+- `include` / `exclude`
+- `layers[]` (`name`, `patterns`, `optional`, `forbiddenGlobals`, `intentPrefixes`, layer `exclude`)
+- `rules[]` (from/to/allowed)
+- Never: disable the check, delete CI gates, or add blanket `allowed: true` for a bad edge without a facade design
+
+## Steps
 
-- 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.
+1. **Snapshot** — coverage governed%, unclassified samples, current violations.
+2. **Smallest edit** for the user intent:
+   - New layer + neighbor rules
+   - Expand patterns for ungoverned dirs (`suggestions` from coverage)
+   - Facade: public surface patterns more specific than internals
+   - **Business rules → manifiesto:**
+     - Add/adjust `intentPrefixes` (`Domain.`, `Application.`, …)
+     - Point Domain patterns at real pure folders (`**/domain/**`, not bare `**/types.ts`)
+     - Document proposed intent names for the app to register (kernel) or for agents to use
+3. **Impact** — re-run coverage/check; report before/after governed% and violation delta.
+4. **Rollback** if strict fails for reasons other than pre-existing debt the user accepted.
 
-## Operating rules
+## Operating modes
 
-- **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).
+Contract edits are most common in **Align (Adapt)**. In **Guard (Enforce)**, treat edits as high-risk product decisions.
 
-## Verify and report
+## Done
 
-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.
+- Diff of `ark.config.json` explained in plain language.
+- **Así te lo re-soluciono en el manifiesto** when intents/Domain were part of the request.
+- Strict check result captured.