arkgate 2.6.0 → 2.7.0

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.

package/templates/skills/ark-coverage.md

@@ -1,96 +1,75 @@
 ---
 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.
+description: Deep-audit this project's real code + Ark adoption gaps. CLI is a sensor only — you must read source, propose concrete remediations, and optional manifest/intent mining. Ranked report with "así te lo re-soluciono".
 ---
 
-# /ark-coverage — What Ark can do for you that you're not using
+# /ark-coverage — Deep coverage + capability gaps
 
-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.
+You audit how this repo uses ArkGate **and** what the **real source tree** needs next.
+Work autonomously. End with a ranked report that includes a concrete fix plan.
+
+## Anti-wrapper rule (mandatory)
+
+**Forbidden:** reporting only `ark-check --coverage/--doctor/--json` paraphrase, gate checklists, or "unused capability" tables with no source evidence.
+
+**Required before you finish:**
+1. Run CLI as **sensor** (`--coverage --json`, `--doctor`, normal `--json` for `summary`).
+2. **Read real source** in the top ungoverned / high-coupling clusters (minimum **8 files** across at least **3 directories** that matter). Prefer `src/core/**`, `domain/**`, adapters, etc.
+3. Deliver **“Así te lo re-soluciono”** — file-level moves, contract globs, intent/manifest proposals, not only “run /ark-contract”.
+
+If you did not open source files, the skill is **not complete**.
+
+## Operating modes (detected — not user-picked)
+
+| Mode | User meaning | What you tell them |
+|------|----------------|--------------------|
+| **Suggest / Setup** | Thin or new tree | “Ark will propose a starting shape — you don’t switch a mode.” |
+| **Adapt / Align** | Contract ≠ folders or open debt | “Gates don’t fully protect you yet — classify + fix plan.” |
+| **Enforce / Guard** | Coverage + clean edges | “You arrived here — keep CI/write gates on.” |
+
+Never say “your architecture is guarded” while `goal.met` is false or governed% is low.
 
 ## 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.
+- **Greenfield:** low governed% → `/ark-architect` or `ark-check --recommend`.
+- **Brownfield:** `/ark-adopt` + this skill’s deep map — **not** `/ark-architect`.
+- **Business rules / intents loose in the tree:** also cover in **Así te lo re-soluciono** (mine → `intentPrefixes` / Domain placement / kernel `defineIntent` stubs). Full apply path is `/ark-adopt` or `/ark-contract` deep mode.
+
+## Checklist (sensor + code)
+
+1. Config + `ark-check --strict-config` (note: dead preset globs are advisory; unclassified files still fail strict).
+2. Baseline policy (orphan empty file? wire or delete).
+3. Write gates + `/ark-*` skills per detected agent.
+4. CI workflow + monorepo install reality (`frontend/package.json`?).
+5. ESLint `arkgate/eslint` if ESLint exists.
+6. Domain `forbiddenGlobals`.
+7. **Governed%** + full unclassified + `suggestions` from `--coverage --json`.
+8. Concentrated edges in check `summary` → contract smell, not N freezes.
+9. `layersWithoutRules`.
+10. Runtime kernel / Nest only if deps prove it — never force-fit Next+Python.
+
+## Deep code pass (the model job)
+
+For each top cluster (e.g. `frontend/src/core/threads`, `components/workspace`):
+
+- Who imports whom (App→Presentation? Domain→App?).
+- Is “core” really application, UI, or mixed?
+- Loose business logic: `calculate*`, `can*`, `validate*`, policy numbers, publish/intent strings without registry.
+- Propose: layer home, `ark.config.json` patterns, optional Domain extract, intent names (`Domain.*` / `Application.*`).
 
 ## Output format
 
