arkgate 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here.
 
+## 2.4.0 — 2026-07-08
+
+### Added — Adoption completeness (P0–P2)
+
+- **`collectAdoptionGaps`** shared classifier: incomplete agent hosts (detected dirs
+  without skills/hooks), dual-bin MCP argv, Codex home temp/wrong root, core layers
+  still `optional` while populated, missing origin report, baseline policy signal.
+- **`--doctor` / `--doctor --json`**: Adoption section + `doctor.adoption` JSON (separate
+  from fitness score); fix commands on each gap.
+- **Codex home fail-closed:** `wireCodexMcp` rewrites temp/`ark-upgrade` roots and stale
+  bins to absolute project root + single `arkgate-mcp` even without `--force`.
+- **P1:** `ark start` / `ark init` nudge origin report + doctor; HTML report **Adoption**
+  card (hosts, MCP, origin, core optionality, baseline) distinct from score ring.
+- **P2:** Educational presentation-heavy / thin-domain note in senior diagnostics;
+  `templates/tests/ark-adoption-gaps.test.ts` structural template for consumers.
+
+### Fixed — MCP dual-bin on upgrade
+
+- **`--migrate-commands`** stripped only `ark-mcp` then re-prepended a bin while
+  `arkgate-mcp` could remain → `args: ["ark-mcp","arkgate-mcp",…]` broke stdio MCP.
+  Now strips **all** MCP bin aliases + runner noise and emits a single
+  **`arkgate-mcp`**. Fresh `.mcp.json` / hooks / Codex+Grok wiring use the preferred bin.
+- Doctor warns when dual bins are detected; `/ark-upgrade` skill documents the check.
+
+### Added — TypeScript 5 / 6 / 7 compatibility bar
+
+- **`usableTypescript` / load fallback** shared in `ark-shared.mjs`: reject modules
+  without classic JS host (`ts.sys` + AST + resolve). TypeScript **7.0.x** main export is
+  version-only — gate falls back to ArkGate’s nested **JS-API** `typescript@^5.9`
+  (production dependency) so teams can try project TS 7 without breaking the gate.
+- **CI job `ts-compat`:** matrix `typescript@5.9.3` / `6.0.3` / `7.0.2` on
+  `tests/fixtures/ts-consumer` via `scripts/ts-compat-matrix.mjs`.
+- **Docs:** [docs/typescript-support.md](docs/typescript-support.md) (supported ranges,
+  TS7 version-only entry, tsconfig 6→7, dual-install 6+7, `ARK_DEBUG_TS`).
+- Optional peer `typescript: >=5 <8` (project compiler); runtime dependency pins JS-API host.
+
+### Docs & skills — full surface update for 2.4
+
+- Skills (`/ark-loop`, `/ark-fix`, `/ark-autopilot`, `/ark-explain`, `/ark-upgrade`) document
+  all three `mechanical-safe` `remediationKind`s and TS7 fallback notes.
+- README / CONTRIBUTING / SECURITY / enthusiast track: **ArkGate** branding, dual CLIs,
+  TS 5–7 badge; drop incorrect “zero dependencies” claim.
+- Agent / AI-gates / brownfield / demos / migrate guide aligned with plan classifier + TS7.
+
 ## 2.3.0 — 2026-07-08
 
 ### Added — P0 complete (mechanical-safe depth + release-trust)

package/README.md

