arkgate 2.11.0 → 2.13.0

package/server.json

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

package/templates/hooks/pre-commit-ark

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Maintained by ArkGate (Q3) — human-edit architecture gate.
+# Install (git hooks):
+#   cp templates/hooks/pre-commit-ark .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+# Or with husky:
+#   cp templates/hooks/pre-commit-ark .husky/pre-commit && chmod +x .husky/pre-commit
+#
+# Blocks commit when ark-check fails. Does not replace CI branch protection.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+run_check() {
+  if [ -f package.json ] && node -e "const p=require('./package.json');process.exit(p.scripts&&p.scripts['check:architecture']?0:1)" 2>/dev/null; then
+    npm run -s check:architecture
+    return $?
+  fi
+  if [ -f bin/ark-check.mjs ]; then
+    node bin/ark-check.mjs --root . --config ark.config.json --strict-config
+    return $?
+  fi
+  if command -v arkgate-check >/dev/null 2>&1; then
+    arkgate-check --root . --config ark.config.json --strict-config
+    return $?
+  fi
+  if command -v npx >/dev/null 2>&1; then
+    # --yes: pre-commit is non-interactive; never hang on npx install prompts
+    npx --yes --no-install arkgate-check --root . --config ark.config.json --strict-config 2>/dev/null \
+      || npx --yes arkgate-check --root . --config ark.config.json --strict-config
+    return $?
+  fi
+  echo "ark-check not found — install arkgate or add check:architecture script" >&2
+  return 1
+}
+
+run_check

package/templates/skills/ark-autopilot.md

@@ -1,38 +1,44 @@
 ---
 name: ark-autopilot
-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.
+description: End-to-end architecture co-pilot — decision-grade explore first, dual plan (remediation + pattern improvements), mechanical-safe fixes, judgment design. CLI is a sensor; you read and remediate files.
 ---
 
 # /ark-autopilot — Get to a sound architecture, end to end
 
-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,
+Composes **explore → sensors → dual 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).
 
+**Not a plan grinder.** Empty `--plan` does **not** mean “architecture is healthy” without
+the explore pass and dual-plan section B (pattern bets).
+
 
 ## 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` — reconnaissance without applying fixes.
+- **Deep map only:** `/ark-explore` — full recon report without applying fixes.
+- **Adoption metrics only:** `/ark-coverage` — governed% + capability gaps (feeds dual plan B).
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
 ## Dual engine (mandatory)
 
 | 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 |
+| **Deterministic** | `ark-check` plan/coverage/doctor, mechanical-safe kinds, write/CI gates, exit codes, origin snapshot |
+| **Exploratory** | You map **this** product’s real tree: entry points, coupling, false greens, field path, pattern debt |
 
-**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without reading the violating files **and** without a short product map.
+**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without a
+decision-grade explore pass **and** without opening violating files.
 
 **Required:**
-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.
+1. **Explore pass** (below) **before** claiming a loop strategy — same bar as `/ark-explore`, budgeted.
+2. CLI sensors: `--plan --json`, `--coverage --json` / `--doctor` as needed.
+3. **Dual plan** always emitted (sections A and B).
+4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
+5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
+6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
 
 
 ## Subagent fan-out (optional, host-dependent)
@@ -52,64 +58,90 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 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)
+Useful first wave: **core product tree** | **field path** (examples/starters) | **agent install surfaces** (hooks vs templates).
+
+## Explore pass (phase 0 — mandatory, first)
 
-Do this even if the plan is non-empty — plan lists *violations*, not *product reality*.
+Do this **before** grinding plan A — plan lists *violations*, not *product reality*.  
+Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot report, not optional fluff).
 
