arkgate 2.9.1 → 2.9.2

package/package.json

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

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.9.1",
+  "version": "2.9.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.9.1",
+      "version": "2.9.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-adopt.md

@@ -1,18 +1,44 @@
 ---
 name: ark-adopt
-description: Brownfield onboarding — match contract to real code, classify ungoverned dirs, mine loose business rules into the Ark manifest/intents, freeze only real debt. Deep source analysis required.
+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.
 ---
 
 # /ark-adopt — Bring Ark into an existing codebase
 
-Goal: contract reflects reality, most code governed, only genuine debt frozen with a burn-down.
-A green check over a wrong contract is a **false green**.
+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**.
 
 
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | coverage, doctor, baseline, strict-config after edits |
+| **Exploratory** | walk the real monorepo/app layout; reclassify; mine rules; suggest shape |
+
+
+## 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.
+- **Deep map only:** `/ark-explore`.
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
 ## Anti-wrapper rule (mandatory)
@@ -21,9 +47,12 @@ A green check over a wrong contract is a **false green**.
 
 **Required:**
 1. CLI sensor: `--coverage --json`, check `--json` (`summary`), doctor.
-2. **Read real source** in largest ungoverned dirs and top import edges (min **10 files**).
-3. **“Así te lo re-soluciono”** — concrete layer globs, file moves, and manifest/intent proposals.
-4. Never freeze a concentrated edge without investigating contract smell.
+2. **Product map** — what ships, which apps/packages, entry routes/CLIs.
+3. **Read real source** in largest ungoverned dirs and top import edges (min **12 files**
+   across **≥4 dirs**).
+4. **“Así te lo re-soluciono”** — concrete layer globs, file moves, manifest/intent proposals.
+5. **Suggestive burn-down** — ranked next steps after adopt (not only “baseline done”).
+6. Never freeze a concentrated edge without investigating contract smell / false-green.
 
 ## Guiding principle
 
@@ -37,7 +66,11 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    If `src/contexts` or `src/bounded-contexts` exists, prefer `ddd-bounded-contexts`.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
    Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
