arkgate 2.9.1 → 2.10.0

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):
@@ -49,7 +66,7 @@ forensics, baseline taxonomy) for tech leads.
 
 When explaining the **plan**, name the four `mechanical-safe` remediation kinds only
 (type-only move, pure-type file relocate, `import type` of pure-type modules,
-`import-type-of-type-exports` for named type exports from mixed modules) — everything
+`import-type-of-type-exports` for named type exports from mixed modules; W6 port-proof inject is judgment when proof holds) — everything
 else is judgment/deferred and must not be auto-applied.
 
 ## Spoken / written explanation
@@ -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.

package/templates/skills/ark-explore.md

@@ -0,0 +1,119 @@
+---
+name: ark-explore
+description: Exploratory architecture reconnaissance of the real project — product map, entry points, coupling hotspots, false-green risks, and suggestive next bets. CLI is a sensor; you read the tree. No gate bypass.
+---
+
+# /ark-explore — Recon the real project
+
+You are a **staff engineer doing architecture reconnaissance** on *this* repository.
+Ark’s CLI is a **sensor** (coverage, doctor, plan). **You** open source, README, entry
+points, and git history. Output is **suggestive and ranked**, not a green checkbox.
+
+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.
+
+## 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).
+- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+
+## 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, hotspots, false greens, opportunities | Only paraphrasing CLI JSON |
+
+**Incomplete:** doctor/coverage dump with no file paths you opened.  
+**Complete:** map + ranked bets + “así te lo re-soluciono” with real paths.
+
+
+## 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.
+
+## Anti-wrapper rule
+
+**Forbidden:** only `ark-check --json` / `--coverage` / `--doctor` paraphrase.
+
+**Required:**
+1. Sensor: `--coverage --json`, `--doctor`, optional `--plan --json` / normal check.
+2. **Product + code pass** (below) — min **12 source files** across **≥4 directories** that matter for *this* product (apps, packages, features, domain, adapters, API routes).
+3. Ranked **suggestions** (opportunities), not only residual violations.
+4. Hard lines: never weaken the contract; never invent mechanical-safe kinds.
+
+## Reconnaissance pass (do all that apply)
+
+### A. Product surface (what the system is)
+- README / package.json `description` / scripts / monorepo workspace roots.
+- User-facing entry: Next/Nest/Express routes, CLIs, workers, public APIs.
+- Deploy shape if obvious (apps/, packages/, services/).
+- One paragraph: **“What does this product do for a real user?”**
+
+### B. Architecture as lived (not only as configured)
+- Map top dirs → intended layer vs what code *actually* does (UI, use-cases, I/O, pure domain).
+- Empty Domain / Persistence while Application owns `airtable|supabase|prisma|repositories` → **false-green** (doctor id `contract-false-green-io-under-application`).
+- Framework guts vs product code (Nest modules, Next app router, generated clients).
+
+### C. Coupling & debt beyond the plan list
+- Import hotspots, god modules, cross-feature leaks (`peerIsolation` candidates).
+- Business rules in UI/hooks (`can*`, `calculate*`, policy constants) → Domain / intents.
+- Dead or aspirational globs; layers with files but no rules.
+
+### D. Agent / gate reality
+- Write gate + CI + `/ark-*` skills present? Stale skills? Global vs pinned `arkgate`?
+- Baseline: real debt or hiding contract smell?
+
+### E. Suggestive bets (not commits yet)
+For each opportunity: **impact × effort × enforceability** (can the gate hold it after?).
+
+## Output format
+
+1. **Headline** — product in one sentence + honesty (mode, governed%, false-green risk).
+2. **Map** — entry points, major packages/dirs, shape name (or “no honest shape yet”).
+3. **What I opened** — bullet list of paths (prove the explore pass).
+4. **Ranked table**
+
+| # | Kind | Finding | Evidence (path) | Suggestion | Next skill / command |
+
+Kinds: `risk` | `false-green` | `debt` | `opportunity` | `shape` | `manifiesto` | `agent-dx`
+
+5. **Top 3 bets** — if the user says “go”, which skill runs first and why.
+   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).
+6. **Deterministic residue** — if plan has steps, point to `/ark-loop` / `/ark-fix` without claiming they are the whole architecture story.
+
+## Done criteria
+
+- ≥12 source files read and cited.
+- At least **3 suggestive** rows (not only “fix violation X”).
+- Clear handoff: `/ark-adopt` | `/ark-contract` | `/ark-autopilot` | `/ark-loop` | stop.
+- No gate weakening; no false ENFORCE claim.
+
+## 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-fix.md

@@ -1,17 +1,45 @@
 ---
 name: ark-fix
