arkgate 3.0.0 → 3.0.2

package/templates/skills/ark-loop.md

@@ -12,6 +12,19 @@ Deterministic kinds stay **tight**. Your job is still **exploratory on the files
 importers/targets, see if the plan step is a symptom of wrong shape / false Domain / I/O
 under Application — escalate to `/ark-contract` or `/ark-explore` when the wall is structural.
 
+## When / not when
+
+| Use `/ark-loop` when… | Do **not** use it when… |
+|-----------------------|-------------------------|
+| Plan A has steps; drive to `goal.met` | Plan A empty — **stop**; residual Shape → `/ark-explore` / `/ark-autopilot` B |
+| Mechanical-safe + approved judgment only | Full product recon first → explore inside `/ark-autopilot` |
+| User already has a plan and wants the apply loop | Brownfield contract false-green → `/ark-adopt` |
+
+**Empty plan is not success for the product** — only for *edge remediation*. If `goal.met` and
+(`goal.designWeak` or non-empty `patternBets` from `--plan --json`): do **not** invent
+mechanical-safe kinds; hand off `/ark-explore` shape-focus or `/ark-autopilot` for dual-plan B.
+Pattern bets always have `neverMechanicalSafe: true` — extraction cards only
+(`docs/brownfield-adoption.md` §6).
 
 ## Related onboarding
 
@@ -71,7 +84,8 @@ Never auto: free value uses of imports, multi-import files, dynamic import/requi
 
 ## Steps
 
-1. **Plan** — `ark-check --plan --json` (+ `--baseline` if used). If `goal.met`, stop.
+1. **Plan** — `ark-check --plan --json` (+ `--baseline` if used). If `goal.met`: stop **A**;
+   if design-weak residual is visible, hand off explore/autopilot B — do not claim architecture done.
 2. **Worktree** — prefer discardable git worktree.
 3. **Apply mechanical-safe** one-by-one with validate/rollback.
 4. **Judgment** — propose with source-based design; apply only if user approved (or parent autopilot said full apply).

package/templates/skills/ark-place.md

@@ -5,6 +5,13 @@ description: "Where does new code go? Names the layer, directory, and naming for
 
 # /ark-place — Where does this code go?
 
+## When / not when
+
+| Use `/ark-place` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| New artifact: where + scaffold under contract | Existing violation fix → `/ark-fix` |
+| Naming / directory for a known kind | Contract layers wrong → `/ark-contract`; full shape choice greenfield → `/ark-architect` |
+
 The user describes something they need to build (a saga, a background job, an
 event handler, a repository, an HTTP client, a use case, a projection, …).
 Your job: name the layer it belongs to, the directory, the naming convention,

package/templates/skills/ark-think.md

@@ -1,6 +1,6 @@
 ---
 name: ark-think
-description: "Host-side architectural reasoning — exploratory options from real code + contract, trade-offs, evolution paths. No gate bypass. No package LLM call."
+description: Host-side architectural reasoning — 2–3 enforceable options from real code + contract for ONE decision. Not full recon (use /ark-explore). No gate bypass. No package LLM call.
 ---
 
 # /ark-think — Architectural reasoning (host LLM only)
@@ -9,17 +9,27 @@ You are the user's architecture thinking partner **inside** the project's Ark co
 This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)
 reason; the write-gate and CI remain deterministic.
 
+## When / not when
+
+| Use `/ark-think` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| One decision: new layer vs slice, port vs shared, peerIsolation choice | Full map / ranked residual / dual-plan seed → `/ark-explore` |
+| 2–3 options already bounded by a known surface | Apply remediation → `/ark-fix` / `/ark-loop` / `/ark-autopilot` |
+| Trade-offs before writing a **new** feature | Brownfield contract wrong / false-green → `/ark-adopt` then `/ark-contract` |
+| Explain *why* a rule exists in *this* tree | HTML tour → `/ark-explain`; fitness numbers → `/ark-coverage` |
+
+If you lack a product map and the tree is messy: run a **compressed** explore pass first
+(≥8 files) **or** **STOP** and invoke `/ark-explore` — do not invent options from diagrams alone.
 
 ## Dual engine (mandatory)
 
 | Engine | Role |
 |--------|------|
 | **Deterministic** | What the contract and doctor *prove* today (layers, rules, governed%, gaps) |