-3. **Classify ungoverned** — use coverage `suggestions`; add layers/patterns via `/ark-contract`.
+   If one edge dominates residual debt: **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).
+   Empty Domain/Persistence + I/O under Application → 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`.
+3. **Classify ungoverned** — use coverage `suggestions` **plus** dirs you discovered by reading;
+   add layers/patterns via `/ark-contract`.
 4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
    - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
    - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used.
@@ -45,7 +78,7 @@ 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 plan** — ranked edges + which are false positives avoided.
+7. **Ratchet + opportunity plan** — ranked residual edges + **explore-style bets** (what to improve next week).
 
 ## Operating modes
 
@@ -54,10 +87,24 @@ Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
 ## 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.
+Report: governed% before/after, files written, frozen count, false positives avoided, manifest/intent proposals applied or deferred, **top opportunities still open**.
 
 ## Never
 
 - Freeze false positives to get green.
 - Force runtime kernel over existing Nest/DI.
-- Claim Enforce while governed% is low or core bags ungoverned.
+- Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
+
+## 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
+- **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/skills/ark-architect.md

@@ -13,6 +13,23 @@ conventional directories, and a passing honest check — without weakening the g
 Commands below are written as `ark-check` / `ark`; run each through the project's
 package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
 
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | CLI / MCP / contract sensors — exit codes, plan kinds, coverage numbers, install status |
+| **Exploratory** | You open **this** repo's real files and product surface before concluding |
+
+The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
+
+
+## Subagent fan-out (optional, host-dependent)
+
+If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
+dirs to sample), fan out read-only scouts; otherwise **fall back to sequential**.
+Parent merges and still emits the **### Completion** contract. Never parallel-write
+the same files or weaken the gate.
+
 ## Relationship to other skills
 
 | Skill | When |
@@ -40,7 +57,7 @@ package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
    or `ark-check --apply-policy-pack enthusiast-<preset>` for the enthusiast variant.
    Optional team record: `ark-check --recommend --write-plan` → `ark-adoption-plan.json`.
    If a config already exists, use `/ark-contract` to align it — do not regenerate
-   unasked.
+   unasked. On a messy brownfield tree: **STOP — do not continue this skill as complete.** Invoke **/ark-adopt** instead of forcing greenfield shape.
 
 4. **Scaffold phase 1** — create conventional directories from the preset/playbook
    (`src/domain`, `src/application`, …). Add a one-line README per folder explaining
@@ -91,4 +108,18 @@ package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
 
 End with `ark-check --root . --config ark.config.json --strict-config` when the
 tree is ready. Report: archetype + preset, directories created, governed %, and
-the next command if anything remains ungoverned.
+the next command if anything remains ungoverned.
+
+## 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
+- **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/skills/ark-autopilot.md

@@ -1,11 +1,11 @@
 ---
 name: ark-autopilot
-description: End-to-end architecture co-pilot — setup, deep plan from real code, apply mechanical-safe fixes, design and apply judgment fixes when the user asks for full apply. CLI is a sensor; you remediate files.
+description: End-to-end architecture co-pilot — exploratory map of the real project, then setup, deep plan from source, mechanical-safe fixes, and judgment design. CLI is a sensor; you read and remediate files.
 ---
 
 # /ark-autopilot — Get to a sound architecture, end to end
 
-Composes **setup + plan + loop**. Safe default: auto-apply only `mechanical-safe`;
+Composes **explore + setup + plan + loop**. Safe default: auto-apply only `mechanical-safe`;
 when the user says full apply / “al mango” / apply everything, also execute
 **judgment** fixes you design from reading source (still validate with ark-check,
 never weaken the gate).
@@ -15,47 +15,86 @@ never weaken the gate).
 
 - **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` — reconnaissance without applying fixes.
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
-## Anti-wrapper rule (mandatory)
+## Dual engine (mandatory)
 
-**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without reading the violating files.
+| Engine | Role |
+|--------|------|
+| **Deterministic** | `ark-check` plan/coverage/doctor, mechanical-safe kinds, write/CI gates, exit codes |
+| **Exploratory** | You map **this** product’s real tree: entry points, packages, coupling, false greens, opportunities |
+
+**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without reading the violating files **and** without a short product map.
 
 **Required:**