-description: Resolve Ark architecture violations at the root cause — ports, adapters, moves, intent/manifest alignment. Never weaken the contract. Read the real code; CLI only validates.
+description: Resolve Ark architecture violations at the root cause — read importers and product context, design ports/adapters/moves/intent alignment. Never weaken the contract. CLI only validates.
 ---
 
 # /ark-fix — Fix architecture violations at the root
 
 You fix violations Ark reports. Prefer structural fixes over silencing the gate.
+**Read the surrounding product code** (callers, package role, feature ownership) — not only
+the two files on the violation edge.
 
 
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | Violation list, plan kinds, post-edit `ark-check` |
+| **Exploratory** | Why this edge exists in *this* product; better home; manifiesto if the rule is business |
+
+
+## Subagent fan-out (optional, host-dependent)
+
+When the user asks to go faster **or** the work naturally splits (multiple packages,
+feature dirs, plan clusters), you **may** dispatch **subagents**:
+
+| Host capability | Behavior |
+|-----------------|----------|
+| **Parallel subagents supported** (e.g. multi-agent / `spawn_subagent` / concurrent Agent tools) | Launch **2–N** agents in **one wave** with **disjoint path scopes**. Prefer **read-only** explore agents for mapping; at most **one writer** unless the host gives isolated worktrees. Parent merges findings, then runs `ark-check` once. |
+| **Not supported** (single agent only) | **Fall back to sequential** — same checklist, one cluster/step at a time. Never claim parallel work you did not run. |
+
+**Rules:**
+1. Give each subagent a **tight brief**: paths in scope, sensor commands allowed, deliverable shape (paths opened + findings JSON or bullets).
+2. **No shared mutable files** across parallel writers.
+3. STOP handoffs and dual-engine rules still apply in every agent.
+4. Parent owns the **### Completion** block (union of **Opened**, single **Handoff**).
+5. Do **not** use subagents to weaken the gate or invent `mechanical-safe` kinds.
+
 ## Related onboarding
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
 - **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Map first:** `/ark-explore` when the violation is one of many structural smells.
 - **peerIsolation / cross-slice:** always **judgment** — extract to shared, events/ports, or redesign ownership. Never auto-apply cross-feature or cross-context moves.
 - **`vertical-slice` ownership:** feature code stays under `src/features/<slice>/…` (no sibling-slice imports); shared primitives in `src/shared/`; infra in `src/lib/`; shell in `src/app/`. Cross-feature edges are peerIsolation — extract shared or use events/ports.
 - **`ddd-bounded-contexts` ownership:** code under `src/contexts/<context>/{domain,application,infrastructure,presentation}/`; shared kernel only under `src/shared/kernel/`. Cross-context imports (same or cross technical layer) are peerIsolation — integrate via application APIs/events, not peer technical layers.
@@ -23,7 +51,10 @@ You fix violations Ark reports. Prefer structural fixes over silencing the gate.
 
 **Required:**
 1. Run `ark-check` as **sensor** (and `--plan --json` if multi-step) — CLI validates; you remediate.
-2. **Read** each violated file and its import target.
+2. **Read** each violated file and its import target (plus callers that explain product role).
+   If the wall is a concentrated contract smell: **STOP — do not continue this skill as complete.** **STOP — concentrated edge: invoke /ark-contract with source evidence** (do not freeze a wrong contract or grind N freezes).
+   If false-green cores: **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
+   If many residuals: **STOP — do not continue this skill as complete.** **STOP — bulk residual debt: invoke /ark-loop or /ark-autopilot** instead of ad-hoc multi-file grinding without a plan.
 3. **“Así te lo re-soluciono”** — concrete change before editing.
 4. After edits: `ark-check --strict-config` (and baseline if configured).
 
@@ -56,3 +87,17 @@ If the “fix” is really a missing business intent or Domain home for a rule:
 
 - Targeted violations gone; no new ones.
 - Report: what moved, what was intentional default, what needs user decision.
+
+## Completion contract (skill incomplete if missing)
+
+End with **exactly** these headings (markdown `###`):
+
+### Completion
+- **Sensor:** commands/tools run
+- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
+- **Result:** one-line outcome
+- **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-loop.md

@@ -1,6 +1,6 @@
 ---
 name: ark-loop
-description: Drive ark-check --plan to zero active violations. Auto-apply only mechanical-safe kinds; design judgment fixes from real source. CLI is the validator — you edit code.
+description: Drive ark-check --plan to zero active violations. Read real source, auto-apply only mechanical-safe kinds, design judgment from the product tree. CLI validates — you edit code.
 ---
 
 # /ark-loop — Apply the plan safely
@@ -8,22 +8,54 @@ description: Drive ark-check --plan to zero active violations. Auto-apply only m
 Read Ark’s classified **plan**, work toward **goal.met**, one small step at a time,
 validating every change with `ark-check` and rolling back regressions.
 
