arkgate 3.0.0 → 3.0.2

package/templates/skills/ark-autopilot.md

@@ -1,6 +1,6 @@
 ---
 name: ark-autopilot
-description: End-to-end architecture co-pilot — decision-grade explore first, dual plan (remediation + pattern improvements), mechanical-safe fixes, judgment design. CLI is a sensor; you read and remediate files.
+description: End-to-end co-pilot — explore first, dual plan A remediation + B pattern/Shape bets, mechanical-safe fixes, judgment design. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
 ---
 
 # /ark-autopilot — Get to a sound architecture, end to end
@@ -11,15 +11,23 @@ execute **judgment** fixes you design from reading source (still validate with a
 never weaken the gate).
 
 **Not a plan grinder.** Empty `--plan` does **not** mean “architecture is healthy” without
-the explore pass and dual-plan section B (pattern bets).
+the explore pass and dual-plan section B (pattern / Shape bets).
 
+## When / not when
+
+| Use `/ark-autopilot` when… | Do **not** use it when… |
+|----------------------------|-------------------------|
+| “Make architecture sound” end-to-end | Map only, no apply → `/ark-explore` |
+| Brownfield or greenfield with apply | Only fitness numbers → `/ark-coverage` |
+| User wants A + B planned and A executed | Single edge fix → `/ark-fix`; plan A only → `/ark-loop` |
+| Spaghetti under ENFORCE: Shape work with user ok on B | Contract false-green first → `/ark-adopt` / `/ark-contract` STOP paths |
 
 ## Related onboarding
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
 - **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
-- **Deep map only:** `/ark-explore` — full recon report without applying fixes.
-- **Adoption metrics only:** `/ark-coverage` — governed% + capability gaps (feeds dual plan B).
+- **Deep map only:** `/ark-explore` — full recon / dual-plan seed without applying.
+- **Adoption fitness only:** `/ark-coverage` — governed% + capability gaps (not pattern dual-plan).
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
 ## Dual engine (mandatory)
@@ -64,30 +72,38 @@ Useful first wave: **core product tree** | **field path** (examples/starters) |
 
 Do this **before** grinding plan A — plan lists *violations*, not *product reality*.  
 Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot report, not optional fluff).
-
-1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise risk).
-2. **Map** — entry points, lived layout vs globs (one screen).
-3. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a`.
-4. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
-5. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
-6. **False-green soft block** — doctor/coverage: empty Domain/Persistence while Application owns I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …). Doctor gap id: `contract-false-green-io-under-application`. If so:
+Include explore **§G** when spaghetti / design-weak signals fire.
+
+1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
+   **ENFORCE·design-weak** risk).
+2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
+3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
+4. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a` + internal norm.
+5. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
+6. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
+7. **False-green soft block** — doctor/coverage: empty Domain/Persistence while Application owns I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …). Doctor gap id: `contract-false-green-io-under-application`. If so:
    **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`.
-7. **Seed dual plan B** — 2–5 pattern / evolution bets ranked (impact × effort × enforceability).
+8. **Seed dual plan B** — 2–5 pattern / Shape bets ranked (impact × effort × enforceability). Each B row needs pilot + success signal; I/O bets need an **extraction card** (explore §G).
 
 Min bar: **≥12 source files** across **≥4 meaningful directories** (not only files in `steps[]`).  
-Standalone long report: `/ark-explore`. Adoption numbers deep-dive: `/ark-coverage`.
+Standalone long report: `/ark-explore`. Adoption fitness only: `/ark-coverage`.
 
 ## Dual plan (always emit)
 
 | Section | Source | Question | Auto-apply? |
 |---------|--------|----------|-------------|
-| **A. Remediation** | `--plan --json` + opened step files | What must change so the gate is honest? | Only `mechanical-safe` by default |
-| **B. Pattern / evolution** | Explore + coverage/doctor | What existing patterns should improve even if A is empty? | **Never** as mechanical-safe |
+| **A. Remediation** | `--plan --json` + opened step files | What must change so the **gate** is honest? | Only `mechanical-safe` by default |
+| **B. Pattern / Shape** | Explore §B/§G (not coverage alone) | What **design** must improve even if A is empty? | **Never** as mechanical-safe |
 
 **Section A** — group by edge; treat `peerIsolation` / cross-slice as **judgment**.  
-**Section B** examples: peerIsolation, move rules out of UI, strengthen starter/preset rules, write-path repair, split god orchestration modules, Domain placement / intents, import surface (`/runtime` vs root). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + success signal.
+**Section B** examples: choose golden pattern + pilot migrate-on-touch, peerIsolation, move rules out of UI, write-path repair, split god modules, Domain placement / intents, facade SQL → port/adapter (extraction card). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + **success signal** + **pilot** (+ kill-switch if new layer).
 
-B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.
+B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.  
+When A is empty and B is non-empty: status is **`goal.met on edges · Shape residual open`** — never “done” without listing B.
+Prefer CLI `patternBets[]` / `designSmells[]` when present; apply B only with explicit user ok using
+**extraction cards** (`docs/brownfield-adoption.md` §6) — never mechanical-safe, never silent.
+If B will take multiple PRs, offer (do not require) persisting a short Shape plan under the
+repo so the next agent session continues the same pilot — still never auto-apply B.
 
 ## Origin snapshot (day-zero picture)
 
@@ -136,12 +152,13 @@ B does **not** count as “architecture healthy finished.” Report B as `propos
 
 ## Done criteria
 