-1. CLI sensor: `ark-check --plan --json`, coverage/doctor as needed.
-2. **Open every file** in the plan’s `steps[]` (and its `target` if present) before classifying a fix.
-3. **“Así te lo re-soluciono”** for each cluster of steps: exact moves (extract type, relocate file, invert dependency).
-4. Apply → re-run ark-check → rollback on regression.
+1. **Explore pass** (below) before claiming a loop strategy.
+2. CLI sensor: `ark-check --plan --json`, coverage/doctor as needed.
+3. **Open every file** in the plan’s `steps[]` (and its `target` if present) before classifying a fix.
+4. **“Así te lo re-soluciono”** for each cluster: exact moves (extract type, relocate file, invert dependency).
+5. Apply → re-run ark-check → rollback on regression.
+
+
+## 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.
+
+## Explore pass (before grinding the plan)
+
+Do this even if the plan is non-empty — plan lists *violations*, not *product reality*.
+
+1. **Product one-liner** — README + main package(s) + what the user gets.
+2. **Entry points** — apps, APIs, CLIs, workers (min paths named).
+3. **Lived layout** — which dirs are really Domain / Application / I/O / UI vs what globs claim.
+4. **False-green soft block** — doctor / coverage: empty Domain/Persistence while Application
+   globs still cover 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`.
+5. **Suggestive top bets** — 2–5 opportunities ranked (shape, extract, manifiesto, gates/DX),
+   separate from mechanical-safe steps. User may defer; still list them.
+
+Min bar: **≥8 source files** across **≥3 meaningful directories** (not only files in `steps[]`).
+
+For a full reconnaissance report, run or fold in `/ark-explore`.
 
 ## Operating modes (detected, not picked)
 
 - **Setup (Suggest):** no config → `ark start` / recommend shape.
-- **Align (Adapt):** open debt or low honesty → drive loop; do not claim “guarded”.
-- **Guard (Enforce):** `goal.met` and solid governed% → install/confirm gates and stop.
+- **Align (Adapt):** open debt, low honesty, or false-green → explore + adopt/loop; do not claim “guarded”.
+- **Guard (Enforce):** `goal.met`, solid governed%, no false-green → install/confirm gates and stop.
 
 ## Flow
 
-0. **False-green soft block (mandatory before victory)** — Run `ark-check --doctor` (or `--coverage`).
-   If Domain/Persistence (or similar cores) are **empty** while Application-class globs still cover
-   I/O dirs (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …), **do not** claim
-   ENFORCE / `goal.met` from type-only cleanup alone. Route to **`/ark-adopt`** or **`/ark-contract`**
-   first: reclassify real persistence/auth out of Application. Doctor gap id:
-   `contract-false-green-io-under-application`.
+0. **Explore pass** — product map + false-green check + suggestive bets (see above).
 1. **Setup if needed** — `ark start` if no `ark.config.json`. Trust `--recommend` / playbook:
    `vertical-slice-product` and `ddd-bounded-contexts` are first-class shapes (not hexagonal by default).
 2. **Origin report** — `ark-check --report ark-report.html` (do not `--reset-origin` unless asked).
 3. **Plan + code read** — `--plan --json`; read each step’s source/target; group by edge.
    Treat `peerIsolation` / cross-slice steps as **judgment** (never mechanical-safe).
-4. **Concentrated edge?** — if one edge dominates, route to `/ark-contract` with a **source-based** diagnosis (not freeze).
+4. **Concentrated edge?** — if one edge dominates:
+   **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).
 5. **Worktree preferred** — discardable git worktree when possible.
 6. **Mechanical-safe** — only kinds from `/ark-loop` table; one step, validate, rollback.
 7. **Judgment** — default: propose with full “así te lo re-soluciono”. If user authorized full apply: implement the designed fix, validate, rollback on fail.
 8. **Manifiesto** — if loose business rules surface (domain logic in UI/core), propose Domain placement + `intentPrefixes` / intents; apply config only via `/ark-contract` discipline (strict check after).
-9. **Final report** — `--report` again; evolution vs origin; honest summary of auto vs judgment vs deferred.
+9. **Final report** — re-`--report`; evolution vs origin; **explore bets** still open vs auto vs judgment applied vs deferred.
 10. **Strict check** — `ark-check --strict-config` (dead preset globs are advisory; real violations still fail).
 11. **Core ratchet (when green)** — if plan `goal.met` and doctor still **ADAPT** only because
     populated cores are `optional: true`, run `ark-check --ratchet-cores` then `--doctor`.
-    Never ratchet while active violations remain.
+    Never ratchet while active violations remain or false-green gap is open.
 
 ## Never
 
@@ -63,9 +102,25 @@ never weaken the gate).
 - Claim clean while judgment steps were skipped without user decision.
 - Claim ENFORCE / “done” when doctor reports `contract-false-green-io-under-application` (adopt first).
 - Replace host Nest/DI with the runtime kernel unasked.
+- Treat “plan empty” as “architecture is healthy” without the explore pass.
 
 ## Done criteria
 
+- Explore pass completed (product map + paths read + bets listed).
 - Every applied step validated by real `ark-check`.
 - Final plan `goal.met` true **or** remaining steps listed with file-level proposals and why blocked.
-- Report cites paths you changed and reports HTML paths.
+- Report cites paths you changed, open **opportunities**, and report HTML paths.
+
+## 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
+- **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/skills/ark-contract.md

@@ -9,6 +9,23 @@ 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).
 
 
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | CLI / MCP / contract sensors — exit codes, plan kinds, coverage numbers, install status |
+| **Exploratory** | You open **this** repo's real files and product surface before concluding |
+
+The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
+
+
+## Subagent fan-out (optional, host-dependent)
+
+If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
+dirs to sample), fan out read-only scouts; otherwise **fall back to sequential**.
+Parent merges and still emits the **### Completion** contract. Never parallel-write
+the same files or weaken the gate.
+
 ## Related onboarding
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
@@ -50,8 +67,27 @@ Also used to **land mined business rules** into the executable manifest (`ark.co
 
 Contract edits are most common in **Align (Adapt)**. In **Guard (Enforce)**, treat edits as high-risk product decisions.
 
