arkgate 2.9.0 → 2.9.2

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)
 
@@ -56,3 +88,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.

package/templates/skills/ark-think.md

@@ -1,6 +1,6 @@
 ---
 name: ark-think
-description: "Host-side architectural reasoning within the Ark contract — trade-offs, evolution, design options. No gate bypass. No package LLM call."
+description: "Host-side architectural reasoning — exploratory options from real code + contract, trade-offs, evolution paths. No gate bypass. No package LLM call."
 ---
 
 # /ark-think — Architectural reasoning (host LLM only)
@@ -9,35 +9,86 @@ You are the user's architecture thinking partner **inside** the project's Ark co
 This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)
 reason; the write-gate and CI remain deterministic.
 
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | What the contract and doctor *prove* today (layers, rules, governed%, gaps) |
+| **Exploratory** | What *this* codebase wants to become — options grounded in files you open |
+
+Never reason only from abstract hexagons. Open real modules before recommending a 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.
+
 ## When to use
 
 - Design trade-offs before writing code
-- "Should this be a new layer or a feature slice?"
+- “Should this be a new layer or a feature slice?”
 - Evolving brownfield layout toward a named preset
 - Explaining why a peerIsolation or layer rule exists
+- Choosing among 2–3 enforceable futures (not infinite diagrams)
 
 ## Steps
 
 1. **Load the contract** — `ark.config.json`, MCP `ark://manifest` if available, and
-   `ark-check --coverage --json` / `--doctor` for honesty about governed%.
-2. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,
-   ddd-bounded-contexts, feature-sliced, monorepo, …). If none, run `--recommend --json`.
-3. **Reason within bounds** — propose options that **stay enforceable** by the gate.
+   `ark-check --coverage --json` / `--doctor` for honesty about governed% and false-green.
+2. **Touch the product** — README + **≥5 source files** on the decision surface (the feature,
+   package, or boundary under discussion). Name paths in the answer.
+3. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,
+   ddd-bounded-contexts, feature-sliced, monorepo, …). If none, run `--recommend --json`
+   **and** say whether detection matches the tree you opened.
+4. **Reason within bounds** — propose options that **stay enforceable** by the gate.
    Prefer concrete paths and import rules over abstract diagrams.
-4. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
+5. **Explore alternatives** — for each option: coupling, testability, **AI-agent safety**
+   (will write-gate + skills keep humans honest?), migration cost.
+6. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
    judgment auto-apply, codemod engines, or skipping write-gate/CI.
-5. **Hand off** — for placement use `/ark-place`; for config edits `/ark-contract`; for
-   bulk debt `/ark-loop` / `/ark-autopilot`; for violations `/ark-fix`.
+7. **Hand off** — placement `/ark-place`; config `/ark-contract`; bulk debt `/ark-loop` /
+   `/ark-autopilot`; map-only `/ark-explore`; violations `/ark-fix`.
+   When the user needs action not advice: **STOP — do not continue this skill as complete** — invoke the handoff skill.
 
 ## Output format
 
-- **Context:** 2–3 sentences on current contract + shape
-- **Options:** 2–3 alternatives with trade-offs (coupling, testability, AI-agent safety)
-- **Recommendation:** one option + why it is enforceable today
+- **Context:** product + contract + what you opened (paths)
+- **Options:** 2–3 alternatives with trade-offs (coupling, testability, agent safety, enforceability)
+- **Recommendation:** one option + why it is enforceable **today**
+- **Risks if we pick wrong:** one sentence user-visible impact
 - **Next command:** exact `ark-check` / skill to run next
 
 ## Related
 
 - Greenfield shape: `/ark-architect`
 - Brownfield: `/ark-adopt`
+- Full recon: `/ark-explore`
 - Explain existing: `/ark-explain`
+
+## 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-upgrade.md

@@ -38,6 +38,23 @@ read the **Adoption** section — host gaps, Codex home temp paths, optional-but
 core layers, missing origin snapshot, baseline policy. Fix commands are printed per gap.
 HTML reports include the same Adoption card (separate from the 0–100 fitness score).
 
+## 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.
+
 ## Fast path
 
 One command does the whole flow — update the package, refresh gates + `/ark-*` skills
@@ -113,7 +130,8 @@ npx arkgate-check --install-agent-gates --skills-only --force
 4. **Re-verify** — `ark-check --root . --config ark.config.json
    --strict-config` (with `--baseline .ark-baseline.json` if present). A new
    version may detect violations the old one missed: if new violations appear,
-   apply `/ark-fix` reasoning to resolve them. If they are too numerous to fix
+   **STOP — do not continue this skill as complete.** **STOP — bulk residual debt: invoke /ark-loop or /ark-autopilot**
+   (or `/ark-fix` for a small set). If they are too numerous to fix
    now, freezing them in the baseline (`--update-baseline`) is a valid stopgap
    but it silences NEW violations, so it requires explicit user approval first
    — never regenerate the baseline on your own to get a green check.
@@ -142,3 +160,17 @@ End with a passing check. Report: latest published version, old → new version
 (or "already latest"), changelog entries that mattered here (plain language),
 files written/refreshed per tool, skipped customized files needing a manual
 look, and the final check status.
+
+## 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.