arkgate 2.9.1 → 2.10.0

package/docs/agent-guide.md

@@ -178,6 +178,20 @@ reference, and explanation for the full path (recommend → init → gallery →
 5. Use `/ark-place` or `ark_place` for individual files after the contract exists.
 6. Verify with `ark-check --root . --config ark.config.json --strict-config`.
 
+### Write protocol (2.10+ / Track W)
+
+Prefer preparing the write before the host commits it to disk:
+
+| Surface | Role |
+|---------|------|
+| MCP **`ark_prepare_write`** | Place + constrain + validate + optional `autoPatch` + `judgmentBrief` + contentHash in one call |
+| Write-gate **`autoPatch`** | Mechanical-safe **import type** rewrites only; post-patch revalidation green or discarded |
+| PreToolUse **`--hook-repair`** | On deny: `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` on stderr (still exit 2 — never silent write) |
+| Doctor **`writePath`** | Reports `repair` \| `reject-only` \| `mcp-only` \| `none` for installed gates |
+
+Port-proof inject binding is **judgment** for auto-apply (signature/arity change), not write-path autoPatch.
+Full reference: [ai-gates.md](ai-gates.md). Loop-cost harness: `npm run eval:loop-cost`.
+
 Do not invent layers outside the 11-layer profile or named presets. Unrecognized
 directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`.
 

package/docs/ai-gates.md

@@ -38,6 +38,11 @@ GitHub Actions, `AGENTS.md`, a Codex TOML snippet under `docs/`, and (when
 selected) Grok Build project files under `.grok/`. It skips existing files unless
 you pass `--force`, so review and commit only the templates that match your project.
 
+**Doctor (W5):** `ark-check --doctor --json` includes `doctor.writePath`
+(`mode`: `repair` | `reject-only` | `mcp-only` | `none`, plus `prepareWrite` /
+`autoPatch` flags) so leads can see whether the write path is repair-capable or
+still reject-only.
+
 If your project uses Codex or Grok, treat MCP registration as part of the default
 setup, not an optional extra. Ark works best when the agent can read `ark://manifest`
 before it writes code; that is the fast path to avoiding architecture drift during
@@ -52,6 +57,40 @@ violations relative to the file's current on-disk state, so files with pre-exist
 (baselined) violations stay editable — they just can't get worse. New files block on
 every violation.
 
+### Opt-in repair payload (W4)
+
+Default is **hard block with prose** on stderr. Hosts that can re-inject a fixed write
+can enable a **machine-readable repair payload** (still exit `2` — **never** silent write):
+
+| Enable | Effect on deny |
+|--------|----------------|
+| `--hook-repair` | Emit `ARK_REPAIR_JSON:…` and, when available, `ARK_AUTOPATCH_JSON:…` on stderr |
+| `ARK_HOOK_REPAIR=1` | Same as `--hook-repair` (env, no template rewrite) |
+
+`ARK_REPAIR_JSON` shape (stable additive):
+
+```json
+{
+  "mode": "repair",
+  "decision": "deny",
+  "filePath": "src/domain/use.ts",
+  "layer": "DomainModel",
+  "autoPatch": {
+    "source": "import type { Row } from '../infra/types-only';\n…",
+    "remediationKind": "import-type-from-pure-type-module",
+    "confidence": 0.85,
+    "valid": true
+  }
+}
+```
+
+When no mechanical-safe patch applies, `autoPatch` is `null` (host still re-reasons or uses
+`ark_prepare_write` / judgment). Grok deny JSON also includes `autoPatch` + `"repair": true`
+when repair mode is on.
+
+`--install-agent-gates` writes Claude/Grok PreToolUse commands with `--hook-repair` enabled.
+Reject-only installs: drop `--hook-repair` (or unset `ARK_HOOK_REPAIR`).
+
 Add to your project's `.claude/settings.json`:
 
 ```json
@@ -63,7 +102,7 @@ Add to your project's `.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+            "command": "npx ark-mcp --hook --hook-repair --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
           }
         ]
       }
@@ -124,10 +163,11 @@ prints nothing and exits 0, so non-Ark projects are untouched.
 
 ## Claude Code — MCP server (contract discovery + on-demand validation)
 
-The MCP server exposes a resource and four tools agents can use proactively:
+The MCP server exposes a resource and tools agents can use proactively (not an exhaustive list — `tools/list` is authoritative):
 
 - **`ark://manifest`** (resource) — the machine-readable architecture contract (layers + rules), so the agent can read the architecture before generating code.
-- **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate).
+- **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate). May return additive **`autoPatch`** (W1) for mechanical-safe import-type rewrites.
+- **`ark_prepare_write`** (tool) — **W2:** place + constrain + validate + optional autoPatch + judgmentBrief + contentHash in one call (composes `ark_place` + write gate).
 - **`ark_place`** (tool) — given a target file path, returns its layer, forbidden globals, and which layers it may / must not import. Call it *before* writing a new file so generated code lands in a governed location.
 - **`ark_check`** (tool) — runs the full architecture check and returns structured violations (applies the baseline automatically when one exists).
 - **`ark_coverage`** (tool) — per-layer file counts, the full unclassified-file list, and layers whose patterns match nothing.

package/docs/enthusiast/how-to-agent-gates.md

@@ -9,6 +9,10 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 Installs:
 
 - Write-gate hook configuration (Claude / Grok PreToolUse; Cursor advisory + MCP)
+  — PreToolUse uses **`--hook-repair`** (W4): on deny, stderr may include
+  `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` for hosts that re-inject a patch.
+  Still exit 2 / hard block; never silent write. Drop `--hook-repair` for
+  reject-only prose, or set `ARK_HOOK_REPAIR=0` and omit the flag.
 - MCP server entry (`.mcp.json`, Cursor/Codex/Grok equivalents)
 - `/ark-*` skills including **`/ark-architect`**, **`/ark-autopilot`**, **`/ark-loop`**
   (with current `mechanical-safe` remediation kinds)
@@ -35,6 +39,10 @@ npx arkgate-check --doctor
 npx arkgate-check --require-gates
 ```
 
+Doctor JSON (`--doctor --json`) includes **`writePath`**: whether PreToolUse is
+`repair` (machine-readable autoPatch on deny), `reject-only`, `mcp-only`, or
+`none` — plus `prepareWrite` / `autoPatch` booleans for leads.
+
 After upgrading the package, refresh skills so agents see the latest plan kinds:
 
 ```bash

package/docs/enthusiast/reference-commands.md

@@ -52,7 +52,7 @@ arkgate-check --watch
 | `class` | Agent may auto-apply? | Examples (`remediationKind`) |
 |---------|----------------------|------------------------------|
 | `mechanical-safe` | Yes (validate + rollback) | `type-only-import-move`, `pure-type-file-relocate`, `import-type-from-pure-type-module`, `import-type-of-type-exports` |
-| `judgment` | No — propose | value imports, ports, infra relocate, cycles |
+| `judgment` | No — propose | free value-import uses, multi-file ports, **W6 port-proof inject** (arity change), infra relocate, cycles |
 | `deferred` | No | unclear shape |
 
 ## Violation JSON (enthusiast fields)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -79,6 +79,7 @@
     "eval:agent": "node eval/run.mjs",
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
+    "eval:loop-cost": "node eval/loop-cost-run.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.9.1",
+  "version": "2.10.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.9.1",
+      "version": "2.10.0",
       "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.