arkgate 4.2.0 → 4.3.0

package/templates/agent-skills/ark-explore/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: ark-explore
+description: Specialized map skill — decision-grade recon of layers + ArkRules opportunities + dual-plan seed (no apply). Primary post-green door when design-weak. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
+---
+
+# /ark-explore — Recon the real project (map only)
+
+**Specialized escape**, not the default curriculum. Use when you need a decision-grade map
+or the post-green Shape door; hand off to `/ark-autopilot` to apply. Day-to-day place + gate
+work does not require this skill.
+
+You are a **staff engineer doing architecture reconnaissance** on *this* repository.
+Ark’s CLI is a **sensor** (coverage, doctor, plan). **You** open source, entry points,
+install hooks, examples/starters, and coupling evidence. Output is **decision-grade**:
+ranked residual that changes the next command — **not** a celebration of ENFORCE and
+**not** a paraphrase of README/ROADMAP.
+
+## When / not when
+
+| Use `/ark-explore` when… | Do **not** use it when… |
+|--------------------------|-------------------------|
+| Map / “what next?” / residual after ENFORCE | User wants edits applied → `/ark-autopilot` or `/ark-fix` |
+| **Primary post-green door (Q01):** messy / spaghetti / design-weak / “clarify for AI” | Skill-shopping coverage or think for the same residual |
+| Spaghetti brownfield: patterns concurrent, design-weak under green check | Only “governed% + gates installed?” numbers → `/ark-coverage` |
+| Dual-plan **seed** (A remediation + B pattern bets) without applying | One design trade-off between 2–3 options already mapped → `/ark-think` |
+| Path-correct vs design-correct honesty | Plain-language tour / HTML report → `/ark-explain` |
+
+**Q01 single path:** when doctor `postGreenPath` / ENFORCE · design-weak is active, **this skill
+(shape-focus / dual-plan seed) is the map half of the one door** — then `/ark-autopilot` only
+to apply B with user OK. Do not send the user to coverage or think as equal first choices.
+
+### Status lights (rank residual; not settings)
+
+| Light | Explore role |
+|-------|----------------|
+| **Suggest** | Point at `ark start` → doctor; map only if user insists on recon before setup |
+| **Adapt** | Map false-green / ungoverned / concentrated edge; hand off adopt/contract before Shape vanity |
+| **Enforce** | Confirm edges; if residual smells/patterns appear, auto-upgrade to dual-plan seed / shape-focus |
+| **Enforce · design-weak** | **Primary post-green map door** — shape-focus + dual-plan B + extraction cards. False-done forbidden. Never claim healthy because plan A is empty. |
+
+`/ark-autopilot`, `/ark-adopt`, and `/ark-coverage` embed a **lighter** version of this pass.
+**You** are the full recon + pattern-planning skill.
+
+## Related onboarding
+
+- **Greenfield / thin tree:** `/ark-architect` or `ark-check --recommend` / `ark start`.
+- **Brownfield action (write contract/baseline):** `/ark-adopt` after the map.
+- **Execute dual plan:** `/ark-autopilot` (explore seeds; autopilot applies A, proposes B).
+- **Default path:** `ark start` → `ark-check --doctor` → `/ark-autopilot` for guided apply; use this skill for map-only or post-green Shape residual.
+
+## Dual engine (mandatory)
+
+| Engine | Role | Never confuse with |
+|--------|------|--------------------|
+| **Deterministic** | Contract truth: layers, rules, violations, `mechanical-safe` kinds, exit codes | Product vision or “good enough” |
+| **Exploratory** | Judgment from **reading this tree**: product surface, field path, hotspots, false greens, **lived design patterns**, spaghetti residual | Only paraphrasing CLI JSON or docs |
+
+**Incomplete:** doctor/coverage dump with no file paths you opened; or a long map that
+only restates README; or a multi-week roadmap when the user only asked for a map;
+or “healthy” because plan A is empty while design-weak smells remain unlisted.  
+**Complete:** dry headline + field evidence + ranked bets with **así te lo re-soluciono**
+(real paths, concrete next step, **success signal**) + honest handoff when residual is
+*not* layer debt.
+
+**ENFORCE / 100% governed / empty plan is baseline, not a finding.** Lead with residual
+that still matters (dogfood gaps, soft starters, identity drift, **semantic false-green**,
+**design-weak under ENFORCE**, coupling that blocks evolution). If residual is truly none,
+say so in one line and hand off `stop`.
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| Plane | What it protects | Where it lives | Sensors / tools |
+|-------|------------------|----------------|-----------------|
+| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
+| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column table with those headers).
+2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
+3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
+4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Explore + ArkRules
+- Always run sensors for **both** planes when present: coverage/doctor **and** `--rules-inventory` if `arkRules` exists or brownfield may hide spaghetti rules.
+- Ranked table kinds may include `arkrules-opportunity` and `invariant-gap`.
+- Dual-plan **B** may include: place advisory structure rules, extract one inventory candidate to Domain + `arkrules` entry, promote one covered invariant.
+- Field path: note whether starters emit `arkrules/*`.
+
+## Output mode (pick one — do not invent a fourth)
+
+| Mode | When | Deliverable |
+|------|------|-------------|
+| **Recon (default)** | map / residual / “what next?” / bare `/ark-explore` | Headline → map → ranked table → **Top 3** → residue → Completion |
+| **Dual-plan seed** | user asks for a **plan**, mejora, roadmap, “Ark + patrón”, **or** spaghetti signals fire (§G) | Same recon **plus** **§ Dual-plan seed** (A + B). **Cap 3–5 B bets.** |
+| **Shape-focus** | plan A already empty / ENFORCE, `plan.completeness` is `complete`, user wants **pattern** depth only | Abbreviated map + **mandatory** concurrent-patterns table + B bets only (A = “goal.met / empty”) |
+
+**Auto-upgrade:** if §G spaghetti signals fire, you **must** use dual-plan seed or shape-focus
+— never end on recon-only with “layers are clean.”
+
+**Forbidden in every mode:**
+- A 6-phase / multi-week implementation roadmap as the default explore product.
+- Phases with week estimates, long PR stacks, or vanity “Domain ≥ N files” as done criteria.
+- Auto-applying anything (explore does not edit the contract or product code unless the user
+  separately asks to execute a bet).
+
+**Dual-plan seed shape (mode dual-plan seed | shape-focus):**
+
+| Section | Content |
+|---------|---------|
+| **A. Remediation** | From `--plan` — usually empty when ENFORCE; one line if so. Empty counts only when `plan.completeness === "complete"` |
+| **B. Pattern / evolution** | **3–5** bets max; each: evidence · así te lo re-soluciono · **success signal** · next skill · **pilot** · **kill-switch** if new layer/big move |
+| **Phase ladder** | Name which of Align / Stabilize / **Shape** the repo is in (§G) |
+
+Long multi-PR execution belongs to **`/ark-autopilot`**. If residual spans sessions/PRs,
+optionally point the user at a durable Shape plan (e.g. `docs/plans/shape-<pilot>/`) seeded
+from patternBets + extraction cards — **optional**, not a gate requirement
+(see `docs/brownfield-adoption.md` §6).
+
+## Subagent fan-out (optional, host-dependent)
+
+When the user asks to go faster **or** the work naturally splits (multiple packages,
+feature dirs, plan clusters), you **may** dispatch **subagents**:
+
+| Host capability | Behavior |
+|-----------------|----------|
+| **Parallel subagents supported** (e.g. multi-agent / `spawn_subagent` / concurrent Agent tools) | Launch **2–N** agents in **one wave** with **disjoint path scopes**. Prefer **read-only** explore agents for mapping; at most **one writer** unless the host gives isolated worktrees. Parent merges findings, then runs `ark-check` once. |
+| **Not supported** (single agent only) | **Fall back to sequential** — same checklist, one cluster/step at a time. Never claim parallel work you did not run. |
+
+**Rules:**
+1. Give each subagent a **tight brief**: paths in scope, sensor commands allowed, deliverable shape (paths opened + findings JSON or bullets).
+2. **No shared mutable files** across parallel writers.
+3. STOP handoffs and dual-engine rules still apply in every agent.
+4. Parent owns the **### Completion** block (union of **Opened**, single **Handoff**).
+5. Do **not** use subagents to weaken the gate or invent `mechanical-safe` kinds.
+
+Useful split: **core product tree** | **field path** (`examples/`, starters) | **agent install surfaces** (hooks vs templates).
+
+## Anti-wrapper rule
+
+**Forbidden:**
+- Only `ark-check --json` / `--coverage` / `--doctor` paraphrase.
+- Echoing README / ROADMAP / marketing as if it were recon.
+- Padding the ranked table with “architecture is clean” rows when the sensor already said that.
+- Ranking debt by **LOC alone** without fan-in, exports, or call-site evidence.
+- **Vanity success metrics** as bet done criteria (e.g. “Domain ≥ 20 files”) without multi-surface proof or a kill-switch.
+- Multi-week roadmaps when mode is recon-only.
+- Claiming “nothing to do” because plan A is empty while §G design smells remain.
+
+**Required:**
+1. Sensor: `--coverage --json`, `--doctor`, optional `--plan --json` / normal check.
+2. **Product + code pass** — min **12 source files** across **≥4 directories** that matter for *this* product (apps, packages, features, domain, adapters, API routes, CLIs).
+3. **Field path** when scaffolds exist (see §E); for pure apps, **internal field path** (see §E).
+4. **Coupling evidence** beyond “large file” (see §C).
+5. **Path-correct vs design-correct** pass (see §B) — always on brownfield or when plan is empty.
+6. **§G spaghetti / design-depth** when signals fire (or always on brownfield).
+7. Ranked rows that **change a decision**; each bet has a **success signal** (not a file count).
+8. Hard lines: never weaken the contract; never invent mechanical-safe kinds; never claim ENFORCE from type-only cleanup while false-green doctor ids are active.
+9. **Parse honesty:** require `plan.completeness === "complete"` before accepting `goal.met`. If `doctor.parseHealth.affectedFiles > 0`, open and name those paths; never describe them as clean or successfully inspected. Doctor alone does not change the gate verdict, but check/plan completeness is `partial`, plan goal is false, and strict merge fails.
+
+## Reconnaissance pass (do all that apply)
+
+### A. Product surface (what the system is)
+- README / package.json `description` / scripts / monorepo workspace roots — **skim for entry points**, do not restate the pitch.
+- User-facing entry: Next/Nest/Express routes, CLIs, workers, public APIs, package exports.
+- Deploy shape if obvious (apps/, packages/, services/).
+- One dry line: **what a real user/agent gets** (not the slogan).
+
+### B. Architecture as lived — path-correct vs design-correct
+- Map top dirs → intended layer vs what code *actually* does (UI, use-cases, I/O, pure domain).
+- Classic false-green: empty Domain / Persistence while Application owns `airtable|supabase|prisma|repositories` → doctor id `contract-false-green-io-under-application`.
+- **Semantic false-green** (edges green, names lie) — flag when you see it:
+  - HTTP handlers / route bodies living under `repositories/` or Persistence globs.
+  - Presentation/routes defaulting to a data facade (`platform/*`, raw db) while “repos exist”.
+  - Domain layer thin while pure business rules sit in Application with no I/O (should be Domain).
+  - Layer labels that match globs but not role (gate path-correct, design wrong).
+- Framework guts vs product code (Nest modules, Next app router, generated clients).
+- **Identity risk:** which layer owns the product *wedge* vs file-count / public barrel.
+- **Concurrent design patterns** (short table when ≥2 styles coexist **or** when spaghetti signals fire):
+
+| Pattern name | Example path | Quality |
+|--------------|--------------|---------|
+| … | `src/…` | `canonical` / `gate-green design-weak` / `legacy` |
+
+Mark the **golden** pattern to copy. Do not only list layer file counts.
+
+When `doctor.physicalCohesion` includes `reshapeDecisions`, treat current rejected/deferred
+targets as explicit adopter decisions, not residual to re-fight. Keep their mirror facts in the
+map. When the user accepts, defers, or rejects a live `reshapePilot.nextPilot`, record the card's
+exact `decisionTarget` with a reason (and optional `reviewBy`) in
+`.ark/reshape-decisions.json`. Never infer or suppress from free-form golden-pattern prose.
+
+### C. Coupling & debt (measure, don’t guess)
+Prefer evidence over aesthetics:
+- **Fan-in / importers** of hot modules (who imports the suspect file?).
+- **Export surface** (how many public symbols does the orchestration module re-export?).
+- Import cycles, cross-feature leaks (`peerIsolation` candidates).
+- Business rules in UI/hooks (`can*`, `calculate*`, policy constants) → Domain / intents.
+- Dead or aspirational globs; layers with files but no rules; **starter/preset rules weaker than sibling archetypes** (soft green).
+- LOC is a **hint** only — pair it with fan-in or export count before calling something a god module.
+
+### D. Agent / gate reality (installed vs generated)
+- Write gate + CI + `/ark-*` skills present? Stale skills? Global vs pinned `arkgate`?
+- **Installed hooks vs install templates:** compare project PreToolUse / write-hook commands to what `--install-agent-gates` would emit. Doctor `writePath` / adoption gaps are leads — **verify on disk**.
+- MCP config present and pointing at a real binary? `prepare-write` / autoPatch surface vs hook mode.
+- Baseline: real debt or hiding contract smell?
+- CI: is architecture check required on the default branch path this repo actually uses?
+- **Origin:** is `.ark/reports/origin.json` present? (Day-zero picture; missing → agent-dx / adopt gap, not a layer violation.)
+
+### E. Field path (consumer promise or internal)
+When `examples/`, `templates/`, gallery starters, eval fixtures, or docs claim “copy this and stay green”:
+1. Open **≥2** scaffolds (prefer one minimal gallery + one “deep” / runnable demo).
+2. **Run** their documented check script when cheap; record pass/fail — do not trust README alone.
+3. Diff **rule strength** across archetypes (missing denies = soft false-green for consumers).
+4. Note import style vs package surface docs (`arkgate` root barrel vs preferred subpath).
+5. Flag **false promises**: demo fails under its own check, or green with a hollow contract.
+
+If the repo is a **pure app** (no examples): state **Field path: internal** and do one of:
+- Name the **norm for new code** that the residual implies (e.g. “no new `platform/db` in routes”), or
+- Point at one **smoke** the team could add — do not invent a full CI system.
+
+### F. Suggestive bets (not commits yet)
+For each opportunity: **impact × effort × enforceability** (can the gate hold it after?).
+
+**Success signal (required per bet)** — observable, not vanity:
+- Good: `doctor.writePath = repair`; `ark-check` green after promote; API + UI import same pure `computeX`; 0 new routes with facade SQL; pilot cluster migrated + kill-switch decision recorded.
+- Bad: “Domain has ≥ N files”; “add layer X”; “more documentation”.
+
+**Kill-switch (required if the bet adds a layer, peerIsolation wall, or big-bang move):**
+- Name a **pilot** (one cluster) and a **stop condition** (e.g. “if pilot does not reduce confusion in 2 real PRs → prefer handlers-under-domain without a new layer”).
+- Prefer **forward-only + migrate-on-touch** over big-bang.
+
+Prefer bets the user can run next (`command` / skill), not vague “improve DX”.
+
+### G. Spaghetti / design-depth ladder (non-deterministic path — mandatory when signals fire)
+
+**Signals (any one → dual-plan seed or shape-focus):**
+- Plan A empty / `goal.met` with `completeness: complete` **and** you still see design-weak / concurrent patterns / god modules.
+- Brownfield with mixed layouts (flat services + “hex” folders + feature dumps).
+- Semantic false-green (path-correct, design-wrong).
+- User words: spaghetti, monstruo, legacy, “está enforce pero horrible”, pattern, refactor shape.
+
+**Phase ladder (name exactly one current phase):**
+
+| Phase | Goal | Done when (falsifiable) |
+|-------|------|-------------------------|
+| **Align** | Contract matches reality (path-correct); no false-green freeze | Governed high; false-green closed; concentrated edge fixed via contract |
+| **Stabilize** | ENFORCE + honest baseline only for real debt | 0 new edges; doctor not lying about write path/CI |
+| **Shape** | One **golden** pattern + pilot cluster | Pilot smells cleared; rest is migrate-on-touch; B bets have success signals |
+
+ENFORCE without Shape progress is **`ENFORCE · design-weak`** — say that out loud. It is **not** “healthy finished.”
+
+**Agent-detected design smells** (list any that apply; paths required — these may predate doctor IDs):
+
+| Smell id (label) | How you detect it in source |
+|------------------|-----------------------------|
+| `io-under-application` | I/O clients under Application; empty Domain/Persistence (also doctor when present) |
+| `handler-in-persistence` | Static framework HTTP imports, `defineRoute` calls, or route bodies under Persistence-role repo/db globs (**envelope:** first 800 sorted candidates; absence of smell ≠ full-tree proof above that cap; incomplete/partial analysis is never “no smells”) |
+| `god-module` | High fan-in + wide export surface + mixed concerns |
+| `domain-logic-in-ui` | `can*` / `calculate*` / policy constants in hooks/pages |
+| `mixed-pattern-cluster` | Same feature area uses ≥2 incompatible layouts |
+| `soft-contract` | Layers without denies / peerIsolation off where peers leak |
+| `facade-sql-in-routes` | Routes import raw ORM/SQL while “repositories exist” elsewhere |
+
+**Extraction card** (for each I/O / god-module B bet — judgment, never mechanical-safe).
+Canonical productized template also in `docs/brownfield-adoption.md` §6.
+
+**Q04 pilot loop:** when doctor/plan JSON is available, use **`pilotLoop.nextPilot`** as the
+**single** next extraction card (one pilot at a time → re-doctor). Do not open five B bets
+in parallel. When `pilotLoop.queuedBets > 0`, those bets stay **queued**, not concurrent.
+`multiPilotBatchForbidden` / `autoApplyForbidden` (alias `autoApplyPlanBForbidden`) are hard
+lines — never silent codemod of plan B. After the pilot lands, re-run doctor; success =
+reduced evidence on pilot paths.
+
+### Plan B one-pilot checklist (mandatory before any B apply)
+
+Empty plan A + design-weak is **not** architecture finished. Plan B is judgment only.
+
+| Step | Gate | Fail closed if… |
+|------|------|-----------------|
+| 1. Confirm residual | `designFitness.designWeak` **or** non-empty `patternBets` / `designSmells` | You would claim healthy finished because plan A is empty |
+| 2. Pick **one** pilot | `pilotLoop.nextPilot` (preferred) **or** one ranked B bet with a path scope | Multi-pilot batch / “fix all smells this PR” |
+| 3. Write extraction card | Pilot · Smell · Move · Do not · Success · **Kill-switch** · Next | Missing kill-switch or success signal |
+| 4. User OK | Explicit approval before edit (or stay map-only) | Silent auto-apply of plan B |
+| 5. Apply **only** that pilot | Via `/ark-autopilot` (apply B) or `/ark-fix` (one cluster) | Opening a second pilot before re-doctor |
+| 6. Re-doctor | Success = reduced evidence on pilot paths; residual outside pilot may remain | Declaring whole-tree done from one pilot |
+
+**Hard lines (never break):**
+- `killSwitch` / kill-switch is **required** on every B card (stop condition if pilot does not reduce confusion).
+- `multiPilotBatchForbidden` — never multi-batch Shape extractions.
+- `autoApplyPlanBForbidden` / `neverMechanicalSafe: true` — never invent mechanical-safe for B.
+- `healthyFinishedForbidden` while design-weak — empty plan A is baseline, not done.
+
+```text
+### Extraction card
+Pilot: <one dir or feature — or pilotLoop.nextPilot.pilotTarget>
+Smell: <doctor designSmells[].id when present, else agent-detected id>
+Move: <verbatim I/O or rule → port/adapter or Domain file>
+Do not:
+  - rewrite queries / touch schema / migrations
+  - weaken ark.config.json
+  - auto-apply as mechanical-safe or invent new mechanical-safe kinds
+  - big-bang the monorepo
+  - open a second pilot before re-doctor
+Success: <observable / falsifiable — re-doctor>
+Kill-switch: <stop condition — e.g. if pilot does not clear smell evidence in 1 PR → stop / re-map>
+Next: /ark-autopilot (apply with user ok) | /ark-fix (one cluster) | re-doctor
+```
+
+When doctor JSON is available, prefer smell `id`s from `designSmells` / `patternBets[].smellId`
+and the ranked **`pilotLoop.nextPilot`**.
+
+## Output format (keep tight)
+
+State **Mode: recon | dual-plan seed | shape-focus** and **Phase: Align | Stabilize | Shape** in the first lines.
+
+1. **Headline** — product one sentence + honesty (mode, governed%, false-green / semantic false-green / **ENFORCE·design-weak** / false-promise risk). ENFORCE is context, not the story.
+2. **Map** — entry points, major dirs, shape name (or “no honest shape yet”). One screen. **Patterns concurrent** table when §B/§G requires it.
+3. **What I opened** — paths + sensors (include field/hook/origin when used).
+4. **Ranked table** — **only rows that change a decision**. Prefer **3–6** hard rows.
+
+| # | Kind | Finding | Evidence (path) | Así te lo re-soluciono | Success signal | Next skill / command |
+
+Kinds: `risk` | `false-green` | `debt` | `opportunity` | `shape` | `manifiesto` | `agent-dx` | `design-weak`
+
+**Así te lo re-soluciono** must be concrete: files to touch, command to run.  
+**Success signal** must be falsifiable (see §F).
+
+5. **Field path summary**.
+6. **Top 3 bets** — first bet = highest leverage residual, even when plan A is empty (design-correct / agent-dx / field honesty — **not** “run loop on zero steps”).
+   On false-green dominant: **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
+   On concentrated edge dominant: **STOP — do not continue this skill as complete.** **STOP — concentrated edge: invoke /ark-contract with source evidence** (do not freeze a wrong contract or grind N freezes).
+7. **Dual-plan seed** — required in dual-plan seed / shape-focus (and when §G auto-upgrades); A + B cap 3–5; extraction cards for I/O bets.
+8. **Deterministic residue** — plan completeness, steps, violations, doctor top action. Point to `/ark-loop` / `/ark-fix` **only when A steps exist**; never call a `partial`/`unavailable` plan met, and never pretend loop is the architecture story when a complete goal is already met.
+
+Optional: **Diff vs naive sensor-only read** (what reading the tree changed).
+
+## Done criteria
+
+- ≥12 source files read and cited across ≥4 directories.
+- Field path: scaffolds run/opened **or** pure-app internal norm stated.
+- At least **3 decision-grade** rows (not “fix violation X” and not “layers are clean”).
+- Coupling claims backed by fan-in / exports / importers (or clearly marked as LOC-only hint).
+- Path vs design called out when concurrent patterns, semantic false-green, or §G signals exist.
+- When §G fires: phase named, design smells listed with paths, dual-plan B or shape-focus B present.
+- Every Top-3 / B bet has a **success signal**; new-layer bets have a **kill-switch** + pilot.
+- Mode respected: no multi-week roadmap in recon mode; dual-plan seed capped at 3–5 B bets.
+- Clear handoff: `/ark-adopt` | `/ark-contract` | `/ark-autopilot` | `/ark-loop` | `/ark-fix` | CLI | `stop`.
+- No gate weakening; no false ENFORCE claim; no README echo as primary content.
+
+## Completion contract (skill incomplete if missing)
+
+End with **exactly** these headings (markdown `###`):
+
+### Completion
+- **Sensor:** commands/tools run
+- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
+- **Result:** one-line outcome
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Handoff:** `/ark-…` / CLI / `none`
+- **Incomplete?** `no` | `yes — <what is missing>`
+
+If a **STOP** handoff applies and you continued as if done, set **Incomplete?** to `yes`.
+**Skill incomplete if missing** any of the bullets above.