-| **Exploratory** | What *this* codebase wants to become — options grounded in files you open |
+| **Exploratory** | What *this* decision surface wants — options grounded in files you open |
 
 Never reason only from abstract hexagons. Open real modules before recommending a shape.
 
-
 ## Subagent fan-out (optional, host-dependent)
 
 When the user asks to go faster **or** the work naturally splits (multiple packages,
@@ -37,38 +47,32 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 4. Parent owns the **### Completion** block (union of **Opened**, single **Handoff**).
 5. Do **not** use subagents to weaken the gate or invent `mechanical-safe` kinds.
 
-## When to use
-
-- Design trade-offs before writing code
-- “Should this be a new layer or a feature slice?”
-- Evolving brownfield layout toward a named preset
-- Explaining why a peerIsolation or layer rule exists
-- Choosing among 2–3 enforceable futures (not infinite diagrams)
-
 ## Steps
 
 1. **Load the contract** — `ark.config.json`, MCP `ark://manifest` if available, and
    `ark-check --coverage --json` / `--doctor` for honesty about governed% and false-green.
-2. **Touch the product** — README + **≥5 source files** on the decision surface (the feature,
-   package, or boundary under discussion). Name paths in the answer.
+2. **Touch the decision surface** — README skim + **≥5 source files** on the feature/package/boundary
+   under discussion. Name paths in the answer.
 3. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,
    ddd-bounded-contexts, feature-sliced, monorepo, …). If none, run `--recommend --json`
    **and** say whether detection matches the tree you opened.
-4. **Reason within bounds** — propose options that **stay enforceable** by the gate.
+4. **Name concurrent patterns** on the decision surface (if ≥2): which is **golden** vs legacy.
+5. **Reason within bounds** — propose **2–3 options** that **stay enforceable** by the gate.
    Prefer concrete paths and import rules over abstract diagrams.
-5. **Explore alternatives** — for each option: coupling, testability, **AI-agent safety**
-   (will write-gate + skills keep humans honest?), migration cost.
-6. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
+6. **Explore alternatives** — for each option: coupling, testability, **AI-agent safety**,
+   migration cost, **pilot + kill-switch** if the option adds a layer or wall.
+7. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
    judgment auto-apply, codemod engines, or skipping write-gate/CI.
-7. **Hand off** — placement `/ark-place`; config `/ark-contract`; bulk debt `/ark-loop` /
+8. **Hand off** — placement `/ark-place`; config `/ark-contract`; bulk debt `/ark-loop` /
    `/ark-autopilot`; map-only `/ark-explore`; violations `/ark-fix`.
    When the user needs action not advice: **STOP — do not continue this skill as complete** — invoke the handoff skill.
 
 ## Output format
 
-- **Context:** product + contract + what you opened (paths)
+- **Context:** product + contract + what you opened (paths) + phase if known (Align/Stabilize/Shape)
 - **Options:** 2–3 alternatives with trade-offs (coupling, testability, agent safety, enforceability)
 - **Recommendation:** one option + why it is enforceable **today**
+- **Pilot / kill-switch:** if the choice changes shape or adds a layer
 - **Risks if we pick wrong:** one sentence user-visible impact
 - **Next command:** exact `ark-check` / skill to run next
 
@@ -76,7 +80,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 
 - Greenfield shape: `/ark-architect`
 - Brownfield: `/ark-adopt`
-- Full recon: `/ark-explore`
+- Full recon / dual-plan seed: `/ark-explore`
 - Explain existing: `/ark-explain`
 
 ## Completion contract (skill incomplete if missing)