arkgate 4.8.13 → 4.8.15

package/templates/skills/ark-think.md

@@ -1,54 +1,24 @@
 ---
 name: ark-think
-description: 2–3 options for one import-rule or ArkRules decision. Not a full map (use /ark-explore).
+description: Shortcut to /ark-explore for one import-rule or ArkRules decision (2–3 options).
 ---
 
-# /ark-think — Architectural reasoning (host LLM only)
+# /ark-think — Shortcut to /ark-explore
 
-**Not a first-run door.** One decision only. Session 0 → **`/ark-adopt`**.
-Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Do not send the user to leftover `/ark-contract` or `/ark-fix`.
-
-You are the user's architecture thinking partner **inside** the project's Ark contract.
-This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)
-reason; the write-gate and CI remain deterministic.
-
-## Improvement compass (process preflight)
-
-When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
-Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
-0–10 scores or Excellent/Good ranks.
-
-**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
-
-**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
-are not “architecture finished.”
-
-**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
-new files; place before write (`/ark-place` / prepare-write).
-
-**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
-patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
-
-**2–3 options labeled by lens impact** (what residual improves / what stays out-of-scope).
-
-## Deep modules (process)
-
-- Prefer **deep modules** (small interface, hidden complexity). Never invent a depth score.
-- Label the **seam** on each option that introduces a port/adapter; apply the **deletion test** before pass-through extracts “for testability.”
-- Recommend tests **at the public interface** of the chosen seam.
+**Not a first-class door.** One-release redirect. One bounded decision with 2–3
+enforceable options is **`/ark-explore`** (section **One decision**). Do that job now.
+Contener · Guiar · Ordenar — this leftover name is not a star.
 
 ## 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-autopilot` |
-| Trade-offs before writing a **new** feature | Brownfield config wrong / false-green → `/ark-adopt` |
-| 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.
+| Use this leftover name when… | Prefer instead |
+|------------------------------|----------------|
+| One decision: 2–3 options already bounded | **`/ark-explore`** (one decision) |
+| Full map / ranked residual / dual-plan seed | **`/ark-explore`** (recon) |
+| Apply the chosen option | **`/ark-autopilot`** |
+| Session 0 / false-green | **`/ark-adopt`** |
+| One kernel candidate | **`/ark-runtime`** |
+| One order-plane candidate | **`/ark-order`** |
 
 ## Dual engine (mandatory)
 
@@ -57,8 +27,7 @@ If you lack a product map and the tree is messy: run a **compressed** explore pa
 | **Deterministic** | What the contract and doctor *prove* today (layers, rules, governed%, gaps) |
 | **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.
-
+The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
 ## MCP workspace binding (mandatory)
 
@@ -69,92 +38,25 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
 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 + extras (mandatory, except /ark-runtime)
-
-ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; you **always label** findings so they never blur. Absence of an extra is silent and valid. Skills never enforce. ArkOrder is an extra **inside** the `arkgate` package (`arkgate/order`), not a second install.
-
-| 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` |
-| **ArkRun** (extra) | Kernel usage + complete declarations; information package `decisionTape` `{ xiHash, event, residual }` | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
-| **ArkOrder** (extra) | Operational pattern (ξ vs s). Valve: first `release()`, later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb \| escalate_up \| hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore` | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
-
-**Rules for every report / answer:**
-1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a 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-adopt`** / leftover **`/ark-contract`**; fixing code under a structure sensor is leftover **`/ark-fix`** / **`/ark-loop`** or **`/ark-autopilot`** (judgment, never invent mechanical-safe). Extra decisions stay on existing doors. Do not invent `/ark-run` or `/ark-order`.
-5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
-
-
-### Think + ArkRules
-- For ONE decision, consider options on **both** planes when relevant: e.g. new layer wall **vs** structure sensor **vs** invariant catalog entry.
-- Every option must state enforceability: which plane holds it after the change.
-
-### Think + extras
-- Extra decisions stay enforceable on existing doors (`/ark-adopt` session 0, `/ark-place` new file, `/ark-autopilot` grind, `/ark-runtime` one kernel candidate). No new skill name. Do not invent `/ark-run` or `/ark-order`.
-
 ## 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**:
+If the host supports **parallel subagents**, fan out read-only scouts; otherwise
+**fall back to sequential**. Never weaken the gate.
 
-| 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. |
+## Related onboarding
 
-**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.
+- **Greenfield:** `/ark-adopt` or `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt`.
+- **One decision:** `/ark-explore` (this leftover name redirects there).
 
 ## Steps
 
-1. **Load the contract** — `ark.config.json`; when MCP is available, call `ark_identity` with
-   the exact project root followed by `ark_manifest` with the same root plus returned project
-   id. The `ark://manifest` resource is compatibility-only and always
-   unverified/non-authoritative. Use `ark-check --coverage --json` / `--doctor` for honesty
-   about governed% and false-green.
-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. **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.
-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.
-8. **Hand off** — placement `/ark-place`; first extra `/ark-adopt`; grind `/ark-autopilot`;
-   map-only `/ark-explore`; leftover config `/ark-contract`; leftover cluster `/ark-fix` /
-   `/ark-loop`. Extra decisions stay on those doors. Do not invent `/ark-run` or `/ark-order`.
-   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) + 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
-
-## Related
-
-- Greenfield shape: `/ark-architect`
-- Brownfield: `/ark-adopt`
-- Full recon / dual-plan seed: `/ark-explore`
-- Explain existing: `/ark-explain`
+1. Execute **`/ark-explore`** one-decision: open ≥5 files, name 2–3 enforceable options, recommend one.
+2. Hand off apply → `/ark-autopilot`; new file → `/ark-place`.
 
 ## Completion contract (skill incomplete if missing)
 
