arkgate 4.2.1 → 4.4.0

package/schemas/ark.status-manifest.schema.json

@@ -0,0 +1,270 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@4/schemas/ark.status-manifest.schema.json",
+  "title": "ArkGate status manifest",
+  "description": "Unified session/project status snapshot for agents (identity, activation honesty, last check, rules counts, next action). Not a score.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "arkgateVersion",
+    "projectIdentity",
+    "activation",
+    "lastCheck",
+    "rules",
+    "nextAction"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "arkgateVersion": {
+      "type": "string",
+      "minLength": 1
+    },
+    "projectIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "projectId",
+        "resolvedRoot",
+        "resolvedConfigPath",
+        "binding",
+        "authoritative"
+      ],
+      "properties": {
+        "projectId": {
+          "anyOf": [
+            {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "resolvedRoot": {
+          "type": "string",
+          "minLength": 1
+        },
+        "resolvedConfigPath": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "binding": {
+          "enum": [
+            "matched",
+            "unverified",
+            "mismatch"
+          ]
+        },
+        "authoritative": {
+          "type": "boolean"
+        },
+        "code": {
+          "enum": [
+            "PROJECT_ROOT_MISMATCH",
+            "PROJECT_ID_MISMATCH",
+            "INVALID_PROJECT_EXPECTATION"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "activation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "writePath",
+        "host",
+        "honestLabel"
+      ],
+      "properties": {
+        "writePath": {
+          "enum": [
+            "hard",
+            "advisory",
+            "unavailable"
+          ]
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "honestLabel": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "lastCheck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "at",
+        "verdict",
+        "activeViolations",
+        "frozenResidual"
+      ],
+      "properties": {
+        "at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "verdict": {
+          "anyOf": [
+            {
+              "enum": [
+                "pass",
+                "fail",
+                "incomplete"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "activeViolations": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "frozenResidual": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "rules": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "arkRulesLoaded",
+        "inventoried",
+        "underContract",
+        "frozenResidual"
+      ],
+      "properties": {
+        "arkRulesLoaded": {
+          "type": "boolean"
+        },
+        "inventoried": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "underContract": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "frozenResidual": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "nextAction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "summary"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "improvementCompass": {
+      "type": "object",
+      "description": "Optional thin improvement-compass residual ids (notAScore). Never a gate input; full lenses on doctor JSON.",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "notAScore",
+        "topResidual"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "1.0"
+        },
+        "notAScore": {
+          "const": true
+        },
+        "topResidual": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "maxItems": 15
+        }
+      }
+    }
+  }
+}

package/server.json

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

package/templates/agent-skills/README.md

@@ -0,0 +1,59 @@
+# ArkGate Agent Skills package
+
+> **Generated layout (Agent Skills packaging).** Do not edit SKILL.md files here by hand.
+> Author skill bodies in `templates/skills/<name>.md`, then run
+> `npm run generate:agent-skills`. Drift: `npm run check:agent-skills`.
+
+This directory is the **Agent Skills–compatible** packaging of the same **13**
+`/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
+
+Package version when last generated context: **arkgate@4.3.0**
+Schema: agent-skills package contract `1.0`
+
+## Skills (frozen catalog)
+
+- `ark-adopt`
+- `ark-architect`
+- `ark-autopilot`
+- `ark-contract`
+- `ark-coverage`
+- `ark-explain`
+- `ark-explore`
+- `ark-fix`
+- `ark-loop`
+- `ark-place`
+- `ark-runtime`
+- `ark-think`
+- `ark-upgrade`
+
+## Install — Ark (host write path + skill catalogs)
+
+Preferred when you also want hooks/MCP/CI wiring:
+
+```bash
+npx ark-check --install-agent-gates --skills-only --force
+# or full host install (hooks + MCP + skills):
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity,opencode
+```
+
+## Install — skills ecosystem (`npx skills`)
+
+From this package directory (checkout or `node_modules/arkgate`):
+
+```bash
+# Local path (after npm install arkgate, or from a git checkout)
+npx skills add ./templates/agent-skills
+# or:
+npx skills add ./node_modules/arkgate/templates/agent-skills
+
+# GitHub tree (Agent Skills package root)
+npx skills add https://github.com/pedroknigge/arkgate/tree/main/templates/agent-skills
+
+# List without installing
+npx skills add ./templates/agent-skills --list
+```
+
+Skills are **process** depth (host judgment + routing). They are **not** enforcement.
+Enforcement is `ark-check` / host write hooks / required CI (`--strict-merge`).
+
+See [docs/agent-guide.md](../../docs/agent-guide.md#install-skills-ark-and-ecosystem).

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: ark-adopt
+description: Brownfield onboarding — match contract to real product code, classify ungoverned dirs, mine business rules, freeze only real debt, seed Shape dual-plan B for spaghetti residual. Deep source analysis required.
+---
+
+# /ark-adopt — Bring Ark into an existing codebase
+
+Goal: contract reflects **product reality**, most code governed, only genuine debt frozen
+with a burn-down. A green check over a wrong contract is a **false green**.
+
+**Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
+spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+when design smells remain after the contract is honest.
+
+## 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.
+
+**Spaghetti → honest contract.** SoC/DIP false-green STOP paths in plain language; residual lenses stay Incomplete until mapped.
+
+## When / not when
+
+| Use `/ark-adopt` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| Existing messy repo; contract ≠ folders | Empty greenfield shape → `/ark-architect` |
+| False-green / concentrated edge needs contract truth | Map-only without writing config/baseline → `/ark-explore` |
+| Mine loose business rules into Domain / intents | Single violation fix → `/ark-fix` |
+| Freeze **real** debt after contract is honest | Grind plan A only → `/ark-loop`; full apply loop → `/ark-autopilot` |
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | coverage, doctor, baseline, strict-config after edits |
+| **Exploratory** | walk the real monorepo/app layout; reclassify; mine rules; suggest shape |
+
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+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 + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| 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` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column 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-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Adopt + ArkRules
+- After classify: emit or refresh `arkRules` for matched layers (exact names; generic mold for unknowns).
+- Mine rules → inventory + propose invariants/structure; land via `/ark-contract`.
+- Freeze baseline is **[Layer]** debt; inventory residual is **[ArkRules]** — report both.
+
+## 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.
+
+## Related onboarding
+
+- **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
+- **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
+- **Deep map only:** `/ark-explore`.
+- **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
+
+## Anti-wrapper rule (mandatory)
+
+**Forbidden:** only running `--init` / `--update-baseline` / coverage JSON without reading the tree.
+
+**Required:**
+1. CLI sensor: `--coverage --json`, check `--json` (`summary`), doctor.
+2. **Product map** — what ships, which apps/packages, entry routes/CLIs.
+3. **Read real source** in largest ungoverned dirs and top import edges (min **12 files**
+   across **≥4 dirs**).
+4. **“Así te lo re-soluciono”** — concrete layer globs, file moves, manifest/intent proposals.
+5. **Suggestive burn-down** — ranked next steps after adopt (not only “baseline done”).
+6. Never freeze a concentrated edge without investigating contract smell / false-green.
+
+## Guiding principle
+
+Ark protects the **boundary around** a framework, not its internals. Nest/DI public surface = one layer; internals black box.
+
+## Steps
+
+1. **Config** — missing → `ark-check --init` (detection). Keep existing unless asked to regenerate.
+   If the tree is `src/features` + `shared`/`lib` **without** FSD `entities`/`widgets`, prefer
+   `vertical-slice` (or pack `enthusiast-vertical-slice`) — do **not** force hexagonal.
+   If `src/contexts` or `src/bounded-contexts` exists, prefer `ddd-bounded-contexts`.
+   **Next.js:** `app/api/**` / `pages/api/**` (and route-group `app/(…)/api/**`) default to
+   **ApplicationOrchestration**, not Presentation — do not reclassify API shells as UI.
+2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
+   Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
+   If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge: invoke /ark-contract with source evidence** (do not freeze a wrong contract or grind N freezes).
+   Empty Domain/Persistence + I/O under Application → false-green.
+   **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
+3. **Classify ungoverned** — use coverage `suggestions` **plus** dirs you discovered by reading;
+   add layers/patterns via `/ark-contract`.
+4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
+   - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
+   - **ArkRules inventory (AR13):** run `ark-check --rules-inventory --json` for deterministic candidates
+     (validation-in-controller, magic constants, anemic entities). Counts are **not a score**.
+   - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
+     land structure/invariant entries under `arkrules/<Layer>.json` via `/ark-contract` (ADR 0015 routing).
+   - Apply config through `/ark-contract` discipline; move pure rules into Domain when safe; validate with ark-check.
+   - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
+5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
+6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
+7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
+   - Name phase: **Align** (contract honesty) → **Stabilize** (baseline real) → **Shape** (golden pattern).
+   - If plan A is empty but the tree still shows concurrent patterns, god modules, facade SQL,
+     domain logic in UI, or semantic false-green: emit **dual-plan B** (3–5 bets) with pilot,
+     success signal, kill-switch, and extraction cards for I/O moves — same bar as `/ark-explore` §G.
+   - Do **not** claim “adopt complete / healthy” solely because the check is green.
+   - Prefer handoff `/ark-autopilot` for B execution with user ok, or `/ark-explore` shape-focus
+     if the user only wanted a plan.
+
+## Operating modes
+
+Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
+**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
+
+## Verify
+
+`ark-check --root . --config ark.config.json --strict-config` (+ baseline only if non-empty file retained).
+Report: governed% before/after, files written, frozen count, false positives avoided, manifest/intent
+proposals applied or deferred, **phase**, **top Shape / design-weak opportunities still open**
+(with success signals).
+
+## Never
+
+- Freeze false positives to get green.
+- Force runtime kernel over existing Nest/DI.
+- Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
+- End adopt with only “baseline written” when design-weak residual is visible in files you opened.
+
+## 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
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
+- **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.