arkgate 3.0.2 → 3.0.4

package/templates/skills/ark-explain.md

@@ -57,7 +57,33 @@ the same files or weaken the gate.
 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. Optionally also run:
+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
@@ -104,6 +130,8 @@ else is judgment/deferred and must not be auto-applied.
   - 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
 
@@ -116,11 +144,14 @@ else is judgment/deferred and must not be auto-applied.
 End with **exactly** these headings (markdown `###`):
 
 ### Completion
-- **Sensor:** commands/tools run
+- **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
+- **Result:** one-line outcome (include `ark-report.html` path; note if browser open was attempted)
 - **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.

package/templates/skills/ark-explore.md

@@ -16,10 +16,15 @@ ranked residual that changes the next command — **not** a celebration of ENFOR
 | Use `/ark-explore` when… | Do **not** use it when… |
 |--------------------------|-------------------------|
 | Map / “what next?” / residual after ENFORCE | User wants edits applied → `/ark-autopilot` or `/ark-fix` |
+| **Primary post-green door (Q01):** messy / spaghetti / design-weak / “clarify for AI” | Skill-shopping coverage or think for the same residual |
 | Spaghetti brownfield: patterns concurrent, design-weak under green check | Only “governed% + gates installed?” numbers → `/ark-coverage` |
 | Dual-plan **seed** (A remediation + B pattern bets) without applying | One design trade-off between 2–3 options already mapped → `/ark-think` |
 | Path-correct vs design-correct honesty | Plain-language tour / HTML report → `/ark-explain` |
 
+**Q01 single path:** when doctor `postGreenPath` / ENFORCE · design-weak is active, **this skill
+(shape-focus / dual-plan seed) is the map half of the one door** — then `/ark-autopilot` only
+to apply B with user OK. Do not send the user to coverage or think as equal first choices.
+
 `/ark-autopilot`, `/ark-adopt`, and `/ark-coverage` embed a **lighter** version of this pass.
 **You** are the full recon + pattern-planning skill.
 
@@ -218,11 +223,15 @@ ENFORCE without Shape progress is **`ENFORCE · design-weak`** — say that out
 | `facade-sql-in-routes` | Routes import raw ORM/SQL while “repositories exist” elsewhere |
 
 **Extraction card** (for each I/O / god-module B bet — judgment, never mechanical-safe).
-Canonical productized template also in `docs/brownfield-adoption.md` §6:
+Canonical productized template also in `docs/brownfield-adoption.md` §6.
+
+**Q04 pilot loop:** when doctor/plan JSON is available, use **`pilotLoop.nextPilot`** as the
+**single** next extraction card (one pilot at a time → re-doctor). Do not open five B bets
+in parallel. After the pilot lands, re-run doctor; success = reduced evidence on pilot paths.
 
 ```text
 ### Extraction card
-Pilot: <one dir or feature>
+Pilot: <one dir or feature — or pilotLoop.nextPilot.pilotTarget>
 Smell: <doctor designSmells[].id when present, else agent-detected id>
 Move: <verbatim I/O or rule → port/adapter or Domain file>
 Do not:
@@ -230,12 +239,13 @@ Do not:
   - weaken ark.config.json
   - auto-apply as mechanical-safe or invent new mechanical-safe kinds
   - big-bang the monorepo
-Success: <observable / falsifiable>
+Success: <observable / falsifiable — re-doctor>
 Kill-switch: <stop condition>
-Next: /ark-autopilot (apply with user ok) | /ark-fix (one cluster) | /ark-contract (globs only)
+Next: /ark-autopilot (apply with user ok) | /ark-fix (one cluster) | re-doctor
 ```
 
-When doctor JSON is available, prefer smell `id`s from `designSmells` / `patternBets[].smellId`.
+When doctor JSON is available, prefer smell `id`s from `designSmells` / `patternBets[].smellId`
+and the ranked **`pilotLoop.nextPilot`**.
 
 ## Output format (keep tight)
 

package/templates/skills/ark-place.md

@@ -47,7 +47,10 @@ the same files or weaken the gate.
 1. **Read the contract, not your intuition.** If the `ark` MCP server is available,
    call the **`ark_place`** tool with the target file path — it returns the layer,
    its forbidden globals, and exactly which layers the file may / must not import,
-   straight from the contract (no guessing). Otherwise load `ark.config.json` and the
+   straight from the contract (no guessing). When present, also honor optional
+   **`goldenPattern`** (from `.ark/golden-pattern.json`) for **NEW code only** —
+   advisory layout norm; never overrides the gate and never clears design-weak.
+   Absent golden is normal. Otherwise load `ark.config.json` and the
    `ark://manifest` MCP resource (it includes `suggestedLayers` with conventional
    directories for layers not yet adopted). The project's `AGENTS.md` placement table,
    if present, is authoritative too.