arkgate 2.12.0 → 2.13.0

package/server.json

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

package/templates/hooks/pre-commit-ark

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Maintained by ArkGate (Q3) — human-edit architecture gate.
+# Install (git hooks):
+#   cp templates/hooks/pre-commit-ark .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+# Or with husky:
+#   cp templates/hooks/pre-commit-ark .husky/pre-commit && chmod +x .husky/pre-commit
+#
+# Blocks commit when ark-check fails. Does not replace CI branch protection.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+run_check() {
+  if [ -f package.json ] && node -e "const p=require('./package.json');process.exit(p.scripts&&p.scripts['check:architecture']?0:1)" 2>/dev/null; then
+    npm run -s check:architecture
+    return $?
+  fi
+  if [ -f bin/ark-check.mjs ]; then
+    node bin/ark-check.mjs --root . --config ark.config.json --strict-config
+    return $?
+  fi
+  if command -v arkgate-check >/dev/null 2>&1; then
+    arkgate-check --root . --config ark.config.json --strict-config
+    return $?
+  fi
+  if command -v npx >/dev/null 2>&1; then
+    # --yes: pre-commit is non-interactive; never hang on npx install prompts
+    npx --yes --no-install arkgate-check --root . --config ark.config.json --strict-config 2>/dev/null \
+      || npx --yes arkgate-check --root . --config ark.config.json --strict-config
+    return $?
+  fi
+  echo "ark-check not found — install arkgate or add check:architecture script" >&2
+  return 1
+}
+
+run_check

package/templates/skills/ark-coverage.md

@@ -56,7 +56,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 |------|----------------|--------------------|
 | **Suggest / Setup** | Thin or new tree | “Ark will propose a starting shape — you don’t switch a mode.” |
 | **Adapt / Align** | Contract ≠ folders or open debt | “Gates don’t fully protect you yet — classify + fix plan.” |
-| **Enforce / Guard** | Coverage + clean edges + honest cores | “You arrived here — keep CI/write gates on.” |
+| **Enforce / Guard** | Coverage + clean edges + honest cores | “You arrived here — keep the host-appropriate write path and CI check on.” |
 
 Never say “your architecture is guarded” while `goal.met` is false, governed% is low,
 or false-green doctor gaps are open.
@@ -73,7 +73,7 @@ or false-green doctor gaps are open.
 
 1. Config + `ark-check --strict-config` (dead preset globs advisory; unclassified files still fail strict).
 2. Baseline policy (orphan empty file? wire or delete).
-3. Write gates + `/ark-*` skills per detected agent.
+3. Host-appropriate write path + `/ark-*` skills per detected agent.
 4. CI workflow + monorepo install reality (`frontend/package.json`?).
 5. ESLint `arkgate/eslint` if ESLint exists.
 6. Domain `forbiddenGlobals`.

package/templates/skills/ark-runtime.md

@@ -1,11 +1,14 @@
 ---
 name: ark-runtime
-description: Replace hand-rolled infra with the Ark runtime kernel — event bus, outbox, audit, sagas, projections, policies, NestJS. Finds candidates, wires one, verifies.
+description: Evaluate the experimental Ark runtime kernel against hand-rolled event bus, outbox, audit, saga, projection, policy, or NestJS code. Finds one candidate, wires one, verifies.
 ---
 
-# /ark-runtime — Adopt the runtime kernel (opt-in features)
+# /ark-runtime — Evaluate the runtime kernel (experimental opt-in)
 
-`arkgate` is not just static checking: it ships a runtime kernel
+The runtime kernel is currently **experimental** and is not required for ArkGate enforcement or
+presented as production-ready. Use this skill only when the user explicitly wants to evaluate it.
+
+`arkgate` ships the experimental runtime kernel
 (`createArkKernel`) with an event bus, event contracts, outbox, audit trail,
 policy engine, workflow/saga coordination, projections, observability hooks,
 and NestJS adapters. This skill migrates hand-rolled versions of those to the
@@ -43,12 +46,12 @@ the same files or weaken the gate.
 2. **Pick ONE target** — the smallest, most self-contained candidate (fewest
    call sites). Migrating everything at once is how adoptions die. List the
    rest as follow-ups in the report.
-3. **Migrate** — import from `arkgate` (root export) or
+3. **Migrate** — import from `arkgate/runtime` (preferred experimental subpath) or
    `arkgate/nestjs`, and read the package's `docs/agent-guide.md`
    (in `node_modules/arkgate/docs/`) for the runtime API before
    writing code. Wire the kernel at the composition root; keep the domain
    ignorant of it (handlers/ports, not kernel imports inside domain code —
-   the write gate will enforce this anyway). Note: the kernel bounds in-memory
+   the architecture check enforces this; Claude/Grok hooks can block it earlier). Note: the kernel bounds in-memory
    history by default (`maxHistorySize` 1000); mention this if the hand-rolled
    version retained everything.
 4. **Delete the hand-rolled version** once call sites are moved — the point is

package/templates/skills/ark-upgrade.md

@@ -1,6 +1,6 @@
 ---
 name: ark-upgrade
-description: Update arkgate to the latest published version, then refresh gates and /ark-* skills for every agent CLI and re-verify the architecture check. Autonomous.
+description: Update arkgate to the latest published version, then refresh gates and /ark-* skills for the active agent host (defer inactive hosts like Codex when not in use) and re-verify the architecture check. Autonomous.
 ---
 
 # /ark-upgrade — Update ArkGate and refresh its gates