+## Critical handoffs
+
+- After contract is honest but residual violations remain: **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.
+- New artifact home after reclassify: **STOP — do not continue this skill as complete.** **STOP — new file placement: invoke /ark-place** when the user needs a new artifact home.
+
 ## Done
 
 - Diff of `ark.config.json` explained in plain language.
 - **Así te lo re-soluciono en el manifiesto** when intents/Domain were part of the request.
 - Strict check result captured.
+
+## 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
+- **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/skills/ark-coverage.md

@@ -1,23 +1,54 @@
 ---
 name: ark-coverage
-description: Deep-audit this project's real code + Ark adoption gaps. CLI is a sensor only — you must read source, propose concrete remediations, and optional manifest/intent mining. Ranked report with "así te lo re-soluciono".
+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".
 ---
 
 # /ark-coverage — Deep coverage + capability gaps
 
-You audit how this repo uses ArkGate **and** what the **real source tree** needs next.
-Work autonomously. End with a ranked report that includes a concrete fix plan.
+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).
 
-## Anti-wrapper rule (mandatory)
 
-**Forbidden:** reporting only `ark-check --coverage/--doctor/--json` paraphrase, gate checklists, or "unused capability" tables with no source evidence.
+## Dual engine (mandatory)
+
+| Engine | Deliverable |
+|--------|-------------|
+| **Deterministic** | governed%, layers, gates, baseline, doctor gaps, summary edges |
+| **Exploratory** | product map, clusters opened, opportunities beyond “fix violation X” |
+
+**Forbidden:** only `ark-check --coverage/--doctor/--json` paraphrase or gate checklists with no source evidence.
 
 **Required before you finish:**
-1. Run CLI as **sensor** (`--coverage --json`, `--doctor`, normal `--json` for `summary`).
-2. **Read real source** in the top ungoverned / high-coupling clusters (minimum **8 files** across at least **3 directories** that matter). Prefer `src/core/**`, `domain/**`, adapters, etc.
-3. Deliver **“Así te lo re-soluciono”** — file-level moves, contract globs, intent/manifest proposals, not only “run /ark-contract”.
+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.
+
+If you did not open source files, the skill is **not complete**.  
+Full recon-only mode: `/ark-explore`.
+
+
+## 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**:
 
-If you did not open source files, the skill is **not complete**.
+| 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.
 
 ## Operating modes (detected — not user-picked)
 
@@ -25,51 +56,74 @@ If you did not open source files, the skill is **not complete**.
 |------|----------------|--------------------|
 | **Suggest / Setup** | Thin or new tree | “Ark will propose a starting shape — you don’t switch a mode.” |
 | **Adapt / Align** | Contract ≠ folders or open debt | “Gates don’t fully protect you yet — classify + fix plan.” |
-| **Enforce / Guard** | Coverage + clean edges | “You arrived here — keep CI/write gates on.” |
+| **Enforce / Guard** | Coverage + clean edges + honest cores | “You arrived here — keep CI/write gates on.” |
 
-Never say “your architecture is guarded” while `goal.met` is false or governed% is low.
+Never say “your architecture is guarded” while `goal.met` is false, governed% is low,
+or false-green doctor gaps are open.
 
 ## 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). Full apply path is `/ark-adopt` or `/ark-contract` deep mode.