-- Explore pass completed (decision-grade map + paths + field path or n/a + B seeds).
-- Dual plan emitted (A and/or B; if both empty, one-line justification).
+- Explore pass completed (decision-grade map + paths + field path or n/a + phase + B seeds).
+- Dual plan emitted (A and/or B; if both empty, one-line justification with evidence no design-weak smells).
 - Origin present under `.ark/reports/origin.*` (frozen this run or earlier).
 - Every applied A step validated by real `ark-check`.
 - Final plan `goal.met` true **or** remaining A steps listed with file-level proposals.
-- Open **B opportunities** listed; report HTML paths cited.
+- Open **B / Shape opportunities** listed with success signals; report HTML paths cited when used.
+- If A empty and design-weak present: B listed — **Incomplete?** must not claim full healthy stop.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-contract.md

@@ -5,6 +5,13 @@ description: Safely edit ark.config.json (layers, rules, forbiddenGlobals, inten
 
 # /ark-contract — Change the architecture contract (safely)
 
+## When / not when
+
+| Use `/ark-contract` when… | Do **not** use it when… |
+|---------------------------|-------------------------|
+| Edit layers/rules/includes/intents with source evidence | Move product code without config change → `/ark-fix` / `/ark-loop` |
+| Concentrated-edge / false-green STOP from other skills | Full map without config edit → `/ark-explore` |
+
 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).
 

package/templates/skills/ark-coverage.md

@@ -1,37 +1,46 @@
 ---
 name: ark-coverage
-description: Exploratory deep-audit of real code + Ark adoption gaps. CLI is a sensor only — map the product, read source, propose concrete remediations and ranked opportunities with "así te lo re-soluciono".
+description: Ark adoption fitness audit — governed%, gates, baseline honesty, capability gaps. CLI is a sensor; read enough source to prove gaps. Full product recon and pattern dual-plan belong to /ark-explore.
 ---
 
-# /ark-coverage — Deep coverage + capability gaps
+# /ark-coverage — Ark adoption fitness (not full recon)
 
-You audit how this repo uses ArkGate **and** what the **real product tree** needs next.
-Work autonomously. End with a ranked report that is both **deterministic** (numbers) and
-**exploratory** (source-backed suggestions).
+You audit **how this repo uses ArkGate** (coverage, gates, baseline, host write path) and
+what adoption gaps remain. Work autonomously. End with a ranked fitness report.
 
