arkgate 4.2.0 → 4.3.0

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

@@ -0,0 +1,136 @@
+---
+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)
+
+## 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)
+- **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-coverage/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: ark-coverage
+description: Ark adoption fitness audit — governed%, gates, baseline honesty, capability gaps. CLI is a sensor; read enough source to prove gaps. Full product recon and pattern dual-plan belong to /ark-explore.
+---
+
+# /ark-coverage — Ark adoption fitness (not full recon)
+
+You audit **how this repo uses ArkGate** (coverage, gates, baseline, host write path) and
+what adoption gaps remain. Work autonomously. End with a ranked fitness report.
+
+**This is not `/ark-explore`.** You do **not** produce a multi-pattern dual-plan or spaghetti
+Shape ladder by default. If the tree is design-weak under ENFORCE, **handoff** to explore.
+
+## When / not when
+
+| Use `/ark-coverage` when… | Do **not** use it when… |
+|---------------------------|-------------------------|
+| “How adopted is Ark?” governed%, gates, baseline, skills stale | Full product map / what-next architecture → `/ark-explore` |
+| Capability gaps (CI, write path, ESLint, optional layers) | Apply fixes end-to-end → `/ark-autopilot` |
+| Ranked *adoption* opportunities (install, ratchet, contract classify) | Spaghetti pattern plan / golden pattern → `/ark-explore` dual-plan seed |
+| Quick honesty before a release checklist | One design trade-off → `/ark-think` |
+
+## Dual engine (mandatory)
+
+| Engine | Deliverable |
+|--------|-------------|
+| **Deterministic** | governed%, layers, gates, baseline, doctor gaps, summary edges |
+| **Exploratory** | Enough source to prove ungoverned clusters / false-green are real (not JSON-only) |
+
+**Forbidden:** only `ark-check --coverage/--doctor/--json` paraphrase with no source evidence.
+
+**Required before you finish:**
+1. CLI sensor: `--coverage --json`, `--doctor`, normal `--json` for `summary`.
+2. **Product surface** — name the app/package(s) in one line (not a full recon).
+3. **Read real source** in the top ungoverned / high-risk clusters (minimum **10 files**
+   across at least **4 directories**). Prefer domain, features, adapters, routes — not only config.
+4. **“Así te lo re-soluciono”** for adoption gaps (globs, install, baseline, intents).
+5. If plan A is empty but you see design-weak / concurrent patterns / god modules:
+   list them briefly and **STOP — do not continue this skill as complete** for pattern work —
+   **handoff `/ark-explore` (dual-plan seed or shape-focus)**. Do not invent a second explore report here.
+
+If you did not open source files, the skill is **not complete**.  
+Full recon + pattern planning: `/ark-explore`.
+
+
+## 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`.
+
+
+### Coverage + ArkRules
+- Fitness report: governed% / gates / baseline = **[Layer]**; `rulesUnderContract` inventoried/under-contract/frozen = **[ArkRules]** (counts, never a score).
+- Capability gap: “no arkRules map” is optional adoption opportunity, not a failed gate.
+
+## 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.
+
+## Operating modes (detected — not user-picked)
+
+| Mode | User meaning | What you tell them |
+|------|----------------|--------------------|
+| **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 for *contract* fitness — design may still be weak; use explore for Shape.” |
+
+Never say “your architecture is guarded” while `goal.met` is false, governed% is low,
+or false-green doctor gaps are open. Never say “architecture is healthy finished” solely
+because governed% is 100% and plan is empty.
+
+**Honesty hard lines (doctor JSON):**
+- `coverageHonesty.worseThanNoGate` / weak coverage (~&lt;50%): green is **worse than no gate**.
+- `baseline.honesty.dirtyBaselineRisk`: green-via-freeze may hide false-positive debt.
+- `writePath.honesty.softWriteHost` (Cursor / Codex / OpenCode): write path is **advisory /
+  best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
+- Do not invent hard write guarantees for soft hosts.
+
+## Related onboarding
+
+- **Greenfield:** low governed% → `/ark-architect` or `ark-check --recommend`.
+- **Brownfield:** `/ark-adopt` for action; this skill for fitness metrics.
+- **Pattern / spaghetti residual:** `/ark-explore` dual-plan seed / shape-focus.
+- **Business rules loose:** note in table; mining action → `/ark-adopt` or `/ark-contract`.
+
+## Checklist (sensor + light code)
+
+1. Config + `ark-check --strict-config`.
+2. Baseline policy (orphan empty file? wire or delete).
+3. Host-appropriate write path + `/ark-*` skills per detected agent.
+4. CI workflow + monorepo install reality.
+5. ESLint `arkgate/eslint` if ESLint exists.
+6. Domain `forbiddenGlobals`.
+7. **Governed%** + unclassified + `suggestions` from `--coverage --json`.
+8. Concentrated edges in check `summary` → contract smell, not N freezes.
+9. `layersWithoutRules` + empty cores with I/O under Application (false-green).
+    On 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`.
+    On one-edge wall: **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).
+10. Runtime kernel / Nest only if deps prove it — never force-fit.
+
+## Output format
+
+1. **Headline honesty** — product one-liner, governed%, mode, violations, false-green risk, **design-weak handoff?** (yes/no).
+2. **Adoption map** — clusters you read for *fitness* (paths) — keep short.
+3. **Ranked table** (adoption residual + install/capability opportunities)
+
+| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) | Next |
+
+Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity` | `design-weak`
+
+4. If any `design-weak` rows: **Handoff required** → `/ark-explore` (do not expand into full dual-plan here).
+5. Offer: “Apply top adoption N?” / “Run /ark-adopt?” / “Run /ark-explore for Shape?” — apply only if user agrees.
+
+## Done criteria
+
+- ≥10 source files read and cited; product surface named.
+- At least one **Así te lo re-soluciono** block with real paths or install commands.
+- CLI numbers used as evidence, not as the whole report.
+- Design residual either absent with evidence or explicitly handed to `/ark-explore`.
+
+## 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-explain/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: ark-explain
+description: Explain this project's architecture in plain language and generate the showcase HTML report — layers, rules, coverage, gates, and why the contract exists.
+---
+
+# /ark-explain — Understand this project's architecture
+
+The user wants to understand the architecture, a specific rule, or why the gate blocked them.
+
+## When / not when
+
+| Use `/ark-explain` when… | Do **not** use it when… |
+|--------------------------|-------------------------|
+| Plain-language tour of layers/rules/report | Decision-grade recon / dual-plan → `/ark-explore` |
+| “Why did the gate block me?” pedagogy | Apply fixes → `/ark-fix` / `/ark-autopilot` |
+| Generate / walk HTML showcase report | Fitness numbers only → `/ark-coverage`; brownfield action → `/ark-adopt` |
+Your job is to **teach with this repo's real data** and leave a shareable visual artifact.
+
+## 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`.
+
+
+### Explain + ArkRules
+- HTML/plain tour: section **Layers** and section **Rules under contract (ArkRules)** —
+  when `arkRules` is active the showcase lists **per-layer counts**, **structure sensors**
+  (id / sensor / mode), **uncovered** invariants (call them out), and a **covered sample**.
+  Inactive map stays a short opt-in note. Counts are never a score.
+- Spoken tour: name 2–4 real invariant IDs and one structure sensor from this repo’s
+  `arkrules/*` (open the files — do not invent). Residual candidates → `--rules-inventory`.
+- **Teach the product model (required when arkRules is active):**
+  - **[Layer]** = dependency direction / purity / capabilities.
+  - **[ArkRules] structure** = module-shape **heuristics** (orchestration-only, thin-adapter, …);
+    enforced is not proof of Domain extraction.
+  - **[ArkRules] invariants** = named business policies as **data + coverage evidence**
+    (symbol/test); not a runtime engine and not a substitute for behavior tests.
+  - Green edges + covered catalog ≠ elegant Shape (design-weak residual stays honest).
+- Never merge Layers and ArkRules into one “architecture score.”
+
+## 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.
+
+## Always do this first (showcase report)
+
+1. Run the full HTML report (uses the real contract + coverage + gates):
+
+   ```bash
+   npx ark-check --root . --config ark.config.json --report ark-report.html
+   ```
+
+   Prefer the project's package-manager runner if gates already emit one
+   (`pnpm … exec ark-check` / `yarn` / `npx`).
+
+   This also maintains snapshots under **`.ark/reports/`**:
+   - `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
+
+   If origin already exists, the HTML includes **Evolution vs origin** (score, governed%,
+   violations, files per layer). Do not delete origin unless the user explicitly wants a
+   new baseline (`--reset-origin`).
+
+2. Tell the user the path to `ark-report.html` and `.ark/reports/origin.html`.
+   Mention `.ark/` should stay gitignored (Ark appends that on first report when possible).
+
+3. **Open the report in the default browser** (mandatory when `ark-report.html` exists and
+   this is a local interactive session — skip only in CI/headless or if the user said not to):
+
+   Detect OS and run **one** simple open (best-effort; do not fail the skill if open fails):
+
+   | OS | Command |
+   |----|---------|
+   | **macOS** | `open ark-report.html` |
+   | **Linux** | `xdg-open ark-report.html` |
+   | **Windows** | `start ark-report.html` (cmd) or `Invoke-Item ark-report.html` (PowerShell) |
+
+   One-liner that picks the host OS (from the project root, after the report was written):
+
+   ```bash
+   # macOS / Linux / Windows (Git Bash or similar)
+   case "$(uname -s 2>/dev/null || echo unknown)" in
+     Darwin*) open ark-report.html ;;
+     Linux*)  xdg-open ark-report.html ;;
+     MINGW*|MSYS*|CYGWIN*|Windows_NT) start ark-report.html 2>/dev/null || cmd.exe /c start ark-report.html ;;
+     *) open ark-report.html 2>/dev/null || xdg-open ark-report.html 2>/dev/null || true ;;
+   esac
+   ```
+
+   Prefer the absolute path if the cwd is not the project root. This only opens the file in
+   the **default browser** — no special flags, no browser selection.
+
+4. Optionally also run:
+
+   ```bash
+   npx ark-check --coverage
+   npx ark-check --doctor
+   npx ark-check --plan
+   ```
+
+   so your spoken explanation matches the report's governed%, operating mode
+   (SUGGEST / ADAPT / ENFORCE), and the plan's safe-to-auto vs decision counts.
+
+The HTML report is the visual twin of this skill: architecture map, files per layer,
+dependency direction, matrix, violations, **ArkRules under contract** (when mapped),
+enforcement points, Ark fitness score, and a **Senior diagnostics** block (coupling
+fan-in/out, deny density, purity surface, pattern forensics, baseline taxonomy) for
+tech leads.
+
+When explaining the **plan**, name the four `mechanical-safe` remediation kinds only
+(type-only move, pure-type file relocate, `import type` of pure-type modules,
+`import-type-of-type-exports` for named type exports from mixed modules; W6 port-proof inject is judgment when proof holds) — everything
+else is judgment/deferred and must not be auto-applied.
+
+**Type-edge honesty:** type-only denied edges are **placement debt** (`typeOnly` +
+`failsStrict: false`) — prefer SharedTypes / owning layer; they do not fail merge like value
+edges. Doctor `productHonesty` and `violations.typeEdgePolicy` must not be sold as “all done”
+when residual signals remain.
+
+## Spoken / written explanation
+
+1. **Load the real contract**: `ark.config.json`, `AGENTS.md`, and—when MCP is available—
+   `ark_identity` with the exact project root followed by `ark_manifest` with the same root plus
+   returned project id. `ark://manifest` is compatibility-only and always
+   unverified/non-authoritative.
+2. **If asked generally** ("explain the architecture"), produce a guided tour:
+   - Operating mode + governed% (honest: low coverage means green checks almost nothing).
+   - Each major layer: name, purpose, one real file from this repo, file count if known.
+   - Dependency direction in one short diagram (ASCII is fine).
+   - Enforcement points that are actually on: write gate, CI, ESLint, baseline.
+   - If a DI/kernel framework border exists, explain public surface vs internals.
+3. **If asked about a specific rule or block**, answer with: the rule, the consequence it
+   prevents, and the sanctioned fix (usually a port). If they want it fixed now:
+   **STOP — do not continue this skill as complete.** **STOP — fix requested: invoke /ark-fix.**
+   This skill stays read-only.
+4. **If asked "what's a port/adapter/saga…"**, two sentences + this-repo example or conventional path.
+
+## Operating rules
+
+- Prefer generating the HTML report even when the question is narrow — then zoom the prose.
+- Read-only for source code: this skill does not refactor product files (writing the report
+  HTML is fine).
+- Calibrate depth: one-rule questions get a paragraph; full tours get structure + report.
+- Every jargon term gets a one-line plain definition on first use.
+- End with:
+  - the strict check from `package.json` (or `ark-check --root . --config ark.config.json --strict-config`)
+  - `/ark-place` for "where does new code go?"
+  - the path to `ark-report.html`
+  - **open that HTML in the default browser** (step 3 above: `open` / `xdg-open` / `start`)
+    if you have not already — so the user sees the showcase without hunting for the file
+
+## Related
+
+- Onboarding: `/ark-architect`, `ark-check --recommend`, `docs/enthusiast/README.md`
+- Brownfield: `/ark-adopt`, `docs/brownfield-adoption.md`
+- Autopilot: `/ark-autopilot` after the user understands the contract
+
+## Completion contract (skill incomplete if missing)
+
+End with **exactly** these headings (markdown `###`):
+
+### Completion
+- **Sensor:** commands/tools run (include report + browser-open command when used)
+- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
+- **Result:** one-line outcome (include `ark-report.html` path; note if browser open was attempted)
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Handoff:** `/ark-…` / CLI / `none`
+- **Incomplete?** `no` | `yes — <what is missing>`
+
+Prefer **Incomplete?** `yes` if the showcase report was generated but the browser-open step was
+skipped without CI/headless/user-opt-out reason.
+
+If a **STOP** handoff applies and you continued as if done, set **Incomplete?** to `yes`.
+**Skill incomplete if missing** any of the bullets above.