arkgate 2.12.0 → 2.13.0

package/docs/threat-model.md

@@ -0,0 +1,65 @@
+# Threat model — ArkGate (Q9)
+
+**Scope:** architecture write/CI gates, agent hooks/MCP, and the experimental optional runtime.
+**Not in scope:** full org identity platforms, browser XSS in consumer apps, or npm registry
+infrastructure beyond how this package is published.
+
+## Assets
+
+| Asset | Why it matters |
+|-------|----------------|
+| `ark.config.json` contract | Defines what agents may import; weaken it → silent architectural debt |
+| Write hook (`arkgate-mcp --hook`) | Hard local boundary only for installed/trusted Claude/Grok hook operations |
+| CI `ark-check --strict-merge` | Repository check for every host; merge blocking requires a required status |
+| Baselines (`.ark-baseline.json`) | Freezes debt; abuse silences real violations |
+| Published npm tarball + Action SHA | Supply-chain integrity of the gate itself |
+| Experimental runtime kernel | Event/saga state; InMemory is not durable |
+
+## Actors
+
+- **AI agent** (Claude / Cursor / Codex / Grok) with tool write access; see the
+  [canonical host support matrix](../README.md#host-enforcement-support)
+- **Human developer** editing files outside hooks (IDE, git apply)  
+- **CI runner** on PRs / main  
+- **Maintainer / attacker** with publish or PR privileges  
+
+## Threats (STRIDE-light)
+
+| ID | Threat | Impact | Mitigations (shipped) |
+|----|--------|--------|------------------------|
+| T1 | Agent bypasses hook (direct `fs` / alternate tool) | Ungoverned code lands | CI gate; optional pre-commit (Q3); doctor writePath honesty |
+| T2 | Human commits without agent path | Same as T1 | `templates/hooks/pre-commit-ark`; branch protection + required check (Q3 external) |
+| T3 | CI job missing / not required | Merge green without architecture | doctor `enforcement-ci-*` gaps; `--strict-merge` profile |
+| T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | safety diagnostics; false-green adoption detector |
+| T5 | Baseline ratcheted open | Debt reintroduced | baseline unused/stale signals; occurrence keys |
+| T6 | Dual MCP bin / wrong root | Gate points at wrong tree | migrate-commands; Codex fail-closed temp roots |
+| T7 | Malicious dependency in publish | Compromised gate | signed tags, npm provenance, dependency-review, CodeQL, Semgrep, `verify-package-files` |
+| T8 | Path traversal in hooks/check | Read/write outside project | root resolution + under-root import resolve |
+| T9 | Runtime InMemory mistaken for durable | Data loss | durability stance docs + safety InMemory production detector |
+| T10 | Repair payload silently applied | Unexpected rewrites | repair never writes; host must re-inject; exit 2 on deny |
+
+## Trust boundaries
+
+```
+Claude/Grok host --PreToolUse--> arkgate-mcp (hard matched-write boundary)
+Any MCP host     --tool call----> arkgate-mcp (advisory validation)
+Human IDE        --disk/git-----> working tree
+working tree     --PR-----------> CI ark-check --strict-merge
+npm publish <-- signed tag ---  GitHub Release + provenance
+```
+
+## Residual risk (accepted)
+
+- Branch protection is **external GitHub state** — doctor reports honestly when unavailable.  
+- Full external adoption matrix (Q4) and independent ≥95 audit (Q10) are separate exit gates.
+- Live multi-agent loop-cost remains optional (`ARK_EVAL_LOOP_LIVE`).
+
+## Verification hooks
+
+| Check | Command |
+|-------|---------|
+| Package allowlist | `node scripts/verify-package-files.mjs` |
+| Module budgets | `node scripts/check-module-budgets.mjs` |
+| Security CI | `.github/workflows/security.yml` |
+| Audit (prod deps) | `npm run security:audit` |
+| Architecture | `npm run check:architecture` |

package/docs/typescript-support.md

@@ -32,7 +32,7 @@ itself; the CLI resolves it from the **project** first, then from the environmen
 ## How loading works
 
 1. Prefer `require('typescript')` from the **project** root (when it has `sys` + AST + resolve).  
-2. If missing or **not API-compatible** (TS 7.0 version-only export, or incomplete host), fall back to **ArkGate’s own** `typescript` dependency (JS-API 5.x nested under the package), then bare `import('typescript')`.  
+2. If missing or **not API-compatible** (TS 7.0 version-only export, or incomplete host), fall back to **ArkGate’s own** `typescript` dependency (JS-API 5.x nested under the package), then bare `import('typescript')`.
 3. If nothing usable is found:  
    - `--plan` still prints **coverage honesty** (no import graph)  
    - full check exits non-zero with an install hint  
@@ -49,9 +49,9 @@ ARK_DEBUG_TS=1 npx arkgate-check --plan
 TypeScript 7 is the **native (Go) compiler** generation. Important for tools like ArkGate:
 
 - **`require('typescript')` on 7.0.x** exports only `{ version, versionMajorMinor }` — not `sys`, `createSourceFile`, or `resolveModuleName`.  
-- Unstable programmatic surfaces live under `typescript/unstable/*` (sync/async API, AST). They are **not** the classic TS 5/6 host ArkGate uses today.  
+- Unstable programmatic surfaces live under `typescript/unstable/*` (sync/async API, AST). They are **not** the classic TS 5/6 host ArkGate uses today.
 - Stable **programmatic JS API** maturity continues over the 7.x line (Microsoft: full story into **7.1+**).  
-- When the project’s TypeScript is not API-compatible, ArkGate loads its **bundled JS-API dependency** (`typescript@^5.9`, nested under the package) so the write/CI gate keeps working while you try TS 7 as the project compiler.  
+- When the project’s TypeScript is not API-compatible, ArkGate loads its **bundled JS-API dependency** (`typescript@^5.9`, nested under the package) so the host write path and CI check keep working while you try TS 7 as the project compiler.
 - Your **tsconfig** must follow TS 6/7 defaults (see below) or `tsc` / resolve can fail independently of ArkGate.
 
 ### tsconfig defaults that surprise teams (TS 6 → 7)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,6 +22,8 @@
       "import": "./dist/eslint/index.js",
       "require": "./dist/eslint/index.cjs"
     },
