arkgate 2.9.1 → 2.10.0

package/templates/skills/ark-think.md

@@ -1,6 +1,6 @@
 ---
 name: ark-think
-description: "Host-side architectural reasoning within the Ark contract — trade-offs, evolution, design options. No gate bypass. No package LLM call."
+description: "Host-side architectural reasoning — exploratory options from real code + contract, trade-offs, evolution paths. No gate bypass. No package LLM call."
 ---
 
 # /ark-think — Architectural reasoning (host LLM only)
@@ -9,35 +9,86 @@ 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.
 
+
+## 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 |
+
+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,
+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.
+
 ## When to use
 
 - Design trade-offs before writing code
-- "Should this be a new layer or a feature slice?"
+- “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%.
-2. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,
-   ddd-bounded-contexts, feature-sliced, monorepo, …). If none, run `--recommend --json`.
-3. **Reason within bounds** — propose options that **stay enforceable** by the gate.
+   `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.
+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.
    Prefer concrete paths and import rules over abstract diagrams.
-4. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
+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
    judgment auto-apply, codemod engines, or skipping write-gate/CI.
-5. **Hand off** — for placement use `/ark-place`; for config edits `/ark-contract`; for
-   bulk debt `/ark-loop` / `/ark-autopilot`; for violations `/ark-fix`.
+7. **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:** 2–3 sentences on current contract + shape
-- **Options:** 2–3 alternatives with trade-offs (coupling, testability, AI-agent safety)
-- **Recommendation:** one option + why it is enforceable today
+- **Context:** product + contract + what you opened (paths)
+- **Options:** 2–3 alternatives with trade-offs (coupling, testability, agent safety, enforceability)
+- **Recommendation:** one option + why it is enforceable **today**
+- **Risks if we pick wrong:** one sentence user-visible impact
 - **Next command:** exact `ark-check` / skill to run next
 
 ## Related
 
 - Greenfield shape: `/ark-architect`
 - Brownfield: `/ark-adopt`
+- Full recon: `/ark-explore`
 - Explain existing: `/ark-explain`
+
+## 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
+- **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/skills/ark-upgrade.md

@@ -38,6 +38,23 @@ read the **Adoption** section — host gaps, Codex home temp paths, optional-but
 core layers, missing origin snapshot, baseline policy. Fix commands are printed per gap.
 HTML reports include the same Adoption card (separate from the 0–100 fitness score).
 
+## 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**.
+
+
+## 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.
+
 ## Fast path
 
 One command does the whole flow — update the package, refresh gates + `/ark-*` skills
@@ -113,7 +130,8 @@ npx arkgate-check --install-agent-gates --skills-only --force
 4. **Re-verify** — `ark-check --root . --config ark.config.json
    --strict-config` (with `--baseline .ark-baseline.json` if present). A new
    version may detect violations the old one missed: if new violations appear,
-   apply `/ark-fix` reasoning to resolve them. If they are too numerous to fix
+   **STOP — do not continue this skill as complete.** **STOP — bulk residual debt: invoke /ark-loop or /ark-autopilot**
+   (or `/ark-fix` for a small set). If they are too numerous to fix
    now, freezing them in the baseline (`--update-baseline`) is a valid stopgap
    but it silences NEW violations, so it requires explicit user approval first
    — never regenerate the baseline on your own to get a green check.
@@ -142,3 +160,17 @@ End with a passing check. Report: latest published version, old → new version
 (or "already latest"), changelog entries that mattered here (plain language),
 files written/refreshed per tool, skipped customized files needing a manual
 look, and the final check status.
+
+## 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
+- **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.