+**This is not `/ark-explore`.** You do **not** produce a multi-pattern dual-plan or spaghetti
+Shape ladder by default. If the tree is design-weak under ENFORCE, **handoff** to explore.
+
+## When / not when
+
+| Use `/ark-coverage` when… | Do **not** use it when… |
+|---------------------------|-------------------------|
+| “How adopted is Ark?” governed%, gates, baseline, skills stale | Full product map / what-next architecture → `/ark-explore` |
+| Capability gaps (CI, write path, ESLint, optional layers) | Apply fixes end-to-end → `/ark-autopilot` |
+| Ranked *adoption* opportunities (install, ratchet, contract classify) | Spaghetti pattern plan / golden pattern → `/ark-explore` dual-plan seed |
+| Quick honesty before a release checklist | One design trade-off → `/ark-think` |
 
 ## Dual engine (mandatory)
 
 | Engine | Deliverable |
 |--------|-------------|
 | **Deterministic** | governed%, layers, gates, baseline, doctor gaps, summary edges |
-| **Exploratory** | product map, clusters opened, opportunities beyond “fix violation X” |
+| **Exploratory** | Enough source to prove ungoverned clusters / false-green are real (not JSON-only) |
 
-**Forbidden:** only `ark-check --coverage/--doctor/--json` paraphrase or gate checklists with no source evidence.
+**Forbidden:** only `ark-check --coverage/--doctor/--json` paraphrase with no source evidence.
 
 **Required before you finish:**
 1. CLI sensor: `--coverage --json`, `--doctor`, normal `--json` for `summary`.
-2. **Product surface** — README, workspaces, entry apps/APIs (name them).
-3. **Read real source** in the top ungoverned / high-coupling clusters (minimum **10 files**
-   across at least **4 directories** that matter for this product). Prefer domain, features,
-   adapters, app routes — not only config.
-4. **“Así te lo re-soluciono”** — file-level moves, contract globs, intent/manifest proposals.
-5. **Suggestive section** — opportunities (shape, extract, peerIsolation, manifiesto, DX)
-   ranked by impact × enforceability, even if the check is already green.
+2. **Product surface** — name the app/package(s) in one line (not a full recon).
+3. **Read real source** in the top ungoverned / high-risk clusters (minimum **10 files**
+   across at least **4 directories**). Prefer domain, features, adapters, routes — not only config.
+4. **“Así te lo re-soluciono”** for adoption gaps (globs, install, baseline, intents).
+5. If plan A is empty but you see design-weak / concurrent patterns / god modules:
+   list them briefly and **STOP — do not continue this skill as complete** for pattern work —
+   **handoff `/ark-explore` (dual-plan seed or shape-focus)**. Do not invent a second explore report here.
 
 If you did not open source files, the skill is **not complete**.  
-Full recon-only mode: `/ark-explore`.
-
+Full recon + pattern planning: `/ark-explore`.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -56,25 +65,25 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 |------|----------------|--------------------|
 | **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 + honest cores | “You arrived here — keep the host-appropriate write path and CI check on.” |
+| **Enforce / Guard** | Coverage + clean edges + honest cores | “You arrived here for *contract* fitness — design may still be weak; use explore for Shape.” |
 
 Never say “your architecture is guarded” while `goal.met` is false, governed% is low,
-or false-green doctor gaps are open.
+or false-green doctor gaps are open. Never say “architecture is healthy finished” solely
+because governed% is 100% and plan is empty.
 
 ## Related onboarding
 
 - **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).
-- **Explore-only report:** `/ark-explore`.
+- **Brownfield:** `/ark-adopt` for action; this skill for fitness metrics.
+- **Pattern / spaghetti residual:** `/ark-explore` dual-plan seed / shape-focus.
+- **Business rules loose:** note in table; mining action → `/ark-adopt` or `/ark-contract`.
 