+    "./schema": "./schemas/ark.config.schema.json",
+    "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
     "./nestjs": {
       "types": "./dist/nestjs/index.d.ts",
       "import": "./dist/nestjs/index.js",
@@ -42,6 +44,7 @@
     "bin",
     "bin/lib",
     "dist",
+    "schemas",
     "docs/agent-guide.md",
     "docs/enthusiast",
     "docs/demos",
@@ -51,8 +54,10 @@
     "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
+    "docs/configuration.md",
     "docs/package-surface.md",
     "docs/production-hardening.md",
+    "docs/threat-model.md",
     "tests/fixtures/ts-consumer",
     "templates",
     "server.json",
@@ -66,7 +71,9 @@
     "dev": "tsup --watch",
     "test": "vitest",
     "test:run": "vitest run",
-    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:coverage": "npm run build && vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:mutation": "npm run build && stryker run",
+    "test:confidence": "npm run test:coverage && npm run test:mutation",
     "typecheck": "tsc --noEmit",
     "security:audit": "npm audit --omit=dev --audit-level=high",
     "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict",
@@ -82,6 +89,9 @@
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "eval:loop-cost": "node eval/loop-cost-run.mjs",
+    "bench:scale": "node scripts/ark-scale-bench.mjs",
+    "check:module-budgets": "node scripts/check-module-budgets.mjs",
+    "check:package-files": "node scripts/verify-package-files.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"
@@ -102,6 +112,7 @@
     }
   },
   "overrides": {
+    "qs": "6.15.3",
     "vite": "6.4.3",
     "tsup": {
       "esbuild": "0.28.1"
@@ -112,6 +123,8 @@
   },
   "devDependencies": {
     "@nestjs/common": "^11.1.27",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^20.14.0",
     "@vitest/coverage-v8": "^3.2.6",
     "reflect-metadata": "^0.2.2",