arkgate 2.1.0

package/templates/skills/ark-runtime.md

@@ -0,0 +1,62 @@
+---
+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.
+---
+
+# /ark-runtime — Adopt the runtime kernel (opt-in features)
+
+`arkgate` is not just static checking: it ships a 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
+kernel, one feature at a time.
+
+## Steps
+
+1. **Inventory** — grep the codebase for hand-rolled equivalents:
+   - event bus / emitter used for domain events (`EventEmitter`, homemade
+     pub/sub, ad-hoc handler registries)
+   - outbox tables or "save event + publish later" code
+   - audit/history logs written manually
+   - saga/workflow orchestration (multi-step processes with compensation)
+   - read-model/projection builders
+   - policy/authorization checks scattered across use cases
+   Also check whether `@nestjs/common` is present → the `arkgate/nestjs`
+   adapters apply.
+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
+   `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
+   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
+   less code, not a second parallel system. Deleting code is a destructive move:
+   confirm with the user before removing the old implementation, and never delete
+   something the inventory only *suspects* is dead (a misclassified load-bearing
+   emitter must not be removed on a guess).
+
+## Operating rules
+
+- If the inventory finds NO hand-rolled equivalents, say so and stop — do not
+  introduce the runtime kernel speculatively. Static enforcement alone is a
+  complete, valid use of Ark.
+- Keep the migration diff reviewable: one feature per invocation.
+- Plain-language reporting: one sentence per concept ("outbox = events are
+  saved in the same transaction as your data, then published — so you never
+  publish something that didn't commit").
+
+## Related onboarding
+
+- Adopt static gates and application shape **first** (`/ark-architect`, `/ark-adopt`).
+- Runtime kernel is optional and separate from enthusiast onboarding.
+
+## Verify and report
+
+Run the project's tests plus `ark-check --root . --config ark.config.json
+--strict-config`. Report: what was migrated, lines deleted vs added, remaining
+candidates ranked, and any behavior differences (e.g. bounded history).

package/templates/skills/ark-upgrade.md

@@ -0,0 +1,109 @@
+---
+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.
+---
+
+# /ark-upgrade — Update Ark and refresh its gates
+
+Update the `arkgate` dependency to the latest published version and
+bring the repo's generated artifacts and gates in line with it. This skill
+checks the registry itself — don't assume the copy in `node_modules` is current.
+
+## 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:
+
+```
+ark upgrade
+```
+
+Use it when the user just wants the update done. Run the detailed steps below instead when
+you need to inspect the changelog first, handle a pnpm cooling-off window, or the one-liner
+reports a problem to triage.
+
+## Steps
+
+1. **Check the registry, then update.** Compare the installed version
+   (`node_modules/arkgate/package.json`) against the latest published:
+   `npm view arkgate version`. If a newer version exists, update it —
+   `npm install -D arkgate@latest` (or the project's package manager:
+   `pnpm add -D` / `yarn add -D`) — so the lockfile moves too; a pinned lockfile
+   is exactly why "just re-run install" often stays on the old version. If the
+   installed version already equals the latest, say so and still run steps 3-4
+   (a prior version may have shipped skills/gates this repo never installed).
+   Do NOT report "no update available" from the `node_modules` version alone —
+   that reads stale.
+   **pnpm cooling-off:** if the repo enforces a pnpm `minimumReleaseAge` and the new
+   version was published inside that window (common for a freshly-cut release), a plain
+   `pnpm add` in loose mode can leave a lockfile that `pnpm install --frozen-lockfile` (what
+   CI runs) then REJECTS. Do it cleanly: add the exact `<pkg>@<version>` to
+   `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` FIRST, bump the dependency spec, then
+   run a plain `pnpm install`, and verify with `pnpm install --frozen-lockfile` before moving
+   on. Only exclude a first-party package you trust.
+2. **Changelog triage** — read `node_modules/arkgate/CHANGELOG.md`
+   (shipped in the package) for the versions between old and new, and pick out
+   only entries that affect THIS repo (new flags, changed defaults, new gate
+   templates, new skills). Summarize each in one sentence with what, if
+   anything, the repo must do about it. If the file is absent (older releases
+   didn't ship it), fall back to `npm view arkgate@<version> ...` or
+   the GitHub release notes — say which source you used.
+3. **Refresh templates** — run `ark-check --install-agent-gates`. Without
+   `--force` it only writes missing files (new skills, new tool templates) and
+   skips existing ones. To pick up NEW versions of the `/ark-*` skills that a
+   package update shipped, run `ark-check --install-agent-gates --skills-only
+   --force`: `--skills-only` scopes the overwrite to the canonical skills and
+   leaves the gate files alone. Do NOT run a bare `--install-agent-gates --force`
+   to refresh skills — it also overwrites `AGENTS.md` (often customized with the
+   project's real layer table), `.claude/settings.json` (hooks/permissions), and
+   `.github/workflows/ark-check.yml` (CI) with the generic templates, silently
+   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.)
+   **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
+   (`.claude/settings.json` hooks, `.mcp.json`, `AGENTS.md`, the `check:architecture` script).
+   In a pnpm/yarn repo that means the write gate runs on a command the repo forbids. Run
+   `ark-check --install-agent-gates --migrate-commands`: it rewrites ONLY the command runner
+   in those files, preserving every customization (no `--force` clobber). A normal `ark-check`
+   also flags this when it detects the mismatch.
+4. **Re-verify** — `ark-check --root . --config ark.config.json
+   --strict-config` (with `--baseline .ark-baseline.json` if present). A new
+   version may detect violations the old one missed: if new violations appear,
+   apply `/ark-fix` reasoning to resolve them. If they are too numerous to fix
+   now, freezing them in the baseline (`--update-baseline`) is a valid stopgap
+   but it silences NEW violations, so it requires explicit user approval first
+   — never regenerate the baseline on your own to get a green check.
+
+## 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.
+- 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.
+
+## Related onboarding
+
+- After upgrade, re-run `ark-check --doctor` — `/ark-architect` and `ark-check --recommend` ship
+  with the package for **greenfield** shape adoption.
+- **Brownfield** repos: point users to `/ark-adopt` and `docs/brownfield-adoption.md`, not
+  `/ark-architect`. Demo: `docs/demos/02-brownfield-baseline-adoption.md`.
+- Refresh gates: `ark-check --install-agent-gates --force --skills-only` if skills are stale.
+
+## Verify and report
+
+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.