arkgate 2.9.2 → 2.11.0

package/dist/{types-D6Q8WHes.d.cts → types-BZ17b9i5.d.cts}

@@ -941,7 +941,11 @@ interface WorkflowStep<P extends SagaContext = SagaContext> {
     onEvent?: IntentName;
     retry?: RetryPolicy;
     timeoutMs?: number;
-    execute: (payload: P, bus: EventBus) => MaybePromise<Partial<P> | void>;
+    /**
+     * Execute one step. The signal is aborted when `timeoutMs` elapses; implementations
+     * performing I/O must pass it to the underlying client for cooperative cancellation.
+     */
+    execute: (payload: P, bus: EventBus, signal: AbortSignal) => MaybePromise<Partial<P> | void>;
     compensate?: (payload: P, bus: EventBus, error?: unknown) => MaybePromise<void>;
 }
 interface WorkflowStartTrigger<P extends SagaContext = SagaContext> {

package/dist/{types-D6Q8WHes.d.ts → types-BZ17b9i5.d.ts}

@@ -941,7 +941,11 @@ interface WorkflowStep<P extends SagaContext = SagaContext> {
     onEvent?: IntentName;
     retry?: RetryPolicy;
     timeoutMs?: number;
-    execute: (payload: P, bus: EventBus) => MaybePromise<Partial<P> | void>;
+    /**
+     * Execute one step. The signal is aborted when `timeoutMs` elapses; implementations
+     * performing I/O must pass it to the underlying client for cooperative cancellation.
+     */
+    execute: (payload: P, bus: EventBus, signal: AbortSignal) => MaybePromise<Partial<P> | void>;
     compensate?: (payload: P, bus: EventBus, error?: unknown) => MaybePromise<void>;
 }
 interface WorkflowStartTrigger<P extends SagaContext = SagaContext> {

package/docs/agent-guide.md

@@ -176,7 +176,21 @@ reference, and explanation for the full path (recommend → init → gallery →
 3. Run `ark init --archetype <id> --yes`, `--apply-policy-pack enthusiast-<preset>`, or `ark init --preset <preset> --yes` when no `ark.config.json` exists.
 4. Optional: `--write-plan` for `ark-adoption-plan.json`; copy a gallery starter from `examples/README.md`.
 5. Use `/ark-place` or `ark_place` for individual files after the contract exists.
-6. Verify with `ark-check --root . --config ark.config.json --strict-config`.
+6. Verify with `ark-check --root . --config ark.config.json --strict`.
+
+### Write protocol (2.10+ / Track W)
+
+Prefer preparing the write before the host commits it to disk:
+
+| Surface | Role |
+|---------|------|
+| MCP **`ark_prepare_write`** | Place + constrain + validate + optional `autoPatch` + `judgmentBrief` + contentHash in one call |
+| Write-gate **`autoPatch`** | Mechanical-safe **import type** rewrites only; post-patch revalidation green or discarded |
+| PreToolUse **`--hook-repair`** | On deny: `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` on stderr (still exit 2 — never silent write) |
+| Doctor **`writePath`** | Reports `repair` \| `reject-only` \| `mcp-only` \| `none` for installed gates |
+
+Port-proof inject binding is **judgment** for auto-apply (signature/arity change), not write-path autoPatch.
+Full reference: [ai-gates.md](ai-gates.md). Loop-cost harness: `npm run eval:loop-cost`.
 
 Do not invent layers outside the 11-layer profile or named presets. Unrecognized
 directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`.

package/docs/ai-gates.md

@@ -38,6 +38,11 @@ GitHub Actions, `AGENTS.md`, a Codex TOML snippet under `docs/`, and (when
 selected) Grok Build project files under `.grok/`. It skips existing files unless
 you pass `--force`, so review and commit only the templates that match your project.
 
+**Doctor (W5):** `ark-check --doctor --json` includes `doctor.writePath`
+(`mode`: `repair` | `reject-only` | `mcp-only` | `none`, plus `prepareWrite` /
+`autoPatch` flags) so leads can see whether the write path is repair-capable or
+still reject-only.
+
 If your project uses Codex or Grok, treat MCP registration as part of the default
 setup, not an optional extra. Ark works best when the agent can read `ark://manifest`
 before it writes code; that is the fast path to avoiding architecture drift during
@@ -52,6 +57,40 @@ violations relative to the file's current on-disk state, so files with pre-exist
 (baselined) violations stay editable — they just can't get worse. New files block on
 every violation.
 
+### Opt-in repair payload (W4)
+
+Default is **hard block with prose** on stderr. Hosts that can re-inject a fixed write
+can enable a **machine-readable repair payload** (still exit `2` — **never** silent write):
+
+| Enable | Effect on deny |
+|--------|----------------|
+| `--hook-repair` | Emit `ARK_REPAIR_JSON:…` and, when available, `ARK_AUTOPATCH_JSON:…` on stderr |
+| `ARK_HOOK_REPAIR=1` | Same as `--hook-repair` (env, no template rewrite) |
+
+`ARK_REPAIR_JSON` shape (stable additive):
+
+```json
+{
+  "mode": "repair",
+  "decision": "deny",
+  "filePath": "src/domain/use.ts",
+  "layer": "DomainModel",
+  "autoPatch": {
+    "source": "import type { Row } from '../infra/types-only';\n…",
+    "remediationKind": "import-type-from-pure-type-module",
+    "confidence": 0.85,
+    "valid": true
+  }
+}
+```
+
+When no mechanical-safe patch applies, `autoPatch` is `null` (host still re-reasons or uses
+`ark_prepare_write` / judgment). Grok deny JSON also includes `autoPatch` + `"repair": true`
+when repair mode is on.
+
+`--install-agent-gates` writes Claude/Grok PreToolUse commands with `--hook-repair` enabled.
+Reject-only installs: drop `--hook-repair` (or unset `ARK_HOOK_REPAIR`).
+
 Add to your project's `.claude/settings.json`:
 
 ```json
@@ -63,7 +102,7 @@ Add to your project's `.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+            "command": "npx ark-mcp --hook --hook-repair --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
           }
         ]
       }
