arkgate 4.2.1 → 4.4.0

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

@@ -0,0 +1,195 @@
+---
+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
+
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Greenfield that is AI-easy day one:** golden norm + thin layers so the next agent turn stays ordered.
+
+## 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 (physical cohesion 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)
+- **Compass:** top residual lenses | `n/a`
+- **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,262 @@
+---
+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).
+
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Guided vibe path:** phase 0 = doctor + compass residual. Shape only with user OK. Never script “done” while residual lenses remain.
+
+## 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 post-green Shape 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 |
+
+**Post-green door:** 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. **One-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. **Reshape decision memory:** 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 (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)
+- **Compass:** top residual lenses | `n/a`
+- **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-contract/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: ark-contract
+description: Safely edit ark.config.json layers/rules and arkrules/* (structure + invariants); land business rules under the dual plane. Validated with strict ark-check. Deep source evidence required.
+---
+
+# /ark-contract — Change the architecture contract (safely)
+
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Contract edits are last resort.** Policy-delta honesty; do not weaken rules to clear compass residual.
+
+## When / not when
+
+| Use `/ark-contract` when… | Do **not** use it when… |
+|---------------------------|-------------------------|
+| Edit layers/rules/includes/intents with source evidence | Move product code without config change → `/ark-fix` / `/ark-loop` |
+| Concentrated-edge / false-green STOP from other skills | Full map without config edit → `/ark-explore` |
+
+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 the project-bound `ark_manifest` tool exposes authoritatively).
+
+
+## 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`.
+
+
+### Contract + ArkRules
+- You own **both** `layers/rules` and `arkRules`/`arkrules/*.json`.
+- Report diffs in two blocks: **[Layer] config** and **[ArkRules] files**.
+- Promotion ladder: advisory→enforced only with coverage; demote = hash-ack weakening.
+
+## 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`.
+- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+
+## Anti-wrapper rule (mandatory)
+
+**Forbidden:** editing globs from vibes without reading the directories those globs claim to cover.
+
+**Required:**
+1. Snapshot before using CLI as **sensor**: coverage + check JSON.
+2. **Read source** in dirs you reclassify (sample files).
+3. **“Así te lo re-soluciono”** — exact JSON fields + which files become governed/ungoverned.
+4. After write: `ark-check --strict-config` must be the validation gate (dead pattern noise is advisory; unclassified + real violations still matter).
+
+## What you may edit
+
+- `include` / `exclude`
+- `layers[]` (`name`, `patterns`, `optional`, `forbiddenGlobals`, `intentPrefixes`, layer `exclude`)
+- `rules[]` (from/to/allowed)
+- **`arkRules` map + `arkrules/<Layer>.json`** (ADR 0012/0014) — structure sensors + invariant catalog;
+  promote advisory→enforced only with coverage evidence; demote/delete requires hash-bound policy ack
+- Never: disable the check, delete CI gates, or add blanket `allowed: true` for a bad edge without a facade design
+
+## Steps
+
+1. **Snapshot** — coverage governed%, unclassified samples, current violations.
+2. **Smallest edit** for the user intent:
+   - New layer + neighbor rules
+   - Expand patterns for ungoverned dirs (`suggestions` from coverage)
+   - Facade: public surface patterns more specific than internals
+   - **Business rules → manifiesto:**
+     - Add/adjust `intentPrefixes` (`Domain.`, `Application.`, …)
+     - Point Domain patterns at real pure folders (`**/domain/**`, not bare `**/types.ts`)
+     - Document proposed intent names for the app to register (kernel) or for agents to use
+3. **Impact** — re-run coverage/check; report before/after governed% and violation delta.
+4. **Rollback** if strict fails for reasons other than pre-existing debt the user accepted.
+
+## Operating modes
+
+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
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
+- **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.