arkgate 3.8.3 → 3.9.0

package/docs/use.md

@@ -0,0 +1,88 @@
+# Use ArkGate
+
+For **anyone** shipping TypeScript with an AI coding agent. You do not need to study clean architecture first.
+
+**One contract. One gate. One co-pilot.**
+
+---
+
+## In one minute
+
+```bash
+npm install -D arkgate typescript
+npx arkgate start                 # preview what will change
+npx arkgate start --apply         # install compact contract + host router + CI plan
+npx arkgate-check --doctor        # where am I? one status light, one next action
+```
+
+Then keep working with your agent. The doctor is the **control plane**: when stuck, run doctor and do action **#1**.
+
+| Stuck on… | Do this |
+|-----------|---------|
+| Unsure | `npx arkgate-check --doctor` |
+| Agent broke architecture | Fix the edge doctor names (or re-run check) |
+| Code is green but still a mess | Shape residual — see below |
+| New ArkGate version | Follow doctor / upgrade guidance |
+
+Full skill pack is **optional** (expert depth). Day-to-day: compact router + doctor is enough.
+
+---
+
+## What you get
+
+| When | What happens |
+|------|----------------|
+| While the AI writes | Host write gate or advisory MCP (depends on host) |
+| Before merge | `arkgate-check` — make it a **required** CI status |
+| Anytime | Doctor: Suggest / Adapt / Enforce (+ design-weak if residual) |
+
+ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + co-pilot for AI TypeScript.
+
+---
+
+## Status lights (not settings)
+
+| Light | Means | Your move |
+|-------|--------|-----------|
+| **Suggest** | New or thin project | Finish `start`, re-run doctor |
+| **Adapt** | Not fully protected yet | Doctor action #1 until clean |
+| **Enforce** | Edges honest under the contract | Keep write path + CI |
+| **Enforce · design-weak** | Edges clean; design still messy | Shape door — not “done” |
+
+**Green edges ≠ elegant design.** Empty remediation plan is not “architecture finished” if design residual remains.
+
+---
+
+## When the gate is green but the code is still messy
+
+That is **Shape** work (plan B) — suggested, never auto-applied as silent magic.
+
+1. Doctor confirms design-weak  
+2. Guided map / dual plan (skill pack: `/ark-explore` then `/ark-autopilot` with your OK)  
+3. One pilot at a time · re-run doctor  
+
+Install skills only when you want that guided path:
+
+```bash
+npx arkgate-check --install-agent-gates --skills-only --force
+```
+
+---
+
+## Tutorials and demos
+
+- Plain-language track: [enthusiast/](enthusiast/README.md)  
+- First project tutorial: [enthusiast/tutorial-first-project.md](enthusiast/tutorial-first-project.md)  
+- Demos: [demos/](demos/)  
+
+---
+
+## Next depth
+
+| Need | Doc |
+|------|-----|
+| Hosts, CI, MCP, brownfield, power CLI | [develop.md](develop.md) |
+| Wire a specific agent host | [ai-gates.md](ai-gates.md) |
+| Improve the library | [CONTRIBUTING.md](../CONTRIBUTING.md) |
+
+← [All docs](README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.8.3",
+  "version": "3.9.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -65,7 +65,11 @@
     "!dist/**/*.d.cts",
     "schemas",
     "!schemas/*.source.json",
+    "docs/README.md",
+    "docs/use.md",
+    "docs/develop.md",
     "docs/agent-guide.md",
+    "docs/product-voice.md",
     "docs/enthusiast",
     "docs/demos/01-write-gate-self-correction.md",
     "docs/demos/02-brownfield-baseline-adoption.md",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "3.8.3",
+  "version": "3.9.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.8.3",
+      "version": "3.9.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/hooks/opencode-ark-write-gate.mjs

@@ -0,0 +1,85 @@
+/**
+ * Experimental OpenCode plugin: best-effort write gate via tool.execute.before.
+ *
+ * Install:
+ *   1. Copy to `.opencode/plugins/ark-write-gate.mjs` (or reference from opencode.json plugin list)
+ *   2. Ensure `arkgate-mcp` / `npx arkgate-mcp` is on PATH
+ *   3. Keep CI on `arkgate-check --strict-merge` + required status
+ *
+ * Honesty: OpenCode plugin hooks are **not** a complete hard write boundary
+ * (subagent and alternate tool paths may bypass). Never treat this plugin as
+ * Claude/Grok/Antigravity PreToolUse hard-write. Prefer MCP `ark_prepare_write`
+ * + required merge status.
+ *
+ * This file is a gallery template shipped with arkgate — not auto-installed.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+const WRITE_TOOLS = new Set(['write', 'edit', 'apply_patch', 'patch']);
+
+function resolveMcpBin() {
+  return process.env.ARK_MCP_BIN?.trim() || 'npx';
+}
+
+function resolveMcpArgs(root) {
+  const bin = process.env.ARK_MCP_SCRIPT?.trim();
+  if (bin) {
+    return [bin, '--hook', '--root', root, '--config', 'ark.config.json'];
+  }
+  return ['arkgate-mcp', '--hook', '--root', root, '--config', 'ark.config.json'];
+}
+
+function toClaudePayload(tool, args) {
+  if (tool === 'write') {
+    return {
+      tool_name: 'Write',
+      tool_input: {
+        file_path: args?.filePath ?? args?.path ?? args?.file_path,
+        content: args?.content ?? '',
+      },
+    };
+  }
+  if (tool === 'edit') {
+    return {
+      tool_name: 'Edit',
+      tool_input: {
+        file_path: args?.filePath ?? args?.path ?? args?.file_path,
+        old_string: args?.oldString ?? args?.old_string ?? '',
+        new_string: args?.newString ?? args?.new_string ?? '',
+      },
+    };
+  }
+  if (tool === 'apply_patch' || tool === 'patch') {
+    return {
+      tool_name: 'apply_patch',
+      tool_input: {
+        patch: args?.patchText ?? args?.patch ?? args?.content ?? '',
+      },
+    };
+  }
+  return null;
+}
+
+export default async function ArkWriteGatePlugin(ctx) {
+  const root = ctx?.directory ?? ctx?.worktree ?? process.cwd();
+  return {
+    'tool.execute.before': async (input, output) => {
+      const tool = String(input?.tool ?? '').toLowerCase();
+      if (!WRITE_TOOLS.has(tool)) return;
+      const payload = toClaudePayload(tool, output?.args ?? input?.args ?? {});
+      if (!payload) return;
+      const result = spawnSync(resolveMcpBin(), resolveMcpArgs(root), {
+        input: JSON.stringify(payload),
+        encoding: 'utf8',
+        cwd: root,
+        env: process.env,
+      });
+      if (result.status === 2) {
+        const reason = (result.stderr || result.stdout || 'Ark write gate denied').trim();
+        throw new Error(reason);
+      }
+      // Plumbing failures fail open (same as ark-mcp --hook contract).
+    },
+  };
+}

package/templates/skills/ark-autopilot.md

@@ -1,14 +1,17 @@
 ---
 name: ark-autopilot
-description: End-to-end co-pilot — explore first, dual plan A remediation + B pattern/Shape bets, mechanical-safe fixes, judgment design. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
+description: Guided end-to-end path — doctor next action when unsure. Explore first; dual plan A (edges) + B (shape); mechanical-safe only by default; B with user OK, one pilot at a time. Empty plan A is not healthy if design-weak. CLI is a sensor; you read and remediate files.
 ---
 
-# /ark-autopilot — Get to a sound architecture, end to end
+# /ark-autopilot — Guided end-to-end architecture path
+
+**This is the full guided co-pilot** after the compact router. Prefer it when the user wants
+architecture cleaned end-to-end, not when they only need a map (`/ark-explore`) or a single
+edge fix (`/ark-fix`). Doctor remains the control plane: re-check status after each major step.
 
 Composes **explore → sensors → dual plan → loop**. Safe default: auto-apply only
-`mechanical-safe`; when the user says full apply / “al mango” / apply everything, also
-execute **judgment** fixes you design from reading source (still validate with ark-check,
-never weaken the gate).
+`mechanical-safe`; when the user says full apply / apply everything, also execute **judgment**
+fixes you design from reading source (still validate with ark-check, never weaken the gate).
 
 **Not a plan grinder.** Empty `--plan` does **not** mean “architecture is healthy” without
 the explore pass and dual-plan section B (pattern / Shape bets).
@@ -32,7 +35,7 @@ to apply B with OK. Prefer that order when `postGreenPath` / design-weak is the
 - **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
 - **Deep map only:** `/ark-explore` — full recon / dual-plan seed without applying.
 - **Adoption fitness only:** `/ark-coverage` — governed% + capability gaps (not pattern dual-plan).
-- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+- **Default path:** `ark start` → `ark-check --doctor` → **`/ark-autopilot`** (this skill) for guided work.
 
 ## Dual engine (mandatory)
 
@@ -127,9 +130,19 @@ repo so the next agent session continues the same pilot — still never auto-app
 
 ## Operating modes (detected, not picked)
 
-- **Setup (Suggest):** no config → `ark start` / recommend shape (start freezes origin after config, before gates).
+Status lights from doctor — not settings you choose. Rank residual honestly:
+
+| Light | Means | Your move (this skill) |
+|-------|--------|------------------------|
+| **Suggest** | Thin/new tree; contract not control plane | Finish `ark start` → re-doctor; do not skill-shop |
+| **Adapt** | Contract/tree disagree or debt open | Explore + adopt/loop/contract; do not claim guarded |
+| **Enforce** | Honest coverage + clean checked **edges** | Confirm gates + CI; emit dual-plan B only if residual found |
+| **Enforce · design-weak** | Edges clean; design smells remain | **Primary Shape door:** explore shape-focus → dual-plan **B** → apply **one** pilot with user OK. Empty plan A ≠ done. Never mechanical-safe B. False-done forbidden. |
+
+- **Setup (Suggest):** no config → `ark start` (start freezes origin after config, before gates).
 - **Align (Adapt):** open debt, low honesty, or false-green → explore + adopt/loop; do not claim “guarded”.
 - **Guard (Enforce):** `goal.met`, solid governed%, no false-green → confirm gates; still emit dual plan B if explore found residual.
+- **Guard · design-weak:** same as Enforce on edges, **plus** mandatory dual-plan B / pilot card; Incomplete? must not claim healthy finished while residual remains.
 
 ## Flow
 

package/templates/skills/ark-explore.md

@@ -1,9 +1,13 @@
 ---
 name: ark-explore
-description: Decision-grade architecture recon — sensor + tree + field path + coupling + design-correct residual. Dual-plan seed for spaghetti/pattern debt (never multi-week roadmaps). CLI is a sensor; you read the tree. No gate bypass.
+description: Specialized map skill — decision-grade recon + dual-plan seed (no apply). Primary post-green door when design-weak. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
 ---
 
-# /ark-explore — Recon the real project
+# /ark-explore — Recon the real project (map only)
+
+**Specialized escape**, not the default curriculum. Use when you need a decision-grade map
+or the post-green Shape door; hand off to `/ark-autopilot` to apply. Day-to-day place + gate
+work does not require this skill.
 
 You are a **staff engineer doing architecture reconnaissance** on *this* repository.
 Ark’s CLI is a **sensor** (coverage, doctor, plan). **You** open source, entry points,
@@ -25,6 +29,15 @@ ranked residual that changes the next command — **not** a celebration of ENFOR
 (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.
 
+### Status lights (rank residual; not settings)
+
+| Light | Explore role |
+|-------|----------------|
+| **Suggest** | Point at `ark start` → doctor; map only if user insists on recon before setup |
+| **Adapt** | Map false-green / ungoverned / concentrated edge; hand off adopt/contract before Shape vanity |
+| **Enforce** | Confirm edges; if residual smells/patterns appear, auto-upgrade to dual-plan seed / shape-focus |
+| **Enforce · design-weak** | **Primary post-green map door** — shape-focus + dual-plan B + extraction cards. False-done forbidden. Never claim healthy because plan A is empty. |
+
 `/ark-autopilot`, `/ark-adopt`, and `/ark-coverage` embed a **lighter** version of this pass.
 **You** are the full recon + pattern-planning skill.
 
@@ -33,7 +46,7 @@ to apply B with user OK. Do not send the user to coverage or think as equal firs
 - **Greenfield / thin tree:** `/ark-architect` or `ark-check --recommend` / `ark start`.
 - **Brownfield action (write contract/baseline):** `/ark-adopt` after the map.
 - **Execute dual plan:** `/ark-autopilot` (explore seeds; autopilot applies A, proposes B).
-- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+- **Default path:** `ark start` → `ark-check --doctor` → `/ark-autopilot` for guided apply; use this skill for map-only or post-green Shape residual.
 
 ## Dual engine (mandatory)
 
@@ -222,7 +235,7 @@ ENFORCE without Shape progress is **`ENFORCE · design-weak`** — say that out
 | Smell id (label) | How you detect it in source |
 |------------------|-----------------------------|
 | `io-under-application` | I/O clients under Application; empty Domain/Persistence (also doctor when present) |
-| `handler-in-persistence` | Static framework HTTP imports, `defineRoute` calls, or route bodies under Persistence-role repo/db globs (first 800 sorted candidates; no advisory is not whole-tree proof above that bound) |
+| `handler-in-persistence` | Static framework HTTP imports, `defineRoute` calls, or route bodies under Persistence-role repo/db globs (**envelope:** first 800 sorted candidates; absence of smell ≠ full-tree proof above that cap; incomplete/partial analysis is never “no smells”) |
 | `god-module` | High fan-in + wide export surface + mixed concerns |
 | `domain-logic-in-ui` | `can*` / `calculate*` / policy constants in hooks/pages |
 | `mixed-pattern-cluster` | Same feature area uses ≥2 incompatible layouts |