arkgate 2.13.0 → 3.0.1

package/templates/skills/ark-adopt.md

@@ -1,6 +1,6 @@
 ---
 name: ark-adopt
-description: Brownfield onboarding — exploratory match of contract to real product code, classify ungoverned dirs, mine business rules into the manifest, freeze only real debt. Deep source analysis required.
+description: Brownfield onboarding — match contract to real product code, classify ungoverned dirs, mine business rules, freeze only real debt, seed Shape dual-plan B for spaghetti residual. Deep source analysis required.
 ---
 
 # /ark-adopt — Bring Ark into an existing codebase
@@ -8,6 +8,18 @@ description: Brownfield onboarding — exploratory match of contract to real pro
 Goal: contract reflects **product reality**, most code governed, only genuine debt frozen
 with a burn-down. A green check over a wrong contract is a **false green**.
 
+**Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
+spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+when design smells remain after the contract is honest.
+
+## When / not when
+
+| Use `/ark-adopt` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| Existing messy repo; contract ≠ folders | Empty greenfield shape → `/ark-architect` |
+| False-green / concentrated edge needs contract truth | Map-only without writing config/baseline → `/ark-explore` |
+| Mine loose business rules into Domain / intents | Single violation fix → `/ark-fix` |
+| Freeze **real** debt after contract is honest | Grind plan A only → `/ark-loop`; full apply loop → `/ark-autopilot` |
 
 ## Dual engine (mandatory)
 
@@ -78,22 +90,33 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
 6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
-7. **Ratchet + opportunity plan** — ranked residual edges + **explore-style bets** (what to improve next week).
+7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
+   - Name phase: **Align** (contract honesty) → **Stabilize** (baseline real) → **Shape** (golden pattern).
+   - If plan A is empty but the tree still shows concurrent patterns, god modules, facade SQL,
+     domain logic in UI, or semantic false-green: emit **dual-plan B** (3–5 bets) with pilot,
+     success signal, kill-switch, and extraction cards for I/O moves — same bar as `/ark-explore` §G.
+   - Do **not** claim “adopt complete / healthy” solely because the check is green.
+   - Prefer handoff `/ark-autopilot` for B execution with user ok, or `/ark-explore` shape-focus
+     if the user only wanted a plan.
 
 ## Operating modes
 
 Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
+**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
 
 ## Verify
 
 `ark-check --root . --config ark.config.json --strict-config` (+ baseline only if non-empty file retained).
-Report: governed% before/after, files written, frozen count, false positives avoided, manifest/intent proposals applied or deferred, **top opportunities still open**.
+Report: governed% before/after, files written, frozen count, false positives avoided, manifest/intent
+proposals applied or deferred, **phase**, **top Shape / design-weak opportunities still open**
+(with success signals).
 
 ## Never
 
 - Freeze false positives to get green.
 - Force runtime kernel over existing Nest/DI.
 - Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
+- End adopt with only “baseline written” when design-weak residual is visible in files you opened.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-architect.md

@@ -5,6 +5,13 @@ description: Choose the application shape, adopt phase-1 layers, scaffold direct
 
 # /ark-architect — Choose your application shape and adopt Ark
 
+## When / not when
+
+| Use `/ark-architect` when… | Do **not** use it when… |
+|----------------------------|-------------------------|
+| Greenfield / thin tree; pick shape + phase-1 layers | Existing spaghetti brownfield → `/ark-adopt` (+ `/ark-explore` first if map missing) |
+| Enthusiast before heavy codegen | Enforcement residual on mature tree → `/ark-autopilot` |
+
 The user is building something new or early in Ark adoption. They may not know
 layered architecture jargon. Your job: translate **what they want to build**
 (application shape, not framework name) into an Ark preset, a phase-1 layer plan,
@@ -44,8 +51,9 @@ the same files or weaken the gate.
 
 1. **Detect the shape** — call MCP tool **`ark_recommend`** (or run
    `ark-check --recommend --json`). Read `archetype`, `preset`, `confidence`,
-   `adoptInOrder.phase1`, `analogy`, and `why`. Ask at most **two** questions only
-   if `confidence < 0.5`:
+   `adoptInOrder.phase1`, `analogy`, `why`, `evidence`, and `requiresConfirmation`.
+   Ask at most **two** questions only if `requiresConfirmation` is true (or for compatibility
+   with older ArkGate output, `confidence < 0.5`):
    - "Will this app save data between sessions?"
    - "Is this one app or several in one repository?"
 

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)