+Deterministic kinds stay **tight**. Your job is still **exploratory on the files**: open
+importers/targets, see if the plan step is a symptom of wrong shape / false Domain / I/O
+under Application — escalate to `/ark-contract` or `/ark-explore` when the wall is structural.
+
 
 ## Related onboarding
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
 - **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Map / opportunities:** `/ark-explore`.
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | Only the four `mechanical-safe` kinds auto-apply; plan tags; gate re-check |
+| **Exploratory** | Read sources; detect concentrated edges / false-green / wrong layer home before grinding |
+
+
+## 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.
+
 ## Anti-wrapper rule (mandatory)
 
 **Forbidden:** re-printing plan JSON without opening sources, or inventing new “safe” kinds.
 
 **Required:**
 1. `--plan --json` as sensor.
-2. For each step you touch: **read** `file` and `target` source.
+2. For each step you touch: **read** `file` and `target` source (and enough callers to know the edge).
 3. **“Así te lo re-soluciono”** — exact edit before applying.
 4. After each apply: full gate re-run; rollback if targeted violation remains or new ones appear.
+5. 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).
+6. If empty cores + I/O under Application: **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`.
 
 ## mechanical-safe only (auto)
 
@@ -33,8 +65,9 @@ validating every change with `ark-check` and rolling back regressions.
 | `pure-type-file-relocate` | Relocate pure-type file to owning layer (or rename out of false Domain globs) |
 | `import-type-from-pure-type-module` | Convert value import of pure-type module to `import type` |
 | `import-type-of-type-exports` | Convert value-syntax named import/export of type-only exports from a mixed module to `import type` / `export type` |
+| *(none for port-proof)* | **W6** `port-proof-inject-binding` is **judgment** (arity change) — propose inject; do not auto-apply |
 
-Never auto: value imports (including mixed bindings with values), dynamic import/require, forbidden globals, cycles, infra moves.
+Never auto: free value uses of imports, multi-import files, dynamic import/require, forbidden globals, cycles, port-proof inject, multi-file adapter scaffolding without proof.
 
 ## Steps
 
@@ -56,3 +89,17 @@ Never auto: value imports (including mixed bindings with values), dynamic import
 - Gate confirms each kept edit.
 - Honest residual list with **Así te lo re-soluciono** for anything left.
 - If residual steps hide domain/business rules in the wrong layer, call out **manifiesto** work (`intentPrefixes` / Domain placement) via `/ark-contract` or `/ark-adopt`.
+
+## 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-place.md

@@ -18,6 +18,23 @@ plus the not-yet-adopted `suggestedLayers` as a footnote. Then ask what they wan
 to place. That map is derived entirely from the repo, so producing it is real work,
 not a stalling question.
 
+## 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.
+
 ## Steps
 
 1. **Read the contract, not your intuition.** If the `ark` MCP server is available,
@@ -51,6 +68,11 @@ not a stalling question.
 5. **If asked to create it**: scaffold the file(s) in place, following the
    nearest existing sibling's style, and any port/adapter split the rules force.
 
+## Critical handoffs
+
+- If the user needs bulk adoption / wrong contract, not a single artifact: **STOP — do not continue this skill as complete.** **STOP — wrong skill: invoke /ark-adopt or /ark-contract** instead of ad-hoc multi-file grinding without a plan.
+- If contract lacks a home for the artifact: **STOP — do not continue this skill as complete.** Adopt the layer via `/ark-contract` first.
+
 ## Operating rules
 
 - Never ask "which layer do you prefer?" — the contract decides; you translate.
@@ -73,3 +95,17 @@ not a stalling question.
 If you created files, run `ark-check --root . --config ark.config.json
 --strict-config` and make it pass. Report: placement + why, files created (if
 any), and the import rules the new code must respect going forward.
+
+## 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-runtime.md

@@ -11,6 +11,23 @@ policy engine, workflow/saga coordination, projections, observability hooks,
 and NestJS adapters. This skill migrates hand-rolled versions of those to the
 kernel, one feature at a time.
 
+## 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.
+
 ## Steps
 
 1. **Inventory** — grep the codebase for hand-rolled equivalents:
@@ -40,6 +57,11 @@ kernel, one feature at a time.
    something the inventory only *suspects* is dead (a misclassified load-bearing
    emitter must not be removed on a guess).
 
+## Critical handoffs
+
+- No static gates yet: **STOP — do not continue this skill as complete.** Run `/ark-architect` or `/ark-adopt` first.
+- Inventory finds nothing: stop; do not introduce kernel speculatively.
+
 ## Operating rules
 
 - If the inventory finds NO hand-rolled equivalents, say so and stop — do not
@@ -60,3 +82,17 @@ kernel, one feature at a time.
 Run the project's tests plus `ark-check --root . --config ark.config.json
 --strict-config`. Report: what was migrated, lines deleted vs added, remaining
 candidates ranked, and any behavior differences (e.g. bounded history).
+
+## 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.