arkgate 2.9.2 → 2.10.0

package/docs/agent-guide.md

@@ -178,6 +178,20 @@ reference, and explanation for the full path (recommend → init → gallery →
 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`.
 
+### 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"
           }
         ]
       }
@@ -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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -79,6 +79,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"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.9.2",
+  "version": "2.10.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.9.2",
+      "version": "2.10.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