@@ -11,7 +11,7 @@ trust — and makes sure a “green” check means something real.
 [![npm](https://img.shields.io/npm/v/arkgate?color=cb3837&label=npm)](https://www.npmjs.com/package/arkgate)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js)
-![Zero deps](https://img.shields.io/badge/dependencies-0-success)
+![TS 5–7](https://img.shields.io/badge/TypeScript-5%20%7C%206%20%7C%207-3178c6?logo=typescript)
 
 </div>
 
@@ -53,8 +53,9 @@ plus tools agents can read *before* generating code (`ark_place`, `ark://manifes
 
 1. **A shape** — Ark looks at your repo (Nest, Next, API, library, …) and suggests how to organize it.
 2. **Guardrails** — config + agent gates + CI so new code can’t quietly break layers.
-3. **A plan** — what’s safe for an agent to fix vs what needs your decision.
+3. **A plan** — what’s safe for an agent to fix vs what needs your decision (`mechanical-safe` vs judgment).
 4. **Honesty** — if Ark only governs 10% of the tree, it says so. “Clean” with almost no coverage is not success.
+5. **Adoption health** — `arkgate-check --doctor` checks co-pilot completeness (hosts, MCP argv, Codex home, core-layer optionality, origin report) **separately** from the 0–100 fitness score.
 
 Three **operating modes** (not “user types”) on the same contract:
 
@@ -121,7 +122,7 @@ npx arkgate-check --install-agent-gates
 | Skill | What it does |
 |-------|----------------|
 | **`/ark-autopilot`** | End-to-end co-pilot: setup → plan → safe auto-fixes → propose the rest → leave gates on |
-| **`/ark-loop`** | Drive the remediation plan in a discardable worktree; only `mechanical-safe` steps auto-apply |
+| **`/ark-loop`** | Drive the plan in a worktree; auto-apply only `mechanical-safe` (type-only move, pure-type file relocate, `import type` of pure-type modules) |
 | **`/ark-architect`** | Greenfield: pick application shape, phase-1 layers, scaffold, verify honestly |
 | **`/ark-adopt`** | Brownfield: match contract to reality, raise coverage, freeze only real debt |
 | **`/ark-contract`** | Safely edit `ark.config.json` (smallest change, strict re-check) |
@@ -130,10 +131,12 @@ npx arkgate-check --install-agent-gates
 | **`/ark-explain`** | Explain the current contract, coverage, and report in plain language |
 | **`/ark-coverage`** | Audit which Ark capabilities you are not using yet |
 | **`/ark-runtime`** | Opt-in: migrate hand-rolled bus/outbox/sagas onto the runtime kernel |
-| **`/ark-upgrade`** | Bump the package and refresh gates + skills for every agent host |
+| **`/ark-upgrade`** | Bump the package and refresh gates + skills for every agent host (also normalizes MCP bins + Codex home) |
 
 Supported agent hosts for full MCP/hook gates: **Claude Code**, **Cursor**, **OpenAI Codex**, **Grok Build**. Instruction-tier hosts (Windsurf, Cline, Copilot, …) get rule files. See [docs/ai-gates.md](docs/ai-gates.md).
 
+After upgrade, run **`npx arkgate-check --doctor`**: it flags incomplete hosts, dual `ark-mcp`/`arkgate-mcp` args, Codex home pointing at a temp path, core layers still `optional` while populated, and a missing origin report.
+
 ---
 
 ## How it works (short)
@@ -141,39 +144,43 @@ Supported agent hosts for full MCP/hook gates: **Claude Code**, **Cursor**, **Op
 ```
 ark.config.json
       │
-      ├─► Write gate (ark-mcp)     — agent PreToolUse / MCP tools
-      ├─► CI gate (ark-check)      — PR / main
-      └─► Runtime kernel (opt-in)  — only if you call it
+      ├─► Write gate (arkgate-mcp)  — agent PreToolUse / MCP tools
+      ├─► CI gate (arkgate-check)   — PR / main
+      └─► Runtime kernel (opt-in)   — only if you call it
 ```
 
-- **Presets:** hexagonal, layered, feature-sliced, monorepo (all layers optional).
+- **Presets:** hexagonal, layered, feature-sliced, monorepo (layers start optional; doctor suggests tightening populated cores).
 - **Frameworks:** Nest / Next / express / library layouts get sensible globs on init so day-one coverage is real.
 - **Brownfield:** baseline ratchet, refuse to freeze a wrong contract, `/ark-adopt` for mature trees.
-- **Agents:** skills above install into Claude / Cursor / Codex / Grok command locations.
+- **Agents:** skills install into Claude / Cursor / Codex / Grok; `ark start` freezes an origin report under `.ark/reports/`.
+- **TypeScript:** project compilers 5.x / 6.x / 7.x — gate falls back to a nested JS-API TypeScript when TS 7’s main export is version-only ([docs/typescript-support.md](docs/typescript-support.md)).
 
 ### Why not only ESLint / dependency-cruiser / Nx?
 
-| | Ark | Typical boundary linter |
+| | ArkGate | Typical boundary linter |
 |--|:---:|:---:|
 | CI import rules | ✅ | ✅ |
 | Block **AI writes** before they land | ✅ | ❌ |
 | Contract agents can read (`ark://manifest`) | ✅ | ❌ |
 | Placement tools (`ark_place`, …) | ✅ | ❌ |
 | Honest governed % + adoption path | ✅ | ❌ |
-| Zero runtime dependencies | ✅ | varies |
+| Classified plan (`mechanical-safe` / judgment) | ✅ | ❌ |
+| TypeScript 5 / 6 / 7 project compilers | ✅ | varies |
+| Adoption scorecard (hosts / MCP / origin) | ✅ | ❌ |
 
 ---
 
 ## Common commands
 
 ```bash
-npx arkgate start                         # guided setup + plan
-npx arkgate-check --doctor                # health + operating mode
+npx arkgate start                         # guided setup + plan + origin report
+npx arkgate-check --doctor                # health + Adoption gaps (not just fitness)
+npx arkgate-check --doctor --json         # machine-readable doctor.adoption
 npx arkgate-check --plan                  # safe-to-auto-fix vs your call
 npx arkgate-check --coverage              # Governed: N%
-npx arkgate-check --report ark-report.html  # showcase HTML + origin/latest snapshots
+npx arkgate-check --report ark-report.html  # showcase HTML + Adoption card + origin/latest
 npx arkgate-check --baseline              # only NEW violations fail
-npx arkgate upgrade                       # update package + refresh gates/skills
+npx arkgate upgrade                       # package + gates/skills + MCP/Codex normalize
 ```
 
 CI (example):
@@ -204,6 +211,8 @@ NestJS: `arkgate/nestjs` (optional peer `@nestjs/common`).
 |----------|------|
 | New builders (plain language) | [docs/enthusiast/](docs/enthusiast/README.md) |
 | Wire Claude / Cursor / Codex / Grok | [docs/ai-gates.md](docs/ai-gates.md) |
+| **TypeScript 5 / 6 / 7 support** | [docs/typescript-support.md](docs/typescript-support.md) |
+| Migrate from `ark-runtime-kernel` | [docs/migrate-from-ark-runtime-kernel.md](docs/migrate-from-ark-runtime-kernel.md) |
 | Messy existing repo | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Agent / MCP tools | [docs/agent-guide.md](docs/agent-guide.md) |
 | Demos | [docs/demos/](docs/demos/) |
@@ -223,7 +232,8 @@ npm run check:architecture   # Ark gates itself
 
 **npm:** [`arkgate`](https://www.npmjs.com/package/arkgate) · formerly `ark-runtime-kernel`  
 **Product:** **ArkGate** — architecture co-pilot / gate for AI TypeScript (not a runtime kernel).  
-CLI: `arkgate` · `arkgate-check` · `arkgate-mcp` (aliases `ark` / `ark-check` / `ark-mcp` still work).
+CLI: `arkgate` · `arkgate-check` · `arkgate-mcp` (aliases `ark` / `ark-check` / `ark-mcp` still work for one major).  
+MCP registry: `io.github.pedroknigge/arkgate`.
 
 Node ≥ 18 · **MIT**.
 

package/SECURITY.md

@@ -1,7 +1,7 @@
 # Security Policy
 
-Ark runs in developer machines, CI, and agent tooling paths, so security reports are
-treated as high priority.
+**ArkGate** (`arkgate`) runs on developer machines, in CI, and in agent tooling paths, so
+security reports are treated as high priority.
 
 ## Supported Versions
 
@@ -17,20 +17,21 @@ Preferred path: use GitHub's private vulnerability reporting for this repository
 - affected version or commit
 - reproduction steps
 - expected impact
-- whether the issue affects `ark-check`, `ark-mcp`, generated agent gates, the GitHub
-  Action, or the optional runtime kernel
+- whether the issue affects `arkgate-check` / `ark-check`, `arkgate-mcp` / `ark-mcp`,
+  generated agent gates, the GitHub Action, or the optional runtime kernel
 
 If private vulnerability reporting is unavailable, open a minimal public issue asking for
 a private security contact without including exploit details.
 
 ## Release Verification
 
-Ark releases are GitHub-first:
+ArkGate releases are GitHub-first:
 
 1. Changes land on GitHub and must pass CI plus the dedicated security workflow.
-2. A GitHub Release is created from an annotated `vX.Y.Z` tag. Signed tags are
-   supported and can be made mandatory by setting `ARK_REQUIRE_SIGNED_RELEASE_TAG=true`
-   in the publish workflow once release signing is configured.
+2. A GitHub Release is created from an annotated `vX.Y.Z` tag. Tag verification is
+   **fail-closed** by default for unsigned tags unless
+   `ARK_ALLOW_UNSIGNED_RELEASE_TAG=true` is set (CI publish sets this until GPG signing is
+   wired). Signed tags can later require `ARK_REQUIRE_SIGNED_RELEASE_TAG=true`.
 3. The manual `Publish npm` workflow verifies the tag, requires the GitHub Release to
    exist, reruns release checks, publishes npm with provenance, and uploads a SHA-256
    checksum for the npm tarball to the GitHub Release.