-1. **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:
+1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise risk).
+2. **Map** — entry points, lived layout vs globs (one screen).
+3. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a`.
+4. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
+5. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
+6. **False-green soft block** — doctor/coverage: empty Domain/Persistence while Application owns I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …). Doctor gap id: `contract-false-green-io-under-application`. If so:
    **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.
+7. **Seed dual plan B** — 2–5 pattern / evolution bets ranked (impact × effort × enforceability).
+
+Min bar: **≥12 source files** across **≥4 meaningful directories** (not only files in `steps[]`).  
+Standalone long report: `/ark-explore`. Adoption numbers deep-dive: `/ark-coverage`.
+
+## Dual plan (always emit)
+
+| Section | Source | Question | Auto-apply? |
+|---------|--------|----------|-------------|
+| **A. Remediation** | `--plan --json` + opened step files | What must change so the gate is honest? | Only `mechanical-safe` by default |
+| **B. Pattern / evolution** | Explore + coverage/doctor | What existing patterns should improve even if A is empty? | **Never** as mechanical-safe |
+
+**Section A** — group by edge; treat `peerIsolation` / cross-slice as **judgment**.  
+**Section B** examples: peerIsolation, move rules out of UI, strengthen starter/preset rules, write-path repair, split god orchestration modules, Domain placement / intents, import surface (`/runtime` vs root). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + success signal.
+
+B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.
 
-Min bar: **≥8 source files** across **≥3 meaningful directories** (not only files in `steps[]`).
+## Origin snapshot (day-zero picture)
 
-For a full reconnaissance report, run or fold in `/ark-explore`.
+- **When:** as soon as `ark.config.json` exists and `.ark/reports/origin.json` is missing — **before** applying fixes and **before** treating “done”. Prefer that `ark start` / `ark init` already froze origin **before** agent docs; if missing, freeze now.
+- **How:** `ark-check --report ark-report.html` (writes origin once under `.ark/reports/`).
+- **Never** `--reset-origin` unless the user explicitly wants a new baseline.
+- **Do not** wait until the end of the loop to create origin the first time — later reports need a frozen “before” picture.
+- End of run: re-`--report` for **latest** + evolution vs origin (origin stays frozen).
 
 ## Operating modes (detected, not picked)
 
-- **Setup (Suggest):** no config → `ark start` / recommend shape.
+- **Setup (Suggest):** no config → `ark start` / recommend shape (start freezes origin after config, before gates).
 - **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.
+- **Guard (Enforce):** `goal.met`, solid governed%, no false-green → confirm gates; still emit dual plan B if explore found residual.
 
 ## Flow
 
-0. **Explore pass** — product map + false-green check + suggestive bets (see above).
+0. **Explore pass** — decision-grade recon (see above); seed plan B.
 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:
+2. **Origin if missing** — freeze day-zero (`--report`) immediately after contract exists.
+3. **Sensors** — `--plan --json`, doctor/coverage as needed.
+4. **Emit dual plan** — A from plan steps (files opened); B from explore (3–5 bets).
+5. **Concentrated edge?** — if one edge dominates A:
    **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** — 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
+6. **Worktree preferred** — discardable git worktree when possible.
+7. **Mechanical-safe (A only)** — kinds from `/ark-loop` table; one step, validate, rollback.
+8. **Judgment (A)** — default: propose with full “así te lo re-soluciono”. If user authorized full apply: implement, validate, rollback on fail.
+9. **Pattern bets (B)** — propose; apply only with explicit user go + correct skill (`/ark-contract`, refactor, install gates, etc.). Never weaken the gate to clear B.
+10. **Manifiesto** — loose business rules → Domain placement + `intentPrefixes` / intents via `/ark-contract` discipline.
+11. **Final report** — re-`--report`; evolution vs origin; A applied vs open; B proposed/deferred; gates on.
+12. **Strict check** — `ark-check --strict-config` (dead preset globs are advisory; real violations still fail).
+13. **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 or false-green gap is open.
 
 ## Never
 
 - Disable rules, broaden allows, or baseline **new** debt to “finish”.
-- Claim clean while judgment steps were skipped without user decision.
+- Claim clean while judgment A steps were skipped without user decision.
 - Claim ENFORCE / “done” when doctor reports `contract-false-green-io-under-application` (adopt first).
+- Claim “done” solely because plan A is empty while explore/B residual remains unlisted.
 - Replace host Nest/DI with the runtime kernel unasked.
-- Treat “plan empty” as “architecture is healthy” without the explore pass.
+- Auto-apply pattern (B) bets as if they were mechanical-safe.
+- Create origin only after a long cleanup (freezes a polished “before” that never was).
 
 ## 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, open **opportunities**, and report HTML paths.
+- Explore pass completed (decision-grade map + paths + field path or n/a + B seeds).
+- Dual plan emitted (A and/or B; if both empty, one-line justification).
+- Origin present under `.ark/reports/origin.*` (frozen this run or earlier).
+- Every applied A step validated by real `ark-check`.
+- Final plan `goal.met` true **or** remaining A steps listed with file-level proposals.
+- Open **B opportunities** listed; report HTML paths cited.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-coverage.md

@@ -56,7 +56,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 |------|----------------|--------------------|
 | **Suggest / Setup** | Thin or new tree | “Ark will propose a starting shape — you don’t switch a mode.” |
 | **Adapt / Align** | Contract ≠ folders or open debt | “Gates don’t fully protect you yet — classify + fix plan.” |
-| **Enforce / Guard** | Coverage + clean edges + honest cores | “You arrived here — keep CI/write gates on.” |
+| **Enforce / Guard** | Coverage + clean edges + honest cores | “You arrived here — keep the host-appropriate write path and CI check on.” |
 
 Never say “your architecture is guarded” while `goal.met` is false, governed% is low,
 or false-green doctor gaps are open.
@@ -73,7 +73,7 @@ or false-green doctor gaps are open.
 
 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.
+3. Host-appropriate write path + `/ark-*` skills per detected agent.
 4. CI workflow + monorepo install reality (`frontend/package.json`?).
 5. ESLint `arkgate/eslint` if ESLint exists.
 6. Domain `forbiddenGlobals`.

package/templates/skills/ark-explain.md

@@ -37,7 +37,8 @@ the same files or weaken the gate.
    (`pnpm … exec ark-check` / `yarn` / `npx`).
 
    This also maintains snapshots under **`.ark/reports/`**:
-   - `origin.json` / `origin.html` — frozen **first** report (start of the journey)
+   - `origin.json` / `origin.html` — frozen **day-zero** report (`ark start`/`ark init`
+     freezes this **right after** `ark.config.json`, before agent docs/CI templates)
    - `latest.json` / `latest.html` — every run
    - `history/*.json` — last ~20 machine-readable points for later tooling
 

package/templates/skills/ark-explore.md

@@ -1,13 +1,15 @@
 ---
 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.
+description: Decision-grade architecture recon — sensor + tree + field path + coupling evidence. Rank residual that changes action; optional dual-plan seed (not multi-week roadmaps). 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.
+Ark’s CLI is a **sensor** (coverage, doctor, plan). **You** open source, entry points,
+install hooks, examples/starters, and coupling evidence. Output is **decision-grade**:
+ranked residual that changes the next command — **not** a celebration of ENFORCE and
+**not** a paraphrase of README/ROADMAP.
 
 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.
@@ -17,17 +19,48 @@ Use alone when the user wants a map / options / “what should we do next?”.
 - **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`.
+- **Execute dual plan + apply:** `/ark-autopilot` (explore is recon / seed, not the loop).
 
 ## 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 |
+| **Exploratory** | Your judgment from **reading this tree**: product surface, field path, hotspots, false greens / false promises, design patterns lived | Only paraphrasing CLI JSON or docs |
 
-**Incomplete:** doctor/coverage dump with no file paths you opened.  
-**Complete:** map + ranked bets + “así te lo re-soluciono” with real paths.
+**Incomplete:** doctor/coverage dump with no file paths you opened; or a long map that
+only restates README; or a multi-week roadmap when the user only asked for a map.  
+**Complete:** dry headline + field evidence + ranked bets with **así te lo re-soluciono**
+(real paths, concrete next step, **success signal**) + honest handoff when residual is
+*not* layer debt.
 
+**ENFORCE / 100% governed / empty plan is baseline, not a finding.** Lead with residual
+that still matters (dogfood gaps, soft starters, identity drift, **semantic false-green**,
+coupling that blocks evolution). If residual is truly none, say so in one line and hand
+off `stop`.
+
+## Output mode (pick one — do not invent a third)
+
+| Mode | When | Deliverable |
+|------|------|-------------|
+| **Recon (default)** | map / residual / “what next?” / bare `/ark-explore` | Headline → map → ranked table → **Top 3** → residue → Completion |
+| **Dual-plan seed** | user asks for a **plan**, mejora, roadmap, o “Ark + patrón de diseño” | Same recon **plus** a short **§ Dual-plan seed** (below). **Cap 3–5 B bets.** |
+
+**Forbidden in either mode:**
+- A 6-phase / multi-week implementation roadmap as the default explore product.
+- Phases with week estimates, long PR stacks, or vanity “Domain ≥ N files” as done criteria.
+- Auto-applying anything (explore does not edit the contract or product code unless the user
+  separately asks to execute a bet).
+
+**Dual-plan seed shape (mode 2 only):**
+
+| Section | Content |
+|---------|---------|
+| **A. Remediation** | From `--plan` — usually empty when ENFORCE; one line if so |
+| **B. Pattern / evolution** | **3–5** bets max from the ranked table; each: evidence · así te lo re-soluciono · **success signal** · next skill · **kill-switch** if proposing a new layer/big move |
+
+Long multi-PR execution plans belong to **`/ark-autopilot`** (or a human-owned doc after
+the seed), not to explore by default.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -46,63 +79,131 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 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.
 
+Useful split when present: **core product tree** vs **field path** (`examples/`,
+`templates/`, gallery starters, eval fixtures) vs **agent install surfaces** (hooks,
+MCP, CI templates).
+
 ## Anti-wrapper rule
 
-**Forbidden:** only `ark-check --json` / `--coverage` / `--doctor` paraphrase.
+**Forbidden:**
+- Only `ark-check --json` / `--coverage` / `--doctor` paraphrase.
+- Echoing README / ROADMAP / marketing as if it were recon.
+- Padding the ranked table with “architecture is clean” rows when the sensor already said that.
+- Ranking debt by **LOC alone** without fan-in, exports, or call-site evidence.
+- **Vanity success metrics** as bet done criteria (e.g. “Domain ≥ 20 files”, “add a layer
+  because the diagram is prettier”) without multi-surface proof or a kill-switch.
+- Multi-week roadmaps when mode is recon-only.
 
 **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.
+2. **Product + code pass** — min **12 source files** across **≥4 directories** that matter for *this* product (apps, packages, features, domain, adapters, API routes, CLIs).
+3. **Field path** when scaffolds exist (see §E); for pure apps, **internal field path** (see §E).
+4. **Coupling evidence** beyond “large file” (see §C).
+5. **Path-correct vs design-correct** pass (see §B).
+6. Ranked rows that **change a decision**; each bet has a **success signal** (not a file count).
+7. Hard lines: never weaken the contract; never invent mechanical-safe kinds; never claim ENFORCE from type-only cleanup while false-green doctor ids are active.
 
 ## 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.
+- README / package.json `description` / scripts / monorepo workspace roots — **skim for entry points**, do not restate the pitch.
+- User-facing entry: Next/Nest/Express routes, CLIs, workers, public APIs, package exports.
 - Deploy shape if obvious (apps/, packages/, services/).
-- One paragraph: **“What does this product do for a real user?”**
+- One dry line: **what a real user/agent gets** (not the slogan).
 
-### B. Architecture as lived (not only as configured)
+### B. Architecture as lived — path-correct vs design-correct
 - 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`).
+- Classic false-green: empty Domain / Persistence while Application owns `airtable|supabase|prisma|repositories` → doctor id `contract-false-green-io-under-application`.
+- **Semantic false-green** (edges green, names lie) — flag when you see it:
+  - HTTP handlers / route bodies living under `repositories/` or Persistence globs.
+  - Presentation/routes defaulting to a data facade (`platform/*`, raw db) while “repos exist”.
+  - Domain layer thin while pure business rules sit in Application with no I/O (should be Domain).
+  - Layer labels that match globs but not role (gate path-correct, design wrong).
 - 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).
+- **Identity risk:** which layer owns the product *wedge* vs file-count / public barrel.
+- **Concurrent design patterns** (short table when ≥2 styles coexist): name each pattern,
+  one example path, quality (`canonical` / `gate-green design-weak` / `legacy`). Mark the
+  **golden** pattern to copy. Do not only list layer file counts.
+
+### C. Coupling & debt (measure, don’t guess)
+Prefer evidence over aesthetics:
+- **Fan-in / importers** of hot modules (who imports the suspect file?).
+- **Export surface** (how many public symbols does the orchestration module re-export?).
+- Import cycles, 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.
+- Dead or aspirational globs; layers with files but no rules; **starter/preset rules weaker than sibling archetypes** (soft green).
+- LOC is a **hint** only — pair it with fan-in or export count before calling something a god module.
 
-### D. Agent / gate reality
+### D. Agent / gate reality (installed vs generated)
 - Write gate + CI + `/ark-*` skills present? Stale skills? Global vs pinned `arkgate`?
+- **Installed hooks vs install templates:** compare project PreToolUse / write-hook commands to what `--install-agent-gates` would emit (e.g. reject-only `--hook` vs `--hook-repair`). Doctor `writePath` / adoption gaps are leads — **verify on disk**.
+- MCP config present and pointing at a real binary? `prepare-write` / autoPatch surface vs hook mode.
 - Baseline: real debt or hiding contract smell?
-
-### E. Suggestive bets (not commits yet)
+- CI: is architecture check required on the default branch path this repo actually uses?
+- **Origin:** is `.ark/reports/origin.json` present? (Day-zero picture; missing → note as agent-dx / adopt gap, not a layer violation.)
+
+### E. Field path (consumer promise or internal)
+When `examples/`, `templates/`, gallery starters, eval fixtures, or docs claim “copy this and stay green”:
+1. Open **≥2** scaffolds (prefer one minimal gallery + one “deep” / runnable demo).
+2. **Run** their documented check script when cheap (`npm run check`, `ark-check --strict-config`); record pass/fail — do not trust README alone.
+3. Diff **rule strength** across archetypes (missing denies = soft false-green for consumers).
+4. Note import style vs package surface docs (`arkgate` root barrel vs preferred subpath).
+5. Flag **false promises**: demo fails under its own check, or green with a hollow contract.
+
+If the repo is a **pure app** (no examples): state **Field path: internal** and do one of:
+- Name the **norm for new code** that the residual implies (e.g. “no new `platform/db` in routes”), or
+- Point at one **smoke** the team could add (lint/CI allowlist, PR checklist) — do not invent a full CI system.
+
+### F. Suggestive bets (not commits yet)
 For each opportunity: **impact × effort × enforceability** (can the gate hold it after?).
 
-## Output format
+**Success signal (required per bet)** — observable, not vanity:
+- Good: `doctor.writePath = repair`; `ark-check` green after promote; API + UI import same pure `computeX`; 0 new routes with facade SQL; pilot cluster migrated + kill-switch decision recorded.
+- Bad: “Domain has ≥ N files”; “add layer X”; “more documentation”.
+
+**Kill-switch (required if the bet adds a layer, peerIsolation wall, or big-bang move):**
+- Name a **pilot** (one cluster) and a **stop condition** (e.g. “if pilot does not reduce confusion in 2 real PRs → prefer handlers-under-domain without a new layer”).
+- Prefer **forward-only + migrate-on-touch** over big-bang.
+
+Prefer bets the user can run next (`command` / skill), not vague “improve DX”.
+
+## Output format (keep tight)
 
-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**
+State **Mode: recon | dual-plan seed** in the headline or first line.
 
-| # | Kind | Finding | Evidence (path) | Suggestion | Next skill / command |
+1. **Headline** — product in one sentence + honesty line (mode, governed%, false-green / semantic false-green / false-promise risk). ENFORCE is context, not the story.
+2. **Map** — one short table or bullet map: entry points, major dirs, shape name (or “no honest shape yet”). One screen max. Include **patterns concurrent** table when relevant (§B).
+3. **What I opened** — paths + sensors that prove the pass (include field/hook/origin paths when used).
+4. **Ranked table** — **only rows that change a decision**. Prefer **3–6** hard rows; drop filler.
+
+| # | Kind | Finding | Evidence (path) | Así te lo re-soluciono | Success signal | 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.
+**Así te lo re-soluciono** must be concrete: files to touch, command to run.  
+**Success signal** must be falsifiable (see §F). If proposing a new layer / wall: add kill-switch in the así-te-lo cell or a footnote.
+
+5. **Field path summary** (scaffolds and/or internal norm).
+6. **Top 3 bets** — if the user says “go”, ordered execution. First bet = highest leverage residual, even when plan is empty (agent-dx / field honesty / design-correct — not “run loop on zero steps”).
    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.
+7. **Dual-plan seed** — **only in mode 2**; A + B with cap 3–5 B rows; no multi-week phase chart.
+8. **Deterministic residue** — compact: plan steps, violations, doctor top action. Point to
+   `/ark-loop` / `/ark-fix` **only when steps exist**; never pretend loop is the architecture story when goal is already met.
+
+Optional when useful: **Diff vs naive sensor-only read** (one short list: what reading the tree changed).
 
 ## 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.
+- ≥12 source files read and cited across ≥4 directories.
+- Field path: scaffolds run/opened **or** pure-app internal norm stated.
+- At least **3 decision-grade** rows (not “fix violation X” and not “layers are clean”).
+- Coupling claims backed by fan-in / exports / importers (or clearly marked as LOC-only hint).
+- Path vs design called out when concurrent patterns or semantic false-green exist.
+- Every Top-3 / B bet has a **success signal**; new-layer bets have a **kill-switch**.
+- Mode respected: no multi-week roadmap in recon mode; dual-plan seed capped at 3–5 B bets.
+- Clear handoff: `/ark-adopt` | `/ark-contract` | `/ark-autopilot` | `/ark-loop` | `/ark-fix` | CLI command | `stop`.
+- No gate weakening; no false ENFORCE claim; no README echo as primary content.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-runtime.md

@@ -1,11 +1,14 @@
 ---
 name: ark-runtime
-description: Replace hand-rolled infra with the Ark runtime kernel — event bus, outbox, audit, sagas, projections, policies, NestJS. Finds candidates, wires one, verifies.
+description: Evaluate the experimental Ark runtime kernel against hand-rolled event bus, outbox, audit, saga, projection, policy, or NestJS code. Finds one candidate, wires one, verifies.
 ---
 
-# /ark-runtime — Adopt the runtime kernel (opt-in features)
+# /ark-runtime — Evaluate the runtime kernel (experimental opt-in)
 
-`arkgate` is not just static checking: it ships a runtime kernel
+The runtime kernel is currently **experimental** and is not required for ArkGate enforcement or
+presented as production-ready. Use this skill only when the user explicitly wants to evaluate it.
+
+`arkgate` ships the experimental runtime kernel
 (`createArkKernel`) with an event bus, event contracts, outbox, audit trail,
 policy engine, workflow/saga coordination, projections, observability hooks,
 and NestJS adapters. This skill migrates hand-rolled versions of those to the
@@ -43,12 +46,12 @@ the same files or weaken the gate.
 2. **Pick ONE target** — the smallest, most self-contained candidate (fewest
    call sites). Migrating everything at once is how adoptions die. List the
    rest as follow-ups in the report.
-3. **Migrate** — import from `arkgate` (root export) or
+3. **Migrate** — import from `arkgate/runtime` (preferred experimental subpath) or
    `arkgate/nestjs`, and read the package's `docs/agent-guide.md`
    (in `node_modules/arkgate/docs/`) for the runtime API before
    writing code. Wire the kernel at the composition root; keep the domain
    ignorant of it (handlers/ports, not kernel imports inside domain code —
-   the write gate will enforce this anyway). Note: the kernel bounds in-memory
+   the architecture check enforces this; Claude/Grok hooks can block it earlier). Note: the kernel bounds in-memory
    history by default (`maxHistorySize` 1000); mention this if the hand-rolled
    version retained everything.
 4. **Delete the hand-rolled version** once call sites are moved — the point is