-## Checklist (sensor)
+## Checklist (sensor + light code)
 
-1. Config + `ark-check --strict-config` (dead preset globs advisory; unclassified files still fail strict).
+1. Config + `ark-check --strict-config`.
 2. Baseline policy (orphan empty file? wire or delete).
 3. Host-appropriate write path + `/ark-*` skills per detected agent.
-4. CI workflow + monorepo install reality (`frontend/package.json`?).
+4. CI workflow + monorepo install reality.
 5. ESLint `arkgate/eslint` if ESLint exists.
 6. Domain `forbiddenGlobals`.
 7. **Governed%** + unclassified + `suggestions` from `--coverage --json`.
@@ -82,37 +91,27 @@ or false-green doctor gaps are open.
 9. `layersWithoutRules` + empty cores with I/O under Application (false-green).
     On false-green: **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 one-edge wall: **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).
-10. Runtime kernel / Nest only if deps prove it — never force-fit Next+Python.
-
-## Deep code pass (exploratory — the model job)
-
-For each top cluster (e.g. `src/features/*`, `src/lib/*`, `apps/*/src`):
-
-- Who imports whom (App→Presentation? Domain→App? cross-feature?).
-- Is “core” / “lib” really application, UI, I/O, or mixed?
-- Loose business logic: `calculate*`, `can*`, `validate*`, policy numbers, publish/intent strings without registry.
-- Propose: layer home, `ark.config.json` patterns, Domain extract, intent names (`Domain.*` / `Application.*`).
-- **Opportunity**, not only residual debt: what would make agents safer next week?
+10. Runtime kernel / Nest only if deps prove it — never force-fit.
 
 ## Output format
 
-1. **Headline honesty** — product one-liner, governed%, mode, violations, false-green risk.
-2. **Code map** — clusters you read + what you found (paths).
-3. **Ranked table** (mix residual gaps + opportunities)
+1. **Headline honesty** — product one-liner, governed%, mode, violations, false-green risk, **design-weak handoff?** (yes/no).
+2. **Adoption map** — clusters you read for *fitness* (paths) — keep short.
+3. **Ranked table** (adoption residual + install/capability opportunities)
 
-| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) |
+| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) | Next |
 
-Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity`
+Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity` | `design-weak`
 
-4. **Manifiesto / reglas de negocio** (if any): proposed intents / Domain files / config edits.
-5. Offer: “Apply top N?” / “Run /ark-adopt?” — apply only if user agrees; then re-run strict check.
+4. If any `design-weak` rows: **Handoff required** → `/ark-explore` (do not expand into full dual-plan here).
+5. Offer: “Apply top adoption N?” / “Run /ark-adopt?” / “Run /ark-explore for Shape?” — apply only if user agrees.
 
 ## Done criteria
 
 - ≥10 source files read and cited; product surface named.
-- At least one **Así te lo re-soluciono** block with real paths.
-- At least **two** exploratory suggestions (not only CLI residual debt).
+- At least one **Así te lo re-soluciono** block with real paths or install commands.
 - CLI numbers used as evidence, not as the whole report.
+- Design residual either absent with evidence or explicitly handed to `/ark-explore`.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-explain.md

@@ -6,6 +6,14 @@ description: Explain this project's architecture in plain language and generate
 # /ark-explain — Understand this project's architecture
 
 The user wants to understand the architecture, a specific rule, or why the gate blocked them.
+
+## When / not when
+
+| Use `/ark-explain` when… | Do **not** use it when… |
+|--------------------------|-------------------------|
+| Plain-language tour of layers/rules/report | Decision-grade recon / dual-plan → `/ark-explore` |
+| “Why did the gate block me?” pedagogy | Apply fixes → `/ark-fix` / `/ark-autopilot` |
+| Generate / walk HTML showcase report | Fitness numbers only → `/ark-coverage`; brownfield action → `/ark-adopt` |
 Your job is to **teach with this repo's real data** and leave a shareable visual artifact.
 
 ## Dual engine (mandatory)