package/templates/agent-skills/ark-fix/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: ark-fix
+description: Resolve Ark architecture violations at the root cause — read importers and product context, design ports/adapters/moves/intent alignment. Never weaken the contract. CLI only validates.
+---
+
+# /ark-fix — Fix architecture violations at the root
+
+You fix violations Ark reports. Prefer structural fixes over silencing the gate.
+**Read the surrounding product code** (callers, package role, feature ownership) — not only
+the two files on the violation edge.
+
+## When / not when
+
+| Use `/ark-fix` when… | Do **not** use it when… |
+|----------------------|-------------------------|
+| One change / small cluster just failed the gate | Bulk residual / many edges → `/ark-loop` or `/ark-autopilot` |
+| Need a structural fix (port, move, intent rename) | Map residual / pattern Shape plan → `/ark-explore` |
+| Judgment design for a known violation | Contract wrong / false-green → STOP to `/ark-contract` / `/ark-adopt` |
+
+When the fix is really a **Shape** extraction (I/O out of routes, god module split), write an
+**extraction card** before editing — same template as `docs/brownfield-adoption.md`
+§6 and explore §G. Fixed fields (never mechanical-safe, never silent B apply).
+
+### Plan B one-pilot checklist (when Shape residual, not a single edge fix)
+
+Empty plan A + `designWeak` is **not** architecture finished. One pilot only:
+
+1. **Confirm** doctor `designFitness.designWeak` / non-empty `patternBets` (or agent-detected smell).
+2. **One pilot** — prefer `pilotLoop.nextPilot`; never multi-batch concurrent Shape extractions.
+3. **Extraction card** with **Kill-switch** + falsifiable Success (required).
+4. **User OK** before apply — `autoApplyPlanBForbidden` / never mechanical-safe.
+5. **Edit only that pilot scope** — then `ark-check` / re-doctor; residual outside pilot may remain.
+6. **Stop** if kill-switch fires; do not open pilot #2 in the same batch.
+
+```text
+### Extraction card
+Pilot: <one directory or feature path — or pilotLoop.nextPilot.pilotTarget>
+Smell: <doctor designSmells id if present>
+Move: <verbatim relocate / split>
+Do not: rewrite queries; weaken ark.config; invent mechanical-safe kinds; big-bang; multi-pilot batch
+Success: <falsifiable — re-doctor on pilot paths>
+Kill-switch: <stop condition — required>
+Next: re-run ark-check; shrink baseline if applicable
+```
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | Violation list, plan kinds, post-edit `ark-check` |
+| **Exploratory** | Why this edge exists in *this* product; better home; manifiesto if the rule is business |
+
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| Plane | What it protects | Where it lives | Sensors / tools |
+|-------|------------------|----------------|-----------------|
+| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
+| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column table with those headers).
+2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
+3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
+4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Fix + ArkRules
+- Classify each violation: `LAYER_*` / capability → **[Layer]**; `ARKRULE_*` / `INVARIANT_*` → **[ArkRules]**.
+- Structure sensor fixes are judgment (ports, factories, private state) — not mechanical-safe.
+
+## Subagent fan-out (optional, host-dependent)
+
+When the user asks to go faster **or** the work naturally splits (multiple packages,
+feature dirs, plan clusters), you **may** dispatch **subagents**:
+
+| Host capability | Behavior |
+|-----------------|----------|
+| **Parallel subagents supported** (e.g. multi-agent / `spawn_subagent` / concurrent Agent tools) | Launch **2–N** agents in **one wave** with **disjoint path scopes**. Prefer **read-only** explore agents for mapping; at most **one writer** unless the host gives isolated worktrees. Parent merges findings, then runs `ark-check` once. |
+| **Not supported** (single agent only) | **Fall back to sequential** — same checklist, one cluster/step at a time. Never claim parallel work you did not run. |
+
+**Rules:**
+1. Give each subagent a **tight brief**: paths in scope, sensor commands allowed, deliverable shape (paths opened + findings JSON or bullets).
+2. **No shared mutable files** across parallel writers.
+3. STOP handoffs and dual-engine rules still apply in every agent.
+4. Parent owns the **### Completion** block (union of **Opened**, single **Handoff**).
+5. Do **not** use subagents to weaken the gate or invent `mechanical-safe` kinds.
+
+## Related onboarding
+
+- **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Map first:** `/ark-explore` when the violation is one of many structural smells.
+- **peerIsolation / cross-slice:** always **judgment** — extract to shared, events/ports, or redesign ownership. Never auto-apply cross-feature or cross-context moves.
+- **`vertical-slice` ownership:** feature code stays under `src/features/<slice>/…` (no sibling-slice imports); shared primitives in `src/shared/`; infra in `src/lib/`; shell in `src/app/`. Cross-feature edges are peerIsolation — extract shared or use events/ports.
+- **`ddd-bounded-contexts` ownership:** code under `src/contexts/<context>/{domain,application,infrastructure,presentation}/`; shared kernel only under `src/shared/kernel/`. Cross-context imports (same or cross technical layer) are peerIsolation — integrate via application APIs/events, not peer technical layers.
+- **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 (plus callers that explain product role).
+   If the wall is a concentrated contract smell: **STOP — do not continue this skill as complete.** **STOP — concentrated edge: invoke /ark-contract with source evidence** (do not freeze a wrong contract or grind N freezes).
+   If false-green cores: **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
+   If many residuals: **STOP — do not continue this skill as complete.** **STOP — bulk residual debt: invoke /ark-loop or /ark-autopilot** instead of ad-hoc multi-file grinding without a plan.
+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
+
+- 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.
+
+## Mechanical-edit hygiene (Y04 — outcome gate)
+
+- Header injection must **merge into the existing doc comment**; the kept result has one `/**`, not stacked headers.
+- Route completion or movement must **preserve the original typed `defineRoute<…>(opts, handler)` call**; reconstruct that call instead of extracting untyped opts/handler constants that drop generics or contextual typing.
+- A convention-only `*-data.ts` stub is not a fix: move the real code or **leave the placeholder file uncreated**; never write `import "server-only"; export {}` as an empty naming token.
+- Keep the edit only when the **previously clean file stays typecheck-clean**. Otherwise roll it back and treat the change as judgment.
+
+## Reshape findings (X04 — never mechanical)
+
+If `doctor.physicalCohesion` fires while you fix: do **not** fold reshape moves into your fix
+batch. Physical moves run only through `/ark-loop`'s one-pilot loop; merge decisions only as
+`/ark-architect` merge cards. A cohesion finding is context for your fix, never a license to
+reorganize. Respect `physicalCohesion.reshapeDecisions`: never revive a current rejected/deferred
+target from the still-visible facts. If the user makes a verdict while reviewing the finding,
+record its exact `decisionTarget` + reason in `.ark/reshape-decisions.json`; never infer one from
+golden-pattern prose.
+
+## Done
+
+- Targeted violations gone; no new ones.
+- Report: what moved, what was intentional default, what needs user decision.
+
+## Completion contract (skill incomplete if missing)
+
+End with **exactly** these headings (markdown `###`):
+
+### Completion
+- **Sensor:** commands/tools run
+- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
+- **Result:** one-line outcome
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Handoff:** `/ark-…` / CLI / `none`
+- **Incomplete?** `no` | `yes — <what is missing>`
+
+If a **STOP** handoff applies and you continued as if done, set **Incomplete?** to `yes`.
+**Skill incomplete if missing** any of the bullets above.