arkgate 2.9.1 → 2.9.2

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 2.9.2 — 2026-07-09
+
+Skill surface hardening: dual-engine, explore, STOP handoffs, AGENTS routing, subagent fan-out.
+**No intentional CLI flag or JSON shape breaks.**
+
+### Added
+
+- **`/ark-explore` skill:** exploratory architecture reconnaissance — product map, entry
+  points, coupling hotspots, false-green risk, ranked *suggestions* (not only residual
+  violations). CLI remains a sensor; host agent reads the real tree.
+- **Skill completion contract:** every `/ark-*` template ends with fixed
+  `### Completion` fields (Sensor / Opened / Result / Handoff / Incomplete?) —
+  **skill incomplete if missing**.
+- **Hard STOP handoffs:** critical paths (false-green, concentrated edge, bulk debt,
+  wrong skill) use `STOP — do not continue this skill as complete` + named next skill.
+- **AGENTS skill routing table:** trigger → skill map in generated `AGENTS.md` while
+  keeping `/ark-autopilot` as the default when unsure.
+- **Subagent fan-out protocol:** every `/ark-*` skill documents optional **parallel
+  subagents** when the host supports them (disjoint read-only scopes + parent merge);
+  otherwise **fall back to sequential**. AGENTS.md repeats the rule.
+
+### Changed
+
+- **Skills dual-engine (deterministic + exploratory):** **all** shipped skill templates
+  require dual-engine behavior (CLI sensor + real source/product pass where applicable).
+  Plan empty ≠ architecture healthy without explore. Refresh installed skills with
+  `ark-check --install-agent-gates --skills-only --force`.
+
 ## 2.9.1 — 2026-07-09
 
 Field-install honesty: non-TTY start, baseline→CI sync, pin, false-green soft block, Grok defaults.

package/README.md

@@ -144,19 +144,25 @@ npx arkgate-check --coverage
 Install once: `npx arkgate-check --install-agent-gates`  
 (`--tools claude,cursor,codex,grok` to pick hosts.)
 
-**Default is always `/ark-autopilot`.** The rest are escapes, not a second curriculum:
+**Default is always `/ark-autopilot`.** The rest are escapes, not a second curriculum.
+Generated `AGENTS.md` includes a **skill routing table** (trigger → skill). Skills are
+**dual-engine** (CLI sensor + read real source) and end with a fixed **completion contract**;
+critical handoffs say **STOP** and name the next skill (hosts must follow — markdown cannot chain calls).
+When the host allows it, skills may **fan out parallel subagents** (disjoint scopes);
+otherwise they **fall back to sequential**.
 
 | Need | Skill |
 |------|--------|
 | Only the apply loop (plan already exists) | `/ark-loop` |
 | Empty greenfield shape/scaffold | `/ark-architect` |
 | Deep brownfield / manifest mining alone | `/ark-adopt` |
+| Exploratory map of the real product (no apply) | `/ark-explore` |
 | New file placement | `/ark-place` |
 | Gate violation on a change | `/ark-fix` |
 | Design trade-offs within the contract (no package LLM) | `/ark-think` |
 | Edit `ark.config.json` safely | `/ark-contract` |
 | Plain-language tour of the report | `/ark-explain` |
-| Deep “what am I not using?” audit | `/ark-coverage` |
+| Deep coverage + opportunities audit | `/ark-coverage` |
 | Migrate hand-rolled bus/outbox (TS) | `/ark-runtime` |
 | Bump ArkGate + refresh all agent hosts | `/ark-upgrade` |
 

package/bin/lib/agent-gates.mjs

@@ -465,13 +465,39 @@ export function agentInstructions(root) {
 
 1. If \`ark.config.json\` is missing: run \`${startCmd}\` once.
 2. For adoption / cleanup / “make architecture sound”: run the **\`/ark-autopilot\`** skill
-   (origin report → adopt → plan → safe fixes → gates). Do **not** invent a parallel workflow
-   from the long skill list.
+   (origin report → adopt → plan → safe fixes → gates). Do **not** invent a second
+   architecture curriculum outside the routing table below — when a trigger matches, use
+   that skill; when unsure, stay on autopilot.
 3. Status anytime: \`${doctorCmd}\` (status light + next action — not a mode picker).
 4. After ordinary feature edits: run \`${checkCmd}\`. On violations → **\`/ark-fix\`** (or
    \`/ark-place\` for new files, \`/ark-contract\` only if the contract itself is wrong).
 
-Other \`/ark-*\` skills are optional escapes (adopt, coverage, runtime, …), not required steps.
+Skills are **dual-engine**: deterministic CLI sensors + exploratory read of *this* repo — not JSON-only wrappers.
+When a skill says **STOP — do not continue this skill as complete**, stop and invoke the named handoff skill.
+
+### Subagent fan-out
+If the host supports **parallel subagents**, skills may ask you to fan out **read-only**
+scouts (disjoint path scopes) and merge in the parent. If the host does **not**,
+**fall back to sequential** — one cluster/step at a time. Never parallel-write the same
+files; never weaken the gate via subagents.
+
+## Skill routing (triggers → skill)
+
+| When | Invoke |
+|------|--------|
+| Unsure / make architecture sound | **/ark-autopilot** (default) |
+| Need map / opportunities only (no apply) | \`/ark-explore\` |
+| Greenfield shape / empty tree | \`/ark-architect\` |
+| Brownfield / wrong contract / false-green | \`/ark-adopt\` then \`/ark-contract\` if globs wrong |
+| Edit \`ark.config.json\` layers/rules/intents | \`/ark-contract\` |
+| New file “where does this go?” | \`/ark-place\` |
+| Gate violation on a change | \`/ark-fix\` |
+| Drive plan to goal.met | \`/ark-loop\` |
+| Deep coverage + ranked audit | \`/ark-coverage\` |
+| Design trade-offs (no package LLM) | \`/ark-think\` |
+| Explain / HTML report tour | \`/ark-explain\` |
+| Bump arkgate + refresh hosts | \`/ark-upgrade\` |
+| Optional runtime kernel migrate | \`/ark-runtime\` |
 
 ## Before editing TypeScript or JavaScript source files
 

package/dist/index.cjs

@@ -80,7 +80,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var version = "2.9.1";
+var version = "2.9.2";
 
 // src/kernel/intent/IntentRegistry.ts
 var IntentRegistry = class {