package/templates/skills/ark-explore.md

@@ -1,6 +1,6 @@
 ---
 name: ark-explore
-description: Decision-grade architecture recon — sensor + tree + field path + coupling evidence. Rank residual that changes action; optional dual-plan seed (not multi-week roadmaps). CLI is a sensor; you read the tree. No gate bypass.
+description: Decision-grade architecture recon — sensor + tree + field path + coupling + design-correct residual. Dual-plan seed for spaghetti/pattern debt (never multi-week roadmaps). CLI is a sensor; you read the tree. No gate bypass.
 ---
 
 # /ark-explore — Recon the real project
@@ -11,56 +11,73 @@ install hooks, examples/starters, and coupling evidence. Output is **decision-gr
 ranked residual that changes the next command — **not** a celebration of ENFORCE and
 **not** a paraphrase of README/ROADMAP.
 
-Use alone when the user wants a map / options / “what should we do next?”.  
-`/ark-autopilot`, `/ark-coverage`, and `/ark-adopt` embed a lighter version of this pass.
+## 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` |
+| 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` |
+
+`/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:** `/ark-adopt` after the map (or hand off from explore STOP paths).
+- **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-autopilot` → `ark-check --doctor`.
-- **Execute dual plan + apply:** `/ark-autopilot` (explore is recon / seed, not the loop).
 
 ## 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** | Your judgment from **reading this tree**: product surface, field path, hotspots, false greens / false promises, design patterns lived | Only paraphrasing CLI JSON or docs |
+| **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.  
+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**,
-coupling that blocks evolution). If residual is truly none, say so in one line and hand
-off `stop`.
+**design-weak under ENFORCE**, coupling that blocks evolution). If residual is truly none,
+say so in one line and hand off `stop`.
 
-## Output mode (pick one — do not invent a third)
+## 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, o “Ark + patrón de diseño” | Same recon **plus** a short **§ Dual-plan seed** (below). **Cap 3–5 B bets.** |
+| **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, 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 either mode:**
+**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 2 only):**
+**Dual-plan seed shape (mode dual-plan seed | shape-focus):**
 
 | Section | Content |
 |---------|---------|
 | **A. Remediation** | From `--plan` — usually empty when ENFORCE; one line if so |
-| **B. Pattern / evolution** | **3–5** bets max from the ranked table; each: evidence · así te lo re-soluciono · **success signal** · next skill · **kill-switch** if proposing a new layer/big move |
+| **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 plans belong to **`/ark-autopilot`** (or a human-owned doc after
-the seed), not to explore by default.
+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)
 
@@ -79,9 +96,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 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 when present: **core product tree** vs **field path** (`examples/`,
-`templates/`, gallery starters, eval fixtures) vs **agent install surfaces** (hooks,
-MCP, CI templates).
+Useful split: **core product tree** | **field path** (`examples/`, starters) | **agent install surfaces** (hooks vs templates).
 
 ## Anti-wrapper rule
 
@@ -90,18 +105,19 @@ MCP, CI templates).
 - 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”, “add a layer
-  because the diagram is prettier”) without multi-surface proof or a kill-switch.
+- **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).
-6. Ranked rows that **change a decision**; each bet has a **success signal** (not a file count).
-7. 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.
+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.
 
 ## Reconnaissance pass (do all that apply)
 
@@ -121,9 +137,13 @@ MCP, CI templates).
   - 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): name each pattern,
-  one example path, quality (`canonical` / `gate-green design-weak` / `legacy`). Mark the
-  **golden** pattern to copy. Do not only list layer file counts.
+- **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.
 
 ### C. Coupling & debt (measure, don’t guess)
 Prefer evidence over aesthetics:
@@ -136,23 +156,23 @@ Prefer evidence over aesthetics:
 
 ### 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 (e.g. reject-only `--hook` vs `--hook-repair`). Doctor `writePath` / adoption gaps are leads — **verify on disk**.
+- **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 → note as agent-dx / adopt gap, not a layer violation.)
+- **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 (`npm run check`, `ark-check --strict-config`); record pass/fail — do not trust README alone.
+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 (lint/CI allowlist, PR checklist) — do not invent a full CI system.
+- 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?).
@@ -167,31 +187,80 @@ For each opportunity: **impact × effort × enforceability** (can the gate hold
 
 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` **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` | HTTP/route bodies under repo/db globs |
+| `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:
+
+```text
+### Extraction card
+Pilot: <one dir or feature>
+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
+Success: <observable / falsifiable>
+Kill-switch: <stop condition>
+Next: /ark-autopilot (apply with user ok) | /ark-fix (one cluster) | /ark-contract (globs only)
+```
+
+When doctor JSON is available, prefer smell `id`s from `designSmells` / `patternBets[].smellId`.
+
 ## Output format (keep tight)
 