-A ranked table (highest value first), then a one-paragraph summary:
+1. **Headline honesty** — governed%, mode, violations, false-green risk (one paragraph).
+2. **Code map** — clusters you read + what you found (paths).
+3. **Ranked table**
+
+| # | Gap | Evidence (path or CLI) | Así te lo re-soluciono (concrete) |
+
+4. **Manifiesto / reglas de negocio** (if any candidates): list proposed intents / Domain files / config edits.
+5. Offer: “Apply top N?” — apply only if user agrees; then re-run strict check.
 
-| # | Unused capability | Evidence in this repo | How to enable (exact command or file) |
+## Done criteria
 
-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.
+- ≥8 source files read and cited.
+- At least one **Así te lo re-soluciono** block with real paths.
+- CLI numbers used as evidence, not as the whole report.

package/templates/skills/ark-fix.md

@@ -1,100 +1,55 @@
 ---
 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.
+description: Resolve Ark architecture violations at the root cause — ports, adapters, moves, intent/manifest alignment. Never weaken the contract. Read the real code; CLI only validates.
 ---
 
-# /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** (`typeOnly: true` on a `LAYER_IMPORT_VIOLATION` — plan class
-  `mechanical-safe`, `remediationKind: type-only-import-move`): a lower layer `import type`s
-  something from an upper layer (e.g. domain importing a type that lives in a UI hook). Move the
-  TYPE down to the layer that owns it and re-export for back-compat
-  (`export type { X } from "@/lib/<domain>/types"`). Highest-volume safe fix — verify with the
-  gate (and `tsc --noEmit` if present). Not mechanical if: (a) the type extends a persistence/ORM
-  row — needs a domain-owned type/port; (b) the source mixes types with runtime logic — split
-  first, then move (or use pure-type file relocate when the *whole file* is type-only).
-- **Pure-type file relocate** (`sourcePureTypeModule` + type-only edge —
-  `remediationKind: pure-type-file-relocate`): the entire source file is type-surface only (no
-  runtime statements). Relocate the **file** to the owning layer (or extract the type module
-  there). Behavior-preserving; do not invent runtime ports.
-- **Value-syntax import of a pure type-only module** (`targetTypeOnlyExports` —
-  `remediationKind: import-type-from-pure-type-module`): convert static `import { T } from …`
-  to `import type { T } from …`. Never auto-apply for `require()` / dynamic `import()` (those stay
-  judgment — they still execute the module).
-- **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.
+# /ark-fix — Fix architecture violations at the root
+
+You fix violations Ark reports. Prefer structural fixes over silencing the gate.
+
 
 ## 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.
+- **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 listing violations from JSON without reading importers/targets.
+
+**Required:**
+1. Run `ark-check` as **sensor** (and `--plan --json` if multi-step) — CLI validates; you remediate.
+2. **Read** each violated file and its import target.
+3. **“Así te lo re-soluciono”** — concrete change before editing.
+4. After edits: `ark-check --strict-config` (and baseline if configured).
+
+## Common fix patterns
+
+| Symptom | Fix |
+|---------|-----|
+| App → Presentation type-only | Extract type to application/core; re-export from UI |
+| App → Presentation value (UI in core) | Move component wrappers to presentation |
+| Domain → outer layer | Port/interface in Domain; adapter outside; or relocate false Domain file (`**/types.ts` trap) |
+| Intent prefix mismatch | Rename intent to layer’s `intentPrefixes` or fix prefix in config via `/ark-contract` |
+| Forbidden global in Domain | Inject a port (Clock, Id, Http) — don’t allow `Date.now` in Domain |
+| Concentrated edge wall | Stop grinding; `/ark-contract` facade/surface split |
+
+## Manifiesto
+
+If the “fix” is really a missing business intent or Domain home for a rule:
+
+- Propose intent name + layer placement.
+- Register / place code so `ark://manifest` / config can enforce it.
+- Do not only delete the import.
+
+## Rules
 