-End with **exactly** these headings (markdown `###`):
+Skill incomplete if missing any field below.
 
 ### Completion
 - **Sensor:** commands/tools run
@@ -162,9 +64,5 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
-- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
-- **Handoff:** `/ark-…` / CLI / `none`
+- **Handoff:** `/ark-explore` / `/ark-autopilot` / `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

@@ -5,9 +5,20 @@ description: Upgrade ArkGate. Preview first, keep customized files, then apply.
 
 # /ark-upgrade — managed ArkGate upgrade
 
+**Contener · Guiar · Ordenar.** In plain words: contain the write, guide the next
+step, order leftover mess. This door is **Contener**: keep the pin current.
+Skills never enforce — CLI / hooks / CI do.
+
 **When:** bump the published `arkgate` package and refresh managed gates.
 **Not when:** session 0 (`/ark-adopt`) or leftover design (`/ark-explore`).
 
+## When / not when
+
+| Use `/ark-upgrade` when… | Do **not** use it when… |
+|--------------------------|-------------------------|
+| Bump the pin and refresh managed gates | Session 0 / path missing → `/ark-adopt` |
+| Preview then `--apply` in this turn | Leftover design / map → `/ark-explore`; apply Shape → `/ark-autopilot` |
+
 ## Steps
 
 1. Preview: `arkgate upgrade` (no writes). Default is **hosts keep** — do not retire other hosts’ skills.
@@ -132,8 +143,8 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 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. After upgrade, leftover architecture work is **`/ark-autopilot`** (never invent `mechanical-safe`).
-5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
-6. Schema `1.3` extras stay off unless already on. Pin teaches `arkgate/runtime` (same tarball), not the deprecated companion. Do not invent `/ark-run` or `/ark-order`.
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` / `INVARIANT_CATALOG_EMPTY` with `evidence.arkruleId`.
+6. Schema `1.3` extras stay off unless already on. Pin teaches `arkgate/runtime` and `arkgate/order` (same tarball), not a second install. Wire after upgrade via `/ark-runtime` / `/ark-order`. Do not invent `/ark-run`.
 
 
 ### Upgrade + ArkRules
@@ -143,7 +154,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ### Upgrade + extras
 - Schema `1.3` extras (`arkRun` / `arkOrder`) stay off unless already on. Do not turn extras on during upgrade.
 - Pin teaches `arkgate/runtime` (same tarball). `@arkgate/runtime` is deprecated. Do not send agents to `packages/runtime/README.md` as the kernel guide.
-- After 4.8.2, customized skills may lag — opt-in `--refresh-skills` with consent so the frozen 13 names pick up four-plane deepen. No new skill names.
+- After 4.8.2, customized skills may lag — opt-in `--refresh-skills` with consent so the closed catalog picks up four-plane deepen + `/ark-order`. Add a name only with a live ROADMAP item.
 
 ## Safety contract
 

package/templates/tests/ark-adoption-gaps.test.ts

@@ -39,12 +39,13 @@ describe('ArkGate adoption gaps (structural)', () => {
       { dir: '.cursor', skill: (n) => path.join('.cursor', 'commands', `${n}.md`) },
     ];
     const required = [
-      'ark-autopilot',
-      'ark-loop',
-      'ark-fix',
       'ark-adopt',
-      'ark-architect',
+      'ark-place',
+      'ark-explore',
+      'ark-autopilot',
       'ark-upgrade',
+      'ark-runtime',
+      'ark-order',
     ];
     for (const h of hosts) {
       if (!exists(h.dir)) continue;