-State **Mode: recon | dual-plan seed** in the headline or first line.
+State **Mode: recon | dual-plan seed | shape-focus** and **Phase: Align | Stabilize | Shape** in the first lines.
 
-1. **Headline** — product in one sentence + honesty line (mode, governed%, false-green / semantic false-green / false-promise risk). ENFORCE is context, not the story.
-2. **Map** — one short table or bullet map: entry points, major dirs, shape name (or “no honest shape yet”). One screen max. Include **patterns concurrent** table when relevant (§B).
-3. **What I opened** — paths + sensors that prove the pass (include field/hook/origin paths when used).
-4. **Ranked table** — **only rows that change a decision**. Prefer **3–6** hard rows; drop filler.
+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`
+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). If proposing a new layer / wall: add kill-switch in the así-te-lo cell or a footnote.
+**Success signal** must be falsifiable (see §F).
 
-5. **Field path summary** (scaffolds and/or internal norm).
-6. **Top 3 bets** — if the user says “go”, ordered execution. First bet = highest leverage residual, even when plan is empty (agent-dx / field honesty / design-correct — not “run loop on zero steps”).
+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** — **only in mode 2**; A + B with cap 3–5 B rows; no multi-week phase chart.
-8. **Deterministic residue** — compact: plan steps, violations, doctor top action. Point to
-   `/ark-loop` / `/ark-fix` **only when steps exist**; never pretend loop is the architecture story when goal is already met.
+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 steps, violations, doctor top action. Point to `/ark-loop` / `/ark-fix` **only when A steps exist**; never pretend loop is the architecture story when goal is already met.
 
-Optional when useful: **Diff vs naive sensor-only read** (one short list: what reading the tree changed).
+Optional: **Diff vs naive sensor-only read** (what reading the tree changed).
 
 ## Done criteria
 
@@ -199,10 +268,11 @@ Optional when useful: **Diff vs naive sensor-only read** (one short list: what r
 - 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 or semantic false-green exist.
-- Every Top-3 / B bet has a **success signal**; new-layer bets have a **kill-switch**.
+- 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 command | `stop`.
+- 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)

package/templates/skills/ark-fix.md

@@ -9,6 +9,28 @@ 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 [brownfield-adoption.md](../../docs/brownfield-adoption.md)
+§6 and explore §G. Fixed fields (never mechanical-safe, never silent B apply):
+
+```text
+### Extraction card
+Pilot: <one directory or feature path>
+Smell: <doctor designSmells id if present>
+Move: <verbatim relocate / split>
+Do not: rewrite queries; weaken ark.config; invent mechanical-safe kinds; big-bang
+Success: <falsifiable>
+Kill-switch: <stop condition>
+Next: re-run ark-check; shrink baseline if applicable
+```
 
 ## Dual engine (mandatory)