@@ -38,6 +38,13 @@ 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).
 
+**Active host vs deferred hosts:** green the **session host** (Grok, Claude, Cursor, …)
+and repo gates first. Codex home (`$CODEX_HOME` prompts + `config.toml` MCP multi-project)
+is **deferred** unless this session is Codex or the user asked to fix Codex. Doctor marks
+those gaps `deferred` / info and does not put them in Top actions. A temp/upgrade MCP
+`--root` stays urgent (fail-closed rewrite). Never set **Incomplete?** because of deferred
+Codex debt.
+
 ## Dual engine (mandatory)
 
 | Engine | Role |
@@ -58,7 +65,8 @@ the same files or weaken the gate.
 ## Fast path
 
 One command does the whole flow — update the package, refresh gates + `/ark-*` skills
-(and Codex home prompts), migrate command runners, and run the strict check:
+(and best-effort Codex home prompts when `~/.codex` exists), migrate command runners,
+and run the strict check:
 
 ```
 arkgate upgrade
@@ -112,13 +120,18 @@ npx arkgate-check --install-agent-gates --skills-only --force
    losing customizations. If the changelog says a GATE file changed, report the
    diff and let the user decide; never rewrite settings/CI/AGENTS.md without
    explicit approval.
-   If you use Codex, its prompts live in `$CODEX_HOME/prompts` (`~/.codex/prompts`),
-   not the repo, so a repo refresh never updates them. Refresh them there too:
-   `ark-check --install-agent-gates --skills-only --codex-home --force`. Keep
-   `--skills-only` — without it, `--force` also rewrites customized gate files
-   (AGENTS.md, CI, settings). This writes to the user's home dir — say so. (A normal
-   `ark-check` now flags stale Codex-home skills when copies exist, so you don't have
-   to remember.)
+   **Active host first.** Refresh skills for the host running this skill (e.g.
+   `.grok/skills/`, `.claude/skills/`, `.cursor/commands/`). Repo-local copies for
+   other detected hosts are fine to refresh in the same pass when cheap.
+   **Codex is deferred when you are not on Codex.** Prompts live in
+   `$CODEX_HOME/prompts` (`~/.codex/prompts`), not the repo. `ark upgrade` may
+   best-effort refresh that home when it exists; still list Codex under
+   **Deferred hosts** and do **not** chase MCP multi-project / stale home skills
+   until the user is on Codex (or asks). Fix command when needed:
+   `ark-check --install-agent-gates --skills-only --codex-home --force`
+   (and `--tools codex` / `--force` for primary MCP rebind). Exception: temp or
+   `ark-upgrade` MCP `--root` paths — leave fail-closed rewrite to the CLI; do not
+   block completion on multi-project noise.
    **Migrate stale command runners.** The package-manager-aware command templates
    (`pnpm exec` / `yarn` / `npx`) only apply to NEWLY written files, so a repo that adopted
    Ark before they shipped keeps a stale `npx` in its EXISTING gate files
@@ -138,10 +151,14 @@ npx arkgate-check --install-agent-gates --skills-only --force
 
 ## Operating rules
 
-- Cover EVERY detected agent CLI (`.claude/`, `.cursor/`, `.codex/`,
-  `.windsurf/`, `.clinerules/`, `.kiro/`), not just the one running this skill —
-  gates and skills must stay in sync across tools or the weakest tool becomes
-  the hole in the fence.
+- **Must green:** the **active session host** (skills + gates that host uses) and
+  shared repo surfaces (`.mcp.json` dual-bin, command runners, architecture check).
+- **May defer:** other hosts not used in this session. Always list them under
+  **Deferred hosts** with the fix command — do not treat them as Incomplete.
+  Codex home (global `$CODEX_HOME`) is the common case on Grok/Claude.
+- **Optional sync:** if other repo-local tool dirs already exist (`.cursor/`,
+  `.claude/`, …), refreshing their `/ark-*` skills is good hygiene when cheap;
+  it is not a reason to fail the skill when the active host is already current.
 - Never run `--force` blindly; customized files are the user's.
 - Stop only if the changelog documents a breaking config change with two valid
   migration paths — then present both with a recommendation.
@@ -158,8 +175,8 @@ npx arkgate-check --install-agent-gates --skills-only --force
 
 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.
+files written/refreshed for the **active host**, deferred hosts (if any),
+skipped customized files needing a manual look, and the final check status.
 
 ## Completion contract (skill incomplete if missing)
 
@@ -168,9 +185,12 @@ 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)
+- **Active host:** e.g. `grok` / `claude` / `cursor` / `codex` (skills/gates OK or note)
+- **Deferred hosts:** `none` | e.g. `codex — home MCP/prompts; fix when using Codex`
 - **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.
+**Deferred hosts (including Codex when not on Codex) never make Incomplete? yes.**
+**Skill incomplete if missing** any of the bullets above (use `none` for Deferred hosts when empty).

package/tests/fixtures/ts-consumer/ark.config.json

@@ -1,4 +1,6 @@
 {
+  "$schema": "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json",
+  "schemaVersion": "1.0",
   "include": ["src"],
   "layers": [
     { "name": "DomainModel", "patterns": ["src/domain/**"], "forbiddenGlobals": ["fetch"] },