arkgate 4.2.0 → 4.3.0

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ark-adopt
+description: Brownfield onboarding — match contract to real product code, classify ungoverned dirs, mine business rules, freeze only real debt, seed Shape dual-plan B for spaghetti residual. Deep source analysis required.
+---
+
+# /ark-adopt — Bring Ark into an existing codebase
+
+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**.
+
+**Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
+spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+when design smells remain after the contract is honest.
+
+## When / not when
+
+| Use `/ark-adopt` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| Existing messy repo; contract ≠ folders | Empty greenfield shape → `/ark-architect` |
+| False-green / concentrated edge needs contract truth | Map-only without writing config/baseline → `/ark-explore` |
+| Mine loose business rules into Domain / intents | Single violation fix → `/ark-fix` |
+| Freeze **real** debt after contract is honest | Grind plan A only → `/ark-loop`; full apply loop → `/ark-autopilot` |
+
+## 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 |
+
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| Plane | What it protects | Where it lives | Sensors / tools |
+|-------|------------------|----------------|-----------------|
+| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
+| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column table with those headers).
+2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
+3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
+4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Adopt + ArkRules
+- After classify: emit or refresh `arkRules` for matched layers (exact names; generic mold for unknowns).
+- Mine rules → inventory + propose invariants/structure; land via `/ark-contract`.
+- Freeze baseline is **[Layer]** debt; inventory residual is **[ArkRules]** — report both.
+
+## 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)
+
+**Forbidden:** only running `--init` / `--update-baseline` / coverage JSON without reading the tree.
+
+**Required:**
+1. CLI sensor: `--coverage --json`, check `--json` (`summary`), doctor.
+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
+
+Ark protects the **boundary around** a framework, not its internals. Nest/DI public surface = one layer; internals black box.
+
+## Steps
+
+1. **Config** — missing → `ark-check --init` (detection). Keep existing unless asked to regenerate.
+   If the tree is `src/features` + `shared`/`lib` **without** FSD `entities`/`widgets`, prefer
+   `vertical-slice` (or pack `enthusiast-vertical-slice`) — do **not** force hexagonal.
+   If `src/contexts` or `src/bounded-contexts` exists, prefer `ddd-bounded-contexts`.
+   **Next.js:** `app/api/**` / `pages/api/**` (and route-group `app/(…)/api/**`) default to
+   **ApplicationOrchestration**, not Presentation — do not reclassify API shells as UI.
+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.
+   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.
+   - **ArkRules inventory (AR13):** run `ark-check --rules-inventory --json` for deterministic candidates
+     (validation-in-controller, magic constants, anemic entities). Counts are **not a score**.
+   - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
+     land structure/invariant entries under `arkrules/<Layer>.json` via `/ark-contract` (ADR 0015 routing).
+   - Apply config through `/ark-contract` discipline; move pure rules into Domain when safe; validate with ark-check.
+   - 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 + Shape seed (mandatory exploratory close)** — after freeze/gates:
+   - Name phase: **Align** (contract honesty) → **Stabilize** (baseline real) → **Shape** (golden pattern).
+   - If plan A is empty but the tree still shows concurrent patterns, god modules, facade SQL,
+     domain logic in UI, or semantic false-green: emit **dual-plan B** (3–5 bets) with pilot,
+     success signal, kill-switch, and extraction cards for I/O moves — same bar as `/ark-explore` §G.
+   - Do **not** claim “adopt complete / healthy” solely because the check is green.
+   - Prefer handoff `/ark-autopilot` for B execution with user ok, or `/ark-explore` shape-focus
+     if the user only wanted a plan.
+
+## Operating modes
+
+Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
+**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
+
+## 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, **phase**, **top Shape / design-weak opportunities still open**
+(with success signals).
+
+## Never
+
+- Freeze false positives to get green.
+- Force runtime kernel over existing Nest/DI.
+- Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
+- End adopt with only “baseline written” when design-weak residual is visible in files you opened.
+
+## 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
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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/agent-skills/ark-architect/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ark-architect
+description: Choose the application shape, adopt phase-1 layers, scaffold directories, and verify honestly — for enthusiasts before codegen. Autonomous.
+---
+
+# /ark-architect — Choose your application shape and adopt Ark
+
+## When / not when
+
+| Use `/ark-architect` when… | Do **not** use it when… |
+|----------------------------|-------------------------|
+| Greenfield / thin tree; pick shape + phase-1 layers | Existing spaghetti brownfield → `/ark-adopt` (+ `/ark-explore` first if map missing) |
+| Enthusiast before heavy codegen | Enforcement residual on mature tree → `/ark-autopilot` |
+
+The user is building something new or early in Ark adoption. They may not know
+layered architecture jargon. Your job: translate **what they want to build**
+(application shape, not framework name) into an Ark preset, a phase-1 layer plan,
+conventional directories, and a passing honest check — without weakening the gate.
+
+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**.
+
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| Plane | What it protects | Where it lives | Sensors / tools |
+|-------|------------------|----------------|-----------------|
+| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
+| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column table with those headers).
+2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
+3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
+4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Architect + ArkRules
+- Preset/init should emit lean `arkRules` + templates for phase-1 layers (exact names).
+- Explain to the user: layers = boundaries; arkrules = habits inside Domain/App/adapters (opt-in, start advisory).
+
+## 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 |
+|-------|------|
+| **/ark-architect** | **Before** — greenfield or fresh config; pick shape + phase 1 |
+| /ark-adopt | **After** — messy existing repo |
+| /ark-contract | **During** — evolve config safely |
+| /ark-place | **During** — one new file |
+| /ark-explain | **After** — understand what exists |
+
+## Steps
+
+1. **Bind and detect the shape** — complete the mandatory `ark_identity` preflight first, then
+   call MCP tool **`ark_recommend`** with the bound `project` envelope (or run the workspace-local
+   `ark-check --recommend --json`). Never use an unverified recommendation. Read `archetype`, `preset`, `confidence`,
+   `adoptInOrder.phase1`, `analogy`, `why`, `evidence`, and `requiresConfirmation`.
+   Ask at most **two** questions only if `requiresConfirmation` is true (or for compatibility
+   with older ArkGate output, `confidence < 0.5`):
+   - "Will this app save data between sessions?"
+   - "Is this one app or several in one repository?"
+
+2. **Present in plain English** — name the application shape (e.g. "product with
+   UI and stored data"), not the framework. One analogy. List **phase-1 layers only**.
+
+3. **Map to Ark** — if `ark.config.json` is missing, run
+   `ark init --archetype <archetype> --yes` (maps playbook id → preset + gates),
+   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. 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
+   what belongs there. Match the nearest sibling file style if code already exists.
+   Flat layouts (`src/` + `lib/` + `api/` at the repo root) are common in Vite and
+   serverless projects — use `/ark-contract` to map them to layers instead of forcing
+   everything under `src/**/domain/**` only.
+
+5. **Install gates** when the user uses AI coding tools and gates are missing:
+   `ark-check --install-agent-gates`.
+
+6. **Verify honestly** — run `ark-check --doctor` and `ark-check --coverage --json`.
+   Report `governed.percent`. Say explicitly what is **not** governed yet
+   (ungoverned directories, empty layers).
+
+7. **Deliver to the user**
+   - ASCII diagram (≤3 boxes for phase 1, inner → outer)
+   - Table: "when you build X, put it in Y"
+   - Three rules the agent must not break (no domain→database imports, no raw
+     `publish()`, no weakening `ark.config.json` to pass)
+   - Optional book refs from `books` in the recommendation JSON under "go deeper"
+   - **Gallery starter** — point the user at the matching clonable example:
+
+     | Archetype | Example directory |
+     |-----------|-------------------|
+     | `crud-product` | `examples/crud-product-starter/` |
+     | `api-backend` | `examples/api-backend-starter/` |
+     | `worker-pipeline` | `examples/worker-pipeline-starter/` |
+     | `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
+     | `vertical-slice-product` | `examples/vertical-slice-starter/` |
+     | `ddd-bounded-contexts` | `examples/ddd-context-starter/` |
+
+     Say they can copy that folder as a baseline (`npm install && npm run check`).
+     For a runnable API with break exercises, mention `examples/hexagonal-order-api/`.
+     Full enthusiast track: `docs/enthusiast/README.md`.
+
+## Operating rules
+
+- Never weaken `ark.config.json`, the baseline, CI, or agent settings to pass.
+- Never invent layers outside the 11-layer profile or named presets
+  (`hexagonal`, `layered`, `feature-sliced`, `monorepo`, `ui-surface`,
+  `vertical-slice`, `ddd-bounded-contexts`).
+- Flag unrecognized dirs (`utils/`, `lib/`) — user must classify via `/ark-contract`.
+- Default to smallest viable phase 1; unlock phase 2 only when the user describes need.
+- All user-facing copy is **English**.
+
+## Merge cards (X04 reshape — judgment only)
+
+When `doctor.physicalCohesion` reports a mirrored concept and the user asks whether files
+should be **merged**, treat it as domain modeling, never deduplication (field fact: zero
+structural clones among 123 same-concept files). Produce a **merge card** per candidate group:
+which files, the domain concept they express, 2–3 shapes the merged module could take, and what
+each shape costs — **no default action, no auto-merge, never a codemod**. Physical **moves**
+belong to `/ark-loop`'s pilot loop; your job here is the judgment about what the concept IS.
+
+## Verify and report
+
+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.
+
+## 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
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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/agent-skills/ark-autopilot/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: ark-autopilot
+description: Guided end-to-end path for layers and opt-in ArkRules — doctor next action when unsure. Explore first; dual plan A (edges) + B (shape); mechanical-safe only by default; B with user OK, one pilot at a time. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
+---
+
+# /ark-autopilot — Guided end-to-end architecture path
+
+**This is the full guided co-pilot** after the compact router. Prefer it when the user wants
+architecture cleaned end-to-end, not when they only need a map (`/ark-explore`) or a single
+edge fix (`/ark-fix`). Doctor remains the control plane: re-check status after each major step.
+
+Composes **explore → sensors → dual plan → loop**. Safe default: auto-apply only
+`mechanical-safe`; when the user says full apply / 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 / Shape bets).
+
+## When / not when
+
+| Use `/ark-autopilot` when… | Do **not** use it when… |
+|----------------------------|-------------------------|
+| “Make architecture sound” end-to-end | Map only, no apply → `/ark-explore` |
+| Brownfield or greenfield with apply | Only fitness numbers → `/ark-coverage` |
+| User wants A + B planned and A executed | Single edge fix → `/ark-fix`; plan A only → `/ark-loop` |
+| **Apply half of Q01 post-green path** (after explore map / when user wants full apply) | Skipping explore when doctor primary is Shape map-first |
+| Spaghetti under ENFORCE: Shape work with user ok on B | Contract false-green first → `/ark-adopt` / `/ark-contract` STOP paths |
+
+**Q01:** doctor’s single door is `/ark-explore` shape-focus → dual-plan B, **then** this skill only
+to apply B with OK. Prefer that order when `postGreenPath` / design-weak is the primary residual.
+
+## 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` — full recon / dual-plan seed without applying.
+- **Adoption fitness only:** `/ark-coverage` — governed% + capability gaps (not pattern dual-plan).
+- **Default path:** `ark start` → `ark-check --doctor` → **`/ark-autopilot`** (this skill) for guided work.
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **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 a
+decision-grade explore pass **and** without opening violating files.
+
+**Required:**
+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.
+7. **Q04 pilot loop for B:** when design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
+   → apply **only** that pilot with user OK → **re-doctor**. Never multi-pilot batch B; residual
+   outside the pilot may remain and must not be called “healthy finished.”
+8. **Y01 reshape verdicts:** read `doctor.physicalCohesion.reshapeDecisions` before acting on
+   mirror facts. Outcome first: a current rejected/deferred verdict means “intentional/deferred
+   layout — no pilot”; never reconstruct that dead card from `findings`. When the user accepts,
+   defers, or rejects a live card, persist its exact `decisionTarget` with a non-empty reason and
+   optional `reviewBy` in `.ark/reshape-decisions.json`; never infer a verdict from golden prose.
+
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| Plane | What it protects | Where it lives | Sensors / tools |
+|-------|------------------|----------------|-----------------|
+| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
+| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column table with those headers).
+2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
+3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
+4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Autopilot + ArkRules
+- After explore/doctor: if inventory has high-confidence candidates **or** user wants domain rules, include **[ArkRules] plan A/B**:
+  - A: mechanical-safe remains inter-layer only; structure/invariant fixes are **judgment**.
+  - B: one pilot = one rule (declare in `arkrules/<Layer>.json` → implement → test title/symbol → re-doctor).
+- Never promote advisory→enforced without coverage evidence (`canPromoteInvariant` / policy-delta).
+- End report must list what was **layer-edge** work vs **intra-layer rule** work.
+
+## 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.
+
+Useful first wave: **core product tree** | **field path** (examples/starters) | **agent install surfaces** (hooks vs templates).
+
+## Explore pass (phase 0 — mandatory, first)
+
+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).
+Include explore **§G** when spaghetti / design-weak signals fire.
+
+1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
+   **ENFORCE·design-weak** risk).
+2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
+3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
+4. **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` + internal norm.
+5. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
+6. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
+7. **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`.
+8. **Seed dual plan B** — 2–5 pattern / Shape bets ranked (impact × effort × enforceability). Each B row needs pilot + success signal; I/O bets need an **extraction card** (explore §G).
+
+Min bar: **≥12 source files** across **≥4 meaningful directories** (not only files in `steps[]`).  
+Standalone long report: `/ark-explore`. Adoption fitness only: `/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 / Shape** | Explore §B/§G (not coverage alone) | What **design** must improve even if A is empty? | **Never** as mechanical-safe |
+
+**Section A** — group by edge; treat `peerIsolation` / cross-slice as **judgment**.  
+**Section B** examples: choose golden pattern + pilot migrate-on-touch, peerIsolation, move rules out of UI, write-path repair, split god modules, Domain placement / intents, facade SQL → port/adapter (extraction card). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + **success signal** + **pilot** (+ kill-switch if new layer).
+
+B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.  
+When A is empty and B is non-empty: status is **`goal.met on edges · Shape residual open`** — never “done” without listing B.
+Prefer CLI `patternBets[]` / `designSmells[]` when present; apply B only with explicit user ok using
+**extraction cards** (`docs/brownfield-adoption.md` §6) — never mechanical-safe, never silent.
+If B will take multiple PRs, offer (do not require) persisting a short Shape plan under the
+repo so the next agent session continues the same pilot — still never auto-apply B.
+
+## Origin snapshot (day-zero picture)
+
+- **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)
+
+Status lights from doctor — not settings you choose. Rank residual honestly:
+
+| Light | Means | Your move (this skill) |
+|-------|--------|------------------------|
+| **Suggest** | Thin/new tree; contract not control plane | Finish `ark start` → re-doctor; do not skill-shop |
+| **Adapt** | Contract/tree disagree or debt open | Explore + adopt/loop/contract; do not claim guarded |
+| **Enforce** | Honest coverage + clean checked **edges** | Confirm gates + CI; emit dual-plan B only if residual found |
+| **Enforce · design-weak** | Edges clean; design smells remain | **Primary Shape door:** explore shape-focus → dual-plan **B** → apply **one** pilot with user OK. Empty plan A ≠ done. Never mechanical-safe B. False-done forbidden. |
+
+- **Setup (Suggest):** no config → `ark start` (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 → confirm gates; still emit dual plan B if explore found residual.
+- **Guard · design-weak:** same as Enforce on edges, **plus** mandatory dual-plan B / pilot card; Incomplete? must not claim healthy finished while residual remains.
+
+## Flow
+
+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 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).
+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.
+
+## Mechanical-edit hygiene (Y04 — outcome gate)
+
+- Header injection must **merge into the existing doc comment**; the kept result has one `/**`, not stacked headers.
+- Route completion or movement must **preserve the original typed `defineRoute<…>(opts, handler)` call**; reconstruct that call instead of extracting untyped opts/handler constants that drop generics or contextual typing.
+- A convention-only `*-data.ts` stub is not a fix: move the real code or **leave the placeholder file uncreated**; never write `import "server-only"; export {}` as an empty naming token.
+- Keep the edit only when the **previously clean file stays typecheck-clean**. Otherwise roll it back and treat the change as judgment.
+
+## Never
+
+- Disable rules, broaden allows, or baseline **new** debt to “finish”.
+- 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.
+- 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 (decision-grade map + paths + field path or n/a + phase + B seeds).
+- Dual plan emitted (A and/or B; if both empty, one-line justification with evidence no design-weak smells).
+- 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 / Shape opportunities** listed with success signals; report HTML paths cited when used.
+- If A empty and design-weak present: B listed — **Incomplete?** must not claim full healthy stop.
+
+## 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
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **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.