-## Verify and report
+- No `ark-*-disable`, no allowing a bad edge “to finish”, no baselining a **new** violation you introduced.
+- Prefer mechanical-safe kinds when the plan tags them; otherwise design judgment carefully.
+- Code only — no DB migrations unless user asked.
 
-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.
+## Done
 
-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.
+- Targeted violations gone; no new ones.
+- Report: what moved, what was intentional default, what needs user decision.

package/templates/skills/ark-loop.md

@@ -1,79 +1,57 @@
 ---
 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.
+description: Drive ark-check --plan to zero active violations. Auto-apply only mechanical-safe kinds; design judgment fixes from real source. CLI is the validator — you edit code.
 ---
 
-# /ark-loop — Drive the plan to a clean architecture (safely)
+# /ark-loop — Apply the plan 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.
+Read Ark’s classified **plan**, work toward **goal.met**, one small step at a time,
+validating every change with `ark-check` and rolling back regressions.
 
-**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.
+## 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:** re-printing plan JSON without opening sources, or inventing new “safe” kinds.
+
+**Required:**
+1. `--plan --json` as sensor.
+2. For each step you touch: **read** `file` and `target` source.
+3. **“Así te lo re-soluciono”** — exact edit before applying.
+4. After each apply: full gate re-run; rollback if targeted violation remains or new ones appear.
+
+## mechanical-safe only (auto)
+
+| `remediationKind` | What to do |
+|-------------------|------------|
+| `type-only-import-move` | Move type to owning layer; re-export for back-compat |
+| `pure-type-file-relocate` | Relocate pure-type file to owning layer (or rename out of false Domain globs) |
+| `import-type-from-pure-type-module` | Convert value import of pure-type module to `import type` |
+
+Never auto: value imports, dynamic import/require, mixed modules, forbidden globals, cycles, infra moves.
 
 ## 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`, plain-language `rationale`, and often
-   `remediationKind`. If `goal.met` is already true, report "nothing to do" and stop.
-
-   **`mechanical-safe` kinds you may auto-apply** (zero false-safe — never invent others):
-
-   | `remediationKind` | What to do |
-   |-------------------|------------|
-   | `type-only-import-move` | Edge is already `import type` / type-only: move the **type** to the owning layer + re-export for back-compat |
-   | `pure-type-file-relocate` | Whole **source file** is pure type-surface (`sourcePureTypeModule`) + type-only edge: relocate the file (or extract types) to the owning layer |
-   | `import-type-from-pure-type-module` | Static value-syntax import of a pure type-only **target** module (`targetTypeOnlyExports`): convert to `import type` (and place type if needed) |
-
-   Still **judgment** (never auto): value imports, `require()` / dynamic `import()`, mixed modules with side effects, forbidden globals, cycles, verbatim infra relocation.
-
-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.** Match the step's
-   `remediationKind` (table above) — do not expand the edit into a broader refactor:
-   - 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.
+1. **Plan** — `ark-check --plan --json` (+ `--baseline` if used). If `goal.met`, stop.
+2. **Worktree** — prefer discardable git worktree.
+3. **Apply mechanical-safe** one-by-one with validate/rollback.
+4. **Judgment** — propose with source-based design; apply only if user approved (or parent autopilot said full apply).
+5. **Re-plan** after each round until dry, `goal.met`, or only judgment left without approval.
+6. **Report** — auto-applied / proposed / deferred with paths; never claim clean if skipped.
 
 ## 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.
+- Never weaken the gate (no rule disables, no fresh baselining of new debt).
+- Concentrated single edge → stop and hand to `/ark-contract` with code evidence.
+- When unsure behavior preservation → judgment, not mechanical-safe.
+
+## Done criteria
+
+- Gate confirms each kept edit.
+- Honest residual list with **Así te lo re-soluciono** for anything left.
+- If residual steps hide domain/business rules in the wrong layer, call out **manifiesto** work (`intentPrefixes` / Domain placement) via `/ark-contract` or `/ark-adopt`.