+- **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`.
 
-## Checklist (sensor + code)
+## Checklist (sensor)
 
-1. Config + `ark-check --strict-config` (note: dead preset globs are advisory; unclassified files still fail strict).
+1. Config + `ark-check --strict-config` (dead preset globs advisory; unclassified files still fail strict).
 2. Baseline policy (orphan empty file? wire or delete).
 3. Write gates + `/ark-*` skills per detected agent.
 4. CI workflow + monorepo install reality (`frontend/package.json`?).
 5. ESLint `arkgate/eslint` if ESLint exists.
 6. Domain `forbiddenGlobals`.
-7. **Governed%** + full unclassified + `suggestions` from `--coverage --json`.
+7. **Governed%** + unclassified + `suggestions` from `--coverage --json`.
 8. Concentrated edges in check `summary` → contract smell, not N freezes.
-9. `layersWithoutRules`.
+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 (the model job)
+## Deep code pass (exploratory — the model job)
 
-For each top cluster (e.g. `frontend/src/core/threads`, `components/workspace`):
+For each top cluster (e.g. `src/features/*`, `src/lib/*`, `apps/*/src`):
 
-- Who imports whom (App→Presentation? Domain→App?).
-- Is “core” really application, UI, or mixed?
+- 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, optional Domain extract, intent names (`Domain.*` / `Application.*`).
+- 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?
 
 ## Output format
 
-1. **Headline honesty** — governed%, mode, violations, false-green risk (one paragraph).
+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**
+3. **Ranked table** (mix residual gaps + opportunities)
+
+| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) |
 
-| # | Gap | Evidence (path or CLI) | Así te lo re-soluciono (concrete) |
+Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity`
 
-4. **Manifiesto / reglas de negocio** (if any candidates): list proposed intents / Domain files / config edits.
-5. Offer: “Apply top N?” — apply only if user agrees; then re-run strict check.
+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.
 
 ## Done criteria
 
-- ≥8 source files read and cited.
+- ≥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).
 - CLI numbers used as evidence, not as the whole report.
+
+## 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
+- **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/skills/ark-explain.md

@@ -8,6 +8,23 @@ description: Explain this project's architecture in plain language and generate
 The user wants to understand the architecture, a specific rule, or why the gate blocked them.
 Your job is to **teach with this repo's real data** and leave a shareable visual artifact.
 
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | CLI / MCP / contract sensors — exit codes, plan kinds, coverage numbers, install status |
+| **Exploratory** | You open **this** repo's real files and product surface before concluding |
+
+The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
+
+
+## Subagent fan-out (optional, host-dependent)
+
+If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
+dirs to sample), fan out read-only scouts; otherwise **fall back to sequential**.
+Parent merges and still emits the **### Completion** contract. Never parallel-write
+the same files or weaken the gate.
+
 ## Always do this first (showcase report)
 
 1. Run the full HTML report (uses the real contract + coverage + gates):
@@ -62,7 +79,9 @@ else is judgment/deferred and must not be auto-applied.
    - Enforcement points that are actually on: write gate, CI, ESLint, baseline.
    - If a DI/kernel framework border exists, explain public surface vs internals.
 3. **If asked about a specific rule or block**, answer with: the rule, the consequence it
-   prevents, and the sanctioned fix (usually a port) — offer `/ark-fix`.
+   prevents, and the sanctioned fix (usually a port). If they want it fixed now:
+   **STOP — do not continue this skill as complete.** **STOP — fix requested: invoke /ark-fix.**
+   This skill stays read-only.
 4. **If asked "what's a port/adapter/saga…"**, two sentences + this-repo example or conventional path.
 
 ## Operating rules
@@ -82,3 +101,17 @@ else is judgment/deferred and must not be auto-applied.
 - Onboarding: `/ark-architect`, `ark-check --recommend`, `docs/enthusiast/README.md`
 - Brownfield: `/ark-adopt`, `docs/brownfield-adoption.md`
 - Autopilot: `/ark-autopilot` after the user understands the contract
+
+## 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
+- **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.