@@ -114,7 +153,7 @@ Layers:
   - PersistenceAdapters: src/adapters/persistence/**
 Rules: 10 denied layer edge(s). Full contract: ark://manifest MCP resource.
 Baseline: 3 frozen violation(s) — only NEW violations fail; do not add to them.
-After edits run: npx ark-check --root . --config ark.config.json --strict-config
+After edits run: npx ark-check --root . --config ark.config.json --strict
 ```
 
 The hook belongs in the **project's** `.claude/settings.json` (that's what
@@ -124,10 +163,11 @@ prints nothing and exits 0, so non-Ark projects are untouched.
 
 ## Claude Code — MCP server (contract discovery + on-demand validation)
 
-The MCP server exposes a resource and four tools agents can use proactively:
+The MCP server exposes a resource and tools agents can use proactively (not an exhaustive list — `tools/list` is authoritative):
 
 - **`ark://manifest`** (resource) — the machine-readable architecture contract (layers + rules), so the agent can read the architecture before generating code.
-- **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate).
+- **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate). May return additive **`autoPatch`** (W1) for mechanical-safe import-type rewrites.
+- **`ark_prepare_write`** (tool) — **W2:** place + constrain + validate + optional autoPatch + judgmentBrief + contentHash in one call (composes `ark_place` + write gate).
 - **`ark_place`** (tool) — given a target file path, returns its layer, forbidden globals, and which layers it may / must not import. Call it *before* writing a new file so generated code lands in a governed location.
 - **`ark_check`** (tool) — runs the full architecture check and returns structured violations (applies the baseline automatically when one exists).
 - **`ark_coverage`** (tool) — per-layer file counts, the full unclassified-file list, and layers whose patterns match nothing.
@@ -350,9 +390,27 @@ Prefer keeping editor + CI on the same `ark.config.json` — do not maintain a p
 Whatever the agent side does, gate the merge:
 
 ```yaml
-- run: npx ark-check --root . --config ark.config.json --strict-config
+- run: npx ark-check --root . --config ark.config.json --strict
+```
+
+The `--strict` profile also requires the generated CI/write gates and fails on safety
+diagnostics. Configure reviewed exceptions explicitly:
+
+```json
+{
+  "dynamicImportAllowlist": ["src/plugins/loader.ts"],
+  "safety": {
+    "maxTsSuppressions": 0,
+    "maxAnyCasts": 0,
+    "allowInMemory": false,
+    "allowDisabledPeerIsolation": false
+  }
+}
 ```
 
+`ark-check --doctor --json` reports counts under `doctor.safety`. An `any` cast is
+reported as lost static assurance; it does not imply that a runtime schema was bypassed.
+
 Adopting Ark on an existing codebase with violations? Freeze them once and ratchet down:
 
 ```bash

package/docs/enthusiast/how-to-agent-gates.md

@@ -9,6 +9,10 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 Installs:
 
 - Write-gate hook configuration (Claude / Grok PreToolUse; Cursor advisory + MCP)
+  — PreToolUse uses **`--hook-repair`** (W4): on deny, stderr may include
+  `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` for hosts that re-inject a patch.
+  Still exit 2 / hard block; never silent write. Drop `--hook-repair` for
+  reject-only prose, or set `ARK_HOOK_REPAIR=0` and omit the flag.
 - MCP server entry (`.mcp.json`, Cursor/Codex/Grok equivalents)
 - `/ark-*` skills including **`/ark-architect`**, **`/ark-autopilot`**, **`/ark-loop`**
   (with current `mechanical-safe` remediation kinds)
@@ -35,6 +39,10 @@ npx arkgate-check --doctor
 npx arkgate-check --require-gates
 ```
 
+Doctor JSON (`--doctor --json`) includes **`writePath`**: whether PreToolUse is
+`repair` (machine-readable autoPatch on deny), `reject-only`, `mcp-only`, or
+`none` — plus `prepareWrite` / `autoPatch` booleans for leads.
+
 After upgrading the package, refresh skills so agents see the latest plan kinds:
 
 ```bash

package/docs/enthusiast/reference-commands.md

@@ -52,7 +52,7 @@ arkgate-check --watch
 | `class` | Agent may auto-apply? | Examples (`remediationKind`) |
 |---------|----------------------|------------------------------|
 | `mechanical-safe` | Yes (validate + rollback) | `type-only-import-move`, `pure-type-file-relocate`, `import-type-from-pure-type-module`, `import-type-of-type-exports` |
-| `judgment` | No — propose | value imports, ports, infra relocate, cycles |
+| `judgment` | No — propose | free value-import uses, multi-file ports, **W6 port-proof inject** (arity change), infra relocate, cycles |
 | `deferred` | No | unclear shape |
 
 ## Violation JSON (enthusiast fields)

package/docs/package-surface.md

@@ -16,10 +16,10 @@ This document is the consumer contract for **what is stable** vs **what is opt-i
 |---------|----------------|-----------------|
 | **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
 | **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
-| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
+| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
 | **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve. |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
-| **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | Inputs for running the check stay stable within a major. |
+| **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 
 Gates need **no application code imports**. Most projects only use the CLI + MCP + config.
 

package/docs/production-hardening.md

@@ -37,6 +37,11 @@ When implementing Ark store interfaces in production, cover these guarantees exp
 - Observability: failed writes and dispatches are visible to operators.
 - Migration: schema changes for stored records are versioned.
 
+Workflow `timeoutMs` uses cooperative cancellation: ArkGate aborts the `AbortSignal`
+passed as the third `execute` argument, but JavaScript cannot stop an operation that
+ignores that signal. Production steps must pass it to network/database clients and keep
+external effects idempotent; otherwise work may finish after the workflow was marked failed.
+
 ## Interface Targets
 
 | Concern | Interface |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.9.2",
+  "version": "2.11.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -66,9 +66,11 @@
     "dev": "tsup --watch",
     "test": "vitest",
     "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
     "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-config",
+    "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict",
+    "check:js": "node scripts/check-js-syntax.mjs",
     "generate:layer-match": "node scripts/generate-layer-match.mjs",
     "check:layer-match": "node scripts/generate-layer-match.mjs --check",
     "generate:cli-pure": "node scripts/generate-cli-pure.mjs",
@@ -79,6 +81,7 @@
     "eval:agent": "node eval/run.mjs",
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
+    "eval:loop-cost": "node eval/loop-cost-run.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"
@@ -110,6 +113,7 @@
   "devDependencies": {
     "@nestjs/common": "^11.1.27",
     "@types/node": "^20.14.0",
+    "@vitest/coverage-v8": "^3.2.6",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",

package/server.json

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

package/templates/skills/ark-explain.md

@@ -66,7 +66,7 @@ forensics, baseline taxonomy) for tech leads.
 
 When explaining the **plan**, name the four `mechanical-safe` remediation kinds only
 (type-only move, pure-type file relocate, `import type` of pure-type modules,
-`import-type-of-type-exports` for named type exports from mixed modules) — everything
+`import-type-of-type-exports` for named type exports from mixed modules; W6 port-proof inject is judgment when proof holds) — everything
 else is judgment/deferred and must not be auto-applied.
 
 ## Spoken / written explanation

package/templates/skills/ark-loop.md

@@ -65,8 +65,9 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 | `pure-type-file-relocate` | Relocate pure-type file to owning layer (or rename out of false Domain globs) |
 | `import-type-from-pure-type-module` | Convert value import of pure-type module to `import type` |
 | `import-type-of-type-exports` | Convert value-syntax named import/export of type-only exports from a mixed module to `import type` / `export type` |
+| *(none for port-proof)* | **W6** `port-proof-inject-binding` is **judgment** (arity change) — propose inject; do not auto-apply |
 
-Never auto: value imports (including mixed bindings with values), dynamic import/require, forbidden globals, cycles, infra moves.
+Never auto: free value uses of imports, multi-import files, dynamic import/require, forbidden globals, cycles, port-proof inject, multi-file adapter scaffolding without proof.
 
 ## Steps